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

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 };
+}

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

@@ -0,0 +1,53 @@
+/**
+ * demote 子命令：把执行失败的 glue 用例降级为 AI 候选用例（运行期降级通道）。
+ *
+ * 触发场景：run 失败且 repair-report 分类为 locator_or_wait_error / iframe_context_error，
+ * 人工确认根因是「组件形态错配」（骨架组件库未覆盖该控件形态）后，由本命令做确定性的
+ * 桶位迁移，避免 Agent 手编 testcase.json5 出错。
+ *
+ * 行为（全链路确定性，逐步过门禁）：
+ * 1. 从 cases[] 摘除目标 case，构造 uncoveredCandidates 条目（保留原 caseId 与执行字段，
+ *    businessIntent 注明降级来源 repair-round 与根因）；
+ * 2. validateTestcase 门禁后写回 testcase.json5，并重渲染 testcase.md；
+ * 3. 显式调 runSpec 重生成 spec（无条件覆写；AI 追加段由 run 时从 ai-snippets.json5 幂等重建）。
+ */
+/**
+ * demote 子命令参数。
+ */
+export type DemoteArgs = {
+    /** testcase.json5 路径 */
+    testcase: string;
+    /** 待降级用例 ID（如 TC01003） */
+    caseId: string;
+    /** 降级原因（写入 .ep-stage/demote-runs 供人审追溯） */
+    reason: string;
+};
+/**
+ * demote 子命令产物。
+ */
+export type DemoteResult = {
+    testcasePath: string;
+    /** 降级后的用例 ID（与原 caseId 相同，桶位从 cases[] 迁到 uncoveredCandidates[]） */
+    caseId: string;
+    /** 重生成的 spec 路径 */
+    specPath: string;
+    /** 重渲染的 testcase.md 路径 */
+    testcaseMdPath: string;
+};
+/**
+ * 解析 demote 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns DemoteArgs。
+ * @throws 缺少必填参数时抛错。
+ */
+export declare function parseDemoteArgs(argv: string[]): DemoteArgs;
+/**
+ * 执行用例降级：cases[] → uncoveredCandidates[]，并重生成 testcase.md 与 spec。
+ *
+ * @param args - demote 参数。
+ * @returns DemoteResult。
+ * @throws 用例不存在 / 用例不在 glue 桶 / 门禁失败时抛错（不写盘）。
+ */
+export declare function runDemote(args: DemoteArgs): DemoteResult;
+//# sourceMappingURL=demote.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"demote.d.ts","sourceRoot":"","sources":["../../../src/cli/demote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAmB1D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY,CAqExD"}

package/dist/src/cli/demote.js

