企业微信集成
将企业微信智能机器人接入 Mopheus，在企微中与智能体对话，接收工单状态和评论推送。
企业微信集成通过 WebSocket 长连接将企业微信智能机器人（aibot）接入 Mopheus。配置完成后，智能体实时响应企微消息，工单状态变更和评论将推回企微对话。
接入方式对比
| 对比项 | 群机器人 | 自建应用 | 智能机器人（URL 回调） | 智能机器人（WebSocket 长连接） |
|---|---|---|---|---|
| 私聊 | 不支持 | 支持 | 支持 | 支持 |
| 群聊 | 群机器人加入的群可接收消息 | 可创建群聊并向应用创建的群发送消息 | 支持群聊中 @机器人 | 支持群聊中 @机器人 |
| 多群使用 | 同一机器人加入多个群后，可向这些群发送消息 | 群聊需由应用创建 | 可加入群聊交互 | 可加入群聊交互 |
| 公网要求 | 接收群消息不需要公网回调地址 | 接收消息需要公网可访问的回调地址；服务端调用 API 还需配置可信 IP | 需要公网可访问的回调 URL | 不需要公网回调地址；部署端需能连接企业微信 WebSocket 服务 |
| 回复时限 | 适合群消息推送，不提供私聊交互 | 按应用消息接口规则处理 | response_url 有效期为 1 小时，且只能使用一次 | 不受 URL 回调 response_url 的 1 小时限制 |
| Mopheus 支持 | 不支持群机器人配置或多群广播 | 支持绑定；当前仅支持私聊 | 不支持 | 支持扫码或手动绑定 |
群机器人、多群使用和智能机器人是企业微信侧的能力说明；Mopheus 支持情况以最后一行为准。URL 回调的 1 小时是 response_url 的有效期，不代表机器人必须持续回复一小时。
配置
1. 智能机器人接入
扫码接入（推荐）
- 在 Mopheus 中，进入智能体或团队详情页 → 集成 标签 → 连接企业微信机器人。
- 选择 扫码接入，使用企业微信扫描显示的二维码，并在企业微信中完成创建与授权。
- 扫码成功后，Mopheus 会在服务端获取 Bot ID 和 Secret，并加密保存到所选的智能体或团队。凭据不会返回到浏览器。
安装入口要求当前成员拥有 channel:bind 权限；将机器人安装到自己以外的智能体或团队时，也会按工作区的归属规则校验。
手动填写凭据
- 进入企业微信管理后台 → 应用管理 → 智能机器人。
- 创建一个新的智能机器人。记录创建时显示的 Bot ID 和 Secret。
- 在 Mopheus 中，进入智能体或团队详情页 → 集成 标签 → 连接企业微信机器人，选择 手动填写。
- 填写 Bot ID 和 Secret。可选设置自定义 WebSocket 地址（默认
wss://openws.work.weixin.qq.com）。
2. 自建应用（回调模式）
在企业微信管理平台完成以下配置：
-
在 应用管理 中创建应用。
-
进入应用详情，记录 AgentId 和 Secret。
-
在 Mopheus 的智能体或团队详情页打开 集成，点击 连接企业微信机器人，选择 自建应用。
在企业微信管理平台的 我的企业 页面底部查看 企业 ID（CorpID）。
填写 CorpID、AgentId 和应用 Secret。Mopheus 会安全生成 Token 与 EncodingAESKey，并加密保存。
企业微信 API 地址 默认为
https://qyapi.weixin.qq.com；私有部署可填写 API 服务基地址。Mopheus 使用GET /cgi-bin/gettoken?corpid=<CorpID>&corpsecret=<Secret>获取 access_token，再使用POST /cgi-bin/message/send?access_token=<access_token>发送消息。创建成功后，复制页面显示的回调 URL、Token 和 EncodingAESKey。
回到企业微信管理平台，进入应用详情的 接收消息，点击 设置 API 接收，填入刚才复制的 URL、Token 和 EncodingAESKey 并保存。
回调地址由部署的
APP_URL和固定路径/wecom/callback/{installationId}生成；Next.js 会将请求转发到 Go API。请确保 Web 公网域名可访问，且NEXT_PUBLIC_API_URL指向后端。
自建应用的外发消息使用企业微信 Markdown 类型。内容仍遵循现有 WeCom 渠道 20KB 的总长度限制；在此范围内，超过 2048 字节的内容会按 UTF-8 字符边界拆成多条消息，并优先在换行处切分。企业微信仅支持部分 Markdown 语法。
自建应用收到的图片、文件和视频回调会通过已配置的 API 基地址，使用回调中的 MediaId 下载，并将文件关联到渠道消息。向同一成员发送的消息至少间隔 4 秒（最多 900 条/小时）；企业微信返回 45009 限频错误时，外发队列会退避重试。企业每日总额度取决于企业账号成员上限（成员上限 × 200），Mopheus 当前无法获知该档位，因此请在企业微信侧保守配置应用可见范围。
该模式从回调 XML 的 FromUserName 获取成员 UserID，并复用现有企业微信身份绑定与 channel engine。回调 Token、EncodingAESKey 和应用 Secret 均在服务端加密保存。
3. 配置 Mopheus
在 管理后台 → 系统配置 中设置：
| 配置项 | 值 |
|---|---|
启用企业微信 (wecom_enabled) | true |
企业微信密钥 (wecom_secret_key) | Base64 编码的 32 字节 AES 密钥，用于加密存储的机器人凭证 — 点击系统配置中的 生成 按钮生成 |
配置机器人凭据后，不要通过通用配置编辑器修改企业微信密钥。系统配置中的 生成 会在一个事务中轮换密钥并重加密全部已有企业微信绑定。
验证集成前，请在企业微信管理后台配置机器人的可见范围或可用成员、部门。连接机器人不会自动授权所有企业微信用户。超出机器人可用范围的发送者可能会被企业微信直接拒绝，消息不会到达 Mopheus。
4. 验证
向企微中的机器人发送任意消息。每位企业微信发送者首次发送消息时，机器人会返回一次性 Mopheus 账号绑定链接。登录并确认绑定后，再次发送消息即可路由到关联的智能体，智能体的回复会自动推回企业微信对话。
绑定粒度为“企业微信发送者 + 机器人安装记录”。连接机器人的人首次使用该机器人时也需要完成绑定；企业微信在安装时不会向 Mopheus 提供安装者的企业微信用户标识。
企业微信机器人的可用范围和 Mopheus 账号绑定是两个独立条件：发送者既要位于机器人的可用范围内，也要完成一次性 Mopheus 账号绑定。
集成区域会显示每个机器人绑定对应的 Mopheus 工作区安装人。
工作原理
入站：企业微信 → Mopheus
企微用户向智能机器人发消息
│
▼
WebSocket aibot_msg_callback 事件
│
▼
Mopheus channel engine 接收并路由
│
▼
创建会话 → 智能体任务入队
│
▼
智能体运行，产生回复
│
▼
Patcher 通过 aibot_send_msg 推回企微出站：Mopheus → 企业微信
Patcher 组件通过共享的 WebSocket 连接处理所有出站消息。
| 事件 | 发送的企微消息 |
|---|---|
| 智能体回复就绪 | 带智能体名称标题的 Markdown 回复 |
| 智能体任务失败 | 包含失败详情的错误卡片 |
| 工单状态变更 | 带工单引用的状态更新 |
| 工单有新评论 | 带工单引用和截断正文的 Markdown 预览 |
| 收件箱通知 | 发送到用户与机器人的 1:1 私聊中的 Markdown 卡片 |
所有出站消息以 msgtype: markdown 发送，纯文本通过 markdown 路径正常渲染。消息按 rune 安全截断到 4000 字节。
单副本约束
企业微信每个机器人仅允许一个活跃的 WebSocket 连接。Mopheus 通过 channel supervisor lease 机制强制单副本。若需水平扩展，请先配置 Redis Streams 中继（独立功能）。
消息历史
智能机器人长连接只接收机器人收到后的实时事件。当前集成不拉取普通群聊的历史消息；企业微信会话内容存档属于独立的合规能力，未包含在智能机器人连接配置中。
故障排除
| 现象 | 检查 |
|---|---|
| 机器人无响应 | 确认 启用企业微信 (wecom_enabled) 为 true，并确认关联智能体已绑定到已启用且在线的运行时。若配置了回退运行时，也可由其恢复排队任务。 |
| 日志中出现 "invalid bot_id or secret" | 安装时输入的 Bot ID 或 Secret 错误 — 使用正确的凭据重新连接 |
| 无出站通知 | 确认机器人的 WebSocket 连接处于活动状态（检查服务端日志 "wecom: subscribe ok"） |
| 智能体无回复 | 确认关联智能体已绑定到已启用且在线的运行时。若配置了回退运行时，也可由其恢复排队任务。 |