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

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

@@ -1,9 +1,14 @@
-import { mkdirSync, writeFileSync } from 'node:fs';
+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 { writeProjectIndex } from '../context/stage-context.js';
 /**
  * 解析 testcase 子命令参数。
  *
@@ -134,6 +139,89 @@ function renderCredentialsTemplate(testcase) {
     }));
     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，不存在则追加。
+ *
+ * @param input - projectDir / requirementName / requirementDir / testsDir / homeDir。
+ * @returns 写入后的索引文件路径。
+ * @throws projectDir 不在 index 时抛中文错误。
+ */
+function appendRequirementToProjectIndex(input) {
+    const homeDir = input.homeDir ?? os.homedir();
+    const indexPath = path.join(homeDir, '.ep-stage', 'projects.index.json5');
+    let parsed;
+    if (existsSync(indexPath)) {
+        parsed = JSON5.parse(readFileSync(indexPath, 'utf8'));
+        parsed.projects = parsed.projects ?? [];
+        parsed.systems = parsed.systems ?? [];
+    }
+    else {
+        parsed = { projects: [], systems: [] };
+    }
+    const targetProjectDir = path.resolve(input.projectDir);
+    const projectIdx = parsed.projects.findIndex((p) => path.resolve(p.projectDir) === targetProjectDir);
+    if (projectIdx === -1) {
+        throw new Error(`未在 ~/.ep-stage/projects.index.json5 找到 projectDir=${input.projectDir} 的 glue 项目，请先跑 /glue-create-project 创建脚手架`);
+    }
+    const projects = parsed.projects;
+    const project = projects[projectIdx];
+    project.requirements = project.requirements ?? [];
+    const entry = {
+        name: input.requirementName,
+        requirementDir: input.requirementDir,
+        testsDir: input.testsDir,
+        lastRunStatus: 'never',
+    };
+    // 去重：同 name 存在则更新，不存在则追加。
+    const existIdx = project.requirements.findIndex((r) => r.name === entry.name);
+    if (existIdx >= 0) {
+        project.requirements[existIdx] = entry;
+    }
+    else {
+        project.requirements.push(entry);
+    }
+    return writeProjectIndex({ homeDir, projects, systems: parsed.systems });
+}
 /**
  * testcase 子命令主体（REQ-CHAIN-01 / REQ-CHAIN-02 / REQ-SCENE-01 / REQ-DATA-02）。
  *
@@ -155,36 +243,51 @@ 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({
+    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,
-        javaActionsDir,
-        hintsPath: args.hints,
+        webappDir: resolvedInputs.webappDir,
+        javaActionsDir: resolvedInputs.javaActionsDir,
+        hintsPath: args.hints ?? resolvedInputs.hintsPath,
         scenario,
     });
     const epStageDir = path.join(args.testsDir, '.ep-stage');
     mkdirSync(epStageDir, { recursive: true });
     const contractPath = path.join(epStageDir, 'contract.json');
+    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。
+    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,
+        });
+    }
     return {
         testcasePath,
         testcaseMdPath,
         credentialsTemplatePath,
+        inferenceTracePath,
         inference: {
             scenario,
             requiredSystems: testcaseV2.requiredSystems,

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

@@ -15,4 +15,12 @@ export declare function main(argv?: string[]): Promise<unknown>;
  * 打印 CLI help（仅 testcase / spec / run 3 子命令，无 contract）。
  */
 export declare function printHelp(): void;
+/**
+ * 判断当前 CLI 文件是否以“直接执行”方式启动。
+ *
+ * @param importMetaUrl - 当前模块的 import.meta.url。
+ * @param argv1 - 进程入口参数，可能是 npm bin 软链路径。
+ * @returns 若当前模块就是实际执行入口则返回 true。
+ */
+export declare function isDirectExecution(importMetaUrl: string, argv1: string | undefined): boolean;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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"}

