主题
十、微信桥(deploy/agent/wechat-bridge)
本章速览:读完后你会知道 —— ① 一条微信消息如何进来、合并、交给 DSH、再把回答发回去;② 超时、空回答、发送失败分别怎么兜底;③ 主动推送端点与会话轮换、心跳、清理策略;④ 常见故障怎么恢复。
定位:协议适配层 + 消息调度器。微信只负责收发;判断、记忆、工具调用全部交给 DSH / 博客后端。桥不写业务数据,只做"可靠地把消息送进去、把回答送出来、把主动消息推出去"。
10.1 组成与运行形态
| 文件/目录 | 作用 |
|---|---|
bridge.mjs(约 3800 行) | 主进程:登录、长轮询收发、DSH 调用、推送端点、心跳、会话管理 |
lib/dsh-store.mjs | 访问 DSH 私有存储的唯一入口(工作区 id、会话体积、旧会话清理);DSH 升级只改这一层 |
lib/inbound.mjs | 微信报文 → 结构化消息(引用/媒体/纯媒体识别)的纯函数,可单测 |
state/ | sessions.json(用户↔会话)、get-updates-buf.txt(水位)、last-context-token.json、notify-dedup.json |
work/ | DSH 会话工作目录(wxagent profile;admin-chat/ 是后台对话的独立目录) |
test/*.mjs | 7 组单测:agent 输出、主动上下文、引用、重试、RPC 游标、store、inbound |
| systemd | cosmos-wechat-bridge.service(含 whitelist drop-in) |
命令:login(扫码)、run(常驻)、status(账号/会话/水位)、ask(不经微信直接问一次)。
10.2 入站:一条微信消息如何变成回答
长轮询 get_updates(水位落盘:重启不重复收、不丢消息)
│
├─ 去抖 debounce:短时间内的"图/文件 + 文字说明"合并成一条(否则第一轮模型只能猜)
├─ 解析 inbound:文本/引用(提取被引用内容)/媒体(下载→嗅探 MIME→上传博客附件)
├─ 刷新 instructions(/api/agent/instructions.md,带时间头)
├─ 调 DSH:--session-id 续会话;RPC 流式读取
│ ├─ 第一段等待 30s(≈p75):超时先回"还在做,好了直接发给你"
│ ├─ 总超时 420s:基于真实尾延迟定(p95≈243s);超时分类记录
│ └─ 空正文(只有思考过程):重试一次专用提示词
└─ 回发:长文分片 → 发送重试 3 次 → 仍失败入待送队列(下一条消息带来新 context_token 时补发)关键参数(都可用环境变量覆盖,默认值来自实测):
| 参数 | 默认 | 说明 |
|---|---|---|
COSMOS_WX_DSH_TIMEOUT_MS | 420000 | 单次问答总超时(240s 曾切在 p95/p99 之间,实测调大) |
COSMOS_WX_HOLD_MS | 30000 | 第一段等待,超时先回"还在做" |
COSMOS_WX_ROTATE_KB | 600 | 会话体积轮换线(超了下一轮换新会话) |
COSMOS_WX_HEARTBEAT_MS | 300000 | 心跳上报间隔(走采集令牌,不影响收发) |
COSMOS_WX_NOTIFY_PORT / BIND | 8790 / 127.0.0.1 | 推送端点;容器访问时改绑 compose 网关,绝不 0.0.0.0 |
COSMOS_WX_ALLOW | 空 | 微信用户白名单(建议设置) |
会话管理:工作区 id 由 cwd 决定;会话命名由 dsh-session-rename-guard.mjs 维护 (按"微信对话/主动文案"打标签);空闲 7 天的会话每小时清理一次(保留当前会话); 收件箱文件 14 天清理;会话体积接近 600KB 时日志提示、达到则换新会话。
10.3 推送端点:主动消息的"最后一公里"
桥在回环开 HTTP,供博客通知链调用:
| 端点 | 作用 |
|---|---|
POST /notify | 接收 {title, content},推送到微信;24h 去重(文件)、分片、重试 3 次 |
GET /health | 暴露账号/队列/最近一次发送结果(lastSendOk/error) |
POST /compose | 主动文案润色:facts ≤20000 字、maxChars 40–2000、timeoutMs 1–120s;场景守卫;返回文本与 usage |
POST /agent | 扩展平台 agent 运行时:profile 白名单、工具黑名单、run id 校验、输出 schema |
GET/POST /admin-chat* | 后台对话:pending 登记/ack/archive、投递与取回 |
推送语义:先微信、失败降级邮件(由博客侧通知链决定);桥侧的失败不改变博客的 "已通知"判断之外的状态,避免重复推送。notify-dedup.json 记录 24h 去重键。
10.4 失败模式与恢复手册
| 症状 | 原因 | 恢复 |
|---|---|---|
推送失败 ret=-2 prepare failed | 微信 context_token 过期(主动消息需要近期入站上下文) | 用微信给 bot 发一句话刷新 token;无需重新扫码 |
| 推送端点不通(容器化后) | 桥绑 127.0.0.1,容器访问不到宿主机回环 | 把 COSMOS_WX_BIND 设为 compose 网关地址(如 172.18.0.1),不要 0.0.0.0 |
| 回答超时 | DSH 长任务/插件卡住 | 看 bridge.log 的 [reply-outcome];桥先回过"还在做";ask 命令可单独排障 |
| 会话体积过大 | 单会话无限增长 | 达到 600KB 自动换新会话(下一轮生效);日志会提示接近阈值 |
| 桥没起来 | systemd 服务停/崩溃 | systemctl status cosmos-wechat-bridge;日志 bridge.log + journal |
| 后台对话卡住 | DSH 超时未答 | 桥登记 pending,AdminChatPendingJob 每 10s 取回;也可在后台归档该会话 |
10.5 安全边界
- 桥只服务白名单用户(
COSMOS_WX_ALLOW); - 推送端点无鉴权,默认只绑回环;只允许内网网关地址,禁止公网绑定;
- DSH 工作目录与后台对话目录隔离;后台对话不进 Hindsight(微信会话才进);
- 桥的日志不写会话正文(只写计数/长度/结果),消息内容只存在 DSH 会话与博客数据库中。