@autobest-ui/agent 1.0.7 → 1.0.10

package/bin/traceability-validators.test.mjs

@@ -156,25 +156,70 @@ test('spec 校验器验证完整映射和输入哈希', async t => {
   const fixture = await createTraceableScope();
   t.after(() => fs.rm(fixture.root, { recursive: true, force: true }));
   const review = {
-    schemaVersion: 1,
+    schemaVersion: 2,
+    sessionStatus: 'complete',
+    userConfirmed: true,
     scope: {
       manifestPath: '../scope-manifest.json',
       directory: '01-product-detail',
       scopePath: 'scope.md'
     },
+    rounds: [{ round: 1, questionIds: ['Q001'] }],
+    questions: [{
+      id: 'Q001',
+      requirementIds: ['REQ-PD-001'],
+      area: 'dataContract',
+      parentQuestionIds: [],
+      question: '主图字段使用哪个接口字段？',
+      recommendation: '使用 PRD 明确的新字段。',
+      affectedAcceptance: '决定主图数据来源。',
+      status: 'answered',
+      answer: '使用新字段',
+      answeredBy: 'user'
+    }],
     requirements: [{
       id: 'REQ-PD-001',
       scopeStatus: 'active',
       reviewStatus: 'confirmed',
+      decisionCoverage: {
+        scopeBoundary: 'evidence',
+        dataContract: 'user',
+        emptyError: 'not-applicable',
+        stateInteraction: 'not-applicable',
+        permission: 'not-applicable',
+        responsiveVisual: 'evidence',
+        acceptanceEvidence: 'evidence'
+      },
+      questionIds: ['Q001'],
       decisions: ['商品主图必须可见'],
+      evidenceRefs: ['scope.md#REQ-PD-001'],
       remainingIssues: []
     }],
+    openFrontier: [],
     scopeUpdatesRequired: []
   };
   const spec = '# 商品详情功能规格\n\n## REQ-PD-001 商品主图\n\n### 验收条件\n\n- 商品主图可见。\n';
   const reviewText = `${JSON.stringify(review, null, 2)}\n`;
   await fs.writeFile(path.join(fixture.pageDir, 'review/review-result.json'), reviewText);
   assert.equal(runValidator(reviewValidator, fixture.pageDir).status, 0);
+
+  const incompleteReview = structuredClone(review);
+  incompleteReview.userConfirmed = false;
+  incompleteReview.questions[0].status = 'open';
+  delete incompleteReview.questions[0].answer;
+  delete incompleteReview.questions[0].answeredBy;
+  incompleteReview.requirements[0].reviewStatus = 'unresolved';
+  incompleteReview.requirements[0].decisionCoverage.dataContract = 'open';
+  incompleteReview.requirements[0].remainingIssues = ['主图字段尚未确定'];
+  incompleteReview.openFrontier = ['Q001'];
+  await fs.writeFile(
+    path.join(fixture.pageDir, 'review/review-result.json'),
+    `${JSON.stringify(incompleteReview, null, 2)}\n`
+  );
+  const incomplete = runValidator(reviewValidator, fixture.pageDir);
+  assert.equal(incomplete.status, 1);
+  assert.match(incomplete.stderr, /complete 会话/);
+  await fs.writeFile(path.join(fixture.pageDir, 'review/review-result.json'), reviewText);
   await fs.writeFile(path.join(fixture.pageDir, 'spec.md'), spec);
   const trace = {
     schemaVersion: 1,

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@autobest-ui/agent",
-  "version": "1.0.7",
+  "version": "1.0.10",
   "private": false,
   "description": "Autobest Agent skills/plugins/mcp assets + sync cli",
   "files": [
     "skills",
     "plugins",
-    "!plugins/**/node_modules",
-    "!plugins/**/.runtime",
     "mcp",
-    "bin"
+    "bin",
+    "!**/node_modules",
+    "!**/.runtime"
   ],
   "type": "module",
   "engines": {

package/plugins/autobest-delivery/README.md

@@ -65,7 +65,9 @@ npx --yes --package=@autobest-ui/agent@latest autobest-delivery-setup --help
 - `baseUrl`：可访问的应用 URL。
 - `outputDir`：工作区内的证据输出目录。
 
-可选参数包括 `iteration`、`timeoutMs`、`headed`、`keepBrowserOpenOnBlock` 和 `blockedSessionTtlMs`。交付验收使用 headed 模式；发生 Blocked 时，工具保留可见浏览器并返回 session ID、过期时间、结构化检查、组件截图、Trace、控制台错误、网络失败和 SHA-256。
+新建或修订场景还必须传入用户确认的 `apiMode`（`real` 或 `mock`）；Runner 会校验它与冻结场景一致。可选参数包括 `iteration`、`timeoutMs`、`headed`、`keepBrowserOpenOnBlock` 和 `blockedSessionTtlMs`。交付验收使用 headed 模式；发生 Blocked 时，工具保留可见浏览器并返回 session ID、过期时间、结构化检查、API 响应证据、组件截图、Trace、控制台错误、网络失败和 SHA-256。
+
+`real` 模式禁止 `route()` 和 `page.route()` 请求拦截，并要求每个声明业务端点都产生响应证据；缺失时不能判为通过。`mock` 模式允许受控 fixture，但 Runner 和报告会明确标记为模拟。Delivery 命令未指定模式时会在 E2E 前询问；例如“执行真实API”会直接锁定 `real`，不会自动创建 mock。
 
 新版场景通过 `scene(id, callback)` 隔离页面和执行错误。一个 scene 的定位器、弹窗或准备步骤阻塞时，运行器会记录该 blocker 并继续执行后续独立 scene，全部 scene 尝试结束后再返回 `blocked`。旧版直接使用顶层 `page` 的场景仍可运行，但无法在未捕获异常后继续。
 
@@ -90,10 +92,29 @@ npx --yes --package=@autobest-ui/agent@latest autobest-delivery-setup --help
 
 ```js
 export const metadata = {
+  apiModeSchemaVersion: 1,
+  apiMode: 'real',
+  apiTargets: [{
+    id: 'product-detail',
+    method: 'GET',
+    pathname: '/api/product/detail'
+  }],
+  reportSchemaVersion: 1,
+  reportCaptureSchemaVersion: 1,
   traceabilitySchemaVersion: 1,
   requirementIds: ['REQ-PD-001'],
   scenes: ['initial'],
   viewports: [{ name: 'desktop', width: 1400, height: 1000 }],
+  reportCaptures: [{
+    requirementId: 'REQ-PD-001',
+    scene: 'initial',
+    capture: 'product-detail-desktop.png',
+    locator: '[data-testid="product-detail"]',
+    reportModule: '产品详情',
+    reportGroup: 'product-detail',
+    reportTitle: '产品详情',
+    reportDevice: 'desktop'
+  }],
   visualMappings: []
 };
 
@@ -113,7 +134,7 @@ export default async function run({
 }
 ```
 
-每个 `metadata.scenes` 项必须由 `scene()` 恰好执行一次，并自行完成导航、API fixture 和状态准备。测试编写者在冻结 SHA-256 前使用同一运行器进行 preflight；定位器、弹窗、fixture 和等待条件等测试机械问题应在草稿阶段修正。preflight 只证明测试代码能够完整执行，不替代独立验收和视觉审查。
+每个 `metadata.scenes` 项必须由 `scene()` 恰好执行一次，并自行完成导航、数据和状态准备。`real` 模式使用真实环境数据且禁止请求拦截；`mock` 模式才允许 API fixture。每个报告功能组至少声明并生成一张代表性 UI 截图。测试编写者在冻结 SHA-256 前使用相同 API 模式和同一运行器进行 preflight；定位器、弹窗、fixture 和等待条件等测试机械问题应在草稿阶段修正。preflight 只证明测试代码能够完整执行、声明 API 已响应且报告截图已生成，不替代独立验收和视觉审查。
 
 视觉审查使用 `1400px` 桌面视口和与 Figma 一致的 `375px` 移动视口。截图必须定位到与基准相同的语义节点；比较组件结构、布局和视觉样式，不比较业务文字的字面值、长度或业务图片主体。文案及数据内容由独立功能检查验证。
 
@@ -123,16 +144,16 @@ export default async function run({
 
 Checker 和代码审计生成的 Markdown 使用简体中文，包括标题、摘要、表头、检查说明、期望、实际结果和 finding。JSON 字段名、机器状态、ID、路径及原始工具错误保持协议格式；英文原始错误旁提供中文解释。
 
-手动调用 `$export-report` 时，Excel 只生成一个 `自测报告` 工作表。每行代表一个真实 UI 组件或完整业务功能；同一组件或功能的文案、样式、布局、响应式行为和相关检查合并到同一行，桌面端与移动端代表截图也放在该行。报告不展示 story ID、scene 名或原子检查明细。新证据通过 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod` 和 `reportDevice` 提供通用分组；旧证据必须由导出 Skill 分析 `spec.md` 后生成经过哈希和完整覆盖校验的语义分组清单，禁止按 E2E scene 猜测。
+手动调用 `$export-report` 时，Excel 只生成一个 `自测报告` 工作表。每行代表一个真实 UI 组件或完整业务功能；同一组件或功能的文案、样式、布局、响应式行为和相关检查合并到同一行，桌面端与移动端代表截图也放在该行。报告不展示 REQ/story ID、scene 名或原子检查明细。新证据通过 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod` 和 `reportDevice` 提供通用分组，并通过 `reportCaptures` 留下运行时 UI 截图。`visualMappings` 只负责有 Figma 基准时的视觉一致性验收；普通报告截图不表示视觉比对通过。旧证据必须由导出 Skill 分析 `spec.md` 后生成经过哈希和完整覆盖校验的语义分组清单，禁止按 E2E scene 猜测。
 
 ## 交付流程
 
-功能目录存在 `spec-traceability.json` 时，Delivery 按 active REQ ID 运行。Maker 报告实现编号，E2E 检查和视觉映射携带 `requirementId`，Checker 与 Audit 逐项核对；运行器拒绝格式错误、未知编号和无验收覆盖的需求。没有追踪文件的历史交付仍按旧契约运行。
+功能目录存在 `spec-traceability.json` 时，Delivery 按 active REQ ID 运行。Maker 报告实现编号，E2E 检查、报告截图和视觉映射携带 `requirementId`，Checker 与 Audit 逐项核对；运行器拒绝格式错误、未知编号和无验收覆盖的需求。没有追踪文件的历史交付仍按旧契约运行。
 
-1. `$delivery-loop` 校验可用的需求追踪文件，调用 `check_environment` 并记录固定审查点。
+1. `$delivery-loop` 校验需求追踪文件，确认 `real` 或 `mock` API 模式，调用 `check_environment` 并记录固定审查点。
 2. `$code-craft` 实现规格。
-3. `$e2e-gen-spec` 创建无依赖场景，运行冻结前 preflight，确认所有 scene 和检查可达后冻结。
-4. `$e2e-ui-checker` 启动声明的应用服务，调用 `run_feature_e2e`，并审查已映射的组件截图。
+3. `$e2e-gen-spec` 按已确认 API 模式创建无依赖场景，运行冻结前 preflight，确认 API、scene、检查和报告截图可达后冻结。
+4. `$e2e-ui-checker` 启动声明的应用服务，使用相同 API 模式调用 `run_feature_e2e`，核对 API 和报告截图证据，并审查有本地设计基准的视觉映射。
 5. Blocked 时进入人工决策；只有用户选择 `stop` 才终止。
 6. 验收通过或用户接受 waiver 后，`$code-audit` 审查代码规范和规格符合度。
 

package/plugins/autobest-delivery/mcp-server/src/report.mjs

@@ -58,10 +58,10 @@ function resolveEvidencePath(rawPath, { featureDir, workspaceRoot }) {
   return resolved;
 }
 
-function parseSpecStories(specText) {
+function parseLegacySpecStories(specText) {
   const section = specText.match(/(?:^|\n)## 用户故事\s*\n([\s\S]*?)(?=\n## |$)/);
   if (!section) {
-    throw new Error('spec.md 缺少“用户故事”章节，无法生成自测点');
+    return null;
   }
   const stories = [];
   const lines = section[1].split(/\r?\n/);
@@ -85,6 +85,33 @@ function parseSpecStories(specText) {
   return stories;
 }
 
+function parseTraceableSpecChecks(specText, checks) {
+  const requirementIds = new Set(
+    [...specText.matchAll(/^## (REQ-[A-Z][A-Z0-9]{1,15}-\d{3})(?:\s+.+)?$/gm)]
+      .map(match => match[1])
+  );
+  if (requirementIds.size === 0) {
+    throw new Error('spec.md 既没有“用户故事”章节，也没有 REQ 需求章节');
+  }
+  if (checks.size === 0) {
+    throw new Error('REQ 规格缺少 Runner/Checker 原子检查，无法生成自测点');
+  }
+  return [...checks.values()].map((check, index) => {
+    if (!nonEmptyString(check.requirementId) || !requirementIds.has(check.requirementId)) {
+      throw new Error(`检查 ${check.id || index + 1} 缺少有效的 spec REQ 映射`);
+    }
+    return {
+      number: index + 1,
+      id: check.id,
+      text: check.specSnippet || check.expect || check.id
+    };
+  });
+}
+
+function parseSpecItems(specText, checks) {
+  return parseLegacySpecStories(specText) || parseTraceableSpecChecks(specText, checks);
+}
+
 async function findLatestRunnerResult(featureDir) {
   const runsDir = path.join(featureDir, 'e2e', 'runs');
   let entries;
@@ -218,8 +245,36 @@ function reportMethodFor(group) {
   ].join('\n');
 }
 
+function resolveApiMode(runner) {
+  const resultMode = nonEmptyString(runner.apiMode);
+  const metadataMode = nonEmptyString(runner.metadata?.apiMode);
+  for (const mode of [resultMode, metadataMode].filter(Boolean)) {
+    if (!['real', 'mock'].includes(mode)) {
+      throw new Error(`Runner 包含无效 apiMode：${mode}`);
+    }
+  }
+  if (resultMode && metadataMode && resultMode !== metadataMode) {
+    throw new Error('Runner 顶层 apiMode 与 metadata.apiMode 不一致');
+  }
+  return resultMode || metadataMode || null;
+}
+
+function reportMethodWithApiMode(group, apiMode) {
+  const method = reportMethodFor(group);
+  if (apiMode === 'real') {
+    return `API 数据：真实环境 API。\n${method}`;
+  }
+  if (apiMode === 'mock') {
+    return `API 数据：模拟 API。\n${method}`;
+  }
+  return method;
+}
+
 function buildCaptureRecords(runner) {
-  const mappings = runner.metadata?.visualMappings || [];
+  const mappings = [
+    ...(runner.metadata?.visualMappings || []),
+    ...(runner.metadata?.reportCaptures || [])
+  ];
   const mappingByCapture = new Map(mappings.map(mapping => [mapping.capture, mapping]));
   return (runner.captures || []).map(rawPath => {
     const basename = path.basename(rawPath);
@@ -509,14 +564,15 @@ export async function exportDeliveryReport(options) {
     throw new Error(`缺少 Checker 结果：${checkerPath}`);
   }
   const specText = await readFile(specPath, 'utf8');
-  const stories = parseSpecStories(specText);
   const checker = await readJson(checkerPath, 'Checker 结果');
   const runnerPath = await selectRunnerResult(checker, context);
   if (!runnerPath) {
     throw new Error(`缺少 Runner 结果：${path.join(featureDir, 'e2e', 'runs')}`);
   }
   const runner = await readJson(runnerPath, 'Runner 结果');
+  const apiMode = resolveApiMode(runner);
   const checks = mergeChecks(checker, runner);
+  const stories = parseSpecItems(specText, checks);
   const captures = buildCaptureRecords(runner);
   const grouping = await resolveReportGroups({
     stories,
@@ -550,7 +606,7 @@ export async function exportDeliveryReport(options) {
     const row = worksheet.addRow([
       group.module,
       group.title,
-      reportMethodFor(group),
+      reportMethodWithApiMode(group, apiMode),
       group.status,
       '',
       ''
@@ -600,6 +656,7 @@ export async function exportDeliveryReport(options) {
     embeddedScreenshots,
     screenshotPlacements,
     groupingSource: grouping.source,
-    groupingPath: grouping.groupingPath
+    groupingPath: grouping.groupingPath,
+    apiMode
   };
 }

package/plugins/autobest-delivery/mcp-server/src/runner.mjs

@@ -155,6 +155,7 @@ export async function runFeatureE2E({
   scenarioPath,
   baseUrl,
   outputDir,
+  apiMode,
   iteration = 1,
   timeoutMs = 300000,
   headed = false,
@@ -175,12 +176,14 @@ export async function runFeatureE2E({
   const scenarioBlockers = [];
   const consoleErrors = [];
   const networkFailures = [];
+  const apiCalls = [];
   const invokedScenes = new Set();
   let browser;
   let context;
   let page;
   let blockedPage;
   let metadata = {};
+  let apiTargets = [];
   let timeoutId;
   let traceStarted = false;
   let traceError;
@@ -197,11 +200,63 @@ export async function runFeatureE2E({
       throw new TypeError('冻结场景必须导出一个默认异步函数');
     }
     metadata = scenarioModule.metadata || {};
+    const apiModeSchemaVersion = metadata.apiModeSchemaVersion;
     const reportSchemaVersion = metadata.reportSchemaVersion;
+    const reportCaptureSchemaVersion = metadata.reportCaptureSchemaVersion;
+    if (apiModeSchemaVersion !== undefined && apiModeSchemaVersion !== 1) {
+      throw new TypeError('metadata.apiModeSchemaVersion 仅支持 1');
+    }
+    if (apiModeSchemaVersion === 1) {
+      if (!['real', 'mock'].includes(metadata.apiMode)) {
+        throw new TypeError('metadata.apiMode 必须是 real 或 mock');
+      }
+      if (!['real', 'mock'].includes(apiMode)) {
+        throw new TypeError('run_feature_e2e 必须显式传入 apiMode: real 或 mock');
+      }
+      if (apiMode !== metadata.apiMode) {
+        throw new TypeError(
+          `执行 API 模式 ${apiMode} 与冻结场景模式 ${metadata.apiMode} 不一致`
+        );
+      }
+      if (!Array.isArray(metadata.apiTargets) || metadata.apiTargets.length === 0) {
+        throw new TypeError('metadata.apiTargets 必须是非空数组');
+      }
+      const targetIds = new Set();
+      apiTargets = metadata.apiTargets.map(target => {
+        if (!target || typeof target.id !== 'string' || !/^[a-z0-9][a-z0-9._-]*$/.test(target.id)) {
+          throw new TypeError('apiTarget.id 必须是稳定的 ASCII ID');
+        }
+        if (targetIds.has(target.id)) {
+          throw new TypeError(`apiTarget.id 不得重复：${target.id}`);
+        }
+        targetIds.add(target.id);
+        if (typeof target.method !== 'string' || !/^[A-Z]+$/.test(target.method)) {
+          throw new TypeError(`apiTarget ${target.id} 的 method 必须是大写 HTTP 方法`);
+        }
+        if (
+          typeof target.pathname !== 'string' ||
+          !target.pathname.startsWith('/') ||
+          target.pathname.includes('?') ||
+          target.pathname.includes('#')
+        ) {
+          throw new TypeError(`apiTarget ${target.id} 的 pathname 必须是无查询参数的绝对路径`);
+        }
+        return {
+          id: target.id,
+          method: target.method,
+          pathname: target.pathname
+        };
+      });
+    } else if (apiMode !== undefined && !['real', 'mock'].includes(apiMode)) {
+      throw new TypeError('apiMode 仅支持 real 或 mock');
+    }
     const traceabilitySchemaVersion = metadata.traceabilitySchemaVersion;
     if (reportSchemaVersion !== undefined && reportSchemaVersion !== 1) {
       throw new TypeError('metadata.reportSchemaVersion 仅支持 1');
     }
+    if (reportCaptureSchemaVersion !== undefined && reportCaptureSchemaVersion !== 1) {
+      throw new TypeError('metadata.reportCaptureSchemaVersion 仅支持 1');
+    }
     if (traceabilitySchemaVersion !== undefined && traceabilitySchemaVersion !== 1) {
       throw new TypeError('metadata.traceabilitySchemaVersion 仅支持 1');
     }
@@ -227,6 +282,14 @@ export async function runFeatureE2E({
           throw new TypeError(`visualMapping 引用了未知需求 ID：${mapping.requirementId}`);
         }
       }
+      for (const mapping of metadata.reportCaptures || []) {
+        if (!mapping || typeof mapping.requirementId !== 'string') {
+          throw new TypeError('reportCapture 必须包含 requirementId');
+        }
+        if (!requirementIds.has(mapping.requirementId)) {
+          throw new TypeError(`reportCapture 引用了未知需求 ID：${mapping.requirementId}`);
+        }
+      }
     }
     if (reportSchemaVersion === 1) {
       for (const mapping of metadata.visualMappings || []) {
@@ -243,6 +306,43 @@ export async function runFeatureE2E({
         }
       }
     }
+    if (reportCaptureSchemaVersion === 1) {
+      if (!Array.isArray(metadata.reportCaptures) || metadata.reportCaptures.length === 0) {
+        throw new TypeError('metadata.reportCaptures 必须是非空数组');
+      }
+      const captureNames = new Set();
+      for (const mapping of metadata.reportCaptures) {
+        for (const field of [
+          'capture',
+          'scene',
+          'locator',
+          'reportModule',
+          'reportGroup',
+          'reportTitle',
+          'reportDevice'
+        ]) {
+          if (!mapping || typeof mapping[field] !== 'string' || !mapping[field].trim()) {
+            throw new TypeError(`reportCapture 必须包含非空字符串字段 ${field}`);
+          }
+        }
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*\.png$/.test(mapping.capture)) {
+          throw new TypeError('reportCapture.capture 必须是简单的 PNG 文件名');
+        }
+        if (captureNames.has(mapping.capture)) {
+          throw new TypeError(`reportCapture.capture 不得重复：${mapping.capture}`);
+        }
+        captureNames.add(mapping.capture);
+        if (!['desktop', 'mobile'].includes(mapping.reportDevice)) {
+          throw new TypeError('reportCapture.reportDevice 必须是 desktop 或 mobile');
+        }
+        if (!/^[a-z0-9][a-z0-9._-]*$/.test(mapping.reportGroup)) {
+          throw new TypeError('reportCapture.reportGroup 必须是稳定的 ASCII ID');
+        }
+        if (Array.isArray(metadata.scenes) && !metadata.scenes.includes(mapping.scene)) {
+          throw new TypeError(`reportCapture 引用了未知 scene：${mapping.scene}`);
+        }
+      }
+    }
 
     browser = await chromium.launch({ headless: !headed });
     context = await browser.newContext();
@@ -261,6 +361,28 @@ export async function runFeatureE2E({
           error: request.failure()?.errorText || '未知请求失败'
         });
       });
+      currentPage.on('response', response => {
+        const request = response.request();
+        const requestUrl = new URL(response.url());
+        for (const target of apiTargets) {
+          if (request.method() === target.method && requestUrl.pathname === target.pathname) {
+            apiCalls.push({
+              targetId: target.id,
+              method: target.method,
+              origin: requestUrl.origin,
+              pathname: target.pathname,
+              status: response.status()
+            });
+          }
+        }
+      });
+      if (metadata.apiMode === 'real') {
+        const rejectInterception = async () => {
+          throw new TypeError('real API 模式禁止 route() 或 page.route() 请求拦截');
+        };
+        Object.defineProperty(currentPage, 'route', { value: rejectInterception });
+        Object.defineProperty(currentPage, 'routeFromHAR', { value: rejectInterception });
+      }
       return currentPage;
     };
     page = await createPage();
@@ -323,7 +445,12 @@ export async function runFeatureE2E({
       expect,
       check,
       scene,
-      route: (pattern, handler) => currentPage.route(pattern, handler),
+      route: (pattern, handler) => {
+        if (metadata.apiMode === 'real') {
+          throw new TypeError('real API 模式禁止 route() 请求拦截');
+        }
+        return currentPage.route(pattern, handler);
+      },
       capture,
       artifact,
       baseUrl,
@@ -399,6 +526,37 @@ export async function runFeatureE2E({
         throw new TypeError(`以下需求 ID 没有运行或视觉覆盖：${uncovered.join(', ')}`);
       }
     }
+    if (metadata.apiModeSchemaVersion === 1 && scenarioBlockers.length === 0) {
+      const observedTargets = new Set(apiCalls.map(call => call.targetId));
+      const missingTargets = apiTargets
+        .filter(target => !observedTargets.has(target.id))
+        .map(target => target.id);
+      if (missingTargets.length > 0) {
+        throw new TypeError(`以下声明 API 未产生响应证据：${missingTargets.join(', ')}`);
+      }
+    }
+    if (reportCaptureSchemaVersion === 1 && scenarioBlockers.length === 0) {
+      const declaredCaptures = new Set(metadata.reportCaptures.map(item => item.capture));
+      const actualCaptures = new Set(captures.map(item => path.basename(item)));
+      const missingCaptures = [...declaredCaptures].filter(name => !actualCaptures.has(name));
+      if (missingCaptures.length > 0) {
+        throw new TypeError(`以下报告截图未生成：${missingCaptures.join(', ')}`);
+      }
+      const captureGroups = new Set(metadata.reportCaptures.map(item => item.reportGroup));
+      const missingGroups = [...new Set(checks.map(item => item.reportGroup))]
+        .filter(group => group && !captureGroups.has(group));
+      if (missingGroups.length > 0) {
+        throw new TypeError(`以下报告功能组没有截图：${missingGroups.join(', ')}`);
+      }
+      const declaredEvidence = new Set([
+        ...declaredCaptures,
+        ...(metadata.visualMappings || []).map(item => item.capture)
+      ]);
+      const undeclaredCaptures = [...actualCaptures].filter(name => !declaredEvidence.has(name));
+      if (undeclaredCaptures.length > 0) {
+        throw new TypeError(`以下截图未在 metadata 中声明：${undeclaredCaptures.join(', ')}`);
+      }
+    }
     if (blockedPage && !blockedPage.isClosed()) {
       await blockedPage.bringToFront().catch(() => undefined);
       page = blockedPage;
@@ -412,6 +570,8 @@ export async function runFeatureE2E({
       scenarioPath: toEvidencePath(root, scenario),
       scenarioSha256: beforeHash,
       metadata,
+      apiMode: metadata.apiMode || null,
+      apiCalls,
       checks,
       captures,
       tracePath: toEvidencePath(root, tracePath),
@@ -432,6 +592,8 @@ export async function runFeatureE2E({
       scenarioPath: toEvidencePath(root, scenario),
       scenarioSha256: beforeHash,
       metadata,
+      apiMode: metadata.apiMode || null,
+      apiCalls,
       checks,
       captures,
       tracePath: traceStarted ? toEvidencePath(root, tracePath) : null,

package/plugins/autobest-delivery/mcp-server/src/server.mjs

@@ -61,12 +61,13 @@ server.registerTool(
   {
     title: '执行冻结的功能 E2E 场景',
     description:
-      '使用插件自带的 Playwright 运行器执行无依赖冻结场景；scene 隔离可在单个场景阻塞后继续执行其余场景，并在功能目录下写入结构化证据。',
+      '使用插件自带的 Playwright 运行器执行无依赖冻结场景；显式校验 real/mock API 模式，scene 隔离可在单个场景阻塞后继续执行其余场景，并在功能目录下写入结构化证据。',
     inputSchema: {
       workspaceRoot: z.string().min(1),
       scenarioPath: z.string().min(1),
       baseUrl: z.string().url(),
       outputDir: z.string().min(1),
+      apiMode: z.enum(['real', 'mock']).optional(),
       iteration: z.number().int().positive().default(1),
       timeoutMs: z.number().int().min(1000).max(900000).default(300000),
       headed: z.boolean().default(false),
@@ -79,6 +80,8 @@ server.registerTool(
       scenarioPath: z.string(),
       scenarioSha256: z.string().nullable(),
       metadata: z.record(z.string(), z.unknown()),
+      apiMode: z.enum(['real', 'mock']).nullable(),
+      apiCalls: z.array(z.record(z.string(), z.unknown())),
       checks: z.array(z.record(z.string(), z.unknown())),
       captures: z.array(z.string()),
       tracePath: z.string().nullable(),
@@ -119,6 +122,8 @@ server.registerTool(
         scenarioPath: input.scenarioPath,
         scenarioSha256: null,
         metadata: {},
+        apiMode: input.apiMode || null,
+        apiCalls: [],
         checks: [],
         captures: [],
         tracePath: null,

package/plugins/autobest-delivery/mcp-server/tests/fixture-server.mjs

@@ -19,6 +19,11 @@ const html = `<!doctype html>
 
 export function startFixtureServer() {
   const server = http.createServer((request, response) => {
+    if (request.url === '/api/status') {
+      response.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+      response.end(JSON.stringify({ source: 'real-fixture-server' }));
+      return;
+    }
     response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
     response.end(html);
   });

package/plugins/autobest-delivery/mcp-server/tests/report.test.mjs

@@ -164,6 +164,44 @@ test('同一组件或功能合并为单 Sheet 一行，不输出原子明细', a
   );
 });
 
+test('REQ 分节规格可从检查映射导出并嵌入报告截图', async () => {
+  const { workspaceRoot, featureDir, runDir } = await createFixture();
+  await writeFile(
+    path.join(featureDir, 'spec.md'),
+    '# 订单规格\n\n## REQ-ORDER-001 订单交互\n\n订单页展示标题、支持支付，并显示错误状态。\n'
+  );
+  const runnerPath = path.join(runDir, 'runner-result.json');
+  const runner = JSON.parse(await readFile(runnerPath, 'utf8'));
+  for (const check of runner.checks) {
+    check.requirementId = 'REQ-ORDER-001';
+  }
+  runner.metadata.reportCaptures = runner.metadata.visualMappings.map(mapping => ({
+    ...mapping,
+    requirementId: 'REQ-ORDER-001',
+    locator: 'main'
+  }));
+  runner.apiMode = 'mock';
+  runner.metadata.apiMode = 'mock';
+  runner.metadata.visualMappings = [];
+  await writeFile(runnerPath, JSON.stringify(runner));
+
+  const checkerPath = path.join(featureDir, 'checker', 'checker-result.json');
+  const checker = JSON.parse(await readFile(checkerPath, 'utf8'));
+  checker.checks[0].requirementId = 'REQ-ORDER-001';
+  await writeFile(checkerPath, JSON.stringify(checker));
+
+  const result = await exportDeliveryReport({ featureDir, workspaceRoot, templatePath });
+  assert.equal(result.rows, 3);
+  assert.equal(result.groupingSource, 'metadata');
+  assert.equal(result.apiMode, 'mock');
+  assert.equal(result.embeddedScreenshots, 2);
+  assert.equal(result.screenshotPlacements, 2);
+
+  const workbook = new ExcelJS.Workbook();
+  await workbook.xlsx.readFile(result.outputPath);
+  assert.match(workbook.getWorksheet('自测报告').getCell('C2').value, /^API 数据：模拟 API。/);
+});
+
 test('旧证据必须提供完整语义分组清单，不能按 scene 猜测功能', async () => {
   const { workspaceRoot, featureDir, runDir, desktop, mobile } = await createFixture();
   const runnerPath = path.join(runDir, 'runner-result.json');