tianshu-mcp 0.7.2 → 0.7.4

package/CHANGELOG.en.md

@@ -8,6 +8,96 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.7.4] - 2026-09-28
+
+### Fixed
+
+- **Project-scoped dispatch on ZCode 3.14.x always failed with `project_mismatch` (issue #24).**
+  ZCode 3.14.x removed the two DOM contracts tianshu-mcp used for **binding read-back**
+  (`data-project-path` and `data-testid^="workspace-item-"`), while `pathOf()` in
+  `src/agents/zcode/dom.ts:27` recognises nothing else — so `workspaceBinding().projectPath` was always
+  empty and `cdp.projects()` always returned `[]`, leaving the binding criterion unsatisfiable forever.
+  The failure happens **before the task brief is ever sent**, which made `autoFixRounds` inert
+  (`roundsUsed` stayed 0). The fix touches four places, all stemming from that one root cause:
+  - `selectors.ts:107` gains `projectMenuItem` (`[role="menuitemcheckbox"]`), and `projectItem` /
+    `projectPath` are now explicitly labelled as 3.11.x contracts;
+  - `workspaceBindingExpression()` in `dom.ts:38` now also returns `projectName` (the bound display name)
+    and `menuChecked` (display names of menu items with `aria-checked="true"`), treating multiple checked
+    items as ambiguity; it **never fabricates a path** — on 3.14.x `projectPath` stays an empty string, and
+    the decision layer uses that to distinguish evidence strength;
+  - `projects()` in `cdp.ts:279` falls back to harvesting the expanded menu **only when the old contracts
+    yield nothing**, and it includes the checked state and excludes "work outside a project", so the
+    3.11.x result is byte-for-byte unchanged;
+  - `matchZcodeProject()` in `project.ts:61` gains a **display-name exact-match** branch and reports
+    `matchedBy`; a new `boundProjectVerdict()` implements the layered criterion — **strict path equality
+    whenever a path is available (unchanged semantics), display name when there is no path channel** —
+    and requires the project list to be free of same-name ambiguity.
+- **Removed a fragile timing dependency**: `ensureProjectBound()` used to accept an externally supplied
+  item, which made "the menu happens to still be open" an implicit precondition. It is now an idempotent
+  self-check: read the verdict first, pass immediately when already bound, and only expand the menu and
+  click when it is not.
+- **Better failure diagnostics**: the `project_mismatch` message now carries the trigger text, the menu
+  checked state and the path read-back, so users are no longer left with a bare "read-back mismatch".
+- **On-device evidence entry point**: `scripts/probe-zcode.mjs` gains a `dom-contracts` subcommand that
+  reports hit counts for both legacy contracts, the trigger's full attributes, the menu item list and the
+  post-fix read-back — for re-checking this contract assumption against a real ZCode build.
+
+### Known limitation
+
+- The ZCode 3.14.x DOM exposes a project's **display name** but not its absolute path, so the criterion is
+  "display name + global same-name disambiguation": more than one same-name item yields
+  `project_ambiguous` (fail-closed). Disambiguation requires the menu to be expanded (that is `projects()`'
+  data source); with the menu closed only the `binding` display-name evidence is used, and a missing list
+  never negates a binding. The 3.11.x path-equality chain keeps the highest priority and is unchanged.
+
+### Tests
+
+- **14** new cases: 4 in `test/unit/zcode-dom.test.ts` (read-back contract under the missing 3.14.x
+  contracts, multi-check ambiguity, and no regression for 3.11.x), 6 in `test/unit/zcode-core.test.ts`
+  (display-name matching / same-name fail-closed / layered criterion / path priority), and 4 in
+  `test/integration/zcode-flow.test.ts` (already-bound dispatch without a stray click, switch-then-dispatch,
+  same-name ambiguity fail-closed, and a **counter-example** where missing display-name evidence still
+  fails closed with diagnostics). Full suite: **1383 passed / 12 skipped** (1395 tests, 115 files plus 3
+  real-browser files skipped by design).
+
+> **On-device verification boundary (disclosed honestly)**: this machine has **no ZCode 3.14.x**, so the fix
+> was not re-verified on hardware. The root cause (missing DOM contracts) is **deterministically reproducible
+> locally** against a `linkedom` fixture: the new cases were first written to show three failing assertions
+> (`projectName`/`menuChecked` absent, `projects()` empty, multi-check not treated as ambiguous) and then
+> driven to green. The on-device measurements reported in issue #24 (`data-project-path` 0 hits,
+> `workspace-item-` 0 hits, `menuitemcheckbox` intact) were **not independently reproduced**; the fix is
+> designed against those contracts. Maintainers with a 3.14.x environment should run
+> `npm run probe:zcode -- dom-contracts` to confirm.
+
+## [0.7.3] - 2026-09-28
+
+### Fixed
+
+- **Skill docs had drifted from the implementation** (`skills/tianshu-mcp/`):
+  - `usage-examples.md` carried a **duplicate `### 2.9`** (codex-cli and the shared-conventions section
+    collided) → the latter is now `### 2.10`;
+  - `SKILL.md` §9 did not state that its error-code table is a subset — `endReason` is typed as an optional
+    `string` (`src/agents/adapter.ts:93`) with **no enum constraint**, so an adapter can add a value without a
+    type change. The doc now says so, and points readers at the adapter's `run.ts` for unknown values;
+  - added three high-frequency `endReason` values that were missing from the table: `input_mismatch`
+    (a leftover draft makes the task land inside stale text), `send_unknown` (delivery unconfirmable —
+    **never resends**), and `reply_stable` (normal completion, not an error).
+
+### Docs
+
+- **Documented Open Design artifact retrieval** (a `v0.7.1` capability, previously absent from the skill):
+  designs live in the product's artifact store `<dataRoot>/projects/<projectId>/<entry>`, **not** in the
+  task directory; once terminal the adapter copies it into `projectPath`.
+- **Documented the daemon-readiness precondition**: the product completes an auth handshake with its daemon
+  before opening the folder picker (measured ~30s after launch); when unready the product **opens no dialog
+  at all**.
+- **Marked the `zip` export as a known limitation** (the product's main process takes over downloads,
+  overriding CDP's handling; the `html` path is fully working).
+
+> This release contains **no runtime code changes** (only `skills/` docs and the version bump), so upgrading
+> from `0.7.2` changes no behaviour; it syncs docs with implementation and aligns tag / Release / npm on a
+> single commit.
+
 ## [0.7.2] - 2026-09-28
 
 ### Fixed

package/CHANGELOG.md

@@ -7,6 +7,75 @@
 
 ---
 
+## [0.7.4] - 2026-09-28
+
+### 修复
+
+- **ZCode 3.14.x 有项目派单恒败于 `project_mismatch`（issue #24）**。ZCode 3.14.x 删除了 tianshu-mcp
+  用于**绑定回读**的两处 DOM 契约（`data-project-path` 与 `data-testid^="workspace-item-"`），而
+  `src/agents/zcode/dom.ts:27` 的 `pathOf()` 只认这两个来源 —— 于是 `workspaceBinding().projectPath`
+  恒为空、`cdp.projects()` 恒为 `[]`，绑定判据永不成立。失败发生在**发送任务书之前**，
+  `autoFixRounds` 形同虚设（`roundsUsed` 恒为 0）。修复落在四处（同一根因）：
+  - `selectors.ts:107` 新增 `projectMenuItem`（`[role="menuitemcheckbox"]`），并把 `projectItem` /
+    `projectPath` 显式标注为 3.11.x 契约；
+  - `dom.ts:38` 的 `workspaceBindingExpression()` 增补 `projectName`（当前绑定显示名）与 `menuChecked`
+    （菜单中 `aria-checked="true"` 的显示名），多勾选判歧义；**不伪造路径** —— 3.14.x 下 `projectPath`
+    仍为空串，判定层据此区分证据等级；
+  - `cdp.ts:279` 的 `projects()` 改为「旧契约完全落空时才从展开菜单采集」（含勾选态、排除
+    「不在项目中工作」），保证 3.11.x 的采集结果逐字不变；
+  - `project.ts:61` 的 `matchZcodeProject()` 增加**显示名精确匹配**分支并返回 `matchedBy`，
+    新增 `boundProjectVerdict()` 实现分层判据：**路径可得时严格判等（原语义不变），无路径渠道时按显示名**，
+    且要求项目列表无同名歧义。
+- **修掉一条被掩盖的脆弱时序**：`ensureProjectBound()` 原先接受外部传入的 item，使「菜单是否恰好还开着」
+  成为隐式前提。现改为幂等自检 —— 每轮先读判定，已绑定即通过、未绑定才展开菜单并点击。
+- **绑定失败诊断补齐**：`project_mismatch` 的错误信息现携带「触发器文本 / 菜单勾选态 / 路径回读」，
+  用户不必再面对一句「回读不一致」而无法自救。
+- **真机取证入口**：`scripts/probe-zcode.mjs` 新增 `dom-contracts` 子命令，输出两处旧契约的命中计数、
+  触发器全属性、菜单项清单与修复后的回读结果（用于在真实 ZCode 上复核本次契约假设）。
+
+### 已知限制
+
+- ZCode 3.14.x 的 DOM 只暴露项目**显示名**、不暴露绝对路径，因此判定采用「显示名 + 全局同名消歧」：
+  同名项 > 1 直接判 `project_ambiguous`（fail-closed）。**能区分的前提是菜单已展开**（`projects()` 的数据源）；
+  菜单收起时只凭 `binding` 的显示名证据，不因列表缺失而否定绑定。3.11.x 的路径判等链路优先级最高，行为不变。
+
+### 测试
+
+- 新增 **14** 用例：`test/unit/zcode-dom.test.ts` 4 条（3.14.x 契约缺席下的回读契约 + 多勾选歧义 +
+  3.11.x 无退化）、`test/unit/zcode-core.test.ts` 6 条（显示名匹配 / 同名 fail-closed / 分层判据 / 路径优先）、
+  `test/integration/zcode-flow.test.ts` 4 条（已绑定直发不误点、未绑定切换后派发、同名歧义 fail-closed、
+  **缺显示名证据的反例**：仍 fail-closed 且错误信息带诊断）。全量 **1383 passed / 12 skipped**
+  （1395 项，115 文件 + 3 个真实浏览器文件按设计 skip）。
+
+> **真机验证边界（如实披露）**：本机**无 ZCode 3.14.x**，未在真机复验。根因（DOM 契约缺席）在
+> `linkedom` 夹具上可**本地决定性复现**：先写用例确认 3 处红灯（`projectName`/`menuChecked` 缺失、
+> `projects()` 为空、多勾选不判歧义），再修到全绿。issue #24 报告的真机实测数据（`data-project-path`
+> 0 命中、`workspace-item-` 0 命中、`menuitemcheckbox` 完好）**未被独立复现**，修复按该契约设计；
+> 有 3.14.x 环境的维护者请跑 `npm run probe:zcode -- dom-contracts` 复核一次。
+
+## [0.7.3] - 2026-09-28
+
+### 修复
+
+- **skill 文档与实现脱节**（`skills/tianshu-mcp/`）：
+  - `usage-examples.md` 存在**两个 `### 2.9`**（codex-cli 与通用约定撞号）→ 后者改为 `### 2.10`；
+  - `SKILL.md` §9 的错误码表未声明「这是子集而非闭集」—— `endReason` 在类型层面只是可选
+    `string`（`src/agents/adapter.ts:93`），**没有枚举约束**，适配器新增分支无需改类型即可引入新取值。
+    现已显式声明，并提示读者遇到表外取值时去读对应适配器的 `run.ts`；
+  - 补入三个真机高频但表中缺失的 `endReason`：`input_mismatch`（输入框残留导致任务被插进残文）、
+    `send_unknown`（无法确认落地，**绝不重发**）、`reply_stable`（正常完成，非错误）。
+
+### 文档
+
+- **补写 Open Design 产物取回**（`v0.7.1` 起的能力，此前未进 skill 正文）：设计稿存在产品的产物存储
+  `<dataRoot>/projects/<projectId>/<entry>` 而**不在任务目录**，终态后由适配器复制到 `projectPath`。
+- **补写 daemon 就绪前置**：产品打开文件夹选择器前需与 daemon 完成鉴权握手（实测启动后约 30s 才驻留），
+  未就绪时产品**根本不弹对话框**。
+- **标注 `zip` 导出为已知限制**（产品主进程接管下载，CDP 接管被覆盖；`html` 路径完全可用）。
+
+> 本版**不含运行时代码变更**（仅 `skills/` 文档 + 版本号），从 `0.7.2` 升级无功能差异；
+> 发布目的是让文档与实现同步、并让 tag / Release / npm 收敛到同一 commit。
+
 ## [0.7.2] - 2026-09-28
 
 ### 修复

package/README.en.md

@@ -77,7 +77,7 @@ git clone https://github.com/lanlan0811/tianshu-mcp.git
 cd tianshu-mcp
 npm ci
 npm run build        # sync-version + tsc → dist/
-npm test             # 867 passed / 12 skipped (879 tests, 85 files: unit/integration/protocol plus 3 real-browser files skipped by design)
+npm test             # 1383 passed / 12 skipped (1395 tests, 115 files: unit/integration/protocol plus 3 real-browser files skipped by design)
 ```
 
 ### Install the npm package
@@ -494,7 +494,7 @@ Qoder CN uses `agentId="qoder"` and requires an existing `projectPath` plus a re
 | agentId | driver / adapter | status | Notes |
 |---|---|---|---|
 | `codex` | `gui` / `codex-gui` | **ready** (`research` on macOS) | Desktop GUI over CDP (Windows: MSIX COM activation; macOS: spawn .app binary + CDP); supports `model`/`reasoningLevel`/`planDoc`/`designSystem`; wait-user, cancel and dispatch-guard semantics machine-verified (v0.3.2); Windows machine-verified; macOS basic closed loop machine-verified (v0.4.0) — stays `research` until the cancel/rework matrix is covered |
-| `zcode` | `gui` / `zcode-gui` | **research** | CDP GUI adapter with the Windows hardware loop passed; adapted to ZCode 3.11.2 model menu and project binding (v0.3.3), with hardened project/model read-back and initialization recovery (v0.3.4); supports project-less dispatch and `allowCreateProject` (v0.5.2, issue #12), and v0.5.3 fixed instance survival across server exit, new-task page switching and send-failure attribution; macOS basic closed loop machine-verified (2026-09-13, v0.4.0) — stays `research` until the cancel/rework/new-project matrix is covered |
+| `zcode` | `gui` / `zcode-gui` | **research** | CDP GUI adapter with the Windows hardware loop passed; adapted to ZCode 3.11.2 model menu and project binding (v0.3.3), with hardened project/model read-back and initialization recovery (v0.3.4); supports project-less dispatch and `allowCreateProject` (v0.5.2, issue #12), and v0.5.3 fixed instance survival across server exit, new-task page switching and send-failure attribution; **v0.7.4 adapts to ZCode 3.14.x** (the product removed the `data-project-path` and `workspace-item-*` contracts, so the binding criterion is now "path first, display name plus global same-name disambiguation when no path channel exists", failing closed on ambiguity); macOS basic closed loop machine-verified (2026-09-13, v0.4.0) — stays `research` until the cancel/rework/new-project matrix is covered |
 | `traework` | `gui` / `traework-gui` | **ready** | CDP-driven TRAE SOLO CN desktop UI; all three panel modes machine-verified |
 | `kimicode` | `gui` / `kimicode-gui` | **ready** (`research` on macOS) | Kimi Code desktop (Electron, measured 1.0.2); **two renderer processes** (main window + `Kimi Browser Overlay` carrying the model/tier/mode menus); workspaces bind by full path and unregistered ones are imported through the native "add workspace" dialog; supports `model`/`reasoningLevel` and rejects `mode`; Windows machine-verified for the success path, unregistered-workspace import + auto-acceptance, and the failure → rework → re-acceptance same-session loop; cancellation/question answering are covered by hermetic integration tests only, and macOS stays `research` and fail-closed |
 | `qoder` | `gui` / `qoder-gui` | Windows real GUI loop passed; macOS **research** | Qoder CN only; full-path workspaces, unregistered directories imported via New Workspace + the native folder picker, default/custom models, global reasoning readback through Model Management, same-session answers and rework; Windows machine-verified for default-model development in an existing workspace, custom-model development in a newly imported workspace, and the controlled failure → plan → same-session repair → re-acceptance loop; macOS is `research` and fail-closed (dispatch disabled) |

package/README.md

@@ -77,7 +77,7 @@ git clone https://github.com/lanlan0811/tianshu-mcp.git
 cd tianshu-mcp
 npm ci
 npm run build        # sync-version + tsc → dist/
-npm test             # 867 passed / 12 skipped（879 项，85 个测试文件：单元/集成/协议 + 3 个真实浏览器文件按设计 skip）
+npm test             # 1383 passed / 12 skipped（1395 项，115 个测试文件：单元/集成/协议 + 3 个真实浏览器文件按设计 skip）
 ```
 
 ### 安装 npm 包
@@ -495,7 +495,7 @@ Qoder CN 使用 `agentId="qoder"`，必须提供已有 `projectPath` 和可读 `
 | agentId | driver / adapter | status | 说明 |
 |---|---|---|---|
 | `codex` | `gui` / `codex-gui` | **ready**（macOS 为 `research`） | Codex 桌面端 GUI（Windows：MSIX COM 激活 + CDP；macOS：spawn .app + CDP）；支持 `model`/`reasoningLevel`/`planDoc`/`designSystem`；等待用户确认、取消与重派护栏均已真机验证（v0.3.2）；Windows 真机已验证；macOS 基本闭环已真机验证（v0.4.0），取消/返修矩阵补齐前保持 `research` |
-| `zcode` | `gui` / `zcode-gui` | **research** | CDP GUI adapter 已实现且 Windows 真机闭环通过；已适配 ZCode 3.11.2 模型菜单与项目绑定（v0.3.3），并加固项目/模型回读与初始化恢复（v0.3.4）；支持无项目派发与 `allowCreateProject`（v0.5.2，issue #12），v0.5.3 修复实例跨 server 驻留、新建任务切页与发送失败归因；macOS 基本闭环已真机验证（2026-09-13，v0.4.0），取消/返修/新建项目矩阵补齐前保持 `research` |
+| `zcode` | `gui` / `zcode-gui` | **research** | CDP GUI adapter 已实现且 Windows 真机闭环通过；已适配 ZCode 3.11.2 模型菜单与项目绑定（v0.3.3），并加固项目/模型回读与初始化恢复（v0.3.4）；支持无项目派发与 `allowCreateProject`（v0.5.2，issue #12），v0.5.3 修复实例跨 server 驻留、新建任务切页与发送失败归因；**v0.7.4 适配 ZCode 3.14.x**（`data-project-path` 与 `workspace-item-*` 两处旧契约已被产品删除 → 绑定判据改为「路径优先、无路径渠道时按显示名 + 全局同名消歧」，同名即 fail-closed）；macOS 基本闭环已真机验证（2026-09-13，v0.4.0），取消/返修/新建项目矩阵补齐前保持 `research` |
 | `traework` | `gui` / `traework-gui` | **ready** | CDP 驱动 TRAE SOLO CN 桌面 UI；三种面板模式真机验证通过 |
 | `kimicode` | `gui` / `kimicode-gui` | **ready**（macOS 为 `research`） | Kimi Code 桌面端（Electron，实测 1.0.2）；**双渲染进程**（主窗口 + `Kimi Browser Overlay` 浮层承载模型/档位/模式菜单）；工作区以完整路径绑定，未登记时经原生「添加工作区」对话框导入；支持 `model`/`reasoningLevel`，不支持 `mode`；Windows 真机已验证成功路径、未登记工作区导入 + 自动验收、失败 → 返修 → 再验收同会话闭环；取消/提问续答仅由 hermetic 集成测试覆盖，macOS 为 `research` 且 fail-closed |
 | `qoder` | `gui` / `qoder-gui` | Windows 真机闭环通过；macOS **research** | 仅 Qoder CN；完整路径工作区、未登记目录经新建工作区 + 原生目录选择器导入、默认/自定义模型、模型管理全局思考等级保存回读、原会话续答与返修；Windows 真机验证：已有工作区默认模型、新登记工作区自定义模型、受控失败 → 落计划 → 原会话返修 → 再验收均通过；macOS 为 `research` 且 fail-closed（禁止派发） |

package/dist/agents/zcode/cdp.js

@@ -178,7 +178,35 @@ export class ZcodeCdpClient {
         return normalizeZcodeModelSelection(raw);
     }
     async projects() {
-        return this.evaluate(`(function(){const out=[];for(const s of ${candidateExpr("projectItem", this.selectors)})for(const e of document.querySelectorAll(s)){const testid=e.getAttribute('data-testid')||'';const testPath=testid.startsWith('workspace-item-')?testid.slice('workspace-item-'.length):undefined;const name=(e.getAttribute('data-project-name')||e.querySelector('[class*=name]')?.textContent||e.textContent||'').trim();const p=e.getAttribute('data-project-path')||e.querySelector('[data-project-path]')?.getAttribute('data-project-path')||testPath||e.getAttribute('title')||undefined;const id=e.getAttribute('data-project-id')||e.getAttribute('data-id')||testid||undefined;if(name)out.push({name,path:p,id})}return out})()`);
+        return this.evaluate(`(function(){
+        const norm=s=>(s||'').normalize('NFKC').trim();
+        const out=[],seen=new Set();
+        const push=(name,path,id,checked)=>{
+          const n=(name||'').trim();
+          if(!n)return;
+          const key=norm(n).toLocaleLowerCase();
+          if(seen.has(key))return;
+          seen.add(key);
+          out.push({name:n,path:path||undefined,id:id||undefined,checked});
+        };
+        for(const s of ${candidateExpr("projectItem", this.selectors)})for(const e of document.querySelectorAll(s)){
+          const testid=e.getAttribute('data-testid')||'';
+          const testPath=testid.startsWith('workspace-item-')?testid.slice('workspace-item-'.length):undefined;
+          const name=(e.getAttribute('data-project-name')||e.querySelector('[class*=name]')?.textContent||e.textContent||'').trim();
+          const p=e.getAttribute('data-project-path')||e.querySelector('[data-project-path]')?.getAttribute('data-project-path')||testPath||e.getAttribute('title')||undefined;
+          const id=e.getAttribute('data-project-id')||e.getAttribute('data-id')||testid||undefined;
+          push(name,p,id,undefined);
+        }
+        // issue #24：ZCode 3.14.x 已删除 workspace-item-*，项目列表只能从展开的下拉菜单采集。
+        // 仅在旧契约完全落空时启用，保证 3.11.x 的采集结果逐字不变。
+        if(!out.length)for(const s of ${candidateExpr("projectMenuItem", this.selectors)})for(const e of document.querySelectorAll(s)){
+          const name=(e.getAttribute('aria-label')||e.textContent||'').trim();
+          // 「不在项目中工作」是工作区切换项，不是项目——按本地化标签排除。
+          if(/不在项目中|outside a project|work outside/i.test(name))continue;
+          push(name,undefined,e.getAttribute('data-value')||undefined,e.getAttribute('aria-checked')==='true');
+        }
+        return out
+      })()`);
     }
     async clickProject(id, projectPath) {
         const displayName = projectPath ? projectDisplayName(projectPath) : "";

package/dist/agents/zcode/dom.js

@@ -34,15 +34,25 @@ const trigger = triggerMatch.node;`;
 }
 export function workspaceBindingExpression(overrides) {
     return `(function(){${projectTriggerDom(overrides)}
-    if (!trigger) return {triggerText:'',projectPath:'',ambiguous:triggerMatch.count>1};
+    if (!trigger) return {triggerText:'',projectPath:'',projectName:'',menuChecked:[],ambiguous:triggerMatch.count>1};
     const triggerText = labelOf(trigger);
     // A path anywhere in the sidebar is not evidence of the composer's binding.
     const explicit = pathOf(trigger) || pathOf(trigger.querySelector('[data-project-path]'));
     const rows = [...document.querySelectorAll('[data-testid^="workspace-item-"]')];
     const matches = rows.filter(e => norm(labelOf(e)) === norm(triggerText));
     const paths = [...new Set(matches.map(pathOf).filter(Boolean))];
+    // issue #24：ZCode 3.14.x 删除了 data-project-path 与 workspace-item-*，路径渠道归零。
+    // 此时当前绑定只剩「显示名」这一证据：展开菜单里 aria-checked=true 的项最权威
+    // （它是 ZCode 自己渲染的绑定状态），菜单未开时退回触发器文本。
+    // 绝不把显示名写进 projectPath——路径字段保持为空，判定层据此区分证据等级。
+    const checked = [...document.querySelectorAll('[role="menuitemcheckbox"][aria-checked="true"]')]
+      .filter(visible).map(labelOf).filter(Boolean);
+    const menuChecked = [...new Set(checked)];
+    const projectName = menuChecked.length===1 ? menuChecked[0]
+      : (menuChecked.length===0 ? triggerText : '');
     return {triggerText, projectPath:explicit || (paths.length===1?paths[0]:''),
-      ambiguous:!explicit && paths.length>1};
+      projectName, menuChecked,
+      ambiguous:(!explicit && paths.length>1) || menuChecked.length>1};
   })()`;
 }
 export function modelSelectionExpression(overrides) {

package/dist/agents/zcode/project.js

@@ -43,16 +43,67 @@ export function matchZcodeProject(items, target, platform = process.platform) {
     const exact = items.filter((item) => item.path &&
         normalizeProjectPath(item.path, platform) === normalizeProjectPath(target, platform));
     if (exact.length === 1)
-        return { item: exact[0], ambiguous: false };
+        return { item: exact[0], ambiguous: false, matchedBy: "path" };
     if (exact.length > 1)
         return { ambiguous: true };
     const api = platform === "win32" ? path.win32 : path.posix;
     const base = api.basename(target);
     const names = items.filter((item) => exactName(item.name, base, platform));
-    if (names.length > 0)
+    if (names.length > 1)
         return { ambiguous: true };
+    if (names.length === 1) {
+        const only = names[0];
+        // 同名项带路径且与目标不符 → 列表里那个不是目标，保持 fail-closed（原语义）。
+        if (only.path &&
+            normalizeProjectPath(only.path, platform) !== normalizeProjectPath(target, platform))
+            return { ambiguous: true };
+        // 无路径渠道（ZCode 3.14.x）：显示名是唯一可用证据，交给上层按显示名判定绑定。
+        return { item: only, ambiguous: false, matchedBy: "name" };
+    }
     return { ambiguous: false };
 }
+/**
+ * 判定「当前 ZCode 工作区是否绑定到 target」（issue #24）。
+ *
+ * 判据分层，证据等级从强到弱：
+ *  1. 路径回读（`binding.projectPath`）——老版本（与未来若恢复路径渠道）的严格判等，语义不变。
+ *  2. 显示名（`binding.projectName`）——3.14.x 的唯一渠道；仅在名称一致时成立，
+ *     并要求项目列表未出现同名歧义。
+ * 绝不把显示名当路径：路径不一致时一定判不绑定，宁可多走一轮点击也不误投。
+ */
+export function boundProjectVerdict(binding, match, target, platform = process.platform) {
+    if (binding.ambiguous)
+        return { bound: false, ambiguous: true, evidence: "工作区绑定回读本身已歧义" };
+    if (binding.projectPath) {
+        const ok = normalizeProjectPath(binding.projectPath, platform) === normalizeProjectPath(target, platform);
+        return { bound: ok, ambiguous: false, evidence: `路径回读=${binding.projectPath}` };
+    }
+    const expect = projectDisplayName(target, platform);
+    const boundName = (binding.projectName || "").trim();
+    if (!boundName)
+        return { bound: false, ambiguous: false, evidence: "未能回读当前绑定的显示名" };
+    if (!sameDisplayName(boundName, expect))
+        return {
+            bound: false,
+            ambiguous: false,
+            evidence: `当前绑定显示名=${boundName}，目标=${expect}`,
+        };
+    // 名称一致：只有列表确实可得且表明同名歧义时才拒绝（列表不可得时不能据此否定）。
+    if (match.ambiguous)
+        return { bound: false, ambiguous: true, evidence: "项目列表存在同名项，无法消歧" };
+    if (match.item?.path &&
+        normalizeProjectPath(match.item.path, platform) !== normalizeProjectPath(target, platform))
+        return {
+            bound: false,
+            ambiguous: false,
+            evidence: `同名项目路径不符：${match.item.path}`,
+        };
+    return {
+        bound: true,
+        ambiguous: false,
+        evidence: `显示名一致=${boundName}${match.matchedBy === "name" ? "（无路径渠道，按 3.14.x 契约以显示名判定）" : ""}`,
+    };
+}
 function exactName(a, b, platform) {
     return platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
 }

package/dist/agents/zcode/run.js

@@ -5,7 +5,7 @@ import { ZCODE_SETUP_DEFAULTS } from "../../config/schema.js";
 import { mkdirp } from "../../util/fs.js";
 import { parseZcodeModel, exactUiName, ZcodeModelReadbackError } from "./model.js";
 import { validateTaskReferences } from "./references.js";
-import { matchZcodeProject, normalizeProjectPath, isUnboundTriggerText, } from "./project.js";
+import { boundProjectVerdict, matchZcodeProject, isUnboundTriggerText, } from "./project.js";
 import { judgeZcodePoll } from "./liveness.js";
 import { ZcodeCdpClient, CdpDisconnectedError, CdpUnavailableError, } from "./cdp.js";
 import { ensureZcodeInstance, listZcodeProcessesAsync, } from "./instance.js";
@@ -80,9 +80,10 @@ function prompt(ctx, refs, initialDispatch) {
 async function waitBound(cdp, target, deps) {
     for (let i = 0; i < 30; i++) {
         const binding = await cdp.workspaceBinding();
-        if (!binding.ambiguous &&
-            binding.projectPath &&
-            normalizeProjectPath(binding.projectPath) === normalizeProjectPath(target))
+        // 与项目分支共用同一套分层判据（issue #24）：路径可得时严格判等，3.14.x 无路径渠道时按显示名。
+        // 点击菜单项后菜单会收起、列表为空，所以这里不传列表——不能因列表缺失而否定已确认的绑定。
+        const verdict = boundProjectVerdict(binding, { ambiguous: false }, target);
+        if (verdict.bound)
             return true;
         await deps.sleep(300);
     }
@@ -404,37 +405,68 @@ export async function runZcodeTask(args) {
                 await deps.sleep(Math.min(300, Math.max(0, deadline - Date.now())));
             }
         };
-        const ensureProjectBound = async (initialItem) => {
-            const currentBinding = await cdp.workspaceBinding();
-            if (currentBinding.ambiguous)
-                return { bound: false, ambiguous: true };
-            if (currentBinding.projectPath &&
-                normalizeProjectPath(currentBinding.projectPath) === normalizeProjectPath(ctx.projectPath))
-                return { bound: true, ambiguous: false };
-            let item = initialItem;
+        /**
+         * 绑定失败时的证据摘要：触发器文本、菜单勾选态与路径回读。
+         * issue #24 要求 fail-closed 时把这几项一并写进错误信息，用户在 ZCode 里能据此判断
+         * 到底绑到了哪个项目（而不是只看到一句「回读不一致」无从自救）。
+         */
+        const describeBinding = async () => {
+            try {
+                const b = await cdp.workspaceBinding();
+                return `触发器文本=${b.triggerText || "空"}；菜单勾选=${b.menuChecked?.length ? b.menuChecked.join("、") : "无"}；路径回读=${b.projectPath || "无"}`;
+            }
+            catch {
+                return "绑定状态回读失败";
+            }
+        };
+        /**
+         * 读一次「当前绑定是否为目标项目」的分层判定（issue #24）：
+         * 路径可得时严格判等；无路径渠道（ZCode 3.14.x）时按显示名，并在列表可得时做同名消歧。
+         */
+        const readBoundVerdict = async () => {
+            const binding = await cdp.workspaceBinding();
+            const match = matchZcodeProject(await cdp.projects(), ctx.projectPath);
+            return { verdict: boundProjectVerdict(binding, match, ctx.projectPath), match };
+        };
+        /**
+         * 幂等确认绑定：每轮先读判定，已绑定即通过；未绑定则（必要时先展开菜单）点击目标项目再复检。
+         * 不再接受外部传入的 item——那会把「菜单是否恰好还开着」变成隐式前提（issue #24 暴露的脆弱时序）。
+         */
+        const ensureProjectBound = async () => {
             for (let round = 0; round <= gui.setupRecoveryMaxRetries; round++) {
-                if (!item || round > 0) {
-                    // eslint-disable-next-line no-await-in-loop
-                    await cdp.dismissMenus();
-                    // eslint-disable-next-line no-await-in-loop
-                    if (!(await cdp.clickProjectTriggerAndConfirm(projectTriggerDeadline())).opened)
-                        continue;
+                // eslint-disable-next-line no-await-in-loop
+                const { verdict, match } = await readBoundVerdict();
+                if (verdict.bound)
+                    return { bound: true, ambiguous: false };
+                if (verdict.ambiguous)
+                    return { bound: false, ambiguous: true };
+                if (match.item) {
                     // eslint-disable-next-line no-await-in-loop
-                    await deps.sleep(300);
+                    const clicked = await cdp.clickProject(match.item.id, match.item.path ?? ctx.projectPath);
                     // eslint-disable-next-line no-await-in-loop
-                    const matched = matchZcodeProject(await cdp.projects(), ctx.projectPath);
-                    if (matched.ambiguous)
-                        return { bound: false, ambiguous: true };
-                    item = matched.item;
+                    if (clicked && (await waitBound(cdp, ctx.projectPath, deps)))
+                        return { bound: true, ambiguous: false };
+                    continue;
                 }
-                if (!item)
+                // 目标不在当前列表（菜单多未展开）：显式展开菜单后再采集一次。
+                // eslint-disable-next-line no-await-in-loop
+                await cdp.dismissMenus();
+                // eslint-disable-next-line no-await-in-loop
+                if (!(await cdp.clickProjectTriggerAndConfirm(projectTriggerDeadline())).opened)
+                    continue;
+                // eslint-disable-next-line no-await-in-loop
+                await deps.sleep(300);
+                // eslint-disable-next-line no-await-in-loop
+                const expanded = matchZcodeProject(await cdp.projects(), ctx.projectPath);
+                if (expanded.ambiguous)
+                    return { bound: false, ambiguous: true };
+                if (!expanded.item)
                     continue;
                 // eslint-disable-next-line no-await-in-loop
-                const clicked = await cdp.clickProject(item.id, item.path);
+                const clicked = await cdp.clickProject(expanded.item.id, expanded.item.path ?? ctx.projectPath);
                 // eslint-disable-next-line no-await-in-loop
                 if (clicked && (await waitBound(cdp, ctx.projectPath, deps)))
                     return { bound: true, ambiguous: false };
-                item = undefined;
             }
             return { bound: false, ambiguous: false };
         };
@@ -555,13 +587,13 @@ export async function runZcodeTask(args) {
                         pendingQuestion: "项目路径存在歧义，请在 ZCode 中确认目标项目后调用 continue_task。",
                     });
                 if (matched.item) {
-                    const binding = await ensureProjectBound(matched.item);
+                    const binding = await ensureProjectBound();
                     if (!binding.bound)
                         return result({
                             hardFailure: true,
                             error: binding.ambiguous
-                                ? "项目绑定重试时目标项目无法唯一匹配"
-                                : "ZCode 项目绑定有限重试均未生效",
+                                ? `项目绑定重试时目标项目无法唯一匹配：${ctx.projectPath}；${await describeBinding()}`
+                                : `ZCode 项目绑定有限重试均未生效：${ctx.projectPath}；${await describeBinding()}`,
                             endReason: "project_mismatch",
                             needsUserKind: "setup_recovery",
                             pendingQuestion: "项目绑定尚未确认，请在 ZCode 中确认目标项目后调用 continue_task。",
@@ -693,8 +725,8 @@ export async function runZcodeTask(args) {
                     return result({
                         hardFailure: true,
                         error: finalBinding.ambiguous
-                            ? "ZCode 项目绑定回读不一致，且重试时目标项目无法唯一匹配"
-                            : "ZCode 项目绑定回读与 projectPath 不一致，有限幂等重试均失败",
+                            ? `ZCode 项目绑定回读不一致，且重试时目标项目无法唯一匹配：${ctx.projectPath}；${await describeBinding()}`
+                            : `ZCode 项目绑定回读与 projectPath 不一致，有限幂等重试均失败：${ctx.projectPath}；${await describeBinding()}`,
                         endReason: "project_mismatch",
                         needsUserKind: "setup_recovery",
                         pendingQuestion: "项目绑定尚未确认，请在 ZCode 中确认目标项目后调用 continue_task。",

package/dist/agents/zcode/selectors.js

@@ -75,7 +75,13 @@ export const ZCODE_SELECTORS = {
         primary: '[data-testid^="workspace-item-"]',
         fallbacks: ['[class*="project-item"]', '[class*="workspace-item"]'],
         verifiedVersion: "3.11.x",
-        note: "项目列表项",
+        note: "3.11.x 的项目列表项。ZCode 3.14.x 已删除该契约（app.asar 扫描 0 命中），改用 projectMenuItem。",
+    },
+    projectMenuItem: {
+        primary: '[role="menuitemcheckbox"]',
+        fallbacks: [],
+        verifiedVersion: "3.14.x",
+        note: "工作区下拉中的项目项：textContent 即项目显示名，aria-checked 表示是否为当前绑定。3.14.x 下 workspace-item-* 与 data-project-path 均已不存在，这是唯一可用的绑定证据来源；仅在项目菜单展开时有效。",
     },
     projectPath: {
         primary: "[data-project-path]",

package/dist/version.generated.js

@@ -4,4 +4,4 @@
  * 本文件由 scripts/sync-version.mjs 在每次 build 前重新生成。
  */
 // generated: 勿手改 —— 运行 `npm run build` 自动同步
-export const MCP_SERVER_VERSION = "0.7.2";
+export const MCP_SERVER_VERSION = "0.7.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tianshu-mcp",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "天枢 × AI-Agent 编排 MCP server —— 驱动 Codex、TraeWork、ZCode、Kimi Code、Qoder CN 与 Open Design 完成项目开发、验收、失败返修与再验收闭环。",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/probe-zcode.mjs

@@ -169,6 +169,77 @@ async function uiState() {
   }
 }
 
+/**
+ * issue #24 真机取证：ZCode 3.14.x 是否真的删除了项目绑定的两处 DOM 契约。
+ *
+ * 输出各契约的命中计数、触发器全属性、展开菜单后的项目项清单，以及修复后的适配器回读结果。
+ * **会展开一次工作区菜单**（只读采集，不选中任何项）。
+ */
+async function domContracts() {
+  const endpoints = await cdpTargets();
+  const endpoint = endpoints.find((item) =>
+    item.targets?.some(
+      (target) =>
+        target.type === "page" && /z[ -]?code/i.test(`${target.title ?? ""} ${target.url ?? ""}`),
+    ),
+  );
+  if (!endpoint) return { ok: false, message: "没有通过产品标识核验的 ZCode CDP 页面" };
+  try {
+    const { ZcodeCdpClient } = await import("../dist/agents/zcode/cdp.js");
+    const client = new ZcodeCdpClient(endpoint.port, 10_000, {});
+    await client.connect();
+    try {
+      const counts = await client.evaluate(
+        `(function(){return {
+          dataProjectPath: document.querySelectorAll('[data-project-path]').length,
+          workspaceItems: document.querySelectorAll('[data-testid^="workspace-item-"]').length,
+          dataProjectName: document.querySelectorAll('[data-project-name]').length,
+          triggers: document.querySelectorAll('[data-testid="composer-workspace-trigger"]').length,
+          menuItemCheckbox: document.querySelectorAll('[role="menuitemcheckbox"]').length
+        }})()`,
+      );
+      const trigger = await client.evaluate(
+        `(function(){const e=document.querySelector('[data-testid="composer-workspace-trigger"]');if(!e)return null;const attrs={};for(const a of e.attributes)attrs[a.name]=a.value;return {text:(e.textContent||'').trim().slice(0,200),attrs}})()`,
+      );
+      // 项目身份只在菜单展开时可见：先收起残留菜单，再展开一次做只读采集。
+      await client.dismissMenus();
+      const opened = await client.clickProjectTriggerAndConfirm(Date.now() + 5_000);
+      const menuItems = opened.opened
+        ? await client.evaluate(
+            `(function(){return [...document.querySelectorAll('[role="menuitemcheckbox"]')].map(function(e){return {text:(e.textContent||'').trim().slice(0,200),checked:e.getAttribute('aria-checked'),testid:e.getAttribute('data-testid')||undefined};})})()`,
+          )
+        : [];
+      const binding = await client.workspaceBinding();
+      const projects = await client.projects();
+      await client.dismissMenus();
+      return {
+        ok: true,
+        port: endpoint.port,
+        counts,
+        trigger,
+        menuOpened: opened.opened,
+        menuItems,
+        binding,
+        projects,
+        verdict: {
+          // 两处旧契约都缺席 ⇒ 路径渠道不可用，适配器必须靠显示名完成绑定。
+          pathChannelAvailable: counts.dataProjectPath > 0 || counts.workspaceItems > 0,
+          nameChannelAvailable: binding.projectPath === "" && !!binding.projectName,
+          ambiguous: binding.ambiguous === true,
+        },
+      };
+    } finally {
+      client.disconnect();
+    }
+  } catch (e) {
+    return {
+      ok: false,
+      port: endpoint.port,
+      message: `绑定契约诊断失败：${e.message}。请先执行 npm run build。`,
+    };
+  }
+}
+
 async function menuControls(kind) {
   const endpoints = await cdpTargets();
   const endpoint = endpoints.find((item) =>
@@ -273,6 +344,7 @@ else if (command === "process") json(processInfo());
 else if (command === "cdp") json(await cdpTargets());
 else if (command === "models") json(await modelState());
 else if (command === "permission") json(await permissionState());
+else if (command === "dom-contracts") json(await domContracts());
 else if (command === "selectors")
   json({
     source: "src/agents/zcode/selectors.ts",

package/skills/tianshu-mcp/SKILL.md

@@ -264,6 +264,11 @@ meta 的 `needsUserKind` 给出等待类型，`pendingQuestion` 给出问题原
 
 `agentEndReason` 与终态映射（先记住这张表，再看错误码表）：
 
+> **下面的错误码表是「常见子集」而非闭集**：`endReason` 在类型层面只是一个可选 `string`
+> （`src/agents/adapter.ts:93`），没有枚举约束，某个适配器新增分支时无需改类型就能引入新取值。
+> 因此看到表里没有的取值时，**按名字猜语义不如去读该适配器的 `run.ts`**，或看 `query_task` 的
+> 日志尾部与 `progressSummary`。
+
 | `agentEndReason` | 任务终态 |
 |---|---|
 | `task_timeout` | `needs_attention` + `errorType=timeout`（GUI：codex/zcode）；qoder 落 `failed(timeout)` |
@@ -273,6 +278,9 @@ meta 的 `needsUserKind` 给出等待类型，`pendingQuestion` 给出问题原
 | `agentEndReason` | 含义 | 处置 |
 |---|---|---|
 | `setup_failed` | 找不到安装 / 实例未就绪 / 点不到「新对话」 | 让用户确认已安装且能手动打开；重试一次 |
+| `input_mismatch` | 任务输入框回读与本次标记不符（真机常见成因：输入框残留模板/草稿，任务被插进残文里） | 适配器已先清空再输入；若仍失败，让用户手动清空输入框后重派 |
+| `send_unknown` | 点了发送但**无法确认消息落地** | 适配器**绝不重发**（避免重复派活）；请用户在界面确认是否已发出，再决定重派或 `continue_task` |
+| `reply_stable` | **正常完成**：对话与产物均已静止 | 不是错误；去读验收报告 |
 | `project_ambiguous` | 项目同名或路径重复，无法消歧 | 已转 `needs_user(setup_recovery)`：请用户确认目标项目后 `continue_task` |
 | `project_mismatch` | 项目绑定或回读不一致，幂等重试仍失败 | 同上：请用户在 GUI 里确认/手工绑定 |
 | `project_create_failed` | 在 GUI 内新建项目失败 | 让用户手动把项目加进 agent，或换 `projectPath` |

package/skills/tianshu-mcp/usage-examples.md

@@ -193,7 +193,16 @@ run_task(projectPath=D:/repo/design, agentId=opendesign,
 - `designSystem` 传**设计系统名**（如 `Claude`、`Neutral Modern`），不是目录路径——与 codex 的 `designSystem` 语义不同（那边是目录）。
 - `mode` 不支持（那是 traework 的面板模式）；`model` 必填，按名字**精确匹配**菜单项，未命中会报错并**回显当前可见候选**，不会退化成模糊匹配。
 - 目录绑定按「展开工作目录 → 选择目录 → 原生『选择文件夹』填绝对路径 → **回读显示值校验**」；已是目标目录则跳过。
-- 视觉验收要求项目里有可截图的页面来源；适配器只**推导建议**（静态入口优先），**不会自动修改** `.tianshu-mcp/acceptance.json`。
+  （绑目录前适配器会先等 **daemon sidecar 就绪** —— 产品打开文件夹选择器前要与 daemon 完成鉴权握手，
+  实测启动后约 30s 才驻留；未就绪时产品只会显示自己的提示、**根本不弹对话框**。）
+- **产物会自动取回任务目录**（`v0.7.1` 起）：Open Design 的设计稿存在它自己的产物存储
+  `<dataRoot>/projects/<projectId>/<entry>`，**不在任务目录里**。终态后适配器把它复制到
+  `projectPath`，视觉验收随后可推导静态入口（`onboarding-guide.html` → 路由 `/onboarding-guide.html`）。
+  取回是**增值步骤**：失败只写进 `progressSummary`，**不改变任务终态**。
+- **`zip` 导出方式尚未打通**（已知限制）：产品的下载由主进程接管，CDP 的下载接管被覆盖；
+  `html` 路径完全可用，zip 待后续优化。
+- 视觉验收要求项目里有可截图的页面来源；适配器只**推导建议**（静态入口优先，白名单未命中时
+  若项目根下 html **恰好唯一**也认它），**不会自动修改** `.tianshu-mcp/acceptance.json`。
 - 修复/优化计划落项目根 `.opendesign/plans/`（Open Design 只能读它工作目录白名单内的文件）。
 - 可正常派活（Windows 真机取证；macOS 为 `research` 且禁止派发）。仍 **fail-closed**：选择器漂移时硬失败 `selector_drift` 并列出缺失键，模型未命中报 `model_unavailable` 并回显可见候选，设计方向非法在**入口**即拒绝。
   详见 [docs/opendesign-cdp.md](../../docs/opendesign-cdp.md) 与 `.dsh/plans/opendesign-gui-adapter-plan.md`。
@@ -212,7 +221,7 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli,
 - 写入被 `workspace-write` 沙箱限制在项目目录内；POSIX 下取消/超时对进程组 `SIGTERM`→`SIGKILL`。
 - **无头路径没有 GUI 交互**：不存在 `user_confirmation` 这类等待，`continue_task` 不适用；失败直接看 `agentEndReason` 与日志。
 
-### 2.9 通用约定
+### 2.10 通用约定
 
 - `run_task` 是**异步契约**：立即返回 `taskId` + 队列位置，不要当同步调用等结果。
 - 轮询间隔 5–10 秒（`query_task` 缺省返回 agent 日志末 40 行）；同项目串行 + 全局并发默认 2，重复派单只会排队。