# 企业微信智能机器人接入指南

通过 `/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 配置选项
