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

package/dist/src/contracts/gap-inference.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Gap Inference 契约类型。
+ *
+ * 定义 gap-planner 识别骨架未覆盖工作流所需的核心数据结构：
+ * - ActionCandidate：上游物料识别到的可交互动作
+ * - SkeletonCoverage：当前骨架已覆盖的动作集合
+ * - AgentInferredWorkflow：经差集和证据判断后需要 Agent 推理补齐的业务工作流
+ *
+ * @module contracts/gap-inference
+ */
+import type { EvidenceRef, PageRole, SlotResolution, SourceRef } from './crud-business-module.js';
+/**
+ * 可交互动作的类型。
+ */
+export type GapActionType = 'page_button' | 'row_action' | 'dialog_action';
+/**
+ * Gap 工作流的状态生命周期。
+ *
+ * candidate → planned → resolved → generated → passed/failed/needs_review
+ *                    ↘ unresolved
+ */
+export type GapWorkflowStatus = 'candidate' | 'planned' | 'resolved' | 'generated' | 'passed' | 'failed' | 'needs_review' | 'unresolved';
+/**
+ * 从上游物料识别到的可交互动作。是事实，不代表一定生成测试。
+ */
+export type ActionCandidate = {
+    /** 稳定唯一标识，由 moduleId + pageId + actionType + label 生成 */
+    actionId: string;
+    moduleId: string;
+    pageId: string;
+    pageRole: PageRole | 'unknown';
+    actionType: GapActionType;
+    label: string;
+    locator?: string;
+    onclick?: string;
+    evidence: EvidenceRef[];
+    sourceRefs: SourceRef[];
+};
+/**
+ * 当前骨架已覆盖的动作集合。
+ */
+export type SkeletonCoverage = {
+    coverageId: 'crud-plus-export/v1';
+    coveredWorkflows: Array<'crud.create' | 'crud.read' | 'crud.update' | 'crud.delete' | 'export.run'>;
+    coveredActionLabels: {
+        create?: string[];
+        read?: string[];
+        update?: string[];
+        delete?: string[];
+        export?: string[];
+        internal?: string[];
+    };
+};
+/**
+ * 经差集和证据判断后，需要 Agent 推理补齐的业务工作流。
+ */
+export type AgentInferredWorkflow = {
+    workflowId: string;
+    workflowKind: 'custom';
+    executionSource: 'agent_inferred';
+    status: GapWorkflowStatus;
+    /** 为什么测：业务意图 */
+    businessIntent: SlotResolution<string>;
+    /** 要做哪些动作：元素操作序列 */
+    elementActions: SlotResolution<string[]>;
+    /** 怎么判断结果：断言预期 */
+    assertionExpectation: SlotResolution<string>;
+    actionCandidates: ActionCandidate[];
+    triggerReason: string;
+    evidence: EvidenceRef[];
+    reviewReason?: string;
+    resolvedRuntime?: {
+        locator?: string;
+        locatorStrategy?: 'html_static' | 'playwright_snapshot' | 'agent_refined';
+        iframeSrcKeyword?: string;
+        exploration?: GapExplorationResult;
+        pageSnapshotPath?: string;
+        generatedSpecFile?: string;
+        playwrightTestTitle?: string;
+    };
+    healerAttempts?: Array<{
+        attempt: number;
+        failureType: 'element_not_found' | 'timeout' | 'toast_not_found' | 'click_intercepted';
+        change: string;
+        evidence: EvidenceRef[];
+        result: 'retry_passed' | 'retry_failed' | 'needs_review';
+    }>;
+};
+/**
+ * 运行态信号类型。
+ *
+ * 描述 gap 按钮点击后真实页面出现的反馈形态，是探索模式判断断言策略的依据。
+ *
+ * - confirm: 点击后出现确认框（如 MiniUI messagebox 的确认/取消）
+ * - alert: 点击后出现提示框（原生 alert 或 mini.alert，常承载 data.msg）
+ * - toast: 点击后出现轻提示
+ * - dialog: 点击后打开业务弹窗页面
+ * - download: 点击后触发文件下载
+ * - page_change: 点击后页面 URL 发生跳转
+ * - none: 点击后未观测到任何反馈
+ * - unknown: 出现了反馈但无法归类
+ */
+export type GapSignalType = 'confirm' | 'alert' | 'toast' | 'dialog' | 'download' | 'page_change' | 'none' | 'unknown';
+/**
+ * Gap 运行态探索结果。
+ *
+ * 探索模式（策略 A）在真实页面对单个 gap 按钮做运行时观测后产出的结构化事实，
+ * 用于回给人工确认，再决定是否落袋为正式 Custom test。
+ *
+ * 与 resolve（引导模式补 locator 后直接 append）不同，探索结果只记录“真实发生了什么”，
+ * 不直接生成测试断言。`suggested*` 字段是探索器对意图/断言的低置信建议，必须经人工确认。
+ *
+ * @property workflowId 关联的 gap workflow 标识
+ * @property buttonLabel 探索的按钮标签
+ * @property locator 真实页面定位到该按钮所用的 locator
+ * @property locatorStrategy locator 来源策略
+ * @property buttonVisible 按钮是否在真实页面可见
+ * @property buttonClickable 按钮是否可点击
+ * @property confirmDialogPresent 点击后是否出现确认框
+ * @property confirmText 确认框文案（confirmDialogPresent 为 true 时）
+ * @property confirmExecuted 探索是否进一步点击了确认框的确认按钮（默认 false，避免触发真实副作用）
+ * @property signalType 观测到的运行态信号类型
+ * @property observedMessage 观测到的提示文案（alert/toast/dialog 文本）
+ * @property pageChanged 点击后页面 URL 是否变化
+ * @property downloadTriggered 点击后是否触发下载
+ * @property networkResponses 点击动作窗口内观测到的关键网络响应摘要
+ * @property suggestedIntent 探索器建议的业务意图（低置信，需人工确认）
+ * @property suggestedAssertion 探索器建议的断言文案（低置信，需人工确认）
+ * @property confidence 探索结论的置信度
+ * @property exploredAt 探索时间戳
+ * @property notes 补充观测说明（如未识别的弹层文本快照）
+ */
+export type GapExplorationResult = {
+    workflowId: string;
+    buttonLabel: string;
+    locator: string;
+    locatorStrategy: 'html_static' | 'playwright_snapshot' | 'agent_refined';
+    buttonVisible: boolean;
+    buttonClickable: boolean;
+    confirmDialogPresent: boolean;
+    confirmText?: string;
+    confirmExecuted: boolean;
+    signalType: GapSignalType;
+    observedMessage?: string;
+    pageChanged: boolean;
+    downloadTriggered: boolean;
+    networkResponses?: string[];
+    suggestedIntent?: string;
+    suggestedAssertion?: string;
+    confidence: 'low' | 'medium' | 'high';
+    exploredAt: string;
+    notes?: string;
+};
+/**
+ * 引导模式推理草案。
+ *
+ * 引导模式（策略 B）下，人工预先给定业务意图与断言预期，runtime 据此在真实页面推理验证，
+ * 产出「待人工确认后落袋」的草案——不直接 append。这是引导模式人工确认 gate 的载体：
+ * runtime 推理产出草案 → 控制台打印 → 人工对话内确认 → 再落袋。
+ *
+ * @property workflowId 关联的 gap workflow 标识
+ * @property buttonLabel 按钮标签
+ * @property guidedIntent 人工给定的业务意图（引导输入）
+ * @property guidedAssertion 人工给定的断言预期（引导输入）
+ * @property exploration 真实页面运行态观测结果（复用探索器）
+ * @property intentSatisfied 真机观测是否满足人工预期
+ * @property suggestedGapFinding 当真机与人工预期不符时，建议的功能缺口结论
+ * @property confidence 推理结论置信度
+ */
+export type GapInferDraft = {
+    workflowId: string;
+    buttonLabel: string;
+    guidedIntent: string;
+    guidedAssertion: string;
+    exploration: GapExplorationResult;
+    intentSatisfied: boolean;
+    suggestedGapFinding?: {
+        kind: 'feature_incomplete' | 'behavior_mismatch';
+        summary: string;
+        observed?: string;
+    };
+    confidence: 'low' | 'medium' | 'high';
+};
+/**
+ * Gap 清单条目。
+ *
+ * 物料钻探后、进入 runtime 推理前，用于在控制台列出每个 gap 供人工筛选——
+ * 让人工剔除无需推理的 gap，减少无效推理、命中有效 gap（gap 人工筛选 gate）。
+ *
+ * @property workflowId gap workflow 标识
+ * @property label 按钮标签
+ * @property status gap 当前状态
+ * @property actionType 动作类型
+ * @property pageRole 所在页面角色
+ * @property hasIntent 是否已具备业务意图
+ * @property hasAssertion 是否已具备断言预期
+ * @property suggestedMode 建议进入的 runtime 模式：explore=探索 / infer=引导 / skip=已处理无需推理
+ * @property evidenceSummary 证据来源摘要（去重的 evidence kind 列表）
+ * @property triggerReason 被判定为 gap 的原因
+ */
+export type GapListItem = {
+    workflowId: string;
+    label: string;
+    status: GapWorkflowStatus;
+    actionType: GapActionType;
+    pageRole: PageRole | 'unknown';
+    hasIntent: boolean;
+    hasAssertion: boolean;
+    suggestedMode: 'explore' | 'infer' | 'skip';
+    evidenceSummary: string;
+    triggerReason: string;
+};
+//# sourceMappingURL=gap-inference.d.ts.map

