@whaletalk/dsh-codex-collab 0.1.5 → 0.1.7

package/README.md

@@ -6,38 +6,51 @@
 
 **Codex 主导，DeepSeek 执行，Codex 验收。** 一个插件体系，让 ChatGPT（Codex）像项目经理一样把编码任务派给本机 DeepSeek Harness 的编码子代理，实时回传结果，读文件验收，并由独立评审员实际跑通构建/测试后出具评审报告。
 
+派活有**两种目标**，必须显式选一种——"接进用户正在用的那条对话"和"新建一个干活的子代理"是两件事：
+
+| 目标 | 什么时候用 | 效果 |
+|---|---|---|
+| `worker`（默认） | 全新任务、独立项目目录 | 在 `--cwd` 里新建持久编码子代理（多工作区 · 多 lane · fast/pro 模型） |
+| `session` | 用户已经在某条对话里推进这件事，你只是替他继续 | 指令**投递进那条会话**，沿用它的上下文，**不新建会话/工作区** |
+
 ```
 Codex 工作区 (ChatGPT)
-   │  派活 / 评审 / 验收
+   │  dsh_task / dsh_sessions / dsh_review / dsh_read_file
    ▼
-DeepSeek Harness 网关 ── 编码子代理（多工作区、多 lane、fast/pro 模型）
-   │                     独立评审子代理（必须跑通构建/测试）
-   ▼
-共享工作目录（任意目录，--cwd 指定）
+DeepSeek Harness 网关 /api/dsh-bridge
+   ├─ worker 目标 ──→ 新建编码子代理（多工作区 · 多 lane · fast/pro）─┐
+   ├─ session 目标 ─→ 已有那条会话（prompt 投递，queue / steer）  ──┤
+   └─ 独立评审子代理（必须跑通构建/测试）───────────────────────────┴→ 共享目录 / 原会话
 ```
 
 ```mermaid
 flowchart LR
     subgraph Codex["Codex (ChatGPT) — 项目经理 + 验收员"]
-        A1[dsh_task 派活]
-        A2[dsh_review 评审]
-        A3[dsh_read_file 验收]
+        A1[dsh_sessions 找会话]
+        A2[dsh_task 派活]
+        A3[dsh_review 评审]
+        A4[dsh_read_file 验收]
     end
     subgraph DSH["DeepSeek Harness"]
         B1[HTTP 网关 /api/dsh-bridge]
-        B2[编码子代理<br/>多工作区 · 多 lane · fast/pro]
-        B3[独立评审子代理<br/>必须跑通构建/测试]
+        B2[worker 目标<br/>新建编码子代理]
+        B3[session 目标<br/>投递进已有会话]
+        B4[独立评审子代理<br/>必须跑通构建/测试]
     end
-    subgraph FS["共享工作目录"]
-        C1[任意项目目录]
+    subgraph FS["工作现场"]
+        C1[共享工作目录]
+        C2[已有会话与其上下文]
     end
-    A1 --> B1
+    A1 -->|只读查找| B1
     A2 --> B1
-    A3 --> C1
+    A3 --> B1
+    A4 --> C1
     B1 --> B2 --> C1
-    B1 --> B3 --> C1
+    B1 --> B3 --> C2
+    B1 --> B4 --> C1
     B2 -.实时回传汇报.-> B1
-    B1 -.任务结果.-> A1
+    B3 -.实时回传汇报.-> B1
+    B1 -.任务结果.-> A2
 ```
 
 ---
@@ -48,7 +61,10 @@ flowchart LR
 |---|---|---|
 | `codex-plugin/` | Codex 本地市场插件包 | 标准 marketplace 结构（`.agents/plugins/marketplace.json` + 插件目录），含协作技能 `dsh-collab` |
 | `mcp/dsh-mcp.mjs` | MCP 服务器（零依赖 Node） | stdio 传输（Codex `[mcp_servers]` 直连）+ Streamable HTTP 传输（`--http`，供 Secure MCP Tunnel / cloudflared 桥接 ChatGPT）；6 个工具：`dsh_task` / `dsh_sessions` / `dsh_task_status` / `dsh_task_cancel` / `dsh_review` / `dsh_read_file` |
-| `harness/dsh-bridge.mjs` | DeepSeek Harness 宿主组合网关插件 | 提供 HTTP 网关（`/api/dsh-bridge/*`）、WS 推送、原生工具，管理编码/评审子代理会话。**必须装进 harness 宿主组合**（见下文） |
+| `harness/dsh-bridge.mjs` | DeepSeek Harness 宿主组合网关插件 | 提供 HTTP 网关（`/api/dsh-bridge/*`）、WS 推送、原生工具；管理编码/评审子代理，并把任务投递进已有会话。**必须装进 harness 宿主组合**（见下文） |
+| `harness/session-target.mjs` | 会话目标的纯决策层 | 目标判定、候选挑选（0/1/N 不猜）、RemoteError→稳定 reason、基线切分、汇报选文。无 DSH import，可单测；`dsh-bridge.mjs` 依赖它，**两个文件必须一起部署** |
+| `test/` | 25 项 Node 测试 | `session-target` 纯函数单测 + `dsh-bridge` 路由级回归测试（假 DSH 运行时加载真实 bridge）。CI 每次都跑 |
+| `templates/codex-mcp/` | 反向通道配置模板 | 把 Codex CLI 当 MCP 服务端挂进 DSH（得到 `mcp__codex__*` 工具），让 DSH 侧也能调用 Codex。见下文「反向通道」 |
 | `cordis.patch.yml` | bundle patch | 把网关插件挂进 DSH 宿主组合；`dsh.bundle.patch` 指向它，所以 `dsh plugin add` 能自动 reconcile |
 
 ## 功能
@@ -69,7 +85,8 @@ flowchart LR
 
 ```sh
 # 1) 网关插件装进 harness profile（自动 reconcile bundles，无需手工复制文件）
-dsh plugin --profile web add @whaletalk/dsh-codex-collab
+dsh plugin --profile desktop add @whaletalk/dsh-codex-collab
+#    ↑ DSH 客户端用的就是 desktop profile；纯 Web 部署换成 --profile web
 
 # 2) MCP 服务器交给 Codex
 npm install -g @whaletalk/dsh-codex-collab
@@ -81,9 +98,27 @@ npm install -g @whaletalk/dsh-codex-collab
 [mcp_servers.dsh]
 command = 'dsh-mcp'
 startup_timeout_sec = 120
+env = { DSH_BRIDGE_URL = "http://127.0.0.1:3080" }   # 见下方"端口"；不写则默认 3080
+```
+
+**端口**：网关挂在 profile 的 `webServer` 上，地址取决于 profile 怎么起的——独立 harness 通常 `3080`，而 DSH 客户端里就是 **GUI 自己的端口**（例如 `http://127.0.0.1:19387`）。MCP 与 CLI 都用 `DSH_BRIDGE_URL` 找网关，指错只会看到连接失败或 401。验证：
+
+```sh
+curl http://127.0.0.1:3080/api/dsh-bridge/status
+```
+
+装完**必须重启 profile 进程**——`dsh plugin add` 改的是 bundles 列表与 node_modules，HMR 不监控这两处；**替换包内容也不会热重载**（ESM 缓存），只有重启进程才加载新版本。
+
+### 升级到新版本（有坑，照做）
+
+```sh
+# 1) 带精确版本号安装：不带版本号时 lockfile 会把旧版按回来
+dsh plugin --profile desktop add @whaletalk/dsh-codex-collab@<新版本>
+# 2) 重启 profile 进程：不重启不会加载新的 JS 模块
 ```
 
-装完**必须重启 profile 进程**——`dsh plugin add` 改的是 bundles 列表与 node_modules，HMR 不监控这两处。
+- **不要用"卸载 → 重装"**：卸载会把这个包从 `dsh.profile.bundles` 移除；重装后若没被重新选中，插件根本不会挂载（表现：所有 `/api/dsh-bridge/*` 都落到网关鉴权层返回 **401**）。真遇到了就在客户端插件页把它的开关打开。
+- **刚发布的版本约 24 小时内装不上**：profile 的 pnpm 带 `minimumReleaseAge` 供应链冷却（`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`）。管理器会把它写进 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 才放行；手工安装可临时加 `--config.minimumReleaseAge=0`。
 
 > 本包只提供 bundle patch，不含 profile 之外的强依赖：`@deepseek-ai/dsh-tools` 是 optional peer，由 DSH 安装树在运行时提供。因此 `npm install` 不会去 registry 拉它，也不会因它缺失而报错。
 
