DeepSeek DSH MCP

一个无运行时依赖的 stdio MCP 适配器：把有边界的开发任务交给本机已安装的 DeepSeek Harness（DSH） 执行，并把文件写入、命令退出码、缺失检查、阻塞项和证据整理成稳定的结构化交接结果。

• 当前版本：1.2.2

• 适配器自身是独立项目，不打包上游 DSH 源码或依赖。

• 发布仓库：lin2703/deepseek-dsh-mcp。

• 许可证：MIT（Copyright (c) 2026 lin2703）。上游 DSH 为 MIT；本适配器代码以仓库根目录的 LICENSE 为准。

• DSH 官方文档：https://deepseek-harness.github.io/deepseek-harness/。

支持条件与边界

Linux + bwrap 限制（重要）：命令执行器直接调用 /usr/bin/bwrap。如果该路径不存在、不可执行或 bwrap 初始化失败，执行会立即失败并停止，错误以 DSH_EXECUTOR_SANDBOX: / bwrap: 形式保留；适配器不会回退到无沙箱执行。当前范围没有实现跨平台沙箱。

离线测试只覆盖纯逻辑、临时文件、stdio 子进程和静态配置检查；不覆盖真实 DeepSeek API 调用、真实宿主沙箱集成、真实模型委派。这些集成需在安装好 DSH 和 bwrap 的机器上单独验证。

Related MCP server: dsh-cli-mcp

从零安装

git clone https://github.com/lin2703/deepseek-dsh-mcp.git
cd deepseek-dsh-mcp
node --version        # 应为 v22.16.0 或更高

本项目没有 npm 运行时依赖，也不需要构建步骤：

# 不需要 npm install；以下命令直接运行源码
node --check server.mjs
node --test

如果本机还没有 DSH，请按上游文档安装（示例，版本以实际为准）：

npm install -g @deepseek-ai/dsh@0.2.1-rc.2

安装后，先按 DSH 官方文档 完成账号/API 认证配置，再启动本适配器。认证属于上游 DSH 的运行前提；本适配器不提供登录 CLI，也不要求把密钥写入仓库或提交到配置文件中。

MCP 客户端只启动 server.mjs；DSH 是本适配器的外部运行前提，不是随仓库发布的依赖。

找到 DSH：解析顺序

DSH 的入口在真正发起委派时才解析，导入 server.mjs 时不会要求 DSH 已安装。因此 initialize、tools/list 和离线测试在没有 DSH 的机器上也能工作。解析顺序：

1. DSH_CLI_PATH：绝对路径覆盖，必须指向 DSH 的 bin 入口文件。设置错误会明确报错，不会静默回退。

2. 适配器目录的局部依赖：只从本适配器自身安装目录解析 node_modules/@deepseek-ai/dsh，读取其 package.json 的 bin 或 lib/bin.js。委派任务的 workspace 和进程当前目录不会被隐式搜索。

3. PATH 中的 dsh：只检查 PATH 中绝对路径条目，相对路径和空条目会被跳过；找到可执行文件后使用其真实路径（解析 npm 符号链接）。

4. 常见全局 node_modules 位置：由当前 Node 可执行文件位置和用户 home 推导。

例如，DSH 已全局安装但不在 PATH 中时：

export DSH_CLI_PATH="/absolute/path/to/node_modules/@deepseek-ai/dsh/lib/bin.js"

如果四步都失败，委派返回 launch_failed，不会尝试联网安装。

配置 MCP 客户端

适配器使用标准 stdio 传输：客户端启动 node /绝对路径/server.mjs，通过 stdin/stdout 交换 JSON-RPC。不要向 stdout 打印日志。

Codex

把 examples/codex.toml 中的占位路径替换为真实绝对路径，然后合并到 Codex 配置。最小形式：

[mcp_servers.deepseek_dsh]
command = "node"
args = ["/absolute/path/to/deepseek-dsh-mcp/server.mjs"]
env_vars = ["PATH", "HOME", "DSH_CLI_PATH", "DEEPSEEK_API_KEY", "DSH_MCP_SEALED_ROOTS", "DSH_MCP_RUNTIME_ROOTS"]
tool_timeout_sec = 960

说明：

• env_vars 把 DSH 需要的环境变量从启动 Codex 的 shell 传入 MCP 进程；不要把真实 token 写进仓库或提交配置文件。

• tool_timeout_sec 需要覆盖适配器允许的最长 900 秒，并留出进程退出宽限；示例为 960 秒。

• Codex 官方 MCP 配置文档：https://learn.chatgpt.com/docs/extend/mcp?surface=cli（旧地址：https://developers.openai.com/codex/mcp/）。

