Skip to content

十、微信桥(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/*.mjs7 组单测:agent 输出、主动上下文、引用、重试、RPC 游标、store、inbound
systemdcosmos-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_MS420000单次问答总超时(240s 曾切在 p95/p99 之间,实测调大)
COSMOS_WX_HOLD_MS30000第一段等待,超时先回"还在做"
COSMOS_WX_ROTATE_KB600会话体积轮换线(超了下一轮换新会话)
COSMOS_WX_HEARTBEAT_MS300000心跳上报间隔(走采集令牌,不影响收发)
COSMOS_WX_NOTIFY_PORT / BIND8790 / 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 会话与博客数据库中。

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。