tianshu-mcp 0.6.0 → 0.6.2

package/CHANGELOG.en.md

@@ -8,6 +8,52 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.6.2] - 2026-09-23
+
+### Fixed
+
+- **Codex project-picker trigger copy drifts across versions** ([issue #23](https://github.com/lanlan0811/tianshu-mcp/issues/23), case 1): the trigger's `aria-label` is "选择项目：<name>" on some versions and "切换项目：<name>" on others (26.915, measured locally). `projectPickerTrigger` now covers both copies via primary/fallback/pattern (including the English `Select/Switch project`), and `boundProjectName` reads both back. **A full 20-key hardware audit was run** (`node scripts/probe-codex.mjs --launch audit`): on local 26.915 there is no drift beyond this trigger, and 9 verified keys were bumped to `verifiedVersion: 26.915.x`.
+- **Qoder workspace binding failed on 0.3.4** (issue #23, case 2): a fresh hardware probe **corrected the issue's conclusion** — the 0.3.4 workspace menu **does render**; the real cause is that the page has **two** `[data-workspace-picker-trigger]` elements, and the old single-match `click()` failed as ambiguous. The workspace trigger's primary selector is now the unique `button[aria-label^="切换或清空当前工作区"]` (with `[data-workspace-picker-trigger]` demoted to a fallback); the "menu is open" check is relaxed to "search box **or** overlay". The production `bindWorkspace` now passes on real Qoder 0.3.4.
+- **TraeWork install discovery failed** (issue #23, case 3): added `src/agents/traework/discovery.ts` (fixed-drive enumeration + registry `InstallLocation` + relative paths) with a dedicated `traework-gui` branch in `registry.ts`. Fixed the built-in profile — removed the wrong `{APPDATA}/TRAE SOLO CN` (measured to be the **user-data dir**: Cache/Crashpad/nested tool exes, not the install location) in favor of `{LOCALAPPDATA}/Programs/TRAE SOLO CN` etc., and added `preferredDrives`/`relativePaths`. **On Windows the executable name is narrowed to `TRAE SOLO CN.exe`** (the old list's `Trae CN` mismatched the unrelated TraeCode CN product). `waitReady` timeouts now emit on-site diagnostics (child exit code, port-listener enumeration, detection of existing instances without the debug port) — **diagnosis only: no launch-strategy change, no termination of existing instances**.
+
+### Added
+
+- **Unified selector diagnostics across the three GUI agents** (`src/agents/gui-diagnostics.ts`): on selector-resolution failure the nearest visible page candidates (aria-labels / short texts) are appended to the error and log, so drift can be located in one step without opening CDP by hand. Wired into codex / qoder / traework.
+- **Codex full-key audit mode** `scripts/probe-codex.mjs --launch audit`: prints the primary hit count and matched labels for all 20 selector keys as a "script + evidence table" gate.
+- **Qoder layered selector structure**: `src/agents/qoder/selectors.ts` upgraded from flat strings to `primary/fallbacks/texts/ariaLabels/ariaPatterns/verifiedVersion` (27 keys); `QoderCdpClient.selector()` keeps its string semantics and adds `candidates()/existsKey()/clickKey()`.
+- **TraeWork selector version field unified**: `verified: boolean` → `verifiedVersion: string` (matching codex/kimicode).
+
+### Docs
+
+- New [issue #23 verification record](docs/issue-23-selector-drift-record.md) (20-key audit table, Qoder 0.3.4 re-probe, TraeWork discovery hardware results); release notes [v0.6.2](docs/release-v0.6.2.en.md).
+
+## [0.6.1] - 2026-09-23
+
+### Added
+
+- **Dangerous-directory decision collapsed into a platform-injectable pure function** `isDangerousProjectDir(norm, platform)` (`src/util/path.ts`): exact root / drive root / system-directory subtree, so all three platform shapes are verifiable on any OS.
+
+### Changed
+
+- **`verify_task` capability moves from `read` to `execute`** ([issue #17](https://github.com/lanlan0811/tianshu-mcp/issues/17) item 2): it runs the project's configured commands and may produce build artifacts, so it never was read-only. **Host note**: its MCP `readOnlyHint` changes from `true` to **`false`**; `requireApproval` stays `false` (still approval-free, the R11 conclusion is unchanged) — **policy layers should key off `_meta.requireApproval`, not `readOnlyHint`**. The policy examples in `docs/tianshu-integration` (both languages) are updated.
+- **The `"network"` value, used by no tool at all, is removed from the `ToolDef.capability` union**, collapsed to three families (`read` / `write` / `execute`) documented on the type and in the `tools.ts` header.
+
+### Fixed
+
+- **System directories are now denied as subtrees** (issue #17 item 4): `/etc`, `/usr`, `/bin`, `/sbin`, `/private/etc` plus `c:/windows`, `c:/program files`, `c:/program files (x86)` moved from exact-equality to **boundary-aware subtree denial**, closing leaks such as `c:/windows/system32` and `/etc/anything`. Boundary-awareness keeps `c:/windows.old`, `/etcetera` and `/usrlocal` from being falsely matched; `/var`, `/tmp`, `/opt`, the home directory and friends stay exact-match (on macOS `os.tmpdir()` *is* `/var/folders/...`, so a subtree rule would sever the test base and legitimate workspaces).
+- **Project registration failures are no longer silent** (issue #17 item 3): `run_task` used to discard the `registerProject` return value (`void registered;`) and then re-read the same record via `projectByPath`; it now consumes the return value, drops the redundant read, and on failure logs `WARN` and returns a structured `isError` **without dispatching** (eliminating the "task created but project unregistered" half-state).
+- **Count-vs-reality wrap-up** (issue #17 item 1): the leftover "9 tools" header comment in `test/protocol/protocol.test.ts` is corrected and a `TOOL_DEFS` count assertion added; the lagging "6 scenarios" references in the `ci.yml` comment, `HANDOFF` (two places) and `CONTRIBUTING` (both languages) are synced to **8** (they lagged behind the two skill scenarios added in issue #16).
+
+### Documentation
+
+- **The `cmd` string-form pitfalls made explicit** (issue #17 item 5, zero behaviour change): `docs/acceptance-config.md` / `.en.md` gain a measured table (no escaping, an unclosed quote does not error, an empty quote yields an empty argument), and the `schema.ts` / `store.ts` comments, `SKILL.md` and `usage-examples.md` carry an "always prefer the array form" note.
+- Bilingual: README (`verify_task` capability row + M31 milestone), ARCHITECTURE (three-family tool table + `readOnlyHint` derivation rule + two new §15 gaps), SECURITY (§3 dangerous-directory matching semantics + §5 wording corrected), `docs/tianshu-integration`, `docs/acceptance-config`; single-language: HANDOFF, `SKILL.md`, `usage-examples.md`; new `docs/issue-17-small-fixes-record.md` (measured evidence).
+
+### Tests
+
+- Full suite **940 passed / 12 skipped** (Windows 10 x64, Node 24.18.0), a net **+42** over v0.6.0's 898: `project-dir-guard` gains `isDangerousProjectDir` table-driven cases for all three platform shapes (including the three key counter-examples `c:/windows.old`, `/etcetera`, `/private/var/folders/...`) and a win32 subtree integration case; `protocol` gains an 11-tool × capability × four-annotation **truth table** and a count assertion; `zcode-handler` gains registration-failure-does-not-dispatch and return-value-consumed cases (the latter asserts a `projectByPath` call count of 0); `core` gains `splitCmd` boundary-semantics locks.
+- The strict stdio gate passes **8/8** on both the dist and src entry points; `pack:check` passes (232 files).
+
 ## [0.6.0] - 2026-09-23
 
 ### Added

package/CHANGELOG.md

@@ -7,6 +7,52 @@
 
 ---
 
+## [0.6.2] - 2026-09-23
+
+### 修复
+
+- **Codex 项目选择触发器文案跨版本漂移**（[issue #23](https://github.com/lanlan0811/tianshu-mcp/issues/23) 例 1）：触发器 `aria-label` 在部分版本为「选择项目：<名>」、部分（本机实测 26.915）仍为「切换项目：<名>」。`projectPickerTrigger` 主/回退/模板并列覆盖两文案（含英文 `Select/Switch project`），`boundProjectName` 的项目名回读同步兼容。**并完成全量 20 键真机审计**（`node scripts/probe-codex.mjs --launch audit`）：本机 26.915 除该触发器外无其他漂移，9 个已实测键的 `verifiedVersion` 提升为 `26.915.x`。
+- **Qoder 工作区绑定在 0.3.4 失败**（issue #23 例 2）：真机重探**更正了 issue 的结论**——0.3.4 工作区菜单**并非不渲染**，真因是页面存在**两个** `[data-workspace-picker-trigger]`，旧 `click()` 要求唯一命中而判歧义失败。工作区触发器主选择器改用唯一的 `button[aria-label^="切换或清空当前工作区"]`（`[data-workspace-picker-trigger]` 降为回退）；「菜单已打开」判定放宽为「搜索框 **或** 浮层」。生产 `bindWorkspace` 已在真实 Qoder 0.3.4 上跑通。
+- **TraeWork 安装发现失败**（issue #23 例 3）：新增 `src/agents/traework/discovery.ts`（固定盘枚举 + 注册表 `InstallLocation` + 相对路径），`registry.ts` 增 `traework-gui` 专用分支。修正内置 profile——删除错误的 `{APPDATA}/TRAE SOLO CN`（实测该目录是**用户数据目录**：Cache/Crashpad/嵌套工具 exe，非安装位置），改为 `{LOCALAPPDATA}/Programs/TRAE SOLO CN` 等，并补 `preferredDrives`/`relativePaths`。**Windows 文件名收窄为只认 `TRAE SOLO CN.exe`**（旧清单含 `Trae CN`，会误匹配另一产品 TraeCode CN）。`waitReady` 超时新增现场诊断（子进程退出码、端口监听者枚举、既有未带调试端口实例检测），**只诊断、不改启动策略、不终止既有实例**。
+
+### 新增
+
+- **三 GUI agent 统一的选择器诊断**（`src/agents/gui-diagnostics.ts`）：选择器解析失败时把页面可见候选标签（最接近的 aria-label / 短文本）写进错误与日志，使用者一步定位漂移，无需人工开 CDP。已接入 codex / qoder / traework。
+- **Codex 全键审计模式** `scripts/probe-codex.mjs --launch audit`：对全部 20 个语义键输出 primary 命中数与命中标签，作为「脚本 + 证据表」门禁。
+- **Qoder 选择器分层结构**：`src/agents/qoder/selectors.ts` 由扁平字符串升级为 `primary/fallbacks/texts/ariaLabels/ariaPatterns/verifiedVersion`（27 键）；`QoderCdpClient.selector()` 保留字符串语义，另增 `candidates()/existsKey()/clickKey()`。
+- **TraeWork 选择器版本字段统一**：`verified: boolean` → `verifiedVersion: string`（与 codex/kimicode 一致）。
+
+### 文档
+
+- 新增 [issue #23 验证记录](docs/issue-23-selector-drift-record.md)（含 20 键审计表、Qoder 0.3.4 重探、TraeWork discovery 真机结果）；发布说明 [v0.6.2](docs/release-v0.6.2.md)。
+
+## [0.6.1] - 2026-09-23
+
+### 新增
+
+- **危险目录判定收敛为可注入平台的纯函数** `isDangerousProjectDir(norm, platform)`（`src/util/path.ts`）：精确根 / 盘符根 / 系统目录子树三选一判定，任意平台都能验证三平台形态。
+
+### 变更
+
+- **`verify_task` 的能力由 `read` 改为 `execute`**（[issue #17](https://github.com/lanlan0811/tianshu-mcp/issues/17) 问题 2）：它会执行项目配置命令、可产生构建产物，本就不是只读。**宿主需知**：其 MCP `readOnlyHint` 由 `true` 变为 **`false`**；`requireApproval` 维持 `false`（仍免审批，R11 结论不变）——**策略层请以 `_meta.requireApproval` 而非 `readOnlyHint` 判断是否需授权**，`docs/tianshu-integration` 双语的 policy 示例已同步。
+- **`ToolDef.capability` 联合类型删除始终无人使用的 `"network"`**，收敛为三族语义（`read` / `write` / `execute`），并写进类型定义与 `tools.ts` 头注释。
+
+### 修复
+
+- **系统目录改为子树拒绝**（issue #17 问题 4）：`/etc`、`/usr`、`/bin`、`/sbin`、`/private/etc` 与 `c:/windows`、`c:/program files`、`c:/program files (x86)` 由「仅精确相等」升级为**边界感知子树拒绝**，修补了 `c:/windows/system32`、`/etc/anything` 这类漏挡。边界感知使 `c:/windows.old`、`/etcetera`、`/usrlocal` 不被误伤；`/var`、`/tmp`、`/opt`、用户主目录等维持精确匹配（macOS 的 `os.tmpdir()` 就是 `/var/folders/...`，子树拒绝会切断测试基座与合法工作区）。
+- **项目登记失败不再静默**（issue #17 问题 3）：`run_task` 原先丢弃 `registerProject` 的返回值（`void registered;`）又用 `projectByPath` 二次读取同一条记录；现直接消费返回值、删除冗余读取，登记失败时记 `WARN` 并返回结构化 `isError` 且**不派单**（杜绝「任务已建、项目未登记」的半状态）。
+- **计数与实际不符收尾**（issue #17 问题 1）：改正 `test/protocol/protocol.test.ts` 头注释残留的「9 个工具」，并新增 `TOOL_DEFS` 数量硬断言；`ci.yml` 注释、`HANDOFF`（两处）与 `CONTRIBUTING` 双语滞后的「6 场景」同步为 **8**（issue #16 新增两技能场景后未同步）。
+
+### 文档
+
+- **`cmd` 字符串形态的坑显式化**（issue #17 问题 5，零行为变更）：`docs/acceptance-config.md` / `.en.md` 新增实测表（无转义、引号不闭合不报错、空引号产出空参数），`schema.ts` / `store.ts` 注释、`SKILL.md`、`usage-examples.md` 补「推荐一律用数组形态」提示。
+- 双语：README（`verify_task` 能力列 + M31 里程碑）、ARCHITECTURE（工具表三族语义 + `readOnlyHint` 推导规则 + §15 两条新缺口）、SECURITY（§3 危险目录匹配语义 + §5 措辞改准）、`docs/tianshu-integration`、`docs/acceptance-config`；单语：HANDOFF、`SKILL.md`、`usage-examples.md`；新增 `docs/issue-17-small-fixes-record.md`（实测证据）。
+
+### 测试
+
+- 全量 **940 passed / 12 skipped**（Windows 10 x64，Node 24.18.0），较 v0.6.0 的 898 净增 **42** 项：`project-dir-guard` 新增 `isDangerousProjectDir` 三平台表驱动用例（含 `c:/windows.old`、`/etcetera`、`/private/var/folders/...` 三个关键反例）与 win32 子树集成用例；`protocol` 新增 11 工具 × capability × 四注解**真值表**与数量硬断言；`zcode-handler` 新增登记失败不派单、返回值被消费（断言 `projectByPath` 调用计数为 0）；`core` 新增 `splitCmd` 边界语义锁定。
+- 严格 stdio 门禁 dist 与 src 两条入口各 **8/8**；`pack:check` 通过（232 文件）。
+
 ## [0.6.0] - 2026-09-23
 
 ### 新增

package/README.en.md

@@ -192,7 +192,7 @@ run_task(projectPath=D:/xxx/my-app, agentId=qoder, planDoc=./plans/development.m
 | `list_tasks` | read | Filtered history of tasks |
 | `get_task_report` | read | Full text of a verification round's report (`report.md`) |
 | `cancel_task` | write + approval | Cancel a running task: CLI agents kill the process tree; GUI agents click the in-app stop control over CDP and bounded-wait (`gui.cancelWaitMs`, default 15s) for the GUI to go idle, stating so explicitly in the final message when the stop is unconfirmed. For a terminal GUI task this call doubles as the manual acknowledgement entry point — after verifying the window holds no residual run, it clears the `guiStopUnconfirmed` marker |
-| `verify_task` | read | Run one verification pass on a task/project path (no source changes). Optional `idempotencyKey`: a retry with the same key never re-runs (a running pass answers "in progress", a finished one returns the existing report) |
+| `verify_task` | execute (no source changes, no approval) | Run one verification pass on a task/project path. Capability is `execute`: it runs the project's configured commands and may produce build artifacts, so MCP `readOnlyHint` is `false` — but it **does not modify sources and still needs no approval**. Optional `idempotencyKey`: a retry with the same key never re-runs (a running pass answers "in progress", a finished one returns the existing report) |
 | `rework_task` | write + approval | Manual rework (feed the failure report back to the same agent) |
 | `get_profiles` | read | Inspect agent adapters and executable discovery results |
 | `prepare_visual_baseline` | write + approval | Capture or import reference images into a reviewable candidate with a digest |
@@ -450,6 +450,19 @@ On stderr, `INFO` means skipped/installed; `WARN` means a stale copy was upgrade
   - **Atomic install and log levels**: "tmp dir → backup → swap in", with rollback on failure so no half-copied tree remains; skip = INFO, overwrite/keep/unknown-source/failure = WARN; after an overwrite, historical `.bak-<timestamp>` directories are pruned to `backupKeep`
   - **Gates**: the strict stdio check gains `skill-locally-modified` / `skill-approve-update` scenarios (6→8); Windows 10 real-machine verification R1–R7 recorded in the [issue-16 record](docs/issue-16-skill-install-hardening-record.md)
   - See the [v0.6.0 release notes](<docs/release-v0.6.0.en.md>)
+- **M31 — Small-fixes sweep (comment & count alignment / capability tri-family / registration failure stops dispatch / system-directory subtree denial / splitCmd docs) + v0.6.1** (2026-09-23) — 42 new cases (issue #17)
+  - **System directories now denied by subtree**: `/etc` `/usr` `/bin` `/sbin` `/private/etc` plus `c:/windows` and `c:/program files*` moved from exact-equality to **boundary-aware subtree denial** (`c:/windows.old` and `/etcetera` are not falsely matched). `/var`, `/tmp` and the home directory stay exact-match (`/var/folders/...` on macOS *is* `os.tmpdir()`, so a blanket subtree rule would sever the test base and many legitimate workspaces). The decision is a platform-injectable pure function `isDangerousProjectDir`, so all three platform shapes are verifiable on any OS
+  - **`capability` collapsed to three families**: the never-used `"network"` value is removed; `verify_task` moves from `read` to **`execute`** (it runs project commands and may produce build artifacts, so it never was read-only) — so its `readOnlyHint` flips from `true` to `false`, **but it still needs no approval** (`requireApproval` stays false; the R11 conclusion is unchanged). A new **truth-table test** covers all 11 tools × capability × four annotations
+  - **Project registration failure now stops dispatch**: `run_task` no longer discards the `registerProject` return value (previously `void registered;` was followed by a redundant `projectByPath` re-read); a registration failure logs WARN and returns a structured `isError`, eliminating the "task created but project unregistered" half-state
+  - **`cmd` string form documented**: the bilingual docs and the schema/source comments state "prefer the array form; the string form **supports no escaping**, an unclosed quote does not error, and a typo silently splits into multiple argv". Five boundary cases pin the existing tokenizer semantics (no behaviour change)
+  - **Counts and scenario numbers aligned**: the "9 tools" header comment in `protocol.test.ts` is corrected to 11 and a `TOOL_DEFS` count assertion is added; the "6 scenarios" references in `ci.yml` / `HANDOFF` / `CONTRIBUTING` (both languages) are synced to 8 (they lagged behind the two skill scenarios added in issue #16)
+  - See the [v0.6.1 release notes](<docs/release-v0.6.1.en.md>); verification record in the [issue-17 record](docs/issue-17-small-fixes-record.md)
+- **M32 — GUI selector version-drift fixes (codex / qoder / traework) + v0.6.2** (2026-09-23) — 26 new cases (issue #23)
+  - **Codex**: the project-picker trigger copy drifts across versions (26.915 locally measured "切换项目", 26.917 "选择项目"); primary+fallback now cover both, and `boundProjectName` reads both back. A new `probe-codex.mjs audit` prints a hit table for all 20 keys — **on local 26.915 there is no drift other than this trigger**
+  - **Qoder**: selectors upgraded from flat strings to a layered structure matching Codex (27 keys with `verifiedVersion`). **The hardware re-probe corrected the issue's conclusion**: on 0.3.4 the workspace menu **does render** — the real cause was **two** `[data-workspace-picker-trigger]` elements breaking the single-match click. Switching to the unique `button[aria-label^="切换或清空当前工作区"]` makes the production `bindWorkspace` pass on real 0.3.4
+  - **TraeWork**: added `discovery.ts` (fixed-drive enumeration + registry + relative paths) and fixed the built-in dir (`{APPDATA}/TRAE SOLO CN` is actually the **user-data dir**, not the install location). On Windows the executable name is narrowed to `TRAE SOLO CN.exe` (the old list's `Trae CN` mismatched the unrelated TraeCode CN product); a port-not-ready path now prints diagnostics (exit code / port listeners / existing instances) — **diagnosis only, no launch-strategy change**
+  - **Unified diagnostics**: new `src/agents/gui-diagnostics.ts` appends the nearest visible page candidates to selector-resolution failures across all three GUI agents
+  - See the [v0.6.2 release notes](<docs/release-v0.6.2.en.md>); verification record in the [issue-23 record](docs/issue-23-selector-drift-record.md)
 
 ## Agent support status
 

package/README.md

@@ -188,7 +188,7 @@ run_task(projectPath=D:/xxx/my-app, agentId=qoder, planDoc=./plans/development.m
 | `list_tasks` | read | 历史任务过滤列表 |
 | `get_task_report` | read | 某轮验收报告全文（`report.md`） |
 | `cancel_task` | write + 审批 | 取消运行中任务：CLI agent kill 进程树；GUI agent 经 CDP 点击停止并在 `gui.cancelWaitMs`（默认 15s）内有界等待 GUI 空闲，未确认停止时终态明示。对已终态的 GUI 任务，本调用兼任人工确认入口——核实窗口无残留运行后调用可清除 `guiStopUnconfirmed` 待确认标记 |
-| `verify_task` | read | 对任务/项目路径做一次验收（不改源码）；可选 `idempotencyKey`：同键重试不重跑（执行中返回进行中提示，已完成返回既有报告） |
+| `verify_task` | execute（不改源码，免审批） | 对任务/项目路径做一次验收。能力归 `execute`：会跑项目配置命令、可能产生构建产物，故 MCP `readOnlyHint` 为 `false`——但**不改源码、仍免审批**。可选 `idempotencyKey`：同键重试不重跑（执行中返回进行中提示，已完成返回既有报告） |
 | `rework_task` | write + 审批 | 手动返修（把失败报告喂回同一 agent） |
 | `get_profiles` | read | 查看 agent 适配与可执行探测结果 |
 | `prepare_visual_baseline` | write + 审批 | 截图或导入参考图，生成待审阅候选和摘要 |
@@ -451,6 +451,19 @@ run_task(projectPath=D:/xxx/my-app, agentId=qoder, planDoc=./plans/development.m
   - **安装原子化与日志分级**：改为「tmp 目录 → 备份 → 换入」，失败回滚不留半成品；跳过=INFO、覆盖/保留/来源不明/失败=WARN；覆盖后按 `backupKeep` 收敛历史 `.bak-<时间戳>`
   - **门禁**：严格 stdio 检查新增 `skill-locally-modified` / `skill-approve-update` 两场景（6→8）；Windows 10 真机复验 R1–R7 留档 [issue-16 记录](docs/issue-16-skill-install-hardening-record.md)
   - 详见 [v0.6.0 发布说明](<docs/release-v0.6.0.md>)
+- **M31 — 五项小项扫尾（注释与计数对齐 / capability 三族 / 登记失败不派单 / 系统目录子树拒绝 / splitCmd 文档）+ v0.6.1**（2026-09-23）— 新增 42 项用例（issue #17）
+  - **系统目录改为子树拒绝**：`/etc` `/usr` `/bin` `/sbin` `/private/etc` 与 `c:/windows`、`c:/program files*` 由「仅精确相等」升级为**边界感知子树拒绝**（`c:/windows.old`、`/etcetera` 不误伤）；`/var`、`/tmp`、家目录维持精确匹配（macOS 的 `/var/folders/...` 正是 `os.tmpdir()`，一刀切会切断测试基座与大量合法工作区）。判定抽为可注入平台的纯函数 `isDangerousProjectDir`，任意平台都能验证三平台形态
+  - **`capability` 收敛为三族语义**：删除始终无人使用的 `"network"`；`verify_task` 由 `read` 改为 **`execute`**（会跑项目命令、可产生构建产物，本就不是只读）——连带 `readOnlyHint` 由 `true` 变 `false`，**但仍免审批**（`requireApproval` 维持 false，R11 结论不变）；新增 11 工具 × capability × 四注解的**真值表测试**锁死全部映射
+  - **项目登记失败即终止派单**：`run_task` 不再丢弃 `registerProject` 的返回值（原先 `void registered;` 后还冗余地 `projectByPath` 二次读取）；登记失败时记 WARN 并返回结构化 `isError`，杜绝「任务已建、项目未登记」的半状态
+  - **`cmd` 字符串形态文档化**：双语文档与 schema/代码注释明示「推荐数组形态；字符串形态**不支持转义**、引号不闭合不报错、写错会静默拆成多个 argv」；补 5 条边界用例锁定既有分词语义（零行为变更）
+  - **计数与场景数对齐**：`protocol.test.ts` 头注释「9 个工具」更正为 11 并新增 `TOOL_DEFS` 数量硬断言；`ci.yml` / `HANDOFF` / `CONTRIBUTING` 双语的「6 场景」同步为 8（issue #16 新增两技能场景后未同步）
+  - 详见 [v0.6.1 发布说明](<docs/release-v0.6.1.md>)；验证记录见 [issue-17 记录](docs/issue-17-small-fixes-record.md)
+- **M32 — GUI 选择器版本漂移修复（codex / qoder / traework 三例）+ v0.6.2**（2026-09-23）— 新增 26 项用例（issue #23）
+  - **Codex**：项目选择触发器文案跨版本漂移（26.915 本机实测为「切换项目」，26.917 为「选择项目」），主/回退并列覆盖两文案；`boundProjectName` 回读同步兼容；新增 `probe-codex.mjs audit` 对全部 20 键输出命中表，**本机 26.915 除该触发器外无其他漂移**
+  - **Qoder**：选择器由扁平字符串升级为与 Codex 同构的分层结构（27 键，含 `verifiedVersion`）；**真机重探更正 issue 结论**——0.3.4 工作区菜单**并非不渲染**，真因是页面有**两个** `[data-workspace-picker-trigger]` 致唯一点击判歧义失败；改用唯一的 `button[aria-label^="切换或清空当前工作区"]` 后，生产 `bindWorkspace` 已在真实 0.3.4 跑通
+  - **TraeWork**：新增 `discovery.ts`（固定盘枚举 + 注册表 + 相对路径），修正内置目录（`{APPDATA}/TRAE SOLO CN` 实为**用户数据目录**，非安装位置）；Windows 文件名收窄为只认 `TRAE SOLO CN.exe`（旧清单含 `Trae CN` 会误匹配另一产品 TraeCode CN）；端口未就绪时输出诊断（退出码 / 端口监听者 / 既有实例），**只诊断不改启动策略**
+  - **统一诊断**：新增 `src/agents/gui-diagnostics.ts`，三 GUI agent 在选择器解析失败时把「页面可见候选」写进错误，使用者一步定位漂移
+  - 详见 [v0.6.2 发布说明](<docs/release-v0.6.2.md>)；验证记录见 [issue-23 记录](docs/issue-23-selector-drift-record.md)
 
 ## Agent 适配现状
 

package/dist/agents/builtin.js

@@ -135,20 +135,21 @@ export const BUILTIN_PROFILES = {
         killTree: "taskkill",
         authNote: "复用 TraeWork 桌面端登录态；窗口需保持可见（发送依赖模拟输入）",
         executableDiscovery: {
+            // issue #23 C3：原先写成 {APPDATA}/TRAE SOLO CN（Roaming），实际安装在
+            // {LOCALAPPDATA}/Programs（Local）。补 preferredDrives + relativePaths + 注册表探测
+            // （由 traework/discovery.ts 消费），Windows 只认 TRAE SOLO CN.exe。
             dirs: [
-                "D:/TRAE Work CN",
-                "{PROGRAMFILES}/TRAE WORK CN",
-                "{PROGRAMFILES(X86)}/TRAE WORK CN",
-                "{LOCALAPPDATA}/Programs/TRAE WORK CN",
-                "{LOCALAPPDATA}/TRAE WORK CN",
-                "{APPDATA}/TRAE SOLO CN",
+                "{LOCALAPPDATA}/Programs/TRAE SOLO CN",
+                "{LOCALAPPDATA}/TRAE SOLO CN",
+                "{PROGRAMFILES}/TRAE SOLO CN",
+                "{PROGRAMFILES(X86)}/TRAE SOLO CN",
                 "/Applications/TraeWork.app/Contents/MacOS",
                 "/Applications/Trae CN.app/Contents/MacOS",
             ],
-            fileNames: ["TRAE SOLO CN.exe", "TraeWork", "TraeWork CN", "Trae CN"],
+            fileNames: process.platform === "darwin" ? ["TRAE SOLO CN", "TraeWork", "Trae CN"] : ["TRAE SOLO CN.exe"],
             fallbackCommand: undefined,
-            preferredDrives: [],
-            relativePaths: [],
+            preferredDrives: ["D:"],
+            relativePaths: ["TRAE Work CN/TRAE SOLO CN.exe"],
             installRelativeExe: [],
             scanRoots: [],
         },

package/dist/agents/codex/cdp.js

@@ -6,6 +6,7 @@
  */
 import { TraeworkCdpClient, CdpDisconnectedError, CdpUnavailableError } from "../traework/cdp/client.js";
 import { resolveFnSource, specArgs } from "./selectors.js";
+import { visibleLabelsExpr, normalizeLabels } from "../gui-diagnostics.js";
 export { CdpDisconnectedError, CdpUnavailableError };
 export class CodexCdpClient {
     selectors;
@@ -81,6 +82,20 @@ export class CodexCdpClient {
     async exists(key) {
         return this.evaluate(this.withResolve(`${this.visibleFilter}const els=__codexResolve(${specArgs(key, this.selectors)});return els.some(vis);`));
     }
+    /**
+     * 收集页面可见候选标签（issue #23 诊断机制）：选择器解析失败时，
+     * 把「页面实际有什么」写进错误信息，使用者一步定位漂移（无需人工开 CDP）。
+     * 永不抛错——诊断失败返回空数组，不影响主流程。
+     */
+    async visibleLabels(scopeCss) {
+        try {
+            const raw = await this.evaluate(visibleLabelsExpr({ scope: scopeCss }));
+            return normalizeLabels(raw);
+        }
+        catch {
+            return [];
+        }
+    }
     /** 第一个可见元素文本 */
     async text(key) {
         return ((await this.evaluate(this.withResolve(`${this.visibleFilter}const els=__codexResolve(${specArgs(key, this.selectors)});for(const e of els){if(vis(e))return ((e.value!==undefined?e.value:'')||e.textContent||'').trim()}return '';`))) || "");
@@ -293,7 +308,8 @@ export class CodexCdpClient {
     }
     /**
      * 读取当前会话已绑定的项目名。
-     * 权威信号：输入框内的项目 chip 带 `aria-label="切换项目：<名>"`（未绑定时为「不在项目中工作」）。
+     * 权威信号：输入框内的项目 chip 带 `aria-label="选择项目：<名>"`（26.917 起；
+     * 26.903 及更早为「切换项目：<名>」；未绑定时为「不在项目中工作」）。
      * 真机教训：早期实现把所有非 chip 按钮文本拼起来，会返回整页文案并意外“通过”匹配。
      */
     async boundProjectName() {
@@ -303,7 +319,7 @@ export class CodexCdpClient {
           for(const e of document.querySelectorAll('[aria-label]')){
             if(!vis(e))continue;
             const aria=norm(e.getAttribute('aria-label'));
-            const m=/^(?:切换项目|Switch project)[：:]\\s*(.+)$/i.exec(aria);
+            const m=/^(?:选择项目|切换项目|Select project|Switch project)[：:]\\s*(.+)$/i.exec(aria);
             if(m&&m[1])return m[1].trim();
           }
           return '';

package/dist/agents/codex/run.js

@@ -26,6 +26,7 @@ import { focusCodexApp } from "./launcher.js";
 import { ensureProjectRegistered } from "./registry.js";
 import { buildInitialPrompt } from "./input.js";
 import { validateTaskReferences } from "../zcode/references.js";
+import { withDiagnostics } from "../gui-diagnostics.js";
 const DEFAULT_DEPS = {
     discover: discoverCodex,
     ensureInstance: ensureCodexInstance,
@@ -496,15 +497,24 @@ async function stopGuiTurn(cdp, gui, deps, logger) {
  */
 async function createProject(cdp, projectPath, aumid, gui, deps, logger) {
     // 新建会话后输入框会重渲染，触发器可能短暂缺席 —— 先等它出现再点。
-    if (!(await waitFor(cdp, "projectPickerTrigger", deps, 12_000)))
+    if (!(await waitFor(cdp, "projectPickerTrigger", deps, 12_000))) {
+        // issue #23 诊断机制：解析失败时把页面可见候选一并给出，使用者一步定位文案漂移。
+        const labels = await cdp.visibleLabels();
         return {
             ok: false,
-            error: "新建会话后未出现项目选择触发器（可用 gui.selectors.projectPickerTrigger 热修复）",
+            error: withDiagnostics("新建会话后未出现项目选择触发器（可用 gui.selectors.projectPickerTrigger 热修复）", labels),
         };
+    }
     if (!(await cdp.click("projectPickerTrigger")))
-        return { ok: false, error: "项目选择触发器点击失败" };
+        return {
+            ok: false,
+            error: withDiagnostics("项目选择触发器点击失败", await cdp.visibleLabels()),
+        };
     if (!(await waitFor(cdp, "newProjectMenuItem", deps, 8_000)))
-        return { ok: false, error: "项目选择弹层未出现（找不到「新建项目」项）" };
+        return {
+            ok: false,
+            error: withDiagnostics("项目选择弹层未出现（找不到「新建项目」项）", await cdp.visibleLabels()),
+        };
     const menu = await cdp.clickExact("newProjectMenuItem", "新建项目");
     if (!menu.clicked)
         return {

package/dist/agents/codex/selectors.js

@@ -13,14 +13,14 @@ export const CODEX_SELECTORS = {
         primary: 'div.ProseMirror[contenteditable="true"]',
         fallbacks: ['[contenteditable="true"][role="textbox"]', 'textarea[placeholder]'],
         ariaLabels: ["随心输入", "Type a message", "Message", "输入消息"],
-        verifiedVersion: "26.903.x",
+        verifiedVersion: "26.915.x",
         note: "ProseMirror 富文本输入框；必须走 CDP 输入，不能设 value",
     },
     sendButton: {
         primary: 'button[aria-label="发送"]',
         fallbacks: ['button[aria-label*="Send" i]', 'button[type="submit"]'],
         ariaLabels: ["发送", "Send"],
-        verifiedVersion: "26.903.x",
+        verifiedVersion: "26.915.x",
         note: "条件渲染：输入框为空时不存在，出现即代表可发送",
     },
     stopButton: {
@@ -49,40 +49,52 @@ export const CODEX_SELECTORS = {
         primary: 'button.sidebar-item',
         fallbacks: ['nav button', 'aside button'],
         texts: ["新对话", "New chat"],
-        verifiedVersion: "26.903.x",
+        verifiedVersion: "26.915.x",
         note: "侧边栏新建会话",
     },
     projectSection: {
         primary: 'button[class*="section-toggle"]',
         fallbacks: ['nav button', 'aside button'],
         texts: ["项目", "Projects"],
-        verifiedVersion: "26.903.x",
+        verifiedVersion: "26.915.x",
         note: "侧边栏项目分组开关",
     },
     addProject: {
         primary: 'button[aria-label="添加新项目"]',
         fallbacks: ["button[aria-label*='添加' i]", "button[aria-label*='Add project' i]"],
         ariaLabels: ["添加新项目", "Add new project", "Add project"],
-        verifiedVersion: "26.903.x",
+        verifiedVersion: "26.915.x",
         note: "打开新建项目入口",
     },
     projectPickerTrigger: {
-        // 真机实测：触发器 = aria-label「切换项目：<名>」(aria-haspopup="dialog")。
-        // 注意两点：
+        // issue #23：触发器 aria-label 存在版本间文案漂移。
+        //   - 26.915（本机实测）：仍为「切换项目：<名>」
+        //   - 26.917（issue #23 报告）：已漂移为「选择项目：<名>」
+        // 两者均为 aria-haspopup="dialog"，故主/回退并列覆盖，兼容 26.903 及更早的「切换项目」。
+        // 注意两点（沿用旧结论，不得回归）：
         //  1) 它**不在** ComposerLayout 作用域内；
         //  2) 侧边栏有 aria-label="添加新项目"、输入框另有独立按钮 aria-label="不在项目中工作"
         //     （那是「离开项目」动作，不是触发器）——都不能混入本键，否则会误点。
-        primary: 'button[aria-haspopup="dialog"][aria-label^="切换项目"]',
-        fallbacks: ["button[aria-haspopup='dialog'][aria-label^='Switch project']"],
-        ariaPatterns: ["^切换项目[：:]", "^Switch project[：:]"],
-        verifiedVersion: "26.903.x",
-        note: "输入框内的项目选择触发器（已绑定/未绑定均为「切换项目…」语义）",
+        primary: 'button[aria-haspopup="dialog"][aria-label^="选择项目"]',
+        fallbacks: [
+            'button[aria-haspopup="dialog"][aria-label^="切换项目"]',
+            "button[aria-haspopup='dialog'][aria-label^='Select project']",
+            "button[aria-haspopup='dialog'][aria-label^='Switch project']",
+        ],
+        ariaPatterns: [
+            "^选择项目[：:]",
+            "^切换项目[：:]",
+            "^Select project[：:]",
+            "^Switch project[：:]",
+        ],
+        verifiedVersion: "26.915–26.917",
+        note: "输入框内的项目选择触发器；26.915 实测文案为「切换项目」，issue #23 报告 26.917 为「选择项目」，两者并列命中（含 26.903 及更早）",
     },
     projectItem: {
         primary: 'button[aria-label$="的项目操作"]',
         fallbacks: ["button[aria-label*='project actions' i]"],
         ariaPatterns: ["的项目操作$", "project actions$"],
-        verifiedVersion: "26.903.x",
+        verifiedVersion: "26.915.x",
         note: "项目项（按 aria-label 前缀提取项目名）",
     },
     newProjectMenuItem: {
@@ -144,7 +156,7 @@ export const CODEX_SELECTORS = {
         // 作用域：输入框容器（CSS Module 基名 ComposerLayout 稳定，哈希后缀会变）。
         // 兼容性优先，同时列出 ProseMirror 元素本身。
         scope: '[class*="ComposerLayout"],div.ProseMirror[contenteditable="true"]',
-        verifiedVersion: "26.903.x",
+        verifiedVersion: "26.915.x",
         note: "模型+思考等级菜单触发器；限定在输入框作用域内，排除顶部菜单栏与模式切换器",
     },
     reasoningSlider: {
@@ -178,7 +190,7 @@ export const CODEX_SELECTORS = {
         primary: 'button[aria-label="更改权限"]',
         fallbacks: ["button[aria-label*='权限' i]", "button[aria-label*='permission' i]"],
         ariaLabels: ["更改权限", "Change permission", "Permissions"],
-        verifiedVersion: "26.903.x",
+        verifiedVersion: "26.915.x",
         note: "权限模式触发器（文本如「完全访问」）",
     },
     permissionOption: {
@@ -205,7 +217,7 @@ export const CODEX_SELECTORS = {
             '[class*="MessageList" i]',
             '[class*="message-list" i]',
         ],
-        verifiedVersion: "26.903.x",
+        verifiedVersion: "26.915.x",
         note: "对话正文区域；用于文本稳定兜底判定（勿用裸 main/#root，会混入导航壳）",
     },
 };

package/dist/agents/gui-diagnostics.js

@@ -0,0 +1,81 @@
+/**
+ * GUI 选择器解析失败的统一诊断（issue #23「机制」建议）。
+ *
+ * 三个 GUI agent（codex / qoder / traework）的选择器解析失败信息往往只有
+ * 「未出现 X」——但报告者真正需要的是「页面上实际有什么」。issue #23 的调查里，
+ * 最有价值的线索（`aria-haspopup="dialog"` 恰 1 个、aria-label 已变成「选择项目」）
+ * 是人工打开 CDP 探针才拿到的。本模块把这步自动化：解析失败时把页面可见候选
+ * 标签一并写进错误信息与日志。
+ *
+ * 约定：本模块只产出「页面内表达式」与「文本」，不参与任何控制流或判定，
+ * 因此注入失败、页面无元素等情况都必须安全降级为空候选。
+ */
+export const DEFAULT_DIAGNOSTIC_LIMIT = 20;
+/** 交互元素扫描选择器（与 codex resolve 的 scan 面保持一致，宁可多扫后截断） */
+const DIAGNOSTIC_SCAN = '[aria-label],[role="button"],[role="menuitem"],[role="menuitemradio"],[role="option"],[role="tab"],button,a,label';
+/**
+ * 生成页面内表达式：收集当前可见、带 aria-label 或可见文本的交互元素标签
+ * （归一化、去重、截断）。返回 `string[]`，可直接交给 `cdp.evaluate`。
+ */
+export function visibleLabelsExpr(opts = {}) {
+    const limit = Math.max(1, Math.floor(opts.limit ?? DEFAULT_DIAGNOSTIC_LIMIT));
+    const scopeSel = opts.scope ? JSON.stringify(opts.scope) : "''";
+    const includeText = opts.includeText !== false;
+    const scan = JSON.stringify(DIAGNOSTIC_SCAN);
+    return `(function(){
+    try{
+      var limit=${limit},includeText=${includeText},scopeSel=${scopeSel},scan=${scan};
+      var root=scopeSel?document.querySelector(scopeSel):document;
+      if(!root)return [];
+      var vis=function(e){try{var r=e.getBoundingClientRect();return r.width>0&&r.height>0&&r.bottom>0&&r.right>0&&r.top<innerHeight&&r.left<innerWidth}catch(_){return false}};
+      var norm=function(s){return (s||'').normalize('NFC').replace(/\\s+/g,' ').trim()};
+      var out=[],seen={};
+      var push=function(s){var v=norm(s);if(!v||v.length>80)return;var k=v.toLocaleLowerCase();if(seen[k])return;seen[k]=1;out.push(v)};
+      var nodes=root.querySelectorAll(scan);
+      for(var i=0;i<nodes.length;i++){
+        if(out.length>=limit)break;
+        var e=nodes[i];
+        if(!vis(e))continue;
+        var aria=norm(e.getAttribute('aria-label')||'');
+        if(aria){push(aria);continue}
+        if(includeText){var t=norm(e.innerText||e.textContent||'');if(t&&t.length<=40)push(t)}
+      }
+      return out;
+    }catch(_){return []}
+  })()`;
+}
+/** 从 CDP 返回值安全提取字符串标签数组（过滤非字符串、去重、截断）。 */
+export function normalizeLabels(raw, max = DEFAULT_DIAGNOSTIC_LIMIT) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const item of raw) {
+        if (typeof item !== "string")
+            continue;
+        const v = item.replace(/\s+/g, " ").trim();
+        if (!v)
+            continue;
+        const key = v.toLocaleLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(v);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+/** 把候选标签渲染成错误信息后缀（无候选返回空串）。 */
+export function formatCandidates(labels, max = DEFAULT_DIAGNOSTIC_LIMIT) {
+    const list = normalizeLabels(labels, max);
+    if (!list.length)
+        return "";
+    return `；页面可见候选=[${list.join(" | ")}]`;
+}
+/** 幂等追加诊断：已含候选段时原样返回，避免重复拼接。 */
+export function withDiagnostics(message, labels, max = DEFAULT_DIAGNOSTIC_LIMIT) {
+    if (/页面可见候选=/.test(message))
+        return message;
+    return message + formatCandidates(labels, max);
+}

package/dist/agents/qoder/cdp.js

@@ -1,5 +1,6 @@
 import { TraeworkCdpClient } from '../traework/cdp/client.js';
-import { QODER_SELECTORS } from './selectors.js';
+import { QODER_SELECTORS, qoderCandidates, qoderPrimary } from './selectors.js';
+import { visibleLabelsExpr, normalizeLabels } from '../gui-diagnostics.js';
 import { setTimeout as delay } from 'node:timers/promises';
 const VISIBLE = `(e)=>{
   if(!e||e.closest('[inert],[hidden],[aria-hidden="true"],[role="dialog"][data-state="closed"]'))return false;
@@ -20,7 +21,9 @@ export class QoderCdpClient {
         this.overrides = overrides;
         this.client = new TraeworkCdpClient({ port, sendTimeoutMs: timeout, targetRank: qoderTargetRank });
     }
-    selector(key) { return this.overrides[key] ?? QODER_SELECTORS[key]; }
+    selector(key) { return qoderPrimary(key, this.overrides); }
+    /** 该语义键的全部候选选择器（覆盖优先，其后 primary 与 fallbacks，去重保序） */
+    candidates(key) { return qoderCandidates(key, this.overrides); }
     async connect() {
         await this.client.connect();
         if (qoderTargetRank({ url: await this.evaluate('location.href') }) !== 0) {
@@ -33,8 +36,39 @@ export class QoderCdpClient {
     async sessionId() {
         return this.evaluate(`location.hash.startsWith('#/chat/')?location.hash.split('?')[0].slice(7):undefined`);
     }
+    /** 收集页面可见候选标签（issue #23 诊断机制）；失败安全返回空数组。 */
+    async visibleLabels(scopeCss) {
+        try {
+            return normalizeLabels(await this.evaluate(visibleLabelsExpr({ scope: scopeCss })));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** 按候选顺序探测某语义键是否存在（单次 evaluate，无等待循环，故多候选代价低） */
+    async existsKey(key) {
+        for (const css of this.candidates(key))
+            if (await this.exists(css))
+                return true;
+        return false;
+    }
+    /**
+     * 按候选顺序点击某语义键：先探测哪个候选存在（避免每个候选各自打满超时），
+     * 再对命中的那个执行坐标点击。全部候选都不存在则抛错并附诊断。
+     */
+    async clickKey(key, text, index) {
+        const cands = this.candidates(key);
+        for (const css of cands) {
+            if (await this.exists(css)) {
+                await this.click(css, text, index);
+                return;
+            }
+        }
+        const labels = await this.visibleLabels();
+        throw new Error(`qoder_control_missing_or_ambiguous: ${key}; candidates=${cands.join(' , ')}${labels.length ? `; 页面可见候选=[${labels.join(' | ')}]` : ''}`);
+    }
     async poll() {
-        const s = Object.fromEntries(Object.keys(QODER_SELECTORS).map(k => [k, this.selector(k)]));
+        const s = Object.fromEntries(Object.keys(QODER_SELECTORS).map(k => [k, this.candidates(k).join(',')]));
         return this.evaluate(`(()=>{
       const s=${JSON.stringify(s)},visible=e=>!!e&&!!e.getBoundingClientRect().width&&!e.hidden;
       const user=[...document.querySelectorAll(s.userMessage)].at(-1);
@@ -87,8 +121,10 @@ export class QoderCdpClient {
             if (Date.now() < deadline)
                 await delay(Math.min(100, deadline - Date.now()));
         } while (Date.now() < deadline);
-        if (!point)
-            throw new Error(`qoder_control_missing_or_ambiguous: ${css} ${text ?? ''}`);
+        if (!point) {
+            const labels = await this.visibleLabels();
+            throw new Error(`qoder_control_missing_or_ambiguous: ${css} ${text ?? ''}${labels.length ? `; 页面可见候选=[${labels.join(' | ')}]` : ''}`);
+        }
         await this.client.send('Input.dispatchMouseEvent', { type: 'mousePressed', ...point, button: 'left', clickCount: 1 });
         await this.client.send('Input.dispatchMouseEvent', { type: 'mouseReleased', ...point, button: 'left', clickCount: 1 });
     }