@difyz/pi-wecom0.1.2

@difyz/pi-wecom

在企业微信中与 Pi 对话，沿用 Pi 当前模型，同时隔离每位用户的会话。

Connect Pi to WeCom AI bots using the official WebSocket SDK. Streaming replies, isolated sessions, explicit access controls, and an independently installed knowledge extension.

面向企业微信智能机器人 API 长连接模式，不是普通群 Webhook 或自建应用。远端会话不接管终端对话，不开放 shell、文件访问、宿主工具、skills 或项目上下文。

源码目标版本为 0.1.2。本次双扩展架构需要发布新的兼容版本后才能从 npm 安装；下方不带版本的命令用于安装正式发布的最新版本。若 npm 仍显示 0.0.0-stage / “Temporary Holding Version”，它不是可用插件。自动化测试不是企业微信真实联调或生产验收。

快速开始

1. 安装企业微信扩展

需要 Node.js >=22.19 和 Pi 1.4.0，以及后台已开启“API 长连接”的企业微信智能机器人。

pi install npm:@difyz/pi-wecom
pi

无需安装知识包，不会引入 pi-knowledge、better-sqlite3 或知识 worker。核心使用 Node 内置 SQLite 保存通道状态。

2. 配置

在用户级 ~/.pi/agent/settings.json 中合并以下节点，保留其他 Pi 设置：

{
  "wecom": {
    "botId": "你的 BotID",
    "secret": "你的长连接 Secret",
    "allowedUsers": ["授权用户真实userid"],
    "allowedGroups": []
  }
}

密钥是明文，建议文件权限为 600 并保护备份。勿提交、转发或粘贴真实凭证到聊天。userid 是机器人实际接收到的精确标识，不一定是通讯录账号。插件不打印用户或消息内容辅助发现 ID。

3. 启动

先在 Pi 中选择已获准处理企业数据的模型并完成授权，再执行：

/wecom doctor
/wecom start
/wecom status

doctor 只做本地检查；ready 代表机器人已鉴权。让白名单用户单聊机器人发送文本。

不需要企业微信专属模型配置：启动时采用 Pi 当前模型及供应商授权，启动后保持固定。切换模型或修改配置后先 /wecom stop 再 /wecom start。无模型、模型不可用或未授权均明确拒绝，不选择替代模型。旧远端历史不覆盖新启动模型。

仅继承模型，不共享终端历史或工具；思考级别仍为 off。不能独立复用的虚拟/路由模型明确拒绝。只在 /wecom start 时连接，Pi 退出、切换会话或重载会停止插件，不是守护进程。

可选：再安装知识扩展

pi install npm:@difyz/pi-wecom-knowledge

重启 Pi。两个包可以在不同安装目录；不需要 npm 全局安装、同目录依赖或模块路径配置。

在同一用户级配置中添加：

{
  "wecom": {
    "botId": "你的 BotID",
    "secret": "你的长连接 Secret",
    "allowedUsers": ["授权用户真实userid"],
    "allowedGroups": [],
    "knowledge": { "enabled": true }
  },
  "knowledge": {
    "policy": "/absolute/private/knowledge-policy.json"
  }
}

wecom.knowledge 只决定该通道是否接入；顶层 knowledge 由知识扩展独立管理。策略的用户、库和 allowedModels 授权必须同时满足。安装不等于建库，知识目录需管理员预先维护。

/knowledge doctor
/wecom doctor
/wecom start

在企业微信单聊中：

/kb list
/kb ask hr 年假规则是什么？

知识问答仅单聊、只读；不开放远端建库、删除、导入、导出或安装。知识包包含原生 SQLite 依赖，安装时需要可用的预编译绑定或本机编译环境。完整策略、引擎维护及接口说明见 知识包文档。

架构与分发

同仓库、两个独立 Pi 扩展、独立版本和发布，无 HTTP 服务或第三个接口包：

包	负责	不负责
@difyz/pi-wecom	机器人连接、身份、排重、队列、限流、独立 Pi 对话	知识策略、数据库、检索引擎
@difyz/pi-wecom-knowledge	库/用户/模型授权、检索、引用、共享 worker 维护	机器人凭证、通道白名单、传输

通过 Pi 进程内事件 difyz:knowledge:discover 发现能力，协议版本 v1；核心不 import 知识包，不声明知识 peer。发现请求由已加载的提供者同步响应，不依赖扩展加载顺序；使用前均须加载到同一 Pi 宿主。

