DSH Codex Bridge

这是一个同时安装在两端的桥接：DSH Cordis 插件提供会话、Agent Tool 和本地服务；Codex MCP 服务器提供规划与独立复核工具。个人同机使用；模型和推理设置由用户在两端管理。

当前能力

• 预览计划 → 一次批准目标、文件范围、验收及可选远端交付 → DSH 执行 → Codex 独立复核。

• 每个子任务独立 worktree；默认同一计划最多 2 个并行执行。依赖任务等待前置复核通过。多任务计划自动增加组合后的集成验证。

• 没有 Git 就初始化；首次提交需要确认文件清单和内容指纹。原目录未提交修改保持原样，worktree 基于已提交 HEAD。

• 稳定任务 ID 和 DSH requestId 去重；持久保存派发意图，未知执行状态先查证，禁止盲目重发。

• 支持插话、整项计划或单子任务停止；确认 DSH 空闲后才标记停止。

• 首次实施后整个计划最多 3 次自动修订；连续两次同类阻塞无进展即停。不会通过换任务 ID 重置限制。

• GitHub / GitLab 可选 issue、任务分支推送、草稿 PR/MR；不合并，不自动创建远端仓库。

• DSH 会话可调用 request_codex_task 发送新任务或问题，也可调用 request_codex_review 把完成摘要与实际自检送入持久收件箱；Codex 通过 dsh_review_inbox 查看，DSH 可用 check_codex_request 查询一般请求、check_codex_review 查询验收回复。一般请求的受理不等于代码验收。

• DSH 审批仍遵守其原有策略；桥接状态会显示待审批。到 DSH 回答后继续，或在 Codex 停止任务。插件不会自动批准完整访问权限。

实现与验证等级见 docs/VALIDATION.md。第三方平台的真实发布、桌面 MCP 工具发现和 UI 可见性分别记录，不能由本地测试替代。

Related MCP server: Codex DSH MCP

连接方式

Codex 当前桌面任务
  └─ MCP 工具（或本任务中的 CLI）
       └─ 当前用户私有 Unix socket
            └─ DSH Web profile 内的桥接插件
                 └─ SessionController / Agent / Git worktree

Codex 的结果通过当前工具调用返回原任务。无需另建 Codex 会话、启动 Codex app-server、使用桌面私有 IPC 或写两端私有会话存储。

桥接记录按任务关联执行身份，不把一个 Codex 会话固定绑定一个 DSH 会话。两端可继续用原有 UI；插件不替换它们。Codex 用 dsh_plan_wait 或 dsh_review_inbox 接收并复核。当前桌面任务另设每分钟定时跟进，读取持久收件箱；仅在桌面应用运行且定时任务正常时提供延迟唤醒，不承诺瞬时推送。

DSH 工作区要求会话 cwd 与工作区路径完全一致。并行修改使用独立 Git worktree 时，DSH 会显示多个工作区；在一个工作区下测试多个会话，应让这些会话共享该目录，并限定为只读检查或人工明确划分且不会冲突的工作。

本机安装

需要 Node >=22.16、Git、已启动的 DSH Web profile。本版对 DSH 0.1.7-alpha.2 的 SessionController / WorkspaceController API 做过运行验证；其他版本先核对接口。

pnpm install
pnpm test
pnpm run build
dsh plugin --profile web add /home/river/work/dsh/dsh-codex-bridge
node bin/bridge.mjs hello
codex mcp add dsh-codex-bridge -- node /home/river/work/dsh/dsh-codex-bridge/bin/mcp.mjs

DSH 使用原生组合包安装：dsh.bundle 将插件登记到 profile 的 dsh.profile.bundles，所以会出现在“插件”页；dsh.client 提供右侧栏的 Codex 桥接 tab。Git 安装需带已构建的 lib/；更新已安装包前需完成或明确停止活跃桥接计划。

Codex 安装后需要让应用重新加载 MCP 配置；当前任务若未发现新工具，可以使用同一服务的 CLI。配置存在不等于应用已加载工具。

socket 默认 ~/.dsh/codex-bridge/bridge.sock，权限 0600；记录目录权限 0700。可用 DSH_HOME 或 DSH_CODEX_BRIDGE_SOCKET 指定路径，MCP 客户端与插件必须一致。不要在多个 DSH 进程中共用同一 socket。

DSH 右侧栏

