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

package/dist/src/testcase/testcase-v1-draft.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ep-stage-testcase/v1-draft 类型定义。
+ *
+ * 字段补齐 spec 门禁 + run 渲染所需 P1 字段：
+ * - cases[].reviewStatus：spec 门禁用
+ * - uncoveredCandidates[].{requiredRole,businessIntent,assertionExpectation}：run 追加渲染用
+ *
+ * 桶位约束：
+ * - cases[] 只承载 generationStrategy='glue'
+ * - uncoveredCandidates[] 只承载 generationStrategy='ai'
+ * 校验函数负责拒绝违规。
+ */
+import type { RuntimeContext } from './runtime-context.js';
+import type { TestAccessConfig } from './test-access.js';
+import type { TestcaseExecutionFields } from './testcase-execution-fields.js';
+/**
+ * 用例生成策略（与 contract 层 GenerationStrategy 对齐，本层独立声明避免跨层依赖）。
+ */
+export type TestcaseGenerationStrategy = 'glue' | 'ai';
+/**
+ * 用例覆盖状态。
+ */
+export type TestcaseCoverageStatus = 'covered' | 'partial' | 'gap' | 'blocked';
+/**
+ * 用例评审状态（spec 门禁消费）。
+ */
+export type TestcaseReviewStatus = 'confirmed' | 'needs_review' | 'blocked';
+/**
+ * testcase.json5 v1-draft 顶层类型。
+ */
+export type EpStageTestcaseV1Draft = {
+    schemaVersion: 'ep-stage-testcase/v1-draft';
+    testcaseId: string;
+    contractRef: string;
+    scenario: string;
+    moduleId: string;
+    moduleName: string;
+    menuPath?: string;
+    runtimeContext?: RuntimeContext;
+    testAccess?: TestAccessConfig;
+    cases: Array<{
+        caseId: string;
+        title: string;
+        generationStrategy: 'glue';
+        coverageStatus: TestcaseCoverageStatus;
+        reviewStatus: TestcaseReviewStatus;
+    } & TestcaseExecutionFields>;
+    uncoveredCandidates: Array<{
+        caseId: string;
+        label: string;
+        generationStrategy: 'ai';
+        coverageStatus: TestcaseCoverageStatus;
+        requiredRole: string;
+        businessIntent: string;
+        assertionExpectation: string;
+    } & TestcaseExecutionFields>;
+};
+//# sourceMappingURL=testcase-v1-draft.d.ts.map

package/dist/src/testcase/testcase-v1-draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testcase-v1-draft.d.ts","sourceRoot":"","sources":["../../../src/testcase/testcase-v1-draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,IAAI,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,cAAc,GAAG,SAAS,CAAC;AAE5E;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,aAAa,EAAE,4BAA4B,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,KAAK,EAAE,KAAK,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,kBAAkB,EAAE,MAAM,CAAC;QAC3B,cAAc,EAAE,sBAAsB,CAAC;QACvC,YAAY,EAAE,oBAAoB,CAAC;KACpC,GAAG,uBAAuB,CAAC,CAAC;IAC7B,mBAAmB,EAAE,KAAK,CAAC;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,kBAAkB,EAAE,IAAI,CAAC;QACzB,cAAc,EAAE,sBAAsB,CAAC;QACvC,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,oBAAoB,EAAE,MAAM,CAAC;KAC9B,GAAG,uBAAuB,CAAC,CAAC;CAC9B,CAAC"}

package/dist/src/testcase/testcase-v1-draft.js

@@ -0,0 +1,13 @@
+/**
+ * ep-stage-testcase/v1-draft 类型定义。
+ *
+ * 字段补齐 spec 门禁 + run 渲染所需 P1 字段：
+ * - cases[].reviewStatus：spec 门禁用
+ * - uncoveredCandidates[].{requiredRole,businessIntent,assertionExpectation}：run 追加渲染用
+ *
+ * 桶位约束：
+ * - cases[] 只承载 generationStrategy='glue'
+ * - uncoveredCandidates[] 只承载 generationStrategy='ai'
+ * 校验函数负责拒绝违规。
+ */
+export {};

