tianshu-mcp 0.7.5 → 0.7.6

package/CHANGELOG.en.md

@@ -8,6 +8,63 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.7.6] - 2026-09-30
+
+### Fixed
+
+- **Three ZCode adapter defects (issue #27), reproduced and fixed on real ZCode `3.14.3.7762` (Windows)**:
+  - **Split project-collection channels causing a binding deadlock**: on 3.14.3 the
+    `[data-testid^="workspace-item-"]` nodes are **not gone from the DOM** — they are scrolled out of
+    the viewport instead (measured on the real machine: **40 of 42 nodes invisible**). The old
+    implementation collected them without any visibility filter, so the ghost entries made
+    `if (!out.length)` permanently false and the only trustworthy channel (the dropdown menu) never
+    ran. `matchZcodeProject` then matched a ghost item, the working auto-import branch was skipped,
+    and the task died with `project_mismatch`. `projects()` now filters the legacy channel by
+    visibility, **always merges both channels**, and lets same-named menu items override sidebar
+    entries (only the menu's `aria-checked` is binding evidence rendered by ZCode itself).
+  - **Fall back to import when clicks never land**: `clickProject` now reports a distinguishable
+    reason (`trigger-unavailable` / `not-found` / `not-visible`). When the target is listed but not a
+    single click ever landed, the adapter falls back to the `selectZcodeFolder` import path instead
+    of declaring failure (still fail-closed when `allowCreateProject=false`).
+  - **Runtime CDP disconnects no longer declare death**: a single `Runtime.evaluate` timeout or an
+    endpoint hiccup does not mean CDP is dead (in the reported incident the agent kept writing
+    artifacts after MCP had already failed the task). The send phase and the runtime loop now share
+    one guard: the first disconnect reconnects **once, for observation only** (matching the existing
+    `codex`/`qoder` pattern — **never resending the task**); a failed reconnect or a second
+    disconnect lands on `needs_user(setup_recovery)` with both facts attached — whether the process
+    is still alive and whether the window still shows running signals — so "still running" is never
+    misread as "stopped".
+  - **`reasoningLevel` implemented end to end**: the tier set **varies per model**, so it is read
+    from the UI **after the model is confirmed** and validated. Out-of-range tiers and unreadable
+    tier sets are rejected **before sending** (`reasoning_level_invalid`) instead of silently reusing
+    the current value; omitting the tier never touches the UI. Real-machine contract:
+    trigger `chat-thought-level-select-trigger` (combobox), options
+    `chat-thought-level-select-item-{enabled,disabled}` (binary on/off), options mounted only while
+    the menu is open.
+  - **Root cause of the "two-level model menu is flaky" symptom**: model items live in the provider
+    group's **second-level submenu**, which renders only on **hover** — clicking selects the group
+    itself or collapses the menu. The provider group testid has also drifted to
+    `chat-model-select-group-registry-provider:`. Group expansion now uses hover
+    (`clickExact(..., "hover")`), and when two rounds both yield an empty candidate list the menu is
+    reopened for one more round instead of declaring `model_unavailable`.
+- **Permission-menu contract drift (surfaced by the real-machine run, fixed as the same class of defect)**:
+  on 3.14.3 the permission items use `menuitemradio` / `menuitemcheckbox` (**not** `option`), and the
+  visible name lives in the item's **direct text node**, followed by an explanatory sentence
+  (e.g. "Full access — fewer confirmations."). Both mismatched the old implementation and stalled
+  dispatch at `permission_unknown`. The selector now carries a role-agnostic fallback, and
+  `clickExact` resolves labels from direct text nodes first.
+
+### Real-machine verification
+
+- `npm run probe:zcode -- dom-contracts`: `workspaceItems=42` (2 visible / 40 invisible),
+  `dataProjectPath=0`; with the menu open `projects()` returns the menu items with correct checked
+  state — independently reproducing both the issue's geometric premise and the fixed collection.
+- `npm run probe:zcode -- models` / `permission` plus one-off probes: pinned the provider-group hover
+  semantics, the permission item role/text structure, and the binary tier shape
+  (`current=on`, `tiers=Off/On`).
+- `npm run smoke:zcode`: end-to-end real-machine dispatch (project binding → model switch →
+  permission confirm → send → poll to terminal state).
+
 ## [0.7.5] - 2026-09-29
 
 ### Fixed

package/CHANGELOG.md

@@ -7,6 +7,45 @@
 
 ---
 
+## [0.7.6] - 2026-09-30
+
+### 修复
+
+- **ZCode 适配器三项缺陷（issue #27），已在真机 ZCode `3.14.3.7762`（Windows）上复现并修复**：
+  - **项目采集渠道分裂导致绑定死锁**：3.14.3 上 `[data-testid^="workspace-item-"]` **并未从 DOM 消失**，
+    只是被滚出视口（真机实测 **42 个节点中 40 个不可见**）。旧实现采集时不做可见性过滤，幽灵项入列使
+    `if (!out.length)` 短路恒为假，唯一可信的菜单渠道永不执行 → `matchZcodeProject` 命中幽灵项 →
+    可用的自动导入分支被跳过 → 任务卡死在 `project_mismatch`。现在 `projects()` 对旧契约项做可见性过滤、
+    两条渠道**始终合并**，且同名的菜单项覆盖侧边栏项（只有菜单的 `aria-checked` 是 ZCode 自己渲染的绑定证据）。
+  - **点击落空时回落导入**：`clickProject` 现在返回可区分的原因（`trigger-unavailable` / `not-found` /
+    `not-visible`）；目标项在列表里却一次都没真正点中时，回落 `selectZcodeFolder` 导入路径而不是直接判死
+    （`allowCreateProject=false` 时仍在下一道闸门 fail-closed）。
+  - **运行期 CDP 断连不再判死**：单次 `Runtime.evaluate` 超时或端点抖动不等于 CDP 已死（issue 现场是
+    「MCP 判定失败后 agent 仍在写产物」）。发送阶段与运行期统一护栏：首次断连重连**观察一次**
+    （对齐 `codex`/`qoder` 的既有范式，重连只用于观察、**绝不重发任务**），重连失败或再次断连落
+    `needs_user(setup_recovery)`，并附「进程是否仍在」「窗口是否仍有运行信号」两侧事实，避免把「仍在跑」
+    误读成「已停」。
+  - **`reasoningLevel` 端到端实现**：档位集合**随模型变化**，因此在**模型确认之后**才读取界面实际渲染的选项
+    并校验；越权档位与「集合读不到」都在**发送前**报错（`reasoning_level_invalid`），绝不静默沿用；
+    未指定档位时完全不触碰界面。真机契约：触发器 `chat-thought-level-select-trigger`（combobox），
+    选项 `chat-thought-level-select-item-{enabled,disabled}`（二值 开启/关闭），选项只在菜单展开时挂载。
+  - **「两级模型菜单点击不稳」根因**：模型项在 provider 分组的**二级子菜单**里，**必须 hover 分组**才渲染，
+    用 click 会选中分组本身或收起菜单；provider 分组 testid 也已漂移为
+    `chat-model-select-group-registry-provider:`。现在展开分组改用 hover（`clickExact(..., "hover")`），
+    并在两轮候选皆空时把菜单重开一次再试一轮，不凭一轮空列表判 `model_unavailable`。
+- **权限菜单契约漂移（真机测试暴露，同类问题一并修复）**：3.14.3 的权限项 role 是
+  `menuitemradio` / `menuitemcheckbox`（**不是** `option`），且可见名写在项内的**直接文本节点**里、
+  后面还跟一句说明（如「完全访问减少确认次数。」）。旧实现两处都会 0 命中，导致派发卡在 `permission_unknown`。
+  候选选择器补无 role 限制的兜底，`clickExact` 的标签解析优先取直接文本节点。
+
+### 真机验证
+
+- `npm run probe:zcode -- dom-contracts`：`workspaceItems=42`（可见 2 / 不可见 40）、`dataProjectPath=0`、
+  菜单展开后 `projects()` 返回菜单项且勾选态正确 —— 独立复现了 issue 的几何前提与修复后的采集结果。
+- `npm run probe:zcode -- models` / `permission` 与一次性探针：锁定 provider 分组 hover 语义、
+  权限项 role 与文本结构、档位二值形态（`current=on`、`tiers=Off/On`）。
+- `npm run smoke:zcode`：真机端到端派发（项目绑定 → 模型切换 → 权限确认 → 发送 → 轮询终态）。
+
 ## [0.7.5] - 2026-09-29
 
 ### 修复

package/README.en.md

@@ -2,7 +2,7 @@
   <img src="./assets/tianshu-mcp-banner.svg" alt="Tianshu Orchestration MCP tianshu-mcp" width="100%">
 </p>
 
-<h1 align="center">Tianshu Orchestration MCP <sub>tianshu-mcp</sub></h1>
+<h1 align="center">Tianshu Orchestration MCP tianshu-mcp</h1>
 
 <p align="center">
   <b>Dispatch with agents, verify with evidence. · 把开发交给 AI-Agent，把验收交给运行时</b>
@@ -30,7 +30,6 @@
 <p align="center">
   <img src="https://img.shields.io/github/actions/workflow/status/lanlan0811/tianshu-mcp/ci.yml?branch=master&style=for-the-badge&logo=github&label=CI" alt="CI">
   <img src="https://img.shields.io/npm/v/tianshu-mcp?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=cb3837" alt="npm version">
-  <img src="https://img.shields.io/npm/dm/tianshu-mcp?style=for-the-badge&logo=npm&logoColor=white&label=downloads&color=cb3837" alt="npm downloads">
   <img src="https://img.shields.io/github/stars/lanlan0811/tianshu-mcp?style=for-the-badge&logo=github&label=stars&color=24292e" alt="GitHub stars">
   <img src="https://img.shields.io/badge/License-Apache%202.0-3B5BDB?style=for-the-badge&logo=apache" alt="License">
   <img src="https://img.shields.io/badge/TypeScript-5.7-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
@@ -39,8 +38,20 @@
   <img src="https://img.shields.io/badge/Tests-1383%20Passed-green?style=for-the-badge" alt="Tests">
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/tianshu-mcp"><img src="https://img.shields.io/npm/d18m/tianshu-mcp?style=for-the-badge&logo=npm&logoColor=white&label=mcp%20downloads&color=cb3837" alt="MCP downloads (npm)"></a>
+  <a href="https://github.com/lanlan0811/tianshu-mcp/releases?q=v&expanded=true"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Flanlan0811%2Ftianshu-mcp%2Fmaster%2Fupdate%2Fstats.json&query=%24.mcpDownloads&style=for-the-badge&logo=github&logoColor=white&label=mcp%20tarball%20downloads&color=2ea44f" alt="MCP tarball downloads (GitHub releases)"></a>
+  <a href="https://github.com/lanlan0811/tianshu-mcp/releases?q=gui-v&expanded=true"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Flanlan0811%2Ftianshu-mcp%2Fmaster%2Fupdate%2Fstats.json&query=%24.guiDownloads&style=for-the-badge&logo=github&logoColor=white&label=gui%20downloads&color=1f6feb" alt="Log viewer GUI downloads (GitHub releases)"></a>
+</p>
+
 ---
 
+<p align="center">
+  <img src="./assets/mcp-running.png" alt="Tianshu Harness desktop orchestrating ZCode through tianshu-mcp" width="100%">
+  <br>
+  Tianshu Harness desktop in action — <b>Tianshu</b> calls <b>tianshu-mcp</b> over MCP to orchestrate <b>ZCode</b> through a development task: tasks dispatched and tracked on the left, tianshu-mcp tool calls and event stream in the middle (<code>mcp__tianshu-mcp__query_task</code> polling a running task), and ZCode doing the actual work on the right
+</p>
+
 ### An orchestration layer and objective acceptance gate for AI agents
 
 > **tianshu-mcp** is an orchestration layer plugged into **Tianshu** as a standard MCP server. Tianshu is the commander and the user-facing surface; this server does three jobs: **scheduling** (queues / concurrency gate / state machine / cancellation), the **execution surface** (delivering task briefs to external AI agents), and the **objective acceptance gate** (command checks, code analysis and optional visual comparison, all relative to a git baseline).
@@ -236,7 +247,7 @@ run_task(projectPath=D:/xxx/my-app, task="…task brief…", agentId=codex,
 | agentId | driver / adapter | status | Notes |
 |---|---|---|---|
 | `codex` | `gui` / `codex-gui` | **ready** (`research` on macOS) | Codex desktop GUI (Windows: MSIX COM activation + CDP; macOS: spawn .app + CDP); supports `model` / `reasoningLevel` / `planDoc` / `designSystem`; user-confirmation wait, cancellation and re-dispatch guards are all machine-verified |
-| `zcode` | `gui` / `zcode-gui` | **research** | CDP GUI adapter implemented and closed-loop verified on real Windows hardware; supports project-less dispatch and `allowCreateProject`; **v0.7.4 adapts ZCode 3.14.x** (two old DOM contracts were removed by the product → the binding verdict became "path first, display-name when no path is available + global name disambiguation", failing closed on duplicates) |
+| `zcode` | `gui` / `zcode-gui` | **ready** (closed-loop verified on real Windows; macOS unverified) | CDP GUI adapter; supports project-less dispatch, `allowCreateProject` and `reasoningLevel` (the tier set **varies per model**; out-of-range tiers fail **before sending**); **v0.7.4 adapted to the missing 3.14.x path contracts** (the binding verdict became "path first, display-name when no path is available + global name disambiguation", failing closed on duplicates); **v0.7.6 fixes the binding deadlock** (sidebar `workspace-item-*` nodes scrolled out of view were still collected, short-circuiting the only trustworthy menu channel), **adds a recovery entry point for runtime CDP disconnects** (reconnect once for observation, never resend; a failed reconnect lands on `needs_user(setup_recovery)`) and **fixes the two-level model menu** (provider groups render their submenu only on hover) |
 | `traework` | `gui` / `traework-gui` | **ready** | CDP-driven TRAE SOLO CN desktop UI; supports `mode` (Work / Code / Design, each of the three modes maintaining its own project binding); all three modes machine-verified |
 | `kimicode` | `gui` / `kimicode-gui` | **ready** (`research` on macOS) | Kimi Code desktop (Electron); **dual renderer processes** (main window plus a `Kimi Browser Overlay` that hosts the model / reasoning / mode menus); workspaces bind by full path; supports `model` / `reasoningLevel`, **not `mode`**, and **not project-less dispatch** |
 | `qoder` | `gui` / `qoder-gui` | closed-loop verified on Windows; **research** on macOS | Qoder CN only; requires an existing `projectPath` and a readable `planDoc`; `modelSource=default\|custom` disambiguates same-named models, and the reasoning level is saved as a global preference via "Model management" and read back |
@@ -384,21 +395,15 @@ Key capabilities:
 - **Update-notes window and dual-source auto-update** — a silent update check at startup pops the "update notes" window when a new version is found (download and install / ignore this version / later), whose body is that version's bilingual release notes; the update source is chosen by **concurrently probing Gitee / GitHub and picking the better one** (never relying on system region) and is shown truthfully, and every package is **minisign-verified** — **a failed signature is never installed**.
 
 <p align="center">
-  <img src="./assets/tianshu-mcp-gui-overview.png" alt="Log viewer · task overview page" width="88%">
+  <a href="./assets/tianshu-mcp-gui-overview.png"><img src="./assets/tianshu-mcp-gui-overview.png" alt="Log viewer · task overview page" width="32%"></a>
+  <a href="./assets/tianshu-mcp-gui-event-stream.png"><img src="./assets/tianshu-mcp-gui-event-stream.png" alt="Log viewer · task event stream workspace" width="32%"></a>
+  <a href="./assets/tianshu-mcp-gui-agent-log.png"><img src="./assets/tianshu-mcp-gui-agent-log.png" alt="Log viewer · agent raw log workspace" width="32%"></a>
   <br>
-  <sub>Task overview page — resident left rail · five-cell metrics (total / running / finished / succeeded / failed) · status chips · task card grid</sub>
-</p>
-
-<p align="center">
-  <img src="./assets/tianshu-mcp-gui-event-stream.png" alt="Log viewer · task event stream workspace" width="88%">
+  <b>Task overview page</b> — resident left rail · five-cell metrics (total / running / finished / succeeded / failed) · status chips · task card grid
   <br>
-  <sub>Full-screen workspace · event stream — line / time / event / detail columns, with status transitions and progress records colour-coded</sub>
-</p>
-
-<p align="center">
-  <img src="./assets/tianshu-mcp-gui-agent-log.png" alt="Log viewer · agent raw log workspace" width="88%">
+  <b>Full-screen workspace · event stream</b> — line / time / event / detail columns, with status transitions and progress records colour-coded
   <br>
-  <sub>Full-screen workspace · agent log — level filtering · line numbers and word wrap · "loaded N / M" with "jump to latest"</sub>
+  <b>Full-screen workspace · agent log</b> — level filtering · line numbers and word wrap · "loaded N / M" with "jump to latest"
 </p>
 
 Decoupling and release boundaries (read before changing anything here):

package/README.md

@@ -2,7 +2,7 @@
   <img src="./assets/tianshu-mcp-banner.svg" alt="天枢编排 MCP tianshu-mcp" width="100%">
 </p>
 
-<h1 align="center">天枢编排 MCP <sub>tianshu-mcp</sub></h1>
+<h1 align="center">天枢编排 MCP tianshu-mcp</h1>
 
 <p align="center">
   <b>把开发交给 AI-Agent，把验收交给运行时 · Dispatch with agents, verify with evidence.</b>
@@ -30,7 +30,6 @@
 <p align="center">
   <img src="https://img.shields.io/github/actions/workflow/status/lanlan0811/tianshu-mcp/ci.yml?branch=master&style=for-the-badge&logo=github&label=CI" alt="CI">
   <img src="https://img.shields.io/npm/v/tianshu-mcp?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=cb3837" alt="npm version">
-  <img src="https://img.shields.io/npm/dm/tianshu-mcp?style=for-the-badge&logo=npm&logoColor=white&label=downloads&color=cb3837" alt="npm downloads">
   <img src="https://img.shields.io/github/stars/lanlan0811/tianshu-mcp?style=for-the-badge&logo=github&label=stars&color=24292e" alt="GitHub stars">
   <img src="https://img.shields.io/badge/License-Apache%202.0-3B5BDB?style=for-the-badge&logo=apache" alt="License">
   <img src="https://img.shields.io/badge/TypeScript-5.7-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
@@ -39,8 +38,20 @@
   <img src="https://img.shields.io/badge/Tests-1383%20Passed-green?style=for-the-badge" alt="Tests">
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/tianshu-mcp"><img src="https://img.shields.io/npm/d18m/tianshu-mcp?style=for-the-badge&logo=npm&logoColor=white&label=MCP%20%E4%B8%8B%E8%BD%BD%E6%AC%A1%E6%95%B0&color=cb3837" alt="MCP 下载次数（npm）"></a>
+  <a href="https://github.com/lanlan0811/tianshu-mcp/releases?q=v&expanded=true"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Flanlan0811%2Ftianshu-mcp%2Fmaster%2Fupdate%2Fstats.json&query=%24.mcpDownloads&style=for-the-badge&logo=github&logoColor=white&label=MCP%20%E5%8E%8B%E7%BC%A9%E5%8C%85%E4%B8%8B%E8%BD%BD%E6%AC%A1%E6%95%B0&color=2ea44f" alt="MCP 压缩包下载次数（GitHub 发行）"></a>
+  <a href="https://github.com/lanlan0811/tianshu-mcp/releases?q=gui-v&expanded=true"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Flanlan0811%2Ftianshu-mcp%2Fmaster%2Fupdate%2Fstats.json&query=%24.guiDownloads&style=for-the-badge&logo=github&logoColor=white&label=GUI%20%E4%B8%8B%E8%BD%BD%E6%AC%A1%E6%95%B0&color=1f6feb" alt="日志台 GUI 下载次数（GitHub 发行）"></a>
+</p>
+
 ---
 
+<p align="center">
+  <img src="./assets/mcp-running.png" alt="天枢 harness 桌面端通过 tianshu-mcp 调用 ZCode 完成开发" width="100%">
+  <br>
+  天枢 harness 桌面端实况 —— <b>天枢</b>经 MCP 调用 <b>tianshu-mcp</b> 编排 <b>ZCode</b> 完成一次开发任务：左侧派发与跟踪任务，中间是 tianshu-mcp 的工具调用与事件流（<code>mcp__tianshu-mcp__query_task</code> 轮询运行中的任务），右侧 ZCode 正在执行实际开发
+</p>
+
 ### 面向 AI-Agent 的编排层与客观验收仪
 
 > **tianshu-mcp** 是被 **天枢（Tianshu）** 当作标准 MCP server 接入的编排层。天枢是总指挥与用户交互面，本 server 承担三件事：**调度**（队列 / 并发闸 / 状态机 / 取消）、**执行面**（把任务书送达外部 AI-Agent）、**客观验收仪**（相对 git 基线做命令检查、代码分析与可选视觉比对）。
@@ -236,7 +247,7 @@ run_task(projectPath=D:/xxx/my-app, task="…任务书…", agentId=codex,
 | 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`；等待用户确认、取消与重派护栏均已真机验证 |
-| `zcode` | `gui` / `zcode-gui` | **research** | CDP GUI adapter 已实现且 Windows 真机闭环通过；支持无项目派发与 `allowCreateProject`；**v0.7.4 适配 ZCode 3.14.x**（旧 DOM 契约被产品删除 → 绑定判据改为「路径优先、无路径渠道时按显示名 + 全局同名消歧」，同名即 fail-closed） |
+| `zcode` | `gui` / `zcode-gui` | **ready**（Windows 真机闭环；macOS 未验证） | CDP GUI adapter；支持无项目派发、`allowCreateProject` 与 `reasoningLevel`（档位集合**随模型变化**，越权在**发送前**报错）；**v0.7.4 适配 3.14.x 的路径契约缺席**（绑定判据改为「路径优先、无路径渠道时按显示名 + 全局同名消歧」，同名即 fail-closed）；**v0.7.6 修掉绑定死锁**（侧边栏 `workspace-item-*` 滚出视口仍被采集 → 唯一可信的菜单渠道被短路）、**运行期 CDP 断连的恢复入口**（重连观察一次、绝不重发，失败落 `needs_user(setup_recovery)`）与**两级模型菜单**（provider 分组须 hover 才渲染子项） |
 | `traework` | `gui` / `traework-gui` | **ready** | CDP 驱动 TRAE SOLO CN 桌面 UI；支持 `mode`（Work / Code / Design，三种模式各自维护独立项目绑定）；三种面板模式真机验证通过 |
 | `kimicode` | `gui` / `kimicode-gui` | **ready**（macOS 为 `research`） | Kimi Code 桌面端（Electron）；**双渲染进程**（主窗口 + `Kimi Browser Overlay` 浮层承载模型 / 档位 / 模式菜单）；工作区以完整路径绑定；支持 `model` / `reasoningLevel`，**不支持 `mode`**，且**不支持无项目派发** |
 | `qoder` | `gui` / `qoder-gui` | Windows 真机闭环通过；macOS **research** | 仅 Qoder CN；必须提供已有 `projectPath` 与可读 `planDoc`；`modelSource=default\|custom` 消除同名模型歧义，思考等级经「模型管理」保存为全局偏好并回读 |
@@ -384,21 +395,15 @@ run_task(projectPath=D:/xxx/my-app, task="…任务书…", agentId=codex,
 - **更新日志窗口与双源自动更新** —— 启动静默检查更新，命中即弹「更新日志」（下载并安装 / 忽略此版本 / 稍后），正文即该版本的双语发行说明；更新源由 **Gitee / GitHub 并发实测择优**（不依赖系统区域）决定并如实展示，包体经 **minisign 验签**，**验签不通过一律拒绝安装**。
 
 <p align="center">
-  <img src="./assets/tianshu-mcp-gui-overview.png" alt="日志台 · 任务概览页" width="88%">
+  <a href="./assets/tianshu-mcp-gui-overview.png"><img src="./assets/tianshu-mcp-gui-overview.png" alt="日志台 · 任务概览页" width="32%"></a>
+  <a href="./assets/tianshu-mcp-gui-event-stream.png"><img src="./assets/tianshu-mcp-gui-event-stream.png" alt="日志台 · 任务事件流工作区" width="32%"></a>
+  <a href="./assets/tianshu-mcp-gui-agent-log.png"><img src="./assets/tianshu-mcp-gui-agent-log.png" alt="日志台 · Agent 原始日志工作区" width="32%"></a>
   <br>
-  <sub>任务概览页 —— 常驻左侧栏 · 五格指标仪（任务总数 / 进行中 / 已结束 / 已成功 / 已失败）· 状态圆片 · 任务卡网格</sub>
-</p>
-
-<p align="center">
-  <img src="./assets/tianshu-mcp-gui-event-stream.png" alt="日志台 · 任务事件流工作区" width="88%">
+  <b>任务概览页</b> —— 常驻左侧栏 · 五格指标仪（任务总数 / 进行中 / 已结束 / 已成功 / 已失败）· 状态圆片 · 任务卡网格
   <br>
-  <sub>全屏工作区 · 事件流 —— 行 / 时间 / 事件 / 详情四列，状态跃迁与进度记录分色标注</sub>
-</p>
-
-<p align="center">
-  <img src="./assets/tianshu-mcp-gui-agent-log.png" alt="日志台 · Agent 原始日志工作区" width="88%">
+  <b>全屏工作区 · 事件流</b> —— 行 / 时间 / 事件 / 详情四列，状态跃迁与进度记录分色标注
   <br>
-  <sub>全屏工作区 · Agent 日志 —— 级别过滤 · 行号与自动换行 · 「已加载 N / 共 M」与「跳到最新」</sub>
+  <b>全屏工作区 · Agent 日志</b> —— 级别过滤 · 行号与自动换行 · 「已加载 N / 共 M」与「跳到最新」
 </p>
 
 解耦与发布边界（改这里之前先读）：

package/dist/agents/zcode/cdp.js

@@ -2,7 +2,7 @@ import { TraeworkCdpClient, CdpDisconnectedError, CdpUnavailableError, } from ".
 import { candidateExpr } from "./selectors.js";
 import { projectDisplayName } from "./project.js";
 import { normalizeZcodeModelSelection } from "./model.js";
-import { projectTriggerDom, projectTriggerProbeExpression, projectMenuOpenExpression, workOutsideProjectExpression, workspaceBindingExpression, modelSelectionExpression, sendButtonPointExpression, } from "./dom.js";
+import { ZCODE_DOM, projectTriggerDom, projectTriggerProbeExpression, projectMenuOpenExpression, workOutsideProjectExpression, workspaceBindingExpression, modelSelectionExpression, sendButtonPointExpression, } from "./dom.js";
 export { CdpDisconnectedError, CdpUnavailableError };
 export async function retryZcodeEvaluation(operation, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     for (let attempt = 0;; attempt++) {
@@ -156,8 +156,15 @@ export class ZcodeCdpClient {
         await this.clickAt(found.point.x, found.point.y);
         return { clicked: true, count: 1 };
     }
-    async clickExact(key, value) {
-        const found = await this.evaluate(`(async function(){const norm=s=>(s||'').normalize('NFKC').trim().toLocaleLowerCase();const target=norm(${JSON.stringify(value)});const sels=${candidateExpr(key, this.selectors)};const visible=e=>{const r=e.getBoundingClientRect();if(!(r.width>0&&r.height>0&&r.bottom>0&&r.right>0&&r.top<innerHeight&&r.left<innerWidth))return false;const x=Math.max(0,Math.min(innerWidth-1,r.left+r.width/2)),y=Math.max(0,Math.min(innerHeight-1,r.top+r.height/2)),hit=document.elementFromPoint(x,y);return !!hit&&(hit===e||e.contains(hit))};const items=()=>{const out=[];for(const s of sels)for(const e of document.querySelectorAll(s))if(visible(e)&&!out.includes(e))out.push(e);return out};const leafTexts=e=>[...e.querySelectorAll('*')].filter(n=>n.children.length===0).map(n=>(n.textContent||'').trim()).filter(Boolean);const label=e=>(e.getAttribute('data-value')||e.getAttribute('data-model')||e.getAttribute('data-provider')||leafTexts(e)[0]||e.textContent||'').trim();let nodes=items();let scroller=nodes[0];while(scroller&&scroller!==document.body&&scroller.scrollHeight<=scroller.clientHeight)scroller=scroller.parentElement;const start=scroller?.scrollTop||0;if(scroller)scroller.scrollTop=0;const seen=new Map(),seenTestids=new Map(),matches=new Map();for(let i=0;i<60;i++){await new Promise(r=>setTimeout(r,25));nodes=items();for(const e of nodes){const text=label(e);const testid=e.getAttribute('data-testid')||'';const id=e.getAttribute('data-id')||e.getAttribute('data-model-id')||e.getAttribute('data-value')||e.getAttribute('data-model')||e.getAttribute('data-provider')||testid||text;const key=norm(id)+'|'+norm(text);if(testid)seenTestids.set(key,testid);if(!text)continue;seen.set(key,text);if(norm(text)===target)matches.set(key,{top:scroller?.scrollTop||0,text})}if(!scroller||scroller.scrollTop+scroller.clientHeight>=scroller.scrollHeight-1)break;const before=scroller.scrollTop;scroller.scrollTop=Math.min(scroller.scrollTop+Math.max(100,scroller.clientHeight*.8),scroller.scrollHeight);if(scroller.scrollTop===before)break}const result={available:[...seen.values()],testids:[...seenTestids.values()]};const matchesFound=[...matches.values()];if(matchesFound.length===1){if(scroller)scroller.scrollTop=matchesFound[0].top;await new Promise(r=>setTimeout(r,50));const exact=items().filter(e=>norm(label(e))===target);if(exact.length===1){exact[0].scrollIntoView({block:'center'});const r=exact[0].getBoundingClientRect();return {count:1,...result,point:{x:r.left+r.width/2,y:r.top+r.height/2}}}}if(scroller)scroller.scrollTop=start;return {count:matchesFound.length,...result}})()`);
+    /**
+     * 按可见文本精确定位候选项并作用。
+     *
+     * `mode="hover"` 只发 mouseMoved、不发按键：radix 的**二级子菜单**（如模型菜单的
+     * provider 分组）要 hover 才渲染子项，click 会选中分组本身或把菜单收起——
+     * 这是 issue #27「两级模型菜单点击不稳」的真机根因（3.14.3 实测）。
+     */
+    async clickExact(key, value, mode = "click") {
+        const found = await this.evaluate(`(async function(){const norm=s=>(s||'').normalize('NFKC').trim().toLocaleLowerCase();const target=norm(${JSON.stringify(value)});const sels=${candidateExpr(key, this.selectors)};const visible=e=>{const r=e.getBoundingClientRect();if(!(r.width>0&&r.height>0&&r.bottom>0&&r.right>0&&r.top<innerHeight&&r.left<innerWidth))return false;const x=Math.max(0,Math.min(innerWidth-1,r.left+r.width/2)),y=Math.max(0,Math.min(innerHeight-1,r.top+r.height/2)),hit=document.elementFromPoint(x,y);return !!hit&&(hit===e||e.contains(hit))};const items=()=>{const out=[];for(const s of sels)for(const e of document.querySelectorAll(s))if(visible(e)&&!out.includes(e))out.push(e);return out};const leafTexts=e=>[...e.querySelectorAll('*')].filter(n=>n.children.length===0).map(n=>(n.textContent||'').trim()).filter(Boolean);const directText=e=>[...e.childNodes].filter(n=>n.nodeType===3).map(n=>(n.textContent||'').trim()).filter(Boolean).join(' ');const label=e=>(e.getAttribute('data-value')||e.getAttribute('data-model')||e.getAttribute('data-provider')||directText(e)||leafTexts(e)[0]||e.textContent||'').trim();let nodes=items();let scroller=nodes[0];while(scroller&&scroller!==document.body&&scroller.scrollHeight<=scroller.clientHeight)scroller=scroller.parentElement;const start=scroller?.scrollTop||0;if(scroller)scroller.scrollTop=0;const seen=new Map(),seenTestids=new Map(),matches=new Map();for(let i=0;i<60;i++){await new Promise(r=>setTimeout(r,25));nodes=items();for(const e of nodes){const text=label(e);const testid=e.getAttribute('data-testid')||'';const id=e.getAttribute('data-id')||e.getAttribute('data-model-id')||e.getAttribute('data-value')||e.getAttribute('data-model')||e.getAttribute('data-provider')||testid||text;const key=norm(id)+'|'+norm(text);if(testid)seenTestids.set(key,testid);if(!text)continue;seen.set(key,text);if(norm(text)===target)matches.set(key,{top:scroller?.scrollTop||0,text})}if(!scroller||scroller.scrollTop+scroller.clientHeight>=scroller.scrollHeight-1)break;const before=scroller.scrollTop;scroller.scrollTop=Math.min(scroller.scrollTop+Math.max(100,scroller.clientHeight*.8),scroller.scrollHeight);if(scroller.scrollTop===before)break}const result={available:[...seen.values()],testids:[...seenTestids.values()]};const matchesFound=[...matches.values()];if(matchesFound.length===1){if(scroller)scroller.scrollTop=matchesFound[0].top;await new Promise(r=>setTimeout(r,50));const exact=items().filter(e=>norm(label(e))===target);if(exact.length===1){exact[0].scrollIntoView({block:'center'});const r=exact[0].getBoundingClientRect(),x=r.left+r.width/2,y=r.top+r.height/2;const hit=document.elementFromPoint(x,y);if(hit&&(hit===exact[0]||exact[0].contains(hit)))return {count:1,...result,point:{x,y}};return {count:1,...result}}}if(scroller)scroller.scrollTop=start;return {count:matchesFound.length,...result}})()`);
         if (!found.point)
             return {
                 clicked: false,
@@ -165,7 +172,14 @@ export class ZcodeCdpClient {
                 available: found.available,
                 testids: found.testids,
             };
-        await this.clickAt(found.point.x, found.point.y);
+        if (mode === "hover")
+            await this.send("Input.dispatchMouseEvent", {
+                type: "mouseMoved",
+                x: found.point.x,
+                y: found.point.y,
+            });
+        else
+            await this.clickAt(found.point.x, found.point.y);
         return {
             clicked: true,
             count: found.count,
@@ -177,44 +191,136 @@ export class ZcodeCdpClient {
         const raw = await this.evaluate(modelSelectionExpression(this.selectors));
         return normalizeZcodeModelSelection(raw);
     }
+    /**
+     * 采集项目候选（issue #27 修复）。
+     *
+     * 两条渠道**始终合并**，不再用 `if(!out.length)` 短路——3.14.x 下必被视口外的侧边栏
+     * 幽灵项污染，那时短路恒为假，唯一可信的菜单渠道被整条掐掉。
+     * 侧边栏项（旧契约）必须先过 `ZCODE_DOM.visible`：3.14.x 的 `workspace-item-*`
+     * 并未从 DOM 消失，只是尺寸塌陷/被滚出视口，它们不是可信的项目证据。
+     * 同名时菜单项覆盖侧边栏项：只有菜单的 `aria-checked` 是 ZCode 自己渲染的绑定证据。
+     */
+    /**
+     * 思考档位的只读快照（issue #27 问题三）。
+     *
+     * 真机实测（2026-09-30，ZCode 3.14.3-Windows）：档位**选项只在菜单展开时挂载**，
+     * 因此没有挂载任何选项时按需点开一次、读完立刻关闭（不给后续步骤留副作用）。
+     * 只采集原始事实，档位归一与校验交给 model.ts 的纯函数。
+     */
+    async thoughtLevelSnapshot() {
+        const triggerExpr = `(function(){${ZCODE_DOM}
+      const found=pick(${candidateExpr("thoughtLevelTrigger", this.selectors)});
+      return {mounted:found.count?1:0, text:(found.node?.textContent||'').replace(/\\s+/g,' ').trim()};
+    })()`;
+        const optionsExpr = `(function(){${ZCODE_DOM}
+      const out=[];
+      for(const s of ${candidateExpr("thoughtLevelOption", this.selectors)})for(const e of document.querySelectorAll(s)){
+        const r=e.getBoundingClientRect();
+        if(!(r.width&&r.height))continue;
+        const id=e.getAttribute('data-testid')||'';
+        out.push({id,
+          token:id.startsWith('chat-thought-level-select-item-')?id.slice('chat-thought-level-select-item-'.length):'',
+          text:(e.textContent||'').replace(/\\s+/g,' ').trim(),
+          checked:e.getAttribute('aria-checked')==='true'});
+      }
+      return out;
+    })()`;
+        const probe = await this.evaluate(triggerExpr);
+        if (!probe.mounted)
+            return { triggerMounted: false, opened: false, triggerText: probe.text, options: [] };
+        let options = await this.evaluate(optionsExpr);
+        let opened = false;
+        if (!options.length && (await this.click("thoughtLevelTrigger"))) {
+            await this.evaluate(`new Promise(r=>setTimeout(r,250))`);
+            options = await this.evaluate(optionsExpr);
+            opened = options.length > 0;
+            await this.dismissRadixSelect();
+        }
+        const after = await this.evaluate(triggerExpr);
+        return { triggerMounted: true, opened, triggerText: after.text, options };
+    }
+    /** 点击指定 testid 的档位选项（选项需已挂载）。 */
+    async clickThoughtLevelOption(id) {
+        const point = await this.evaluate(`(function(){${ZCODE_DOM}
+        for(const s of ${candidateExpr("thoughtLevelOption", this.selectors)})for(const e of document.querySelectorAll(s)){
+          if((e.getAttribute('data-testid')||'')!==${JSON.stringify(id)})continue;
+          const r=e.getBoundingClientRect();
+          if(!(r.width&&r.height))continue;
+          e.scrollIntoView({block:'center'});
+          const b=e.getBoundingClientRect();
+          return {x:b.left+b.width/2,y:b.top+b.height/2};
+        }
+        return null;
+      })()`);
+        if (!point)
+            return false;
+        await this.clickAt(point.x, point.y);
+        return true;
+    }
+    /**
+     * 关闭 radix select 的 listbox。`dismissMenus` 只认 `[role="menu"]`，
+     * 而档位下拉是 combobox + listbox，需要单独的 Escape。
+     */
+    async dismissRadixSelect() {
+        for (let i = 0; i < 2; i++) {
+            // eslint-disable-next-line no-await-in-loop
+            await this.send("Input.dispatchKeyEvent", {
+                type: "keyDown",
+                key: "Escape",
+                code: "Escape",
+                windowsVirtualKeyCode: 27,
+            });
+            // eslint-disable-next-line no-await-in-loop
+            await this.send("Input.dispatchKeyEvent", {
+                type: "keyUp",
+                key: "Escape",
+                code: "Escape",
+                windowsVirtualKeyCode: 27,
+            });
+            // eslint-disable-next-line no-await-in-loop
+            await this.evaluate(`new Promise(r=>setTimeout(r,120))`);
+        }
+    }
     async projects() {
-        return this.evaluate(`(function(){
-        const norm=s=>(s||'').normalize('NFKC').trim();
-        const out=[],seen=new Set();
-        const push=(name,path,id,checked)=>{
+        return this.evaluate(`(function(){${ZCODE_DOM}
+        const order=[];
+        const byName=new Map();
+        const put=(name,path,id,checked,channel)=>{
           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});
+          const key=norm(n);
+          const previous=byName.get(key);
+          // 菜单渠道优先：同名的侧边栏项被菜单项顶掉；同渠道之间保持先入先得。
+          if(previous&&previous.channel==='menu'&&channel!=='menu')return;
+          if(!previous)order.push(key);
+          byName.set(key,{item:{name:n,path:path||undefined,id:id||undefined,checked},channel});
         };
         for(const s of ${candidateExpr("projectItem", this.selectors)})for(const e of document.querySelectorAll(s)){
+          if(!visible(e))continue;
           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);
+          put(name,p,id,undefined,'sidebar');
         }
         // 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)){
+        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');
+          put(name,undefined,e.getAttribute('data-value')||undefined,e.getAttribute('aria-checked')==='true','menu');
         }
-        return out
+        return order.map(key=>byName.get(key).item)
       })()`);
     }
     async clickProject(id, projectPath) {
         const displayName = projectPath ? projectDisplayName(projectPath) : "";
-        const point = await this.evaluate(`(async function(){${projectTriggerDom(this.selectors)}if(!trigger)return null;const targetName=norm(${JSON.stringify(displayName)});let containers=[];const controlledId=trigger?.getAttribute('aria-controls')||'';if(controlledId){const controlled=document.getElementById(controlledId);if(controlled&&visible(controlled))containers.push(controlled)}if(trigger){let parent=trigger.parentElement;while(parent&&!containers.length){if(parent.querySelector('[role="menuitemcheckbox"]'))containers.push(parent);parent=parent.parentElement}}if(!containers.length)containers=[...document.querySelectorAll('[role="menu"]')].filter(e=>visible(e)&&e.querySelector('[role="menuitemcheckbox"]'));const checkboxMatches=[];for(const container of containers)for(const e of container.querySelectorAll('[role="menuitemcheckbox"]'))if(visible(e)&&norm(e.getAttribute('aria-label')||e.getAttribute('data-value')||e.textContent||'')===targetName&&!checkboxMatches.includes(e))checkboxMatches.push(e);let selected=checkboxMatches.length===1?checkboxMatches[0]:null;if(!selected){const matches=[];for(const s of ${candidateExpr("projectItem", this.selectors)})for(const e of document.querySelectorAll(s)){const testid=e.getAttribute('data-testid')||'';const itemId=e.getAttribute('data-project-id')||e.getAttribute('data-id')||testid;const p=e.getAttribute('data-project-path')||e.querySelector('[data-project-path]')?.getAttribute('data-project-path')||(testid.startsWith('workspace-item-')?testid.slice('workspace-item-'.length):'')||e.getAttribute('title')||'';if(((${JSON.stringify(id ?? "")}&&itemId===${JSON.stringify(id ?? "")})||(${JSON.stringify(projectPath ?? "")}&&p===${JSON.stringify(projectPath ?? "")}))&&!matches.includes(e))matches.push(e)}if(matches.length===1)selected=matches[0]}if(!selected)return null;selected.scrollIntoView({block:'center'});await new Promise(r=>setTimeout(r,50));const r=selected.getBoundingClientRect();return visible(selected)?{x:r.left+r.width/2,y:r.top+r.height/2}:null})()`);
-        if (!point)
-            return false;
-        await this.clickAt(point.x, point.y);
-        return true;
+        const outcome = await this.evaluate(`(async function(){${projectTriggerDom(this.selectors)}if(!trigger)return {reason:'trigger-unavailable'};const targetName=norm(${JSON.stringify(displayName)});let containers=[];const controlledId=trigger?.getAttribute('aria-controls')||'';if(controlledId){const controlled=document.getElementById(controlledId);if(controlled&&visible(controlled))containers.push(controlled)}if(trigger){let parent=trigger.parentElement;while(parent&&!containers.length){if(parent.querySelector('[role="menuitemcheckbox"]'))containers.push(parent);parent=parent.parentElement}}if(!containers.length)containers=[...document.querySelectorAll('[role="menu"]')].filter(e=>visible(e)&&e.querySelector('[role="menuitemcheckbox"]'));const checkboxMatches=[];for(const container of containers)for(const e of container.querySelectorAll('[role="menuitemcheckbox"]'))if(visible(e)&&norm(e.getAttribute('aria-label')||e.getAttribute('data-value')||e.textContent||'')===targetName&&!checkboxMatches.includes(e))checkboxMatches.push(e);let selected=checkboxMatches.length===1?checkboxMatches[0]:null;if(!selected){const matches=[];for(const s of ${candidateExpr("projectItem", this.selectors)})for(const e of document.querySelectorAll(s)){const testid=e.getAttribute('data-testid')||'';const itemId=e.getAttribute('data-project-id')||e.getAttribute('data-id')||testid;const p=e.getAttribute('data-project-path')||e.querySelector('[data-project-path]')?.getAttribute('data-project-path')||(testid.startsWith('workspace-item-')?testid.slice('workspace-item-'.length):'')||e.getAttribute('title')||'';if(((${JSON.stringify(id ?? "")}&&itemId===${JSON.stringify(id ?? "")})||(${JSON.stringify(projectPath ?? "")}&&p===${JSON.stringify(projectPath ?? "")}))&&!matches.includes(e))matches.push(e)}const shown=matches.filter(visible);if(matches.length&&!shown.length)return {reason:'not-visible'};if(shown.length===1)selected=shown[0]}if(!selected)return {reason:'not-found'};selected.scrollIntoView({block:'center'});await new Promise(r=>setTimeout(r,50));const r=selected.getBoundingClientRect();return visible(selected)?{point:{x:r.left+r.width/2,y:r.top+r.height/2}}:{reason:'not-visible'}})()`);
+        if (!("point" in outcome))
+            return { clicked: false, reason: outcome.reason };
+        await this.clickAt(outcome.point.x, outcome.point.y);
+        return { clicked: true, reason: "clicked" };
     }
     async boundProjectPath() {
         return (await this.workspaceBinding()).projectPath;

package/dist/agents/zcode/model.js

@@ -1,12 +1,110 @@
 export class ZcodeModelReadbackError extends Error {
 }
-export function parseZcodeModel(value) {
+/** 思考档位校验失败（值域外或不在界面实际档位集合内）。 */
+export class ZcodeReasoningLevelError extends Error {
+}
+/** 界面 token（testid 后缀或可见文本）→ 规范档位。中英双语都接受。 */
+const THOUGHT_LEVEL_ALIASES = {
+    关闭: "off",
+    关闭思考: "off",
+    off: "off",
+    disabled: "off",
+    开启: "on",
+    on: "on",
+    enabled: "on",
+    低: "low",
+    low: "low",
+    中: "medium",
+    medium: "medium",
+    高: "high",
+    high: "high",
+    max: "max",
+    最大: "max",
+    极高: "max",
+    xhigh: "max",
+};
+/** 档位在错误文案里的界面写法 */
+const THOUGHT_LEVEL_UI = {
+    off: "Off",
+    on: "On",
+    low: "Low",
+    medium: "Medium",
+    high: "High",
+    max: "Max",
+};
+/** 规范顺序（读到的集合按此排序，便于比较与展示） */
+const THOUGHT_LEVEL_ORDER = ["off", "on", "low", "medium", "high", "max"];
+function thoughtKey(value) {
+    return value.normalize("NFKC").trim().replace(/\s+/g, " ").toLocaleLowerCase();
+}
+/** 界面 token → 档位；无法识别返回 undefined（绝不猜） */
+export function thoughtLevelOfToken(token) {
+    const key = thoughtKey(token ?? "");
+    return key ? THOUGHT_LEVEL_ALIASES[key] : undefined;
+}
+/**
+ * 请求值归一。取值域外的值**不归一**，原值放进 unsupportedLevel 供发送前报错——
+ * 静默丢弃会让「请求高档却被沿用当前档」这种偏差无人察觉。
+ */
+export function normalizeZcodeReasoningLevel(value) {
+    const raw = value?.normalize("NFKC").trim() ?? "";
+    if (!raw)
+        return {};
+    const level = thoughtLevelOfToken(raw);
+    return level ? { level } : { unsupported: raw };
+}
+/** 由界面实际档位标签集合归类 */
+export function thoughtTierSetOf(labels) {
+    const levels = new Set();
+    for (const label of labels) {
+        const level = thoughtLevelOfToken(label);
+        if (level)
+            levels.add(level);
+    }
+    const tiers = THOUGHT_LEVEL_ORDER.filter((level) => levels.has(level));
+    if (levels.has("on") && levels.has("off"))
+        return { tiers, kind: "onoff" };
+    return tiers.length ? { tiers, kind: "multi" } : { tiers, kind: "unknown" };
+}
+export function thoughtTierLabels(tiers) {
+    return tiers.tiers.map((level) => THOUGHT_LEVEL_UI[level]).join("/") || "（空）";
+}
+export function thoughtLevelUiName(level) {
+    return THOUGHT_LEVEL_UI[level];
+}
+/**
+ * 校验请求档位是否落在**界面实际档位集合**内。
+ * 读不到档位标签（unknown）一律 fail-closed：宁可报错也不按内置名单猜，
+ * 否则模型/UI 升级后会把不支持的值"成功"发出去。
+ */
+export function assertZcodeLevelSupported(spec, tiers) {
+    if (tiers.kind === "unknown")
+        throw new ZcodeReasoningLevelError(`无法从界面读到模型 ${spec.model} 的思考档位（读到 ${thoughtTierLabels(tiers)}），拒绝猜测档位；请检查 ZCode 版本与选择器`);
+    const labels = thoughtTierLabels(tiers);
+    if (spec.unsupportedLevel !== undefined)
+        throw new ZcodeReasoningLevelError(`模型 ${spec.model} 的思考档位仅支持 ${labels}，收到「${spec.unsupportedLevel}」`);
+    if (spec.level && !tiers.tiers.includes(spec.level))
+        throw new ZcodeReasoningLevelError(`模型 ${spec.model} 的思考档位仅支持 ${labels}，收到「${spec.level}」`);
+}
+/** 参数级（handlers）可取值的取值域错误文案；无错时返回 undefined。 */
+export function describeZcodeLevelValueError(spec) {
+    if (spec.unsupportedLevel === undefined)
+        return undefined;
+    return `ZCode 的思考档位不支持「${spec.unsupportedLevel}」：仅支持 低/low、中/medium、高/high、max、on/off，且必须落在所选模型界面实际渲染的档位集合内`;
+}
+export function parseZcodeModel(value, level) {
     if (!value)
         throw new Error("ZCode 必须指定 model，格式为 供应商/模型");
     const parts = value.split("/");
     if (parts.length !== 2 || !parts[0].trim() || !parts[1].trim())
         throw new Error(`ZCode model 格式错误：${value}（应为 供应商/模型）`);
-    return { provider: parts[0].trim(), model: parts[1].trim() };
+    const normalized = normalizeZcodeReasoningLevel(level);
+    return {
+        provider: parts[0].trim(),
+        model: parts[1].trim(),
+        level: normalized.level,
+        unsupportedLevel: normalized.unsupported,
+    };
 }
 export function exactUiName(a, b) {
     return (a.normalize("NFKC").trim().toLocaleLowerCase() ===

package/dist/agents/zcode/run.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import { ZCODE_SETUP_DEFAULTS } from "../../config/schema.js";
 import { mkdirp } from "../../util/fs.js";
-import { parseZcodeModel, exactUiName, ZcodeModelReadbackError } from "./model.js";
+import { parseZcodeModel, exactUiName, ZcodeModelReadbackError, ZcodeReasoningLevelError, assertZcodeLevelSupported, describeZcodeLevelValueError, thoughtLevelOfToken, thoughtTierSetOf, } from "./model.js";
 import { validateTaskReferences } from "./references.js";
 import { boundProjectVerdict, matchZcodeProject, isUnboundTriggerText, } from "./project.js";
 import { judgeZcodePoll } from "./liveness.js";
@@ -121,11 +121,11 @@ async function connectStableZcode(ready, gui, deps, allowLoginPage = false) {
         ? lastError
         : new Error(`ZCode CDP 未在 ${gui.launchTimeoutMs}ms 内恢复`);
 }
-async function clickExactWhenReady(cdp, key, value, deps) {
+async function clickExactWhenReady(cdp, key, value, deps, mode = "click") {
     let last = { clicked: false, count: 0, available: [] };
     for (let i = 0; i < 15; i++) {
         // eslint-disable-next-line no-await-in-loop
-        last = await cdp.clickExact(key, value);
+        last = await cdp.clickExact(key, value, mode);
         if (last.clicked || last.count > 1)
             return last;
         // eslint-disable-next-line no-await-in-loop
@@ -168,6 +168,18 @@ function describeProjectTriggerFailure(outcome) {
             return "无法打开 ZCode 项目列表：项目触发器始终未挂载（等待项目触发器超时）";
     }
 }
+/**
+ * 运行期 CDP 断连且重连无效（issue #27）：任务已经发出，因此不再判死，
+ * 而是由外层归位到可恢复出口（needs_user/setup_recovery），把现场与已确认的会话
+ * 一起交回用户处理。
+ */
+class ZcodeRuntimeDisconnect extends Error {
+    session;
+    constructor(message, session) {
+        super(message);
+        this.session = session;
+    }
+}
 export async function runZcodeTask(args) {
     const started = Date.now(), { ctx, resolved, opts, logFile } = args, baseDeps = { ...DEFAULT_DEPS, ...args.deps };
     const gui = guiOf(resolved);
@@ -199,6 +211,8 @@ export async function runZcodeTask(args) {
         },
     };
     let cdp;
+    /** 运行期断连时组织诊断文案（进程侧 + 窗口侧）；在发送阶段的护栏里装配。 */
+    let runtimeDiagnosis;
     const result = (extra) => ({
         ok: false,
         exitCode: null,
@@ -211,7 +225,7 @@ export async function runZcodeTask(args) {
     });
     try {
         await mkdirp(path.dirname(logFile));
-        const spec = parseZcodeModel(ctx.model);
+        const spec = parseZcodeModel(ctx.model, ctx.reasoningLevel);
         // 无项目模式（issue #12）：进入 ZCode 的 default 工作区，不解析项目引用、不绑定/导入项目。
         const defaultWorkspace = ctx.workspaceMode === "default";
         const refs = validateTaskReferences(ctx.task, ctx.context, defaultWorkspace ? undefined : ctx.projectPath);
@@ -336,6 +350,94 @@ export async function runZcodeTask(args) {
         let session = activeSession;
         let permission = ctx.resume?.permissionMode ?? gui.defaultPermissionMode ?? "完全访问";
         let answeredQuestion = false;
+        /**
+         * 运行期 CDP 断连的恢复位（issue #27）：单次 evaluate 超时或端点抖动不等于 CDP 已死。
+         * 首次断连只**重连观察一次**（对齐 qoder/run.ts 与 codex/run.ts 的既有范式）——
+         * 重连只用于继续观察，绝不重发任务；重连失败或再次断连才归位到可恢复出口。
+         *
+         * 护栏从**发送阶段**就生效，而不只是主循环：issue 的物理现场正是「任务已经发出、
+         * agent 仍在写产物，MCP 却因一次 poll 失败把任务判死」。
+         */
+        let reconnected = false;
+        /** 已确认发出的会话身份：随断连一起交回，用户 continue_task 时能回到原会话观察。 */
+        const sessionEvidence = () => ({
+            id: session.id,
+            title: session.title,
+            boundProjectPath: ctx.projectPath,
+            provider: spec.provider,
+            model: spec.model,
+            permissionMode: permission,
+        });
+        const reconnectOnce = async () => {
+            try {
+                logger.warn("[zcode] 运行期 CDP 连接中断；重连观察一次（不重发任务）");
+                cdp.disconnect();
+                cdp = await connectStableZcode(ready, { ...gui, launchTimeoutMs: Math.min(gui.launchTimeoutMs, 20_000) }, deps);
+                return true;
+            }
+            catch (error) {
+                logger.error(`[zcode] 运行期 CDP 重连失败：${error instanceof Error ? error.message : String(error)}`);
+                return false;
+            }
+        };
+        const guardRuntimeCdp = async (operation) => {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                const isCdpLoss = error instanceof CdpUnavailableError || error instanceof CdpDisconnectedError;
+                if (!isCdpLoss)
+                    throw error;
+                const message = error instanceof Error ? error.message : String(error);
+                if (!reconnected) {
+                    reconnected = true;
+                    if (await reconnectOnce()) {
+                        logger.info("[zcode] 运行期 CDP 已重连，继续观察原任务（不重发）");
+                        try {
+                            return await operation();
+                        }
+                        catch (retryError) {
+                            if (!(retryError instanceof CdpUnavailableError) &&
+                                !(retryError instanceof CdpDisconnectedError))
+                                throw retryError;
+                            throw new ZcodeRuntimeDisconnect(`ZCode 调试连接在任务运行期重连后再次中断（${retryError instanceof Error ? retryError.message : String(retryError)}）`, sessionEvidence());
+                        }
+                    }
+                }
+                throw new ZcodeRuntimeDisconnect(`ZCode 调试连接在任务运行期中断（${message}）`, sessionEvidence());
+            }
+        };
+        /** 进程侧事实：区分「ZCode 已退出」与「进程还在但端点无响应」——两者的自救动作不同。 */
+        const describeProcessState = async () => {
+            if (!ready.pid)
+                return "未能确认 ZCode 进程 id";
+            try {
+                const processes = await Promise.resolve(deps.listProcesses());
+                return processes.some((process) => process.pid === ready.pid)
+                    ? `ZCode 进程仍在（pid=${ready.pid}）但调试端点无响应`
+                    : `ZCode 进程已退出（pid=${ready.pid} 不在进程表中）——请重启 ZCode 客户端`;
+            }
+            catch (error) {
+                return `ZCode 进程状态不可读：${error instanceof Error ? error.message : String(error)}`;
+            }
+        };
+        /**
+         * 窗口侧事实：issue 的物理现场是「agent 被判死后仍在写产物」，因此断连时必须回读
+         * 窗口内是否仍有运行信号，避免把「仍在跑」误读成「已停」。
+         */
+        const describeRuntimeWindow = async () => {
+            try {
+                const snapshot = await cdp.poll();
+                const running = snapshot.stopVisible || snapshot.loading || snapshot.activeTool;
+                return running
+                    ? "窗口内仍有运行信号（stop/loading/tool-call 可见），任务可能仍在继续"
+                    : "窗口内未见运行信号（任务可能已停止）";
+            }
+            catch {
+                return "窗口状态不可读（调试端点无响应）";
+            }
+        };
+        runtimeDiagnosis = async () => `${await describeProcessState()}；${await describeRuntimeWindow()}`;
         /**
          * 无项目模式的就绪判据：必须确认当前会话真的处于「未绑定项目的 default 工作区」。
          * 「不点击项目按钮」不足以证明——当前 UI 可能继承上一次绑定，所以要求触发器文本
@@ -431,21 +533,35 @@ export async function runZcodeTask(args) {
         /**
          * 幂等确认绑定：每轮先读判定，已绑定即通过；未绑定则（必要时先展开菜单）点击目标项目再复检。
          * 不再接受外部传入的 item——那会把「菜单是否恰好还开着」变成隐式前提（issue #24 暴露的脆弱时序）。
+         *
+         * `unclickable`（issue #27）：所有点击尝试都**从未成功发出一次点击**（`clickProject` 每次
+         * 返回 `clicked:false`，例如目标项在 UI 上不可达）。继续点下去是徒劳——上层据此回落
+         * `selectZcodeFolder` 导入路径，而不是把任务判死在 project_mismatch。
          */
         const ensureProjectBound = async () => {
+            let clickAttempts = 0;
+            let clickFailures = 0;
+            const attemptClick = async (item) => {
+                clickAttempts += 1;
+                const click = await cdp.clickProject(item.id, item.path ?? ctx.projectPath);
+                if (!click.clicked) {
+                    clickFailures += 1;
+                    logger.warn(`[zcode] 项目项点击未生效：reason=${click.reason}；target=${item.name}；尝试=${clickAttempts}`);
+                    return false;
+                }
+                return waitBound(cdp, ctx.projectPath, deps);
+            };
             for (let round = 0; round <= gui.setupRecoveryMaxRetries; round++) {
                 // eslint-disable-next-line no-await-in-loop
                 const { verdict, match } = await readBoundVerdict();
                 if (verdict.bound)
-                    return { bound: true, ambiguous: false };
+                    return { bound: true, ambiguous: false, unclickable: false };
                 if (verdict.ambiguous)
-                    return { bound: false, ambiguous: true };
+                    return { bound: false, ambiguous: true, unclickable: false };
                 if (match.item) {
                     // eslint-disable-next-line no-await-in-loop
-                    const clicked = await cdp.clickProject(match.item.id, match.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 };
+                    if (await attemptClick(match.item))
+                        return { bound: true, ambiguous: false, unclickable: false };
                     continue;
                 }
                 // 目标不在当前列表（菜单多未展开）：显式展开菜单后再采集一次。
@@ -459,16 +575,18 @@ export async function runZcodeTask(args) {
                 // eslint-disable-next-line no-await-in-loop
                 const expanded = matchZcodeProject(await cdp.projects(), ctx.projectPath);
                 if (expanded.ambiguous)
-                    return { bound: false, ambiguous: true };
+                    return { bound: false, ambiguous: true, unclickable: false };
                 if (!expanded.item)
                     continue;
                 // eslint-disable-next-line no-await-in-loop
-                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 };
+                if (await attemptClick(expanded.item))
+                    return { bound: true, ambiguous: false, unclickable: false };
             }
-            return { bound: false, ambiguous: false };
+            return {
+                bound: false,
+                ambiguous: false,
+                unclickable: clickAttempts > 0 && clickFailures === clickAttempts,
+            };
         };
         if (ctx.resume?.kind === "continue" && ctx.resume.sendMessage) {
             const pending = await cdp.poll();
@@ -586,20 +704,33 @@ export async function runZcodeTask(args) {
                         needsUserKind: "setup_recovery",
                         pendingQuestion: "项目路径存在歧义，请在 ZCode 中确认目标项目后调用 continue_task。",
                     });
+                let projectBound = false;
                 if (matched.item) {
                     const binding = await ensureProjectBound();
-                    if (!binding.bound)
+                    projectBound = binding.bound;
+                    if (!projectBound && binding.ambiguous)
+                        return result({
+                            hardFailure: true,
+                            error: `项目绑定重试时目标项目无法唯一匹配：${ctx.projectPath}；${await describeBinding()}`,
+                            endReason: "project_mismatch",
+                            needsUserKind: "setup_recovery",
+                            pendingQuestion: "项目绑定尚未确认，请在 ZCode 中确认目标项目后调用 continue_task。",
+                        });
+                    if (!projectBound && !binding.unclickable)
                         return result({
                             hardFailure: true,
-                            error: binding.ambiguous
-                                ? `项目绑定重试时目标项目无法唯一匹配：${ctx.projectPath}；${await describeBinding()}`
-                                : `ZCode 项目绑定有限重试均未生效：${ctx.projectPath}；${await describeBinding()}`,
+                            error: `ZCode 项目绑定有限重试均未生效：${ctx.projectPath}；${await describeBinding()}`,
                             endReason: "project_mismatch",
                             needsUserKind: "setup_recovery",
                             pendingQuestion: "项目绑定尚未确认，请在 ZCode 中确认目标项目后调用 continue_task。",
                         });
+                    // 目标项就在列表里、却一次点击都没真正落下去（issue #27 的幽灵项/不可达项）：
+                    // 继续重试是徒劳，但也不该直接判死——交给下面的导入路径兜底；
+                    // allowCreateProject=false 时仍在下一道闸门 fail-closed。
+                    if (!projectBound)
+                        logger.warn(`[zcode] 目标项目在列表中但点击始终不生效，回落项目导入路径：${ctx.projectPath}`);
                 }
-                else if (ctx.allowCreateProject === false) {
+                if (!projectBound && ctx.allowCreateProject === false) {
                     // 明确禁止创建：在打开文件夹面板等任何导入副作用之前停止派发。
                     return result({
                         hardFailure: true,
@@ -607,7 +738,7 @@ export async function runZcodeTask(args) {
                         error: `目标目录未在 ZCode 项目列表中登记，且本次调用禁止自动创建项目（allowCreateProject=false）：${ctx.projectPath}。请在 ZCode 中手动添加该项目后重新提交，或省略 allowCreateProject 以允许自动导入。`,
                     });
                 }
-                else {
+                if (!projectBound) {
                     budget.setStage("准备文件夹面板");
                     let pids = [];
                     let before;
@@ -778,11 +909,26 @@ export async function runZcodeTask(args) {
                 let model = await clickExactWhenReady(cdp, "modelOption", spec.model, deps);
                 let provider = { clicked: false, count: 0, available: [] };
                 if (!model.clicked) {
-                    provider = await clickExactWhenReady(cdp, "providerOption", spec.provider, deps);
+                    // issue #27：模型项在 provider 分组的二级子菜单里，**hover 分组**才会渲染子项；
+                    // 用 click 会选中分组本身或收起菜单，这正是「两级模型菜单点击不稳」的根因。
+                    provider = await clickExactWhenReady(cdp, "providerOption", spec.provider, deps, "hover");
                     if (provider.clicked)
-                        await deps.sleep(250);
+                        await deps.sleep(600);
                     model = await clickExactWhenReady(cdp, "modelOption", spec.model, deps);
                 }
+                /**
+                 * issue #27 问题三：radix 子菜单由 hover 维持，press 时子菜单可能已收回——
+                 * 表现为「本轮候选为空」，而不是「模型真的不存在」。此时把菜单重开一次再试一轮，
+                 * 不要凭一轮空列表就把任务判死在 model_unavailable。
+                 */
+                if (!model.clicked && !model.count && !provider.clicked) {
+                    logger.warn("[zcode] 模型项两轮均未命中且候选为空（菜单可能已收起）；重开模型菜单后再试一轮");
+                    await cdp.dismissMenus();
+                    if (await cdp.click("modelTrigger")) {
+                        await deps.sleep(250);
+                        model = await clickExactWhenReady(cdp, "modelOption", spec.model, deps);
+                    }
+                }
                 if (!model.clicked)
                     return result({
                         hardFailure: true,
@@ -803,6 +949,63 @@ export async function runZcodeTask(args) {
                     error: `模型切换回读不一致：display=${modelValue.display || "空"}，internal=${modelValue.internal || "空"}`,
                     endReason: "model_mismatch",
                 });
+            /**
+             * 思考档位（issue #27 问题三）：`reasoningLevel` 此前完全没有实现。
+             *
+             * 档位集合**随模型变化**（真机实测 3.14.3：当前模型只有 开启/关闭 二值），
+             * 所以必须在模型确认之后才读界面；未指定档位时完全不碰界面（沿用当前值）。
+             * 越权档位与「集合读不到」都在**发送前**报错，绝不静默沿用。
+             */
+            if (spec.unsupportedLevel !== undefined)
+                return result({
+                    hardFailure: true,
+                    error: describeZcodeLevelValueError(spec) ??
+                        `ZCode 的思考档位不支持「${spec.unsupportedLevel}」`,
+                    endReason: "reasoning_level_invalid",
+                });
+            if (spec.level) {
+                budget.setStage("确认思考档位");
+                const snapshot = await cdp.thoughtLevelSnapshot();
+                // 控件本身不存在（该版本/该模型不提供档位选择）与「控件存在但读不到选项」是两种失败，
+                // 文案必须区分，否则用户会去翻一个根本不存在的菜单。
+                if (!snapshot.triggerMounted)
+                    return result({
+                        hardFailure: true,
+                        endReason: "reasoning_level_unavailable",
+                        error: "ZCode 界面没有思考档位控件（该版本或该模型不提供档位选择）；请移除 reasoningLevel 后重试",
+                    });
+                const tiers = thoughtTierSetOf(snapshot.options.map((option) => option.token || option.text));
+                assertZcodeLevelSupported(spec, tiers);
+                const current = thoughtLevelOfToken(snapshot.triggerText);
+                if (current === spec.level) {
+                    logger.info(`[zcode] 思考档位已是「${spec.level}」，无需切换`);
+                }
+                else {
+                    const target = snapshot.options.find((option) => thoughtLevelOfToken(option.token || option.text) === spec.level);
+                    if (!target)
+                        return result({
+                            hardFailure: true,
+                            endReason: "reasoning_level_unavailable",
+                            error: `ZCode 思考档位「${spec.level}」在界面上没有对应选项（界面档位=${snapshot.options.map((option) => option.token || option.text).join("、") || "空"}）`,
+                        });
+                    if (!(await cdp.clickThoughtLevelOption(target.id)))
+                        return result({
+                            hardFailure: true,
+                            endReason: "reasoning_level_unavailable",
+                            error: `无法点击 ZCode 思考档位选项：${target.id}（当前显示=${snapshot.triggerText || "空"}）`,
+                        });
+                    await deps.sleep(250);
+                    const applied = await cdp.thoughtLevelSnapshot();
+                    const readback = thoughtLevelOfToken(applied.triggerText);
+                    if (readback !== spec.level)
+                        return result({
+                            hardFailure: true,
+                            endReason: "reasoning_level_mismatch",
+                            error: `ZCode 思考档位回读不一致：期望「${spec.level}」，实际「${applied.triggerText || "空"}」`,
+                        });
+                    logger.info(`[zcode] 思考档位已切换为「${spec.level}」`);
+                }
+            }
             permission = gui.defaultPermissionMode ?? "完全访问";
             if (!exactUiName(await cdp.text("permissionValue"), permission)) {
                 if (!(await cdp.click("permissionTrigger")))
@@ -884,7 +1087,7 @@ export async function runZcodeTask(args) {
                     const [after, input, polled] = await Promise.all([
                         cdp.conversationText(),
                         cdp.inputText(),
-                        cdp.poll(),
+                        guardRuntimeCdp(() => cdp.poll()),
                     ]);
                     seenMessage ||= after.includes(marker);
                     seenStateChange ||= !input.includes(marker);
@@ -941,7 +1144,7 @@ export async function runZcodeTask(args) {
                     error: "ZCode 任务总时限已到；已停止 MCP 等待并保留 ZCode 现场",
                 });
             await deps.sleep(gui.pollIntervalMs);
-            const poll = await cdp.poll();
+            const poll = await guardRuntimeCdp(() => cdp.poll());
             const verdict = judgeZcodePoll(poll, state, gui.stableRounds, gui.idleTimeoutMs);
             state = verdict.state;
             if (Date.now() - lastProgress >= gui.progressIntervalMs) {
@@ -1011,8 +1214,23 @@ export async function runZcodeTask(args) {
             });
         if (e instanceof ZcodeBudgetError)
             return result({ hardFailure: true, endReason: "cdp_disconnected", error: msg });
+        if (e instanceof ZcodeReasoningLevelError)
+            return result({ hardFailure: true, error: msg, endReason: "reasoning_level_invalid" });
         if (e instanceof ZcodeModelReadbackError)
             return result({ hardFailure: true, error: msg, endReason: "model_mismatch" });
+        if (e instanceof ZcodeRuntimeDisconnect) {
+            const diagnosis = runtimeDiagnosis
+                ? await runtimeDiagnosis().catch(() => "窗口状态不可读")
+                : "无法读取 ZCode 窗口状态";
+            // 任务已经发出：不再判死，交回用户处理现场（进程/窗口两侧事实随附），绝不重发。
+            return result({
+                endReason: "needs_user",
+                needsUserKind: "setup_recovery",
+                pendingQuestion: `${msg}。${diagnosis}。请检查 ZCode 客户端后调用 continue_task 继续观察原任务（不会重发任务）。`,
+                session: e.session,
+                progressSummary: "ZCode 运行期 CDP 断连，已保留现场并等待处理",
+            });
+        }
         if (e instanceof CdpDisconnectedError || e instanceof CdpUnavailableError)
             return result({ hardFailure: true, error: msg, endReason: "cdp_disconnected" });
         return result({ hardFailure: true, error: msg, endReason: "internal" });

package/dist/agents/zcode/selectors.js

@@ -120,11 +120,12 @@ export const ZCODE_SELECTORS = {
     providerOption: {
         primary: '[data-testid^="chat-model-select-group-provider:"]',
         fallbacks: [
+            '[data-testid^="chat-model-select-group-registry-provider:"]',
             '[data-testid^="chat-model-select-group-family:"]',
             '[role="option"][data-provider]',
         ],
         verifiedVersion: "3.11.x",
-        note: "3.11.2 分组前缀漂移为 family；家族标签可能不可点，仅作兜底展开",
+        note: "3.11.2 分组前缀漂移为 family；3.14.3 真机实测为 registry-provider（如 chat-model-select-group-registry-provider:new-provider）。模型项在分组的二级子菜单里，必须 hover 分组才渲染（click 会选中/收起）",
     },
     modelOption: {
         primary: '[data-testid^="chat-model-select-item-"][role="menuitemradio"]',
@@ -156,9 +157,26 @@ export const ZCODE_SELECTORS = {
     },
     permissionOption: {
         primary: '[data-testid^="chat-mode-select-item-"][role="option"]',
-        fallbacks: ['[role="option"][data-permission]'],
-        verifiedVersion: "3.11.x",
-        note: "权限候选",
+        fallbacks: [
+            // 3.14.3 真机实测：权限项 role 是 menuitemradio/menuitemcheckbox（不是 option），
+            // 加 role 限制会 0 命中；与 modelOption 一样保留无 role 的兜底候选。
+            '[data-testid^="chat-mode-select-item-"]',
+            '[role="option"][data-permission]',
+        ],
+        verifiedVersion: "3.14.3-Windows",
+        note: "权限候选。真机 testid 形如 chat-mode-select-item-{plan,build,edit,yolo}，可见名是项内的直接文本节点（如「完全访问」），其后还跟着一句说明文本",
+    },
+    thoughtLevelTrigger: {
+        primary: '[data-testid="chat-thought-level-select-trigger"]',
+        fallbacks: ['[role="combobox"][aria-label*="思考"]', '[role="combobox"][data-state]'],
+        verifiedVersion: "3.14.3-Windows",
+        note: "思考档位触发器（combobox）。真机实测（2026-09-30，模型 step-plan/step-5-preview）：存在且可见，文本为当前档位（如「开启」）；档位选项只在菜单展开后挂载",
+    },
+    thoughtLevelOption: {
+        primary: '[data-testid^="chat-thought-level-select-item-"]',
+        fallbacks: ['[role="option"][data-thought-level]'],
+        verifiedVersion: "3.14.3-Windows",
+        note: "思考档位选项。真机实测：testid 后缀为 enabled/disabled（开启/关闭），aria-checked 表示当前档位；档位集合随模型变化，因此集合的唯一判据是这里实际渲染出来的选项",
     },
     workOutsideProject: {
         primary: '[data-testid="composer-work-outside-project"]',

package/dist/mcp/handlers.js

@@ -19,7 +19,7 @@ import { captureBaseline, gitRefExists, } from "../verify/git-baseline.js";
 import { readTextSafe, readJsonSafe } from "../util/fs.js";
 import { readLatestReportSummary } from "../loop/fix-loop.js";
 import { readDirSafe } from "../util/fs.js";
-import { parseZcodeModel } from "../agents/zcode/model.js";
+import { parseZcodeModel, describeZcodeLevelValueError } from "../agents/zcode/model.js";
 import { describeLevelValueError, parseKimicodeModel } from "../agents/kimicode/model.js";
 import { validateTaskReferences } from "../agents/zcode/references.js";
 /** 任务目录里下一可用 report round（避免手动验收覆盖已有 report-0/1…） */
@@ -264,7 +264,12 @@ function runTaskHandler(ctx, defaults, idempotency) {
             if (args.mode !== undefined)
                 return errorResult("ZCode 不支持 mode 参数；请移除 mode 后重试");
             try {
-                parseZcodeModel(args.model);
+                // 参数级只做「格式 + 取值域」校验（issue #27 问题三）：档位集合随模型变化，
+                // 只能在运行期读界面实际渲染的选项，故「越权档位」的判定留给 run.ts。
+                const spec = parseZcodeModel(args.model, args.reasoningLevel);
+                const levelError = describeZcodeLevelValueError(spec);
+                if (levelError)
+                    throw new Error(levelError);
                 validateTaskReferences(args.task, args.context, norm);
             }
             catch (e) {
@@ -451,7 +456,10 @@ async function runTaskWithoutProject(ctx, defaults, args, idempotency) {
         return errorResult("无项目模式不支持 dryRun：没有可静态分析的项目基线与文件树。请提供 projectPath，或移除 dryRun。");
     }
     try {
-        parseZcodeModel(args.model);
+        const spec = parseZcodeModel(args.model, args.reasoningLevel);
+        const levelError = describeZcodeLevelValueError(spec);
+        if (levelError)
+            throw new Error(levelError);
         // 无项目模式不做项目引用解析：识别到本地引用就在发送前说明需要 projectPath。
         validateTaskReferences(args.task, args.context, undefined);
     }

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.5";
+export const MCP_SERVER_VERSION = "0.7.6";

package/package.json

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

package/skills/tianshu-mcp/SKILL.md

@@ -69,7 +69,7 @@ run_task（秒回 taskId，异步）
 | `projectPath` | 必填 | **可省略**（无项目模式，见 §3.4） | 必填 | 必填 | 必填 | 必填（无项目派发现仅支持 zcode） |
 | `model` | **必填**（面板模型名） | **必填**，`供应商/模型` | 可选 | **必填**（界面模型名） | 可选 | **必填**（界面模型名；精确匹配，未命中回显候选） |
 | `modelSource` | ✗ | ✗ | ✗ | ✗ | 可选 `default`/`custom` | ✗ |
-| `reasoningLevel` | `低/中/高`（`low/medium/high`） | ✗ | ✗ | `低/low`、`高/high`、`max`、`on`、`off` | `低/中/高/极高/最大/关闭思考` | ✗ |
+| `reasoningLevel` | `低/中/高`（`low/medium/high`） | `低/low`、`中/medium`、`高/high`、`max`、`on/off`（以界面实际档位为准） | ✗ | `低/low`、`高/high`、`max`、`on`、`off` | `低/中/高/极高/最大/关闭思考` | ✗ |
 | `mode` | ✗ | ✗ | **唯一支持**（`Work`/`Code`/`Design`） | ✗ | ✗ | ✗（用 `designDirection`） |
 | `designDirection` | ✗ | ✗ | ✗ | ✗ | ✗ | **必填**（`原型`/`文档`/`网站复刻`） |
 | `planDoc` | 可选 | ✗ | ✗ | ✗ | **必填**且必须可读 | ✗ |
@@ -92,6 +92,8 @@ run_task（秒回 taskId，异步）
 - **`codex`**（默认，推荐先试）：ChatGPT/Codex 桌面端，MSIX COM 激活 + CDP（Windows 冷启动实测 60–90 秒，首轮偏慢属正常；macOS spawn `.app` + CDP）。
   `model` 必填且用**面板里的模型名**；`planDoc`/`designSystem` 会拼进初始指令且必须存在、在项目内。**不支持 `mode`**。
 - **`zcode`**：ZCode 桌面端（Electron CDP）。`model` 必填 `供应商/模型`（如 `DeepSeek/deepseek-flash`）；发送前确认「完全访问」权限模式；**不支持 `mode`**。支持省略 `projectPath` 的无项目模式（§3.4）。
+  `reasoningLevel` 可选：档位集合**随模型变化**，以界面实际渲染的选项为准（真机实测 3.14.3：当前模型只有 `on`/`off` 两档，触发器 `chat-thought-level-select-trigger`）。传了界面不存在的档位在**发送前**报错（`reasoning_level_invalid`），绝不静默沿用；不传则不触碰档位界面（沿用当前值）。**换模型必须重开任务**（`model` 在 `run_task` 时固化）。
+  项目绑定按「路径优先、无路径时按显示名」分层判定；3.14.x 侧边栏的 `workspace-item-*` 可能仍挂在 DOM 里但被滚出视口（issue #27：实测 42 个中 40 个不可见），采集时按可见性过滤，不可达时回落「打开文件夹」导入路径。
 - **`traework`**：TraeWork / TRAE SOLO CN。`model` 可选；**唯一支持 `mode`**（不传时从任务书文本识别「切换 X 模式」，识别不到保持 `Work`）；实现顺序固定为「新建会话 → 切模式 → 在目标模式内绑定项目」。窗口必须保持可见（发送依赖模拟输入）。**`continue_task` 不支持**。
 - **`kimicode`**：Kimi Code 桌面端（普通 Electron，实测 1.0.2；CDP 基准端口 9666）。`model` 必填，直接填**界面模型名**（如 `K3`、`K2.8 Preview`、`stepfun/step-3.7-flash:free`）。
   `reasoningLevel` 取值域刻意**不含 `中`/`medium`**（那不是任何模型的合法档位）：官方模型 `低/low`、`高/high`、`max`；非官方模型只有 `on`/`off`。档位集合以**界面实际渲染的标签**为准，传了界面不存在的档位在发送前报错，绝不静默沿用；不传时官方档位沿用界面当前值、非官方强制 `on`。