tianshu-mcp 0.6.1 → 0.6.2

package/CHANGELOG.en.md

@@ -8,6 +8,25 @@ 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

package/CHANGELOG.md

@@ -7,6 +7,25 @@
 
 ---
 
+## [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
 
 ### 新增

package/README.en.md

@@ -457,6 +457,12 @@ On stderr, `INFO` means skipped/installed; `WARN` means a stale copy was upgrade
   - **`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

@@ -458,6 +458,12 @@ run_task(projectPath=D:/xxx/my-app, agentId=qoder, planDoc=./plans/development.m
   - **`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 });
     }