@epoint-testtech/ep-stage-skill 0.0.3-alpha.2 → 0.0.4-alpha.0

package/dist/src/cli/generate-crud-contract.js

@@ -1,77 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import { buildCrudBusinessModuleContract, extractCodeListSummary, extractHtmlPage, extractJavaAction, extractSpecYaml } from '../index.js';
-function parseArgs(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(`Invalid argument pair near ${key ?? '<empty>'}`);
-        }
-        result[key.slice(2)] = value;
-    }
-    if (result.module) {
-        throw new Error('已废弃 --module，请使用 --module-id。' +
-            '例: pnpm generate:crud-contract -- --module-id zwplace ...');
-    }
-    const required = ['module-id', 'docs', 'code-list', 'webapp', 'java-actions', 'out'];
-    for (const key of required) {
-        if (!result[key]) {
-            throw new Error(`Missing required argument --${key}`);
-        }
-    }
-    return {
-        module: result['module-id'],
-        docs: result.docs,
-        codeList: result['code-list'],
-        webapp: result.webapp,
-        javaActions: result['java-actions'],
-        hints: result.hints,
-        out: result.out
-    };
-}
-function htmlFiles(dir) {
-    return readdirSync(dir)
-        .filter((fileName) => fileName.endsWith('.html'))
-        .sort()
-        .map((fileName) => path.join(dir, fileName));
-}
-function javaFiles(dir) {
-    return readdirSync(dir)
-        .filter((fileName) => fileName.endsWith('Action.java'))
-        .sort()
-        .map((fileName) => path.join(dir, fileName));
-}
-const args = parseArgs(process.argv.slice(2));
-const hints = args.hints
-    ? JSON.parse(readFileSync(args.hints, 'utf8'))
-    : undefined;
-const codeList = extractCodeListSummary(args.codeList);
-function resolveSpec(docsDir, moduleId, codeListSummary) {
-    const specPath = path.join(docsDir, 'spec.yaml');
-    if (existsSync(specPath)) {
-        return extractSpecYaml(specPath);
-    }
-    return {
-        path: specPath,
-        module: {
-            id: moduleId,
-            label: codeListSummary.moduleLabel
-        },
-        fields: [],
-        businessRules: []
-    };
-}
-const contract = buildCrudBusinessModuleContract({
-    moduleId: args.module,
-    spec: resolveSpec(args.docs, args.module, codeList),
-    codeList,
-    pages: htmlFiles(args.webapp).map(extractHtmlPage),
-    actions: javaFiles(args.javaActions).map(extractJavaAction),
-    hints
-});
-mkdirSync(path.dirname(args.out), { recursive: true });
-writeFileSync(args.out, `${JSON.stringify(contract, null, 2)}\n`, 'utf8');
-console.log(`Wrote ${args.out}`);
+import { runExtractContract } from './dev/extract-contract.js';
+/**
+ * 旧 pnpm script 入口薄壳（REQ-CLI-03 修订）：所有逻辑搬到 dev/extract-contract.ts。
+ * 本文件不删除，保持旧 pnpm script `generate:crud-contract` 零回归；新代码请直接
+ * 调用 `runExtractContract`。
+ */
+runExtractContract(process.argv.slice(2));

package/dist/src/cli/generate-playwright-tests.d.ts

