@epoint-testtech/ep-stage-skill 0.0.15 → 0.0.17

package/codex-skill/ep-stage/page-element-scan/SKILL.md

@@ -1,91 +1,92 @@
----
-name: page-element-scan
-description: 基于 Playwright 实时渲染识别页面中的可操作元素（按钮、表单字段、列表行操作、标签页、链接等），输出带定位符和可见/可用状态的元素清单（JSON + Markdown）。可与页面源 html 交叉比对，标注「静态有渲染无」「渲染有静态无」的差异证据。当用户想盘点页面元素、摸清页面有哪些按钮和字段、生成页面元素清单、为自动化测试/用例编写摸清页面结构时使用，即使用户只给了一个 URL 也应主动使用本技能。
----
-
-# page-element-scan — 页面可操作元素识别
-
-## 用途
-
-对指定页面做一次「可操作元素盘点」：用 Playwright 真实渲染页面，提取所有用户可操作的元素，并为每个元素给出 Playwright 可用的定位符。
-
-与静态读 html 源码的区别：运行时渲染才能回答「这个元素用户到底看不看得到、点不点得动」。 MiniUI 等框架会把声明式标记渲染成复杂 DOM，权限控制会让部分元素渲染时隐藏，脚本会动态创建新元素——这些只有渲染结果能告诉我们。如果用户同时提供了页面源 html，本技能会做双证据比对：
-
-- `both`：源码声明且渲染确认 —— 最可信
-- `runtime-only`：渲染时才出现（脚本动态创建）—— 静态分析会漏掉
-- `source-only`：源码声明但渲染时不可见（权限隐藏/逻辑移除）—— 对最终用户不可操作
-
-## 输入收集
-
-开始扫描前，向用户确认以下信息（能从上下文推断就不要再问）：
-
-1. **目标 URL**（必填）。本地 html 文件用 `file:///` 绝对路径。
-2. **登录方式**（如需要）：账号密码，或已有的 Playwright storage-state 文件。若当前目录是胶水/e2e 项目且有 `.env`（含 `LOGIN_SYSTEM_URL` / `LOGIN_USERNAME` / `LOGIN_PASSWORD`），直接读取复用，不要问用户要密码。
-3. **源 html 路径**（可选）：有就给 `--source`，触发双证据比对。
-4. **输出位置**：默认 `./page-elements/` 下，`<页面名>.json` + `<页面名>.md`。
-
-## 执行步骤
-
-1. 确定一个安装了 playwright 的工作目录作为 `--project-dir`：当前项目根、或 `e2e-test/` 下任一胶水项目（它们的 node_modules 里有 playwright）。脚本用 `createRequire` 从该目录解析依赖。
-
-2. 运行扫描脚本（路径相对于本技能目录）：
-
-```bash
-node <技能目录>/scripts/scan-page.mjs \
-  --url "<目标URL>" \
-  --out "<输出>.json" --md "<输出>.md" \
-  --project-dir "<含playwright的目录>"
-```
-
-按需追加：
-- 登录：`--login-url <登录页> --login-user <账号> --login-pass <密码>`（启发式填用户名密码框）；启发式失败时用 `--login-user-selector` / `--login-pass-selector` / `--login-submit-selector` 显式指定。
-- 登录态复用：`--storage-state <state.json>`。
-- 双证据：`--source <页面源html>`。
-- 渲染不充分时加大 `--wait 3000`；调试时 `--headed` 看浏览器实际行为。
-
-3. 脚本默认扫描主 frame 和所有子 frame（epoint 页面常嵌 iframe），每个元素的 `frame` 字段标注来源；跨域 frame 会自动跳过。
-
-## 结果呈现
-
-扫描完成后读 JSON，向用户汇报：
-
-1. **概览**：元素总数、可操作数、按类型分布（button / field / grid / tab / link）。
-2. **值得注意的发现**（这是盘点的价值所在，不要只报数字）：
-   - 渲染时隐藏或禁用的元素（可能受权限/状态控制）
-   - `runtime-only` 元素（动态创建，静态分析发现不了）
-   - `source-only` 元素（声明了但用户看不到）
-   - grid 的行操作和列信息
-3. 文件路径，提示 JSON 里的 `locator` 可直接用于 Playwright 脚本。
-
-## 输出格式
-
-JSON 结构：
-
-```json
-{
-  "url": "...", "title": "...", "scannedAt": "...",
-  "summary": { "total": 42, "byType": {"button": 8, "field": 12}, "actionable": 35,
-               "hiddenAtRuntime": 2, "runtimeOnly": 3, "sourceOnly": 1 },
-  "dialogs": [{"trigger": "openChild", "title": "新增窗口", "pagePath": "xxx.html"}],
-  "elements": [
-    { "type": "button", "label": "新增", "locator": "xpath=//a[contains(@class,'mini-button')]...",
-      "visible": true, "enabled": true, "evidence": "both", "frame": "main" }
-  ]
-}
-```
-
-`dialogs` 仅 `--source` 模式产出（从 script 中解析 openTopDialog 调用）。
-
-## 边界与须知
-
-- 「可操作」判定 = 可见（非 display:none、有尺寸）且可用（非 disabled）。默认输出过滤不可见元素，`--include-hidden` 可保留。
-- 脚本不做交互（不点按钮、不开弹窗）。弹窗/二级页面内的元素需把对应 URL 再扫一遍，或先用 `--headed` 观察交互路径。
-- 登录启发式覆盖常见登录页；复杂登录（验证码、SSO 跳转）失败时，让用户手动登录后用 `--storage-state` 重试。
-- 元素去重键是 `type|label|locator`，同 label 不同类型控件不会合并。
-- **已知覆盖范围**（已验证于真实 epoint MiniUI 页面）：
-  - 按钮：MiniUI `a.mini-button`、epoint `a.cond-srh-btn`（搜索按钮）、原生 `button`、`[role=button]`
-  - 字段：`div[label]` 包装的 MiniUI 控件（textbox/combobox/buttonedit/datepicker/spinner）、原生 `input/select/textarea`
-  - Grid：`mini-datagrid` 的 `.mini-grid-headertxt` 列名 + `[data-tooltip]` 行操作图标
-  - 标签页：`.mini-tabs li`
-  - 噪音过滤：无 label 的分页跳页输入框（`pagination-number`）等无业务意义输入不输出
-- **双证据实现说明**：源码侧使用 `DOMParser` 解析 HTML（不执行脚本），得到纯声明态 DOM；运行时侧用 Playwright 渲染；两者按 type+label 比对后标注 `both / runtime-only / source-only`。`setContent` 方案会执行内联脚本导致 evidence 误标，已废弃。
+---
+name: page-element-scan
+description: 使用时机：当用户想盘点页面元素、摸清页面有哪些按钮和字段、生成页面元素清单、为自动化测试/用例编写摸清页面结构时使用，即使用户只给了一个 URL 也应主动使用本技能。基于 Playwright 实时渲染识别页面中的可操作元素（按钮、表单字段、列表行操作、标签页、链接等），输出带定位符和可见/可用状态的元素清单（JSON + Markdown）。可与页面源 html 交叉比对，标注「静态有渲染无」「渲染有静态无」的差异证据。
+version: 2026-08-20+6cf6d2e
+---
+
+# page-element-scan — 页面可操作元素识别
+
+## 用途
+
+对指定页面做一次「可操作元素盘点」：用 Playwright 真实渲染页面，提取所有用户可操作的元素，并为每个元素给出 Playwright 可用的定位符。
+
+与静态读 html 源码的区别：运行时渲染才能回答「这个元素用户到底看不看得到、点不点得动」。 MiniUI 等框架会把声明式标记渲染成复杂 DOM，权限控制会让部分元素渲染时隐藏，脚本会动态创建新元素——这些只有渲染结果能告诉我们。如果用户同时提供了页面源 html，本技能会做双证据比对：
+
+- `both`：源码声明且渲染确认 —— 最可信
+- `runtime-only`：渲染时才出现（脚本动态创建）—— 静态分析会漏掉
+- `source-only`：源码声明但渲染时不可见（权限隐藏/逻辑移除）—— 对最终用户不可操作
+
+## 输入收集
+
+开始扫描前，向用户确认以下信息（能从上下文推断就不要再问）：
+
+1. **目标 URL**（必填）。本地 html 文件用 `file:///` 绝对路径。
+2. **登录方式**（如需要）：账号密码，或已有的 Playwright storage-state 文件。若当前目录是胶水/e2e 项目且有 `.env`（含 `LOGIN_SYSTEM_URL` / `LOGIN_USERNAME` / `LOGIN_PASSWORD`），直接读取复用，不要问用户要密码。
+3. **源 html 路径**（可选）：有就给 `--source`，触发双证据比对。
+4. **输出位置**：默认 `./page-elements/` 下，`<页面名>.json` + `<页面名>.md`。
+
+## 执行步骤
+
+1. 确定一个安装了 playwright 的工作目录作为 `--project-dir`：当前项目根、或 `e2e-test/` 下任一胶水项目（它们的 node_modules 里有 playwright）。脚本用 `createRequire` 从该目录解析依赖。
+
+2. 运行扫描脚本（路径相对于本技能目录）：
+
+```bash
+node <技能目录>/scripts/scan-page.mjs \
+  --url "<目标URL>" \
+  --out "<输出>.json" --md "<输出>.md" \
+  --project-dir "<含playwright的目录>"
+```
+
+按需追加：
+- 登录：`--login-url <登录页> --login-user <账号> --login-pass <密码>`（启发式填用户名密码框）；启发式失败时用 `--login-user-selector` / `--login-pass-selector` / `--login-submit-selector` 显式指定。
+- 登录态复用：`--storage-state <state.json>`。
+- 双证据：`--source <页面源html>`。
+- 渲染不充分时加大 `--wait 3000`；调试时 `--headed` 看浏览器实际行为。
+
+3. 脚本默认扫描主 frame 和所有子 frame（epoint 页面常嵌 iframe），每个元素的 `frame` 字段标注来源；跨域 frame 会自动跳过。
+
+## 结果呈现
+
+扫描完成后读 JSON，向用户汇报：
+
+1. **概览**：元素总数、可操作数、按类型分布（button / field / grid / tab / link）。
+2. **值得注意的发现**（这是盘点的价值所在，不要只报数字）：
+   - 渲染时隐藏或禁用的元素（可能受权限/状态控制）
+   - `runtime-only` 元素（动态创建，静态分析发现不了）
+   - `source-only` 元素（声明了但用户看不到）
+   - grid 的行操作和列信息
+3. 文件路径，提示 JSON 里的 `locator` 可直接用于 Playwright 脚本。
+
+## 输出格式
+
+JSON 结构：
+
+```json
+{
+  "url": "...", "title": "...", "scannedAt": "...",
+  "summary": { "total": 42, "byType": {"button": 8, "field": 12}, "actionable": 35,
+               "hiddenAtRuntime": 2, "runtimeOnly": 3, "sourceOnly": 1 },
+  "dialogs": [{"trigger": "openChild", "title": "新增窗口", "pagePath": "xxx.html"}],
+  "elements": [
+    { "type": "button", "label": "新增", "locator": "xpath=//a[contains(@class,'mini-button')]...",
+      "visible": true, "enabled": true, "evidence": "both", "frame": "main" }
+  ]
+}
+```
+
+`dialogs` 仅 `--source` 模式产出（从 script 中解析 openTopDialog 调用）。
+
+## 边界与须知
+
+- 「可操作」判定 = 可见（非 display:none、有尺寸）且可用（非 disabled）。默认输出过滤不可见元素，`--include-hidden` 可保留。
+- 脚本不做交互（不点按钮、不开弹窗）。弹窗/二级页面内的元素需把对应 URL 再扫一遍，或先用 `--headed` 观察交互路径。
+- 登录启发式覆盖常见登录页；复杂登录（验证码、SSO 跳转）失败时，让用户手动登录后用 `--storage-state` 重试。
+- 元素去重键是 `type|label|locator`，同 label 不同类型控件不会合并。
+- **已知覆盖范围**（已验证于真实 epoint MiniUI 页面）：
+  - 按钮：MiniUI `a.mini-button`、epoint `a.cond-srh-btn`（搜索按钮）、原生 `button`、`[role=button]`
+  - 字段：`div[label]` 包装的 MiniUI 控件（textbox/combobox/buttonedit/datepicker/spinner）、原生 `input/select/textarea`
+  - Grid：`mini-datagrid` 的 `.mini-grid-headertxt` 列名 + `[data-tooltip]` 行操作图标
+  - 标签页：`.mini-tabs li`
+  - 噪音过滤：无 label 的分页跳页输入框（`pagination-number`）等无业务意义输入不输出
+- **双证据实现说明**：源码侧使用 `DOMParser` 解析 HTML（不执行脚本），得到纯声明态 DOM；运行时侧用 Playwright 渲染；两者按 type+label 比对后标注 `both / runtime-only / source-only`。`setContent` 方案会执行内联脚本导致 evidence 误标，已废弃。

