# 微信 Bot 接入系统 AI

系统提供 `POST /api/wechat/bot/reply` 作为统一桥接接口。微信侧只负责收发消息，Agent、数字人、技能和已绑定知识库由系统处理。

## 配置

在生产服务器的 `/Users/macclaw/Desktop/yawan-workbench/.env.production` 设置（项目提供了 `.env.production.example` 模板；启动脚本和守护脚本会自动读取）：

```bash
YAWAN_WECHAT_ADAPTER_URL=http://127.0.0.1:8765
```

现在使用多账号模式时不需要手动填写 Bot Secret、Agent ID 或用户 ID。创建数字人后系统会自动生成同名 Agent 并绑定；数字人审核生效后，在“数字人 → 微信 Bot 连接”中选择该 Agent 并扫码。系统会为每个账号自动生成独立密钥和凭据目录。一个数字人可以绑定多个 Agent。

接口支持时间戳 HMAC 请求头：

```text
X-WeChat-Bot-Timestamp: 当前 Unix 秒
X-WeChat-Bot-Signature: HMAC-SHA256(secret, timestamp.conversation_id.message_id.text)
```

`message_id` 用于幂等。Bot 重试同一消息时，系统会直接返回上次回复，不重复扣费。旧适配器也可暂时使用 `X-WeChat-Bot-Secret`，但新接入应升级到 HMAC。

## Wechaty 开发验证

`scripts/wechat_bot_adapter.mjs` 是可运行示例：

```bash
cd /Users/macclaw/Desktop/yawan-workbench
npm i wechaty wechaty-puppet-wechat4u
YAWAN_API_URL=https://agent.pducv.cn \
  YAWAN_WECHAT_BOT_SECRET="$YAWAN_WECHAT_BOT_SECRET" \
  YAWAN_WECHAT_AGENT_ID=3 \
  node scripts/wechat_bot_adapter.mjs
```

个人微信的 Web/UOS 协议存在封号和兼容性风险，只建议开发测试。生产建议使用腾讯官方 [openclaw-weixin](https://github.com/Tencent/openclaw-weixin) 的 iLink Bot 通道，或企业微信/公众号官方回调；这些适配器只需把收到的文本按同样 JSON 调用本接口，再将 `reply` 发回微信。

## 官方 iLink 多账号 sidecar

项目还提供 `scripts/wechat_ilink_sidecar.mjs`，使用 CoreSpeed 的官方 iLink SDK 管理多个账号。启动：

```bash
cd /Users/macclaw/Desktop/yawan-workbench
npm i @wechatbot/wechatbot
YAWAN_API_URL=https://agent.pducv.cn \
  YAWAN_WECHAT_SIDECAR_PORT=8765 \
  /opt/homebrew/opt/node@22/bin/node scripts/wechat_ilink_sidecar.mjs
```

`@wechatbot/wechatbot` 要求 Node.js 22 或更高版本；macOS/Homebrew 环境请使用上面的 Node 22 路径，或将 Node 22 放在 `PATH` 首位。

然后在 API 服务环境设置 `YAWAN_WECHAT_ADAPTER_URL=http://127.0.0.1:8765`。数字人页面点击“微信 Bot 连接”即可生成官方二维码；每个账号使用独立密钥、独立凭证目录和独立会话，只能调用自己绑定且有权限的 Agent。

请求示例：

```json
{"agent_id":3,"conversation_id":"wx-room-or-user-id","message_id":"msg-001","text":"你好，帮我介绍一下课程"}
```

系统会保留会话上下文，并把 Agent 的数字人规则、已挂接技能和知识库相关片段用于本轮回答。知识库检索失败时会记录日志并继续普通对话，避免微信侧卡死。