提供者建立每通道租约：通道传入隔离回答后端、可信身份/模型/作用域、字节预算和取消通知。释放通道租约仅取消自身任务，不关闭共享服务。知识 stop/restart 取消知识任务及排队问题、切换代次并释放 worker，不断开通道、不重置普通历史、不重放旧请求。

首次接入按需启动知识服务；管理员停止后不会由新通道自动唤醒。Pi 切换会话会停止两套扩展的运行资源；在新会话中先 /knowledge restart，再 /wecom start。重新启动 Pi 则恢复首次按需启动行为。

事件总线不是安全边界；宿主安装的扩展必须可信。共享引擎执行中的检索被取消时可能终止 worker、影响其他知识调用；状态会变为 unavailable，需要管理员恢复，不伪装成功。

配置字段

只读取 Pi 用户级 settings.json，不读取项目级企业微信配置。路径跟随 Pi 的用户目录（默认 ~/.pi/agent；宿主可设置 PI_CODING_AGENT_DIR），启动/doctor 时重新读，不自动写回。

wecom 字段	必填	说明
botId	是	智能机器人 ID 字符串
secret	是	长连接 Secret 字符串，不是 Token/EncodingAESKey
allowedUsers	是	非空精确 userid 字符串数组
allowedGroups	否	精确 chatid 数组，默认 [] 禁止全部群聊，不支持 *
dataDir	否	默认 Pi 用户目录下的 wecom，自定义必须绝对路径
concurrency	否	数字 4，范围 1–16
queueSize	否	每会话等待 5 条，范围 1–20
timeoutMs	否	数字 540000，范围 1–540000 毫秒
knowledge	否	{ "enabled": true } 接入独立知识扩展，省略或 { "enabled": false } 关闭

迁移：

• 不再读取 WECOM_* 环境变量或 .env。
• 删除旧 wecom.provider / wecom.model，采用 Pi 当前模型。
• 将旧 wecom.knowledgePolicy 移到顶层 knowledge.policy，添加 wecom.knowledge.enabled: true。
• 将旧知识库安装改为 pi install npm:@difyz/pi-wecom-knowledge，重启 Pi；仅作为 npm 库安装而未加载扩展不足以提供能力。
• 无效 JSON、未知字段、类型错误、空白名单和相对路径明确报错，原始异常/密钥不回显。

命令

本地 Pi 命令	行为
/wecom doctor	检查配置、模型、目录；启用知识时检查提供者 v1，不打开知识引擎
/wecom start / stop / status	通道启动、停止、状态及实际模型/能力状态
/wecom pair <alias> <userid>	为指定白名单用户生成一次性群目标配对码
/wecom pair cancel	撤销待配对码
/wecom routes / routes remove <alias>	本地查看或删除群目标，不更改群权限
/knowledge doctor	知识引擎诊断；已运行时只看状态，不开第二个 worker
/knowledge status / stop / restart	独立维护知识服务，restart 重读策略

旧 /wecom knowledge ... 不再管理服务，会提示使用 /knowledge ...。以上管理命令不开放给企业微信用户。

企业微信命令	行为
/help	能力说明
/status	本人的任务与排队状态
/stop	取消本人任务与等待队列
/new	空闲时重置本人上下文，不删除旧文件
/kb list / /kb ask <alias> <问题>	已启用知识时单聊只读查询

支持独立命令前 @机器人名 前缀，不删除普通文本中的 @。不支持图片、文件、语音或卡片；获准来源收到明确提示。

群白名单与配对

普通群消息必须同时满足用户和群白名单，区分大小写、精确匹配；未授权消息在入库/能力调用前丢弃，不在群内回复。群成员上下文按人隔离，但回复仍对全群可见。

配对仅记录群目标，不自动授权、不主动发消息：

1. 本地 /wecom pair ops 已获准的真实userid。
2. 指定用户在目标群 @机器人发送生成的 /wecom pair 一次性码。
3. 本地 /wecom routes 核对 groupId；此输出含敏感标识，勿转发。
4. 确认后另行配置 wecom.allowedGroups 并重启通道。

唯一的默认拒绝例外是上述有效配对：128 位随机码、5 分钟有效、绑定指定用户、仅群聊、一次性使用，不入任务库/不调用模型/不远端回复。生成新码、断线、停止或撤销使旧码失效。别名以小写字母开头，仅小写字母/数字/_/-，最长 32 字符，不能覆盖旧绑定。

绑定按 Bot 持久化；删除别名不撤销群配置权限。暂不提供主动通知或单聊目标绑定。

故障与数据边界

