@epoint-testtech/ep-stage-skill 0.0.4-alpha.1 → 0.0.6

package/dist/src/cli/generate-testcase.js

@@ -2,12 +2,12 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import JSON5 from 'json5';
-import { runProbeAndCoverage } from './probe.js';
 import { createSoftlinkWithFallback } from '../util/softlink.js';
-import { i18nTestcase } from '../util/i18n-testcase.js';
-import { extractCodeListSummary } from '../extractors/code-list.js';
-import { resolveMaterialInventory } from '../material/material-inventory.js';
-import { validateInferenceTrace } from '../validation/inference-trace.js';
+import { extractCodeListJson5, assertCodeListJson5Path } from '../extractors/code-list-json5.js';
+import { assembleJson5ContractAndTestcase } from '../testcase/contract-testcase-assembler.js';
+import { renderUnifiedTestcaseMarkdown } from '../testcase/testcase-markdown.js';
+import { validateContract } from '../validation/contract.js';
+import { validateTestcase } from '../validation/testcase.js';
 import { writeProjectIndex } from '../context/stage-context.js';
 /**
  * 解析 testcase 子命令参数。
@@ -34,151 +34,50 @@ export function parseGenerateTestcaseArgs(argv) {
     return {
         codeList: result['code-list'],
         testsDir: result['tests-dir'],
-        scenario: result.scenario,
-        hints: result.hints,
         projectDir: result['project-dir'],
         requirementDir: result['requirement-dir'],
+        directUrl: result['direct-url'],
+        sourceRoot: result['source-root'],
     };
 }
 /**
- * scenario 3 档决策（REQ-SCENE-01）：
- * 1. --scenario CLI 参数（最高优先级）
- * 2. ModuleHints 文件路径包含 `scenario=<value>` 字串（粗推断）
- * 3. 默认 "crud.single-page"（与 i18n 表 / skeleton scenario 一致）
+ * 渲染 credentials.template.json5 数组内容。
+ * 每条对应一个 role，url/systemName 复用 code_list.systems[0]（多系统场景由用户补齐）。
  *
- * @param args - 解析后的参数。
- * @returns 决策结果。
- */
-export function decideScenario(args) {
-    if (args.scenario)
-        return args.scenario;
-    if (args.hints && args.hints.includes('scenario=')) {
-        const inferred = args.hints.split('scenario=')[1]?.split(/\s|,/)[0];
-        if (inferred)
-            return inferred;
-    }
-    return 'crud.single-page';
-}
-/**
- * 把 TestcaseV2 渲染成中文 testcase.md（REQ-UX-03）。
- *
- * 设计：
- * - 字段名 / 状态值通过 i18nTestcase() 翻译；
- * - `unresolved` 字段标题硬编码「未确认项」（i18n 表中 `unresolved` 解析为状态值「未解决」）；
- * - 每次重跑覆盖（REQ-DATA-03 由调用方 writeFileSync 触发）。
- *
- * @param testcase - TestcaseV2 顶层结构。
- * @returns Markdown 文本。
- */
-export function renderTestcaseMarkdown(testcase) {
-    const lines = [];
-    lines.push(`# ${testcase.moduleName} 胶水测试用例`);
-    lines.push('');
-    lines.push(`- 模块 ID：${testcase.moduleId}`);
-    lines.push(`- ${i18nTestcase('scenario')}：${i18nTestcase(testcase.scenario)}`);
-    lines.push(`- ${i18nTestcase('menuPath')}：${testcase.menuPath || '（未填写）'}`);
-    lines.push(`- ${i18nTestcase('requiredSystems')}：${testcase.requiredSystems.map((s) => s.url || '（待填写）').join('，')}`);
-    lines.push(`- ${i18nTestcase('requiredRoles')}：${testcase.requiredRoles.map((r) => r.role).join('，')}`);
-    lines.push('');
-    lines.push(`## ${i18nTestcase('coveredActions')}`);
-    if (testcase.coveredActions.length === 0)
-        lines.push('（无）');
-    for (const action of testcase.coveredActions) {
-        lines.push(`- ${action.actionId}（${action.kind}）证据：${action.evidence.join(' / ')}`);
-    }
-    lines.push('');
-    lines.push(`## ${i18nTestcase('uncoveredCandidates')}`);
-    if (testcase.uncoveredCandidates.length === 0)
-        lines.push('（无）');
-    for (const cand of testcase.uncoveredCandidates) {
-        lines.push(`- ${cand.actionId} ${cand.label}｜状态：${i18nTestcase(cand.status)}｜${i18nTestcase('requiredRole')}：${cand.requiredRole}`);
-        lines.push(`  - ${i18nTestcase('businessIntent')}：${cand.businessIntent}`);
-        lines.push(`  - ${i18nTestcase('assertionExpectation')}：${cand.assertionExpectation}`);
-        lines.push(`  - ${i18nTestcase('evidence')}：${cand.evidence.join(' / ')}`);
-    }
-    lines.push('');
-    lines.push('## 用例');
-    for (const c of testcase.cases) {
-        lines.push(`### ${c.title}（${i18nTestcase('caseId')}：${c.caseId}）`);
-        lines.push(`- ${i18nTestcase('scenario')}：${i18nTestcase(c.scenario)}｜${i18nTestcase('reviewStatus')}：${i18nTestcase(c.reviewStatus)}｜${i18nTestcase('requiredRole')}：${c.requiredRole}`);
-        lines.push(`- ${i18nTestcase('evidence')}：${c.evidence.join(' / ')}`);
-        lines.push('- 步骤：');
-        for (const s of c.steps)
-            lines.push(`  1. ${s}`);
-        lines.push('- 断言：');
-        for (const a of c.assertions)
-            lines.push(`  - ${a}`);
-        // 硬编码标题「未确认项」：i18nTestcase('unresolved') 返回状态值「未解决」（spec §4.6 trade-off）。
-        lines.push(`- 未确认项：${c.unresolved.length === 0 ? '（无）' : c.unresolved.join('；')}`);
-        lines.push('');
-    }
-    lines.push('## 推理摘要');
-    lines.push(testcase.reasoningSummary.conclusion);
-    lines.push('');
-    lines.push('证据链：');
-    for (const ev of testcase.reasoningSummary.evidenceChain)
-        lines.push(`- ${ev}`);
-    return `${lines.join('\n').trimEnd()}\n`;
-}
-/**
- * 渲染 credentials.template.json5 数组内容。每条对应 requiredRoles[i]，
- * url/systemName 复用 requiredSystems[0]（多系统场景由用户手工补齐）。
- *
- * @param testcase - TestcaseV2。
+ * @param codeList - code_list 解析产出。
  * @returns JSON5 字符串。
  */
