Codex 任务派发桥 GEB-lab/dsh-codex-mcp

dsh-codex-mcp

一个 DSH 宿主插件，在 DeepSeek Harness 进程内运行只监听回环地址的 Streamable HTTP MCP 服务器，让 Codex 能通过 MCP 把编码任务派发给 DSH —— 不需要 shell 包装，也不需要每次调用写脚本。

中文说明 · MIT · 零运行时依赖

Codex CLI
└─ MCP (Streamable HTTP + Bearer token) http://127.0.0.1:39391/mcp
└─ DSH host plugin dsh-codex-mcp (lives inside the DSH process)
└─ node <dsh install>/lib/bin.js --profile headless --json
└─ DSH reads/writes code, runs commands, streams NDJSON events

写代码的智能体仍然是 DSH。Codex 只负责派发任务、读回结构化结果，然后自己再跑一遍验收命令。

dsh-codex-mcp: Codex dispatches to a DSH headless agent over a loopback MCP endpoint

Install, check and dispatch from the terminal

为什么做成插件，而不是 DSH 工具

普通的 DSH 智能体工具（ctx.tools）只有 DSH 自己的模型能看到，Codex 看不到。要让另一个智能体也能调用，这项能力就必须离开进程。因此这个插件会：

- 在 DSH 宿主加载它时，于 127.0.0.1 上启动一个 HTTP MCP 端点；插件卸载时关闭它（ctx.effect 返回一个清理函数）；
- 直接实现 MCP Streamable HTTP 传输和旧版 JSON-RPC —— 这个包刻意做到零依赖，所以配置档里不需要解析 MCP SDK 或 @deepseek-ai/ 包；
- 复用承载它的 DSH 安装：在 resources/app 旁边找 @deepseek-ai/dsh 的 lib/bin.js，或者按 DSH_APP_ROOT / dshCli 指向的位置找。

功能

- 三个 MCP 工具 —— dsh_env、dsh_run、dsh_resume。新建会话和后续追问都会把会话 id 带回给调用方。
- 结构化结果 —— 最终答案、session、cwd、exit、turn_end、每轮 token 用量、步数、耗时；失败时还会返回 stderr 尾部内容和分类后的原因。
- 如实报错 —— 出现以下情况时，调用会返回 MCP 错误：超时、子进程以非零码退出、turn_end 不是 completed、没有收到 final 事件、最终答案为空。插件从不轻信 DSH 自己说的「我做完了」。
- 超时杀进程树（Windows 上用 taskkill /T /F，其他平台杀进程组），不留孤儿智能体。
- 并发上限（maxConcurrentRuns，默认 4）—— 超出的调用快速失败，而不是悄悄排队。
- 只监听回环地址 + Bearer token —— 首次启动时生成 token（32 个随机字节，权限 0600），用 sha256 + timingSafeEqual 比对，默认路径为 $DSH_HOME/codex-mcp.token。
- 有界 NDJSON 解析 —— 格式错误的行只计数，不致命；事件数、行长和 stderr 尾部都有上限。
- 双语工具描述（locale/en.json、locale/zh.json），调用方模型可以用自己的语言读说明。

环境要求

| DSH | 桌面版或命令行安装，其 @deepseek-ai/dsh 支持 --profile headless --json |
| Node | ^22.19.0 || >=24.0.0（使用宿主机自带的 Node） |
| DSH 凭据 | 已存入 ~/.dsh 配置档的模型 API key（GUI 的 Models 页面或凭据服务） |
| DSH 配置档 | headless 配置档；桌面版配置档会拒绝 --json，且由桌面应用管理 |

安装

from GitHub (recommended)
dsh plugin --profile desktop add github:GEB-lab/dsh-codex-mcp

from a release tarball
dsh plugin --profile desktop add https://github.com/GEB-lab/dsh-codex-mcp/releases/latest/download/dsh-codex-mcp.tgz

local checkout, for development (changes apply after a host restart)
dsh plugin --profile desktop add link:/absolute/path/to/dsh-codex-mcp

dsh plugin 是 DSH 的插件命令：它把命令转发给配置档的包管理器，然后在 dsh.profile.bundles 中选中新 bundle。如果开了 HMR，插件会立即加载；否则重启 DSH。

检查插件是否已启动：

curl -i http://127.0.0.1:39391/mcp -X POST \
-H "authorization: Bearer $(cat ~/.dsh/codex-mcp.token)" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}'

或者不用 curl：

node scripts/smoke.mjs # protocol + dsh_env only, spends no tokens
node scripts/smoke.mjs --task "reply SMOKE_OK" --cwd /path/to/project

