dsh-desktop-bridge

给正在运行的 DSH（DeepSeek Harness）宿主——桌面端应用，或一个 dsh web 服务——开一个带令牌鉴权的本机 HTTP 接口。任何本地程序都能调用它：脚本、构建工具、 别家的 agent、curl。

安全敏感。 插件启用期间，任何能读到 <DSH_HOME>/desktop-bridge.json 的进程，都能列出你的会话、读取它们的事件、往里面发消息、并创建新会话——每个新会话 都会启动一个以你的权限运行的 agent。安装前请读 SECURITY.md， 不用的时候把插件停掉。

English documentation: README.md。

为什么需要它

DSH 把会话控制留在宿主进程里，也就是 sessionController 服务。这是有意为之，也正 因为如此，常规入口都够不着一个已经在跑的应用：

• dsh --profile desktop … 直接拒绝——error: profile "desktop" is managed exclusively by the Electron application。桌面端独占的 profile，CLI 既不能启动 也不能往里装插件。
• SDK / ACP 那些入口会启动它们自己的宿主，因此够不着你正在看的那个实例里的会话。

本插件跑在那个宿主内部，把它的 sessionController 以 bearer 令牌保护的形式重新 发布到一个回环端口上。除此之外什么都没有改变：不启动第二个 profile，桥接自身不写会话 文件，也不对外网开放。

与其他同名/同类包的区别

包	机制	谁能用它驱动 DSH
本插件	回环 HTTP + bearer 令牌	任何本地进程、任何语言、curl
dsh-session-bridge	注册在 DSH 内部的 agent 工具	只有 DSH 自己的 agent，且要在它的对话里
dsh-agent-bridge	通过配方拉起别的 agent CLI	别的 agent CLI，不是任意程序
dsh-desktop-bridge（npm 上另一位作者的包）	只读的 fetch 路由	只读，不能创建与发送

npm 上的 dsh-desktop-bridge 已被一个不相关的只读包占用，所以本包以 scope 形式发布。

环境要求

• DSH 的 profile 组合里包含 @deepseek-ai/dsh-web-app（桌面端和 dsh web 都满足）。 该 bundle 挂载 @deepseek-ai/dsh-api-session-controller，它提供本插件注入的 sessionController 服务。
• 随包的命令行客户端需要 Node.js ≥ 20。插件本体用宿主的运行时，且零依赖。

安装

让 agent 帮你装

如果你的会话用的是 cordis 预设，agent 手里有插件管理工具，整件事它自己能办完—— 直接说：

安装插件 @ignotuss/dsh-desktop-bridge

standard 和 ptc 预设把那个工具关掉了；在这两个预设下 agent 没有任何安装手段， 只能退回到下面的命令。想在桌面端用"对话即安装"，先在 设置 → Agent 预设 里换成 cordis。

CLI 管理的 profile（web、tui、headless）

dsh plugin --profile web add @ignotuss/dsh-desktop-bridge

本包是 bundle：它自带的 cordis.patch.yml 会挂载插件，所以装上即启用。重启该 profile（或在开启了 HMR 的场合交给它），然后在 设置 → 插件 里确认状态为已启用。

DSH 桌面端

桌面端独占自己的 profile，CLI 按设计拒绝它。请在侧栏 插件 → 添加插件 里填入包名 （或本地检出目录），并选择 立即启用。以后改完源码要生效，把该插件的开关关掉再打开 即可——在线的 profile 会就地重组合，不需要重启整个应用。

使用

装上包之后还会得到一个 dsh-desktop-bridge 命令：

dsh-desktop-bridge list
dsh-desktop-bridge create ~/projects/demo "发版排查"
dsh-desktop-bridge events session-1f0e…-… 50
dsh-desktop-bridge send session-1f0e…-… "请总结一下失败的测试。"

每个请求都要带上 <DSH_HOME>/desktop-bridge.json 里的 bearer 令牌。该文件由插件在 挂载时写入、卸载时删除：

{
  "version": 1,
  "address": "127.0.0.1",
  "port": 63339,
  "token": "…64 位十六进制…",
  "pid": 30820,
  "startedAt": "2026-10-02T02:31:07.114Z"
}

端口和令牌每次挂载都会重新随机，所以重载之后要重新读文件，不要缓存。

方法	路径	请求体 / 查询	结果
GET	/v1/sessions	—	200 {items: […]}，宿主的会话列表（含实时投影）
POST	/v1/sessions	{cwd, title?}	201 返回新建会话；cwd/title 不合法为 400；被配置禁用或超出白名单为 403
GET	/v1/sessions/{id}/events	?limit=1..100（默认 30）	200 {sessionId, events: […]}，事件日志的尾部
POST	/v1/sessions/{id}/messages	{text}（1–4096 字节）	200 {accepted, requestId}；文本作为一条用户回合追加

curl 示例：

curl -s -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:$PORT/v1/sessions"
curl -s -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"cwd":"/home/me/projects/demo","title":"发版排查"}' \
  "http://127.0.0.1:$PORT/v1/sessions"

带浏览器 Origin 头的请求一律拒绝，且 Host 必须写明回环地址与端口——因此网页即使 通过 DNS 重绑定也够不着这个桥。

配置

插件会读取补丁行里可选的 config，每个键都可省略，省略时即为下面这种宽松默认值：

- id: desktop-bridge
  config:
    allowCreate: false        # 默认 true；false 直接拒绝 POST /v1/sessions
    auditLog: true            # 默认 true；每个请求一行 JSON
    cwdAllowlist:             # 默认 []，不限制
      - 'C:\work'

• allowCreate —— 设为 false 后，列表、读取、发消息照常可用，但不能再启动新的 agent。
• auditLog —— 每个请求向 <DSH_HOME>/desktop-bridge.log 追加一行 JSON：时间、 方法、路径、路由、状态码、耗时，以及目标目录或会话 id。不记录令牌，也不记录消息 正文。
• cwdAllowlist —— 非空时，新会话只能建在这些目录之内（含子目录）。

POST /v1/sessions 传入的路径必须是已存在的目录；桥接不会替你创建。

兼容性

已在 DSH 0.2.0-rc.2（desktop profile，Windows）上验证。插件只是五个 sessionController 方法之上的薄层——list、inspect、prompt、create、 rename——不依赖其他内部 API。若某个 DSH 版本改了方法名，相应路由会返回 500 DSH request failed，真实错误写进审计日志，应用其他部分不受影响。

注入不到服务时，插件会在启动日志里报 sessionController is unavailable，而不是挂载 一个半死不活的桥。

开发

node --test          # 23 个测试：路由、策略、审计、descriptor 生命周期

测试占用临时回环端口并使用桩 controller，不需要跑着 DSH。

许可证

MIT，见 LICENSE。