cd-connect

中文 · English

在 Codex 中规划和审查，让 DSH Desktop 执行阶段任务。

快速开始 · 工作方式 · 支持范围 · 文档 · 贡献

cd-connect 通过 MCP 连接规划与审查端和现有的 DeepSeek Harness Desktop。你定义目标、范围和验收条件，DSH 使用原有模型、工具权限和人工审批执行；执行结束后，由人或用户授权的审查 Agent 检查当前运行的证据和实际产物，决定通过或返工。

项目名中的 c 代表 ChatGPT，d 代表 DeepSeek Harness。目前实测客户端为 Codex 桌面会话，面向同一台 Linux 电脑上的单用户使用。

核心能力

• 明确交接任务：提交目标、工作目录、允许范围、排除事项、约束和验收条件，创建普通 DSH 原生会话；返工沿用该会话。

• 按证据审查：读取本轮助手消息、工具调用和结果，核对实际文件。执行结束与审查通过分别记录。

• 中断后可核对：持久保存请求编号、运行记录和派发回执。结果不明时先查原生日志，不自动重发。

• 保留原生控制：不更换模型、不扩大工具权限、不代替人工审批；续写与取消都检查当前运行和版本。

Related MCP server: Codex DSH MCP

工作方式

插件运行在已有 DSH Desktop Host 内；本地 stdio 适配器只转发 Host 实际提供的工具。桥接保存任务记录，DSH 保存原生日志；完成时的目录见证记录文件内容、权限、目录结构与符号链接目标文本的摘要，供审查时核对变化。组件职责 · 图表源文件与维护

一次任务按以下顺序推进：

1. 提交：先检查 bridge_health，再用 task_submit 提交明确规格，保存任务编号、运行编号、版本和事件游标。

2. 等待：用 task_wait 消费事件页；超时只表示本次没有新事件。遇到 waiting_approval，由人在 DSH 中核对并批准或拒绝。

3. 审查：进入 awaiting_review 后，读取当前运行的全部 task_evidence 页，检查实际产物，再用 task_review 记录决定。

4. 返工或通过：需要修正时先记录 changes_requested，再用 task_continue 在同一会话继续；新运行完成后重新审查。通过时才记录 accepted。

支持范围

本项目不提供跨机器执行、多租户隔离、无人值守自动恢复或外部副作用恰好一次的保证。

快速开始

需要可用的 DSH Desktop、符合上表的 Node.js，以及支持本地 stdio MCP 的客户端。以下 /absolute/path/to/... 和 /tmp/... 均为示例路径，请替换为实际路径。升级、卸载、Desktop CLI 替代安装和故障处理见安装与维护。

1. 获取源码并检查环境

git clone https://github.com/M1racleShih/cd-connect.git
cd cd-connect
npm ci --ignore-scripts
npm test
npm run check

项目是直接运行的 ESM JavaScript，无构建步骤。默认测试使用隔离夹具，会跳过需要 DSH 源码的原生组件测试；check 递归检查 src/、scripts/、test/ 的 JavaScript 语法，不做类型检查。CI 覆盖基础安装和这两项检查，并运行双语文档检查；验证范围见贡献指南。

2. 在 DSH 中启用插件

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

• 在 http://127.0.0.1:48763/mcp 提供 MCP 服务；可用原生 port 配置改端口。

• 在实际 DSH home 下写入 cd-connect/connection.json，保存本次加载的随机凭据，权限为 0600。

• 在 cd-connect/ledger/tasks.json 持久保存任务记录。

本地脚本默认查找 ${DSH_HOME:-~/.dsh-linux}/cd-connect。实际位置不同时，设置 CD_CONNECT_STATE_DIR 指向对应的 cd-connect 目录。

3. 连接 Codex 并确认工具可用

从源码根目录运行，替换示例路径：

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

刷新客户端的 MCP 连接后，让目标 Codex 会话直接调用 bridge_health。确认连接的是预期实例，且返回：

• profile: "desktop"、bridge.version: "0.5.0"、bridge.phase: 3；

• storage.healthy: true、capabilities.task_execution: true；

• capabilities.task_storage: "durable_snapshot_v1"，capabilities.tools 恰好包含九个工具。