@@ -92,21 +127,23 @@ startup_timeout_sec = 120
 
 ### 1. DeepSeek Harness 网关（必需，后端）
 
-把 `harness/dsh-bridge.mjs` 复制到你的 dsh profile 目录（例如 `$DSH_HOME/profiles/web/`），并在该目录的 `cordis.patch.yml` 中追加：
+把 **`harness/` 整个目录**复制到你的 dsh profile 目录（例如 `$DSH_HOME/profiles/web/` 下的 `harness/`），并在该目录的 `cordis.patch.yml` 中追加：
 
 ```yaml
 - insert:
     - id: dsh-bridge
-      name: './dsh-bridge.mjs'
+      name: './harness/dsh-bridge.mjs'
 ```
 
+> `dsh-bridge.mjs` 会 `import './session-target.mjs'`——**两个文件必须在一起**，只复制前者会直接加载失败。
+
 重启 harness。默认共享工作目录为 `D:\Harness`，可用环境变量 `DSH_BRIDGE_WORKSPACE` 覆盖。验证：
 
 ```
 GET http://127.0.0.1:3080/api/dsh-bridge/status
 ```
 
-> 手工方式必须用相对路径 `'./dsh-bridge.mjs'`，因为文件就在 profile 目录里；npm 方式则用包子路径 `@whaletalk/dsh-codex-collab/bridge`，两者不要混用。
+> 手工方式必须用相对路径（文件就在 profile 目录里）；npm 方式则用包子路径 `@whaletalk/dsh-codex-collab/bridge`，两者不要混用。
 
 ### 2. Codex 侧（二选一或都用）
 
@@ -158,16 +195,32 @@ tunnel-client run --profile dsh
 
 **Codex 工作区会话**（MCP 工具就绪后）：
 
-> 用 dsh_task 让 DeepSeek 生成一个随机密码 CLI + 测试 + README，放在当前项目目录，完成后你用 dsh_read_file 验收，再 dsh_review 评审
+> **新建子代理**：用 dsh_task 让 DeepSeek 生成一个随机密码 CLI + 测试 + README，放在当前项目目录，完成后你用 dsh_read_file 验收，再 dsh_review 评审
+>
+> **接进原对话**：先用 dsh_sessions 按标题找到用户正在用的那条会话，再用 dsh_task 带 sessionId 把下一步指令投递进去（不要新建会话）
+
+**MCP 工具**（Codex 侧首选，工具名带 `mcp__dsh__` 前缀）：
+
+```jsonc
+// 1) 找到会话（只读）
+dsh_sessions({ "query": "按文档启动OKX策略实验计划" })
+// → { "items": [{ "sessionId": "session-8d481ad9-…", "snippet": "按文档启动OKX策略实验计划",
+//                 "agentAvailable": true }], "matchedBy": "list" }
+
+// 2) 投递进那条会话
+dsh_task({ "instruction": "继续推进第 3 步…", "sessionId": "session-8d481ad9-…" })
+// deliver 可选 "queue"（默认，排队）或 "steer"（插入当前回合）
+```
 
 **命令行**（npm 安装后直接用；源码方式用 `node <脚本路径>`）：
 
 ```bash
-# 新建子代理（原有行为）
+# 新建子代理（默认行为）
 dsh-task --in "<指令>" --cwd "<目录>" [--lane backend] [--model fast|pro] [--commit]
 
-# 接进已有会话：先找，再派
+# 接进已有会话：先找（或先空跑验证），再派
 dsh-task --sessions "<标题关键词>"                    # 只读列候选，拿 sessionId
+dsh-task --dry-run --find "<标题关键词>"               # 只解析目标、回显命中，不投递任何消息
 dsh-task --in "<指令>" --session "<sessionId>" [--steer]
 dsh-task --in "<指令>" --find "<标题关键词>"           # 唯一命中才派；否则退出码 4
 
@@ -180,19 +233,82 @@ dsh-task --list | --status <taskId> | --cancel <taskId> [--force]
 ```bash
 # 1) 找到（只读，不创建任何东西）
 dsh-task --sessions "按文档启动OKX策略实验计划"
