企业微信机器人(应用)

NOTE

本集成属于「应用类机器人」。在企业微信中，机器人通过自建应用实现——你需要先在企业微信管理后台创建一个自建应用，然后配置消息接收回调，从而赋予该应用 AI 智能问答能力。

与"智能机器人"相比，企业微信机器人基于标准的自建应用体系，拥有更丰富的权限控制和消息类型支持。它通过 XML 协议的回调通知接收用户消息，并借助应用消息 API 回复。

推荐场景

企业级 AI 助手：作为内部员工的统一 AI 入口，直接在企业微信应用中对话。
知识库问答：员工在企微中随时查询企业内部知识（产品手册、规章制度、FAQ 等）。
工单分派：与内部系统集成，接受用户咨询后自动分派工单。

与其他企微机器人模式的区别

特性	应用机器人 (wecom-app)	智能机器人 (wecom-smart)	客服 (wecom-kefu)
消息协议	XML	JSON	XML
需要 AgentId	✅	❌	❌
需要 Secret	✅	✅	✅
适用对象	企业内部员工	企业内部员工 / 群聊	外部微信用户
流式回复	❌ (一次性回复)	✅ (WebSocket 长连接 Stream)	❌ (一次性回复)
API 发送消息	✅ `message/send`	✅ (WebSocket 长连接推送)	✅ `kf/send_msg`

1. 企业微信管理后台配置

1.1 创建自建应用

登录企业微信管理后台。
进入 "应用管理" -> "自建"。
点击 "创建应用"：
- 填写应用名称（如「CatWiki AI 助手」）。
- 上传应用 Logo。
- 设置可见范围（选择哪些部门/人员可以使用此机器人）。
创建完成后，记录以下信息：
- AgentId：应用详情页中可以看到。
- Secret：应用详情页中点击查看。

1.2 获取企业 CorpID

在管理后台首页 -> "我的企业" 底部可以找到 企业 ID (CorpID)。

1.3 配置接收消息

进入您刚创建的应用详情页。
找到 "接收消息" 部分，点击 "设置 API 接收"。
URL 配置：
- 填入 CatWiki 提供的 Webhook 地址。
- 格式为：https://您的域名/v1/bot/wecom-app?site_id={site_id}
- 注意：请将 {site_id} 替换为您在 CatWiki 后台的实际站点 ID。
- 该地址必须能够从公网访问且支持 HTTPS。
获取凭据：
- 记录下 Token 和 EncodingAESKey（或点击随机生成，并记录下来）。
⚠️ 暂不点击保存！ 先将获取到的全部参数填入 CatWiki 后台并启动服务（参考下方步骤 2），只有 CatWiki 后端加载了你的 Token 和 AES Key 后，再回到这里点击“保存”，才能通过企业微信的 URL 签名机制连通性测试。

1.4 配置企业可信 IP

在应用详情页底部，找到 "开发者工具" 部分。
点击 "企业可信IP"。
在弹出框中填入 CatWiki 服务器的 公网出口 IP 地址。
- 提示：若不配置可信 IP，企业微信将拒绝来自该服务器的 API 调用请求，导致机器人无法回复。

2. CatWiki 后台配置与打通验证

保持企微后台页面不关，开个新标签页进入 CatWiki 后台 "站点设置" -> "AI 机器人"。
选中 "企业微信机器人" 卡片，开启开关。
填入配置：
- CorpID：填入企业 ID。
- AgentID：填入自建应用的 AgentId。
- Secret：填入自建应用的 Secret。
- Token：填入"接收消息"中生成的 Token。
- EncodingAESKey：填入"接收消息"中生成的 EncodingAESKey。
点击界面上的 "保存"。
打通验证：现在切回企业微信管理后台的 “设置 API 接收” 页面，点击 “保存”，提示验证成功即可！

3. 技术特性

流式回复：❌ 不支持 (受限于企业微信官方 message/send API 机制限制，此时系统默认开启非流式调用，以进一步提升大模型的返回速度)。
消息格式：采用 XML 加解密协议接收和解析消息。
去重保护：基于 MsgId 的 OrderedDict 去重，TTL 600 秒，防止企业微信重试回调导致重复回答。
Token 缓存：Access Token 自动缓存，提前 5 分钟刷新，避免频繁请求 Token 接口。
并发控制：接入 RobotOrchestrator 全局任务锁，同一用户同时只有一个 AI 推理任务在运行。