@epoint-testtech/ep-stage-skill 0.0.3-alpha.1

package/dist/src/testcase/testcase-generator.d.ts

@@ -0,0 +1,43 @@
+import type { CoverageDiffTrace, GlueTestcaseDocument, PageScenario } from '../contracts/observable-chain.js';
+import type { CrudBusinessModuleContract } from '../contracts/crud-business-module.js';
+/**
+ * generateGlueTestcases 的入参。
+ *
+ * @property contract - CRUD 业务模块契约；生成器运行时必需。
+ * @property menu - 菜单路由；生成器运行时必需。
+ * @property scenarios - 推理出的全部场景。
+ * @property confirmedScenarios - 人工已确认的场景（决定用例 reviewStatus）。
+ * @property coverageDiff - coverage diff trace。
+ * @property menuReviewHint - 可选菜单候选提示，供 testcase markdown 与 gate 一并审阅。
+ */
+export type GenerateGlueTestcasesInput = {
+    contract: CrudBusinessModuleContract;
+    menu: string;
+    scenarios: PageScenario[];
+    confirmedScenarios?: PageScenario[];
+    coverageDiff: CoverageDiffTrace;
+    menuReviewHint?: string;
+};
+/**
+ * generateGlueTestcases 的产物。
+ *
+ * @property json - 结构化用例文档。
+ * @property markdown - 人类可读 markdown。
+ */
+export type GenerateGlueTestcasesOutput = {
+    json: GlueTestcaseDocument;
+    markdown: string;
+};
+/**
+ * 从同一份 CRUD 契约、已确认场景和 coverage diff 生成胶水测试用例。
+ *
+ * - 选择已确认场景或第一个候选场景。
+ * - 通过 testcase skeleton + contract slots 渲染人工审阅 Markdown。
+ * - 用例证据记录 skeleton、contract、confirmed scenario、slotSources 和 unresolved。
+ * - 未解析槽位只进入 unresolved，不静默补成业务值。
+ *
+ * @param input - 用例生成入参。
+ * @returns 用例 JSON + Markdown。
+ */
+export declare function generateGlueTestcases(input: GenerateGlueTestcasesInput): GenerateGlueTestcasesOutput;
+//# sourceMappingURL=testcase-generator.d.ts.map

package/dist/src/testcase/testcase-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testcase-generator.d.ts","sourceRoot":"","sources":["../../../src/testcase/testcase-generator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,EAEb,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAOvF;;;;;;;;;GASG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,kBAAkB,CAAC,EAAE,YAAY,EAAE,CAAC;IACpC,YAAY,EAAE,iBAAiB,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,2BAA2B,CA2GpG"}

