@tencent-ai/codebuddy-code 2.67.0 → 2.68.0

package/dist/web-ui/docs/cn/cli/wecom-bot-setup.md

@@ -0,0 +1,274 @@
+# 企业微信智能机器人接入指南
+
+通过 `/remote-control` 命令，您可以将 CodeBuddy Code 快速接入企业微信智能机器人，实现远程消息驱动。采用 **WebSocket 长连接** 主动连接方式，无需公网 IP，配置最为简洁。
+
+## 前置条件
+
+- 已注册企业微信账户
+- CodeBuddy Code 已安装：`codebuddy --version`
+- 已完成登录认证：`codebuddy` 后执行 `/login`
+
+
+## 2. 配置环境变量
+
+在启动 CodeBuddy CLI 前，设置以下环境变量：
+
+```bash
+export CODEBUDDY_WECOM_BOT_ID="<你的 Bot ID>"
+export CODEBUDDY_WECOM_BOT_SECRET="<你的 Bot Secret>"
+```
+
+### 可选配置
+
+| 环境变量 | 说明 | 默认值 |
+|---------|------|--------|
+| `CODEBUDDY_WECOM_BOT_ID` | AI Bot ID（必填） | — |
+| `CODEBUDDY_WECOM_BOT_SECRET` | AI Bot Secret（必填） | — |
+| `CODEBUDDY_WECOM_BOT_WS_URL` | WebSocket 服务地址（私有化部署时使用） | `wss://openws.work.weixin.qq.com` |
+
+### 持久化配置（可选）
+
+将环境变量添加到 shell 启动文件中，每次启动时自动生效：
+
+```bash
+# ~/.zshrc 或 ~/.bashrc
+export CODEBUDDY_WECOM_BOT_ID="<你的 Bot ID>"
+export CODEBUDDY_WECOM_BOT_SECRET="<你的 Bot Secret>"
+```
+
+---
+
+## 3. 启动 CodeBuddy 并连接
+
+### 3.1 启动交互模式
+
+```bash
+codebuddy
+```
+
+### 3.2 打开远程控制面板
+
+```
+/remote-control
+```
+
+此命令打开交互式面板，列出所有可用的连接客户端。
+
+### 3.3 连接 wecom-bot
+
+使用方向键选择 `wecom-bot` 条目，按 `Enter` 发起连接：
+
+```
+Remote Control Clients
+
+  1. • wecom-bot  [disconnected]  (Press Enter to connect)
+  2. • centrifugo [disconnected]
+  3. Cancel
+```
+
+连接成功后面板会自动关闭。如果环境变量未配置，面板会停留并显示错误信息。
+
+### 3.4 查看连接状态
+
+再次执行 `/remote-control` 可查看连接状态：
+
+```
+  1. • wecom-bot  [connected]  (Press Enter to disconnect)
+  2. Cancel
+```
+
+状态说明：
+- `disconnected` — 未连接，可选择发起连接
+- `connecting` — 连接中，请稍候
+- `connected` — 已连接，可选择断开连接
+
+---
+
+## 4. 面板操作说明
+
+| 操作 | 说明 |
+|------|------|
+| `↑` / `↓` | 选择客户端条目 |
+| `j` / `k` | Vim 风格导航（等同于上下方向键） |
+| `Enter` | 连接（`disconnected` 状态）或断开（`connected`/`connecting` 状态） |
+| `Esc` | 退出面板（操作进行中时不响应） |
+
+---
+
+## 5. 验证接入
+
+连接建立后，可通过以下方式验证 Bot 是否正常工作。
+
+### 方式一：直接对话
+
+1. 打开企业微信客户端（桌面端或移动端）
+2. 在消息列表中找到你创建的机器人
+3. 发送测试消息（如「你好」），确认 Bot 有回复
+
+### 方式二：群组对话
+
+1. 将机器人添加到群聊
+2. 在群组中通过 @机器人名称 发送消息
+3. Bot 会响应被 @ 的消息
+
+---
+
+## 6. 消息处理流程和状态指示
+
+### 消息处理全流程
+
+用户发送消息到 Bot 后的处理流程：
+
+```
+用户在企业微信发送消息
+        ↓ WebSocket 长连接实时推送消息
+CodeBuddy CLI 接收消息
+        ↓ 5 秒内回复（满足企微回调超时要求）
+发送流式消息 (stream finish=false)："正在处理，请稍候..."
+        ↓ 企微客户端展示流式消息
+Agent 处理中...（处理时间可能 1 秒到 5+ 分钟）
+        ↓
+处理完成，发送流式消息 (stream finish=true)：最终结果
+        ↓ 企微客户端用最终结果全量替换"正在处理..."
+企业微信用户看到最终回复（聊天记录中仅保留最终结果）
+```
+
+### 流式状态指示机制
+
+利用企微流式消息（`aibot_respond_msg` stream 类型）的全量替换特性：
+
+1. **立即回复**：收到用户消息后，立即发送 `finish=false` 的流式消息，内容为"正在处理，请稍候..."
+2. **原位替换**：Agent 处理完成后，用同一个 `stream.id` 发送 `finish=true` + 最终结果
+3. 企微客户端收到 `finish=true` 后，用全量内容替换之前显示的"正在处理..."
+
+> 参考：[智能机器人长连接文档](https://developer.work.weixin.qq.com/document/path/101463) —— stream.content 为全量内容，每次发送替换上一次的显示。
+
+#### 用户看到的效果
+
+| 阶段 | 聊天窗口显示 | 说明 |
+|------|-----------|------|
+| 消息发送后 | "正在处理，请稍候..." | 流式消息占位，表示 Bot 正在处理 |
+| 处理完成后 | 最终回复内容 | "正在处理..."被最终结果原位替换 |
+
+#### 与之前方案的区别
+
+| 方面 | 旧方案（文本消息 ack） | 新方案（流式消息替换） |
+|------|---------------------|---------------------|
+| "正在处理..." | 永久保留在聊天记录 | 被最终结果原位替换 |
+| 聊天记录 | 2 条消息（ack + 结果） | 1 条消息（仅最终结果） |
+| 状态指示 | 有 | 有 |
+
+### 超时处理
+
+- **流式消息超时**：6 分钟（从首次发送 stream 开始计时）
+- **安全超时**：5 分钟（预留 1 分钟余量）
+- **超时回退**：如果 Agent 处理超过 5 分钟，自动回退到异步推送（`aibot_send_msg`，24 小时有效期）
+- **回调超时**：收到消息回调后需在 5 秒内发送回复（流式占位消息满足此要求）
+
+---
+
+## 7. 工作原理
+
+```
+企业微信用户发送消息
+        ↓
+企业微信服务器（WebSocket 连接池）
+        ↓ WebSocket 长连接实时推送
+CodeBuddy CLI（WecomBotClient）
+        ↓
+CodeBuddy Agent 处理消息，生成回复
+        ↓
+通过同一 WebSocket 连接回复消息
+        ↓
+企业微信用户收到 Bot 回复
+```
+
+### 关键特性
+
+- **连接方式**：WebSocket 长连接（客户端主动连接，无需公网 IP）
+- **认证机制**：启动时发送 `aibot_subscribe` 帧，携带 `bot_id` + `secret` 完成鉴权
+- **消息接收**：企业微信服务器通过 `aibot_msg_callback` 帧实时推送用户消息
+- **消息回复**：通过 `aibot_respond_msg` 帧以流式方式返回 Agent 回复
+- **心跳保活**：每 30 秒发送一次 `ping` 帧保持连接活跃
+- **自动重连**：连接断开后按指数退避策略自动重连，最长延迟 60 秒
+
+---
+
+## 8. 常见问题
+
+### 环境变量未配置
+
+**症状**：在 `/remote-control` 面板中选择 `wecom-bot` 后显示错误
+
+```
+Error: WeChat Work AI Bot is not configured.
+Missing environment variables: CODEBUDDY_WECOM_BOT_ID, CODEBUDDY_WECOM_BOT_SECRET
+```
+
+**解决方案**：
+1. 确认已设置 `CODEBUDDY_WECOM_BOT_ID` 和 `CODEBUDDY_WECOM_BOT_SECRET`
+2. 执行 `echo $CODEBUDDY_WECOM_BOT_ID` 验证环境变量是否生效
+3. 重新启动 CodeBuddy CLI
+4. 再次执行 `/remote-control` 尝试连接
+
+### 连接失败
+
+**可能原因及排查**：
+
+1. **Bot ID 或 Secret 错误**
+   - 确认从企业微信后台复制的值完全一致（注意末尾是否有空格）
+   - 确认 AI Bot 应用状态正常，未被停用
+
+2. **网络连接问题**
+   - 检查是否能访问 `wss://openws.work.weixin.qq.com`
+   - 如使用私有化部署，确认 `CODEBUDDY_WECOM_BOT_WS_URL` 设置正确
+   - 尝试在浏览器中测试网络连接：`curl -v wss://openws.work.weixin.qq.com`
+
+3. **CLI 日志查看**
+   - 查看终端输出的错误日志
+   - 执行 `codebuddy` 后保持在主界面，观察连接过程中的输出
+
+### 连接后消息无响应
+
+**排查步骤**：
+
+1. 执行 `/remote-control` 确认 `wecom-bot` 状态为 `connected`
+2. 如状态为 `disconnected`，重新连接
+3. 检查 CLI 终端日志是否有错误信息
+4. 确认 CodeBuddy CLI 进程仍在运行（未被中断或退出）
+
+### CLI 重启后需要重新连接
+
+`/remote-control` 连接状态是临时的，不会持久化。每次重启 CodeBuddy CLI 后，需要重新执行 `/remote-control` 并选择 `wecom-bot` 建立连接。
+
+**自动连接方案**（如需每次启动自动连接）：
+
+将以下内容添加到启动脚本或 shell 配置文件中：
+
+```bash
+# ~/.zshrc 或 ~/.bashrc
+export CODEBUDDY_WECOM_BOT_ID="<你的 Bot ID>"
+export CODEBUDDY_WECOM_BOT_SECRET="<你的 Bot Secret>"
+
+# 可选：创建别名快速启动并自动连接
+alias cbc-wecom='codebuddy -c "/remote-control"'
+```
+
+> 其中 `-c` 参数表示启动时自动执行指定命令。
+
+### 应用提示"Token 过期"或"Secret 无效"
+
+这通常表示 Bot 的 Secret 已失效或被重新生成。解决方案：
+
+1. 登录企业微信管理后台，进入 Bot 详情页
+2. 在「API 配置」区域重新生成 Secret
+3. 更新环境变量 `CODEBUDDY_WECOM_BOT_SECRET`
+4. 重启 CodeBuddy CLI 并重新连接
+
+---
+
+## 相关文档
+
+- [Remote Control（远程控制）](./remote-control.md) - 了解 Remote Control 的完整功能和其他客户端
+- [斜杠命令](./slash-commands.md) - 掌握所有内置命令
+- [设置配置](./settings.md) - 了解 CodeBuddy 配置选项