-# → {"items":[{"sessionId":"session-8d481ad9-...","snippet":"@okx-strategy-lab/ 开始按照文档进行计划"}]}
+# → {"items":[{"sessionId":"session-8d481ad9-…","snippet":"按文档启动OKX策略实验计划",
+#              "agentAvailable":true}],"total":1,"matchedBy":"list"}
+
+# 1b) 没命中时会给近似候选（按标题相似度 + 最近更新排序），换词重查或改用 sessionId——
+#     绝不要发一条消息去"试探命中"（它会落进对方会话并跑成回合，污染对话）
+dsh-task --dry-run --find "量化框架"
+# → {"resolved":false,"reason":"session-query-empty",
+#    "candidates":[{"sessionId":"1c0f99f8-…","snippet":"你是一个量化研究项目的技术","score":0.333}, …]}
+
+# 2) 接通（投递进那条会话；这一轮的助手回复作为汇报返回，只回报本轮新增文本）
+dsh-task --in "<继续推进的指令>" --session "session-8d481ad9-…"
+```
+
+`matchedBy` 说明"找到"走了哪条路：`search` = 会话搜索索引；`list` = 索引被部署禁用时退回遍历列表 + 标题投影（都不激活 Agent）。
 
-# 2) 接通（指令投递进那条会话，跑完把这一轮的助手回复作为汇报返回）
-dsh-task --in "<继续推进的指令>" --session "session-8d481ad9-..."
+**`delivered` 与排队语义**（重要）：`prompt` 一旦被目标会话接受，就表示消息**已经进了它的队列**，响应里会带 `delivered: true`；此后即便我们的观察超时（会话可能正跑一个很长的回合），也**不要重发**——重发会让同一份内容在用户会话里出现两次。`queue` 模式不再用 120s 判失败：没在 120s 内开跑只记一条 note 并继续等，最终由总预算（默认 1h）收口为 `session-timeout` + `delivered: true`。
+
+失败返回稳定 `reason` 且**不创建任何会话/工作区**：`session-query-empty`（没命中，附 `candidates`）、`session-ambiguous`（多条命中，附 `candidates`）、`session-not-found`、`session-busy`、`session-writer-held`（会话被别的写入方占用）、`session-archived`、`session-not-accepted`（仅当 prompt **未被接受**）、`session-timeout`、`session-cancel-refused`（取消会话目标默认被拒，需 `--force`）。
+
+## 反向通道：让 DSH 调用 Codex
+
+上面的链路都是 **Codex → DSH**。反过来的 **DSH → Codex** 也能做，但要分清两种含义：
+
+| 含义 | 可行性 |
+|---|---|
+| 让 DSH 调用 Codex（把 Codex 当执行器/评审员） | ✅ 两端原生支持，见下 |
+| 让 DSH 往你**正开着的某条 ChatGPT/Codex 对话**里插一条消息、就地开一轮 | ❌ 做不到 |
+
+第二种做不到的原因：现有链路是 Codex 主动（它启动 `dsh-mcp` 子进程调工具），而 MCP 是
+**客户端发起**的协议——服务端无法命令客户端开一轮。服务端→客户端只有 `notifications/*`
+（纯通知，不触发回合）、`sampling/createMessage`、`elicitation/create`（取决于客户端是否
+实现，且不等于"在对话里跑工具"）；ChatGPT 侧同样没有公开 API 能向用户会话投消息。
+
+### 方案 A：反向通道已内置在本包里（推荐）
+
+**装本包就同时得到两个方向**——`cordis.patch.yml` 里插了两行：`dsh-bridge`（Codex → DSH 派活）与 `codex-mcp`（DSH → Codex 反向调用）。原理是两端各有一个原生件：
+
+- DSH 侧 `@deepseek-ai/dsh-mcp-client`（harness 自带）：连外部 MCP 服务器，并把工具以 `mcp__<serverName>__<tool>` 注册进 `ctx.tools`；
+- Codex 侧 `codex mcp-server`（stdio）：把 Codex 暴露成 MCP 服务端。
+
+内置的那一行等价于：
+
+```yaml
+- insert:
+    - id: codex-mcp
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: codex
+        transport: stdio
+        command: codex                 # 跨平台：SDK 用 cross-spawn，Windows 的 .cmd 垫片也能解析
+        args: ['mcp-server']
+        failOnStartupError: false      # 没装/没登录 Codex 只是没这批工具，不会拖垮 harness
+        toolCallTimeoutMs: 600000      # 默认只有 60s，Codex 跑一轮常常不够
+```
+
+- 前提：本机装了 Codex CLI 并已登录（`codex --version` / `codex mcp-server --help` 能跑）。
+- **不需要反向通道**？在 profile 的 `cordis.patch.yml` 里覆盖一行即可关掉：`- id: codex-mcp` + `disabled: true`。
+- 想单独用反向通道（不装本插件主体）可以用独立模板 [`templates/codex-mcp/`](templates/codex-mcp/README.md)。
+- 装完需**重启 profile 进程**；连接失败只是这批工具不出现（日志里有原因）。
+- 排查：若 `codex` 不在 DSH 进程的 PATH 上，把 `command` 换成 `node` + `args: ['<...>/@openai/codex/bin/codex.js', 'mcp-server']`，或直接指向平台 `codex.exe`。
+
+### 方案 B：worker 里直接跑 `codex exec`
+
+```powershell
+codex exec "把刚才的 diff 审一遍，只回结论" --cd E:\proj
 ```
 
-失败一律返回稳定 `reason` 且**不创建任何会话/工作区**：`session-query-empty`（没命中）、`session-ambiguous`（多条命中，附 `candidates`）、`session-not-found`、`session-busy`、`session-writer-held`（会话被别的写入方占用）、`session-archived`、`session-not-accepted`、`session-timeout`、`session-cancel-refused`（取消会话目标默认被拒，需 `--force`）。
+一次性、零协议改动；代价是每次都是新会话（无跨轮记忆），且需要执行 shell 的权限。
+
+> 注意：插件自带的 `dsh_collab_send` / `dsh_collab_review` 是 **DSH 侧入口**，只回到同一个网关，**不经过 Codex**。要"叫 Codex 干活"用上面 A/B；要"让 Codex 那条对话继续"，只能等 Codex 自己下一轮（`dsh_task --wait` 或 `dsh_task_status`）。
 
 ## 环境变量
 
 | 变量 | 默认 | 说明 |
 |---|---|---|
-| `DSH_BRIDGE_URL` | `http://127.0.0.1:3080` | 网关地址 |
+| `DSH_BRIDGE_URL` | `http://127.0.0.1:3080` | 网关地址。**必须指向插件实际挂载的那个 profile 的端口**（DSH 客户端里就是 GUI 端口，例如 19387） |
 | `DSH_BRIDGE_WORKSPACE` | `D:\Harness` | 网关默认共享工作目录 |
 | `DSH_BRIDGE_ROOT` | `D:\Harness` | `dsh_read_file` 相对路径基准 |
 | `DSH_BRIDGE_HISTORY` | 多级降级 | 协作历史文件位置（默认 D 盘 → 用户目录 → 临时目录逐级降级） |
@@ -211,12 +327,26 @@ dsh-task --in "<继续推进的指令>" --session "session-8d481ad9-..."
 - **评审不支持会话目标**：评审员必须与编码会话隔离，"独立评审"才成立
 - session 目标不使用 `cwd`/`lane`/`model`/`--commit`（会话自带这些语义），传了会被判 `invalid-target`
 - 网关重启会丢失内存中的任务表（含 session 观察器），这是既有设计
+- **替换包内容不会热重载**：升级后必须重启 profile 进程，否则跑的还是旧 JS 模块（HMR 只重挂组合，不复用新代码）
+- **组合包被取消选中 = 插件完全不挂载**：此时所有 `/api/dsh-bridge/*` 都落到网关鉴权层返回 401（不是 404，容易误判成没装）
 - **DSH profile 的 pnpm 供应链冷却**：新发布的版本约 24 小时内会被 `minimumReleaseAge` 拒绝安装（`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`）；管理器会把它写进 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 才放行。刚发版就装不上属正常，不是包的问题
-- 升级已装组合包 = **卸载 → 重新安装**；卸载会把该包从 `dsh.profile.bundles` 移除，所以重装后**要确认它被重新选中**，否则插件不会挂载（表现为所有 `/api/dsh-bridge/*` 都落到网关鉴权层返回 401）
+- 升级已装组合包：客户端插件页没有升级入口，官方姿势是**卸载 → 重装**；但卸载会把该包从 `dsh.profile.bundles` 移除，重装后**要确认它被重新选中**，否则插件不会挂载（表现为所有 `/api/dsh-bridge/*` 都落到网关鉴权层返回 401）。更省事的做法是直接 `dsh plugin add <包>@<版本>`，见上文「升级到新版本」
 - Codex Desktop Windows 本地市场技能注入 bug（见上，MCP 通道不受影响）
 - 动态插件环境无 `AbortSignal`，冷恢复失败时自动降级为一次性执行；宿主组合持久化版无此问题
 - ChatGPT Plus 写入型 MCP 的开放度取决于 OpenAI 产品策略
 
+## 开发与测试
+
+```sh
+node test/session-target.test.mjs      # 纯函数：目标判定 / 候选挑选 / 错误映射 / 基线切分 / 汇报选文
+node test/dsh-bridge.test.mjs          # 路由级：假 DSH 运行时 + 桩 peer，加载真实 bridge 跑真实路由
+node --test test/*.test.mjs            # 两个一起跑（CI 用的是这条）
+```
+
+- 路由级测试会断言 **worker 分支确实调用了 `startContinuable`**、**session 分支只调用 `prompt` 且不建 owner/子代理**——这类"参数遮蔽/串线"缺陷只有在这一层才抓得到（v0.1.2~0.1.4 的 `deliver` 遮蔽 bug 就是它抓回来的）。
+- CI（`.github/workflows/publish.yml`）每次 tag 都跑：语法检查 → 单测 → 包契约 → 版本号三处一致 → tarball 清单 → 干净目录安装 + CLI/MCP 冒烟 → 6 工具握手断言 → bridge 导出契约。**任何一步失败都不会发布**。
+- 发布：`package.json` / `.codex-plugin/plugin.json` / `mcp/dsh-mcp.mjs` 的 `SERVER_VERSION` 三处同步改版本 → commit → 打 tag `vX.Y.Z` → 推 tag，CI 自动带 provenance 发布。
+
 ## License
 
 MIT

package/codex-plugin/plugins/dsh/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Codex 主导的双向编码协作插件：ChatGPT 把编码任务下发给本机 DeepSeek Harness 的持久编码子代理执行，DeepSeek 在共享工作目录 D:\\Harness 中写代码并实时回传进度与汇报，Codex 读文件验收、反馈修正，直到通过。",
   "author": {
     "name": "FuJackGao"

package/codex-plugin/plugins/dsh/skills/dsh-collab/SKILL.md

@@ -30,10 +30,17 @@ description: "与 DeepSeek Harness 编码协作。当用户要写代码、建项
 ## 找到已有会话（只读，不创建任何东西）
 
 ```bash
-dsh-task --sessions "<标题或内容关键词>"
+dsh-task --sessions "<标题或内容关键词>"          # 只读列出候选
+dsh-task --dry-run --find "<标题关键词>"          # 只解析目标、回显命中结果，不投递
 ```
 
-输出候选（`sessionId` + 片段）。**必须唯一命中**才能直接用；多条会返回 `candidates` 让你改用 `--session <id>`。退出码 `4` = 没命中或不唯一。
+输出候选（`sessionId` + 片段）。**必须唯一命中**才能直接用；多条会返回 `candidates` 让你改用 `--session <id>`。
+
+没命中时会额外给出 `candidates`（按标题相似度 + 最近更新排序）——**换词重查，或直接确认用户指的是哪一条**。
+
+> ⛔ **绝不投递任何消息来"验证命中"**（例如发一条「占位/测试/忽略本条」）。真实事故：调用方搜不到标题后发了条占位消息试探，它解析成了用户自己的会话，于是**作为一条真实用户消息落进对话并跑成回合**，会话里的 agent 还以为那是用户发的。验证命中只有两种合法手段：上面的 `--sessions` 和 `--dry-run`。
+>
+> ⛔ **看到 `delivered: true` 就不要重发**。它表示 prompt 已被那条会话接受、进了它的队列；我们只是没等到它开跑（会话可能正忙着一个很长的回合）。重发会让同一份内容在用户会话里出现两次。用 `--status <taskId>` 继续观察。
 
 ## 下发任务
 

package/codex-plugin/plugins/dsh/skills/dsh-collab/scripts/task.mjs

@@ -41,6 +41,7 @@ function parseArgs(argv) {
     else if (a === '--session') { out.sessionId = argv[++i] || '' }
     else if (a === '--find') { out.find = argv[++i] || '' }
     else if (a === '--steer') { out.steer = true }
+    else if (a === '--dry-run') { out.dryRun = true }
     else if (a === '--force') { out.force = true }
     else { rest.push(a) }
   }
@@ -175,22 +176,53 @@ async function main() {
     }
     console.log(JSON.stringify(res.json, null, 2))
     const items = Array.isArray(res.json.items) ? res.json.items : []
+    if (items.length === 0 && Array.isArray(res.json.candidates) && res.json.candidates.length > 0) {
+      console.error('未命中。候选（改用 --session <id>，或换个关键词）:')
+      for (const c of res.json.candidates) console.error('  ' + c.sessionId + '  ' + c.snippet + (c.score === undefined ? '' : '  score=' + c.score))
+      console.error('提示: 验证命中用 --dry-run，不要投递消息去试探。')
+    }
     finish(items.length > 0 ? 0 : 4)
   }
 
   const instruction = opts.instruction.trim()
+  const cwd = (opts.cwd || process.env.DSH_BRIDGE_CWD || '').trim()
+  const sessionId = (opts.sessionId || '').trim()
+  const find = (opts.find || '').trim()
+  const sessionTarget = sessionId !== '' ? { sessionId } : (find !== '' ? { sessionQuery: find } : null)
+
+  // --dry-run：只解析目标、回显命中结果，什么都不投递。验证"这条查询会命中哪条会话"就用它，
+  // 绝不要投递一条消息去试探（那会落进用户会话并跑成回合，污染对话）。
+  if (opts.dryRun) {
+    if (instruction === '' && sessionTarget === null && cwd === '') {
+      console.error('用法: node task.mjs --dry-run (--find "<标题关键词>" | --session <会话id> | --cwd <目录>)')
+      finish(2)
+    }
+    const res = await request('POST', GATEWAY + '/api/dsh-bridge/task', {
+      instruction: instruction === '' ? '(dry-run)' : instruction,
+      dryRun: true,
+      ...(sessionTarget === null ? (cwd ? { cwd } : {}) : sessionTarget),
+    })
+    console.log(JSON.stringify(res.json, null, 2))
+    if (res.json === null || typeof res.json !== 'object') finish(1)
+    if (res.json.resolved !== true) {
+      if (Array.isArray(res.json.candidates) && res.json.candidates.length > 0) {
+        console.error('未命中。候选（改用 --session <id>，或换个关键词）:')
+        for (const c of res.json.candidates) console.error('  ' + c.sessionId + '  ' + c.snippet + (c.score === undefined ? '' : '  score=' + c.score))
+      }
+      finish(4)
+    }
+    finish(0)
+  }
+
   if (!instruction) {
     console.error('用法: node task.mjs --in "<指令>" [--cwd 目录] [--lane 名] [--model fast|pro] [--commit] [--timeout 秒] [--no-wait]')
     console.error('      node task.mjs --in "<指令>" (--session <会话id> | --find "<标题关键词>") [--steer]   # 投递进已有会话')
     console.error('查找: node task.mjs --sessions "<标题关键词>"   # 只读列出候选, 拿 sessionId 再派活')
+    console.error('      node task.mjs --dry-run (--find "<关键词>" | --session <id>)   # 只解析目标, 不投递（验证命中用这个）')
     console.error('管理: node task.mjs --list | --status <taskId> | --cancel <taskId> [--force]')
     console.error('退出码: 0 成功 / 1 失败 / 2 用法 / 3 超时 / 4 会话未命中或不唯一 / 5 session 目标取消被拒')
     finish(2)
   }
-  const cwd = (opts.cwd || process.env.DSH_BRIDGE_CWD || '').trim()
-  const sessionId = (opts.sessionId || '').trim()
-  const find = (opts.find || '').trim()
-  const sessionTarget = sessionId !== '' ? { sessionId } : (find !== '' ? { sessionQuery: find } : null)
   if (sessionTarget !== null && (cwd !== '' || opts.commit)) {
     console.error('task.mjs: --session/--find 不能与 --cwd/--commit 同时使用（已有会话自带工作目录，本工具不替它提交）')
     finish(2)
@@ -246,6 +278,11 @@ async function main() {
       console.log(JSON.stringify({ phase: 'finished', ...status }))
       console.log('=== DeepSeek 汇报 ===')
       console.log(status.result || status.error || '(无内容)')
+      // delivered=true 表示 prompt 已被那条会话接受（进了它的队列）：即便我们等超时了，
+      // 消息也可能会跑，**不要重发**（重发会让同一份内容在用户会话里出现两次）。
+      if (status.status === 'error' && status.delivered === true) {
+        console.error('注意: 消息已投递进该会话的队列（delivered=true），只是我们没等到它开跑。不要重发；可用 --status ' + task.taskId + ' 继续观察。')
+      }
       if (status.status === 'done') {
         // session 目标的记忆就在那条会话里，不再往协作历史里塞一份。
         if (sessionTarget === null) {

package/cordis.patch.yml

@@ -1,20 +1,45 @@
-# DSH Collab bundle layer — 双向编码协作网关。
+# DSH Collab bundle layer —— 双向协作：Codex → DSH 派活 + DSH → Codex 反向调用。
 #
 # 安装（npm）：
-#   dsh plugin --profile web add @whaletalk/dsh-codex-collab
-# `dsh plugin add` 会把本包加入 profile 的 dsh.profile.bundles，并自动套用本
-# patch，无需手工复制 dsh-bridge.mjs。
+#   dsh plugin --profile desktop add @whaletalk/dsh-codex-collab
+# `dsh plugin add` 会把本包加入 profile 的 dsh.profile.bundles，并自动套用本 patch。
 #
-# 下面这一行把宿主网关插件插进 bundle：
-#   - id  dsh-bridge       —— 行 id。用户的 patch 层可用同 id 覆盖整段 config。
-#   - name用包子路径而非相对路径（对比 './dsh-bridge.mjs'）：只有这样从 npm 安装
-#     后解析器才能定位到包内文件，同时保持 profile 目录干净。
+# 本 bundle 插两行：
 #
-# 依赖的服务：webServer / agents / subagents / tools 四个注入，加上运行时取用的
-# timer、sessionQuery、agentPresets、sessionPersistence、workspaceRegistry、llm。
-# 其中 webServer 由 dsh-web-app 提供 —— 因此本 bundle 只能挂 web / desktop
-# profile，headless profile 没有该服务会一直 pending。
-# 本插件不使用 workflowEngine，所以 web GUI 默认禁用 workflow 引擎不影响它。
+# 1) dsh-bridge —— 宿主网关插件（Codex → DSH 的派活通道）
+#    - id  行 id；用户的 patch 层可用同 id 覆盖整段 config。
+#    - name 用包子路径而非相对路径（对比 './dsh-bridge.mjs'）：只有这样从 npm 安装
+#      后解析器才能定位到包内文件，同时保持 profile 目录干净。
+#    依赖的服务：webServer / agents / subagents / tools 四个注入，加上运行时取用的
+#    timer、sessionQuery、agentPresets、sessionPersistence、workspaceRegistry、llm。
+#    其中 webServer 由 dsh-web-app 提供 —— 因此本 bundle 只能挂 web / desktop
+#    profile，headless profile 没有该服务会一直 pending。
+#    本插件不使用 workflowEngine，所以 web GUI 默认禁用 workflow 引擎不影响它。
+#
+# 2) codex-mcp —— 反向通道（DSH → Codex）
+#    把 Codex CLI 当 MCP 服务端挂进来：DSH 侧 agent 会拿到 mcp__codex__* 工具，
+#    可以把活交回 Codex。两端都是现成的（DSH 自带 @deepseek-ai/dsh-mcp-client，
+#    Codex 自带 `codex mcp-server`），这里只是配置。
+#
+#    - command 写裸名 `codex` 即可跨平台：MCP SDK 的 stdio 用 cross-spawn
+#      （shell:false）spawn，它在 Windows 上会正确解析 npm 的 .cmd 垫片。
+#      若你的 codex 不在 PATH 上，改成 `node` + args 指向
+#      `...\@openai\codex\bin\codex.js`，或直接指向平台 codex.exe。
+#    - toolCallTimeoutMs 默认只有 60s，Codex 跑一轮读仓库常常不够。
+#    - failOnStartupError:false：没装/没登录 Codex 时只是这批工具不出现并记一条
+#      日志，不会拖垮 harness。
+#    - 不需要反向通道？在 profile 的 cordis.patch.yml 里加一行覆盖即可关掉：
+#        - id: codex-mcp
+#          disabled: true
 - insert:
     - id: dsh-bridge
-      name: '@whaletalk/dsh-codex-collab/bridge'
+      name: '@whaletalk/dsh-codex-collab/bridge'
+    - id: codex-mcp
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: codex
+        transport: stdio
+        command: codex
+        args: ['mcp-server']
+        failOnStartupError: false
+        toolCallTimeoutMs: 600000

package/harness/dsh-bridge.mjs

@@ -32,6 +32,7 @@ import {
   mapControllerError,
   sessionTitleOf,
   looksLikeDisabledSearch,
+  rankTitleCandidates,
   taskResponse,
 } from './session-target.mjs'
 
@@ -449,6 +450,33 @@ export async function apply(ctx) {
     }
   }
 
+  /**
+   * 查询没命中时给的"近似候选"：读 list（不激活 Agent、不开索引），按 bigram 相似度
+   * 与最近更新排序。存在的意义是**不给"探测"留动机**——真实事故里调用方搜不到标题后
+   * 发了一条占位消息去试探，那条消息落进用户会话并跑成回合。有了候选，只读就能改词重查。
+   */
+  const sessionNearMisses = async (query, limit = 5) => {
+    const controller = sessionControllerNow()
+    if (controller === undefined) return []
+    try {
+      const value = await controller.list({}, signalOf())
+      const items = value !== undefined && value !== null && Array.isArray(value.items) ? value.items : []
+      const summaries = []
+      for (const summary of items) {
+        if (summary === null || typeof summary !== 'object' || typeof summary.sessionId !== 'string') continue
+        summaries.push({
+          sessionId: summary.sessionId,
+          title: sessionTitleOf(summary),
+          updatedAt: typeof summary.updatedAt === 'number' ? summary.updatedAt : 0,
+        })
+      }
+      return rankTitleCandidates(query, summaries, limit)
+    } catch (e) {
+      console.error('[dsh-bridge] near-miss lookup failed:', errText(e).slice(0, 200))
+      return []
+    }
+  }
+
   /** 只读解析：query → search 选一；sessionId → 直接用。任何不确定性都返回 reason。 */
   const resolveSessionTarget = async (target) => {
     const controller = sessionControllerNow()
@@ -467,7 +495,13 @@ export async function apply(ctx) {
       }
     }
     const picked = selectSession(hits, target)
