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

package/dist/src/cli/run.js

@@ -1,17 +1,22 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import JSON5 from 'json5';
 import { validateTestcase } from '../validation/testcase.js';
+import { classifyRunFailure, createInitialAiRuntimeTrace, nextRepairRound, writeAiRuntimeTrace, writeRepairReport, } from '../runtime/ai-runtime-trace.js';
+import { runSpec } from './spec.js';
 /**
  * AI 追加段分隔标记。重跑时 detect 已有标记则覆盖（保证幂等）。
+ *
+ * 注释语义：本段由 uncoveredCandidates[].generationStrategy='ai' 的候选渲染而来。
  */
-export const AI_APPEND_MARKER = '// === AI 钻探追加（基于 uncoveredCandidates[].status=planned）===';
+export const AI_APPEND_MARKER = '// === AI 钻探追加（基于 uncoveredCandidates[].generationStrategy=ai）===';
 /**
  * 解析 run 子命令参数。
  *
  * @param argv - 已剥离子命令名的命令行参数。
  * @returns RunArgs。
- * @throws 缺少 --spec / --testcase 或参数对非法时抛错。
+ * @throws 缺少 --testcase 或参数对非法时抛错。
  */
 export function parseRunArgs(argv) {
     const result = {};
@@ -22,49 +27,174 @@ export function parseRunArgs(argv) {
         if (!key?.startsWith('--') || !value) {
             throw new Error(`无效参数对: ${key ?? '<empty>'}`);
         }
-        result[key.slice(2)] = value;
+        result[key.slice(2).replace(/-([a-z])/g, (_, char) => char.toUpperCase())] = value;
     }
-    if (!result.spec)
-        throw new Error('缺少 --spec');
     if (!result.testcase)
         throw new Error('缺少 --testcase');
     return {
-        spec: result.spec,
         testcase: result.testcase,
         // headless 默认 true；--headless false 时关闭无头。
         headless: result.headless !== 'false',
-        projectDir: result['project-dir'],
+        aiSnippets: result.aiSnippets,
     };
 }
 /**
- * 渲染 AI 追加段：每条 planned uncoveredCandidate 输出一个占位 test，含
- * requiredRole / businessIntent / assertionExpectation 三条注释（供 AI runtime
- * 推理时拓展为真实业务步骤）。
+ * 判断 testcase 是否位于项目目录内部。
+ *
+ * @param projectDir - 测试项目目录。
+ * @param testcasePath - testcase.json5 路径。
+ * @returns true 表示 testcase 位于 projectDir 内。
+ */
+function isPathInsideProject(projectDir, testcasePath) {
+    const relative = path.relative(projectDir, testcasePath);
+    return !!relative && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+/**
+ * 校验目录是否具备 glue 测试项目最小结构。
+ *
+ * @param candidateDir - 待校验目录。
+ * @returns true 表示目录结构满足 run 阶段回退条件。
+ */
+function isGlueProjectDir(candidateDir) {
+    return (existsSync(path.join(candidateDir, 'package.json')) &&
+        existsSync(path.join(candidateDir, 'playwright.config.ts')) &&
+        existsSync(path.join(candidateDir, 'src', 'skeletons')));
+}
+/**
+ * 从 testcase.json5 定位测试项目和 spec 路径。
+ *
+ * 优先消费 runtimeContext；若缺失或目录校验失败，则从 testcase 所在目录向上查找。
+ *
+ * @param testcasePath - testcase.json5 路径。
+ * @returns run 阶段消费的路径集合。
+ */
+export function resolveRunPaths(testcasePath) {
+    const resolvedTestcasePath = path.resolve(testcasePath);
+    const caseDir = path.dirname(resolvedTestcasePath);
+    const testcaseRaw = JSON5.parse(readFileSync(resolvedTestcasePath, 'utf8'));
+    const testcase = validateTestcase(testcaseRaw);
+    if (testcase.runtimeContext) {
+        const projectDir = path.resolve(testcase.runtimeContext.testProjectDir);
+        const specPath = path.resolve(testcase.runtimeContext.specPath);
+        if (isGlueProjectDir(projectDir) && isPathInsideProject(projectDir, resolvedTestcasePath)) {
+            return {
+                testcasePath: resolvedTestcasePath,
+                caseDir,
+                projectDir,
+                specPath,
+                contractPath: path.join(caseDir, '.ep-stage', 'contract.json5'),
+            };
+        }
+    }
+    let cursor = caseDir;
+    while (true) {
+        if (isGlueProjectDir(cursor)) {
+            return {
+                testcasePath: resolvedTestcasePath,
+                caseDir,
+                projectDir: cursor,
+                specPath: path.join(caseDir, 'crud.spec.ts'),
+                contractPath: path.join(caseDir, '.ep-stage', 'contract.json5'),
+            };
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor) {
+            break;
+        }
+        cursor = parent;
+    }
+    throw new Error(`无法从 testcase.json5 定位测试项目目录: ${resolvedTestcasePath}`);
+}
+/**
+ * 构造从项目目录执行完整 spec 的 Playwright 命令。
+ *
+ * headless=false 时追加 --headed；specPath 原样透传（绝对路径，跨目录稳定）。
+ *
+ * @param input - projectDir / specPath / headless。
+ * @returns 命令、参数与 cwd，供 execFileSync 直接消费。
+ */
+export function buildPlaywrightCommand(input) {
+    // Playwright 命令行参数按正则表达式匹配测试文件路径；原样传中文/含点号
+    // 的绝对路径会被误解析为无效正则。取 basename 并转义正则特殊字符，
+    // 构造 `.*<escaped-basename>` 模式，在 testDir 内稳定命中对应 spec。
+    const basename = path.basename(input.specPath);
+    const escapedBasename = basename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const specArg = `.*${escapedBasename}`;
+    // 追加 list reporter 保证控制台有可被 classifyRunFailure 消费的原生输出；
+    // stage-core 等 reporter 会吞并原生输出，导致失败信息为空。
+    const args = ['playwright', 'test', specArg, '--reporter=list'];
+    if (!input.headless) {
+        args.push('--headed');
+    }
+    return { command: 'npx', args, cwd: input.projectDir };
+}
+/**
+ * 默认执行器：从 projectDir 通过 npx playwright test 执行完整 spec。
+ *
+ * 捕获 stdout 与 stderr；非零退出码即视为失败。同步执行（Playwright run 本身阻塞）。
+ *
+ * @param input - projectDir / specPath / headless。
+ * @returns passed 与合并输出。
+ */
+async function defaultExecuteFullSpec(input) {
+    const cmd = buildPlaywrightCommand(input);
+    // Windows 上 execFileSync 调用 npx 经常捕获不到子进程输出（status=null，
+    // stdout/stderr 为空）。改用 shell 执行 spawnSync，并手动拼接命令字符串
+    // 避免 Node 的 DEP0190 警告（shell=true 时仍传 args 会被弃用）。
+    const command = `${cmd.command} ${cmd.args.map((arg) => `"${arg.replace(/"/g, '\\"')}"`).join(' ')}`;
+    const spawned = spawnSync(command, {
+        cwd: cmd.cwd,
+        encoding: 'utf8',
+        shell: true,
+    });
+    const stdout = spawned.stdout ?? '';
+    const stderr = spawned.stderr ?? '';
+    const status = spawned.status ?? 1;
+    return { passed: status === 0, output: `${stdout}\n${stderr}` };
+}
+/**
+ * 获取默认 AI snippets 路径。
+ *
+ * @param caseDir - 用例目录。
+ * @returns 默认 .ep-stage/ai-snippets.json5 路径。
+ */
+function defaultAiSnippetsPath(caseDir) {
+    return path.join(caseDir, '.ep-stage', 'ai-snippets.json5');
+}
+/**
+ * 读取并校验 Agent O-D-A-V 产出的 snippets。
  *
- * 当前实现只生成占位骨架；真正的 AI runtime 推理在 Phase 5 真机验收阶段接入
- * （参考 run-gap-pipeline.ts 的 planAgentInferredWorkflows 调用链）。本 Sub-step
- * 聚焦于「追加段幂等覆盖」契约，确保重跑不会无限叠加注释体。
+ * 只有 testcasePath 匹配、caseId 属于当前任务、status=resolved 且 specSnippet 非空时才可合并。
  *
- * @param planned - status='planned' 的 uncoveredCandidates。
- * @returns 拼接后的追加段（不含 marker，由调用方串接）。
+ * @param input - snippets 路径、testcase 路径和当前 AI tasks。
+ * @returns 可合并的 AiRuntimeResult 列表。
  */
