dfzjb/deskpet-bridge

DeskPet Bridge

给 DSH（DeepSeek Harness） 增加「外部可编程接口 + 可编程审批通道」的本地 JS agent preset 插件。

概述

deskpet-bridge 是一个独立的 agent preset（三个文件），放入 DSH 的 .agent-presets/ 目录即可生效，无需修改 DSH 仓库。

对 DSH 的作用

1. 扩展 DSH 的 Web 服务面

通过 DSH 自带的 webServer 注册 3 个新路由，让 DSH 多出几个可被外部程序调用的接口：

| 端点 | 用途 |
|---|---|
| GET /api/deskpet/v2/get-status | 查询当前 agent 状态快照 |
| GET /api/deskpet/v2/events | SSE 实时事件流 |
| POST /api/deskpet/v2/approve | 提交审批决定 |

2. 状态可观测性

监听 DSH 内部的 agent/status 事件，维护一份状态缓存（idle / running 等），并累计状态变更次数 changes 与 agent 数量 agentCount，使 DSH 的运行状态能被外部程序查询与订阅。

3. 可编程审批通道（核心）

作为 DSH 审批机制的一个 answerer：

- 通过 { prepend: true } 抢在 DSH 默认审批面板（api-proxy）之前认领 approval/request。
- 认领后将审批挂起（返回 pending Promise），并通过 SSE 把审批请求推送给外部客户端。
- 外部客户端通过 /approve 回传决定后，插件 resolve 该审批 —— 放行（allowed-once）或拒绝（rejected）。
- 120 秒无回应或收到 abort 信号时按 cancelled 处理，审批不会永久挂起。

4. 实时事件推送

通过 SSE 广播 DSH 内部事件：hello / agent-status / approval-request / approval-decided / approval-expired，并带 5 秒心跳保活。

5. 降级保护

没有外部客户端连接时，审批 answerer 直接 next() 放行，回落到 DSH 默认审批面板，不影响 DSH 原有审批流程。

文件结构

| 文件 | 用途 |
|---|---|
| agent.cordis.yml | composition 入口（id: deskpet-bridge + name: ./bridge.js） |
| bridge.js | 核心插件（ESM：export name / inject / apply） |
| preset.yml | preset 元数据（名称 + 描述） |

安装

将三个文件复制到 %DSH_HOME%/.agent-presets/deskpet-bridge/，然后在 agent session 中选择或设为默认 deskpet-bridge preset。

接口契约

基础地址：http://127.0.0.1:3080 · 前缀：/api/deskpet/v2/

GET /get-status

{"ok":true,"status":"idle","agentCount":4,"changes":0,"connectedClients":0,"pendingApprovals":0}

GET /events（SSE，text/event-stream）

事件类型：hello / agent-status / approval-request / approval-decided / approval-expired

POST /approve

{"approvalId":"appr_N","decision":"approve-once"}  → 200 {"ok":true,"outcome":"allowed-once"}
{"approvalId":"appr_N","decision":"reject"}         → 200 {"ok":true,"outcome":"rejected"}
未知 approvalId                                     → 404 {"ok":false,"error":"unknown approvalId"}

审批流程

approval/request (waterfall)
└─ prepend answerer 认领
├─ 有外部客户端 → 挂起 + 推送 SSE approval-request
│      └─ POST /approve → resolve allowed-once / rejected
└─ 无客户端 → next() → DSH 默认审批面板

120s 超时 / abort → cancelled

许可

MIT（与 DSH 许可一致）。