企业微信NPC机器人全流程指南

企业微信的智能机器人走「长连接」模式时，不再有 Webhook 回调地址，客户端要自己维持 WebSocket、完成认证帧、处理心跳，并把消息转发给后端 NPC。团队常见的问题不是模型能力不足，而是链路太长：企微后台配置、CNB NPC 仓库、流水线触发、Node.js 长连接客户端、systemd 常驻，任何一环脱节都会表现为「消息收不到」或「认证失败」。这个技能把全流程拆成可核对的步骤，并提供可直接运行的模板。

它解决什么问题

• 长连接模式的认证细节不直观：认证回复帧没有 cmd 字段，只能通过 req_id 前缀 auth_ 判断。
• CNB 流水线配置位置错误会导致构建报 CONFIG_EVENT_EMPTY，但排查时容易先怀疑 Token。
• NPC 输出混入 Runner、Usage、Skills 等元数据行，直接返回给用户会破坏角色人设。
• 多机器人部署时，同一个 Bot ID 被多个进程连接会造成频繁断线和重连竞争。

技能如何工作

它按 7 步串起完整链路：企业微信后台创建智能机器人并选择「API 模式 / 长连接」，关闭「仅限创建者使用」；创建 CNB NPC 仓库；在 .cnb/settings.yml 里定义角色名、prompt、口头禅与格式要求；在 .cnb.yml 中把 api_trigger_npc 放在 $: 下触发 NPC；推送后查询构建状态与 Stage 日志；复制 templates/index.js 部署长连接客户端；用 systemd 模板常驻运行。

客户端负责订阅 aibot_subscribe，按 req_id 前缀区分认证、心跳 ping_ 与流式回复 stream_；收到 aibot_msg_callback 后携带运行时上下文调用 CNB NPC，再通过 aibot_respond_msg 的 stream 字段把回复分段写回企微。NPC 结果提取采用三层 fallback：标准匹配 Master[...][agent][N]、宽松过滤元数据行、尾部兜底，避免镜像格式变化导致无输出。

适用边界与注意点

• 需要企业微信管理员权限、具备 repo-cnb-trigger:rw scope 的 CNB Token，以及 Node.js >= 18 的服务器。
• 必须使用 wss://openws.work.weixin.qq.com，并保持每 30 秒发送心跳；pong 帧同样没有 cmd。
• 若认证失败返回 errcode=853000，应先核对 Bot ID/Secret 与长连接模式，而不是立刻认定限流。
• 密钥不要写进 service 文件，.env 权限应为 600；多机器人通过环境变量区分，并确保每个 Bot ID 只有一个进程。
• 角色人设统一放在 settings.yml 的 prompt，不要在客户端里重复硬编码风格。