@@ -0,0 +1,111 @@
+/**
+ * demote 子命令：把执行失败的 glue 用例降级为 AI 候选用例（运行期降级通道）。
+ *
+ * 触发场景：run 失败且 repair-report 分类为 locator_or_wait_error / iframe_context_error，
+ * 人工确认根因是「组件形态错配」（骨架组件库未覆盖该控件形态）后，由本命令做确定性的
+ * 桶位迁移，避免 Agent 手编 testcase.json5 出错。
+ *
+ * 行为（全链路确定性，逐步过门禁）：
+ * 1. 从 cases[] 摘除目标 case，构造 uncoveredCandidates 条目（保留原 caseId 与执行字段，
+ *    businessIntent 注明降级来源 repair-round 与根因）；
+ * 2. validateTestcase 门禁后写回 testcase.json5，并重渲染 testcase.md；
+ * 3. 显式调 runSpec 重生成 spec（无条件覆写；AI 追加段由 run 时从 ai-snippets.json5 幂等重建）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import JSON5 from 'json5';
+import { validateTestcase } from '../validation/testcase.js';
+import { validateContract } from '../validation/contract.js';
+import { renderUnifiedTestcaseMarkdown } from '../testcase/testcase-markdown.js';
+import { resolveRunPaths } from './run.js';
+import { runSpec } from './spec.js';
+/**
+ * 解析 demote 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns DemoteArgs。
+ * @throws 缺少必填参数时抛错。
+ */
+export function parseDemoteArgs(argv) {
+    const result = {};
+    const normalizedArgv = argv.filter((arg) => arg !== '--');
+    for (let index = 0; index < normalizedArgv.length; index += 2) {
+        const key = normalizedArgv[index];
+        const value = normalizedArgv[index + 1];
+        if (!key?.startsWith('--') || !value) {
+            throw new Error(`无效参数对: ${key ?? '<empty>'}`);
+        }
+        result[key.slice(2).replace(/-([a-z])/g, (_, char) => char.toUpperCase())] = value;
+    }
+    if (!result.testcase)
+        throw new Error('缺少 --testcase');
+    if (!result.caseId)
+        throw new Error('缺少 --case-id');
+    if (!result.reason)
+        throw new Error('缺少 --reason（建议带 repair-round 与根因，供人审追溯）');
+    return {
+        testcase: result.testcase,
+        caseId: result.caseId,
+        reason: result.reason,
+    };
+}
+/**
+ * 执行用例降级：cases[] → uncoveredCandidates[]，并重生成 testcase.md 与 spec。
+ *
+ * @param args - demote 参数。
+ * @returns DemoteResult。
+ * @throws 用例不存在 / 用例不在 glue 桶 / 门禁失败时抛错（不写盘）。
+ */
+export function runDemote(args) {
+    const testcasePath = path.resolve(args.testcase);
+    const paths = resolveRunPaths(testcasePath);
+    const testcaseRaw = JSON5.parse(readFileSync(testcasePath, 'utf8'));
+    const testcase = validateTestcase(testcaseRaw);
+    const caseIndex = testcase.cases.findIndex((c) => c.caseId === args.caseId);
+    if (caseIndex < 0) {
+        const inUncovered = testcase.uncoveredCandidates.find((c) => c.caseId === args.caseId);
+        throw new Error(inUncovered
+            ? `用例 ${args.caseId} 已是 AI 候选（uncoveredCandidates），无需降级`
+            : `用例 ${args.caseId} 不存在于 cases[]（可降级对象仅限 glue 桶用例）`);
+    }
+    const [target] = testcase.cases.splice(caseIndex, 1);
+    const firstRole = testcase.testAccess?.requiredRoles?.[0] ?? '业务角色待确认';
+    const demoted = {
+        caseId: target.caseId,
+        label: target.title,
+        generationStrategy: 'ai',
+        coverageStatus: 'gap',
+        requiredRole: firstRole,
+        // Runtime evidence belongs in demote-runs, not in the testcase fact source.
+        businessIntent: target.title,
+        assertionExpectation: target.assertion ?? '（原用例无断言文本，见 repair 记录）',
+        queryKey: target.queryKey ?? '不适用',
+        precondition: target.precondition,
+        steps: target.steps,
+        assertion: target.assertion,
+    };
+    testcase.uncoveredCandidates.push(demoted);
+    // 门禁：迁移后的 testcase 必须仍然合法（桶位约束等），失败则不写盘。
+    validateTestcase(testcase);
+    // contract 只读（testcase.md 重渲染需要按钮映射表等契约事实），缺失时降级为不带契约渲染。
+    const contractPath = path.join(paths.caseDir, '.ep-stage', 'contract.json5');
+    const contract = existsSync(contractPath)
+        ? validateContract(JSON5.parse(readFileSync(contractPath, 'utf8')))
+        : undefined;
+    writeFileSync(testcasePath, `${JSON5.stringify(testcase, null, 2)}\n`, 'utf8');
+    const testcaseMdPath = path.join(paths.caseDir, 'testcase.md');
+    writeFileSync(testcaseMdPath, renderUnifiedTestcaseMarkdown(testcase, contract), 'utf8');
+    const demoteDir = path.join(paths.caseDir, '.ep-stage', 'demote-runs');
+    mkdirSync(demoteDir, { recursive: true });
+    const recordedAt = new Date().toISOString();
+    const demoteRecordPath = path.join(demoteDir, `${recordedAt.replace(/[:.]/g, '-')}-${args.caseId}.json`);
+    writeFileSync(demoteRecordPath, `${JSON.stringify({ caseId: args.caseId, reason: args.reason, recordedAt }, null, 2)}\n`, 'utf8');
+    // 显式重生成 spec（无条件覆写；AI 追加段由 run 时从 ai-snippets.json5 幂等重建）。
+    runSpec({ testcase: testcasePath, out: paths.specPath });
+    return {
+        testcasePath,
+        caseId: args.caseId,
+        specPath: paths.specPath,
+        testcaseMdPath,
+    };
+}

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

