cd-connect

中文 | English

cd-connect 把规划与审查端连接到现有的 DeepSeek Harness Desktop：你在 ChatGPT/Codex 一侧定义阶段任务，DSH 在原有的原生会话、模型、工具权限和人工审批边界内执行，你再依据当前运行的证据决定通过或返工。

项目名中的 c 代表 ChatGPT，d 代表 DeepSeek Harness。当前实测的规划端是 Codex 桌面会话；ChatGPT 网页与隧道方案尚未验证。

它适合谁

• 你已经在同一台 Linux 电脑上使用 DSH Desktop，希望把另一个会话中的阶段目标交给它执行，而不是手工复制提示词。

• 你需要可追踪的任务状态、明确的验收条件和可核对的当前运行证据。

• 你接受执行完成后由独立审查决定是否通过：审查可由人或用户授权的规划/审查 Agent 执行，模型自述完成不能替代证据；DSH 原生审批仍由人按原生策略决定。

它不适合需要无人值守调度、跨多台机器执行、多租户隔离或“外部副作用恰好一次”保证的场景。第一版只面向本地单用户。

Related MCP server: Codex DSH MCP

当前支持范围

桥接提供九个 MCP 工具：八个任务工具，加上只读的 bridge_health。任务提交会创建普通原生 DSH 会话；续写复用同一会话。cd-connect 不更换模型，不授予额外权限，也不替你在 DSH 中批准操作。

快速开始

以下命令中的 /absolute/path/to/... 与 /tmp/... 都是示例占位，请替换为实际路径。正常路径可以一次走完；完整安装替代路径、升级、卸载和故障恢复见安装与维护。

1. 准备环境

需要 Node.js 22.19.0 或更新版本、可用的 DSH Desktop 0.2.1-rc.2，以及支持本地 stdio MCP 的规划端。先把完整源码放在任意绝对目录，例如 /absolute/path/to/cd-connect。

源码仓库为 M1racleShih/cd-connect，采用完整源码目录安装，不提供 npm 包。获取源码后，再执行下面的安装步骤。

2. 安装依赖并做基础检查

cd /absolute/path/to/cd-connect   # 示例路径
npm ci --ignore-scripts
npm test
npm run check

--ignore-scripts 与当前安装流程一致；项目是直接运行的 ESM JavaScript，没有构建步骤。npm test 默认运行隔离测试；需要 DSH 源码的原生组件测试会跳过，说明见贡献指南。npm run check 递归检查 src/、scripts/ 和 test/（含 test/support/）中的 .js 文件，只做语法检查，不是类型检查。CI 配置覆盖同样的基础检查，不包含原生组件测试或真实桌面验收。

3. 在 DSH 中启用插件

打开 DSH 的“插件”页面，安装上述源码的绝对目录，启用 cd-connect bundle。插件加载后会：

• 在 127.0.0.1:48763/mcp 启动回环 MCP 服务（port 配置可覆盖端口）；

• 在实际 DSH home 下的 cd-connect/connection.json 写入本次加载的独立随机凭据，文件权限为 0600；

• 在实际 DSH home 下的 cd-connect/ledger/tasks.json 保存任务账本。

本地脚本默认查找 ${DSH_HOME:-~/.dsh-linux}/cd-connect；实际 DSH home 不同时，设置 CD_CONNECT_STATE_DIR 指向它。

如果加载失败，先检查端口占用、DSH 版本、profile 类型和存储目录权限。完整替代路径见安装与维护。

4. 连接 MCP 并确认成功标志

npm run health
codex mcp add cd-connect -- "$(command -v node)" /absolute/path/to/cd-connect/src/stdio.js

注册后按客户端方式重新加载本地 MCP 连接，再让目标会话直接调用 bridge_health。正常结果应包含：

• profile: "desktop"，bridge.version: "0.4.1"，bridge.phase: 3；

• storage.healthy: true；

• capabilities.task_execution: true、task_storage: "durable_snapshot_v1"；

