Files
agent/wxbot/README.md
T
kicer b97b13095f 部署初始化收敛:init.sh 不再生成配置,只做 .env + 公网地址 + 初始 admin
- scripts/init.sh 重写:不再生成模型/MCP/用户配置;只维护 .env(幂等复用密钥、保留手改变量)、
  探测 PUBLIC_BASE_URL、config.yml 缺失时写入初始管理员(admin/admin)。已存在绝不改写;
  Docker 误建的空目录自动删除重建,非空目录报错退出;去掉 --env-only 参数
- config.js:config.yml 缺失/为空/被误建成目录都能正常启动(不再 EISDIR 崩);PATCH 在文件
  缺失时以空文档继续并自动创建;public_link 改为 config.yml 优先、PUBLIC_BASE_URL 兜底
- compose:ASR_URL 固定为 http://mcp_asr:3000;agent-core 注入 PUBLIC_BASE_URL;
  token 缺失提示改指 scripts/init.sh
- 删除 .env.example(与 init.sh/compose 重复),引用改指 README
- 移除仓库内所有 VIRTUAL_HOST/VIRTUAL_PORT/CERT_NAME 关联(特定部署的反代约定,不进仓库)
- 同步 README / AGENTS.md / config.example.yml / init_host.sh / wxbot / mcp 文档
2026-10-25 08:42:26 +08:00