package/dist/src/testcase/testcase-generator.js

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs';
+import { mapContractToCrudTestcaseSlots, renderGlueTestcaseSkeleton, selectTestcaseSkeletonByScenario, } from './testcase-skeleton.js';
+/**
+ * 从同一份 CRUD 契约、已确认场景和 coverage diff 生成胶水测试用例。
+ *
+ * - 选择已确认场景或第一个候选场景。
+ * - 通过 testcase skeleton + contract slots 渲染人工审阅 Markdown。
+ * - 用例证据记录 skeleton、contract、confirmed scenario、slotSources 和 unresolved。
+ * - 未解析槽位只进入 unresolved，不静默补成业务值。
+ *
+ * @param input - 用例生成入参。
+ * @returns 用例 JSON + Markdown。
+ */
+export function generateGlueTestcases(input) {
+    if (!input.contract || !input.menu) {
+        throw new Error('生成胶水测试用例必须提供 contract 和 menu，不能再由 moduleId/moduleName 自由拼装');
+    }
+    const confirmedScenarios = input.confirmedScenarios ?? [];
+    const scenario = confirmedScenarios.find((item) => input.scenarios.includes(item)) ?? input.scenarios[0];
+    if (!scenario) {
+        throw new Error('生成胶水测试用例前必须至少提供一个场景');
+    }
+    const selection = selectTestcaseSkeletonByScenario(scenario);
+    const slots = mapContractToCrudTestcaseSlots({
+        contract: input.contract,
+        scenario,
+        menu: input.menu,
+    });
+    const unresolved = collectReviewUnresolved(input.coverageDiff, slots.unresolved, scenario, confirmedScenarios, input.menuReviewHint);
+    const reviewStatus = confirmedScenarios.includes(scenario) && unresolved.length === 0
+        ? 'confirmed'
+        : 'needs_review';
+    const evidence = [
+        `skeleton=${selection.skeletonId}`,
+        `contract=${input.contract.contractVersion}`,
+        `listPage=${slots.listPageId}`,
+        `confirmedScenario=${confirmedScenarios.includes(scenario) ? scenario : 'none'}`,
+        `slotSources=${slots.slotSources.join(',') || 'none'}`,
+        `unresolved=${unresolved.join(',') || 'none'}`,
+    ];
+    const cases = [
+        {
+            caseId: `${input.contract.module.id}.create`,
+            title: slots.createCaseTitle,
+            scenario,
+            reviewStatus,
+            evidence,
+            steps: [slots.createSteps],
+            assertions: [slots.createAssertions],
+            unresolved,
+        },
+        {
+            caseId: `${input.contract.module.id}.read`,
+            title: slots.searchCaseTitle,
+            scenario,
+            reviewStatus,
+            evidence,
+            steps: [slots.searchSteps],
+            assertions: [slots.searchAssertions],
+            unresolved,
+        },
+        {
+            caseId: `${input.contract.module.id}.update`,
+            title: slots.updateCaseTitle,
+            scenario,
+            reviewStatus,
+            evidence,
+            steps: [slots.updateSteps],
+            assertions: [slots.updateAssertions],
+            unresolved,
+        },
+        {
+            caseId: `${input.contract.module.id}.delete`,
+            title: slots.deleteCaseTitle,
+            scenario,
+            reviewStatus,
+            evidence,
+            steps: [slots.deleteSteps],
+            assertions: [slots.deleteAssertions],
+            unresolved,
+        },
+    ];
+    const json = {
+        moduleId: input.contract.module.id,
+        moduleName: input.contract.module.label,
+        cases,
+        reasoningSummary: {
+            conclusion: `基于 ${selection.skeletonId} 和同一份 ${input.contract.contractVersion} 契约生成 ${cases.length} 条胶水测试用例。`,
+            evidenceChain: [
+                ...input.coverageDiff.reasoningSummary.evidenceChain,
+                createHumanEvidence(`skeleton=${selection.skeletonId}`),
+                createHumanEvidence(`confirmedScenario=${confirmedScenarios.includes(scenario) ? scenario : 'none'}`),
+                createHumanEvidence(`slotSources=${slots.slotSources.join(',') || 'none'}`),
+                createHumanEvidence(`unresolved=${unresolved.join(',') || 'none'}`),
+            ],
+            alternatives: input.coverageDiff.reasoningSummary.alternatives,
+            confidence: input.coverageDiff.reasoningSummary.confidence,
+            risks: unresolved,
+            needsHumanReview: cases.some((item) => item.reviewStatus !== 'confirmed'),
+        },
+    };
+    return {
+        json,
+        markdown: renderGlueTestcaseSkeleton(readTestcaseTemplate(selection.templateName), {
+            ...slots,
+            reviewStatus,
+            unresolved,
+            unresolvedSummary: unresolved.join('；') || '无',
+        }),
+    };
+}
+/**
+ * 合并契约槽位、coverage diff 和嵌套 CRUD 候选中的未确认项。
+ *
+ * @param coverageDiff - coverage diff trace。
+ * @param slotUnresolved - 契约槽位未解析项。
+ * @param menuReviewHint - 菜单候选提示。
+ * @returns testcase gate 需要展示的未确认项。
+ */
+function collectReviewUnresolved(coverageDiff, slotUnresolved, scenario, confirmedScenarios, menuReviewHint) {
+    const ignoreNestedCrudCandidates = scenario === 'crud.single-page' && confirmedScenarios.includes('crud.single-page');
+    return [
+        ...slotUnresolved,
+        ...(menuReviewHint ? [menuReviewHint] : []),
+        ...coverageDiff.unresolved.map((item) => `coverageDiff.unresolved: ${item.reason}`),
+        ...(ignoreNestedCrudCandidates
+            ? []
+            : coverageDiff.nestedCrudCandidates.map((item) => `coverageDiff.nestedCrudCandidates[${item.pageId}]: ${item.unresolvedReason}`)),
+    ];
+}
+/**
+ * 读取用例骨架模板文件。
+ *
+ * @param templateName - 模板文件名。
+ * @returns Markdown 模板内容。
+ */
+function readTestcaseTemplate(templateName) {
+    return readFileSync(new URL(`./templates/${templateName}`, import.meta.url), 'utf8');
+}
+/**
+ * 构造 testcase-generation 阶段的人审证据。
+ *
+ * @param text - 证据摘要。
+ * @returns 可观测推理证据。
+ */
+function createHumanEvidence(text) {
+    return {
+        source: 'human',
+        path: 'testcase-generation.json',
+        text,
+    };
+}

