桌宠状态桥 XiaoPb/dsh-pet-bridge

dsh-pet-bridge

DSH 服务端插件：桥接 dsh-pet（桌面宠物插件），把它的会话事件与工作状态对外发布 —— webhook 主动推送 + 回环 HTTP 拉取服务，全程 Token 鉴权；同时保留 v0.2.0 的手机桌宠 /bubble 推送。

源自 npm 上游 dsh-pet-bridge@0.1.0（wsxwj123/dsh-plugins，MIT）；工作状态聚合语义移植自 dsh-pet 0.3.8（MIT）。当前版本协议与 0.2.x 兼容（/bubble 行为不变）。

安装

npm（推荐）
dsh plugin add @xiaopb/dsh-pet-bridge

或直接从 GitHub 装
dsh plugin add github:XiaoPb/dsh-pet-bridge

无 scope 的同名包 dsh-pet-bridge 只有上游 0.1.0（归原作者所有，无法发新版），不兼容带鉴权的 DSH Mobile。

与 DSH Mobile 的兼容矩阵

| DSH Mobile | 要求的本插件版本 | /bubble 协议 |
| ≥ v1.4.21（协议 v2） | ≥ 0.3.1 | 必带 X-DSH-Pet-Token（fail-closed 403），显式 Content-Length |
| < v1.4.21（协议 v1） | 0.1.x（上游） | 无 token |

0.3.1 同时修了上游 0.1.0 的真 bug：push() 未设 Content-Length（Node 走 chunked 编码），而 APK 只按定长读 body，必然回 400 —— 这是「插件已连接但桌宠没有事件」的隐性根因。App 侧从 v1.4.21 起按版本硬门禁，低于 0.3.1 会提示「需 0.3.1+」并禁止开启桌宠。

架构：怎么对接 dsh-pet

dsh-pet 是自包含插件，通过 session/event 内部监听把 DSH 会话事件聚合成 6 档工作状态（thinking / working / result / waiting / success / error）+ todo 任务详情，发布在自己的 HTTP 路由上（桌面 Helper 消费同一份）。本桥两条数据通道对接：

┌────────────────────────────────────────────┐
DSH 宿主 ──────────▶ dsh-pet（session/event → 官方聚合） │ │ │ GET /dsh-pet-7340/state（长轮询） │ ┌────────▼───────────────────────────────────┐ │ dsh-pet-bridge │ │ ① listen：直连 dsh-pet /state（主） │──▶ webhook 推送 │ ② replay：session/event 本地归约（备） │──▶ 回环拉取服务 │ ③ 原始会话事件转发（dsh-pet 未对外暴露） │──▶ /bubble（v0.2.0） └────────────────────────────────────────────┘

- ① listen（主，mode=auto/listen）：直连长轮询 dsh-pet 的 GET /dsh-pet-7340/state?since=&timeout=（与桌面 Helper 同源同协议），转发的是 dsh-pet 官方聚合结果 {state, task}——零逻辑重复，dsh-pet 升级不漂移。
- ② replay（备）：dsh-pet 不可达（未安装/未启动/下线）时，mode=auto 自动切到本地归约——从 session/event 按 dsh-pet 0.3.8 同款 reduceWorkStatus 语义（含 goal 续跑轮、todo 任务文案、终态 60s 清理）独立算出快照，保证对外不断流；dsh-pet 恢复后自动切回直连。
- ③ 原始事件：turn/start、tool/call、tool/result、approval/asked、turn/end、todo/write、user/message 等原始事件环形缓冲（200 条）+ 转发——这是 dsh-pet 对外没有暴露的部分，由桥补齐。宿主不支持 session/event 时回退 agent 轮询游标。

发布出口

| 出口 | 方向 | 鉴权 | 说明 |
| webhook targets | 推 | X-DSH-Bridge-Token（可按目标改头/换 token） | kind="work-status"（状态快照）推全部目标；kind="event"（原始事件）只推 events: true 的目标。fire-and-forget，失败不重试不上抛 |
| GET http://127.0.0.1:7780/work-status | 拉 | 同上 | 当前工作状态快照 {state, task, ts}（/ping 免鉴权存活探针） |
| GET http://127.0.0.1:7780/events?limit=N | 拉 | 同上 | 最近原始事件（新在后，上限 200） |
| GET http://127.0.0.1:7780/state?since=&timeout= | 拉 | 同上 | 统一发布状态 {counter, workStatus, events}，长轮询语义对齐 dsh-pet /state（since/timeout 成对必填，timeout ≤ 10s） |
| POST http://127.0.0.1:7779/bubble | 推 | X-DSH-Pet-Token（v0.2.0 契约不变） | 手机桌宠 5 类 kind：user/pre/post/stop |