93 lines
6.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# wxbot
Agent 栈的微信「调制解调器」:基于官方 iLink 协议的 Node SDK
[`@wechatbot/wechatbot`](https://www.wechatbot.dev/zh/nodejs),同进程多实例,
一个实例对应 agent-core 的一个用户绑定(扫码登录后,该微信里出现 bot 好友,
发给它的消息即进入你的 Agent 会话,回复实时推回)。
**本服务不保存业务状态、不对外服务**:绑定关系(core 用户 ↔ bot 账号)的权威在
agent-core 的 `wechat_bindings` 表;扫码二维码呈现在 agent-core 的 Web 设置页
(账户 → 微信绑定)。本服务已并入根 `docker-compose.yml`(`agent-wxbot` 服务),目录代码已入 git 库;
零配置文件运行,接线全靠 compose 注入的 env(见下)。
## 架构与数据流
```
微信用户 ⇄ [iLink] ⇄ agent-wxbot(本服务, :8093, 仅内网 agent-mcp-net)
│ 收信转发 POST core:/wxhook/inbox {id, from, text}
│ 状态回调 POST core:/wxhook/hook {id, event, accountId?}
│ 接收投递 POST self:/api/deliver ← core 推最终回复
agent-core ⇄ 浏览器 ⇄ core:/api/wechat(cookie 鉴权,绑定管理 + QR SVG 代理)
│ 实例控制 POST/DELETE agent-wxbot:/api/instances*
└ 总线监听 assistant 消息 → 分段投递(游标落库不重发)
```
- 收信 → core `/wxhook/inbox` 复用 **channel 命令层**(`/new /list /switch /rename /delete /models /stop /compact /clear /status /help`),
命令回执同步回文本;普通消息(AI 回复)异步由 core 经 `/api/deliver` 推送(`bot.send`)。
图片/视频/文件消息经 SDK `download` 取字节随 inbox 转发(限 20MB),core 落会话任务目录;带说明文字的
拼「用户上传了文件」告知行一起触发回合,**单发媒体只静默留痕不唤醒 AI**(下次提及自然能指代到该文件)。
- **单线对话**:iLink 扫码登录后只有绑定者本人能与 bot 会话,无陌生人入口,故无联系人授权面。
- 实例凭证按绑定隔离在 `./data/bots/<binding_id>/`,容器重启自动恢复登录免扫码;
启动时扫描该目录逐个拉起实例(core 不在线也照常上线,状态回调失败不影响,首条消息会纠偏)。
- **一个微信账号全集群只允许一个实例在轮询**(SDK 硬约束):绑定表 + wxbot 实例 Map 双重防重。
## 配置:零文件(同 executor 模式)
接线全靠根 compose 注入的环境变量,**不需要 wxbot/.env,也不需要 config.yml**:
| env | 来源 | 用途 |
| --- | --- | --- |
| `WXBOT_TOKEN` | 根 `.env`(`scripts/init.sh` 生成/复用) | 本服务 `/api/*` 鉴权白名单(自动并入)+ 回调 core `/wxhook/*` 的凭据,与 core 侧同一值双向互信 |
| `CORE_URL` | compose 静态注 `http://agent-core:8090` | 转发目标 |
| `WXBOT_LOG_LEVEL` | compose 静态注 `info` | 日志等级(debug 原样打印收信消息结构;none/off→silent) |
| `WXBOT_STRIP_MARKDOWN` | 根 `.env` 可选(默认空) | 出口 markdown 纯文化开关:空/0 = 原样透传(微信已支持渲染);1 = 恢复 stripMarkdown 降级 |
端口、非文本消息占位文案等次要旋钮走 `src/server.js` 内置 DEFAULTS;日志等级由 env `WXBOT_LOG_LEVEL`
决定(compose 注入,同 executor 的 `EXECUTOR_LOG_LEVEL` 约定;`debug` 原样打印收信消息结构,
长文本截断、Buffer 只记大小,便于观察新消息类型字段)。
本服务**不挂不读 core 的 `config.yml`**(内含平台密钥/登录 secret,只给 core 进程)。
## 部署
```sh
./scripts/init.sh # 生成/复用根 .env 的 WXBOT_TOKEN(幂等)
docker compose up -d --build agent-wxbot # 首次构建镜像(npm 源可 --build-arg NPM_REGISTRY= 换)
docker compose up -d agent-core # core 带 WXBOT_URL/WXBOT_TOKEN 重建(compose 检测到 env 变化自动 recreate)
```
之后绑定在 **agent-core 的 Web 设置页 → 账户 → 微信绑定** 完成:生成二维码 → 扫一扫 →
手机确认 → 上线;换微信号先解绑再重绑。core 侧关闭微信入口:根 `.env` 置 `WXBOT_URL=`
(设置页自动隐藏,服务零报错)。
## 接口(仅内网可达;除 /health 外需 Bearer WXBOT_TOKEN)
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/health` | `{ok, instances:[{id,state}]}`,免鉴权 |
| GET | `/api/instances` | 实例列表(core 启动对账用) |
| POST | `/api/instances {id}` | 幂等确保实例存在(新建绑定/重启恢复) |
| POST | `/api/instances/:id/refresh` | 重发登录流程(二维码过期/失败后;保留凭证) |
| DELETE | `/api/instances/:id` | 销毁实例并删登录凭证(解绑) |
| GET | `/api/instances/:id/qr.svg` | 当前登录二维码(core 设置页代理渲染) |
| POST | `/api/deliver {id,to,text}` | 文本投递(core 已分段;markdown 默认透传,微信已支持渲染,`WXBOT_STRIP_MARKDOWN=1` 时出口纯文化) |
| POST | `/api/typing {id,to}` | 「正在输入」心跳(core 在工具调用/结果时触发,每绑定 2s 冷却;typing 自然过期无需 stopTyping) |
| POST | `/api/deliver_media {id,to,filename,b64}` | 附件投递(core 已把正文里的 /p/ 链接换成本地字节并做归属/大小校验;SDK 按扩展名自动路由 image/video/file 卡片) |
## 本地调试
```sh
set -a && . ./.env && set +a # 仓库根的 .env(WXBOT_TOKEN)
npm --prefix wxbot/app install
WXBOT_TOKEN=$WXBOT_TOKEN CORE_URL=http://127.0.0.1:8090 \
node wxbot/app/src/server.js
```
## 已知边界 / 后续扩展
- 语音消息已接入:iLink 服务端自动转写(`msg.text` 即识别文字),按普通文本转发进会话——
语音说 `/new` 这类命令也能用;转写为空(环境噪音等)时回 `bot.empty_hint` 占位提示。
原始 silk 音频不下载,无需本地 ASR。
- 出站文件/图片已实现「链接→卡片」:AI 在回复正文里给 mint 链接,core 自动换成微信文件卡片
(链接文字保留兜底);AI 侧约定见 core 注入的 channel_note。
- core 未配 `WXBOT_URL` 时微信功能整体静默关闭(设置页不出现入口,服务零报错)。