-    if (!picked.ok) return picked
+    if (!picked.ok) {
+      // 查询落空不是"死路"：附上近似候选，调用方只读就能改词重查（别再发消息探测）。
+      if (picked.reason === REASONS.QUERY_EMPTY) {
+        return { ...picked, candidates: await sessionNearMisses(target.query) }
+      }
+      return picked
+    }
     let result
     try {
       result = await controller.resolveAgent(picked.sessionId)
@@ -494,6 +528,7 @@ export async function apply(ctx) {
     if (fields.error !== undefined) task.error = fields.error
     if (fields.reason !== undefined) task.reason = fields.reason
     if (fields.stopReason !== undefined) task.stopReason = fields.stopReason
+    if (fields.delivered !== undefined) task.delivered = fields.delivered
     pushTask(task.taskId, status === 'done' ? 'result' : 'error', {
       ...(task.result === undefined ? {} : { text: task.result }),
       ...(task.error === undefined ? {} : { error: task.error }),
@@ -603,6 +638,8 @@ export async function apply(ctx) {
       sessionId: resolved.sessionId, taskId: task.taskId, deliver, baseline,
       total: '', sawRunning: false, activeSince: Date.now(), startedAt: Date.now(),
       settled: false, abort: undefined, watcher: 'pending',
+      // prompt 被接受 = 消息已进会话队列。此后就不该再把它当"没发出去"（见 sweepSessionTargets）。
+      delivered: false, queuedNoted: false,
     }
     sessionTargets.set(resolved.sessionId, record)
 
@@ -635,7 +672,9 @@ export async function apply(ctx) {
     }
 
     watchSessionTask(record)
-    pushTask(task.taskId, 'task-accepted', { target: { kind: 'session', sessionId: resolved.sessionId }, deliver, cwd: resolved.snippet })
+    record.delivered = true
+    task.delivered = true
+    pushTask(task.taskId, 'task-accepted', { target: { kind: 'session', sessionId: resolved.sessionId }, deliver, cwd: resolved.snippet, delivered: true })
     return { task, failed: null }
   }
 
@@ -770,16 +809,39 @@ export async function apply(ctx) {
           }
         } catch (e) { /* 读不到就下一轮再试 */ }
       }
+      // 派发超时只在"prompt 没被接受"时才算失败。
+      // queue 模式下 prompt 被接受就意味着消息已进队列，会在会话空闲时跑；此时报 error
+      // 是误报——实测会话正跑一个 38 分钟的回合，排队等待远超 120s 完全正常，而误报会
+      // 直接诱导调用方重发（真实事故：同一条汇报被投了两次）。所以这里只记一条 note，
+      // 继续等，由下面的总预算兜底。
       if (!record.sawRunning && now - record.startedAt > SESSION_DISPATCH_TIMEOUT_MS) {
-        settleSessionTask(record, 'error', { error: 'the session never started a turn after the prompt was accepted (it may still be queued)', reason: REASONS.NOT_ACCEPTED })
-        continue
+        if (record.delivered === true) {
+          if (record.queuedNoted !== true) {
+            record.queuedNoted = true
+            pushTask(record.taskId, 'note', {
+              note: 'QUEUED',
+              text: 'prompt 已被接受并进入该会话队列，等它空闲时会跑；不要重发',
+              target: { kind: 'session', sessionId: record.sessionId },
+              delivered: true,
+            })
+          }
+        } else {
+          settleSessionTask(record, 'error', { error: 'the session never accepted the prompt', reason: REASONS.NOT_ACCEPTED, delivered: false })
+          continue
+        }
       }
       if (record.sawRunning && record.activeSince > 0 && now - record.activeSince > SESSION_QUIET_TIMEOUT_MS) {
         finishSessionTask(record, 'quiet-timeout')
         continue
       }
       if (now - record.startedAt > SESSION_TOTAL_TIMEOUT_MS) {
-        settleSessionTask(record, 'error', { error: 'session task exceeded its total budget', reason: REASONS.TIMEOUT })
+        settleSessionTask(record, 'error', {
+          error: record.delivered === true
+            ? 'prompt 已投递进该会话队列，但预算内它始终没有开始这一轮（会话可能一直在忙，或未被激活）；不要重发，可用 status 继续观察'
+            : 'session task exceeded its total budget before the prompt was accepted',
+          reason: REASONS.TIMEOUT,
+          delivered: record.delivered === true,
+        })
       }
     }
   }
