前言¶

在 DSH 里跑智能体时，桌面插件 dsh-pet 会把会话事件聚合成几档工作状态（思考、执行、等待、成功、错误等），并在本机 HTTP 路由上对外提供快照。若你还需要把同一份状态推给 webhook、用脚本轮询拉取，或让 DSH Mobile 手机桌宠收到气泡事件，单靠 dsh-pet 本身不够：它没有把原始会话事件和统一发布面全部暴露给第三方。

dsh-pet-bridge（维护者 XiaoPb，npm 包 @xiaopb/dsh-pet-bridge，当前版本 0.3.6）是 DSH 服务端插件，分类为工作流。它在 dsh-pet 与外部消费者之间做桥接：优先直连 dsh-pet 的官方聚合结果，必要时在本地按相同语义回放；同时提供 Token 鉴权下的 webhook 推送与回环 HTTP 拉取，并保留 v0.2.0 起面向手机桌宠的 /bubble 推送。

这是什么¶

一句话：监听 dsh-pet（或本地回放会话事件），把工作状态与原始事件发布到 webhook 和本机 HTTP 服务，并可选推送到 DSH Mobile 桌宠。

插件源自 npm 上游 dsh-pet-bridge@0.1.0（wsxwj123/dsh-plugins，MIT），工作状态聚合语义与 dsh-pet 0.3.8 对齐；与 0.2.x 的 /bubble 行为保持兼容。许可证为 MIT（见 GitHub 与 package.json）。

架构与数据通道¶

dsh-pet 通过 session/event 内部监听，把 DSH 会话事件聚合成 6 档工作状态，并在例如 GET /dsh-pet-7340/state 上长轮询发布。本桥用三条通道对接：

1. listen（主，mode=auto / listen）：长轮询 dsh-pet 的 GET /dsh-pet-7340/state?since=&timeout=，转发官方 {state, task}，与桌面 Helper 同源，避免重复实现聚合逻辑。
2. replay（备）：dsh-pet 不可达时，mode=auto 自动切到本地从 session/event 归约（语义同 dsh-pet 0.3.8）；恢复后切回直连。mode=replay 则仅本地归约。
3. 原始事件：turn/start、tool/call、tool/result、approval/asked、turn/end、todo/write 等进入环形缓冲（最多 200 条）并转发；用于 /bubble 与可选 webhook 的 kind="event"。老宿主不支持 session/event 时可回退 agent 轮询。

发布出口¶

webhook 信封示例（version: 1）：

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

Token 解析顺序：config.token → 环境变量 DSH_PET_BRIDGE_TOKEN → 进程内随机生成（不落盘，启动时经引擎日志输出一次）。回环服务除 /ping 外缺失或不匹配一律 403。

与 DSH Mobile 的兼容¶

0.3.2 起 /bubble 的五类 kind 主要从 session/event 派生，避免依赖已重构的 agent.session.events 数组。0.3.3 起 payload 可带 text（任务详情或随机台词，与 dsh-pet 措辞规则一致）；0.3.5 起可通过 selfPublishRandomLines（默认 true）控制无任务详情时是否由桥端自发布随机台词；关闭后 text 仅带真实任务详情，手机端可用 DSH Mobile 桌宠台词库。0.3.6 在浏览器设置中增加「桌宠桥接」分区，经 GET/PUT /dsh-pet-bridge-7781/config 读写并持久化到 $DSH_HOME/profiles/web/cordis.patch.yml。

资料提醒：无 scope 的 npm 包 dsh-pet-bridge 仅上游 0.1.0，不兼容带鉴权的 DSH Mobile；应使用 @xiaopb/dsh-pet-bridge。

安装与启用¶

Node 引擎要求 >=22.12.0（见 package.json）。peer 依赖 @deepseek-ai/cordis ^4.0.1。

推荐从 npm 安装：

dsh plugin add @xiaopb/dsh-pet-bridge

或从 GitHub 安装：

dsh plugin add github:XiaoPb/dsh-pet-bridge

面向 web profile 的写法（README 另节）：

dsh plugin --profile web add @xiaopb/dsh-pet-bridge

bundle 类插件安装后需重启 DSH 引擎。前置条件：希望走直连时，应先安装并启用 dsh-pet；仅 replay 可不装 dsh-pet，但直连是首选数据源。webhook 或拉取客户端需从引擎日志读取 bridge token（若未在配置或环境中固定）。

配置要点¶

通过 cordis config 或环境变量覆盖。常用键如下（默认值见 README）：

典型用法¶

拉取当前工作状态（需与配置或日志中的 token 一致）：

curl -H "X-DSH-Bridge-Token: <token>" http://127.0.0.1:7780/work-status

长轮询统一状态（since 与 timeout 成对）：

curl -H "X-DSH-Bridge-Token: <token>" \
  "http://127.0.0.1:7780/state?since=0&timeout=10"

验证手机桌宠链路（README 示例）：

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

仓库内自检：

npm test
npm run smoke

适用场景与注意¶

适合：需要在 DSH 智能体运行期间，把与 dsh-pet 一致的工作状态同步到自建监控、自动化脚本、或 DSH Mobile 桌宠；需要原始会话事件流而非仅最终 UI 状态的外部集成。

注意：

• 插件以当前 DSH 进程权限运行，安装前请阅读 GitHub 源码 与 MIT 许可证，自行评估 webhook URL 与本地端口暴露范围。
• 回环服务默认只监听 127.0.0.1；向公网转发需自行做反向代理与鉴权，勿把 token 写进不可信环境。
• 社区目录 SkillHub 插件页 与 GitHub 为独立生态信息源，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-pet-bridge 把 dsh-pet 的聚合状态与缓冲后的会话事件，整理成 webhook 推送、本机 HTTP 拉取和可选的 /bubble 三条消费路径，并用 Token 做 fail-closed 鉴权。若你的工作流依赖「桌宠所见即外部系统所得」，可先装 dsh-pet，再装本桥并按 targets 或 7780 端口对接消费者。

• 目录页：https://www.skillhub.cn/plugins/XiaoPb/dsh-pet-bridge
• 源码与文档：https://github.com/XiaoPb/dsh-pet-bridge