其他 MCP 客户端

配置等价的 stdio server 即可：命令 node，参数为 server.mjs 的绝对路径，并传入 DSH 所需环境变量。客户端必须支持工具调用和多行 JSON 结果。

工具参数

唯一对外工具是 deepseek_delegate。必填 task、context、acceptance；可选 execution：

省略 execution 时只返回文本答案，不执行工具；这是兼容模式。

模型可见的 bash schema（v1.2.2）

授权 commands 存在时，适配器会重写 bash 工具 schema：

• command 是枚举，值恰好等于本次授权的命令字符串。枚举外命令在执行前被拒绝，结果明确标注未执行；模型不得自行改写、拼接或扩大命令。

• workdir 枚举为 workspace 或 "."；工作目录固定为 workspace，其他目录未授权。

• timeoutMs 是整数，必须 > 0 且 <= 120000；零、负数、非整数和更大值都在执行前被拒绝。

• additionalProperties: false：后台任务、提权、额外参数不可用。

• 依赖/环境探测必须放进已授权的实现或检查命令，不能追加独立探测命令。

这些拒绝是执行前的分类。真实执行输出里出现“拒绝”字样，不代表命令未执行；只要存在执行事实（退出码或命令证据），就按真实结果判断。

预算与交接语义

每次委派都会返回稳定的 JSON 交接，包含：

• status：completed / partial / blocked / failed。

• stop_reason：完成、预算耗尽、截止时间、取消、输出上限、JSONL 损坏、缺失最终回复、未完成工具调用、未解决失败、未配对结果、重复证据、契约冲突、缺失检查、未验证命令等。

• modified_files.observed：仅记录成功的 write/edit 工具调用；attempted 记录未成功的写入。不生成 diff，命令副作用需人工复核。

• commands[]：每条授权命令的 status、exit_code、attempts 和输出摘录。状态包括 not_run、unfinished、not_executed、succeeded、succeeded_unverified、failed、unknown。

• missing_authorized_checks、unresolved_failures、warnings、duplicate_pairs、unfinished_tool_calls、unverified_commands、blockers、next_steps。

• budget 与 deadline：请求预算、保留区、当前阶段和剩余时间。

• verification.acceptance_ready：只有 completed 才为 true。

• evidence：会话、边界、最终回复、工具调用/结果转录和原始事件。

判定原则：

1. 执行事实优先于模型文本：真实零退出码可判成功，即使输出看起来像拒绝；非零退出码、超时、信号、显式结构化错误始终是失败。

2. 矛盾证据不通过：顶层退出码与规范命令证据冲突、同一 call id 出现两组完整调用/结果、结果无法配对，都是失败/阻塞证据。

3. 拒绝不等于执行：只有无任何执行事实的执行前拒绝才能归为“未执行”；真实执行输出中的拒绝词不能冒充未执行。

4. 模型声称完成不算完成：没有最终回复、检查缺失、失败未解决或证据矛盾时，不会报告 completed。

5. 不自动重试：预算/截止时间/取消/失败都会停止；需先检查证据并做针对性修复。

此外，同一 workspace 同时只允许一个委派；通过私有 /tmp 锁目录协调。不要删除不属于自己的锁；强制终止时锁可能保留，需先确认原进程已停止。

保护、封存与运行时根

默认保护由真实用户 home 推导，不写死任何用户路径：

• 私人目录（不可读）：$HOME/.codex、$HOME/.dsh、$HOME/.ssh、$HOME/.aws。

• 受保护写路径：上述私人目录，以及路径中任意位置的 .git、.codex、.agents、.ssh、.aws；拒绝软链接别名扩大权限。

• 硬链接文件不可通过写路径修改。

• 读路径必须落在 workspace 或显式 read_roots 内；.. 和符号链接按真实路径判定。

DSH_MCP_SEALED_ROOTS

额外封存根，JSON 数组，只增加写保护，不会扩大任何权限：

export DSH_MCP_SEALED_ROOTS='["/absolute/path/to/private-artifacts","/absolute/path/to/sealed-data"]'

每个值必须是已存在的绝对目录；无效 JSON、非数组、相对路径、不存在路径、宽泛根（/、/home、用户 home、/tmp、/usr、/etc、/var、/opt）以及与凭据目录重叠的路径都会被拒绝。

DSH_MCP_RUNTIME_ROOTS

额外只读运行时挂载，JSON 数组。典型用途是让沙箱内的命令访问某个工具链/环境目录（例如 Python 环境）：

export DSH_MCP_RUNTIME_ROOTS='["/absolute/path/to/toolchain/env"]'