打开任一 DSH 会话，在右侧栏的引导页选择“Codex 桥接”。面板显示当前会话、工作目录和 DSH 工作区登记、此仓库的桥接计划和来源 Codex 任务 ID、相关 DSH 执行会话及 worktree、验收收件箱及回复。可发送新任务/问题；工作完成后填写真实摘要和 1–8 条已执行自检，提交独立验收请求。该请求在本机持久保存，由当前 Codex 任务的每分钟定时跟进读取。面板显示最近一次桌面任务核验时间和当时状态；超过两分钟标为过期，不冒充瞬时在线状态。DSH Web 需重启 Host 插件后才会读到新增心跳接口。

使用

向 Codex 描述目标，让它展示计划并取得你的批准。工具描述包含执行、独立复核和停止规则。可直接说：

在当前仓库用 DSH 实现这个功能。先列出文件范围、子任务、依赖和验收要求给我确认，完成后回到这里复核。不要发布远端。

CLI 与 MCP 共享接口；参数从 JSON 文件读取，避免 shell 插值：

node bin/bridge.mjs plan.preview /path/plan.json
node bin/bridge.mjs plan.approve /path/approval.json
node bin/bridge.mjs plan.status /path/id.json
node bin/bridge.mjs plan.wait /path/id.json
node bin/bridge.mjs plan.stop /path/id.json

最小计划：

{
  "id": "feature-001",
  "cwd": "/absolute/repository/root",
  "goal": "实现一个已确认的功能",
  "sourceTask": "originating-codex-task-id",
  "tasks": [
    {
      "id": "implementation",
      "title": "实现功能与验证",
      "prompt": "具体要求及约束",
      "files": ["src/example.js", "test/example.test.js"],
      "acceptance": ["运行指定测试并报告结果"],
      "dependsOn": []
    }
  ]
}

files 是精确相对文件路径，或以 / 结尾的目录范围；不支持 glob。计划 ID 在本机桥接记录中唯一。同一 ID 不同内容会被拒绝。批准参数是 {"id":"feature-001","hash":"预览返回的 hash"}。plan.status 返回 nextAction、任务状态、会话、worktree、真实回复及提交证据。

可选 delivery 必须在批准前指定完整目标：

{
  "forge": "github",
  "host": "github.com",
  "repository": "owner/repo",
  "remote": "origin",
  "targetBranch": "main"
}

GitLab 使用 "forge":"gitlab" 和实际 Web/API 主机。沿用已认证的 gh / glab，不读取或复制密钥。Git 推送目标必须与此仓库一致。没有远端配置的计划仍可本地交付。

复核须传当前 reviewHash、判断、反馈和证据引用。执行方自报通过不是验收依据。目标分支推进后会阻止发布，需重新集成与复核。远端创建结果不明时保留意图，不盲目创建第二份 issue/PR。草稿 PR 返回后由 Codex 附加到当前任务；用户自行决定合并。

从 DSH 主动请求与送审

新任务或问题可在右侧栏选“新任务 / 问题”，也可由 DSH 会话调用 request_codex_task，提供稳定 requestId 和 summary。Codex 主动读取收件箱后，可用 dsh_review_respond 回复；此处的 accepted 只代表受理，不代表代码验收或已完成任务。新的工作范围仍由 Codex 与用户确定。

在 DSH 会话完成工作和自检后调用 request_codex_review：提供稳定 requestId、summary 和 1–8 条具体 checks。桥接会记录 DSH 的真实 session ID、工作目录、Git HEAD 与变更文件指纹；重复的同一请求不再创建第二份。计划内任务还需带 planId / taskId，来源必须是该任务正在运行的 DSH 会话。

Codex 在原任务调用 dsh_review_inbox（参数 cwd 为仓库根目录），读取请求后检查实际文件和测试证据。独立 DSH 会话可用 dsh_review_respond 记录回复；计划内任务必须使用 dsh_plan_review，并沿用原修订预算。DSH 用 check_codex_review 查询验收结果。送审与自检均不等于 Codex 验收；由 Codex 定时跟进主动读取后，请求才会进入当前任务；本地 Codex 应用需保持运行。

恢复与卸载

plan.list 找到任务后查 plan.status。unknown、中断的准备阶段、冲突和范围越界需要检查已有文件、分支及远端事实；本版保守停止，不自动回滚或再次执行不明操作。不要删记录后重发来绕过去重。

卸载前停止活跃任务，再执行 dsh plugin --profile web remove dsh-codex-bridge 和 codex mcp remove dsh-codex-bridge。已产生的 worktree、提交、执行记录和配置备份保留，供人工处理。