package/dist/src/testcase/testcase-skeleton.d.ts

@@ -0,0 +1,91 @@
+import type { CrudBusinessModuleContract } from '../contracts/crud-business-module.js';
+import type { PageScenario } from '../contracts/observable-chain.js';
+/**
+ * 用例骨架选择结果。
+ *
+ * @property skeletonId - 用例骨架版本标识。
+ * @property templateName - 模板文件名。
+ * @property scenario - 适配的页面场景。
+ */
+export type TestcaseSkeletonSelection = {
+    skeletonId: 'crud.skeleton-testcase/v1';
+    templateName: 'crud.skeleton-testcase.md';
+    scenario: 'crud.single-page' | 'crud.nested';
+};
+/**
+ * CRUD 用例骨架渲染槽位。
+ *
+ * @property unresolved - 无法从契约确定的槽位，必须交给人工补齐。
+ * @property slotSources - 槽位来源说明，用于 testcase-generation.json 审阅。
+ */
+export type CrudTestcaseSlots = {
+    skeletonId: string;
+    contractVersion: CrudBusinessModuleContract['contractVersion'];
+    scenario: PageScenario;
+    reviewStatus: 'confirmed' | 'needs_review';
+    moduleId: string;
+    moduleName: string;
+    menu: string;
+    listPageId: string;
+    listPageTitle: string;
+    createActionLabel: string;
+    searchFieldLabel: string;
+    updateActionLabel: string;
+    deleteActionLabel: string;
+    createCaseTitle: string;
+    searchCaseTitle: string;
+    updateCaseTitle: string;
+    deleteCaseTitle: string;
+    createSteps: string;
+    searchSteps: string;
+    updateSteps: string;
+    deleteSteps: string;
+    createAssertions: string;
+    searchAssertions: string;
+    updateAssertions: string;
+    deleteAssertions: string;
+    envBaseUrl: string;
+    envUsername: string;
+    envPassword: string;
+    slotSources: string[];
+    slotSourcesSummary: string;
+    unresolved: string[];
+    unresolvedSummary: string;
+};
+/**
+ * 从 CRUD 契约映射用例骨架槽位的入参。
+ *
+ * @property contract - CRUD 业务模块契约。
+ * @property scenario - 已确认或候选场景。
+ * @property menu - 菜单路由文本。
+ */
+export type MapContractToCrudTestcaseSlotsInput = {
+    contract: CrudBusinessModuleContract;
+    scenario: PageScenario;
+    menu: string;
+};
+/**
+ * 按场景选择可审阅用例骨架。
+ *
+ * @param scenario - 页面场景。
+ * @returns 用例骨架选择结果。
+ * @throws 当场景暂不支持生成用例骨架时抛出中文错误。
+ */
+export declare function selectTestcaseSkeletonByScenario(scenario: PageScenario): TestcaseSkeletonSelection;
+/**
+ * 从同一份 CRUD 契约映射 Markdown 用例骨架所需槽位。
+ *
+ * @param input - 契约、场景与菜单路由。
+ * @returns 可渲染槽位；缺失业务来源进入 unresolved。
+ */
+export declare function mapContractToCrudTestcaseSlots(input: MapContractToCrudTestcaseSlotsInput): CrudTestcaseSlots;
+/**
+ * 使用 `{{slotName}}` 占位符渲染用例骨架模板。
+ *
+ * @param template - Markdown 模板内容。
+ * @param slots - 用例骨架槽位。
+ * @returns 完整 Markdown。
+ * @throws 当模板引用未知槽位时抛出中文错误。
+ */
+export declare function renderGlueTestcaseSkeleton(template: string, slots: CrudTestcaseSlots): string;
+//# sourceMappingURL=testcase-skeleton.d.ts.map