• capabilities.tools 中恰好九个工具，包含 task_submit 与 bridge_health。

npm run health 和 npm run verify:native 只验证本机 SDK/HTTP/stdio 路径，不是目标会话的验收。更新插件后需让 DSH 重新加载插件，并刷新客户端的 MCP 连接以更新工具目录。

5. 完成一次最小任务

先创建一个真正的一次性空工作区，并记录命令输出的绝对路径。该目录必须已存在、是绝对路径，并只包含本次允许修改的内容：

workspace=$(mktemp -d /tmp/cd-connect-hello.XXXXXX)
printf '%s\n' "$workspace"

在规划端会话中用自然语言提交类似下面的规格；把 <workspace> 换成上一步输出的实际绝对路径，不要原样提交占位符：

请通过 cd-connect 提交一个阶段任务。workspace 为 <workspace>（上一步输出的实际绝对路径，不要原样使用占位符）；goal 是创建 greeting.txt，内容恰为 hello 加一个换行；scope 仅允许修改该文件；out_of_scope 为其他文件、外部服务与发布；constraints 为使用现有模型和原生权限、不使用子 agent；acceptance 为重新读取文件得到 6 字节 hello\n，并报告校验命令、退出状态和 SHA-256。

随后按工具返回的标识推进，不要跳步：

1. 先 bridge_health，确认连的是预期实例。

2. task_submit 返回 task_id、revision、run.id 和 event_cursor。保存这些值，保留提交时的请求编号。

3. 用最后消费的事件游标调用 task_wait。等待超时只表示这段时间没有新事件，不代表执行完成。

4. 进入 awaiting_review 后，用当前 run.id 从游标 0 开始调用 task_evidence，消费全部页。同时直接检查工作区中的实际文件；模型陈述不能替代验证。

5. 核对范围和验收条件后调用 task_review，携带当前版本、当前 run_id、新请求编号、decision: "accepted"、具体说明和本轮证据编号。成功标志是任务状态最终为 accepted，且任务确实出现在对应的 DSH 原生会话中。

具体返工示例：若文件实际内容是 hello world 加换行，先以 changes_requested 记录“应为 hello 加单个换行，当前多出 world；请修正后重新读取并报告摘要”，附上当前证据编号；再用当前 run_id、revision 和新请求编号调用 task_continue，要求在同一原生会话中修正并重新验证；等待新运行完成后，只审查新运行的证据，最后才记录 accepted。

执行完成（execution_completed / awaiting_review）与验收通过（accepted）是两个独立事实。字段级定义、游标规则和恢复顺序见任务协议。

为什么这样设计

仅转发一段提示词，只能证明消息被发送；它不能证明任务被正确执行，不能证明结果在审查时仍然有效，也不能证明某次重试不会重复产生副作用。因此 cd-connect 把协作单位定义为包含目标、范围、排除项、约束和验收条件的任务，而不是一条聊天消息。

规划与审查端决定要完成什么、依据什么接受；执行端复用已有 DSH 会话、工具和权限，负责实现与验证。断线、重启、超时和迟到响应被视为正常情况：桥接保存请求身份、实际会话映射、运行编号和派发回执；无法证明结果时先核对原生日志，而不是自动重放。文件可能在执行结束后被改动，所以验收还要关联当前运行的证据与完成时的目录见证。

授权不能由模型报告或另一段模型输出产生。DSH 保留原生人工审批，桥接只展示审批状态；续写与取消必须核对当前运行。由此形成的是一个边界明确、可恢复、可审查的任务协议。

