dsh-bridge

把本机的 DeepSeek Harness（dsh web）包装成一个 MCP stdio server，让 Codex、Claude Desktop、Cursor 这类 MCP 客户端可以直接创建会话、派发任务、读取结果。

桥接不改 dsh，也不往客户端里装插件：它只把 dsh 的本地 /api 封装成 11 个工具，并在本地维护一份"派发过什么"的账本。

MCP client ──stdio──▶ dsh-bridge ──HTTP /api (127.0.0.1)──▶ dsh web ──▶ 会话 / 工具 / 工作区

环境要求

• Node.js ≥ 18.14（用到 headers.getSetCookie()）

• 已安装 @deepseek-ai/dsh（npm i -g @deepseek-ai/dsh）

• 在 dsh 0.2.1-rc.2 / Windows 11 / Node 24 上验证

dsh 的 /api 不是稳定公开契约。升级 dsh 之后请按下面的升级检查重新验证一遍。

Related MCP server: dsh-orchestrator

安装

git clone https://github.com/controlledentropy/dsh-bridge.git
cd dsh-bridge
npm install
npm test

node launch.mjs resolve   # 检查 Node、dsh 入口与版本
node launch.mjs check     # 预检，不启动服务

配置 MCP 客户端

Codex（~/.codex/config.toml，路径换成本机绝对路径）：

[mcp_servers.dsh]
command = 'node'
args = ['C:\\path\\to\\dsh-bridge\\bridge.mjs']
startup_timeout_sec = 120
tool_timeout_sec = 180

[mcp_servers.dsh.env]
DSH_PORT = '3080'
DSH_BRIDGE_STATE = 'C:\\path\\to\\dsh-bridge\\.state'

其他客户端用同样的 command / args / env 三要素，JSON 里反斜杠写成 \\。

两点值得注意：

• 改过 bridge.mjs 或 MCP 配置后要重启客户端——stdio 子进程加载的是启动那一刻的代码。

• tool_timeout_sec 建议 ≥ 180：首次调用可能包含启动 dsh web（≤ 90 s）、等待模型目录加载（≤ 15 s）和内部等待（≤ 40 s）。

使用

dsh web 的生命周期由桥接自己管：端口空闲时它会冷启动一个实例，也可以提前用 node launch.mjs start（或 start-dsh-web.ps1）起好。一台机器跑一个实例就够了。

一轮典型调用：

dsh_models → dsh_launch{alias,cwd,task} → dsh_wait{alias} 循环 → dsh_result{alias}

alias 是调用方起的名字，匹配 ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$，对应会话 ID dsh-<alias>。cwd 必须是已存在的绝对路径，它就是该会话的写入边界。

工具

dsh_launch / dsh_send 只返回一个简短的回执（状态、是否已结束、错误、下一步提示），完整产出用 dsh_result 读。需要诊断信息时加 detail: true。

停止实例

node launch.mjs stop              # 停掉本状态目录启动的实例
node launch.mjs stop --pid 1234   # 停掉别处启动、你确认过归属的实例
node launch.mjs restart

也可以调用 MCP 工具 dsh_stop（dryRun: true 只报告不动手）。

stop 会杀掉整棵进程树，因为 dsh web 会派生子进程，只杀父进程的话子进程还会占着端口。成功的判据是端口真的空出来，不是"信号发出去了"——返回里的 stillListeningOnPort 就是证据。桥接不会去杀一个自己没有归属证据的进程，那种情况它只把端口占用者报给你。

生命周期命令

返回值

state 是唯一该据以分支的字段：

accepted: true 只表示受理，session/list.running 从 true 变 false 也不区分成功与失败。另外两条容易踩的：

• 客户端超时不会取消 dsh 的执行。超时后应该重读同一轮，而不是重发同一段工单——同别名有在途同文本轮次时，dsh_send 会直接拒绝，除非显式 force: true。

• dsh_wait 在发现本轮停在人工审批或待人回答的提问时会立即返回，而不是耗完整个等待窗口。看 pending[] 与 waitingOnHuman / asked[]。

配置

全部通过 MCP server 的环境变量传入。

模型策略在请求发出前判定，越权不会消耗额度。推理强度是否合法看 dsh_models 回显的模型声明。

状态目录与凭据

• dsh web 的启动 token 只出现在它的 stdout 里，是 bearer 凭据：同一个 token 可以多次换取有效 cookie，直到实例重启。捕获文件的可读性就是这个实例在本机上的权限边界。

• Windows 上 chmod 对 NTFS 无效，ACE 直接继承目录。doctor 会用 icacls 列出除本人、SYSTEM、Administrators 之外还能读的主体；要收紧就显式跑 lock-acl。

• sessions.json 逐字保存每轮下发的任务原文（可能含路径与需求细节），但不缓存助手输出——结果一律从 dsh 重新读取。按敏感文件对待，不要把 .state/ 放到共享目录或同步盘。

已知限制

• cwd 守卫只扫一种路径风格。 会话 cwd 是盘符/UNC 路径时只认 Windows 绝对路径，是 posix 路径时只认 /…。相对路径、file:// URL、以及 POSIX 上不带前导斜杠的写法都不在识别范围内。分级是启发式的，误判时用 allowOutsideCwd: true 放行。

• /api 删不掉会话。 方法表里没有 session/delete，workspace/archiveSession 之后 id 仍在列表里，只能由人在 UI 清理。

• 分栏在创建时确定，接管已有会话不能改组。

• 运行中会话的沙箱档位不可编程修改，提权是人的动作。

• ask_user_question 不能直接调用，它经 run_code 以 PTC 分发形式出现；桥接只能报告"停在人身上"，不能替人回答。

• workspace-write 不等于无人值守可用。 该档位下 pwsh、git 等操作仍会触发审批并停在那里，而 running 保持 true。要真正无人值守需要会话处于 danger-full-access。派单前用 dsh_status 看 unattended。

• 要求 git commit 的任务在 workspace-write 下不可行：worktree 的索引与对象在主仓 .git/worktrees/ 下，属会话工作区之外，每次提交都会弹审批。

开发

npm test                                  # 离线用例，不起服务、不联网、不耗额度
node tools/remote-surface.mjs --check     # 方法表漂移检查
node tests/live-check.mjs                 # 对运行中的实例做只读复验

测试是离线的：用 fixture 驱动判读逻辑，用 MCP 子进程方式跑拒绝路径。CI 只跑 Windows（Node 20 / 22），因为部分 fixture 与断言依赖 Windows 的路径与 PATHEXT 语义。

升级检查

升级 dsh 之后按顺序执行：

node launch.mjs check      # 版本与 profile
node launch.mjs doctor     # 端到端体检
npm test
node tools/remote-surface.mjs --check
node tests/live-check.mjs

最后确认 DSH_ALLOWED_MODELS 是否仍表达本意。

代码结构

许可

MIT，见 LICENSE。