@@ -1,30 +1,2 @@
-/**
- * Playwright 测试脚本生成 CLI 入口
- *
- * 从 CRUD 业务模块契约 JSON 文件生成基于 glue 模板骨架的 Playwright 测试脚本。
- *
- * 使用方式：
- * ```bash
- * pnpm generate:playwright-tests -- \
- *   --contract <contract-json-path> \
- *   --out <output-spec-ts-path> \
- *   --menu <menu-path> \
- *   --testcase <glue-testcase-json-path>
- * ```
- *
- * 参数说明：
- * - --contract (必填): 契约 JSON 文件路径
- * - --out (必填): 输出的 .spec.ts 文件路径
- * - --menu (必填): 菜单路径，传给 MenuPage.navigateToMenu()
- * - --testcase (可选): 已确认的 glue testcase JSON；传入后会校验用例与 contract 粒度一致。
- *
- * 示例：
- * ```bash
- * pnpm generate:playwright-tests -- \
- *   --contract output/zwplace.crud.contract.json \
- *   --out ../stage-project/src/tests/generated-zwplace.skeleton.spec.ts \
- *   --menu "场所窗口信息管理>场所窗口信息列表"
- * ```
- */
 export {};
 //# sourceMappingURL=generate-playwright-tests.d.ts.map

package/dist/src/cli/generate-playwright-tests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-playwright-tests.d.ts","sourceRoot":"","sources":["../../../src/cli/generate-playwright-tests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}
+{"version":3,"file":"generate-playwright-tests.d.ts","sourceRoot":"","sources":["../../../src/cli/generate-playwright-tests.ts"],"names":[],"mappings":""}

package/dist/src/cli/generate-playwright-tests.js

@@ -1,81 +1,4 @@
-/**
- * Playwright 测试脚本生成 CLI 入口
- *
- * 从 CRUD 业务模块契约 JSON 文件生成基于 glue 模板骨架的 Playwright 测试脚本。
- *
- * 使用方式：
- * ```bash
- * pnpm generate:playwright-tests -- \
- *   --contract <contract-json-path> \
- *   --out <output-spec-ts-path> \
- *   --menu <menu-path> \
- *   --testcase <glue-testcase-json-path>
- * ```
- *
- * 参数说明：
- * - --contract (必填): 契约 JSON 文件路径
- * - --out (必填): 输出的 .spec.ts 文件路径
- * - --menu (必填): 菜单路径，传给 MenuPage.navigateToMenu()
- * - --testcase (可选): 已确认的 glue testcase JSON；传入后会校验用例与 contract 粒度一致。
- *
- * 示例：
- * ```bash
- * pnpm generate:playwright-tests -- \
- *   --contract output/zwplace.crud.contract.json \
- *   --out ../stage-project/src/tests/generated-zwplace.skeleton.spec.ts \
- *   --menu "场所窗口信息管理>场所窗口信息列表"
- * ```
- */
-import { readFileSync, writeFileSync } from 'node:fs';
-import { generateStageSkeletonCrudSpec } from '../generators/stage-skeleton-script.js';
-import { validateGlueTestcaseDocumentForSpecAssembly } from '../testcase/testcase-spec-assembly.js';
-/**
- * 解析命令行参数
- *
- * 将 process.argv 转换为结构化的参数对象。
- * 支持 `--key value` 格式的参数对，自动过滤 `--` 分隔符。
- *
- * @param argv - 命令行参数数组（不含 node 和脚本路径）
- * @returns 解析后的参数对象
- * @throws 当参数格式无效或缺少必填参数时抛出错误
- */
-function parseArgs(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)] = value;
-    }
-    // 验证必填参数
-    if (!result.contract || !result.out || !result.menu) {
-        throw new Error('用法: tsx generate-playwright-tests.ts --contract <path> --out <path> --menu <menu-path>');
-    }
-    return {
-        contract: result.contract,
-        out: result.out,
-        menu: result.menu,
-        testcase: result.testcase,
-    };
-}
-// 执行主流程
-const args = parseArgs(process.argv.slice(2));
-// 读取契约 JSON 文件
-const contract = JSON.parse(readFileSync(args.contract, 'utf8'));
-if (args.testcase) {
-    const testcaseDocument = JSON.parse(readFileSync(args.testcase, 'utf8'));
-    validateGlueTestcaseDocumentForSpecAssembly(testcaseDocument, contract);
-}
-// 生成基于 glue 模板骨架的 Playwright 测试脚本
-const script = generateStageSkeletonCrudSpec({
-    contract,
-    menuNavigation: args.menu
-});
-// 写入输出文件
-writeFileSync(args.out, script, 'utf8');
-console.log(`已生成 ${args.out}`);
+// 薄壳：保留旧入口零回归，实际逻辑见 ./spec.ts（src/cli/index.ts spec 子命令统一入口）。
+// 新参数：--testcase <p> --out <p>（旧的 --contract / --menu 已迁移到 testcase 子命令 + spec 子命令链路）。
+import { parseSpecArgs, runSpec } from './spec.js';
+runSpec(parseSpecArgs(process.argv.slice(2)));