package/codex-skill/ep-stage/scripts/validate-skill.mjs

@@ -55,15 +55,18 @@ function assertSymlink(linkPath, targetPath) {
   }
 }
 
-// ep-stage scope 下四个 skill 的包内真相源目录。
+// ep-stage scope 下全部六个 skill 的包内真相源目录。
 // 注：Task 0.2 已 git mv 改名 3 个 skill 目录（glue-* 前缀化）。
 // - glue-create-project：Task 2.1 已同步 SKILL.md frontmatter name → 'glue-create-project'。
 // - glue-generate-testcase：Task 3.2 已同步 SKILL.md frontmatter name → 'glue-generate-testcase'。
 // - glue-run-test：Task 4.3 已同步 SKILL.md frontmatter name → 'glue-run-test'。
+// 2026-08-20：补登 code-list-generate / page-element-scan（此前漏登，frontmatter 不受校验）。
 const skillSources = [
+  { name: 'code-list-generate', source: path.join(epStageRoot, 'code-list-generate') },
   { name: 'glue-create-project', source: path.join(epStageRoot, 'glue-create-project') },
   { name: 'glue-generate-testcase', source: path.join(epStageRoot, 'glue-generate-testcase') },
   { name: 'glue-run-test', source: path.join(epStageRoot, 'glue-run-test') },
+  { name: 'page-element-scan', source: path.join(epStageRoot, 'page-element-scan') },
   { name: 'recording-to-glue', source: path.join(epStageRoot, 'recording-to-glue') },
 ];
 

