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

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"}