@@ -851,14 +913,55 @@ export async function apply(ctx) {
       const parsed = await readJsonBody(req, res)
       if (parsed === null) return
       const instruction = parsed !== null && typeof parsed === 'object' && typeof parsed.instruction === 'string' ? parsed.instruction : ''
-      if (instruction.trim() === '') { sendJson(res, 400, { error: 'missing instruction' }); return }
+      const dryRun = parsed !== null && typeof parsed === 'object' && parsed.dryRun === true
+      if (!dryRun && instruction.trim() === '') { sendJson(res, 400, { error: 'missing instruction' }); return }
       const classified = classifyTarget(parsed)
       if (!classified.ok) { sendJson(res, 400, { error: classified.message, reason: classified.reason }); return }
+      // dryRun：只解析目标、回显它，**不投递任何东西**。存在的意义是让"我这条查询会命中
+      // 哪条会话"能纯只读地问出来——真实事故里调用方就是因为没法先验证，才发了一条占位
+      // 消息去探测，结果污染了用户会话。
+      if (dryRun) {
+        if (classified.target.kind === 'session') {
+          const resolved = await resolveSessionTarget(classified.target)
+          if (!resolved.ok) {
+            sendJson(res, 200, {
+              dryRun: true,
+              resolved: false,
+              reason: resolved.reason,
+              error: resolved.message,
+              ...(Array.isArray(resolved.candidates) && resolved.candidates.length > 0 ? { candidates: resolved.candidates } : {}),
+            })
+            return
+          }
+          sendJson(res, 200, {
+            dryRun: true,
+            resolved: true,
+            wouldDispatch: true,
+            target: { kind: 'session', sessionId: resolved.sessionId, deliver: classified.deliver },
+            ...(resolved.snippet === undefined ? {} : { snippet: resolved.snippet }),
+            ...(resolved.matchedBy === undefined ? {} : { matchedBy: resolved.matchedBy }),
+            ...(resolved.candidates.length > 0 ? { candidates: resolved.candidates } : {}),
+            note: '只解析目标，未投递任何消息',
+          })
+          return
+        }
+        const cwd = normalizeCwd(classified.target.cwd)
+        const lane = normalizeLane(classified.target.lane)
+        sendJson(res, 200, {
+          dryRun: true,
+          resolved: true,
+          wouldDispatch: true,
+          target: { kind: 'worker', cwd, lane },
+          note: '只解析目标，未派活',
+        })
+        return
+      }
       const task = await enqueue(instruction, parsed.history, classified.target, parsed.model, 'task', classified.deliver, classified.notes)
       if (task.status === 'error') {
         sendJson(res, 400, {
           error: task.error,
           reason: task.reason,
+          ...(task.delivered === true ? { delivered: true } : {}),
           ...(Array.isArray(task.candidates) && task.candidates.length > 0 ? { candidates: task.candidates } : {}),
         })
         return
@@ -939,7 +1042,18 @@ export async function apply(ctx) {
             }
           }
         }