package/dist/src/cli/calibrate.d.ts

@@ -0,0 +1,75 @@
+/**
+ * calibrate 子命令：运行时校准回路（A 支柱）。
+ *
+ * 输入 page-element-scan 产出的 elementmap.json（运行时真实控件形态），按确定性规则
+ * 改写 contract.json5 的组件类型与定位符槽位，使静态装配与运行时实据对齐。
+ *
+ * 契约写入纪律（双写入者）：contract 只允许 assembler（静态事实）与本 calibrator
+ * （运行时实据）两个写入者，均机器执行 + 账本落盘（calibration-report.json）+
+ * 过同一 validateContract 门禁；Agent 不手编 contract。
+ *
+ * 校准规则表（高置信自动改，低置信落 unresolvedSlots 人审）：
+ * - R1-R4 查询字段 label 命中且 controlType 映射为白名单类型 → 改 component + 重建 slot；
+ * - R5 label 命中但 controlType 未识别 → 不改契约，unresolvedSlots += unsupported_query_component；
+ * - R6 searchFields label 在 elementmap 未命中 → unresolvedSlots += query_field_not_found；
+ * - R7 导出按钮定位符与 elementmap 实据不一致 → 用实据覆盖 exportButton；
+ * - R8 elementmap 无「查询/搜索」按钮 → unresolvedSlots += search_submit_unverified；
+ * - R9 elementmap 存在导出面板证据（待选列/已选列）→ 注入 exportContainer 语义锚点。
+ *
+ * 默认 dry-run（只打印变更计划）；--write 才落盘并级联重生成 spec / 重渲染 testcase.md。
+ * 组件类别变化导致用例文案变化时，该用例 reviewStatus 拨回 needs_review（机器改语义必人审）。
+ */
+import type { UnresolvedSlotRecord } from '../contracts/glue-contract-v1.js';
+/**
+ * calibrate 子命令参数。
+ */
+export type CalibrateArgs = {
+    /** testcase.json5 路径 */
+    testcase: string;
+    /** elementmap.json 路径（缺省 <caseDir>/.ep-stage/elementmap.json） */
+    elementmap?: string;
+    /** true 时落盘并级联重生成；缺省 dry-run 只打印变更计划 */
+    write: boolean;
+};
+/** 校准变更记录。 */
+export type CalibrationChange = {
+    slotPath: string;
+    from: string;
+    to: string;
+    rule: string;
+    evidence: {
+        label?: string;
+        locator?: string;
+        controlType?: string;
+    };
+};
+/**
+ * calibrate 子命令产物。
+ */
+export type CalibrateResult = {
+    reportPath: string;
+    changes: CalibrationChange[];
+    unresolvedAdded: UnresolvedSlotRecord[];
+    /** 因组件变化被拨回 needs_review 的用例 ID 清单 */
+    casesPatched: string[];
+    /** 是否已落盘（false = dry-run） */
+    written: boolean;
+    /** 是否已级联重生成 spec（用例拨回 needs_review 时跳过，待人工确认后由 prepare-tasks/run 补齐） */
+    specRegenerated: boolean;
+};
+/**
+ * 解析 calibrate 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns CalibrateArgs。
+ */
+export declare function parseCalibrateArgs(argv: string[]): CalibrateArgs;
+/**
+ * 执行运行时校准。
+ *
+ * @param args - calibrate 参数。
+ * @returns CalibrateResult。
+ * @throws elementmap 缺失 / 校验门禁失败（不落盘）时抛错。
+ */
+export declare function runCalibrate(args: CalibrateArgs): CalibrateResult;
+//# sourceMappingURL=calibrate.d.ts.map