smoke 脚本会打印出适配你机器的 config.toml 片段，可直接粘贴。

Codex 配置

~/.codex/config.toml：

[mcp_servers.dsh_codex]
url = "http://127.0.0.1:39391/mcp"
http_headers = { Authorization = "Bearer <contents of $DSH_HOME/codex-mcp.token>" }
startup_timeout_sec = 30
tool_timeout_sec = 3600
enabled = true

之后 codex mcp list 应显示 dsh_codex … enabled Bearer token。

接着在 Codex 里说：

用 dsh_run 让 DSH 在 C:\work\proj 下给 src/sum.mjs 加上类型化输入支持，再补三个 node:test 用例；只许改 src/ 和 test/。它返回后，你自己跑 node --test test\.test.mjs 并汇报结果。

工具参考

dsh_env()

无副作用，不消耗 token。返回 JSON：plugin{name,version,pid,startedAt}、mcp{url,token,tokenFile}、dsh{cli,version,profile,dshHome,permissionMode,node,nodeVersion}、defaults{cwd,timeoutSec}、runtime{activeRuns,maxConcurrentRuns}，以及一段可直接粘贴的 codexConfig 片段。

dsh_run(task, cwd?, timeout_sec?, include_events?)

启动一个新的无头会话。task 通过 stdin 传入（没有引号转义问题，也不受 argv 长度限制）。成功时文本结果如下：

[DSH done] turn 1 · steps 1 · 2.9s session: session-1a2b3c4d-... cwd: /work/proj exit: 0 · turn_end: completed usage: in 469 / out 8 / cacheRead 5760 / total 6237

--- final answer ---
DSH_PLUGIN_OK

--- continue this session ---
dsh_resume({ "session_id": "session-1a2b3c4d-...", "task": "<next task>" })
dsh_resume(session_id, task, cwd?, timeout_sec?)
继续已有会话。必须在与原会话相同的 cwd 下运行，否则 DSH 会在启动前拒绝（插件也会说明原因）。

失败返回会带上分类（timed out、exit code N、turn_end was X、no final answer、empty final answer）、stderr 尾部、事件计数，以及针对常见原因（凭据缺失、配置档错误、会话未知、cwd 不匹配、未授权）的下一步提示。

配置

所有键都放在 cordis.patch.yml（bundle 默认）或 ~/.dsh/profiles/<profile>/cordis.patch.yml（你的覆盖）中本条的 config 下： yaml
- id: dsh-codex-mcp
name: dsh-codex-mcp
config:
port: 39400
defaultCwd: 'D:\code'

| 键 | 默认值 | 含义 |
| host | 127.0.0.1 | 绑定地址；非回环地址会被拒绝，除非设置 allowNonLoopback: true |
| port | 39391 | 0 表示自动选空闲端口（dsh_env 会报告实际端口） |
| path | /mcp | 端点路径 |
| tokenFile | $DSH_HOME/codex-mcp.token | Bearer token；缺失时自动创建 |
| regenerateToken | false | 下次启动时轮换 token |
| dshHome | $DSH_HOME 或 ~/.dsh | 子进程的 DSH_HOME |
| profile | headless | 子进程 DSH 配置档 |
| permissionMode | danger-full-access | 子进程的 DSH_PERMISSION_MODE |
| defaultCwd | 宿主 cwd | 调用未传 cwd 时使用 |
| defaultTimeoutSec | 3600 | 单次调用超时 |
| maxConcurrentRuns | 4 | 并行 headless 任务数 |
| dshCli | 自动探测 | 显式指定 …/@deepseek-ai/dsh/lib/bin.js 路径 |
| nodePath | 自动探测 | 显式指定 Node 可执行文件 |
| locale | zh | MCP 工具文案语言，en 或 zh |
| includeEvents | false | 在结果后追加原始 NDJSON 事件尾部 |

~/、相对路径和 $DSH_HOME 都会展开；未知键会被忽略。

安全模型

- 默认绑定 127.0.0.1。即使放宽绑定，对端不是回环地址的请求仍会被拒绝，除非显式设置 allowNonLoopback: true。
- 每个请求都要带 Bearer token；否则端点返回 401，并附 WWW-Authenticate: Bearer realm="dsh-codex-mcp"。token 比较基于 SHA-256 摘要，采用常量时间。
- 请求体上限 4 MiB；支持 JSON-RPC 批量请求；未知方法返回 -32601。
- 子进程以 DSH_PERMISSION_MODE=danger-full-access 运行，因为 headless DSH 无人值守——它确实能以你的用户权限改文件、跑命令。务必传入你要改动项目内的 cwd，并让 token 远离仓库和截图。
- token 文件以 0600 权限创建；用 regenerateToken: true 轮换（然后更新 Codex 的配置）。

