# Codex DSH Bridge

把 Codex 的任务交给**你本机已安装的** DeepSeek Harness（DSH）执行的本地协作桥。Codex 负责目标、取舍与验收；DSH 在自己的私有 SDK 会话里完成被委派的那一部分。桥本身只做进程、协议与记录，不实现模型。

> 这是独立的社区集成，不是 DeepSeek、Codex 或任何模型厂商的官方产品，也不代表其背书。仓库**不包含** DSH、Electron、Node 运行时、模型或任何密钥。

## 快速开始

先让 DSH 自己能独立完成一个任务，再接桥。完整步骤（准备、两种安装强度、更新、回退、卸载、隐私）见 **[docs/installation.md](docs/installation.md)**。

```sh
npm ci --ignore-scripts
 
# 先复制并编辑 examples/config.example.json，再替换下面的 YOUR_CONFIG.json
node bin/codex-dsh-bridge.mjs doctor --config "YOUR_CONFIG.json"
node bin/codex-dsh-bridge.mjs install --config "YOUR_CONFIG.json"          # 只预览
node bin/codex-dsh-bridge.mjs install --config "YOUR_CONFIG.json" --apply  # 才写入
```

`YOUR_CONFIG.json` 代表你刚准备的文件；路径含空格时保留引号。`install` 默认只打印将修改的文件，`--apply` 才落盘。写完后新开一个 Codex 会话，确认技能与 MCP 工具已加载，并先跑一个小型只读任务。

## 你需要自己准备

这个包不替你准备运行环境，也不附带任何账户：

- **Node.js 22 或更新版本**：用于启动这个桥；本次实测版本为 24.22.1。
- **DSH 与运行时**：官方 DSH 安装、`config.executable` 指向的 Node/Electron 可执行文件、`config.entrypoint` 指向的官方 SDK 入口，都来自你自己的安装。
- **提供方与模型**：`defaultProvider` / `defaultModel` 必须出现在你自己的 DSH `desktopConfig`（默认 profile `llm-pi-ai`，可用 `desktopProfileId` 改）里。
- **凭据引用**：`credentialsPath` 只记录**位置**。桥接代码不主动读取凭据文件正文；DSH 运行时使用它完成模型服务认证。发布包不包含真实凭据。
- **相对路径**按配置文件所在目录解析；`~/` 与 `${HOME}` 会展开。配置文件允许带 UTF-8 BOM（与安装器一致）。

可选字段：`workerRoutes`（精确 `{provider, model}` 白名单，默认空）、`modelRoutingFile`、`maxConcurrentTasks`、`maxTokens`、`home`、`stateDir`。示例见 [examples/config.example.json](examples/config.example.json) 与 [examples/README.md](examples/README.md)。

## 命令

安装 / 卸载（默认预览，`--apply` 写入）：

| 命令 | 作用 |
| --- | --- |
| `install --config FILE [--apply] [--with-global-rule] [--codex-home DIR] [--skills-dir DIR]` | 写入 MCP 工具与协作技能；可选全局 AGENTS 规则 |
| `uninstall [--codex-home DIR] [--apply]` | 只移除本安装器写入的内容，DSH 本体、凭据、任务结果保留 |

运行时（`--config FILE` 或环境变量 `DSH_BRIDGE_CONFIG`）：

| 命令 | 作用 |
| --- | --- |
| `doctor` | 检查配置、路径与可用路线；不启动 SDK 会话、不发模型请求，可能创建本地状态目录 |
| `run REQUEST.json` | 执行一次委派，进程保持到出现终态结果 |
| `status TASK_ID` | 读取已保存的任务状态与结果 |
| `plan TASK_TYPE [root\|child]` | 按任务类型查看候选路线与理由 |
| `feedback REVIEW.json` | 记录一次**已独立验收**的复核结论 |
| `serve` | 以 MCP stdio 服务方式运行 |

## 费用、数据与边界

- **费用**：模型调用走你自己配置的提供方，按其价目计入**你的**账户；本包不代付、不转售、不含额度。
- **数据**：执行委派时，任务提示与必要上下文会发送给你选择的提供方并适用其数据政策；DSH 自行处理认证。工具输出可能进入本地日志，分享日志前检查敏感内容。
- **本地记录**：任务提示、结果与事件默认保存在 `~/.codex-dsh-bridge/state/`，可能含项目内容，只在本机，不属于发布包。
- **不是同步产品**：不做手机端、云端同步或多设备漫游；也不接管你已打开的桌面会话。
- **全局规则不是强制**：可选的 `--with-global-rule` 会在全局 `AGENTS.md` 写入“先发现、适用时委派”的工作约定。它是给模型的指令，不是拦截引擎，简单问答、小改动、无法拆分的界面操作仍可由 Codex 直接处理。

## 入口在 app.asar 里时

官方桌面版可能把 SDK 入口放在 `app.asar` 内部。普通 Node 的 `fs.stat` 看不到归档成员，会把可用的入口误报为缺失，所以 `doctor` 对这类路径改走归档感知探测：用你在 `config.executable` 明确指定的 Electron 可执行文件、以 `ELECTRON_RUN_AS_NODE` 模式、带超时上限、无 shell、无模型请求地询问**目标成员本身**是否是可读文件。`app.asar` 容器存在与否不构成通过依据。

探测无法给出可信结论时（不可执行、超时、输出无法解析、或运行时自称不是 Electron），`doctor` 报告**“未验证”（unverified）**并判为未通过，而不是“缺失”或“已通过”。普通文件仍沿用原有的 `fs.stat` 检查。

## 测试与发布检查

```sh
npm test
node scripts/check-release.mjs
```

发布检查是文件白名单加启发式敏感模式扫描，仍需人工复核；不要把整个工作目录直接上传。

Windows 打包：`powershell -File scripts/package.ps1`，生成源码 ZIP 与逐文件校验清单。测试结果和未验证平台见 [docs/verification.md](docs/verification.md)。首发以 GitHub 源码与 Release ZIP 交付，不发布 npm 包。

## 许可证

MIT，见 [LICENSE](LICENSE)。第三方依赖、官方 SDK 协议与“不打包运行时”的说明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。