package/dist/src/cli/calibrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calibrate.d.ts","sourceRoot":"","sources":["../../../src/cli/calibrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAUH,OAAO,KAAK,EAA0B,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAoBrG;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,cAAc;AACd,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,eAAe,EAAE,oBAAoB,EAAE,CAAC;IACxC,sCAAsC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6BAA6B;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAmBhE;AAoED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CA8NjE"}

package/dist/src/cli/calibrate.js

@@ -0,0 +1,318 @@
+/**
+ * calibrate 子命令：运行时校准回路（A 支柱）。
+ *
+ * 输入 page-element-scan 产出的 elementmap.json（运行时真实控件形态），按确定性规则
+ * 改写 contract.json5 的组件类型与定位符槽位，使静态装配与运行时实据对齐。
+ *
+ * 契约写入纪律（双写入者）：contract 只允许 assembler（静态事实）与本 calibrator
+ * （运行时实据）两个写入者，均机器执行 + 账本落盘（calibration-report.json）+
+ * 过同一 validateContract 门禁；Agent 不手编 contract。
+ *
+ * 校准规则表（高置信自动改，低置信落 unresolvedSlots 人审）：
+ * - R1-R4 查询字段 label 命中且 controlType 映射为白名单类型 → 改 component + 重建 slot；
+ * - R5 label 命中但 controlType 未识别 → 不改契约，unresolvedSlots += unsupported_query_component；
+ * - R6 searchFields label 在 elementmap 未命中 → unresolvedSlots += query_field_not_found；
+ * - R7 导出按钮定位符与 elementmap 实据不一致 → 用实据覆盖 exportButton；
+ * - R8 elementmap 无「查询/搜索」按钮 → unresolvedSlots += search_submit_unverified；
+ * - R9 elementmap 存在导出面板证据（待选列/已选列）→ 注入 exportContainer 语义锚点。
+ *
+ * 默认 dry-run（只打印变更计划）；--write 才落盘并级联重生成 spec / 重渲染 testcase.md。
+ * 组件类别变化导致用例文案变化时，该用例 reviewStatus 拨回 needs_review（机器改语义必人审）。
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import JSON5 from 'json5';
+import { validateContract } from '../validation/contract.js';
+import { validateTestcase } from '../validation/testcase.js';
+import { renderUnifiedTestcaseMarkdown } from '../testcase/testcase-markdown.js';
+import { buildGlueExecutionFields } from '../testcase/contract-testcase-assembler.js';
+import { resolveQueryComponent } from '../testcase/query-component-map.js';
+import { resolveRunPaths } from './run.js';
+import { runSpec } from './spec.js';
+/**
+ * 解析 calibrate 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns CalibrateArgs。
+ */
+export function parseCalibrateArgs(argv) {
+    const result = {};
+    const flags = new Set();
+    const normalizedArgv = argv.filter((arg) => arg !== '--');
+    for (let index = 0; index < normalizedArgv.length; index++) {
+        const key = normalizedArgv[index];
+        if (key === '--write') {
+            flags.add('write');
+            continue;
+        }
+        const value = normalizedArgv[index + 1];
+        if (!key?.startsWith('--') || !value || value.startsWith('--')) {
+            throw new Error(`无效参数对: ${key ?? '<empty>'}`);
+        }
+        result[key.slice(2).replace(/-([a-z])/g, (_, char) => char.toUpperCase())] = value;
+        index += 1;
+    }
+    if (!result.testcase)
+        throw new Error('缺少 --testcase');
+    return { testcase: result.testcase, elementmap: result.elementmap, write: flags.has('write') };
+}
+/** 24 小时（elementmap 新鲜度阈值）。 */
+const ELEMENTMAP_STALE_MS = 24 * 60 * 60 * 1000;
+/**
+ * 按校准后组件类型重建 searchConditions 槽位（与装配器槽位形状镜像）。
+ *
+ * @param kind - 校准后组件类型。
+ * @param field - 字段名。
+ * @param label - 中文标签。
+ * @param runtimeLocator - elementmap 实据定位器（可选）。
+ * @param existingSlot - 既有槽位（listbox 的 createSelections 等需保留）。
+ * @returns 新槽位对象。
+ */
+function buildCalibratedSlot(kind, field, label, runtimeLocator, existingSlot) {
+    const inputLocator = runtimeLocator ?? `xpath=//div[@label='${label}']//input`;
+    if (kind === 'input') {
+        return {
+            component: 'input',
+            field,
+            label,
+            seedValue: existingSlot?.seedValue ?? '测试数据',
+            strategy: 'timestamp_prefix',
+            addLocator: inputLocator,
+            editLocator: inputLocator,
+            listLocator: inputLocator,
+        };
+    }
+    if (kind === 'datepicker') {
+        return {
+            component: 'datepicker',
+            field,
+            label,
+            listLocator: inputLocator,
+            searchAssertion: 'none',
+            triggerSearch: true,
+        };
+    }
+    if (kind === 'tree') {
+        return {
+            component: 'tree',
+            field,
+            label,
+            ...(runtimeLocator ? { treeLocator: runtimeLocator } : {}),
+            nodeStrategy: 'first_leaf',
+            searchOnSelect: true,
+            searchAssertion: 'none',
+        };
+    }
+    return {
+        component: 'listbox',
+        field,
+        label,
+        valueStrategy: 'first_non_placeholder',
+        skipValues: ['请选择'],
+        searchAssertion: 'none',
+        // 保留装配期按 add 表单推导的 createSelections；校准不改写 create 侧语义
+        createSelections: existingSlot?.createSelections ?? [],
+    };
+}
+/**
+ * 执行运行时校准。
+ *
+ * @param args - calibrate 参数。
+ * @returns CalibrateResult。
+ * @throws elementmap 缺失 / 校验门禁失败（不落盘）时抛错。
+ */
+export function runCalibrate(args) {
+    const testcasePath = path.resolve(args.testcase);
+    const paths = resolveRunPaths(testcasePath);
+    const elementmapPath = args.elementmap
+        ? path.resolve(args.elementmap)
+        : path.join(paths.caseDir, '.ep-stage', 'elementmap.json');
+    if (!existsSync(elementmapPath)) {
+        throw new Error(`elementmap.json 不存在: ${elementmapPath}。请先经 /glue-run-test Step 4a（登录 + 全 frame 扫描）产出新鲜 elementmap。`);
+    }
+    const scannedAt = JSON5.parse(readFileSync(elementmapPath, 'utf8'));
+    if (scannedAt.scannedAt && Date.now() - Date.parse(scannedAt.scannedAt) > ELEMENTMAP_STALE_MS) {
+        console.warn(`警告：elementmap 扫描时间 ${scannedAt.scannedAt} 距今超过 24h，建议重新扫描后再校准。`);
+    }
+    const elementmap = scannedAt;
+    const elements = (elementmap.elements ?? []).filter((e) => e.visible !== false);
+    const contractPath = path.join(paths.caseDir, '.ep-stage', 'contract.json5');
+    if (!existsSync(contractPath)) {
+        throw new Error(`contract.json5 不存在: ${contractPath}（应先由 testcase 子命令产出）`);
+    }
+    const contract = JSON5.parse(readFileSync(contractPath, 'utf8'));
+    const testcase = validateTestcase(JSON5.parse(readFileSync(testcasePath, 'utf8')));
+    const changes = [];
+    const unresolvedAdded = [];
+    const casesPatched = [];
+    contract.unresolvedSlots = contract.unresolvedSlots ?? [];
+    const pushUnresolved = (record) => {
+        const duplicated = contract.unresolvedSlots.some((slot) => slot.kind === record.kind && slot.slotPath === record.slotPath);
+        if (!duplicated) {
+            contract.unresolvedSlots.push(record);
+            unresolvedAdded.push(record);
+        }
+    };
+    const crudSlots = contract.scenario.skeletonSlots.crud;
+    const searchConditions = Array.isArray(crudSlots.searchConditions)
+        ? crudSlots.searchConditions
+        : [];
+    crudSlots.searchConditions = searchConditions;
+    // R1-R6：查询字段组件形态校准
+    for (const searchField of contract.scenario.searchFields) {
+        const label = searchField.label;
+        const hit = elements.find((e) => e.type === 'field' && e.label === label);
+        if (!hit) {
+            pushUnresolved({
+                slotPath: `scenario.searchFields[${label}]`,
+                kind: 'query_field_not_found',
+                reason: `查询字段「${label}」在运行时 elementmap 中未命中（隐藏/未渲染/label 漂移）。`,
+                suggestedAction: 'human_review',
+                detectedAt: 'calibrate',
+                evidence: { source: 'elementmap', ref: path.basename(elementmapPath) },
+            });
+            continue;
+        }
+        const controlType = hit.controlType ?? '';
+        const resolution = resolveQueryComponent({ component: controlType });
+        if (resolution.source === 'unrecognized') {
+            pushUnresolved({
+                slotPath: `scenario.searchFields[${label}]`,
+                kind: 'unsupported_query_component',
+                rawComponent: resolution.raw,
+                reason: `查询字段「${label}」运行时组件 ${resolution.raw} 不在 glue 白名单映射表。`,
+                suggestedAction: 'extend_component_library',
+                detectedAt: 'calibrate',
+                evidence: { source: 'elementmap', ref: hit.locator ?? label },
+            });
+            continue;
+        }
+        const nextKind = resolution.kind;
+        if (nextKind && nextKind !== searchField.component) {
+            const ruleByKind = {
+                input: 'R1', listbox: 'R2', datepicker: 'R3', tree: 'R4',
+            };
+            changes.push({
+                slotPath: `scenario.searchFields[${label}].component`,
+                from: searchField.component,
+                to: nextKind,
+                rule: ruleByKind[nextKind],
+                evidence: { label, locator: hit.locator, controlType },
+            });
+            searchField.component = nextKind;
+            // 重建 searchConditions 槽位（按 label 找既有槽位保留需保留字段）
+            const existingIndex = searchConditions.findIndex((c) => c.label === label);
+            const existingSlot = existingIndex >= 0 ? searchConditions[existingIndex] : undefined;
+            const nextSlot = buildCalibratedSlot(nextKind, searchField.field, label, hit.locator, existingSlot);
+            if (existingIndex >= 0) {
+                searchConditions[existingIndex] = nextSlot;
+            }
+            else {
+                searchConditions.push(nextSlot);
+            }
+        }
+    }
+    // R7：导出按钮定位符用 elementmap 实据覆盖
+    const exportButtonHit = elements.find((e) => e.type === 'button' && e.label === '导出');
+    const exportLocators = (contract.scenario.skeletonSlots.export.locators ??= {});
+    if (exportButtonHit?.locator && exportLocators.exportButton !== exportButtonHit.locator) {
+        changes.push({
+            slotPath: 'scenario.skeletonSlots.export.locators.exportButton',
+            from: exportLocators.exportButton ?? '<未配置>',
+            to: exportButtonHit.locator,
+            rule: 'R7',
+            evidence: { label: '导出', locator: exportButtonHit.locator },
+        });
+        exportLocators.exportButton = exportButtonHit.locator;
+    }
+    // R8：查询/搜索按钮在 elementmap 中缺席 → 人审（树节点选择后仍要求显式提交）
+    const hasSearchSubmit = elements.some((e) => e.type === 'button' && (e.label === '查询' || e.label === '搜索'));
+    if (!hasSearchSubmit) {
+        pushUnresolved({
+            slotPath: 'scenario.skeletonSlots.crud.locators.listSearchSubmit',
+            kind: 'search_submit_unverified',
+            reason: 'elementmap 中未发现「查询/搜索」按钮；datepicker/input 条件的 triggerSearch 与 tree 的 searchOnSelect 语义需人工确认。',
+            suggestedAction: 'human_review',
+            detectedAt: 'calibrate',
+            evidence: { source: 'elementmap', ref: path.basename(elementmapPath) },
+        });
+    }
+    // R9：导出面板证据（待选列/已选列）→ 注入 exportContainer 语义锚点
+    const hasPanelEvidence = elements.some((e) => e.label === '待选列' || e.label === '已选列');
+    if (hasPanelEvidence && !exportLocators.exportContainer) {
+        const containerAnchor = "xpath=//div[.//*[normalize-space()='待选列'] and .//*[normalize-space()='已选列']]";
+        changes.push({
+            slotPath: 'scenario.skeletonSlots.export.locators.exportContainer',
+            from: '<未配置>',
+            to: containerAnchor,
+            rule: 'R9',
+            evidence: { label: '待选列/已选列' },
+        });
+        exportLocators.exportContainer = containerAnchor;
+    }
+    // 用例级联：组件类别变化影响 glue 用例语义时的诚实拨回（机器改语义必人审）。
+    // - read 用例：按新组件类型重算 steps/assertion，文案有变化才拨回 needs_review；
+    // - create/update/delete 用例：组件变为 datepicker/tree 后用例计划规则已不再产出它们
+    //   （datepicker/tree 只产 read），无条件拨回 needs_review，由人审后重跑 testcase 子命令重整。
+    const changedFields = new Map(changes
+        .filter((change) => change.slotPath.startsWith('scenario.searchFields['))
+        .map((change) => [
+        change.slotPath.slice('scenario.searchFields['.length, -1),
+        change.to,
+    ]));
+    const searchFieldLabels = contract.scenario.searchFields.map((field) => field.label);
+    for (const testcaseCase of testcase.cases) {
+        if (testcaseCase.generationStrategy !== 'glue')
+            continue;
+        if (!testcaseCase.queryKey)
+            continue;
+        const nextKind = changedFields.get(testcaseCase.queryKey);
+        if (!nextKind)
+            continue;
+        const isReadCase = testcaseCase.title.includes(' read');
+        if (!isReadCase) {
+            testcaseCase.reviewStatus = 'needs_review';
+            casesPatched.push(testcaseCase.caseId);
+            continue;
+        }
+        const rebuilt = buildGlueExecutionFields('read', testcaseCase.queryKey, nextKind, false, searchFieldLabels);
+        if (rebuilt.steps !== testcaseCase.steps || rebuilt.assertion !== testcaseCase.assertion) {
+            testcaseCase.steps = rebuilt.steps;
+            testcaseCase.assertion = rebuilt.assertion;
+            testcaseCase.reviewStatus = 'needs_review';
+            casesPatched.push(testcaseCase.caseId);
+        }
+    }
+    // 门禁：改写后的 contract 必须过同一 validateContract（含白名单交叉规则），失败则不落盘。
+    validateContract(contract);
+    validateTestcase(testcase);
+    const report = {
+        schemaVersion: 'ep-stage-calibration-report/v1',
+        calibratedAt: new Date().toISOString(),
+        elementmapRef: elementmapPath,
+        changes,
+        unresolvedAdded,
+        testcaseCasesPatched: casesPatched.map((caseId) => ({ caseId })),
+        written: args.write,
+    };
+    const reportPath = path.join(paths.caseDir, '.ep-stage', 'calibration-report.json');
+    if (!args.write) {
+        console.log(JSON5.stringify(report, null, 2));
+        return { reportPath, changes, unresolvedAdded, casesPatched, written: false, specRegenerated: false };
+    }
+    writeFileSync(contractPath, `${JSON5.stringify(contract, null, 2)}\n`, 'utf8');
+    let specRegenerated = false;
+    if (casesPatched.length > 0) {
+        // 用例语义被机器改写 → reviewStatus 已拨回 needs_review，spec 门禁会阻断重生成；
+        // 本轮只落 contract/testcase/账本，spec 待人工确认用例后由 prepare-tasks/run 重生成。
+        writeFileSync(testcasePath, `${JSON5.stringify(testcase, null, 2)}\n`, 'utf8');
+        writeFileSync(path.join(paths.caseDir, 'testcase.md'), renderUnifiedTestcaseMarkdown(testcase, contract), 'utf8');
+    }
+    else {
+        // 级联重生成 spec（无条件覆写；AI 追加段由 run 时从 ai-snippets.json5 幂等重建）
+        runSpec({ testcase: testcasePath, out: paths.specPath });
+        specRegenerated = true;
+    }
+    writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    return { reportPath, changes, unresolvedAdded, casesPatched, written: true, specRegenerated };
+}