Codex 派单桥 ksoulness/dsh-codex-kit

DSH Codex Kit

Codex 负责跟你对话，本机的 DeepSeek Harness（DSH）负责真正干活：一次派发、等到终态、验收结果、按精确 ID 归档——源码不离开工作区。

一个本机 MCP 工具包，把「Codex 想清楚」和「DSH 动手做」接成一条闭环：Codex 用原生工具把有明确范围的任务派给 DSH，持续监控到终态，读完 assistantText 自己复核证据，最后只归档这次新建的那个会话。

不复制粘贴代码，不搬运 diff，不靠终端里手敲 RPC。

解决什么问题

| 没有它的时候 | 有了它 |
| 想让别的模型干活，只能把整段源码、diff、仓库压缩包粘进聊天框：上下文爆炸、内容外流、改完还对不上 | 只传工作区 + 路径 + 范围 + 授权 + 验收，由 DSH 在本机自己读；源码不出工作区 |
| 派出去的任务没法盯：跑没跑、跑完没有、卡在哪，全靠猜 | wait_run 拉到终态，state/stopReason/assistantText 都是结构化字段，超时不算终态 |
| 「它说做完了」= 验收？ | 工具返回的是证据：实际改动路径、测试结果、限制说明；调用方自己复核文件差异才算完 |
| 会话台账越堆越乱：分不清哪条是这次任务、哪条能动、哪条是用户的 | 每个父任务一条 fresh 会话，记录 sessionId/sessionReused:false，终态消费后按完整 ID 归档，archived:true 才算成功 |
| 路径/权限靠口头约定 | reviewTargets、contextReadScope、excludedPaths、writeScope 显式声明；只读任务权限固定 read-only，实施才用 workspace-write |

最后效果

一次「只读核对 + 精确归档」在 Codex 里长这样（工具名、字段名都是真实接口；真机端到端验收见下方「已验证 / 未验证」）：

你 ❯ 调用 DSH 只读核对 docs/design.md 第 6 节，给出精确行证据，不改文件

Codex ❯ list_workspaces → 选中已注册工作区 list_capabilities → provider/model/effort/权限的真实取值
start_review { → promptAdmission: accepted
workspace, reviewTargets:["docs/design.md"], contextReadScope:[...],
sessionMode:"fresh", openBrowser:false, provider, model,
authorizationBasis:"explicit-user-request", idempotencyKey }
→ runId, sessionId, sessionReused:false, webUrl
wait_run { runId } → 未终态就继续等；hostMustCallWaitRunAgain:true
wait_run { runId } → state:"succeeded", stopReason:"end_turn"
（读 assistantText → 自己打开文件核对行号与结论）

archive_terminal_session { → { archived: true }
sessionId: "session-<完整 UUID>" }

你拿到的不是「已完成」四个字，而是：结论 + 文件行证据 + 实际改动 + 验证结果 + archived: true。任何一步没坐实（比如 Host 拒绝归档），它会如实留 archive_pending，不会编一个成功。

提示词怎么写

关键是说清范围与授权，而不是把内容塞给它。三条可直接复制的模板：

1. 只读核对 / 评审 / 调研（不改文件，走 start_review）

调用 DSH 只读核对 <文件或目录> 的 <章节/问题>：给出精确文件与行证据、影响面、最小修复建议和置信度；无法验证的标为未验证。不要修改任何文件。

2. 明确授权的实施（改代码，走 start_run + workspace-write）

调用 DSH 修复 <文件> 中已确认的 <问题>。只允许修改 <文件A> 与 <测试文件B>，运行相关测试并回报结果；不要提交、不要 push、不要碰其他文件。

3. 长任务 / 多轮（同一会话续接，不新开）

调用 DSH 继续 <上次的 runId 或会话>：把 <新增要求> 补进去，仍然只改 <范围>，完成后给出改动路径与测试结果。

反例（会破坏这套设计）：

- ❌ 把源码 / diff / zip 贴进任务内容 —— 应该只给路径，让 DSH 自己读。
- ❌ 「随便看看 / 你懂的」—— 没有范围就没有可验收的证据。
- ❌ 派发后立刻宣布完成 —— 必须 wait_run 到终态并消费 assistantText。
- ❌ 用临时 Node / PowerShell 脚本自己打 JSON-RPC —— 原生工具缺失就修安装，不要绕过。
想让 Codex 默认把实际任务都派出去（轻问答仍自己答），把可选路由规则合并到 Codex 侧全局指令即可。