package/dist/src/testcase/testcase-skeleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testcase-skeleton.d.ts","sourceRoot":"","sources":["../../../src/testcase/testcase-skeleton.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAOrE;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,UAAU,EAAE,2BAA2B,CAAC;IACxC,YAAY,EAAE,2BAA2B,CAAC;IAC1C,QAAQ,EAAE,kBAAkB,GAAG,aAAa,CAAC;CAC9C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,0BAA0B,CAAC,iBAAiB,CAAC,CAAC;IAC/D,QAAQ,EAAE,YAAY,CAAC;IACvB,YAAY,EAAE,WAAW,GAAG,cAAc,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,mCAAmC,GAAG;IAChD,QAAQ,EAAE,0BAA0B,CAAC;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,YAAY,GAAG,yBAAyB,CAUlG;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,mCAAmC,GAAG,iBAAiB,CA4E5G;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAS7F"}

package/dist/src/testcase/testcase-skeleton.js

@@ -0,0 +1,121 @@
+const CRUD_TESTCASE_SKELETON_ID = 'crud.skeleton-testcase/v1';
+const CONTRACT_VERSION = 'crud-business-module/v1';
+const HUMAN_REQUIRED = '待人工确认';
+const UNRESOLVED_SLOT_VALUES = new Set(['未确认菜单路径', HUMAN_REQUIRED]);
+/**
+ * 按场景选择可审阅用例骨架。
+ *
+ * @param scenario - 页面场景。
+ * @returns 用例骨架选择结果。
+ * @throws 当场景暂不支持生成用例骨架时抛出中文错误。
+ */
+export function selectTestcaseSkeletonByScenario(scenario) {
+    if (scenario !== 'crud.single-page' && scenario !== 'crud.nested') {
+        throw new Error(`暂不支持为场景 ${scenario} 生成胶水测试用例骨架`);
+    }
+    return {
+        skeletonId: CRUD_TESTCASE_SKELETON_ID,
+        templateName: 'crud.skeleton-testcase.md',
+        scenario,
+    };
+}
+/**
+ * 从同一份 CRUD 契约映射 Markdown 用例骨架所需槽位。
+ *
+ * @param input - 契约、场景与菜单路由。
+ * @returns 可渲染槽位；缺失业务来源进入 unresolved。
+ */
+export function mapContractToCrudTestcaseSlots(input) {
+    const selection = selectTestcaseSkeletonByScenario(input.scenario);
+    const unresolved = [...input.contract.unresolvedSlots.map((slot) => `${slot.slotId}: ${slot.reason}`)];
+    const slotSources = [];
+    const contract = input.contract;
+    const moduleId = requireSlot(contract.module.id, 'moduleId', 'contract.module.id', unresolved, slotSources);
+    const moduleName = requireSlot(contract.module.label, 'moduleName', 'contract.module.label', unresolved, slotSources);
+    const listPageId = requireSlot(contract.pages.list.pageId, 'listPageId', 'contract.pages.list.pageId', unresolved, slotSources);
+    const listPageTitle = requireSlot(contract.pages.list.title, 'listPageTitle', 'contract.pages.list.title', unresolved, slotSources);
+    const menu = requireSlot(input.menu, 'menu', 'input.menu', unresolved, slotSources);
+    const createActionLabel = requireSlot(contract.flows.create?.entryButton.label, 'createActionLabel', 'contract.flows.create.entryButton.label', unresolved, slotSources);
+    const searchFieldLabel = requireSlot(contract.flows.search?.searchField.label ?? firstSearchConditionLabel(contract), 'searchFieldLabel', 'contract.flows.search.searchField.label', unresolved, slotSources);
+    const updateActionLabel = requireSlot(contract.flows.update?.entryAction.label, 'updateActionLabel', 'contract.flows.update.entryAction.label', unresolved, slotSources);
+    const deleteActionLabel = requireSlot(contract.flows.delete?.entryButton.label, 'deleteActionLabel', 'contract.flows.delete.entryButton.label', unresolved, slotSources);
+    const slots = {
+        skeletonId: selection.skeletonId,
+        contractVersion: CONTRACT_VERSION,
+        scenario: input.scenario,
+        reviewStatus: unresolved.length === 0 ? 'confirmed' : 'needs_review',
+        moduleId,
+        moduleName,
+        menu,
+        listPageId,
+        listPageTitle,
+        createActionLabel,
+        searchFieldLabel,
+        updateActionLabel,
+        deleteActionLabel,
+        createCaseTitle: `新增${moduleName}`,
+        searchCaseTitle: `查询${moduleName}`,
+        updateCaseTitle: `修改${moduleName}`,
+        deleteCaseTitle: `删除${moduleName}`,
+        createSteps: `进入菜单 ${menu}；确认列表页 ${listPageTitle}；点击 ${createActionLabel}；填写并保存测试数据`,
+        searchSteps: `进入菜单 ${menu}；按查询字段：${searchFieldLabel} 输入测试值；提交查询`,
+        updateSteps: `在列表结果中定位测试记录；点击 ${updateActionLabel}；修改查询字段：${searchFieldLabel}；保存`,
+        deleteSteps: `在列表结果中定位测试记录；点击 ${deleteActionLabel}；按契约策略确认删除结果`,
+        createAssertions: `新增后可在 ${listPageTitle} 按 ${searchFieldLabel} 查询到记录`,
+        searchAssertions: `查询结果包含 ${searchFieldLabel} 对应的测试记录`,
+        updateAssertions: `修改后可按 ${searchFieldLabel} 查询到更新后的记录`,
+        deleteAssertions: '删除结果符合契约中的 delete.expectedOutcome 与断言策略',
+        envBaseUrl: '.env: LOGIN_SYSTEM_URL',
+        envUsername: '.env: LOGIN_USERNAME',
+        envPassword: '.env: LOGIN_PASSWORD',
+        slotSources,
+        slotSourcesSummary: slotSources.join('；') || '无',
+        unresolved,
+        unresolvedSummary: unresolved.join('；') || '无',
+    };
+    return slots;
+}
+/**
+ * 使用 `{{slotName}}` 占位符渲染用例骨架模板。
+ *
+ * @param template - Markdown 模板内容。
+ * @param slots - 用例骨架槽位。
+ * @returns 完整 Markdown。
+ * @throws 当模板引用未知槽位时抛出中文错误。
+ */
+export function renderGlueTestcaseSkeleton(template, slots) {
+    return template.replace(/\{\{(\w+)\}\}/g, (placeholder, slotName) => {
+        if (!(slotName in slots)) {
+            throw new Error(`用例骨架模板引用了未知槽位：${placeholder}`);
+        }
+        const value = slots[slotName];
+        return Array.isArray(value) ? value.join('；') : String(value);
+    });
+}
+/**
+ * 读取第一个搜索条件标签。
+ *
+ * @param contract - CRUD 业务模块契约。
+ * @returns 搜索条件标签；不存在时返回 undefined。
+ */
+function firstSearchConditionLabel(contract) {
+    return contract.searchConditions?.[0]?.label;
+}
+/**
+ * 读取必需槽位，不存在时登记 unresolved。
+ *
+ * @param value - 候选槽位值。
+ * @param slotId - 槽位标识。
+ * @param source - 槽位来源。
+ * @param unresolved - 未解析槽位列表。
+ * @param slotSources - 已解析槽位来源列表。
+ * @returns 已解析值或人工确认占位。
+ */
+function requireSlot(value, slotId, source, unresolved, slotSources) {
+    if (value && value.trim().length > 0 && !UNRESOLVED_SLOT_VALUES.has(value.trim())) {
+        slotSources.push(`${slotId}=${source}`);
+        return value;
+    }
+    unresolved.push(`${slotId}: 缺少 ${source}`);
+    return HUMAN_REQUIRED;
+}

