# dsh-mcp-bridge —— 让 Codex 把任务派给本机 DSH

**2026-11-08 建立并实测通过。** Codex（以及任何 MCP 客户端）通过一个 stdio MCP 服务器，
把子任务派给 NAS 上的 DeepSeek Harness（DSH）在后台执行，带文件、能续接会话、能指定
provider / 模型 / 思考档位。

```
Codex ──MCP(stdio)──► dsh_mcp_server.py ──spawn──► dsh --profile headless --json "任务"
                              │                          │
                              └── /vol1/ai/dsh-runs/<run_id>/  ◄── NDJSON 事件落盘
                                    meta.json / events.ndjson / stderr.log / done.json
```

## 一、文件

| 路径 | 作用 |
|---|---|
| `/vol1/ai/projects/dsh-mcp-bridge/dsh_mcp_server.py` | MCP 服务器（stdio，9 个工具） |
| `/vol1/ai/projects/dsh-mcp-bridge/dsh_runner.py` | 子进程执行器（跑 dsh、落盘事件、写 done.json） |
| `/vol1/ai/projects/dsh-mcp-bridge/test_client.py` | MCP 冒烟（initialize / tools/list / 单工具） |
| `/vol1/ai/projects/dsh-mcp-bridge/test_flow.py` | 全链路验收（新建会话 / 传文件 / 续接 / 切档） |
| `/vol1/ai/projects/dsh-mcp-bridge/test_channel.py` | 通道切换验收（mimo / 缺 key 报错） |
| `/vol1/ai/projects/dsh-mcp-bridge/codex-e2e.sh` | **真·端到端**：让 codex 自己调 MCP 派任务 |
| `/vol1/ai/projects/dsh-mcp-bridge/codex-e2e-upload.sh` | 端到端 2：codex 调 `dsh_upload` + 带文件派单 |
| `/vol1/ai/_scripts/dsh-creds-exec.py` | 把 `.credentials.yaml` 的 refs 注入环境后执行命令（排障用） |
| `/vol1/ai/dsh-runs/` | 每次派单的运行目录（`dsh_result` 读的就是它） |
| `/vol1/ai/dsh-workspace/` | DSH 默认工作区；上传文件落 `dsh-inbox/` |

注册位置：`/vol1/ai/agents/codex/config.toml`

```toml
[mcp_servers.dsh]
command = "/usr/bin/python3"
args = ["/vol1/ai/projects/dsh-mcp-bridge/dsh_mcp_server.py"]
env = { DSH_HOME = "/vol1/ai/home/.dsh", HOME = "/vol1/ai/home" }
startup_timeout_sec = 30
tool_timeout_sec = 900
```

## 二、工具

| 工具 | 参数 | 说明 |
|---|---|---|
| `dsh_dispatch` | `task`*, `cwd`, `session_id`, `provider`, `model`, `effort`, `files[]` | 后台开跑，立即返回 `run_id` |
| `dsh_result` | `run_id`*, `wait_seconds`（≤600） | 拿 `state` / `answer` / `session_id` / 步数 / 用量 |
| `dsh_runs` | `limit` | 最近派的单 |
| `dsh_cancel` | `run_id`* | SIGTERM 掉 |
| `dsh_models` | — | provider / 模型 / 档位 / `credential: ready|missing-key` |
| `dsh_set_default` | `provider`*, `model`, `effort` | 改 headless 默认模型（自动备份 patch） |
| `dsh_sessions` | `limit` | 最近 DSH 会话（含 codex 派单建的） |
| `dsh_session_read` | `session_id`* | 读该会话最后一轮问答 + 真实 `model_config` |
| `dsh_upload` | `paths[]`*, `cwd` | 复制进 `<cwd>/dsh-inbox/`，返回落点 |

`state` 三种：`running` / `done` / `error`（error 时 `error` 字段带 DSH 原始错误码）。