安装

前置：本机已有可用的 DSH（bundle peer 为 0.2.0-rc.2 或 0.2.1-alpha.2）、Node.js ≥ 22.19、pnpm（装 DSH bundle 用）。可选：Python 3（打包与路径清单脚本）。

A. 丢给 AI（推荐）

把下面整段发给 Codex / Claude Code / 任意能执行命令的 Agent，它会自己装完并验收：

帮我在本机安装 dsh-codex-kit，并做一次只读验收。

仓库：https://github.com/ksoulness/dsh-codex-kit

步骤：
1. 先读 README.md、docs/setup.md、docs/publishing.md，确认本机 DSH 版本与 DSH_HOME 绝对路径。
2. git clone 到本机一个固定目录；在该目录执行 npm ci --ignore-scripts、npm test、
npm run check、npm run verify:relay。任何一步失败就停下报告，不要跳过。
3. 先备份目标 profile 的 package.json 与 pnpm-lock.yaml，再执行 dsh plugin --profile <profile> add ./vendor/harness-relay；用 dsh --profile <profile> --dump-config 确认出现 harness-relay-mcp 层。
4. 用 codex mcp add 接入两个 MCP（env 必须带 DSH_HOME 绝对路径），或用 npm run configure 生成配置后合并；然后用 codex mcp list 确认两个 server 都是 enabled。
5. 新开一个 Codex 任务，调用原生的 doctor、list_workspaces、list_capabilities 各一次，把真实返回值贴给我。

不要做的事：不要 push、不要改远端、不要提交代码、不要归档任何会话、不要读取或打印任何 token / cookie / 密钥、不要用危险权限覆盖我的 profile。
每一步的实际输出都要贴出来；不确定的地方问我，不要猜。

B. 手动三步

1) 拿到源码
git clone https://github.com/ksoulness/dsh-codex-kit && cd dsh-codex-kit
npm ci --ignore-scripts && npm test # 9/9

2) 把 Relay 装进 DSH 的目标 profile（已有兼容 Relay 可跳过）
dsh plugin --profile web add ./vendor/harness-relay
dsh --profile web --dump-config | grep -n harness-relay-mcp

3) 接入 Codex 的两个 MCP（把 <...> 换成你的真实路径）
codex mcp add harness-relay-mcp --env DSH_HOME=<本机 DSH_HOME 绝对路径> \
-- node <本仓库绝对路径>/scripts/relay-proxy.mjs
codex mcp add dsh-session-archive --env DSH_HOME=<本机 DSH_HOME 绝对路径> \
-- node <本仓库绝对路径>/scripts/session-archive-mcp.mjs codex mcp list

npm run configure -- --home <DSH_HOME> --profile web 可以生成同样内容的 .local/mcp.json 与 .local/codex-mcp.toml（含绝对路径，供手工合并），不修改你的任何现有配置。

C. 只要插件（一条命令）

codex plugin marketplace add ksoulness/dsh-codex-kit
codex plugin add dsh-codex-kit@dsh-codex-kit

插件路线会一并带上两个技能，但不注入 DSH_HOME，需要你在客户端环境里设置，或改用 A/B。细节与三条路线的差异见安装与故障定位。

换一台电脑？ 同一份仓库多机并用时，每台机器各自安装、各自生成配置，descriptor/凭据/.local/ 一律不跨机复制：见在另一台电脑安装。

工具清单

Relay 暴露 25 个原生 MCP 工具（scripts/relay-proxy.mjs 转发到 DSH 内嵌 Relay），归档 MCP 只暴露 1 个：

| 工具 | 作用 |
| doctor / setup_doctor / setup_plan | 连接与安装自检 |
| list_workspaces / list_workspace_sessions | 找到已注册工作区与历史会话 |
| list_capabilities | 真实可用的 provider / model / effort / 权限 |
| start_review | 只读派发（权限固定 read-only） |
| start_run | 实施派发（permissionPreset: workspace-write） |
| wait_run / get_run / get_run_summary / status_run / list_runs | 监控到终态 |
| steer_run / reply_run / cancel_run | 运行中纠偏、终态后补充、取消 |
| read_notifications / open_run | 事件与页面链接 |
| get_operation / reconcile_operation / reconcile_permissions | 不确定是否送达时的核对 |
| start_service / open_service / list_services / stop_service | Host 服务管理 |
| archive_terminal_session（归档 MCP） | 按完整 sessionId 归档，返回结构化结果 |