@@ -1,19 +1,21 @@
 #!/usr/bin/env node
 /**
- * ep-stage-skill CLI 统一入口（REQ-CLI-02 修订）：1 bin + 3 子命令。
+ * ep-stage-skill CLI 统一入口：1 bin + 6 子命令。
  *
  * 用法：
  *   ep-stage-skill testcase --code-list <p> --tests-dir <p> --direct-url <url> [--project-dir <p>] [--requirement-dir <p>]
  *   ep-stage-skill spec --testcase <p> --out <p>
  *   ep-stage-skill prepare-tasks --testcase <p>
- *   ep-stage-skill run --testcase <p> [--ai-snippets <p>] [--headless false]
+ *   ep-stage-skill run --testcase <p> [--ai-snippets <p>] [--headless false] [--strict-ai true]
+ *   ep-stage-skill calibrate --testcase <p> [--elementmap <p>] [--write]
+ *   ep-stage-skill demote --testcase <p> --case-id <id> --reason <text>
  *
  * 无 contract 子命令（contract 提取作为 testcase 子命令内部步骤；
  * 开发期独立调试入口为 dev/extract-contract.ts，被 pnpm generate:crud-contract 调用）。
  */
 export declare function main(argv?: string[]): Promise<unknown>;
 /**
- * 打印 CLI help（仅 testcase / spec / run 3 子命令，无 contract）。
+ * 打印 CLI help。
  */
 export declare function printHelp(): void;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AAOA;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAuD1E;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAchC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAS3F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AASA;;;;;;;;;;;;;GAaG;AACH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CA0F1E;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAkBhC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAS3F"}

package/dist/src/cli/index.js

@@ -4,14 +4,18 @@ import { fileURLToPath } from 'node:url';
 import { parseGenerateTestcaseArgs, runGenerateTestcase } from './generate-testcase.js';
 import { parseSpecArgs, runSpec } from './spec.js';
 import { parseRunArgs, prepareAiRuntimeTasks, runRun } from './run.js';