webhook 信封（version: 1）：

{
"version": 1,
"source": "dsh-pet-bridge",
"kind": "work-status",
"workStatus": { "state": "working", "task": "写代码", "ts": 1760000000000 },
"sentAt": 1760000000000
}

kind="event" 时为 { "version": 1, "source": "dsh-pet-bridge", "kind": "event", "sessionId": "...", "event": { "type": "tool/call", "data": {...}, "seq": 3 }, "sentAt": ... }。

Token 鉴权（fail-closed）

- 回环服务：除 /ping 外，缺失或不匹配一律 403（恒时比较，不区分缺失与错误）。
- token 解析顺序：config.token > 环境变量 DSH_PET_BRIDGE_TOKEN > 进程内随机生成（不落盘，启动时经 logger.info 打一次——消费端从引擎日志取）。
- webhook：每请求带 X-DSH-Bridge-Token（默认头，target.header 可改），token 取 target.token ?? 全局 token。
- /bubble：沿用 v0.2.0——auth: "off" 可刻意不带 token（模拟上游 0.1.0 验证 App 侧 403 fail-closed）。

配置（cordis config）

| 键 | 默认 | 说明 |
| mode | auto | auto=直连 dsh-pet，失败回退本地归约、恢复切回；listen=仅直连；replay=仅本地归约。环境变量 DSH_PET_BRIDGE_MODE 可覆盖 |
| petBaseUrl | http://127.0.0.1:3080 | dsh-pet 路由 origin（与桌面 Helper 同源）。环境变量 DSH_PET_BRIDGE_PET_URL 可覆盖 |
| serverEnabled | true | 回环拉取服务开关 |
| serverPort | 7780 | 回环拉取服务端口（仅绑定 127.0.0.1） |
| token | 见上 | 回环服务 + webhook 默认 token |
| targets | [] | webhook 目标数组：{url, header?, token?, events?, timeoutMs?} |
| port | 7779 | v0.2.0：手机桌宠 /bubble 端口（仅回环生效） |
| pollInterval | 250 | v0.2.0：事件轮询间隔（ms），必须 >0 |
| enabled | true | false 时装载但零推送 |
| auth | auto | v0.2.0：off=刻意不带 /bubble token |

验证

npm test # 单测（node:test，27 项）
npm run smoke # E2E 冒烟：伪 dsh-pet + 伪 ctx 全链路（listen/replay/事件/bubble/webhook）

验证 APK（假数据框架，v0.2.0 既有）：

adb forward tcp:17779 tcp:7779
node tools/verify-apk.mjs --token <DSH_PET_BRIDGE_TOKEN> --port 17779

安装

从 npm 安装（推荐）
dsh plugin --profile web add @xiaopb/dsh-pet-bridge

或本地路径安装
dsh plugin --profile web add /path/to/dsh-pet-bridge
之后重启引擎（bundle 插件不热加载）

前置：dsh-pet 已安装并启用（replay 模式可不装，但直连是首选数据源）；webhook/拉取的消费端拿引擎日志里的 token。

CI/CD

.github/workflows/release.yml（结构参考 dsh-hardssh）：push/PR/手动跑 verify（元数据校验 → 单测 → E2E 冒烟 → npm pack → tarball 形状校验）；v* tag 额外触发 npm 发布（trusted publishing OIDC 优先、NPM_TOKEN 兜底，pre-release 自动走 next dist-tag）与 GitHub Release（分类 changelog + tarball + SHA256SUMS）。compat.yml：Node 22.12 / 24 矩阵 × 单测 / 冒烟 / 打包三验证面。

许可

MIT。源自上游 dsh-pet-bridge（MIT）；工作状态聚合语义移植自 dsh-pet（MIT）。