package/dist/src/cli/generate-testcase.d.ts

@@ -0,0 +1,83 @@
+import type { TestcaseV2 } from '../testcase/testcase-v2.js';
+/**
+ * testcase 子命令解析后的参数（REQ-CHAIN-01 / REQ-SCENE-01）。
+ *
+ * - codeList：上游 code_list.md 绝对路径（必填）；
+ * - testsDir：<projectDir>/src/tests/<需求名> 绝对路径（必填）；
+ * - scenario：①档优先级（显式 CLI 参数）；
+ * - hints：ModuleHints JSON 路径（可选；推断 scenario 用）；
+ * - projectDir / requirementDir：可选覆盖，默认从 codeList 路径推断。
+ */
+export type GenerateTestcaseArgs = {
+    codeList: string;
+    testsDir: string;
+    scenario?: string;
+    hints?: string;
+    projectDir?: string;
+    requirementDir?: string;
+};
+/**
+ * testcase 子命令产物 + 推断结果（供 skill Step 5 交互确认）。
+ */
+export type GenerateTestcaseResult = {
+    testcasePath: string;
+    testcaseMdPath: string;
+    credentialsTemplatePath: string;
+    inference: {
+        scenario: string;
+        requiredSystems: TestcaseV2['requiredSystems'];
+        requiredRoles: TestcaseV2['requiredRoles'];
+        credentialsTemplatePath: string;
+        credentialsActualPath: string;
+        cachedSystemsHit: string[];
+    };
+};
+/**
+ * 解析 testcase 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns 解析后的 GenerateTestcaseArgs。
+ * @throws 缺少 --code-list 或 --tests-dir 时抛错。
+ */
+export declare function parseGenerateTestcaseArgs(argv: string[]): GenerateTestcaseArgs;
+/**
+ * scenario 3 档决策（REQ-SCENE-01）：
+ * 1. --scenario CLI 参数（最高优先级）
+ * 2. ModuleHints 文件路径包含 `scenario=<value>` 字串（粗推断）
+ * 3. 默认 "crud.single-page"（与 i18n 表 / skeleton scenario 一致）
+ *
+ * @param args - 解析后的参数。
+ * @returns 决策结果。
+ */
+export declare function decideScenario(args: GenerateTestcaseArgs): string;
+/**
+ * 把 TestcaseV2 渲染成中文 testcase.md（REQ-UX-03）。
+ *
+ * 设计：
+ * - 字段名 / 状态值通过 i18nTestcase() 翻译；
+ * - `unresolved` 字段标题硬编码「未确认项」（i18n 表中 `unresolved` 解析为状态值「未解决」）；
+ * - 每次重跑覆盖（REQ-DATA-03 由调用方 writeFileSync 触发）。
+ *
+ * @param testcase - TestcaseV2 顶层结构。
+ * @returns Markdown 文本。
+ */
+export declare function renderTestcaseMarkdown(testcase: TestcaseV2): string;
+/**
+ * testcase 子命令主体（REQ-CHAIN-01 / REQ-CHAIN-02 / REQ-SCENE-01 / REQ-DATA-02）。
+ *
+ * 流程：
+ * 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 边界，保持职责单一）。
+ *
+ * @param args - 已解析参数。
+ * @returns 产物路径 + 推断结果。
+ */
+export declare function runGenerateTestcase(args: GenerateTestcaseArgs): GenerateTestcaseResult;
+//# sourceMappingURL=generate-testcase.d.ts.map