它怎么跑起来

┌────────────┐ stdio MCP ┌──────────────────────┐ loopback HTTP ┌───────────────┐
│ Codex │ ─────────────▶ │ relay-proxy.mjs │ ────────────────▶ │ DSH 内嵌 Relay │
│ (客户端) │ ◀───────────── │ (25 个原生工具) │ ◀──────────────── │ (vendor bundle)│
└────────────┘ └──────────────────────┘ └───────┬───────┘
│ │ 真实会话 │ stdio MCP ┌──────────────────────┐ descriptor + grant ▼ └────────────────────▶│ session-archive-mcp │ ────────────────▶ DSH Web /archiveSession └──────────────────────┘ （拒绝活动会话）

- 端口从本机 DSH_HOME/plugins/dsh-relay/<profile>/relay-endpoint.json 读取，没有硬编码端口，也不跟随重定向。
- 归档只接受一个完整 session-<UUID>；不扫目录、不按标题/天数批量处理。
- 两个 MCP 都是 stdio，不需要开公网、不需要云端账号、不发任何外部消息。

安全与边界

- 路径声明不等于沙箱：reviewTargets 等字段是给模型的指令声明；模型可能把它读到范围内的内容发给所选服务商。loopback 只描述控制链路。
- 归档不绕过拒绝：会话仍活跃或 Host 拒绝时保留 archive_pending，不通过终端、数据库直写或强停绕过。
- 凭据只在内存：归档适配器在本机读取 browser-session grant 派生短期 Cookie，不落盘、不打包、不传给模型。
- 不自动改你的环境：配置生成器只写输出目录；安装器不覆盖已有配置档，也不需要凭据值写进配置。
- 本包不是 DeepSeek / OpenAI 官方产品，模型读取内容由所选服务商按其条款处理。

已验证 / 未验证

在制作机（Windows、Node v24.19.0、pnpm 10.34.3、DSH 0.2.1-alpha.2、Codex CLI 0.147.0）用隔离 DSH_HOME / CODEX_HOME 实测：

- ✅ dsh plugin --profile <name> add ./vendor/harness-relay → link: 装入，dsh.profile.bundles 自动登记，--dump-config 出现 relay 层；
- ✅ 真实 descriptor 下 relay-proxy.mjs 列出 25 个原生工具；session-archive-mcp.mjs 只暴露 archive_terminal_session；
- ✅ codex mcp add 写出的配置与包内生成器一致；codex plugin marketplace add + plugin add 可装可卸；
- ✅ 隔离 mock 覆盖 RPC、认证签名、拒绝响应、MCP stdio、路径与配置生成；npm test 9/9；Relay 重建与源码一致。

尚未验证（请在自己的机器上验收）：DSH 重启后的 Host 重连、一次真实只读委派及其精确归档、Codex 桌面端加载、其他 DSH / Codex 版本。

目录结构

scripts/relay-proxy.mjs Codex → DSH 的 stdio MCP 代理（25 工具） scripts/session-archive-mcp.mjs 精确会话归档 MCP（1 工具） scripts/configure.mjs 按本机路径生成 MCP / Codex 配置 vendor/harness-relay/ Relay 源码与构建产物（上游 MIT，本地适配 0.2.17-local.3） skills/delegate-to-deepseek-harness/ 派发、监控、验收流程 skills/dsh-session-hygiene/ 每任务一新会话、终态后精确归档 .agents/plugins/marketplace.json Codex 插件市场入口 tests/ docs/ licenses/ 隔离测试、文档、第三方许可

文档

- 安装与故障定位 —— 三条接入路线的实测命令、故障表
- 在另一台电脑安装 —— 多机并用、不能复制的东西、跨平台差异
- 上传到 GitHub —— 版本发布、Release 附件、回退
- 可选 Codex 默认路由
- 来源与本地改动
- 第三方许可
- DSH 接手提示与验收清单

来源与许可

本仓库新增代码与文档为 MIT。vendor/harness-relay 来自 tonytanglab/deepseek-harness-relay-mcp v0.2.17 的本地适配（MIT，许可见 vendor/harness-relay/LICENSE）；构建内嵌依赖的许可列在 licenses/ 与本文件同级的 THIRD_PARTY_NOTICES.md。DSH、Codex、模型服务不在本包内，各按其自身许可与条款。