# Codex–DSH Windows 协作桥接

这是基于 Cryocell77/deepseek-harness-desktop-mcp-bridge（MIT）制作的本地 Windows 适配版，增加持久化任务、方向问答、计划检查点、阶段验收和成果指纹。上游版权见 LICENSE 和 NOTICE。

当前已安装版本：`0.2.1-rc3-windows.4`，已与本机 DSH Desktop `0.2.1-rc.3` 完成真实联调。首次连接的问题来自插件可选依赖解析到旧 Schemastery，现已将它作为精确版本依赖固定到 3.18.5。

## 本机入口

- Codex MCP：`dsh_desktop`，已通过本机 CLI 注册。现有聊天可能需要刷新 MCP 连接或在新聊天中加载。
- DSH：使用已安装 Desktop 的现有 Host 和模型配置。桥接不会复制模型凭据。
- 本地状态：`F:/codex/dsh-bridge-state`。这里有认证信息和任务记录，不要分享整个文件夹。
- 任务成果：`F:/codex/dsh-bridge-work/<jobId>`。
- DSH 工作区：`codex自动`，对应 `F:/codex/dsh-bridge-work`。今后通过桥接新建的会话（包括恢复时的新 worker）自动归入该工作区；文件仍分任务子目录保存。
- 编译后的入口：`dist/cli.js`；当前会话的客户端后备入口：`dist/call.js`。
- 协作技能：`codex-skill/SKILL.md`，安装后可通过 `$codex-dsh` 调用。

## 使用

在 Codex 中说：“用 DSH 协同完成……，由你制定标准、处理它的问题并验收。”

第一版支持单个任务串行执行。任务先询问必要方向并提交计划，得到 Codex 放行后才能使用桥接文件工具写入成果。完成执行后进入待审查状态，Codex 检查实际成果后才能验收。DSH 的提问会在 Codex 当前执行期间通过事件等待被读取；关闭聊天后的自动唤醒尚未实现。

当前桥接给 DSH 注册五个工具：方向提问、阶段检查点、任务目录内文件读取、写入和目录列表。其他 DSH 原生工具默认不开放。代码构建、命令执行和外部核验暂由 Codex 处理。文件路径限制并非操作系统级隔离。

在本机私有配置中设置 `"workspaceTitle": "codex自动"`，插件加载时通过 DSH 官方工作区注册服务创建或复用 `workspaceRoot` 并设置名称。会话创建后必须成功登记归属，才会交给调用方。此设置在插件重新加载后生效，不迁移历史会话；命名工作区模式要求 `allowedTools: []`，避免原生工具使用公共会话目录。监督文件工具继续使用各自任务目录。

## 验证记录

`verification-all.txt` 保存 33 项自动检查通过的结果；`LIVE-VERIFICATION.json` 保存真实提问、计划放行、文件生成和最终验收结果，`LIVE-REVIEW-CYCLE.json` 保存同一 DSH 会话的退回修改和复验结果。两个真实联调记录均为 status=passed。联调样例文件见“联调样例”目录。

## 故障恢复

确保 DSH Desktop 正在运行并加载了桥接插件，然后运行：

```text
node dist/cli.js doctor --config F:/codex/dsh-bridge-state/config.json
```

重启后的任务会保留记录，并标为 interrupted。检查成果后由 Codex 显式恢复，不能自动重复执行原请求。取消保留已写文件。

如提示 bridge.lock 残留，先确认旧 DSH Host 已停止。不要在旧进程仍存活时删除锁或启动另一个 Desktop Host。

## 卸载

用 Codex CLI 删除 `dsh_desktop` MCP，并用 DSH Desktop 自带的 dsh 命令移除 `dsh-desktop-mcp-bridge` 插件。协作技能可以单独移除。配置和成果默认保留，需另行决定是否清理。

源码中的 upstream docs/ 和 plugins/ 保留上游参考信息，可能含 macOS 专属步骤。本机使用以上 Windows 入口。