这些目录只以 --ro-bind 进入 bwrap，不会成为模型可写路径，也不会自动加入 read_roots。校验规则与 DSH_MCP_SEALED_ROOTS 相同。默认系统只读根为 /usr、/bin、/lib、/lib64、/etc（存在的才挂载）。

两项配置在启动时解析；无效配置直接报错退出，不会静默忽略。它们只增加封存/只读挂载，不改变 write_paths 的 workspace 内约束。

验证命令

在仓库根目录执行：

node --check server.mjs
node --check guard.mjs
node --check runtime.mjs
node --test

node --test 会运行全部 *.test.mjs，包括原有契约/恢复/完整性测试和新增测试：

• 入口解析：DSH_CLI_PATH 绝对覆盖、适配器目录局部依赖、绝对 PATH 真实入口、启动脚本，以及委派 workspace 伪造包/相对 PATH 条目被拒绝；

• 保护/配置：home 推导私人目录、DSH_MCP_SEALED_ROOTS / DSH_MCP_RUNTIME_ROOTS 的校验与“只读、不扩写”行为；

• v1.2.2 元数据：package.json、MCP initialize 的 serverInfo.version、bash 枚举 schema。

离线 MCP 握手（不需要 DSH）：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' | node server.mjs

预期输出包含 "serverInfo":{"name":"deepseek-dsh","version":"1.2.2"}；stdin 关闭后进程正常退出。tools/list 应返回唯一的 deepseek_delegate。

v1.2.2 更新内容

以下变更依据 v1.2.1 → v1.2.2 的 server.mjs / guard.mjs 差异整理。

1. bash 工具 schema 变为枚举授权

• 模型可见的 bash schema 把 command 设为本次 commands 的精确枚举；workdir 枚举为 workspace 或 "."；timeoutMs 为 0 < timeoutMs <= 120000 的整数；禁止额外参数。

• 工具描述明确：枚举外命令在执行前拒绝且报告为未执行；依赖/环境探测必须放进已授权命令，不能作为额外命令发送。

• 命令级描述补充“一次一条、字面匹配、不授权替代命令或扩大范围”。

2. 拒绝信息与未执行标记更明确

• 非契约命令、错误 workdir、非法 timeoutMs、提权/后台请求都明确说明“命令未执行”。

• 未执行识别模式加入 timeoutMs；已知执行事实存在时不再把输出误判为未执行。

3. 执行证据优先，冲突即失败

• 直接退出码与规范命令证据分别读取；两者冲突标记为失败（exit_code_conflict），不会让递归扫描先遇到的 0 掩盖非零。

• 真实执行事实优先于可读文本：真实 0 退出即使文本像拒绝也算执行成功；非零退出、超时、中止、信号或显式结构化错误始终失败。

• denied 仅在没有执行事实时成立；命令证据即使退出码未知也证明执行发生过。

4. 重复/孤立证据不再被接受

• 严格配对：call id、工具名兼容且结果在调用之后；缺失结果工具名可容忍，名称不匹配不算证据。

• 同一 call id 出现两组完整调用/结果 → duplicate_evidence；结果无法配对 → unpaired_results；两者都会出现在 blockers 与 verification 计数中，不能据此报告完成。

• 只有无执行事实的“命令已在当前编辑上运行过”拒绝可复用先前结果；真实的重跑仍以最新退出码判定。

5. 版本元数据

• MCP initialize 的 serverInfo.version 从 1.2.1 更新为 1.2.2。

适配器发布整理

• DSH 入口改为延迟解析：DSH_CLI_PATH / 适配器目录局部依赖 / 绝对 PATH dsh / 常见全局位置；导入与 initialize/tools/list 不再依赖本机安装，也不会从委派 workspace 或进程当前目录隐式加载 DSH。

• guard 的私人目录改由真实用户 home 推导，移除个人机器路径；新增 DSH_MCP_SEALED_ROOTS 与 DSH_MCP_RUNTIME_ROOTS 两项经校验的 JSON 配置。

• 补齐 README.md、package.json、.gitignore、examples/codex.toml、runtime.mjs 与测试；path-scopes.test.mjs 改为 home 推导。

• 保留 v1.2.2 的证据优先、拒绝分类、命令约束、预算/锁和失败即停语义。

目录结构

server.mjs          MCP stdio server、工具 schema、交接构建
guard.mjs           权限围栏、命令沙箱参数、预算/截止时间
runtime.mjs         DSH CLI 延迟解析与启动脚本
*.test.mjs          离线测试
examples/codex.toml Codex MCP 配置示例（含占位路径）
package.json        版本 1.2.2、MIT 许可证、仓库地址、start/test 脚本、type=module
.gitignore          依赖、凭据、本地配置、会话/日志、备份和测试产物