+import { parseDemoteArgs, runDemote } from './demote.js';
+import { parseCalibrateArgs, runCalibrate } from './calibrate.js';
 /**
- * ep-stage-skill CLI 统一入口（REQ-CLI-02 修订）：1 bin + 3 子命令。
+ * ep-stage-skill CLI 统一入口：1 bin + 6 子命令。
  *
  * 用法：
  *   ep-stage-skill testcase --code-list <p> --tests-dir <p> --direct-url <url> [--project-dir <p>] [--requirement-dir <p>]
  *   ep-stage-skill spec --testcase <p> --out <p>
  *   ep-stage-skill prepare-tasks --testcase <p>
- *   ep-stage-skill run --testcase <p> [--ai-snippets <p>] [--headless false]
+ *   ep-stage-skill run --testcase <p> [--ai-snippets <p>] [--headless false] [--strict-ai true]
+ *   ep-stage-skill calibrate --testcase <p> [--elementmap <p>] [--write]
+ *   ep-stage-skill demote --testcase <p> --case-id <id> --reason <text>
  *
  * 无 contract 子命令（contract 提取作为 testcase 子命令内部步骤；
  * 开发期独立调试入口为 dev/extract-contract.ts，被 pnpm generate:crud-contract 调用）。
@@ -34,6 +38,34 @@ export async function main(argv = process.argv) {
             ].join('\n'));
             return result;
         }
+        case 'calibrate': {
+            const result = runCalibrate(parseCalibrateArgs(args));
+            console.log([
+                `calibration-report: ${result.reportPath}`,
+                `changes: ${result.changes.length}`,
+                `unresolved added: ${result.unresolvedAdded.length}`,
+                ...(result.casesPatched.length > 0
+                    ? [`用例拨回 needs_review（待人工确认后重跑）: ${result.casesPatched.join('、')}`]
+                    : []),
+                result.written
+                    ? result.specRegenerated
+                        ? '已写盘（contract/spec 已级联重生成）'
+                        : '已写盘（spec 待用例人审后重生成）'
+                    : 'dry-run（未写盘，加 --write 生效）',
+            ].join('\n'));
+            return result;
+        }
+        case 'demote': {
+            const result = runDemote(parseDemoteArgs(args));
+            console.log([
+                `已降级: ${result.caseId} → uncoveredCandidates（AI 桶）`,
+                `testcase: ${result.testcasePath}`,
+                `spec 已重生成: ${result.specPath}`,
+                `testcase.md 已重渲染: ${result.testcaseMdPath}`,
+                '下一步：重跑 prepare-tasks 产出该用例的 AI 任务，经 O-D-A-V 后 run。',
+            ].join('\n'));
+            return result;
+        }
         case 'run': {
             const result = await runRun(parseRunArgs(args));
             // 结果摘要回显（此前 run 静默退出，自动化无法感知成败）。
@@ -42,6 +74,9 @@ export async function main(argv = process.argv) {
                 `report: ${result.reportDir}`,
                 `trace: ${result.aiRuntimeTracePath}`,
             ];
+            if (result.needsReviewCount) {
+                lines.push(`AI 任务待审（本轮未执行）: ${result.needsReviewCount} 条`);
+            }
             if (result.comprehensiveReportPath) {
                 lines.push(`综合报告: ${result.comprehensiveReportPath}`);
             }
@@ -66,12 +101,12 @@ export async function main(argv = process.argv) {
             printHelp();
             return;
         default:
-            console.error(`未知子命令: ${subcommand}。可用: testcase / spec / prepare-tasks / run`);
+            console.error(`未知子命令: ${subcommand}。可用: testcase / spec / prepare-tasks / run / calibrate / demote`);
             process.exit(1);
     }
 }
 /**
- * 打印 CLI help（仅 testcase / spec / run 3 子命令，无 contract）。
+ * 打印 CLI help。
  */
 export function printHelp() {
     console.log(`ep-stage-skill — 胶水测试链路 CLI
@@ -80,13 +115,17 @@ export function printHelp() {
   ep-stage-skill testcase --code-list <path> --tests-dir <path> --direct-url <url> [--project-dir <path>] [--requirement-dir <path>]
   ep-stage-skill spec --testcase <path> --out <path>
   ep-stage-skill prepare-tasks --testcase <path>
-  ep-stage-skill run --testcase <path> [--ai-snippets <path>] [--headless false]
+  ep-stage-skill run --testcase <path> [--ai-snippets <path>] [--headless false] [--strict-ai true]
+  ep-stage-skill calibrate --testcase <path> [--elementmap <path>] [--write]
+  ep-stage-skill demote --testcase <path> --case-id <id> --reason <text>
 
 子命令:
   testcase   读取 _docs/code_list.json5 + 生成 contract.json5 / testcase.json5 / inference-trace.json
   spec       基于 testcase.json5 + contract.json5 的 glue cases 生成初始版 .spec.ts（只生成不执行）
   prepare-tasks  组装 glue 骨架并输出 AI Runtime 任务包
-  run        合并 Agent 产出的 ai-snippets.json5 并执行完整 spec`);
+  run        合并 Agent 产出的 ai-snippets.json5 并执行完整 spec（默认部分执行：needs_review 的 AI 任务不阻断；--strict-ai true 恢复旧短路语义）
+  calibrate  用 elementmap.json 运行时实据校准 contract（组件形态/定位符），默认 dry-run，--write 落盘并重生成 spec
+  demote     把形态错配失败的 glue 用例降级为 AI 候选（迁移桶位并重渲染 testcase.md、重生成 spec）`);
 }
 /**
  * 判断当前 CLI 文件是否以“直接执行”方式启动。

package/dist/src/cli/run-report.d.ts

@@ -14,6 +14,12 @@ export type RunReportTestItem = {
     durationMs: number;
     location?: string;
     errorMessage?: string;
+    /**
+     * 骨架运行时复核结论（如搜索前后数据量无变化/查询字段不在列表列）。
+     * 由 run 子命令从 stage-glue 执行记录（recorder JSON）按用例标题合并进来；
+     * 存在时报告按「待审阅」呈现，Playwright 层的 passed 不代表业务语义已验证。
+     */
+    reviewNote?: string;
 };
 export type RunReportData = {
     suiteTitle: string;

package/dist/src/cli/run-report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-report.d.ts","sourceRoot":"","sources":["../../../src/cli/run-report.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,mDAAmD;IACnD,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,wBAAwB;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAkDF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B,CA0CA;AA4ED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CA4L/D"}
+{"version":3,"file":"run-report.d.ts","sourceRoot":"","sources":["../../../src/cli/run-report.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,mDAAmD;IACnD,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,wBAAwB;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAkDF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B,CA0CA;AAsFD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAgM/D"}