npm run health 与可选的 npm run verify:native 只验证本地 SDK/HTTP/stdio 路径。目标会话是否能发现和调用工具，要在该会话中确认。插件升级后需重新加载插件并刷新客户端连接。

4. 完成一个小任务

创建一次性空工作目录，记下输出的绝对路径：

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。

按上文流程等待并审查。读取证据时，从当前 run.id 的游标 0 开始消费全部页；调用 task_review 时携带当前 expected_revision、run_id、新 request_id、具体说明及本轮 evidence_ids。

若文件写成了 hello world 加换行，先记录具体的 changes_requested，再要求同会话修正并重新读取验证；只审查新运行的证据。成功标志是产物符合规格、任务出现在对应 DSH 会话中，且审查后状态为 accepted。完整字段与恢复步骤

为什么这样设计

转发提示词只能证明消息已发送。cd-connect 还要回答：执行的是哪项任务、哪些记录属于本轮、文件在审查时是否变化，以及中断后的请求是否已经执行。

为此，桥接保存结构化规格和稳定请求编号，用固定 Markdown 模板向 DSH 逐项传达要求；每次运行单独编号，证据与审查绑定该运行；派发前后分别保存意图和回执。无法确定执行结果时，先核对快照与原生日志。

这些文字要求不会变成额外的工具权限。执行方负责实现和验证，审查方根据证据决定是否通过，DSH 按原生策略保留人工审批。架构与设计细节

使用边界

• 审批在 DSH 中完成：waiting_approval 展示工具、调用编号和原因；完整命令需在 DSH 界面核对。桥接没有批准接口。

• 完成后仍需审查：execution_completed 和 awaiting_review 都不是 accepted。执行失败、取消、阻塞、token 上限、权限拒绝或证据不足时不能按成功验收。

• 取消需等待确认：取消请求的 accepted 仅表示收到请求；匹配轮次以 aborted 结束并空闲后才是 confirmed。取消不回滚修改，不自动释放目录占用。

• 未知结果先核对：重启、超时或回执缺失时，先 task_get，再 task_recover + inspect。只有记录证明尚未尝试的意图才可用 dispatch_prepared 显式派发。

• 文件检查有范围：同一桥接存储中，未验收任务占用同目录及父子目录；这不是系统级写锁。目录见证排除 .git，不跟随符号链接，上限为 20000 个条目、128 MiB。它不能阻止并发写入、归属其他进程的修改，或证明外部服务、链接目标内容及修改后又恢复的历史。

• 会话按工作目录归组：新任务按规范目录创建或复用 DSH 侧栏工作区，通过 workspaceId 关联会话并确定 cwd。保留已有名称；不按父目录或显示名称匹配。关联失败会停止派发并要求人工核对；旧会话不自动迁移。

• 私有数据留在本机：connection.json 含凭据，tasks.json 含任务正文、会话映射和部分工具证据。不要提交或公开；删除任务记录会丢失去重和恢复依据。回环监听、Bearer 认证和文件权限不构成多租户沙箱，不要向互联网暴露服务。

实验性事件协调器

可显式启动独立本地程序，由它调用 task_wait 等待任务。仅当绑定的实例、任务、运行和版本进入 awaiting_review 时，最多尝试一次唤醒专用 Codex 审查聊天；普通进度和审批等待不启动模型。

它使用实验性 Codex app-server stdio，保留原生模型与权限策略，只给出审查建议，不自动接受、续写、取消或恢复任务。CLI 提供 init/run/status/stop/rearm/reconcile，不安装常驻服务或定时模型轮询，也不保证账号零用量。专用聊天所有权、停止、游标和不确定发送的处理见事件协调器指南。普通 MCP 客户端继续使用原有等待流程。

文档

所有项目指南均提供中英文版本；每页顶部可切换语言。

贡献前请阅读贡献指南，并按变更范围运行检查。CI 配置覆盖基础安装、默认测试、递归语法检查与双语文档检查；原生组件测试和真实桌面验收需单独执行。

相关项目

• DeepSeek Harness：上游执行框架。

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

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

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

许可

MIT，版权 © 2026 Han-Qing Shi。第三方依赖保留各自许可。cd-connect 是独立项目，与 OpenAI 或 DeepSeek 不存在官方隶属或背书关系。