-        sendJson(res, 200, { items, hasMore: hits.length > items.length, total: hits.length, matchedBy: found.matchedBy })
+        // 没命中不是死路：给近似候选（同一批只读数据，按相似度 + 最近更新排序），
+        // 让调用方改词重查——而不是发一条消息去"探测命中"。
+        const candidates = hits.length === 0 ? await sessionNearMisses(query, limit) : []
+        sendJson(res, 200, {
+          items,
+          hasMore: hits.length > items.length,
+          total: hits.length,
+          matchedBy: found.matchedBy,
+          ...(candidates.length > 0
+            ? { candidates, reason: REASONS.QUERY_EMPTY, note: '标题/目录里都没有这个关键词；candidates 是按相似度与最近更新排的候选，改词重查或直接用 sessionId' }
+            : {}),
+        })
       } catch (e) {
         sendJson(res, 502, { error: errText(e), reason: mapControllerError(e) })
       }
@@ -1042,6 +1156,8 @@ export async function apply(ctx) {
           taskId: task.taskId, status: task.status, kind: task.kind, cwd: task.cwd, lane: task.lane,
           target: task.target, deliver: task.deliver, instruction: task.instruction.slice(0, 300),
           result: task.result, error: task.error, reason: task.reason, fallback: task.fallback,
+          // delivered=true 表示 prompt 已被会话接受（进了队列）——即便后面报错也不要重发。
+          ...(task.delivered === undefined ? {} : { delivered: task.delivered }),
           ...(task.matchedBy === undefined ? {} : { matchedBy: task.matchedBy }),
           ...(Array.isArray(task.candidates) && task.candidates.length > 0 ? { candidates: task.candidates } : {}),
           ...(record === undefined ? {} : { watcher: record.watcher, sawRunning: record.sawRunning }),
@@ -1143,24 +1259,48 @@ export async function apply(ctx) {
   // ---- 原生工具（宿主全局工具层）----
   ctx.effect(() => ctx.tools.register(defineTool({
     name: 'dsh_collab_send',
-    description: '向 Codex 协作频道发送一条编码指令。默认新建编码子代理在指定工作目录执行;给出 sessionId 或 sessionQuery 时改为投递进那一条已有会话(会话自带的对话与上下文)。指令用中文。',
+    description: '向 Codex 协作频道发送一条编码指令。默认新建编码子代理在指定工作目录执行;给出 sessionId 或 sessionQuery 时改为投递进那一条已有会话(会话自带的对话与上下文)。指令用中文。'
+      + '【硬规则】验证"这条查询会命中哪条会话"必须用 dryRun=true(只解析、不投递);**绝不投递任何消息去试探命中**——那会作为一条真实用户消息落进对方会话并跑成回合,污染对话。'
+      + '【硬规则】返回里 delivered=true 表示消息已被那条会话接受(进了它的队列),即便随后观察到超时或错误也**不要重发**,用 wait=false 记下 taskId 再查状态。'
+      + 'sessionQuery 落空时会返回 candidates(按标题相似度 + 最近更新排序),换词重查或改用 sessionId。',
     parameters: {
       instruction: { type: 'string', required: true, description: '要交给编码子代理执行的指令。' },
       cwd: { type: 'string', description: '工作目录(默认 ' + DEFAULT_WORKSPACE + ')。与 sessionId/sessionQuery 互斥。' },
       lane: { type: 'string', description: '并行通道名(默认 main,同目录不同 lane 并行)。' },
       model: { type: 'string', description: '模型别名: default | fast | pro。' },
       sessionId: { type: 'string', description: '已有会话 id:把指令投递进这条会话,而不是新建。' },
-      sessionQuery: { type: 'string', description: '按标题/内容搜索已有会话(唯一命中才生效,多条会返回候选)。' },
+      sessionQuery: { type: 'string', description: '按标题/内容搜索已有会话(唯一命中才生效,多条或落空会返回候选)。' },
       deliver: { type: 'string', description: "投递方式: queue(默认,排队) 或 steer(插入当前回合)。" },
+      dryRun: { type: 'boolean', description: '为 true 时只解析目标并回显(含 matchedBy 与候选),不投递任何消息——验证命中用它。' },
       wait: { type: 'boolean', description: '为 true 时等待结果(最长 15 分钟)。' },
     },
     output: { schema: { type: 'json' }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }] },
     async execute(args) {
       const classified = classifyTarget(args)
       if (!classified.ok) return { ok: false, reason: classified.reason, error: classified.message }
+      // dryRun：只解析目标、回显，不投递。给调用方一条"先验证命中"的正路，免得它发消息试探。
+      if (args.dryRun === true) {
+        if (classified.target.kind === 'session') {
+          const resolved = await resolveSessionTarget(classified.target)
+          if (!resolved.ok) {
+            return { ok: false, dryRun: true, resolved: false, reason: resolved.reason, error: resolved.message, ...(resolved.candidates.length > 0 ? { candidates: resolved.candidates } : {}) }
+          }
+          return {
+            ok: true, dryRun: true, resolved: true,
+            target: { kind: 'session', sessionId: resolved.sessionId, deliver: classified.deliver },
+            ...(resolved.snippet === undefined ? {} : { snippet: resolved.snippet }),
+            ...(resolved.matchedBy === undefined ? {} : { matchedBy: resolved.matchedBy }),
+            ...(resolved.candidates.length > 0 ? { candidates: resolved.candidates } : {}),
+            note: '只解析目标，未投递任何消息',
+          }
+        }
+        const cwd = normalizeCwd(classified.target.cwd)
+        const lane = normalizeLane(classified.target.lane)
+        return { ok: true, dryRun: true, resolved: true, target: { kind: 'worker', cwd, lane }, note: '只解析目标，未派活' }
+      }
       const task = await enqueue(args.instruction, undefined, classified.target, args.model, 'task', classified.deliver, classified.notes)
       if (task.status === 'error') {
-        return { ok: false, taskId: task.taskId, reason: task.reason, error: task.error, ...(task.candidates === undefined ? {} : { candidates: task.candidates }) }
+        return { ok: false, taskId: task.taskId, reason: task.reason, error: task.error, ...(task.delivered === true ? { delivered: true } : {}), ...(task.candidates === undefined ? {} : { candidates: task.candidates }) }
       }
       const brief = { taskId: task.taskId, status: task.status, ...taskResponse(task) }
       if (args.wait !== true || timer === undefined) {
@@ -1171,7 +1311,7 @@ export async function apply(ctx) {
         if (Date.now() - t0 > 900000) return { ...brief, status: task.status, result: task.result, note: 'wait 超时' }
         await timer.timeout(2500)
       }
-      return { ...brief, status: task.status, result: task.result, error: task.error, reason: task.reason }
+      return { ...brief, status: task.status, result: task.result, error: task.error, reason: task.reason, ...(task.delivered === true ? { delivered: true, resend: false } : {}) }
     },
   })))
 

package/harness/session-target.mjs

@@ -232,6 +232,54 @@ export const looksLikeDisabledSearch = (error) => {
   return /search is disabled/i.test(text)
 }
 
+/** 去空白后的字符 bigram 集合（CJK 友好：不需要分词）。 */
+const bigramsOf = (value) => {
+  const text = typeof value === 'string' ? value.replace(/\s+/g, '') : ''
+  const out = new Set()
+  if (text.length === 1) out.add(text)
+  for (let i = 0; i + 1 < text.length; i++) out.add(text.slice(i, i + 2))
+  return out
+}
+
+/** 查询里的 bigram 有多少比例出现在标题里（0..1）。 */
+export const titleSimilarity = (query, title) => {
+  const q = bigramsOf(query)
+  const t = bigramsOf(title)
+  if (q.size === 0 || t.size === 0) return 0
+  let shared = 0
+  for (const gram of q) if (t.has(gram)) shared++
+  return shared / q.size
+}
+
+/**
+ * `session-query-empty` 时给出的"近似候选"。
+ *
+ * 起因是一个真实事故：调用方搜「量化框架」没命中，又**没有别的办法确认标题**，于是
+ * 发了一条占位消息去"探测命中"——那条消息落进了用户自己的会话并跑成回合，污染了
+ * 对话。修法是不给"探测"留动机：查询落空时直接回一批候选标题（同 bigram 相似度排
+ * 序，无相似度的按最近更新补位），调用方靠只读信息就能改词重查。
+ */
+export const rankTitleCandidates = (query, summaries, limit = 5) => {
+  const list = Array.isArray(summaries) ? summaries : []
+  const scored = []
+  for (const summary of list) {
+    if (summary === null || typeof summary !== 'object') continue
+    if (typeof summary.sessionId !== 'string' || summary.sessionId === '') continue
+    const title = typeof summary.title === 'string' && summary.title !== '' ? summary.title : ''
+    const updatedAt = typeof summary.updatedAt === 'number' ? summary.updatedAt : 0
+    scored.push({ sessionId: summary.sessionId, snippet: title, score: titleSimilarity(query, title), updatedAt })
+  }
+  const byRecency = (a, b) => b.updatedAt - a.updatedAt
+  const related = scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score || byRecency(a, b))
+  const rest = scored.filter((s) => s.score === 0).sort(byRecency)
+  const bound = Math.max(1, Math.min(Number(limit) || 5, MAX_CANDIDATES))
+  return [...related, ...rest].slice(0, bound).map((s) => ({
+    sessionId: s.sessionId,
+    snippet: s.snippet,
+    score: Math.round(s.score * 1000) / 1000,
+  }))
+}
+
 /** 任务在 HTTP 行上的回显：调用方一眼能看出这次是"新建"还是"接进哪个会话"。 */
 export const taskResponse = (task) => {
   const out = { taskId: task.taskId, status: task.status, kind: task.kind }
@@ -246,5 +294,10 @@ export const taskResponse = (task) => {
     out.target = { kind: 'worker', cwd: target.cwd, lane: target.lane }
   }
   if (Array.isArray(task.notes) && task.notes.length > 0) out.notes = task.notes
+  // delivered=true：prompt 已被目标会话接受（进了它的队列）。调用方据此知道
+  // "别重发"——即便随后我们的观察超时并报错，消息也可能正在队列里等着跑。
+  if (task.target !== undefined && task.target !== null && task.target.kind === 'session' && task.delivered === true) {
+    out.delivered = true
+  }
   return out
 }