故障排查

| 现象 | 原因 / 修复 |
| codex mcp list 能看到服务器，但调用失败 | 没有进程在监听，或 token 不匹配。运行 node scripts/smoke.mjs；返回 401 说明要重新复制 token |
| EADDRINUSE | 端口被另一个进程占用——改 port |
| MISSING_CREDENTIAL: … no API key for provider route | headless 配置档看不到你的密钥；在 ~/.dsh/profiles/headless/cordis.patch.yml 里启用 credentials/authorization 服务商 |
| unknown option '--json' | 子进程跑的是非 headless 配置档；保持 profile: headless |
| session … does not exist / cwd mismatch | 续跑必须用原来的 cwd；否则新开一个 dsh_run |
| 插件改动不生效 | 宿主已经加载了模块——重启 DSH（改配置也一样） |
| 找不到 agent | 显式设置 dshCli 为 <dsh install>/node_modules/@deepseek-ai/dsh/lib/bin.js |

Development
sh
npm test # node --test test/*.test.mjs — 19 cases, no network, uses a fake dsh CLI
node scripts/smoke.mjs --url http://127.0.0.1:39391/mcp --task "reply SMOKE_OK"
node index.js # standalone server, no DSH host needed

测试套件覆盖这些场景：鉴权（401 / token 错误）、会话头、批量请求、通知、未知方法与路径、SSE 保活、DELETE、tools/list、dsh_env 内容、一次成功运行、格式错误的事件行、续跑参数传递、非零退出并带诊断信息、空答案、turn_end 不是 completed、超时杀进程。

Limitations

- 每个宿主只能有一个插件实例；端点按设计只监听本机。
- 改配置或改代码都要重启宿主才生效。
- 不给调用方推流式进度——dsh_run 调用要等任务结束才返回（受 timeout_sec 限制）。
- 子进程能做什么由 DSH 的沙箱配置档决定；本插件不额外加隔离。

License

MIT

中文说明

一句话：在 DSH 宿主进程里起一个 Streamable HTTP MCP 服务，只监听回环地址，让 Codex 通过 MCP 把开发任务派给 DSH headless agent 执行，不再需要 PowerShell 包装器。

为什么做成插件：DSH 的普通 agent 工具只对 DSH 自己的模型可见，Codex 看不到。要让另一个 agent 调用，能力必须暴露到进程外——所以插件在宿主里起 HTTP MCP 端点，卸载时由 ctx.effect 注册的清理逻辑关掉。

安装： sh
dsh plugin --profile desktop add github:GEB-lab/dsh-codex-mcp

Codex 侧（~/.codex/config.toml）： toml [mcp_servers.dsh_codex]
url = "http://127.0.0.1:39391/mcp"
http_headers = { Authorization = "Bearer <token 文件内容>" }
tool_timeout_sec = 3600
enabled = true

token 默认在 ~/.dsh/codex-mcp.token（首次启动自动生成，权限 0600）。

三个工具：
- dsh_env() — 查 dsh 版本、CLI 路径、profile、权限模式、token 位置，并给出可直接粘贴的 Codex 配置片段；
- dsh_run(task, cwd?, timeout_sec?) — 开新会话，任务走 stdin，回传最终答案 + session + cwd + 退出码 + turn_end + token 用量；
- dsh_resume(session_id, task, cwd?, timeout_sec?) — 同一 cwd 续跑上一个会话。

失败判据（插件内建，调用方不必自己判断）：超时 / 非零退出 / turn_end 不是 completed / 没有 final 事件 / 最终答案为空 —— 任一命中都返回 MCP 错误，并附 stderr 尾部与下一步提示。超时会 taskkill /T /F 杀掉整棵进程树。

安全：只绑 127.0.0.1，Bearer token（sha256 + 定时安全比较），请求体上限 4 MiB；子进程以 danger-full-access 运行（headless 无人值守必须如此），所以派任务时把 cwd 限定在项目目录内，别把 token 提交进仓库。

自测：npm test（19 个用例，用假 dsh CLI，不联网）、node scripts/smoke.mjs（像 Codex 一样连端点跑一轮）。
局限：单实例；改配置或改代码后需重启宿主才生效；不给调用方推送流式进度（调用在任务结束时返回）。