package/dist/src/testcase/testcase-spec-assembly.d.ts

@@ -0,0 +1,11 @@
+import type { CrudBusinessModuleContract } from '../contracts/crud-business-module.js';
+import type { GlueTestcaseDocument } from '../contracts/observable-chain.js';
+/**
+ * 校验已确认的 glue testcase 是否可作为 spec assembly 输入。
+ *
+ * @param document - testcase-generation 阶段产出的结构化用例。
+ * @param contract - 同一次链路产出的 CRUD 契约。
+ * @throws 当用例未确认、模块不一致或缺少 CRUD 工作流颗粒度时抛出中文错误。
+ */
+export declare function validateGlueTestcaseDocumentForSpecAssembly(document: GlueTestcaseDocument, contract: CrudBusinessModuleContract): void;
+//# sourceMappingURL=testcase-spec-assembly.d.ts.map

package/dist/src/testcase/testcase-spec-assembly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testcase-spec-assembly.d.ts","sourceRoot":"","sources":["../../../src/testcase/testcase-spec-assembly.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAI7E;;;;;;GAMG;AACH,wBAAgB,2CAA2C,CACzD,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,0BAA0B,GACnC,IAAI,CAkBN"}

package/dist/src/testcase/testcase-spec-assembly.js

@@ -0,0 +1,24 @@
+const CRUD_WORKFLOW_KINDS = ['create', 'read', 'update', 'delete'];
+/**
+ * 校验已确认的 glue testcase 是否可作为 spec assembly 输入。
+ *
+ * @param document - testcase-generation 阶段产出的结构化用例。
+ * @param contract - 同一次链路产出的 CRUD 契约。
+ * @throws 当用例未确认、模块不一致或缺少 CRUD 工作流颗粒度时抛出中文错误。
+ */
+export function validateGlueTestcaseDocumentForSpecAssembly(document, contract) {
+    if (document.moduleId !== contract.module.id) {
+        throw new Error(`glue testcase moduleId 与 contract 不一致：${document.moduleId} !== ${contract.module.id}`);
+    }
+    const pendingCases = document.cases.filter((item) => item.reviewStatus !== 'confirmed');
+    if (pendingCases.length > 0) {
+        throw new Error(`glue testcase 仍有未确认用例：${pendingCases.map((item) => item.caseId).join(', ')}`);
+    }
+    const caseIds = new Set(document.cases.map((item) => item.caseId));
+    const missingCaseIds = CRUD_WORKFLOW_KINDS
+        .map((kind) => `${contract.module.id}.${kind}`)
+        .filter((caseId) => !caseIds.has(caseId));
+    if (missingCaseIds.length > 0) {
+        throw new Error(`glue testcase 缺少 spec assembly 需要的用例：${missingCaseIds.join(', ')}`);
+    }
+}