-function renderAppendedTests(planned) {
-    return planned
-        .map((item) => {
-        return [
-            `test(${JSON.stringify(item.label)}, async ({ page: _page }) => {`,
-            `  // actionId: ${item.actionId}`,
-            `  // requiredRole: ${item.requiredRole}`,
-            `  // businessIntent: ${item.businessIntent}`,
-            `  // assertionExpectation: ${item.assertionExpectation}`,
-            `  // TODO: AI runtime 推理后填入实际 Playwright 步骤`,
-            `});`,
-        ].join('\n');
-    })
-        .join('\n\n');
+export function loadAiSnippets(input) {
+    if (!existsSync(input.snippetsPath)) {
+        return [];
+    }
+    const parsed = JSON5.parse(readFileSync(input.snippetsPath, 'utf8'));
+    if (parsed.schemaVersion !== 'ep-stage-ai-snippets/v1') {
+        throw new Error(`ai-snippets.json5 schemaVersion 非法: ${input.snippetsPath}`);
+    }
+    if (path.resolve(String(parsed.testcasePath)) !== path.resolve(input.testcasePath)) {
+        throw new Error(`ai-snippets.json5 testcasePath 与当前 testcase 不匹配: ${input.snippetsPath}`);
+    }
+    if (!Array.isArray(parsed.results)) {
+        throw new Error(`ai-snippets.json5 缺少 results 数组: ${input.snippetsPath}`);
+    }
+    const taskIds = new Set(input.tasks.map((task) => task.caseId));
+    return parsed.results.filter((result) => {
+        if (!taskIds.has(result.caseId)) {
+            throw new Error(`ai-snippets.json5 包含未知 caseId: ${result.caseId}`);
+        }
+        return (result.status === 'resolved' &&
+            typeof result.specSnippet === 'string' &&
+            result.specSnippet.trim().length > 0);
+    });
 }
 /**
- * 截断现有 spec 的 AI 追加段（用于重跑覆盖）。
+ * 截断现有 spec 的 AI 追加段（用于重跑覆盖，幂等）。
  *
  * @param specBody - 现有 spec 文件全文。
  * @returns 截断到 AI_APPEND_MARKER 之前的基线 spec。
@@ -74,43 +204,342 @@ function truncateAtMarker(specBody) {
     return markerIndex >= 0 ? specBody.slice(0, markerIndex).trimEnd() : specBody.trimEnd();
 }
 /**
- * run 子命令主体（REQ-CHAIN-02 / REQ-SPEC-01）。
+ * 按角色从 testcase.testAccess 中查找最佳匹配。
+ *
+ * @param testcase - 已校验 testcase。
+ * @param requiredRole - 候选用例要求角色。
+ * @returns 匹配到的系统与角色；未命中则返回 undefined。
+ */
+function findRoleAccess(testcase, requiredRole) {
+    for (const system of testcase.testAccess?.systems ?? []) {
+        for (const role of system.roles) {
+            if (role.role === requiredRole) {
+                return { system, role };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * 宽松读取 credentials.json5，用于构建 AI Runtime Task 上下文。
+ *
+ * 这里不做全量强校验，避免未使用角色的空占位阻断任务包生成；真正执行前由运行门禁报告缺失字段。
+ *
+ * @param testcasePath - testcase.json5 绝对路径。
+ * @returns credentials 条目数组；缺文件或结构异常时返回空数组。
+ */
+function resolveCredentialPath(testcase, testcasePath) {
+    const ref = testcase.testAccess?.credentialRef ?? 'credentials.json5';
+    return path.isAbsolute(ref) ? ref : path.join(path.dirname(testcasePath), ref);
+}
+function loadCredentialEntriesLoose(testcase, testcasePath) {
+    const credPath = resolveCredentialPath(testcase, testcasePath);
+    if (!existsSync(credPath))
+        return [];
+    try {
+        const raw = JSON5.parse(readFileSync(credPath, 'utf8'));
+        return Array.isArray(raw) ? raw : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 从 contract.json5 读取待测页面 directUrl。
+ *
+ * @param contractPath - contract.json5 绝对路径。
+ * @returns directUrl 或 undefined。
+ */
+function loadContractDirectUrl(contractPath) {
+    if (!existsSync(contractPath))
+        return undefined;
+    try {
+        const raw = JSON5.parse(readFileSync(contractPath, 'utf8'));
+        return typeof raw.base?.navigation?.directUrl === 'string'
+            ? raw.base.navigation.directUrl
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 按角色从 credentials.json5 中查找运行访问数据。
+ *
+ * @param paths - run 阶段解析出的路径。
+ * @param requiredRole - 候选用例要求角色。
+ * @returns 匹配到的 credentials 条目。
+ */
+function findCredentialAccess(testcase, paths, requiredRole) {
+    return loadCredentialEntriesLoose(testcase, paths.testcasePath).find((entry) => entry.role === requiredRole);
+}
+/**
+ * 构建 AI Runtime Task 的入口上下文。
+ *
+ * @param testcase - 已校验 testcase。
+ * @param requiredRole - 候选用例要求角色。
+ * @param paths - run 阶段解析出的路径。
+ * @returns entryContext。
+ */
+function buildEntryContext(testcase, requiredRole, paths) {
+    const credentialAccess = findCredentialAccess(testcase, paths, requiredRole);
+    const matchedAccess = findRoleAccess(testcase, requiredRole);
+    return {
+        systemName: credentialAccess?.systemName ?? matchedAccess?.system.systemName,
+        directUrl: credentialAccess?.directUrl ?? loadContractDirectUrl(paths.contractPath),
+        loginUrl: credentialAccess?.loginUrl ?? credentialAccess?.url ?? matchedAccess?.system.loginUrl,
+        role: requiredRole,
+        username: credentialAccess?.username ?? matchedAccess?.role.username,
+        password: credentialAccess?.password ?? matchedAccess?.role.password,
+        permissions: matchedAccess?.role.permissions ?? [],
+        testProjectDir: paths.projectDir,
+        caseDir: paths.caseDir,
+        specPath: paths.specPath,
+    };
+}
+/**
+ * 从 testcase 构建 AI Runtime Task 列表。
+ *
+ * `coverageStatus='blocked'` 的候选仅保留在 testcase/审阅侧，不进入 runtime task。
+ *
+ * @param testcase - 已校验 testcase。
+ * @param paths - run 阶段解析出的路径。
+ * @returns AI Runtime Task 列表。
+ */
+export function buildAiRuntimeTasks(testcase, paths) {
+    return testcase.uncoveredCandidates
+        .filter((item) => item.generationStrategy === 'ai' && item.coverageStatus !== 'blocked')
+        .map((item) => ({
+        caseId: item.caseId,
+        title: item.label,
+        role: item.requiredRole,
+        businessIntent: item.businessIntent,
+        assertionExpectation: item.assertionExpectation,
+        entryContext: buildEntryContext(testcase, item.requiredRole, paths),
+        knownContext: {
+            queryKey: item.queryKey,
+            precondition: item.precondition,
+            steps: item.steps,
+            assertion: item.assertion,
+        },
+        codingRules: {
+            devRulesPath: 'docs/00-memory/dev-rules.md',
+        },
+        status: 'pending',
+    }));
+}
+/**
+ * 生成 AI Runtime 初始任务包。
+ *
+ * 该函数只做确定性工作：定位路径、补齐 glue 骨架 spec、构建 tasks 并写 trace。
+ *
+ * @param testcasePath - testcase.json5 路径。
+ * @returns trace 路径、spec 路径和任务摘要。
+ */
+export function prepareAiRuntimeTasks(testcasePath) {
+    const paths = resolveRunPaths(testcasePath);
+    if (!existsSync(paths.specPath)) {
+        runSpec({ testcase: paths.testcasePath, out: paths.specPath });
+    }
+    const testcaseRaw = JSON5.parse(readFileSync(paths.testcasePath, 'utf8'));
+    const testcase = validateTestcase(testcaseRaw);
+    const tasks = buildAiRuntimeTasks(testcase, paths);
+    const blockedCount = testcase.uncoveredCandidates.filter((item) => item.generationStrategy === 'ai' && item.coverageStatus === 'blocked').length;
+    const tracePath = path.join(paths.caseDir, '.ep-stage', 'ai-runtime-trace.json5');
+    writeAiRuntimeTrace(tracePath, createInitialAiRuntimeTrace({
+        testcasePath: paths.testcasePath,
+        tasks,
+    }));
+    return {
+        testcasePath: paths.testcasePath,
+        tracePath,
+        specPath: paths.specPath,
+        taskCount: tasks.length,
+        blockedCount,
+    };
+}
+/**
+ * 为缺少 resolved snippet 的 AI tasks 生成 needs_review 结果。
  *
- * 完整设计（spec §5.4 / brief Step 6）：
- * 1. 按 cases[].requiredRole 用 credentials.json5 登录；
- * 2. 跑 v1 胶水部分 spec；
- * 3. 对 uncoveredCandidates 里 status='planned' 的项做 AI 实时推理（含 requiredRole 切换）；
- * 4. 追加段以 AI_APPEND_MARKER 分隔；重跑检测已有段则覆盖（幂等）；
- * 5. 报告落 e2e/glue-code-mvp/glue-report/<timestamp>/；
- * 6. 回写 projects.index.json5 的 systems[].credentialsCache 与 requirements[].lastRun*。
+ * @param tasks - 当前待推理任务。
+ * @param resolvedResults - 已由 Agent 解决的结果。
+ * @returns 未解决任务的 needs_review 结果。
+ */
+function buildNeedsReviewResults(tasks, resolvedResults) {
+    const resolvedIds = new Set(resolvedResults.map((result) => result.caseId));
+    return tasks
+        .filter((task) => !resolvedIds.has(task.caseId))
+        .map((task) => ({
+        caseId: task.caseId,
+        status: 'needs_review',
+        observation: {
+            summary: '未找到 Agent O-D-A-V 产出的 resolved snippet，等待人工或 Agent 继续推理。',
+        },
+        decision: {
+            action: 'skip merge and execution',
+        },
+        verification: {
+            assertionExpectation: task.assertionExpectation,
+        },
+        evidence: [{ source: 'ep-stage-cli', note: 'CLI 不生成占位 snippet，避免假通过' }],
+    }));
+}
+/**
+ * 生成器在 test.describe 闭包内输出的 in-place 定位 marker（`  // @stage-gap-append`）。
+ *
+ * snippet 必须插到此 marker 之前，marker 与随后的 `});` 保留原位，才能让 AI test 落在
+ * describe 闭包内部并访问 recorder / workflowMeta / openModule / crudSlots 等常量。
+ */
+const AI_INPLACE_MARKER = '  // @stage-gap-append';
+/**
+ * 将 resolved snippets 按任务顺序合并到 spec 的 AI_INPLACE_MARKER 之前（describe 闭包内）。
+ *
+ * @param specPath - crud.spec.ts 路径。
+ * @param tasks - 当前 AI tasks。
+ * @param results - Agent 产出的 resolved results。
+ */
+function appendAiSnippets(specPath, tasks, results) {
+    const byCaseId = new Map(results.map((result) => [result.caseId, result]));
+    const snippets = tasks
+        .map((task) => byCaseId.get(task.caseId)?.specSnippet)
+        .filter((snippet) => typeof snippet === 'string' && snippet.trim().length > 0);
+    const currentSpec = readFileSync(specPath, 'utf8');
+    const markerIndex = currentSpec.indexOf(AI_INPLACE_MARKER);
+    // Fallback：老 spec 无 in-place marker → 沿用旧的末尾追加逻辑（兼容）。
+    if (markerIndex < 0) {
+        const baseSpec = truncateAtMarker(currentSpec);
+        if (snippets.length > 0) {
+            writeFileSync(specPath, `${baseSpec}\n\n${AI_APPEND_MARKER}\n${snippets.join('\n\n')}\n`, 'utf8');
+        }
+        else {
+            writeFileSync(specPath, `${baseSpec}\n`, 'utf8');
+        }
+        return;
+    }
+    // in-place 合并：snippet 插入 marker 之前，marker 与随后 `});` 保留原位。
+    let before = currentSpec.slice(0, markerIndex);
+    const oldHeaderIndex = before.lastIndexOf(AI_APPEND_MARKER);
+    if (oldHeaderIndex >= 0) {
+        // 幂等清除上一轮追加段（旧 header 到当前 marker 之间的所有内容）。
+        before = `${before.slice(0, oldHeaderIndex).replace(/[\s\n]+$/, '')}\n\n`;
+    }
+    const after = currentSpec.slice(markerIndex);
+    if (snippets.length === 0) {
+        writeFileSync(specPath, `${before}${after}`, 'utf8');
+        return;
+    }
+    const section = `  ${AI_APPEND_MARKER}\n${snippets.join('\n\n')}\n\n`;
+    writeFileSync(specPath, `${before}${section}${after}`, 'utf8');
+}
+/**
+ * 读取并声明消费 credentials.json5（消费边界声明）。
+ *
+ * 当前版本：缺失时不崩溃，返回提示字符串供上游告知用户填充；
+ * 存在则 JSON5.parse 读入（本阶段不实现真登录，仅声明消费边界）。
+ *
+ * @param testcasePath - testcase.json5 路径，credentials 约定与之间目录。
+ * @returns credentialsNotice：缺失时为提示文本；存在时为 undefined。
+ */
+function loadCredentialsNotice(testcase, testcasePath) {
+    const credPath = resolveCredentialPath(testcase, testcasePath);
+    if (!existsSync(credPath)) {
+        return `未找到凭据文件（预期路径：${credPath}），当前未消费凭据执行真实登录，请填充凭据后再启用真机模式。`;
+    }
+    // 读入以校验可解析；本 task 不实现真登录，仅声明消费边界。
+    JSON5.parse(readFileSync(credPath, 'utf8'));
+    return undefined;
+}
+/**
+ * run 子命令主体（REQ-CHAIN-02 / REQ-SPEC-01，新协议 v1-draft）。
  *
- * 当前 Sub-step 6 范围：
- * - 完整实现「步骤 4」（AI 追加段幂等覆盖契约）；
- * - 完整实现「步骤 5」（报告目录生成）；
- * - 步骤 1 / 2 / 3 / 6 的 Playwright runtime + AI 推理 + 索引回写在 Phase 5 真机验收阶段
- *   迁移 run-gap-pipeline.ts 的 runtime runner 实现接入（brief 已说明 AI 推理在 Phase 5 证）。
+ * 行为：
+ * 1. resolveRunPaths 定位 projectDir/specPath；spec 缺失时先跑 runSpec 组装 glue 骨架。
+ * 2. 解析 testcase，构建 aiRuntimeTasks（已过滤 coverageStatus='blocked'）。
+ * 3. 读取 Agent O-D-A-V 产出的 ai-snippets.json5。
+ * 4. 若 AI tasks 未全部 resolved，则写 trace results=needs_review 并停止，避免假通过。
+ * 5. 幂等合并 specSnippet 到 spec：truncateAtMarker 后追加 marker + snippets。
+ * 6. 执行完整 spec（deps 注入或默认真实 Playwright）；失败则分类、回写 trace repairRounds 并写 repair report。
+ *
+ * 失败时不静默改变测试意图：写 repair-report.md 等待人审确认。
  *
  * @param args - 已解析参数。
- * @returns version: 'v1-with-planned-stubs' — 真实的 v2（Playwright 执行 + AI 推理填充 planned 项）
- *   待 Phase 5 真机验收阶段从 run-gap-pipeline.ts 的 runtime runner 迁移过来。当前返回 'v1-with-planned-stubs'
- *   而非 'v2' 是为了让下游 skill（glue-run-test 等）能区分"真 v2"与"stub 形态"。
- */
-export async function runRun(args) {
-    if (!existsSync(args.spec))
-        throw new Error(`spec 不存在: ${args.spec}`);
-    const testcaseRaw = JSON5.parse(readFileSync(args.testcase, 'utf8'));
+ * @param deps - 可选注入依赖（测试用于替换推理与执行）。
+ * @returns RunResult。
+ */
+export async function runRun(args, deps) {
+    const paths = resolveRunPaths(args.testcase);
+    if (!existsSync(paths.specPath)) {
+        runSpec({ testcase: paths.testcasePath, out: paths.specPath });
+    }
+    const testcaseRaw = JSON5.parse(readFileSync(paths.testcasePath, 'utf8'));
     const testcase = validateTestcase(testcaseRaw);
-    const planned = testcase.uncoveredCandidates.filter((item) => item.status === 'planned');
-    const currentSpec = readFileSync(args.spec, 'utf8');
-    const baseSpec = truncateAtMarker(currentSpec);
-    if (planned.length > 0) {
-        const appendedTests = renderAppendedTests(planned);
-        writeFileSync(args.spec, `${baseSpec}\n\n${AI_APPEND_MARKER}\n${appendedTests}\n`, 'utf8');
-    }
-    else {
-        // 没有 planned 项时，仍然把 spec 收敛到 baseSpec（保证幂等：重跑能擦掉旧追加段）。
-        writeFileSync(args.spec, `${baseSpec}\n`, 'utf8');
-    }
-    const reportDir = path.join(args.projectDir ?? process.cwd(), 'e2e/glue-code-mvp/glue-report', new Date().toISOString().replace(/[:.]/g, '-'));
-    return { specPath: args.spec, reportDir, version: 'v1-with-planned-stubs' };
+    const tracePath = path.join(paths.caseDir, '.ep-stage', 'ai-runtime-trace.json5');
+    const aiRuntimeTasks = buildAiRuntimeTasks(testcase, paths);
+    const trace = createInitialAiRuntimeTrace({
+        testcasePath: paths.testcasePath,
+        tasks: aiRuntimeTasks,
+    });
+    const snippetsPath = args.aiSnippets ? path.resolve(args.aiSnippets) : defaultAiSnippetsPath(paths.caseDir);
+    const loadSnippets = deps?.loadAiSnippets ?? loadAiSnippets;
+    const resolvedResults = loadSnippets({
+        snippetsPath,
+        testcasePath: paths.testcasePath,
+        tasks: aiRuntimeTasks,
+    });
+    const needsReviewResults = buildNeedsReviewResults(aiRuntimeTasks, resolvedResults);
+    trace.results = [...resolvedResults, ...needsReviewResults];
+    if (needsReviewResults.length > 0) {
+        writeAiRuntimeTrace(tracePath, trace);
+        const reportDir = path.join(paths.projectDir, 'e2e/glue-code-mvp/glue-report', new Date().toISOString().replace(/[:.]/g, '-'));
+        mkdirSync(reportDir, { recursive: true });
+        return {
+            specPath: paths.specPath,
+            reportDir,
+            credentialsNotice: loadCredentialsNotice(testcase, paths.testcasePath),
+            version: 'v1',
+            aiRuntimeTracePath: tracePath,
+        };
+    }
+    appendAiSnippets(paths.specPath, aiRuntimeTasks, resolvedResults);
+    writeAiRuntimeTrace(tracePath, trace);
+    // 执行完整 spec。
+    const executor = deps?.executeFullSpec ?? defaultExecuteFullSpec;
+    const execution = await executor({
+        projectDir: paths.projectDir,
+        specPath: paths.specPath,
+        headless: args.headless,
+    });
+    // 失败时分类并写 repair report，停止等待人审；成功时 repairReportPath 留空。
+    let repairReportPath;
+    if (!execution.passed) {
+        const classification = classifyRunFailure(execution.output);
+        const round = nextRepairRound(paths.caseDir);
+        repairReportPath = writeRepairReport({
+            caseDir: paths.caseDir,
+            round,
+            failureType: classification.failureType,
+            summary: classification.summary,
+            output: execution.output,
+        });
+        trace.repairRounds.push({
+            round,
+            status: 'failed',
+            failureType: classification.failureType,
+            summary: classification.summary,
+        });
+        writeAiRuntimeTrace(tracePath, trace);
+    }
+    // 报告目录。
+    const reportDir = path.join(paths.projectDir, 'e2e/glue-code-mvp/glue-report', new Date().toISOString().replace(/[:.]/g, '-'));
+    mkdirSync(reportDir, { recursive: true });
+    // credentials.json5 消费边界声明。
+    const credentialsNotice = loadCredentialsNotice(testcase, paths.testcasePath);
+    return {
+        specPath: paths.specPath,
+        reportDir,
+        credentialsNotice,
+        version: 'v1',
+        aiRuntimeTracePath: tracePath,
+        repairReportPath,
+    };
 }

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

@@ -1,7 +1,7 @@
 /**
- * spec 子命令参数（REQ-SPEC-01）。
+ * spec 子命令参数（新协议 v1-draft，REQ-SPEC-01）。
  *
- * - testcase：testcase.json5 路径（必填，由 testcase 子命令产出）；
+ * - testcase：testcase.json5 路径（必填，由 testcase 子命令产出，v1-draft）；
  * - out：.spec.ts 输出路径（必填，通常为 <tests-dir>/crud.spec.ts）。
  */
 export type SpecArgs = {
@@ -12,7 +12,7 @@ export type SpecArgs = {
  * spec 子命令产物。
  *
  * @property specPath - 写盘后的 .spec.ts 路径。
- * @property version - 'v1' 表示只含 coveredActions 胶水部分，待 run 子命令追加 v2。
+ * @property version - 'v1' 表示只含 glue 骨架部分，待 run 子命令追加 AI 推理段。
  */
 export type SpecResult = {
     specPath: string;
@@ -27,16 +27,23 @@ export type SpecResult = {
  */
 export declare function parseSpecArgs(argv: string[]): SpecArgs;
 /**
- * spec 子命令主体（REQ-SPEC-01）：只生成 v1 初始版 .spec.ts，不启动浏览器。
+ * spec 子命令主体（新协议 v1-draft，REQ-SPEC-01）：只生成 v1 初始版 .spec.ts，不启动浏览器。
  *
- * v1 = 仅 coveredActions 胶水部分（顶部注释 `// === 胶水模式生成 ===`）；
- * run 子命令后续在底部追加 AI 推理段产 v2。
+ * v1 = 仅 glue 骨架部分（顶部注释 `// === 胶水模式生成 ===`）；
+ * run 子命令后续在底部 `// @stage-gap-append` 处追加 AI 推理段。
  *
- * 实现：
- * 1. 校验 testcase.json5 通过 validateTestcase（v2 schema）；
- * 2. 加载 contract.json（位于 <tests-dir>/.ep-stage/contract.json；不存在时报错引导用户先跑 testcase 子命令）；
- * 3. 调 generateStageSkeletonCrudSpec 生成基线骨架脚本；
- * 4. 头部插入 SKELETON_MARKER_LINE 标记，写盘。
+ * 流程：
+ * 1. JSON5.parse 读 testcase.json5 → validateTestcase（v1-draft schema）；
+ * 2. 门禁 assertTestcaseReadyForSpec（cases 全 confirmed；不阻断 uncoveredCandidates）；
+ * 3. 定位 `.ep-stage/contract.json5`（不再是 contract.json；不存在则中文报错引导先跑 testcase 子命令）；
+ * 4. JSON5.parse + validateContract；
+ * 5. 从 `contract.scenario.skeletonSlots.{crud,export}` 取槽位、
+ *    从 `testcase.{moduleId,moduleName}` 取模块 → 调
+ *    {@link generateStageSkeletonCrudSpecFromSlots} 生成基线骨架脚本；
+ * 6. 头部插 SKELETON_MARKER_LINE 标记，写盘。
+ *
+ * 消费边界（REQ-INFER-008）：只读 testcase.json5 + contract.json5，不读 inference-trace.json。
+ * 新链路零依赖旧 CrudBusinessModuleContract 类型。
  *
  * @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":"AASA;;;;;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;AAiCF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CActD;AAcD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CA+ClD"}