package/dist/src/cli/generate-testcase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-testcase.d.ts","sourceRoot":"","sources":["../../../src/cli/generate-testcase.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC;QAC/C,aAAa,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;QAC3C,uBAAuB,EAAE,MAAM,CAAC;QAChC,qBAAqB,EAAE,MAAM,CAAC;QAC9B,gBAAgB,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC;CACH,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAqB9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAOjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAgDnE;AAsBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,sBAAsB,CA+CtF"}

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

@@ -0,0 +1,197 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+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';
+/**
+ * 解析 testcase 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns 解析后的 GenerateTestcaseArgs。
+ * @throws 缺少 --code-list 或 --tests-dir 时抛错。
+ */
+export function parseGenerateTestcaseArgs(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)] = value;
+    }
+    if (!result['code-list'])
+        throw new Error('缺少 --code-list');
+    if (!result['tests-dir'])
+        throw new Error('缺少 --tests-dir');
+    return {
+        codeList: result['code-list'],
+        testsDir: result['tests-dir'],
+        scenario: result.scenario,
+        hints: result.hints,
+        projectDir: result['project-dir'],
+        requirementDir: result['requirement-dir'],
+    };
+}
+/**
+ * scenario 3 档决策（REQ-SCENE-01）：
+ * 1. --scenario CLI 参数（最高优先级）
+ * 2. ModuleHints 文件路径包含 `scenario=<value>` 字串（粗推断）
+ * 3. 默认 "crud.single-page"（与 i18n 表 / skeleton scenario 一致）
+ *
+ * @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。
+ * @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,
+    }));
+    return `${JSON5.stringify(entries, null, 2)}\n`;
+}
+/**
+ * testcase 子命令主体（REQ-CHAIN-01 / REQ-CHAIN-02 / REQ-SCENE-01 / REQ-DATA-02）。
+ *
+ * 流程：
+ * 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 边界，保持职责单一）。
+ *
+ * @param args - 已解析参数。
+ * @returns 产物路径 + 推断结果。
+ */
+export function runGenerateTestcase(args) {
+    const scenario = decideScenario(args);
+    mkdirSync(args.testsDir, { recursive: true });
+    const requirementDir = args.requirementDir ?? path.dirname(args.codeList);
+    const docsDir = requirementDir;
+    const webappDir = path.join(requirementDir, 'src/main/webapp');
+    const javaActionsDir = path.join(requirementDir, 'src/main/java');
+    const moduleId = path.basename(args.testsDir);
+    const { contract, testcaseV2 } = runProbeAndCoverage({
+        moduleId,
+        codeListPath: args.codeList,
+        docsDir,
+        webappDir,
+        javaActionsDir,
+        hintsPath: args.hints,
+        scenario,
+    });
+    const epStageDir = path.join(args.testsDir, '.ep-stage');
+    mkdirSync(epStageDir, { recursive: true });
+    const contractPath = path.join(epStageDir, 'contract.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');
+    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'));
+    return {
+        testcasePath,
+        testcaseMdPath,
+        credentialsTemplatePath,
+        inference: {
+            scenario,
+            requiredSystems: testcaseV2.requiredSystems,
+            requiredRoles: testcaseV2.requiredRoles,
+            credentialsTemplatePath,
+            credentialsActualPath,
+            cachedSystemsHit: [],
+        },
+    };
+}

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

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * 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 spec --testcase <p> --out <p>
+ *   ep-stage-skill run --spec <p> --testcase <p> [--headless false]
+ *
+ * 无 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）。
+ */
+export declare function printHelp(): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AAKA;;;;;;;;;;GAUG;AACH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB1E;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAYhC"}