## 三、当前默认配置（2026-11-08）

- provider `deepseek-go` → `https://opencode.ai/zen/go/v1`（走 Go 订阅）
- model `deepseek-v4.1-flash`
- **effort `max`**（最高档；`high` 也可切，`off` 关思考）
- 权限：`danger-full-access` + `approval=never`（与 web profile 对齐，否则 headless 的 `ask` 会挡住工作区外读写）
- 通道现状：`deepseek-go` 可用；`mimo` 有 key 但账户 **402 余额不足**；`deepseek`（官方）refs 里**没有 `DEEPSEEK_API_KEY`** → 派单前会被拦下并直接说清楚

## 四、实测记录（2026-11-08）

| 项 | 结果 |
|---|---|
| 新建会话 | ✅ `session-f3c1d3f6-…`（16 步），DSH 网页里带自动标题 |
| 上传文件 + 读取 | ✅ `dsh-inbox/sample-upload.txt` 首行原样回显「白桦 37 株…」 |
| 会话续接（对话） | ✅ 同一 `session_id` 继续，回答 `OK` |
| 切思考档位 | ✅ 覆盖层生效：会话 `request/header` 里 `reasoningEffort` 从 `max` 变 `high` |
| 切 API 通道 | ⚠️ 机制通（`--patch` 覆盖 provider），但 mimo=402、官方 deepseek 缺 key |
| Codex 自动派单 | ✅ `codex exec` 自己调 `dsh_models → dsh_dispatch → dsh_result`，拿到 `answer=桥通了`、`state=done` |

## 五、踩过的坑（改之前先看）

1. **headless 不读凭据服务**：`dsh headless` 直接报
   `MISSING_CREDENTIAL ... DEEPSEEK_GO_API_KEY is not set`。`.credentials.yaml` 的 `refs`
   只对 web 有效 → MCP 服务器启动子进程时把 refs **注入环境变量**。
2. **`--patch` 是启动器级参数**，必须写在 profile 之后、`--json/--session-id` 之前：
   `dsh --profile headless --patch x.yml --json "任务"`。放到 `--json` 后面就报 `unknown option '--patch'`。
3. **headless 原来没声明 `reasoningEfforts`** → 传 `max` 直接 `UNSUPPORTED_REASONING_EFFORT`。
   已在 `profiles/headless/cordis.patch.yml` 给 `deepseek-v4.1-flash` 补 `off/high/max`，并把默认设成 `max`。
4. **YAML 的 `off:` 会被 PyYAML 解析成 `False`** → 读档位列表时要还原成字符串。
5. **子进程 stdin 必须 DEVNULL**：否则 dsh 继承 MCP 的 JSON-RPC 管道，读走客户端的请求或触发 EOF，
   MCP server 会“莫名其妙退出”。
6. **档位要跟模型声明对齐**：模型不声明档位时（mimo、beam-free、官方 deepseek）传 `max` 会报错 →
   MCP 会降级并回一条 `warnings`，不会闷声失败。

## 六、重装 / 排障

```bash
# 1) MCP 冒烟（不起 codex）
cd /vol1/ai/projects/dsh-mcp-bridge && python3 test_client.py '[{"tool":"dsh_models","args":{}}]'

# 2) 全链路（新建会话 / 传文件 / 续接 / 切档，3~4 分钟）
python3 test_flow.py

# 3) codex 是否认得这个 MCP
codex mcp list | grep dsh

# 4) codex 真派一次单（约 1~2 分钟，消耗 luna 额度）
./codex-e2e.sh

# 5) 单次派单的手工排障
python3 /vol1/ai/_scripts/dsh-creds-exec.py dsh --profile headless --json "只回两个字：收到"
```

`/vol1/ai/dsh-runs/` 会一直涨，定期清 7 天前的：`find /vol1/ai/dsh-runs -maxdepth 1 -mtime +7 -type d -exec rm -rf {} +`