package/mcp/dsh-mcp.mjs

@@ -6,7 +6,7 @@
 //      客户端（Secure MCP Tunnel / cloudflared）桥接给 ChatGPT 等远程产品。
 const GATEWAY = process.env.DSH_BRIDGE_URL || 'http://127.0.0.1:3080'
 const SERVER_NAME = 'dsh-bridge'
-const SERVER_VERSION = '0.1.5'
+const SERVER_VERSION = '0.1.7'
 const PROTOCOL_VERSION = '2024-11-05'
 
 const log = (...args) => console.error('[dsh-mcp]', ...args)
@@ -20,17 +20,20 @@ const tools = [
       '参数: instruction(必填,完整中文指令:目标/产出目录/验收标准/约束), cwd(工作目录,默认 D:\\Harness,通常传当前项目目录), ' +
       'lane(并行通道名,默认 main), model(fast=deepseek-v4-flash 快而省 / pro=deepseek-v4-pro 质量优先), ' +
       'sessionId(已有会话 id), sessionQuery(按标题/内容搜已有会话,需唯一命中,否则返回候选), deliver(queue=排队(默认) / steer=插入当前回合), ' +
-      'wait(默认 true,阻塞至任务完成并返回 DeepSeek 汇报), timeoutSec(默认 600,最长 900)。',
+      'dryRun(true 时只解析目标并回显, 不投递任何消息), ' +
+      'wait(默认 true,阻塞至任务完成并返回 DeepSeek 汇报), timeoutSec(默认 600,最长 900)。' +
+      '注意: 验证"这条查询会命中哪条会话"必须用 dryRun 或 dsh_sessions——**绝不要投递一条消息去试探**（那会污染用户会话）。',
     inputSchema: {
       type: 'object',
       properties: {
-        instruction: { type: 'string', description: '完整中文编码指令（目标、产出目录、验收标准、约束）。' },
+        instruction: { type: 'string', description: '完整中文编码指令（目标、产出目录、验收标准、约束）。dryRun 时可省略。' },
         cwd: { type: 'string', description: '工作目录（绝对路径）。默认 D:\\Harness。与 sessionId/sessionQuery 互斥。' },
         lane: { type: 'string', description: '并行通道名（默认 main）。' },
         model: { type: 'string', enum: ['fast', 'pro'], description: '模型别名：fast=deepseek-v4-flash，pro=deepseek-v4-pro。' },
         sessionId: { type: 'string', description: '已有会话 id：把指令投递进这条会话，而不是新建子代理。' },
-        sessionQuery: { type: 'string', description: '按标题或内容搜索已有会话；唯一命中才派发，多条会返回 candidates 让你改用 sessionId。' },
+        sessionQuery: { type: 'string', description: '按标题或内容搜索已有会话；唯一命中才派发，多条或落空会返回 candidates 让你改用 sessionId。' },
         deliver: { type: 'string', enum: ['queue', 'steer'], description: '投递方式：queue 排队（默认），steer 插入当前回合。' },
+        dryRun: { type: 'boolean', description: '只解析目标并回显（含命中路径 matchedBy 与候选），不投递任何消息。用来确认命中，替代"发消息探测"。' },
         wait: { type: 'boolean', description: '默认 true：阻塞直到任务完成并返回汇报。' },
         timeoutSec: { type: 'number', description: '最长等待秒数（默认 600，最大 900）。' },
       },
@@ -138,12 +141,19 @@ async function handleToolCall(name, args) {
       sessionId: args.sessionId,
       sessionQuery: args.sessionQuery,
       deliver: args.deliver,
+      dryRun: args.dryRun === true,
     })
+    // dryRun 只解析目标，不产生任务：原样回显给你看命中结果。
+    if (args.dryRun === true) return { ok: task.resolved === true, phase: 'dry-run', ...task }
     // 4xx 拒绝（缺目标 / 会话不存在 / 搜索结果不唯一 / 被写锁占用）不带 taskId，绝不静默新建。
     if (task.taskId === undefined) return { ok: false, phase: 'rejected', ...task }
     if (task.status === 'error') return { ok: false, ...task }
     if (args.wait === false) return { ok: true, phase: 'submitted', ...task }
     const done = await waitTask(task.taskId, args.timeoutSec || 600)
+    // 会话目标报错但 delivered=true：消息已在目标会话队列里，不要重发。
+    if (done.delivered === true && done.status === 'error') {
+      return { ok: false, phase: 'queued-then-failed', resend: false, ...done }
+    }
     return { ok: done.status === 'done', phase: 'finished', ...done }
   }
   if (name === 'dsh_sessions') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whaletalk/dsh-codex-collab",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Codex × DeepSeek Harness 双向编码协作：Codex 主导派活与验收，DeepSeek Harness 编码子代理在共享工作目录执行并回传，独立评审子代理实际跑通构建/测试后出具报告。提供 DSH 宿主网关插件、零依赖 MCP 服务器与 Codex 技能三件套。",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
     "harness/",
     "mcp/",
     "codex-plugin/",