package/dist/src/contracts/gap-inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gap-inference.d.ts","sourceRoot":"","sources":["../../../src/contracts/gap-inference.ts"],"names":[],"mappings":"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"}

package/dist/src/contracts/gap-inference.js

@@ -0,0 +1,11 @@
+/**
+ * Gap Inference 契约类型。
+ *
+ * 定义 gap-planner 识别骨架未覆盖工作流所需的核心数据结构：
+ * - ActionCandidate：上游物料识别到的可交互动作
+ * - SkeletonCoverage：当前骨架已覆盖的动作集合
+ * - AgentInferredWorkflow：经差集和证据判断后需要 Agent 推理补齐的业务工作流
+ *
+ * @module contracts/gap-inference
+ */
+export {};

package/dist/src/contracts/observable-chain.d.ts

@@ -0,0 +1,250 @@
+/**
+ * 可观测胶水链路契约类型。
+ *
+ * 该契约只描述每个推理阶段的输入、输出、证据和人工确认 gate，
+ * 供 trace writer 写出可审阅产物；当前阶段不接入 CLI 或 gap planner。
+ */
+import type { Confidence, EvidenceRef } from './crud-business-module.js';
+/**
+ * 可观测链路阶段名称。
+ */
+export type ObservableStageName = 'context-resolution' | 'material-inventory' | 'evidence-extraction' | 'capability-candidates' | 'scenario-inference' | 'skeleton-capability-model' | 'coverage-diff' | 'testcase-generation' | 'glue-spec-assembly' | 'runtime-gap-inference' | 'playwright-execution' | 'glue-report' | 'generalization-evaluation';
+/**
+ * trace 中引用的输入或输出产物。
+ *
+ * @property kind - 产物类别。
+ * @property path - 产物路径。
+ * @property description - 可选的人类可读说明。
+ */
+export type ObservableArtifactRef = {
+    kind: string;
+    path: string;
+    description?: string;
+};
+/**
+ * 推理证据链条目。
+ *
+ * @property source - 证据来源。
+ * @property path - 证据文件或运行态快照路径。
+ * @property text - 可审阅的证据摘要。
+ */
+export type ReasoningEvidence = {
+    source: 'spec' | 'code_list' | 'html' | 'java_action' | 'module_hints' | 'runtime' | 'human';
+    path: string;
+    text: string;
+};
+/**
+ * 可审阅推理摘要。
+ *
+ * @property conclusion - 当前阶段结论。
+ * @property evidenceChain - 人类可读证据链。
+ * @property alternatives - 候选解释或候选方案。
+ * @property confidence - 复用 CRUD 契约置信度。
+ * @property risks - 需要人工确认或后续验证的风险。
+ * @property needsHumanReview - 是否必须进入人工审阅。
+ */
+export type ReasoningSummary = {
+    conclusion: string;
+    evidenceChain: ReasoningEvidence[];
+    alternatives: string[];
+    confidence: Confidence;
+    risks: string[];
+    needsHumanReview: boolean;
+};
+/**
+ * 阶段 gate 结果。
+ *
+ * @property status - 当前阶段状态。
+ * @property reason - 状态原因。
+ */
+export type ObservableGate = {
+    status: 'not_required';
+    reason: string;
+} | {
+    status: 'needs_review';
+    reason: string;
+} | {
+    status: 'confirmed';
+    confirmedBy: 'human' | 'policy';
+    reason: string;
+} | {
+    status: 'corrected';
+    reason: string;
+    correction: string;
+};
+/**
+ * 单个可观测阶段的 trace payload。
+ *
+ * @property stage - 阶段名称。
+ * @property stageLabel - 中文阶段标题。
+ * @property inputs - 阶段输入产物。
+ * @property outputs - 阶段输出产物。
+ * @property deterministicEvidence - 复用既有 EvidenceRef 的确定性结构证据。
+ * @property reasoningSummary - 可审阅推理摘要。
+ * @property candidateCount - 候选数量。
+ * @property unresolvedCount - 未解决项数量。
+ * @property gate - 阶段 gate 结果。
+ */
+export type ObservableStagePayload = {
+    stage: ObservableStageName;
+    stageLabel: string;
+    inputs: ObservableArtifactRef[];
+    outputs: ObservableArtifactRef[];
+    deterministicEvidence?: EvidenceRef[];
+    reasoningSummary?: ReasoningSummary;
+    candidateCount?: number;
+    unresolvedCount?: number;
+    gate: ObservableGate;
+};
+/**
+ * summary.md 中展示的阶段摘要。
+ */
+export type ObservableStageSummary = {
+    stage: ObservableStageName;
+    stageLabel: string;
+    status: ObservableGate['status'];
+    conclusion: string;
+    needsHumanReview: boolean;
+};
+/**
+ * trace writer 初始化参数。
+ *
+ * @property projectDir - 用户项目目录。
+ * @property runId - 当前运行批次标识。
+ * @property codeListPath - 可选 code_list.md 路径，用于后续审阅定位。
+ */
+export type TraceWriterOptions = {
+    projectDir: string;
+    runId?: string;
+    codeListPath: string;
+};
+/**
+ * 页面场景类型。
+ */
+export type PageScenario = 'crud.single-page' | 'crud.nested' | 'export' | 'report.statistical' | 'custom.business-action' | 'unknown';
+/**
+ * 单个场景候选。
+ *
+ * @property scenario - 场景类型。
+ * @property confidence - 复用 CRUD 契约置信度。
+ * @property evidenceRefs - 支撑该候选的证据标签。
+ * @property matchedSkeletonCapabilities - 命中的骨架能力。
+ * @property unresolved - 需人工确认的未决项。
+ */
+export type ScenarioCandidate = {
+    scenario: PageScenario;
+    confidence: Confidence;
+    evidenceRefs: string[];
+    matchedSkeletonCapabilities: string[];
+    unresolved: string[];
+};
+/**
+ * 场景推理阶段 trace。
+ *
+ * @property moduleId - 模块 id。
+ * @property candidates - 场景候选列表（按置信排序）。
+ * @property gate - 阶段 gate。
+ * @property reasoningSummary - 可审阅推理摘要。
+ * @property conversationReview - 人工确认/纠偏记录。
+ */
+export type ScenarioInferenceTrace = {
+    moduleId: string;
+    candidates: ScenarioCandidate[];
+    gate: ObservableGate;
+    reasoningSummary: ReasoningSummary;
+    conversationReview?: {
+        status: 'confirmed' | 'corrected' | 'skipped';
+        humanCorrection?: string;
+        rerunRequired: boolean;
+    };
+};
+/**
+ * coverage diff 中单个动作的分类结果。
+ *
+ * @property status - 覆盖状态（covered/partially-covered/gap-candidate/unresolved）。
+ * @property reason - 分类原因。
+ */
+export type CoverageDiffAction = {
+    actionId: string;
+    label: string;
+    pageId: string;
+    status: 'covered' | 'partially-covered' | 'gap-candidate' | 'unresolved';
+    reason: string;
+};
+/**
+ * 嵌套 CRUD 候选的 trace 条目。
+ */
+export type NestedCrudCandidateTrace = {
+    pageId: string;
+    evidence: string[];
+    supportedActions: string[];
+    unresolvedReason: string;
+};
+/**
+ * coverage diff 阶段 trace：组合骨架覆盖、gap 候选、嵌套 CRUD 候选与基线 workflow 对比。
+ */
+export type CoverageDiffTrace = {
+    moduleId: string;
+    skeletonCoverageId: string;
+    baseline: {
+        plannedWorkflows: string[];
+        candidateWorkflows: string[];
+        unresolvedWorkflows: string[];
+    };
+    covered: CoverageDiffAction[];
+    partiallyCovered: CoverageDiffAction[];
+    gapCandidates: CoverageDiffAction[];
+    unresolved: CoverageDiffAction[];
+    nestedCrudCandidates: NestedCrudCandidateTrace[];
+    comparison: {
+        both: string[];
+        onlyBaseline: string[];
+        onlyGeneralized: string[];
+    };
+    reasoningSummary: ReasoningSummary;
+};
+/**
+ * 单条胶水测试用例。
+ *
+ * @property reviewStatus - 审阅状态（confirmed/needs_review/blocked）。
+ * @property unresolved - 未确认项；未确认项不得直接进入 spec assembly。
+ */
+export type GlueTestcase = {
+    caseId: string;
+    title: string;
+    scenario: PageScenario;
+    reviewStatus: 'confirmed' | 'needs_review' | 'blocked';
+    evidence: string[];
+    steps: string[];
+    assertions: string[];
+    unresolved: string[];
+};
+/**
+ * 胶水测试用例文档。
+ *
+ * @property moduleId - 模块 id。
+ * @property moduleName - 模块中文名。
+ * @property cases - 用例列表。
+ * @property reasoningSummary - 可审阅推理摘要。
+ */
+export type GlueTestcaseDocument = {
+    moduleId: string;
+    moduleName: string;
+    cases: GlueTestcase[];
+    reasoningSummary: ReasoningSummary;
+};
+/**
+ * 运行时页面结构信号：静态结构在运行时是否可见。
+ *
+ * @property staticPresent - 静态抽取时是否存在。
+ * @property runtimeVisible - 运行时是否可见。
+ * @property runtimeMismatch - 静态存在但运行时不可见（需人工确认）。
+ */
+export type RuntimePageStructureSignal = {
+    selector: string;
+    staticPresent: boolean;
+    runtimeVisible: boolean;
+    runtimeMismatch: boolean;
+    evidenceText: string;
+};
+//# sourceMappingURL=observable-chain.d.ts.map