package/dist/src/cli/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { parseGenerateTestcaseArgs, runGenerateTestcase } from './generate-testcase.js';
+import { parseSpecArgs, runSpec } from './spec.js';
+import { parseRunArgs, 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 spec --testcase <p> --out <p>
+ *   ep-stage-skill run --spec <p> --testcase <p> [--headless false]
+ *
+ * 无 contract 子命令（contract 提取作为 testcase 子命令内部步骤；
+ * 开发期独立调试入口为 dev/extract-contract.ts，被 pnpm generate:crud-contract 调用）。
+ */
+export async function main(argv = process.argv) {
+    const [, , subcommand, ...rest] = argv;
+    const args = rest.filter((arg) => arg !== '--');
+    switch (subcommand) {
+        case 'testcase':
+            return runGenerateTestcase(parseGenerateTestcaseArgs(args));
+        case 'spec':
+            return runSpec(parseSpecArgs(args));
+        case 'run':
+            return runRun(parseRunArgs(args));
+        case undefined:
+        case '--help':
+        case '-h':
+            printHelp();
+            return;
+        default:
+            console.error(`未知子命令: ${subcommand}。可用: testcase / spec / run`);
+            process.exit(1);
+    }
+}
+/**
+ * 打印 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 + 报告`);
+}
+// 直接执行时调用 main；作为模块 import 时由调用方决定是否执行。
+if (import.meta.url === `file://${process.argv[1]}`) {
+    await main();
+}

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

@@ -0,0 +1,44 @@
+import type { CrudBusinessModuleContract } from '../contracts/crud-business-module.js';
+import type { CoverageDiffTrace } from '../contracts/observable-chain.js';
+import type { TestcaseV2 } from '../testcase/testcase-v2.js';
+/**
+ * probe 子模块入参（REQ-CHAIN-01）。
+ *
+ * 把 run-gap-pipeline.ts 与 generate-testcase.ts 共用的「物料解析 → contract 构建 →
+ * skeleton coverage → coverage diff」段抽成单一入口，避免两侧复制实现。
+ */
+export type ProbeAndCoverageArgs = {
+    moduleId: string;
+    codeListPath: string;
+    docsDir: string;
+    webappDir: string;
+    javaActionsDir: string;
+    hintsPath?: string;
+    scenario: string;
+    menuPath?: string;
+};
+/**
+ * probe 子模块产物。
+ *
+ * @property contract - 标准化后的 CRUD 业务模块契约。
+ * @property coverageDiff - 骨架 vs gap 覆盖度差异 trace。
+ * @property testcaseV2 - 装配后的 testcase v2 顶层结构（待 generate-testcase 写入 .json5）。
+ */
+export type ProbeAndCoverageResult = {
+    contract: CrudBusinessModuleContract;
+    coverageDiff: CoverageDiffTrace;
+    testcaseV2: TestcaseV2;
+};
+/**
+ * probe + coverage + testcase v2 装配的统一入口（REQ-CHAIN-01）。
+ *
+ * 把 run-gap-pipeline.ts 与 generate-testcase.ts 共用的物料解析 → contract → skeleton coverage →
+ * coverage diff 段抽成单一函数，避免 1881 行 run-gap-pipeline.ts 与新 CLI 双份维护。
+ *
+ * 注意：本函数只做钻探与装配，不写文件；写盘由调用方负责（保持 I/O 边界清晰）。
+ *
+ * @param args - 物料路径 + 场景。
+ * @returns contract + coverageDiff + 装配好的 TestcaseV2。
+ */
+export declare function runProbeAndCoverage(args: ProbeAndCoverageArgs): ProbeAndCoverageResult;
+//# sourceMappingURL=probe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../../src/cli/probe.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,0BAA0B,EAAe,MAAM,sCAAsC,CAAC;AACpG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,YAAY,EAAE,iBAAiB,CAAC;IAChC,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC;AA+LF;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,sBAAsB,CAkCtF"}