package/dist/src/trace/review-summary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 人工审阅摘要渲染器。
+ */
+import type { ReasoningSummary } from '../contracts/observable-chain.js';
+export type ReviewSummaryInput = {
+    title: string;
+    reasoningSummary: ReasoningSummary;
+    nextAction: string;
+};
+/**
+ * 将结构化推理摘要渲染为适合对话输出的中文文本。
+ *
+ * @param input 审阅标题、推理摘要和下一步动作。
+ * @returns 中文人工审阅摘要。
+ */
+export declare function renderReviewSummary(input: ReviewSummaryInput): string;
+//# sourceMappingURL=review-summary.d.ts.map

package/dist/src/trace/review-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-summary.d.ts","sourceRoot":"","sources":["../../../src/trace/review-summary.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CA4BrE"}

package/dist/src/trace/review-summary.js

@@ -0,0 +1,34 @@
+/**
+ * 将结构化推理摘要渲染为适合对话输出的中文文本。
+ *
+ * @param input 审阅标题、推理摘要和下一步动作。
+ * @returns 中文人工审阅摘要。
+ */
+export function renderReviewSummary(input) {
+    const { reasoningSummary } = input;
+    const evidenceLines = reasoningSummary.evidenceChain.length > 0
+        ? reasoningSummary.evidenceChain.map((item) => {
+            const pathText = item.path ? `（${item.path}）` : '';
+            return `- ${item.source}${pathText}：${item.text}`;
+        })
+        : ['- 无'];
+    const riskText = reasoningSummary.risks.length > 0
+        ? reasoningSummary.risks.join('；')
+        : '无';
+    const alternativesText = reasoningSummary.alternatives.length > 0
+        ? reasoningSummary.alternatives.join(' / ')
+        : '无';
+    return [
+        `# ${input.title}`,
+        '',
+        `结论：${reasoningSummary.conclusion}`,
+        `置信度：${reasoningSummary.confidence}`,
+        '证据链：',
+        ...evidenceLines,
+        `候选方案：${alternativesText}`,
+        `待确认项：${riskText}`,
+        `是否需要人工确认：${reasoningSummary.needsHumanReview ? '是' : '否'}`,
+        `下一步：${input.nextAction}`,
+        '',
+    ].join('\n');
+}

package/dist/src/trace/trace-writer.d.ts