package/dist/src/validation/contract.d.ts

@@ -0,0 +1,14 @@
+import type { EpStageContractV1Draft } from '../contracts/glue-contract-v1.js';
+/**
+ * 校验 contract.json5 v1-draft schema。
+ *
+ * 必含 schemaVersion:"ep-stage-contract/v1-draft" + contractId + contractKind +
+ * base.{module,navigation,credentials} + scenario.{searchFields[],skeletonSlots,gapCandidates[]} +
+ * unresolvedSlots[]。
+ *
+ * @param obj - 从 JSON5 解析出来的原始对象。
+ * @returns 归一化后的 EpStageContractV1Draft。
+ * @throws 缺字段 / 版本不匹配 / 桶位结构错时抛结构化错误。
+ */
+export declare function validateContract(obj: unknown): EpStageContractV1Draft;
+//# sourceMappingURL=contract.d.ts.map

package/dist/src/validation/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/validation/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAsB,MAAM,kCAAkC,CAAC;AAcnG;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,CAuHrE"}

package/dist/src/validation/contract.js

@@ -0,0 +1,132 @@
+const ALLOWED_STRATEGIES = new Set(['glue', 'ai']);
+/**
+ * 断言值为非空字符串，否则抛错。
+ *
+ * @param value - 待校验值。
+ * @param field - 字段路径（错误信息用）。
+ */
+function requireString(value, field) {
+    if (typeof value !== 'string' || !value)
+        throw new Error(`contract.json5 字段 ${field} 必须为非空字符串`);
+}
+/**
+ * 校验 contract.json5 v1-draft schema。
+ *
+ * 必含 schemaVersion:"ep-stage-contract/v1-draft" + contractId + contractKind +
+ * base.{module,navigation,credentials} + scenario.{searchFields[],skeletonSlots,gapCandidates[]} +
+ * unresolvedSlots[]。
+ *
+ * @param obj - 从 JSON5 解析出来的原始对象。
+ * @returns 归一化后的 EpStageContractV1Draft。
+ * @throws 缺字段 / 版本不匹配 / 桶位结构错时抛结构化错误。
+ */
+export function validateContract(obj) {
+    if (!obj || typeof obj !== 'object')
+        throw new Error('contract.json5 顶层必须是对象');
+    const raw = obj;
+    if (raw.schemaVersion !== 'ep-stage-contract/v1-draft') {
+        throw new Error(`contract.json5 schemaVersion 必须为 ep-stage-contract/v1-draft，实际: ${String(raw.schemaVersion)}`);
+    }
+    requireString(raw.contractId, 'contractId');
+    requireString(raw.contractKind, 'contractKind');
+    // base.{module,navigation,credentials}
+    const base = raw.base;
+    if (!base || typeof base !== 'object')
+        throw new Error('contract.json5 缺 base');
+    const baseObj = base;
+    const moduleObj = baseObj.module;
+    if (!moduleObj || typeof moduleObj !== 'object')
+        throw new Error('contract.json5 缺 base.module');
+    const moduleRec = moduleObj;
+    requireString(moduleRec.id, 'base.module.id');
+    requireString(moduleRec.label, 'base.module.label');
+    const navigation = baseObj.navigation;
+    if (!navigation || typeof navigation !== 'object')
+        throw new Error('contract.json5 缺 base.navigation');
+    const navRec = navigation;
+    if (navRec.entryMode !== 'directUrl' && navRec.entryMode !== 'menu') {
+        throw new Error('contract.json5 base.navigation.entryMode 必须为 directUrl 或 menu');
+    }
+    if (navRec.entryMode === 'directUrl') {
+        requireString(navRec.directUrl, 'base.navigation.directUrl');
+    }
+    const credentials = baseObj.credentials;
+    if (!credentials || typeof credentials !== 'object')
+        throw new Error('contract.json5 缺 base.credentials');
+    requireString(credentials.source, 'base.credentials.source');
+    // scenario
+    const scenario = raw.scenario;
+    if (!scenario || typeof scenario !== 'object')
+        throw new Error('contract.json5 缺 scenario');
+    const sc = scenario;
+    requireString(sc.kind, 'scenario.kind');
+    // scenario.searchFields[]
+    if (!Array.isArray(sc.searchFields) || sc.searchFields.length === 0) {
+        throw new Error('contract.json5 缺 scenario.searchFields[]');
+    }
+    for (const [i, sf] of sc.searchFields.entries()) {
+        requireString(sf.field, `scenario.searchFields[${i}].field`);
+        requireString(sf.label, `scenario.searchFields[${i}].label`);
+        requireString(sf.component, `scenario.searchFields[${i}].component`);
+    }
+    // scenario.skeletonSlots.{crud,export}
+    const slots = sc.skeletonSlots;
+    if (!slots || typeof slots !== 'object')
+        throw new Error('contract.json5 缺 scenario.skeletonSlots');
+    const slotsRec = slots;
+    if (!slotsRec.crud || typeof slotsRec.crud !== 'object') {
+        throw new Error('contract.json5 缺 scenario.skeletonSlots.crud');
+    }
+    if (!slotsRec.export || typeof slotsRec.export !== 'object') {
+        throw new Error('contract.json5 缺 scenario.skeletonSlots.export');
+    }
+    if (!slotsRec.export || typeof slotsRec.export !== 'object') {
+        throw new Error('contract.json5 缺 scenario.skeletonSlots.export');
+    }
+    const exportSlot = slotsRec.export;
+    requireString(exportSlot.moduleId, 'scenario.skeletonSlots.export.moduleId');
+    requireString(exportSlot.label, 'scenario.skeletonSlots.export.label');
+    requireString(exportSlot.mode, 'scenario.skeletonSlots.export.mode');
+    // scenario.skeletonSlots.childGrids（可选）
+    if (slotsRec.childGrids !== undefined) {
+        if (!Array.isArray(slotsRec.childGrids)) {
+            throw new Error('contract.json5 scenario.skeletonSlots.childGrids 必须是数组');
+        }
+        for (const [i, grid] of slotsRec.childGrids.entries()) {
+            if (!grid || typeof grid !== 'object') {
+                throw new Error(`contract.json5 scenario.skeletonSlots.childGrids[${i}] 必须是对象`);
+            }
+            requireString(grid.gridId, `scenario.skeletonSlots.childGrids[${i}].gridId`);
+            requireString(grid.label, `scenario.skeletonSlots.childGrids[${i}].label`);
+            if (!Array.isArray(grid.columns)) {
+                throw new Error(`contract.json5 scenario.skeletonSlots.childGrids[${i}].columns 必须是数组`);
+            }
+            for (const [j, col] of grid.columns.entries()) {
+                if (!col || typeof col !== 'object') {
+                    throw new Error(`contract.json5 scenario.skeletonSlots.childGrids[${i}].columns[${j}] 必须是对象`);
+                }
+                requireString(col.field, `scenario.skeletonSlots.childGrids[${i}].columns[${j}].field`);
+                requireString(col.label, `scenario.skeletonSlots.childGrids[${i}].columns[${j}].label`);
+                if (col.component !== 'input' && col.component !== 'listbox') {
+                    throw new Error(`contract.json5 scenario.skeletonSlots.childGrids[${i}].columns[${j}].component 必须为 input 或 listbox`);
+                }
+            }
+        }
+    }
+    // scenario.gapCandidates[]
+    if (!Array.isArray(sc.gapCandidates)) {
+        throw new Error('contract.json5 缺 scenario.gapCandidates[]');
+    }
+    for (const [i, g] of sc.gapCandidates.entries()) {
+        requireString(g.gapId, `scenario.gapCandidates[${i}].gapId`);
+        requireString(g.label, `scenario.gapCandidates[${i}].label`);
+        if (!ALLOWED_STRATEGIES.has(g.generationStrategy)) {
+            throw new Error(`scenario.gapCandidates[${i}].generationStrategy 必须 ∈ {glue,ai}`);
+        }
+    }
+    // unresolvedSlots[]
+    if (!Array.isArray(raw.unresolvedSlots)) {
+        throw new Error('contract.json5 缺 unresolvedSlots[]');
+    }
+    return raw;
+}