• 未启用知识：普通聊天正常，/kb 明确提示不支持。
• 已启用但扩展缺失/冲突/v1 不兼容：通道照常启动，本地固定编号告警；无法确认自动问答策略时，单聊普通文本也拒绝，避免把知识问题误发为普通聊天。修复安装后重启 Pi。
• 策略已确认 autoAnswer: false 而引擎故障/服务停止：普通聊天正常，知识请求明确失败。
• 策略开启自动问答：服务不可用时自动问题拒绝，不回退普通聊天；/knowledge restart 恢复。
• 群知识请求始终拒绝，不泄漏目录或调用检索/模型。
• Pi 供应商实现虽复用，远端会话仍禁用全部工具/扩展/上下文文件；这不是操作系统沙箱。

知识片段会发给继承的回答模型供应商；allowedModels 是强制外发许可，不是重复模型配置。引用格式校验不保证回答语义正确。

数据在 wecom.dataDir 下按 BotID 哈希隔离：state.sqlite 保存排重、任务、发送计数和群目标；随机 sessions 目录保存普通/知识 JSONL。知识 JSONL 可能含未发送的无效回答和检索片段。目录 0700、数据库及完成的会话 0600，不加密、不自动删除，/new 不删除旧历史。上线前制定磁盘加密、备份及保留策略。

同 BotID 仅允许本机一个实例；锁位于 ~/.pi/agent/wecom-locks/，勿删除运行中的锁。离线时取消现有/排队任务，不重放。最终发送有总计 5 秒上限，未确认送达不记成功；限流计数只保留滚动一小时，排重历史不随之删除。

日志写入 stderr，仅固定编号，不输出正文、用户 ID、原始 SDK 日志或密钥。常见：MESSAGE_UNAUTHORIZED、MESSAGE_GROUP_UNAUTHORIZED、WECOM_AUTH_FAILED、WECOM_REPLACED_BY_ANOTHER_CONNECTION、KNOWLEDGE_EXTENSION_MISSING、KNOWLEDGE_PROTOCOL_INCOMPATIBLE、KNOWLEDGE_PROVIDER_CONFLICT、KNOWLEDGE_INITIALIZATION_FAILED、STREAM_FINISH_UNCONFIRMED。曾泄漏 Secret 时先轮换再更新本地配置。

源码开发、验证与独立发布

npm ci --ignore-scripts
npm rebuild better-sqlite3 # 知识引擎开发/集成测试需要
npm run check             # 两包类型检查
npm test                  # 构建知识包并运行全仓集成测试

仅核心检查/发布不构建知识包：

npm run check:wecom
npm run test:wecom
npm run version:wecom -- patch
npm publish --access public

仅知识包：

npm run version:knowledge -- patch
npm publish --workspace=@difyz/pi-wecom-knowledge --access public

版本命令也支持 minor、major 或更高稳定版本；各自升级，不要求两包相同版本，不修改另一包依赖。旧 version:bump 已移除。锁文件及两份 README 中对应包的版本示例同步；不创建 Git 提交/标签、不自动发布，失败恢复发布文件。请勿并发执行或同时编辑发布文件。

发布无固定顺序，通过能力接口 v1 兼容；发布前分别运行自身检查/测试，接口变更须运行全仓集成测试。npm 已发布版本不可覆盖，不要在待审核时盲目重复发布。维护者登录官方 registry 并确认 scope 权限；不要将 token 写入仓库。

本地 tarball 为 difyz-pi-wecom-0.1.2.tgz、difyz-pi-wecom-knowledge-0.1.1.tgz；可分别用 npm 安装到独立测试目录，再让 Pi -e 加载各自包目录。源码临时加载：

npm pack --dry-run
npm pack --dry-run --workspace=@difyz/pi-wecom-knowledge
./node_modules/.bin/pi -e . -e ./packages/knowledge

核心仅分发 src/README/LICENSE/包清单；知识仅分发编译 dist/README/LICENSE/包清单，prepack 自动构建。不发布笔记、配置、数据库或测试资料。

测试覆盖真实本地 WebSocket/官方 SDK、Pi SSE/隔离会话、排重与配额、能力发现/代次取消/独立生命周期、分别及共同加载、tarball 安装和独立版本脚本。未验证真实 Bot、业务库 Recall@5、语义回答依据、检索 p95 或一小时稳定性，生产使用前须验收。

升级/卸载前 /wecom stop；固定版本安装后更新应先 remove 对应旧包，再 install 新包并重启 Pi。卸载不会删除配置、数据库或会话。

暂无公开源码仓库或独立问题入口；通过现有维护者渠道反馈版本、脱敏错误编号和复现步骤，勿附凭证或企业正文。

协议参考：企业微信长连接。

许可证

MIT © difyz；第三方依赖遵循各自许可证。