@@ -0,0 +1,17 @@
+import type { ObservableStageName, ObservableStagePayload, ObservableStageSummary, TraceWriterOptions } from '../contracts/observable-chain.js';
+export type TraceWriter = {
+    runId: string;
+    traceDir: string;
+    /** 写入单个阶段 JSON，并返回写入路径。 */
+    writeStage(stage: ObservableStageName, payload: ObservableStagePayload): string;
+    /** 写入批次 summary.md，并返回写入路径。 */
+    writeSummary(stages: ObservableStageSummary[]): string;
+};
+/**
+ * 创建 trace writer，并确保运行批次目录存在。
+ *
+ * @param options trace writer 初始化参数。
+ * @returns 可写阶段 JSON 与 summary.md 的 writer。
+ */
+export declare function createTraceWriter(options: TraceWriterOptions): TraceWriter;
+//# sourceMappingURL=trace-writer.d.ts.map

package/dist/src/trace/trace-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-writer.d.ts","sourceRoot":"","sources":["../../../src/trace/trace-writer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,kCAAkC,CAAC;AAE1C,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,UAAU,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAAC;IAChF,+BAA+B;IAC/B,YAAY,CAAC,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,CAAC;CACxD,CAAC;AAwBF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CA6B1E"}

package/dist/src/trace/trace-writer.js

@@ -0,0 +1,81 @@
+/**
+ * 可观测链路 trace writer。
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * 生成默认运行批次标识。
+ *
+ * @returns UTC 时间格式的运行批次标识。
+ */
+function defaultRunId() {
+    return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * 校验 runId 只能是单个安全路径段。
+ *
+ * @param runId 待校验的运行批次标识。
+ * @returns 无返回值。
+ * @throws 当 runId 含路径分隔或非白名单字符时抛错。
+ */
+function assertSafeRunId(runId) {
+    if (!/^[A-Za-z0-9._-]+$/.test(runId) || runId.includes('..') || runId === '.') {
+        throw new Error(`invalid trace runId: ${runId}`);
+    }
+}
+/**
+ * 创建 trace writer，并确保运行批次目录存在。
+ *
+ * @param options trace writer 初始化参数。
+ * @returns 可写阶段 JSON 与 summary.md 的 writer。
+ */
+export function createTraceWriter(options) {
+    const runId = options.runId ?? defaultRunId();
+    assertSafeRunId(runId);
+    const traceDir = path.join(options.projectDir, '.stage', 'trace', runId);
+    mkdirSync(traceDir, { recursive: true });
+    return {
+        runId,
+        traceDir,
+        writeStage(stage, payload) {
+            if (stage !== payload.stage) {
+                throw new Error(`trace stage mismatch: file stage "${stage}" does not match payload stage "${payload.stage}"`);
+            }
+            const filePath = path.join(traceDir, `${stage}.json`);
+            writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+            return filePath;
+        },
+        writeSummary(stages) {
+            const filePath = path.join(traceDir, 'summary.md');
+            writeFileSync(filePath, renderTraceSummary(stages, options, runId), 'utf8');
+            return filePath;
+        },
+    };
+}
+/**
+ * 渲染批次级 summary.md，供人工快速审阅每个阶段状态。
+ *
+ * @param stages 阶段摘要列表。
+ * @param options trace writer 初始化参数。
+ * @param runId 实际使用的运行批次标识。
+ * @returns Markdown 文本。
+ */
+function renderTraceSummary(stages, options, runId) {
+    const header = [
+        '# ep-stage glue trace summary',
+        '',
+        `- 运行批次：${runId}`,
+        options.codeListPath ? `- code_list：${options.codeListPath}` : undefined,
+        '',
+    ].filter((line) => line !== undefined);
+    const stageLines = stages.flatMap((stage) => [
+        `## ${stage.stageLabel}`,
+        '',
+        `- 阶段：${stage.stage}`,
+        `- 状态：${stage.status}`,
+        `- 结论：${stage.conclusion}`,
+        `- 需要人工确认：${stage.needsHumanReview ? '是，需要人工确认' : '否，无需人工确认'}`,
+        '',
+    ]);
+    return `${[...header, ...stageLines].join('\n')}\n`;
+}

package/dist/test/crud-contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=crud-contract.test.d.ts.map

package/dist/test/crud-contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crud-contract.test.d.ts","sourceRoot":"","sources":["../../test/crud-contract.test.ts"],"names":[],"mappings":""}