package/dist/src/cli/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+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';
@@ -49,7 +51,25 @@ export function printHelp() {
   spec       基于 testcase + contract 生成 v1 初始版 .spec.ts（只生成不执行）
   run        启动 Playwright 跑胶水部分 + AI 推理追加 uncoveredCandidates → 产 v2 + 报告`);
 }
+/**
+ * 判断当前 CLI 文件是否以“直接执行”方式启动。
+ *
+ * @param importMetaUrl - 当前模块的 import.meta.url。
+ * @param argv1 - 进程入口参数，可能是 npm bin 软链路径。
+ * @returns 若当前模块就是实际执行入口则返回 true。
+ */
+export function isDirectExecution(importMetaUrl, argv1) {
+    try {
+        if (!argv1) {
+            return false;
+        }
+        return realpathSync(fileURLToPath(importMetaUrl)) === realpathSync(argv1);
+    }
+    catch {
+        return false;
+    }
+}
 // 直接执行时调用 main；作为模块 import 时由调用方决定是否执行。
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isDirectExecution(import.meta.url, process.argv[1])) {
     await main();
 }

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

@@ -1,6 +1,7 @@
 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';
+import type { InferenceTraceV1 } from '../contracts/inference-trace.js';
 /**
  * probe 子模块入参（REQ-CHAIN-01）。
  *
@@ -28,6 +29,7 @@ export type ProbeAndCoverageResult = {
     contract: CrudBusinessModuleContract;
     coverageDiff: CoverageDiffTrace;
     testcaseV2: TestcaseV2;
+    inferenceTrace: InferenceTraceV1;
 };
 /**
  * probe + coverage + testcase v2 装配的统一入口（REQ-CHAIN-01）。

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

@@ -1 +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"}
+{"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;AAI7D,OAAO,KAAK,EAAE,gBAAgB,EAAoE,MAAM,iCAAiC,CAAC;AAI1I;;;;;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;IACvB,cAAc,EAAE,gBAAgB,CAAC;CAClC,CAAC;AAoYF;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,sBAAsB,CAuFtF"}

package/dist/src/cli/probe.js

@@ -10,6 +10,8 @@ import { createSkeletonCoverage } from '../gap-planner/skeleton-coverage.js';
 import { planAgentInferredWorkflows } from '../gap-planner/plan-agent-workflows.js';
 import { summarizePageStructure } from '../capability/page-structure.js';
 import { createCoverageDiff } from '../capability/coverage-diff.js';
+import { buildSourceAnalysis } from '../inference/source-analysis.js';
+import { inferModuleHintsFromMaterials } from '../inference/module-hints-inference.js';
 /**
  * 收集指定目录下的 HTML 物料文件。
  *
@@ -35,23 +37,130 @@ function javaFiles(dir) {
         .map((fileName) => path.join(dir, fileName));
 }
 /**
- * 解析 docs 目录下的 spec.yaml；缺失时返回最小空骨架。
+ * 根据页面 ID 推断 CRUD 页面角色。
+ *
+ * @param pageId - 页面标识。
+ * @returns CRUD 页面角色。
+ */
+function inferCrudPageRole(pageId) {
+    if (pageId.endsWith('add'))
+        return 'add';
+    if (pageId.endsWith('edit'))
+        return 'edit';
+    if (pageId.endsWith('detail'))
+        return 'detail';
+    return 'list';
+}
+/**
+ * 将 HTML 控件类型映射为 spec.yaml 兼容的组件类型。
+ *
+ * @param controlType - HTML extractor 提取到的控件类型。
+ * @returns spec 字段组件类型。
+ */
+function mapHtmlControlTypeToSpecComponent(controlType) {
+    if (controlType === 'mini-combobox') {
+        return 'listbox';
+    }
+    if (controlType === 'mini-textarea') {
+        return 'textarea';
+    }
+    return 'input';
+}
+/**
+ * 在缺少 spec.yaml 时，根据 HTML 页面结构合成最小可用的 spec。
+ *
+ * 设计取舍：
+ * - searchable: 仅由列表页搜索区字段决定；
+ * - formVisible: 由 add/edit 页面字段决定；
+ * - listVisible: 优先取列表页 datagrid 列定义；
+ * - businessRules: 当前无法可靠结构化抽取，保持空数组，交给 testcase 审阅阶段。
+ *
+ * @param docsDir - 需求文档目录。
+ * @param moduleId - 模块 ID。
+ * @param codeListSummary - code_list 摘要。
+ * @param pages - 已提取的 HTML 页面集合。
+ * @returns 供 contract 正常生成使用的推理 spec。
+ */
+function inferSpecFromPages(docsDir, moduleId, codeListSummary, pages) {
+    const fieldMap = new Map();
+    const listPage = pages.find((page) => inferCrudPageRole(page.pageId) === 'list');
+    /**
+     * 合并同名字段的页面证据，避免列表页 / 新增页重复字段互相覆盖。
+     *
+     * @param field - 当前页面字段。
+     * @param role - 当前页面角色。
+     * @returns 无返回值。
+     */
+    function mergeField(field, role) {
+        const existing = fieldMap.get(field.name) ?? {
+            name: field.name,
+            label: field.label,
+            component: mapHtmlControlTypeToSpecComponent(field.controlType),
+            required: field.required,
+            searchable: false,
+            listVisible: false,
+            formVisible: false,
+            length: field.maxLength,
+        };
+        existing.label ||= field.label;
+        existing.component ||= mapHtmlControlTypeToSpecComponent(field.controlType);
+        existing.required ||= field.required;
+        existing.length ??= field.maxLength;
+        if (role === 'list') {
+            existing.searchable = true;
+        }
+        if (role === 'add' || role === 'edit') {
+            existing.formVisible = true;
+        }
+        fieldMap.set(field.name, existing);
+    }
+    for (const page of pages) {
+        const role = inferCrudPageRole(page.pageId);
+        for (const field of page.fields) {
+            mergeField(field, role);
+        }
+    }
+    for (const column of listPage?.grids.flatMap((grid) => grid.dataColumns) ?? []) {
+        if (!column.field) {
+            continue;
+        }
+        const existing = fieldMap.get(column.field) ?? {
+            name: column.field,
+            label: column.headerText || column.field,
+            component: 'input',
+            required: false,
+            searchable: false,
+            listVisible: false,
+            formVisible: false,
+        };
+        existing.label ||= column.headerText || column.field;
+        existing.listVisible = true;
+        fieldMap.set(column.field, existing);
+    }
+    return {
+        path: path.join(docsDir, 'spec.inferred-from-html.yaml'),
+        module: {
+            id: moduleId,
+            label: codeListSummary.moduleLabel || moduleId,
+        },
+        fields: Array.from(fieldMap.values()),
+        businessRules: [],
+    };
+}
+/**
+ * 解析 docs 目录下的 spec.yaml；缺失时根据 HTML 页面结构合成 fallback spec。
  *
  * @param docsDir - 需求文档目录。
  * @param moduleId - 模块 ID。
  * @param codeListSummary - 已解析的 code_list 摘要。
+ * @param pages - 已提取的 HTML 页面集合。
  * @returns ExtractedSpecYaml。
  */
-function resolveSpec(docsDir, moduleId, codeListSummary) {
+function resolveSpec(docsDir, moduleId, codeListSummary, pages) {
     const specPath = path.join(docsDir, 'spec.yaml');
     if (existsSync(specPath))
         return extractSpecYaml(specPath);
-    return {
-        path: specPath,
-        module: { id: moduleId, label: codeListSummary.moduleLabel },
-        fields: [],
-        businessRules: [],
-    };
+    return inferSpecFromPages(docsDir, moduleId, codeListSummary, pages);
 }
 /**
  * 推断 requiredRole 默认值。
@@ -173,6 +282,75 @@ function assembleTestcaseV2(input) {
         },
     };
 }
+/**
+ * 组装 materialInventory 章节（spec §7）。
+ *
+ * 把 probe 已解析到的 codeList / pages / actions / args 登记成可审阅的物料清单，
+ * 缺失项进 `missing` 数组。保持私有，不做跨文件抽象（Task 3 范围）。
+ *
+ * @param args - probe 入参。
+ * @param codeList - 已解析的 code_list 摘要。
+ * @param pages - 已抽取的 HTML 页面。
+ * @param actions - 已抽取的 Java Action。
+ * @returns MaterialInventoryTrace。
+ */
+function buildMaterialInventory(args, codeList, pages, actions) {
+    const missing = [];
+    const moduleIdSlot = { status: 'resolved', value: args.moduleId };
+    const menuSlot = codeList.menu
+        ? { status: 'resolved', value: codeList.menu }
+        : (() => {
+            missing.push('menu');
+            return { status: 'missing', reason: 'code_list.md 未提供 menu' };
+        })();
+    const htmlFiles = pages.map((page) => ({
+        status: 'resolved',
+        value: page.path,
+    }));
+    const javaActionFiles = actions.map((action) => ({
+        status: 'resolved',
+        value: action.path,
+    }));
+    const docsFiles = [];
+    if (args.docsDir && existsSync(args.docsDir)) {
+        docsFiles.push({ status: 'resolved', value: args.docsDir });
+    }
+    else {
+        missing.push('docsDir');
+        docsFiles.push({ status: 'missing', reason: '未提供 docsDir' });
+    }
+    return {
+        knowledgeRoot: codeList.knowledgeRoot ?? '',
+        moduleId: moduleIdSlot,
+        menu: menuSlot,
+        htmlFiles,
+        javaActionFiles,
+        docsFiles,
+        missing,
+    };
+}
+/**
+ * 把 coverageDiff（CoverageDiffTrace）映射为 InferenceTraceV1.coverageDiff 的内联形状。
+ *
+ * 映射规则（controller 裁定）：
+ * - coveredActions ← coverageDiff.covered
+ * - uncoveredCandidates ← [...gapCandidates, ...partiallyCovered, ...unresolved]
+ * - needsReview ← unresolved.map(i => i.actionId)
+ *
+ * @param coverageDiff - probe 产出的 CoverageDiffTrace。
+ * @returns InferenceTraceV1.coverageDiff。
+ */
+function mapCoverageDiffForTrace(coverageDiff) {
+    return {
+        coveredActions: coverageDiff.covered,
+        uncoveredCandidates: [
+            ...coverageDiff.gapCandidates,
+            ...coverageDiff.partiallyCovered,
+            ...coverageDiff.unresolved,
+        ],
+        needsReview: coverageDiff.unresolved.map((item) => item.actionId),
+    };
+}
 /**
  * probe + coverage + testcase v2 装配的统一入口（REQ-CHAIN-01）。
  *
@@ -185,16 +363,43 @@ function assembleTestcaseV2(input) {
  * @returns contract + coverageDiff + 装配好的 TestcaseV2。
  */
 export function runProbeAndCoverage(args) {
-    const hints = args.hintsPath
-        ? JSON.parse(readFileSync(args.hintsPath, 'utf8'))
-        : undefined;
     const codeList = extractCodeListSummary(args.codeListPath);
     const pages = htmlFiles(args.webappDir).map(extractHtmlPage);
     const actions = javaFiles(args.javaActionsDir).map(extractJavaAction);
+    // 源分析快照（spec §7 sourceAnalysis）。
+    const sourceAnalysis = buildSourceAnalysis({
+        codeListPath: args.codeListPath,
+        docsDir: args.docsDir,
+        codeList,
+        pages,
+        actions,
+    });
+    // 显式 hints 文件 vs 推理 hints：
+    // - 有 hintsPath 时读取为 explicitHints，mode 标记 explicit_override，explicitHints 流入 builders。
+    // - 无 hintsPath 时调 inferModuleHintsFromMaterials，推理出的 hints 流入 builders（替换原 undefined）。
+    let hints;
+    let moduleHintsInference;
+    if (args.hintsPath) {
+        const explicitHints = JSON.parse(readFileSync(args.hintsPath, 'utf8'));
+        // 仍跑一次推理以记录推理过程，但 mode 标记 explicit_override，builders 用 explicitHints。
+        const inferred = inferModuleHintsFromMaterials({
+            sourceAnalysis,
+            pages,
+            actions,
+            explicitHints,
+        });
+        moduleHintsInference = { ...inferred.inference, mode: 'explicit_override' };
+        hints = explicitHints;
+    }
+    else {
+        const inferred = inferModuleHintsFromMaterials({ sourceAnalysis, pages, actions });
+        moduleHintsInference = inferred.inference;
+        hints = inferred.hints;
+    }
     const pageStructures = pages.map(summarizePageStructure);
     const contract = buildCrudBusinessModuleContract({
         moduleId: args.moduleId,
-        spec: resolveSpec(args.docsDir, args.moduleId, codeList),
+        spec: resolveSpec(args.docsDir, args.moduleId, codeList, pages),
         codeList,
         pages,
         actions,
@@ -217,5 +422,26 @@ export function runProbeAndCoverage(args) {
         menuPath: args.menuPath ?? codeList.menu ?? '',
         codeListPath: args.codeListPath,
     });
-    return { contract, coverageDiff, testcaseV2 };
+    // 组装 inference trace（REQ-INFER-004 / REQ-INFER-006）。
+    const materialInventory = buildMaterialInventory(args, codeList, pages, actions);
+    const reasoningSummary = {
+        conclusion: `基于 ${sourceAnalysis.mode} 源分析（置信度 ${sourceAnalysis.confidence}）与 ${moduleHintsInference.mode} 槽位推理生成契约；coverageDiff unresolved ${coverageDiff.unresolved.length} 项。`,
+        confidence: sourceAnalysis.confidence,
+        risks: [
+            ...sourceAnalysis.unresolved,
+            ...moduleHintsInference.unresolved.map((slot) => `未解析槽位：${slot}`),
+        ],
+        needsHumanReview: moduleHintsInference.unresolved.length > 0 || sourceAnalysis.confidence === 'low',
+    };
+    const inferenceTrace = {
+        schemaVersion: 'inference-trace/v1',
+        codeListPath: args.codeListPath,
+        generatedAt: new Date().toISOString(),
+        materialInventory,
+        sourceAnalysis,
+        moduleHintsInference,
+        coverageDiff: mapCoverageDiffForTrace(coverageDiff),
+        reasoningSummary,
+    };
+    return { contract, coverageDiff, testcaseV2, inferenceTrace };
 }

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

@@ -34,9 +34,12 @@ export declare function parseSpecArgs(argv: string[]): SpecArgs;
  *
  * 实现：
  * 1. 校验 testcase.json5 通过 validateTestcase（v2 schema）；
- * 2. 加载 contract.json（位于 <tests-dir>/.ep-stage/contract.json；不存在时报错引导用户先跑 testcase 子命令）；
- * 3. 调 generateStageSkeletonCrudSpec 生成基线骨架脚本；
- * 4. 头部插入 SKELETON_MARKER_LINE 标记，写盘。
+ * 2. 门禁检查：用例必须全部 confirmed、未覆盖项不得为 candidate/unresolved（REQ-INFER-007）；
+ * 3. 加载 contract.json（位于 <tests-dir>/.ep-stage/contract.json；不存在时报错引导用户先跑 testcase 子命令）；
+ * 4. 调 generateStageSkeletonCrudSpec 生成基线骨架脚本；
+ * 5. 头部插入 SKELETON_MARKER_LINE 标记，写盘。
+ *
+ * 消费边界（REQ-INFER-008）：只读 testcase.json5 + contract.json，不读 inference-trace.json。
  *
  * @param args - 解析后的参数。
  * @returns SpecResult（含 version='v1' 显式标识阶段）。

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

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../../src/cli/spec.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CActD;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAkBlD"}
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../../src/cli/spec.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,CAAC;AAmCF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CActD;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAmBlD"}

package/dist/src/cli/spec.js

@@ -4,6 +4,30 @@ import JSON5 from 'json5';
 import { generateStageSkeletonCrudSpec } from '../generators/stage-skeleton-script.js';
 import { validateTestcase } from '../validation/testcase.js';
 const SKELETON_MARKER_LINE = '// === 胶水模式生成（基于 contract + coveredActions）===';
+/**
+ * spec 组装前的 testcase 就绪门禁（REQ-INFER-007）。
+ *
+ * 独立于 validateTestcase（纯 schema 校验，被 spec 和 run 共享），这里只判定
+ * "testcase 是否已通过人工审阅、可进入 spec 组装阶段"的 readiness 策略，
+ * 仅在 runSpec 内调用，不影响 run 子命令。
+ *
+ * 阻断条件：
+ * - 任一 cases[].reviewStatus !== 'confirmed'（needs_review / blocked 均阻断）；
+ * - 任一 uncoveredCandidates[].status ∈ {'candidate','unresolved'}。
+ *
+ * @param testcase - 已通过 validateTestcase 的 TestcaseV2。
+ * @throws 存在未确认用例或未处理未覆盖项时抛中文错误。
+ */
+function assertTestcaseReadyForSpec(testcase) {
+    const unconfirmed = testcase.cases.find((c) => c.reviewStatus !== 'confirmed');
+    if (unconfirmed) {
+        throw new Error(`testcase.json5 存在未确认用例（needs_review/blocked），请逐条审阅置为 confirmed 后再生成 spec（caseId=${unconfirmed.caseId}，reviewStatus=${unconfirmed.reviewStatus}）`);
+    }
+    const unresolvedCandidate = testcase.uncoveredCandidates.find((item) => item.status === 'candidate' || item.status === 'unresolved');
+    if (unresolvedCandidate) {
+        throw new Error(`testcase.json5 存在 candidate/unresolved 未覆盖项，请处理后再生成 spec（actionId=${unresolvedCandidate.actionId}，status=${unresolvedCandidate.status}）`);
+    }
+}
 /**
  * 解析 spec 子命令参数。
  *
@@ -48,9 +72,12 @@ function locateContract(testcasePath) {
  *
  * 实现：
  * 1. 校验 testcase.json5 通过 validateTestcase（v2 schema）；
- * 2. 加载 contract.json（位于 <tests-dir>/.ep-stage/contract.json；不存在时报错引导用户先跑 testcase 子命令）；
- * 3. 调 generateStageSkeletonCrudSpec 生成基线骨架脚本；
- * 4. 头部插入 SKELETON_MARKER_LINE 标记，写盘。
+ * 2. 门禁检查：用例必须全部 confirmed、未覆盖项不得为 candidate/unresolved（REQ-INFER-007）；
+ * 3. 加载 contract.json（位于 <tests-dir>/.ep-stage/contract.json；不存在时报错引导用户先跑 testcase 子命令）；
+ * 4. 调 generateStageSkeletonCrudSpec 生成基线骨架脚本；
+ * 5. 头部插入 SKELETON_MARKER_LINE 标记，写盘。
+ *
+ * 消费边界（REQ-INFER-008）：只读 testcase.json5 + contract.json，不读 inference-trace.json。
  *
  * @param args - 解析后的参数。
  * @returns SpecResult（含 version='v1' 显式标识阶段）。
@@ -58,6 +85,7 @@ function locateContract(testcasePath) {
 export function runSpec(args) {
     const testcaseRaw = JSON5.parse(readFileSync(args.testcase, 'utf8'));
     const testcase = validateTestcase(testcaseRaw);
+    assertTestcaseReadyForSpec(testcase);
     const contractPath = locateContract(args.testcase);
     if (!contractPath) {
         throw new Error(`未找到 ${path.dirname(args.testcase)}/.ep-stage/contract.json。请先运行 \`ep-stage-skill testcase --code-list <p> --tests-dir <p>\` 生成 contract.json。`);