flowchart LR
    Human["用户"] -->|目标与授权| Client["规划与审查端<br/>当前实测 Codex 桌面"]
    Client <-->|MCP stdio| Stdio["本地适配器<br/>src/stdio.js"]
    subgraph Host["现有 DSH Desktop Host"]
        Server["MCP 服务<br/>src/server.js"]
        Tasks["任务与审查管理<br/>src/tasks.js"]
        Native["原生接口适配<br/>src/native.js"]
        Agent["DSH 原生会话与 Agent"]
        Ledger[("桥接任务账本")]
        Witness["工作目录见证<br/>src/workspace.js"]
        NativeLog[("原生会话日志")]
        Server <--> Tasks
        Tasks <--> Native
        Native <--> Agent
        Tasks <-->|持久化| Ledger
        Tasks -->|完成时核对产物| Witness
        Agent --> NativeLog
        NativeLog -->|恢复时读取| Native
    end
    Stdio <-->|回环 HTTP<br/>独立凭据| Server
    Workspace[("任务工作目录")]
    Agent -->|执行工具| Workspace
    Witness --> Workspace
    Human -->|原生审批| Agent

插件运行在现有 Host 内，stdio 适配器只转发 Host 实际提供的工具；任务状态在插件内，桥接账本与原生日志职责不同。目录占用只约束同一桥接存储中的任务，不是系统级写锁。组件职责与协议身份详见架构说明。

关键限制与安全边界

• 审批仍在 DSH：waiting_approval 只展示待审批的工具、调用编号和原因；桥接没有批准接口，也不更改模型、权限或审批策略。请在 DSH 界面核对完整命令后自行决定。

• 完成不等于通过：原生执行失败、取消、阻塞或 token 上限不会进入可验收状态。即使模型声明完成，权限拒绝或证据不完整仍不能验收。

• 取消有确认边界：accepted 只表示取消请求被接受；匹配轮次以 aborted 结束且空闲后才是 confirmed。取消不回滚修改，也不自动释放目录占用。

• 未知结果不重放：重启、超时、派发回执缺失或取消结果不明时，先读取快照并用 task_recover 核对原生日志。只有能证明尚未尝试的意图才能显式派发。

• 不保证恰好一次：桥接降低重复派发风险，但不能证明任意外部副作用恰好一次；也不能阻止或归属执行期间其他进程的写入。

• 目录与证据范围有限：同一桥接存储中，未验收任务占用同目录及父子目录；完成时见证覆盖普通文件内容/权限、目录结构和符号链接目标文本，排除 .git，不跟随符号链接，上限为 20000 个条目与 128 MiB。外部服务、链接目标内容和修改后又恢复的历史不在见证范围内。

• workspace 只是磁盘 cwd：提交的目录会成为新原生会话的当前目录，但当前版本不会注册或关联 DSH 侧栏工作区；新会话可能出现在未分组列表中。请保存 session_id 并按任务映射查找。

• 本地边界并非沙箱：回环监听、Bearer 凭据、Host/Origin 检查和文件权限只保护本机单用户路径，不构成不可信多租户隔离。不要把监听公开到互联网。

• 账本含私有内容：tasks.json 保存任务正文、会话映射与部分工具证据，连接文件含本机凭据。不要提交、上传或公开整份账本/连接文件；删除账本会失去去重与恢复依据。

深入文档与贡献

以下深入文档与贡献入口当前均为中文；英文 README 同步了支持范围、命令和限制，并在此明示语言差异。

• 安装、连接、升级、卸载与故障恢复

• 架构、协议身份与控制边界

• 任务提交、等待、证据、审查、取消与恢复

• 贡献指南与验证分层

• 安全策略、敏感数据与私下报告

• Agent 工作入口

• CI 工作流

相关项目

• DeepSeek Harness：上游执行框架。

• DSH Linux：第一版接入目标。

• dsh-chatgpt-bridge：相关桥接实现参考。

• codex-bridge：多执行器桥接实现参考。

许可

本项目采用 MIT 许可证，完整文本与版权声明见 LICENSE，版权 © 2026 Han-Qing Shi。第三方依赖保留各自的许可；支持的 Node.js 版本与基础验证范围见上文，安全报告方式见安全策略。

cd-connect 是独立项目，与 OpenAI 或 DeepSeek 不存在官方隶属或背书关系。