package/dist/src/contracts/observable-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observable-chain.d.ts","sourceRoot":"","sources":["../../../src/contracts/observable-chain.ts"],"names":[],"mappings":"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"}

package/dist/src/contracts/observable-chain.js

@@ -0,0 +1 @@
+export {};

package/dist/src/extractors/code-list.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 从 `code_list.md` 钻探出的单条上游物料引用。
+ *
+ * @property kind - 物料类别（html / java_action / spec / module_hints / other）。
+ * @property rawPath - markdown 中以反引号包裹的原始相对路径。
+ * @property path - 解析后的绝对路径（按 knowledge-root / code_list 所在目录 / `_docs/` 父目录优先级）。
+ * @property exists - 解析后的路径是否真实存在，供下游 material-inventory gate 判定。
+ */
+export type ExtractedMaterialRef = {
+    kind: 'spec' | 'html' | 'java_action' | 'module_hints' | 'other';
+    rawPath: string;
+    path: string;
+    exists: boolean;
+};
+export type ExtractedCodeListSummary = {
+    path: string;
+    knowledgeRoot?: string;
+    knowledgeRootSource: 'input' | 'code_list' | 'inferred' | 'none';
+    menu?: string;
+    moduleLabel: string;
+    pages: string[];
+    methods: string[];
+    actionMethods: Record<string, string[]>;
+    serviceMethods: string[];
+    daoMethods: string[];
+    entityFields: string[];
+    materialRefs: ExtractedMaterialRef[];
+};
+export type ExtractCodeListSummaryOptions = {
+    knowledgeRoot?: string;
+};
+/**
+ * 解析 code_list.md 并提取上游物料摘要。
+ *
+ * @param filePath - code_list.md 文件路径。
+ * @param options - 可选的 knowledgeRoot，用于 code_list 不在知识库根目录下时解析物料路径。
+ * @returns code_list 摘要。
+ */
+export declare function extractCodeListSummary(filePath: string, options?: ExtractCodeListSummaryOptions): ExtractedCodeListSummary;
+//# sourceMappingURL=code-list.d.ts.map

package/dist/src/extractors/code-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-list.d.ts","sourceRoot":"","sources":["../../../src/extractors/code-list.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,CAAC;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,oBAAoB,EAAE,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAoNF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,6BAAkC,GAC1C,wBAAwB,CAuC1B"}