-function renderCredentialsTemplate(testcase) {
-    const baseUrl = testcase.requiredSystems[0]?.url ?? '';
-    const baseSystem = testcase.requiredSystems[0]?.systemName ?? '';
-    const entries = testcase.requiredRoles.map((roleEntry) => ({
-        url: baseUrl,
-        username: '',
-        password: '',
-        role: roleEntry.role,
-        systemName: baseSystem,
-    }));
+function renderCredentialsTemplate(codeList, directUrl) {
+    const baseSystem = codeList.systems[0]?.name ?? '';
+    // 字段命名对齐 stage-core Credential type：`url` = 登录页 URL（stage-core 消费入口，
+    // 用于 process.env.LOGIN_SYSTEM_URL）；`directUrl` = 待测页面直达链接（应用侧读，
+    // 由 spec openModule 用 loginPage.gotoDirectUrl 消费）。旧 template 用 loginUrl 会
+    // 导致 stage-core loadCredentials 解析到的 credential.url=undefined、下游 goto("undefined") 失败。
+    const loginUrl = codeList.systems[0]?.defaultLoginUrl ?? '';
+    const entries = codeList.roles.length > 0
+        ? codeList.roles.map((role) => ({
+            directUrl,
+            url: loginUrl,
+            systemName: role.systemName || baseSystem,
+            role: role.role,
+            username: '',
+            password: '',
+        }))
+        : (codeList.requirement?.businessRoles ?? []).map((role) => ({
+            directUrl,
+            url: loginUrl,
+            systemName: baseSystem,
+            role: role.label,
+            username: '',
+            password: '',
+        }));
     return `${JSON5.stringify(entries, null, 2)}\n`;
 }
-/**
- * 从 code_list.md 解析 testcase 子命令所需的 HTML / Action 物料目录。
- *
- * @param codeListPath - code_list.md 绝对路径。
- * @returns probe 阶段所需的 webapp / java 目录。
- * @throws 无法唯一解析 HTML 或 Action 目录时抛错。
- */
-function resolveProbeInputsFromCodeList(codeListPath) {
-    const codeList = extractCodeListSummary(codeListPath);
-    const materialResult = resolveMaterialInventory({
-        codeListPath,
-        codeList,
-        debugOverrides: {},
-    });
-    if (materialResult.resolvedInputs.webappDir.status !== 'resolved') {
-        throw new Error(`code_list.md 无法唯一解析 HTML 目录：${codeListPath}`);
-    }
-    if (materialResult.resolvedInputs.javaActionsDir.status !== 'resolved') {
-        throw new Error(`code_list.md 无法唯一解析 Action 目录：${codeListPath}`);
-    }
-    return {
-        docsDir: materialResult.resolvedInputs.docsDir.status === 'resolved'
-            ? materialResult.resolvedInputs.docsDir.path
-            : undefined,
-        webappDir: materialResult.resolvedInputs.webappDir.path,
-        javaActionsDir: materialResult.resolvedInputs.javaActionsDir.path,
-        hintsPath: materialResult.resolvedInputs.hintsPath.status === 'resolved'
-            ? materialResult.resolvedInputs.hintsPath.path
-            : undefined,
-        moduleId: materialResult.resolvedInputs.moduleId.status === 'resolved'
-            ? materialResult.resolvedInputs.moduleId.value
-            : undefined,
-    };
-}
 /**
  * 往 projects.index.json5 对应 project 的 requirements[] 追加（去重）一条需求条目。
  *
  * 设计：
  * - 读 index 时同时保留 systems[]（writeProjectIndex 整体覆写，丢失 systems 会丢凭据缓存）；
- * - 用 JSON5.parse(readFileSync) 直接读，不复用 readProjectIndexRaw（后者未导出且丢 systems）；
  * - 按 projectDir 精确匹配 project，找不到抛中文错误引导先跑 /glue-create-project；
  * - 同 name 的 requirement 去重：存在则更新 requirementDir/testsDir/lastRunStatus，不存在则追加。
  *
@@ -212,7 +111,6 @@ function appendRequirementToProjectIndex(input) {
         testsDir: input.testsDir,
         lastRunStatus: 'never',
     };
-    // 去重：同 name 存在则更新，不存在则追加。
     const existIdx = project.requirements.findIndex((r) => r.name === entry.name);
     if (existIdx >= 0) {
         project.requirements[existIdx] = entry;
@@ -223,61 +121,63 @@ function appendRequirementToProjectIndex(input) {
     return writeProjectIndex({ homeDir, projects, systems: parsed.systems });
 }
 /**
- * testcase 子命令主体（REQ-CHAIN-01 / REQ-CHAIN-02 / REQ-SCENE-01 / REQ-DATA-02）。
+ * testcase 子命令主体（JSON5 新产线，Task 3）。
  *
  * 流程：
- * 1. 决定 scenario（3 档优先级，写入 testcase 顶层 scenario 字段）；
- * 2. 调 runProbeAndCoverage 钻探上游物料 + 装配 TestcaseV2；
- * 3. 落盘 testcase.json5 + testcase.md（中文 i18n） + credentials.template.json5；
- * 4. 软链上游 code_list.md → <tests-dir>/code_list.md；
- * 5. 返回推断结果（供 skill Step 5 交互确认 systemUrl / credentialsCache 命中）。
- *
- * 注意：contract 提取通过 probe 内部完成，不直接复用 dev/extract-contract.ts 的 CLI 入口
- * （probe + extract-contract 共享同一组 buildCrudBusinessModuleContract + extractor 依赖，
- * 二者各自负责自己的 I/O 边界，保持职责单一）。
+ * 1. extractCodeListJson5 解析 code_list.json5；
+ * 2. assembleJson5ContractAndTestcase 装配 contract + testcase + inference-trace；
+ * 3. validateContract / validateTestcase schema 门禁；
+ * 4. 落盘 .ep-stage/contract.json5 + testcase.json5 + .ep-stage/inference-trace.json +
+ *    credentials.template.json5 + testcase.md；软链 code_list.json5；
+ * 5. 可选回写 projects.index.json5（仅当显式传入 projectDir）。
  *
  * @param args - 已解析参数。
- * @returns 产物路径 + 推断结果。
+ * @returns 产物路径。
  */
 export function runGenerateTestcase(args) {
-    const scenario = decideScenario(args);
+    // 路径硬校验：必须是 .json5（拒绝旧 code_list.md）。
+    assertCodeListJson5Path(args.codeList);
     mkdirSync(args.testsDir, { recursive: true });
     const requirementDir = args.requirementDir ?? path.dirname(args.codeList);
-    const resolvedInputs = resolveProbeInputsFromCodeList(args.codeList);
-    const docsDir = resolvedInputs.docsDir ?? requirementDir;
-    const moduleId = resolvedInputs.moduleId ?? path.basename(args.testsDir);
-    const { contract, testcaseV2, inferenceTrace } = runProbeAndCoverage({
-        moduleId,
-        codeListPath: args.codeList,
-        docsDir,
-        webappDir: resolvedInputs.webappDir,
-        javaActionsDir: resolvedInputs.javaActionsDir,
-        hintsPath: args.hints ?? resolvedInputs.hintsPath,
-        scenario,
+    const codeList = extractCodeListJson5(args.codeList);
+    const listPage = codeList.pages.find((page) => page.role === 'list');
+    const directUrl = args.directUrl ?? listPage?.directUrl;
+    if (!directUrl) {
+        throw new Error('缺少待测页面 directUrl：请在 /glue-generate-testcase 交互中提供列表页直达地址，或在 code_list.json5 的 pages[role=list].directUrl 中提供。');
+    }
+    const { contract, testcase, inferenceTrace } = assembleJson5ContractAndTestcase({
+        codeList,
+        directUrl,
+        sourceRoot: args.sourceRoot,
     });
+    if (args.projectDir) {
+        testcase.runtimeContext = {
+            testProjectDir: args.projectDir,
+            caseDir: args.testsDir,
+            specPath: path.join(args.testsDir, 'crud.spec.ts'),
+        };
+    }
+    // schema 门禁（破旧立新，结构错直接抛）。
+    validateContract(contract);
+    validateTestcase(testcase);
     const epStageDir = path.join(args.testsDir, '.ep-stage');
     mkdirSync(epStageDir, { recursive: true });
-    const contractPath = path.join(epStageDir, 'contract.json');
+    const contractPath = path.join(epStageDir, 'contract.json5');
     const inferenceTracePath = path.join(epStageDir, 'inference-trace.json');
     const testcasePath = path.join(args.testsDir, 'testcase.json5');
     const testcaseMdPath = path.join(args.testsDir, 'testcase.md');
     const credentialsTemplatePath = path.join(args.testsDir, 'credentials.template.json5');
-    const credentialsActualPath = path.join(args.testsDir, 'credentials.json5');
-    // 落盘 contract.json 供 spec / run 子命令复用（避免重复钻探）。
-    writeFileSync(contractPath, `${JSON.stringify(contract, null, 2)}\n`, 'utf8');
-    // 落盘 inference-trace.json（解释链产物，REQ-INFER-004 / REQ-INFER-008；trace 只做解释，不驱动 spec）。
-    writeFileSync(inferenceTracePath, `${JSON.stringify(validateInferenceTrace(inferenceTrace), null, 2)}\n`, 'utf8');
-    writeFileSync(testcasePath, `${JSON5.stringify(testcaseV2, null, 2)}\n`, 'utf8');
-    writeFileSync(credentialsTemplatePath, renderCredentialsTemplate(testcaseV2), 'utf8');
-    writeFileSync(testcaseMdPath, renderTestcaseMarkdown(testcaseV2), 'utf8');
-    createSoftlinkWithFallback(args.codeList, path.join(args.testsDir, 'code_list.md'));
-    // 往 projects.index.json5 对应 project 追加（去重）一条 requirement 条目（skill Step 7）。
-    // 仅当显式传入 projectDir 时追加（skill Step 4 命令总带 --project-dir）；
-    // 未传则跳过 —— 不反推 projectDir，避免非标准 testsDir 位置静默写入错误 project。
+    writeFileSync(contractPath, `${JSON5.stringify(contract, null, 2)}\n`, 'utf8');
+    writeFileSync(inferenceTracePath, `${JSON.stringify(inferenceTrace, null, 2)}\n`, 'utf8');
+    writeFileSync(testcasePath, `${JSON5.stringify(testcase, null, 2)}\n`, 'utf8');
+    writeFileSync(credentialsTemplatePath, renderCredentialsTemplate(codeList, directUrl), 'utf8');
+    writeFileSync(testcaseMdPath, renderUnifiedTestcaseMarkdown(testcase, contract), 'utf8');
+    // 软链 code_list.json5 → testsDir/code_list.json5（保留 code_list 旁路访问）。
+    createSoftlinkWithFallback(args.codeList, path.join(args.testsDir, 'code_list.json5'));
+    // 仅当显式传入 projectDir 时回写 projects.index.json5（不反推，避免静默写入错误 project）。
     if (args.projectDir) {
         appendRequirementToProjectIndex({
             projectDir: args.projectDir,
-            // 需求名 = testsDir 的 basename（与 moduleId 来源一致：resolvedInputs.moduleId ?? path.basename(args.testsDir)）。
             requirementName: path.basename(args.testsDir),
             requirementDir,
             testsDir: args.testsDir,
@@ -288,13 +188,6 @@ export function runGenerateTestcase(args) {
         testcaseMdPath,
         credentialsTemplatePath,
         inferenceTracePath,
-        inference: {
-            scenario,
-            requiredSystems: testcaseV2.requiredSystems,
-            requiredRoles: testcaseV2.requiredRoles,
-            credentialsTemplatePath,
-            credentialsActualPath,
-            cachedSystemsHit: [],
-        },
+        contractPath,
     };
 }

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

@@ -3,9 +3,10 @@
  * ep-stage-skill CLI 统一入口（REQ-CLI-02 修订）：1 bin + 3 子命令。
  *
  * 用法：
- *   ep-stage-skill testcase --code-list <p> --tests-dir <p> [--scenario <v>] [--hints <p>]
+ *   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 run --spec <p> --testcase <p> [--headless false]
+ *   ep-stage-skill prepare-tasks --testcase <p>
+ *   ep-stage-skill run --testcase <p> [--ai-snippets <p>] [--headless false]
  *
  * 无 contract 子命令（contract 提取作为 testcase 子命令内部步骤；
  * 开发期独立调试入口为 dev/extract-contract.ts，被 pnpm generate:crud-contract 调用）。

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;;;;;;;;;;GAUG;AACH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB1E;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAYhC;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":";AAOA;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAoD1E;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"}

package/dist/src/cli/index.js

@@ -3,14 +3,15 @@ import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { parseGenerateTestcaseArgs, runGenerateTestcase } from './generate-testcase.js';
 import { parseSpecArgs, runSpec } from './spec.js';
-import { parseRunArgs, runRun } from './run.js';
+import { parseRunArgs, prepareAiRuntimeTasks, runRun } from './run.js';
 /**
  * ep-stage-skill CLI 统一入口（REQ-CLI-02 修订）：1 bin + 3 子命令。
  *
  * 用法：
- *   ep-stage-skill testcase --code-list <p> --tests-dir <p> [--scenario <v>] [--hints <p>]
+ *   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 run --spec <p> --testcase <p> [--headless false]
+ *   ep-stage-skill prepare-tasks --testcase <p>
+ *   ep-stage-skill run --testcase <p> [--ai-snippets <p>] [--headless false]
  *
  * 无 contract 子命令（contract 提取作为 testcase 子命令内部步骤；
  * 开发期独立调试入口为 dev/extract-contract.ts，被 pnpm generate:crud-contract 调用）。
@@ -23,15 +24,46 @@ export async function main(argv = process.argv) {
             return runGenerateTestcase(parseGenerateTestcaseArgs(args));
         case 'spec':
             return runSpec(parseSpecArgs(args));
-        case 'run':
-            return runRun(parseRunArgs(args));
+        case 'prepare-tasks': {
+            const result = prepareAiRuntimeTasks(parseRunArgs(args).testcase);
+            console.log([
+                `trace: ${result.tracePath}`,
+                `spec: ${result.specPath}`,
+                `ai tasks: ${result.taskCount}`,
+                `blocked: ${result.blockedCount}`,
+            ].join('\n'));
+            return result;
+        }
+        case 'run': {
+            const result = await runRun(parseRunArgs(args));
+            // 结果摘要回显（此前 run 静默退出，自动化无法感知成败）。
+            const lines = [
+                `spec: ${result.specPath}`,
+                `report: ${result.reportDir}`,
+                `trace: ${result.aiRuntimeTracePath}`,
+            ];
+            if (result.repairReportPath) {
+                lines.push(`repair: ${result.repairReportPath}`);
+            }
+            if (result.credentialsNotice) {
+                lines.push(result.credentialsNotice);
+            }
+            console.log(lines.join('\n'));
+            // 执行失败（已落修补报告）以非 0 退出，对齐 skill 文档「CLI 非 0 退出 → 复述 stderr」契约；
+            // 修补流程本身不受影响，人审确认方向后重跑即可。
+            if (result.repairReportPath) {
+                console.error(`执行失败：已落修补报告 ${result.repairReportPath}，待人审确认修补方向`);
+                process.exitCode = 1;
+            }
+            return result;
+        }
         case undefined:
         case '--help':
         case '-h':
             printHelp();
             return;
         default:
-            console.error(`未知子命令: ${subcommand}。可用: testcase / spec / run`);
+            console.error(`未知子命令: ${subcommand}。可用: testcase / spec / prepare-tasks / run`);
             process.exit(1);
     }
 }
@@ -39,17 +71,19 @@ export async function main(argv = process.argv) {
  * 打印 CLI help（仅 testcase / spec / run 3 子命令，无 contract）。
  */
 export function printHelp() {
-    console.log(`ep-stage-skill — 胶水测试链路 CLI
-
-用法:
-  ep-stage-skill testcase --code-list <path> --tests-dir <path> [--scenario <value>] [--hints <path>]
-  ep-stage-skill spec --testcase <path> --out <path>
-  ep-stage-skill run --spec <path> --testcase <path> [--headless false]
-
-子命令:
-  testcase   钻探上游物料 + 生成 testcase v2 + credentials.template + 软链 code_list
-  spec       基于 testcase + contract 生成 v1 初始版 .spec.ts（只生成不执行）
-  run        启动 Playwright 跑胶水部分 + AI 推理追加 uncoveredCandidates → 产 v2 + 报告`);
+    console.log(`ep-stage-skill — 胶水测试链路 CLI
+
+用法:
+  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]
+
+子命令:
+  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`);
 }
 /**
  * 判断当前 CLI 文件是否以“直接执行”方式启动。

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

@@ -1,63 +1,170 @@
+import type { EpStageTestcaseV1Draft } from '../testcase/testcase-v1-draft.js';
+import { type AiRuntimeResult, type AiRuntimeTask } from '../runtime/ai-runtime-trace.js';
 /**
- * run 子命令参数（REQ-CHAIN-02 / REQ-SPEC-01）。
+ * run 子命令参数（REQ-CHAIN-02 / REQ-SPEC-01，新协议 v1-draft）。
  *
- * - spec：crud.spec.ts 路径（必填，由 spec 子命令产出，v1 或已含 AI 追加段 v2）；
- * - testcase：testcase.json5 路径（必填，提供 uncoveredCandidates 与 cases[].requiredRole）；
+ * - testcase：testcase.json5 路径（必填，提供 uncoveredCandidates 与 generationStrategy 分桶）；
  * - headless：是否启动无头浏览器，真实业务系统通常 false；
- * - projectDir：报告目录基址，默认 process.cwd()。
+ * - aiSnippets：Agent O-D-A-V 产出的 ai-snippets.json5 路径。
  */
 export type RunArgs = {
-    spec: string;
     testcase: string;
     headless: boolean;
-    projectDir?: string;
+    aiSnippets?: string;
 };
 /**
- * run 子命令产物。
+ * run 子命令产物（新协议 v1-draft）。
  *
  * @property specPath - 写盘后的 .spec.ts（含 AI 追加段）。
  * @property reportDir - 本次 run 产出的报告目录。
- * @property version - 'v1-with-planned-stubs' 表示当前 run.ts 阶段产物（已追加 planned 占位但未跑真实 Playwright + AI 推理）；
- *   'v2' 保留给 Phase 5 真机验收阶段迁移完整 runtime 后使用。
+ * @property credentialsNotice - credentials.json5 消费边界声明（缺失时提示用户填充）。
+ * @property version - 'v1'：已接入 Agent snippets 合并、spec 执行和 repair 回路。
+ * @property aiRuntimeTracePath - 落盘的 .ep-stage/ai-runtime-trace.json5（含 tasks 与 results）。
+ * @property repairReportPath - 执行失败时落盘的 repair-report.md；成功时为 undefined。
  */
 export type RunResult = {
     specPath: string;
     reportDir: string;
-    version: 'v1' | 'v1-with-planned-stubs' | 'v2';
+    credentialsNotice?: string;
+    version: 'v1';
+    aiRuntimeTracePath?: string;
+    repairReportPath?: string;
+};
+/**
+ * runRun 的可注入依赖（测试即契约：允许单测替换推理与执行，避免触发真机）。
+ *
+ * 默认实现读取 Agent 产出的 ai-snippets.json5 并执行真实 Playwright；
+ * 测试通过该 seam 注入确定性桩。
+ *
+ * @property loadAiSnippets - 读取 Agent 产出的 resolved snippet。
+ * @property executeFullSpec - 从 projectDir 执行完整 spec，返回通过状态与输出。
+ */
+export type RunDeps = {
+    loadAiSnippets?: (input: {
+        snippetsPath: string;
+        testcasePath: string;
+        tasks: AiRuntimeTask[];
+    }) => AiRuntimeResult[];
+    executeFullSpec?: (input: {
+        projectDir: string;
+        specPath: string;
+        headless: boolean;
+    }) => Promise<{
+        passed: boolean;
+        output: string;
+    }>;
+};
+/**
+ * 从 testcase.json5 推导 run 阶段路径。
+ */
+export type RunPaths = {
+    testcasePath: string;
+    caseDir: string;
+    projectDir: string;
+    specPath: string;
+    contractPath: string;
+};
+export type PrepareAiRuntimeTasksResult = {
+    testcasePath: string;
+    tracePath: string;
+    specPath: string;
+    taskCount: number;
+    blockedCount: number;
+};
+export type AiSnippetsFile = {
+    schemaVersion: 'ep-stage-ai-snippets/v1';
+    testcasePath: string;
+    generatedAt?: string;
+    results: AiRuntimeResult[];
 };
 /**
  * AI 追加段分隔标记。重跑时 detect 已有标记则覆盖（保证幂等）。
+ *
+ * 注释语义：本段由 uncoveredCandidates[].generationStrategy='ai' 的候选渲染而来。
  */
-export declare const AI_APPEND_MARKER = "// === AI \u94BB\u63A2\u8FFD\u52A0\uFF08\u57FA\u4E8E uncoveredCandidates[].status=planned\uFF09===";
+export declare const AI_APPEND_MARKER = "// === AI \u94BB\u63A2\u8FFD\u52A0\uFF08\u57FA\u4E8E uncoveredCandidates[].generationStrategy=ai\uFF09===";
 /**
  * 解析 run 子命令参数。
  *
  * @param argv - 已剥离子命令名的命令行参数。
  * @returns RunArgs。
- * @throws 缺少 --spec / --testcase 或参数对非法时抛错。
+ * @throws 缺少 --testcase 或参数对非法时抛错。
  */
 export declare function parseRunArgs(argv: string[]): RunArgs;
 /**
- * run 子命令主体（REQ-CHAIN-02 / REQ-SPEC-01）。
+ * 从 testcase.json5 定位测试项目和 spec 路径。
+ *
+ * 优先消费 runtimeContext；若缺失或目录校验失败，则从 testcase 所在目录向上查找。
+ *
+ * @param testcasePath - testcase.json5 路径。
+ * @returns run 阶段消费的路径集合。
+ */
+export declare function resolveRunPaths(testcasePath: string): RunPaths;
+/**
+ * 构造从项目目录执行完整 spec 的 Playwright 命令。
+ *
+ * headless=false 时追加 --headed；specPath 原样透传（绝对路径，跨目录稳定）。
+ *
+ * @param input - projectDir / specPath / headless。
+ * @returns 命令、参数与 cwd，供 execFileSync 直接消费。
+ */
+export declare function buildPlaywrightCommand(input: {
+    projectDir: string;
+    specPath: string;
+    headless: boolean;
+}): {
+    command: 'npx';
+    args: string[];
+    cwd: string;
+};
+/**
+ * 读取并校验 Agent O-D-A-V 产出的 snippets。
+ *
+ * 只有 testcasePath 匹配、caseId 属于当前任务、status=resolved 且 specSnippet 非空时才可合并。
+ *
+ * @param input - snippets 路径、testcase 路径和当前 AI tasks。
+ * @returns 可合并的 AiRuntimeResult 列表。
+ */
+export declare function loadAiSnippets(input: {
+    snippetsPath: string;
+    testcasePath: string;
+    tasks: AiRuntimeTask[];
+}): AiRuntimeResult[];
+/**
+ * 从 testcase 构建 AI Runtime Task 列表。
+ *
+ * `coverageStatus='blocked'` 的候选仅保留在 testcase/审阅侧，不进入 runtime task。
+ *
+ * @param testcase - 已校验 testcase。
+ * @param paths - run 阶段解析出的路径。
+ * @returns AI Runtime Task 列表。
+ */
+export declare function buildAiRuntimeTasks(testcase: EpStageTestcaseV1Draft, paths: RunPaths): AiRuntimeTask[];
+/**
+ * 生成 AI Runtime 初始任务包。
+ *
+ * 该函数只做确定性工作：定位路径、补齐 glue 骨架 spec、构建 tasks 并写 trace。
+ *
+ * @param testcasePath - testcase.json5 路径。
+ * @returns trace 路径、spec 路径和任务摘要。
+ */
+export declare function prepareAiRuntimeTasks(testcasePath: string): PrepareAiRuntimeTasksResult;
+/**
+ * run 子命令主体（REQ-CHAIN-02 / REQ-SPEC-01，新协议 v1-draft）。
  *
- * 完整设计（spec §5.4 / brief Step 6）：
- * 1. 按 cases[].requiredRole 用 credentials.json5 登录；
- * 2. 跑 v1 胶水部分 spec；
- * 3. 对 uncoveredCandidates 里 status='planned' 的项做 AI 实时推理（含 requiredRole 切换）；
- * 4. 追加段以 AI_APPEND_MARKER 分隔；重跑检测已有段则覆盖（幂等）；
- * 5. 报告落 e2e/glue-code-mvp/glue-report/<timestamp>/；
- * 6. 回写 projects.index.json5 的 systems[].credentialsCache 与 requirements[].lastRun*。
+ * 行为：
+ * 1. resolveRunPaths 定位 projectDir/specPath；spec 缺失时先跑 runSpec 组装 glue 骨架。
+ * 2. 解析 testcase，构建 aiRuntimeTasks（已过滤 coverageStatus='blocked'）。
+ * 3. 读取 Agent O-D-A-V 产出的 ai-snippets.json5。
+ * 4. 若 AI tasks 未全部 resolved，则写 trace results=needs_review 并停止，避免假通过。
+ * 5. 幂等合并 specSnippet 到 spec：truncateAtMarker 后追加 marker + snippets。
+ * 6. 执行完整 spec（deps 注入或默认真实 Playwright）；失败则分类、回写 trace repairRounds 并写 repair report。
  *
- * 当前 Sub-step 6 范围：
- * - 完整实现「步骤 4」（AI 追加段幂等覆盖契约）；
- * - 完整实现「步骤 5」（报告目录生成）；
- * - 步骤 1 / 2 / 3 / 6 的 Playwright runtime + AI 推理 + 索引回写在 Phase 5 真机验收阶段
- *   迁移 run-gap-pipeline.ts 的 runtime runner 实现接入（brief 已说明 AI 推理在 Phase 5 证）。
+ * 失败时不静默改变测试意图：写 repair-report.md 等待人审确认。
  *
  * @param args - 已解析参数。
- * @returns version: 'v1-with-planned-stubs' — 真实的 v2（Playwright 执行 + AI 推理填充 planned 项）
- *   待 Phase 5 真机验收阶段从 run-gap-pipeline.ts 的 runtime runner 迁移过来。当前返回 'v1-with-planned-stubs'
- *   而非 'v2' 是为了让下游 skill（glue-run-test 等）能区分"真 v2"与"stub 形态"。
+ * @param deps - 可选注入依赖（测试用于替换推理与执行）。
+ * @returns RunResult。
  */
-export declare function runRun(args: RunArgs): Promise<RunResult>;
+export declare function runRun(args: RunArgs, deps?: RunDeps): Promise<RunResult>;
 //# sourceMappingURL=run.d.ts.map