+    "templates/",
     "cordis.patch.yml",
     "README.md",
     "LICENSE",

package/templates/codex-mcp/README.md

@@ -0,0 +1,84 @@
+# templates/codex-mcp —— 反向通道：让 DSH 调用 Codex
+
+> **注意：主包已内置这一行。** 装 `@whaletalk/dsh-codex-collab` 时会同时挂上
+> `dsh-bridge`（Codex → DSH 派活）和 `codex-mcp`（DSH → Codex），不需要再单独装。
+> 本目录是**独立版本**：只想用反向通道、或想单独调参时用。关掉内置的那一行只需在
+> profile 的 `cordis.patch.yml` 里覆盖 `- id: codex-mcp` + `disabled: true`。
+
+把 **Codex CLI 当作 MCP 服务端**挂进 DeepSeek Harness，于是 DSH 侧的 agent（包括
+本插件派出去的 worker）会拿到 `mcp__codex__*` 工具，可以把活**交回 Codex**。
+
+- DSH 侧负责连接的是 harness 自带的 `@deepseek-ai/dsh-mcp-client`（把外部 MCP
+  服务器的工具注册进 `ctx.tools`，支持 `stdio` 与 `streamable-http`，带断线重连）。
+- Codex 侧负责暴露的是 `codex mcp-server`（stdio）。
+
+## 装法
+
+**A. 并进你现有的 profile patch**（推荐，最少文件）：把 `cordis.patch.yml` 里那行
+`insert` 追加到 `~/.dsh/profiles/<profile>/cordis.patch.yml` 数组末尾。
+
+**B. 当作独立 bundle 安装**：
+
+```sh
+dsh plugin --profile desktop add "<本目录绝对路径>"
+```
+
+两种方式都一样：**装完必须重启 profile 进程**（新增组合包不会热挂载），
+重启后工具才会出现在列表里。
+
+## 配置要点
+
+| 字段 | 说明 |
+|---|---|
+| `serverName` | 工具命名空间，工具名形如 `mcp__codex__<tool>`；同时挂多个服务器时各自独立 |
+| `transport` | `stdio`（本地进程）或 `streamable-http`（远端） |
+| `command` / `args` / `env` / `cwd` | 仅 stdio：可执行文件、参数、追加环境变量、工作目录 |
+| `failOnStartupError` | `false` = 连不上也照常启动 harness，只是没有这批工具 |
+| `toolCallTimeoutMs` | 每次 `tools/call` 超时；**默认只有 60s**，Codex 跑一轮常常不够，建议 600000 |
+
+### `command` 怎么写（Windows 也能用裸名）
+
+**默认写裸名 `codex` 即可，跨平台。** DSH 的 MCP 客户端走官方 SDK 的
+`StdioClientTransport`，它内部用 **cross-spawn**（`shell: false`）spawn——cross-spawn
+在 Windows 上会正确解析 npm 的 `.cmd` 垫片。实测：
+
+```
+cross-spawn('codex', ['--version']) → exit 0, "codex-cli 0.147.0"
+```
+
+只有当 `codex` 不在 DSH 进程的 PATH 上（或你想完全绕开 npm 垫片）时才需要换写法：
+
+```yaml
+# 备选 1：node 跑垫片背后的 JS
+command: node
+args: ['C:\Users\<you>\AppData\Roaming\npm\node_modules\@openai\codex\bin\codex.js', 'mcp-server']
+
+# 备选 2：直接指向平台二进制（路径随版本/架构略有不同）
+command: 'C:\Users\<you>\AppData\Roaming\npm\node_modules\@openai\codex\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\bin\codex.exe'
+args: ['mcp-server']
+```
+
+## 验证
+
+```sh
+codex --version                 # 需要 CLI 已登录可用
+codex mcp-server --help         # 应打印 "Start Codex as an MCP server (stdio)"
+```
+
+接好后在 DSH 侧让 agent 调一次 `mcp__codex__*`；工具没出现就去看 harness 日志
+（连接失败会记录原因，且不会中止启动）。
+
+## 能做什么、不能做什么
+
+| | 可行性 |
+|---|---|
+| 让 DSH 调用 Codex（当执行器/评审员） | ✅ 本目录的做法 |
+| 让 DSH 往你**正开着的某条 ChatGPT/Codex 对话**里插消息、就地开一轮 | ❌ 做不到 |
+
+原因：现有链路是 Codex 主动（它启动 `dsh-mcp` 子进程调工具），MCP 是**客户端发起**
+的协议，服务端无法命令客户端开一轮；服务端→客户端只有 `notifications/*`（不触发
+回合）、`sampling/createMessage`、`elicitation/create`（取决于客户端实现，且不等于
+"在对话里跑工具"）。ChatGPT 侧同样没有公开 API 能向用户会话投消息。
+
+> 另注：本插件自带的 `dsh_collab_send` / `dsh_collab_review` 是 **DSH 侧入口**，
+> 它们只回到同一个网关，**不经过 Codex**。

package/templates/codex-mcp/cordis.patch.yml

@@ -0,0 +1,46 @@
+# 反向通道：把 Codex 挂成 DSH 的一个 MCP 服务端。
+#
+# 谁提供什么：
+#   - DSH 侧：@deepseek-ai/dsh-mcp-client（harness 自带）——连外部 MCP 服务器，
+#     并把它们的工具以 mcp__<serverName>__<tool> 注册进 ctx.tools。
+#   - Codex 侧：codex mcp-server（stdio）——把 Codex 暴露成 MCP 服务端。
+#
+# 用法（二选一）：
+#   A) 把下面这行 insert 追加到你的 profile cordis.patch.yml 数组末尾；
+#   B) 把本目录当作一个 bundle 安装（路径写绝对路径）：
+#        dsh plugin --profile <profile> add <本目录绝对路径>
+#
+# 注意：主包 @whaletalk/dsh-codex-collab 已内置等价的一行；本文件是**独立版本**，
+# 用于只想单独挂反向通道、或想单独调参的场景。
+#
+# 装完必须**重启 profile 进程**：新增组合包不会热挂载，只有重启后工具才会出现。
+# 之后在 DSH 侧的工具列表里找 mcp__codex__*（例如 mcp__codex__codex）。
+- insert:
+    - id: codex-mcp
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: codex
+        transport: stdio
+
+        # 裸名 `codex` 跨平台可用：DSH 的 MCP 客户端用官方 SDK 的
+        # StdioClientTransport，内部是 cross-spawn（shell:false），在 Windows 上
+        # 也能正确解析 npm 的 .cmd 垫片（本机实测 exit 0）。
+        command: codex
+        args: ['mcp-server']
+
+        # 若 codex 不在 DSH 进程的 PATH 上，改成下面任一种：
+        #   command: node
+        #   args: ['C:\Users\<you>\AppData\Roaming\npm\node_modules\@openai\codex\bin\codex.js', 'mcp-server']
+        # 或直接指向平台二进制：
+        #   command: 'C:\Users\<you>\AppData\Roaming\npm\node_modules\@openai\codex\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\bin\codex.exe'
+        #   args: ['mcp-server']
+
+        # 远端 Codex（有人把 mcp-server 包成 HTTP 时）用：
+        #   transport: streamable-http
+        #   url: http://127.0.0.1:3000/mcp
+        #   headers: { Authorization: 'Bearer ...' }
+
+        # 启动失败不拖垮 harness：插件仍激活，只是不注册这批工具，日志里有原因。
+        failOnStartupError: false
+        # Codex 一轮可能跑很久（要读完仓库再答），给足超时；默认只有 60s。
+        toolCallTimeoutMs: 600000

package/templates/codex-mcp/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "dsh-codex-mcp-bridge",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "把 Codex CLI 当作 MCP 服务端挂进 DeepSeek Harness：DSH 侧 agent 获得 mcp__codex__* 工具，可反向调用 Codex。",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}