package/dist/src/validation/credentials.d.ts

@@ -1,6 +1,11 @@
 /** credentials.json5 单条凭据（REQ-ENV-03）。 */
 export type Credential = {
-    url: string;
+    /** 兼容旧字段，等价于 loginUrl。 */
+    url?: string;
+    /** 登录地址。 */
+    loginUrl?: string;
+    /** 待测页面直达链接。 */
+    directUrl?: string;
     username: string;
     password: string;
     role?: string;
@@ -9,7 +14,7 @@ export type Credential = {
 /**
  * 校验 credentials.json5 数组形态（REQ-ENV-02 / REQ-ENV-03）。
  *
- * 不变量：数组至少 1 条；必填 url/username/password 非空；同 (url, role) 组合唯一。
+ * 不变量：数组至少 1 条；必填 loginUrl 或 url、username、password 非空；同 (loginUrl/url, role) 组合唯一。
  *
  * @param obj - 从 JSON5 解析出来的原始对象。
  * @returns 归一化后的凭据数组。

package/dist/src/validation/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../../src/validation/credentials.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,EAAE,CAyB9D"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../../src/validation/credentials.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG;IACvB,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,EAAE,CAoC9D"}

package/dist/src/validation/credentials.js

@@ -1,7 +1,7 @@
 /**
  * 校验 credentials.json5 数组形态（REQ-ENV-02 / REQ-ENV-03）。
  *
- * 不变量：数组至少 1 条；必填 url/username/password 非空；同 (url, role) 组合唯一。
+ * 不变量：数组至少 1 条；必填 loginUrl 或 url、username、password 非空；同 (loginUrl/url, role) 组合唯一。
  *
  * @param obj - 从 JSON5 解析出来的原始对象。
  * @returns 归一化后的凭据数组。
@@ -16,18 +16,29 @@ export function validateCredentials(obj) {
     const result = [];
     for (let i = 0; i < obj.length; i++) {
         const e = obj[i];
-        for (const f of ['url', 'username', 'password']) {
+        for (const f of ['username', 'password']) {
             if (typeof e[f] !== 'string' || !e[f].trim()) {
                 throw new Error(`credentials.json5 第 ${i + 1} 条缺必填字段 ${f}`);
             }
         }
+        const loginUrl = typeof e.loginUrl === 'string' && e.loginUrl.trim()
+            ? e.loginUrl
+            : e.url;
+        if (typeof loginUrl !== 'string' || !loginUrl.trim()) {
+            throw new Error(`credentials.json5 第 ${i + 1} 条缺必填字段 loginUrl`);
+        }
+        if (e.directUrl !== undefined && typeof e.directUrl !== 'string') {
+            throw new Error(`credentials.json5 第 ${i + 1} 条 directUrl 必须为字符串`);
+        }
         const role = typeof e.role === 'string' ? e.role : '';
-        const key = `${e.url}|${role}`;
+        const key = `${loginUrl}|${role}`;
         if (seen.has(key))
             throw new Error(`credentials.json5 同 (url, role) 重复: ${key}`);
         seen.add(key);
         result.push({
-            url: e.url,
+            loginUrl,
+            ...(typeof e.url === 'string' ? { url: e.url } : {}),
+            ...(typeof e.directUrl === 'string' ? { directUrl: e.directUrl } : {}),
             username: e.username,
             password: e.password,
             ...(role ? { role } : {}),

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

@@ -1,5 +1,7 @@
 export { validateProjectsIndex } from './projects-index.js';
 export { validateTestcase } from './testcase.js';
+export { validateContract } from './contract.js';
 export { validateCredentials } from './credentials.js';
+export { validateInferenceTrace } from './inference-trace.js';
 export type { Credential } from './credentials.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/validation/index.js

@@ -1,3 +1,5 @@
 export { validateProjectsIndex } from './projects-index.js';
 export { validateTestcase } from './testcase.js';
+export { validateContract } from './contract.js';
 export { validateCredentials } from './credentials.js';
+export { validateInferenceTrace } from './inference-trace.js';

package/dist/src/validation/inference-trace.d.ts

@@ -0,0 +1,13 @@
+import type { InferenceTraceV1 } from '../contracts/inference-trace.js';
+/**
+ * 校验 inference-trace.json 的顶层结构（REQ-INFER-006）。
+ *
+ * 最小校验：只保证 schemaVersion 正确且 5 个必需顶层章节存在。
+ * 章节内部证据数组 / reason 允许扩展（spec §8），不做深校验。
+ *
+ * @param obj - 从 JSON.parse 得到的任意值。
+ * @returns 类型收窄后的 InferenceTraceV1。
+ * @throws 顶层非对象、schemaVersion 不符或缺章节时抛错。
+ */
+export declare function validateInferenceTrace(obj: unknown): InferenceTraceV1;
+//# sourceMappingURL=inference-trace.d.ts.map

package/dist/src/validation/inference-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-trace.d.ts","sourceRoot":"","sources":["../../../src/validation/inference-trace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAExE;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAoBrE"}

package/dist/src/validation/inference-trace.js

@@ -0,0 +1,31 @@
+/**
+ * 校验 inference-trace.json 的顶层结构（REQ-INFER-006）。
+ *
+ * 最小校验：只保证 schemaVersion 正确且 5 个必需顶层章节存在。
+ * 章节内部证据数组 / reason 允许扩展（spec §8），不做深校验。
+ *
+ * @param obj - 从 JSON.parse 得到的任意值。
+ * @returns 类型收窄后的 InferenceTraceV1。
+ * @throws 顶层非对象、schemaVersion 不符或缺章节时抛错。
+ */
+export function validateInferenceTrace(obj) {
+    const raw = obj;
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('inference-trace.json 顶层必须是对象');
+    }
+    if (raw.schemaVersion !== 'inference-trace/v1') {
+        throw new Error('inference-trace.json schemaVersion 必须是 inference-trace/v1');
+    }
+    for (const key of [
+        'materialInventory',
+        'sourceAnalysis',
+        'moduleHintsInference',
+        'coverageDiff',
+        'reasoningSummary',
+    ]) {
+        if (!raw[key]) {
+            throw new Error(`inference-trace.json 缺 ${key}`);
+        }
+    }
+    return raw;
+}

package/dist/src/validation/testcase.d.ts

@@ -1,13 +1,15 @@
-import type { TestcaseV2 } from '../testcase/testcase-v2.js';
+import type { EpStageTestcaseV1Draft } from '../testcase/testcase-v1-draft.js';
 /**
- * 校验 testcase.json5 v2 schema（REQ-DATA-02 / REQ-SCHEMA-01）。
+ * 校验 testcase.json5 v1-draft schema（新协议重构后唯一版本，破旧立新不保留 v2 兼容）。
  *
- * 必含 schemaVersion:"v2" + scenario + menuPath + requiredSystems[] + requiredRoles[] +
- * coveredActions[] + uncoveredCandidates[] + cases[]；evidence 元素符合 <kind>=<ref>。
+ * 桶位约束：
+ * - cases[] 每项 generationStrategy 必须 === 'glue'，且含 reviewStatus
+ * - uncoveredCandidates[] 每项 generationStrategy 必须 === 'ai'，
+ *   且含 requiredRole/businessIntent/assertionExpectation
  *
  * @param obj - 从 JSON5 解析出来的原始对象。
- * @returns 归一化后的 TestcaseV2。
- * @throws 缺字段 / 版本不匹配 / evidence 格式错时抛结构化错误。
+ * @returns 归一化后的 EpStageTestcaseV1Draft。
+ * @throws 缺字段 / 版本不匹配 / 桶位违规时抛结构化错误。
  */
-export declare function validateTestcase(obj: unknown): TestcaseV2;
+export declare function validateTestcase(obj: unknown): EpStageTestcaseV1Draft;
 //# sourceMappingURL=testcase.d.ts.map

package/dist/src/validation/testcase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testcase.d.ts","sourceRoot":"","sources":["../../../src/validation/testcase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAI7D;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAuCzD"}
+{"version":3,"file":"testcase.d.ts","sourceRoot":"","sources":["../../../src/validation/testcase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EAGvB,MAAM,kCAAkC,CAAC;AA6I1C;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,CAwErE"}

package/dist/src/validation/testcase.js

@@ -1,53 +1,200 @@
-const EVIDENCE_RE = /^(html|java|spec|contract|skeleton|hint)=.+$/;
+const ALLOWED_COVERAGE = new Set([
+    'covered',
+    'partial',
+    'gap',
+    'blocked',
+]);
+const ALLOWED_REVIEW = new Set([
+    'confirmed',
+    'needs_review',
+    'blocked',
+]);
 /**
- * 校验 testcase.json5 v2 schema（REQ-DATA-02 / REQ-SCHEMA-01）。
+ * 断言值为非空字符串，否则抛错。
  *
- * 必含 schemaVersion:"v2" + scenario + menuPath + requiredSystems[] + requiredRoles[] +
- * coveredActions[] + uncoveredCandidates[] + cases[]；evidence 元素符合 <kind>=<ref>。
+ * @param value - 待校验值。
+ * @param field - 字段路径（错误信息用）。
+ */
+function requireString(value, field) {
+    if (typeof value !== 'string' || !value)
+        throw new Error(`testcase.json5 字段 ${field} 必须为非空字符串`);
+}
+/**
+ * 断言值为字符串数组，否则抛错。
+ *
+ * @param value - 待校验值。
+ * @param field - 字段路径（错误信息用）。
+ */
+function requireStringArray(value, field) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item)) {
+        throw new Error(`testcase.json5 字段 ${field} 必须为非空字符串数组`);
+    }
+}
+/**
+ * 断言值若存在则必须为字符串。
+ *
+ * @param value - 待校验值。
+ * @param field - 字段路径（错误信息用）。
+ */
+function requireOptionalString(value, field) {
+    if (value !== undefined && typeof value !== 'string') {
+        throw new Error(`testcase.json5 字段 ${field} 必须为字符串`);
+    }
+}
+/**
+ * 校验可选执行字段。
+ *
+ * @param raw - 原始对象。
+ * @param fieldPrefix - 字段前缀。
+ */
+function validateExecutionFields(raw, fieldPrefix) {
+    requireOptionalString(raw.queryKey, `${fieldPrefix}.queryKey`);
+    requireOptionalString(raw.precondition, `${fieldPrefix}.precondition`);
+    requireOptionalString(raw.steps, `${fieldPrefix}.steps`);
+    requireOptionalString(raw.assertion, `${fieldPrefix}.assertion`);
+}
+/**
+ * 校验 runtimeContext。
+ *
+ * @param value - 原始 runtimeContext。
+ */
+function validateRuntimeContext(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('testcase.json5 字段 runtimeContext 必须为对象');
+    }
+    const runtimeContext = value;
+    requireString(runtimeContext.testProjectDir, 'runtimeContext.testProjectDir');
+    requireString(runtimeContext.caseDir, 'runtimeContext.caseDir');
+    requireString(runtimeContext.specPath, 'runtimeContext.specPath');
+}
+/**
+ * 校验 testAccess 角色。
+ *
+ * @param role - 角色配置。
+ * @param fieldPrefix - 字段前缀。
+ */
+function validateTestAccessRole(role, fieldPrefix) {
+    requireString(role.role, `${fieldPrefix}.role`);
+    requireOptionalString(role.username, `${fieldPrefix}.username`);
+    requireOptionalString(role.password, `${fieldPrefix}.password`);
+    requireStringArray(role.permissions, `${fieldPrefix}.permissions`);
+}
+/**
+ * 校验 testAccess 系统。
+ *
+ * @param system - 系统配置。
+ * @param fieldPrefix - 字段前缀。
+ */
+function validateTestAccessSystem(system, fieldPrefix) {
+    requireString(system.systemName, `${fieldPrefix}.systemName`);
+    requireOptionalString(system.loginUrl, `${fieldPrefix}.loginUrl`);
+    if (!Array.isArray(system.roles)) {
+        throw new Error(`testcase.json5 字段 ${fieldPrefix}.roles 必须为数组`);
+    }
+    for (const [index, role] of system.roles.entries()) {
+        if (!role || typeof role !== 'object') {
+            throw new Error(`testcase.json5 字段 ${fieldPrefix}.roles[${index}] 必须为对象`);
+        }
+        validateTestAccessRole(role, `${fieldPrefix}.roles[${index}]`);
+    }
+}
+/**
+ * 校验 testAccess。
+ *
+ * @param value - 原始 testAccess。
+ */
+function validateTestAccess(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('testcase.json5 字段 testAccess 必须为对象');
+    }
+    const testAccess = value;
+    requireOptionalString(testAccess.credentialRef, 'testAccess.credentialRef');
+    if (testAccess.requiredRoles !== undefined) {
+        requireStringArray(testAccess.requiredRoles, 'testAccess.requiredRoles');
+    }
+    if (testAccess.systems === undefined) {
+        if (testAccess.credentialRef === undefined) {
+            throw new Error('testcase.json5 字段 testAccess.credentialRef 或 testAccess.systems 必须至少提供一个');
+        }
+        return;
+    }
+    if (!Array.isArray(testAccess.systems)) {
+        throw new Error('testcase.json5 字段 testAccess.systems 必须为数组');
+    }
+    for (const [index, system] of testAccess.systems.entries()) {
+        if (!system || typeof system !== 'object') {
+            throw new Error(`testcase.json5 字段 testAccess.systems[${index}] 必须为对象`);
+        }
+        validateTestAccessSystem(system, `testAccess.systems[${index}]`);
+    }
+}
+/**
+ * 校验 testcase.json5 v1-draft schema（新协议重构后唯一版本，破旧立新不保留 v2 兼容）。
+ *
+ * 桶位约束：
+ * - cases[] 每项 generationStrategy 必须 === 'glue'，且含 reviewStatus
+ * - uncoveredCandidates[] 每项 generationStrategy 必须 === 'ai'，
+ *   且含 requiredRole/businessIntent/assertionExpectation
  *
  * @param obj - 从 JSON5 解析出来的原始对象。
- * @returns 归一化后的 TestcaseV2。
- * @throws 缺字段 / 版本不匹配 / evidence 格式错时抛结构化错误。
+ * @returns 归一化后的 EpStageTestcaseV1Draft。
+ * @throws 缺字段 / 版本不匹配 / 桶位违规时抛结构化错误。
  */
 export function validateTestcase(obj) {
     if (!obj || typeof obj !== 'object')
         throw new Error('testcase.json5 顶层必须是对象');
     const raw = obj;
-    if (raw.schemaVersion !== 'v2') {
-        throw new Error('testcase.json5 schemaVersion 不是 v2（可能是 v1）。请重跑 `ep-stage-skill testcase` 升级。');
+    if (raw.schemaVersion !== 'ep-stage-testcase/v1-draft') {
+        throw new Error(`testcase.json5 schemaVersion 必须为 ep-stage-testcase/v1-draft，实际: ${String(raw.schemaVersion)}`);
     }
-    for (const f of ['scenario', 'menuPath', 'moduleId', 'moduleName']) {
-        if (typeof raw[f] !== 'string')
-            throw new Error(`testcase.json5 缺 ${f}`);
+    // 顶层字符串字段
+    for (const f of ['testcaseId', 'contractRef', 'scenario', 'moduleId', 'moduleName']) {
+        requireString(raw[f], f);
     }
-    for (const f of ['requiredSystems', 'requiredRoles', 'coveredActions', 'uncoveredCandidates', 'cases']) {
-        if (!Array.isArray(raw[f]))
-            throw new Error(`testcase.json5 缺 ${f}[]`);
+    if (raw.menuPath !== undefined) {
+        requireString(raw.menuPath, 'menuPath');
     }
-    const checkEvidence = (ev) => {
-        if (typeof ev !== 'string' || !EVIDENCE_RE.test(ev)) {
-            throw new Error(`evidence 必须为 <kind>=<ref> 格式（kind ∈ html/java/spec/contract/skeleton/hint），实际: ${String(ev)}`);
-        }
-    };
-    for (const a of raw.coveredActions) {
-        if (!Array.isArray(a.evidence))
-            throw new Error('coveredActions[].evidence 必须为数组');
-        a.evidence.forEach(checkEvidence);
+    if (raw.runtimeContext !== undefined) {
+        validateRuntimeContext(raw.runtimeContext);
+    }
+    if (raw.testAccess !== undefined) {
+        validateTestAccess(raw.testAccess);
     }
-    for (const item of raw.uncoveredCandidates) {
-        if (typeof item.requiredRole !== 'string' || !item.requiredRole.trim()) {
-            throw new Error('uncoveredCandidates[].requiredRole 必填');
+    // cases[]
+    if (!Array.isArray(raw.cases))
+        throw new Error('testcase.json5 缺 cases[]');
+    for (const [i, c] of raw.cases.entries()) {
+        requireString(c.caseId, `cases[${i}].caseId`);
+        requireString(c.title, `cases[${i}].title`);
+        if (c.generationStrategy !== 'glue') {
+            throw new Error(`cases[${i}].generationStrategy 必须为 glue（cases 桶只承载 glue），实际: ${String(c.generationStrategy)}`);
+        }
+        if (!ALLOWED_COVERAGE.has(c.coverageStatus)) {
+            throw new Error(`cases[${i}].coverageStatus 必须 ∈ {covered,partial,gap,blocked}`);
         }
-        if (!Array.isArray(item.evidence))
-            throw new Error('uncoveredCandidates[].evidence 必须为数组');
-        item.evidence.forEach(checkEvidence);
+        if (!ALLOWED_REVIEW.has(c.reviewStatus)) {
+            throw new Error(`cases[${i}].reviewStatus 必须 ∈ {confirmed,needs_review,blocked}（spec 门禁用）`);
+        }
+        validateExecutionFields(c, `cases[${i}]`);
+    }
+    // uncoveredCandidates[]
+    if (!Array.isArray(raw.uncoveredCandidates)) {
+        throw new Error('testcase.json5 缺 uncoveredCandidates[]');
     }
-    for (const c of raw.cases) {
-        if (typeof c.requiredRole !== 'string' || !c.requiredRole.trim()) {
-            throw new Error('cases[].requiredRole 必填');
+    for (const [i, u] of raw.uncoveredCandidates.entries()) {
+        requireString(u.caseId, `uncoveredCandidates[${i}].caseId`);
+        requireString(u.label, `uncoveredCandidates[${i}].label`);
+        const strat = u.generationStrategy;
+        if (strat !== 'ai') {
+            throw new Error(`uncoveredCandidates[${i}].generationStrategy 必须为 ai（gap 桶不承载 glue/manual），实际: ${String(strat)}`);
+        }
+        if (!ALLOWED_COVERAGE.has(u.coverageStatus)) {
+            throw new Error(`uncoveredCandidates[${i}].coverageStatus 必须 ∈ {covered,partial,gap,blocked}`);
         }
-        if (Array.isArray(c.evidence))
-            c.evidence.forEach(checkEvidence);
+        requireString(u.requiredRole, `uncoveredCandidates[${i}].requiredRole`);
+        requireString(u.businessIntent, `uncoveredCandidates[${i}].businessIntent`);
+        requireString(u.assertionExpectation, `uncoveredCandidates[${i}].assertionExpectation`);
+        validateExecutionFields(u, `uncoveredCandidates[${i}]`);
     }
     return raw;
 }