@autobest-ui/agent 1.0.8 → 1.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobest-ui/agent",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "private": false,
   "description": "Autobest Agent skills/plugins/mcp assets + sync cli",
   "files": [

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');

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

@@ -41,6 +41,138 @@ test('checkEnvironment 能报告浏览器运行时缺失', async () => {
   assert.match(result.error, /缺少浏览器可执行文件/);
 });
 
+test('real API 模式命中声明端点并记录真实响应证据', async t => {
+  const fixture = await startFixtureServer();
+  t.after(fixture.close);
+  const workspace = await createWorkspace();
+  t.after(() => fs.rm(workspace.root, { recursive: true, force: true }));
+  await fs.writeFile(workspace.scenarioPath, `export const metadata = {
+  apiModeSchemaVersion: 1,
+  apiMode: 'real',
+  apiTargets: [{ id: 'status', method: 'GET', pathname: '/api/status' }],
+  scenes: ['real-status']
+};
+export default async function ({ scene }) {
+  await scene('real-status', async ({ page, check, baseUrl }) => {
+    await page.goto(baseUrl);
+    await check({ id: 'real-status', specSnippet: '真实 API 返回状态。', scene: 'real-status',
+      errorType: '功能缺陷', expect: '真实 API 响应可用' }, async () => {
+      const data = await page.evaluate(async () => (await fetch('/api/status')).json());
+      if (data.source !== 'real-fixture-server') throw new Error('响应来源错误');
+      return '真实 API 响应可用';
+    });
+  });
+}\n`, 'utf8');
+
+  const result = await runFeatureE2E({
+    workspaceRoot: workspace.root,
+    scenarioPath: path.relative(workspace.root, workspace.scenarioPath),
+    baseUrl: fixture.baseUrl,
+    outputDir: 'feature/e2e/runs/api-real',
+    apiMode: 'real',
+    timeoutMs: 10000
+  });
+
+  assert.equal(result.status, 'passed');
+  assert.equal(result.apiMode, 'real');
+  assert.deepEqual(result.apiCalls.map(call => [call.targetId, call.method, call.pathname, call.status]), [
+    ['status', 'GET', '/api/status', 200]
+  ]);
+});
+
+test('real API 模式拒绝 page.route 请求拦截', async t => {
+  const fixture = await startFixtureServer();
+  t.after(fixture.close);
+  const workspace = await createWorkspace();
+  t.after(() => fs.rm(workspace.root, { recursive: true, force: true }));
+  await fs.writeFile(workspace.scenarioPath, `export const metadata = {
+  apiModeSchemaVersion: 1,
+  apiMode: 'real',
+  apiTargets: [{ id: 'status', method: 'GET', pathname: '/api/status' }],
+  scenes: ['intercept']
+};
+export default async function ({ scene }) {
+  await scene('intercept', async ({ page }) => {
+    await page.route('**/api/status', route => route.fulfill({ status: 200, body: '{}' }));
+  });
+}\n`, 'utf8');
+
+  const result = await runFeatureE2E({
+    workspaceRoot: workspace.root,
+    scenarioPath: path.relative(workspace.root, workspace.scenarioPath),
+    baseUrl: fixture.baseUrl,
+    outputDir: 'feature/e2e/runs/api-real-intercepted',
+    apiMode: 'real',
+    timeoutMs: 10000
+  });
+
+  assert.equal(result.status, 'blocked');
+  assert.match(result.blockers[0].detail, /real API 模式禁止/);
+});
+
+test('执行参数与冻结场景 API 模式不一致时阻断', async t => {
+  const workspace = await createWorkspace();
+  t.after(() => fs.rm(workspace.root, { recursive: true, force: true }));
+  await fs.writeFile(workspace.scenarioPath, `export const metadata = {
+  apiModeSchemaVersion: 1,
+  apiMode: 'mock',
+  apiTargets: [{ id: 'status', method: 'GET', pathname: '/api/status' }]
+};
+export default async function () {}\n`, 'utf8');
+
+  const result = await runFeatureE2E({
+    workspaceRoot: workspace.root,
+    scenarioPath: path.relative(workspace.root, workspace.scenarioPath),
+    baseUrl: 'http://127.0.0.1:1',
+    outputDir: 'feature/e2e/runs/api-mode-mismatch',
+    apiMode: 'real',
+    timeoutMs: 10000
+  });
+
+  assert.equal(result.status, 'blocked');
+  assert.match(result.blockers[0].detail, /模式 real 与冻结场景模式 mock 不一致/);
+});
+
+test('mock API 模式允许显式 fixture 并记录模拟响应', async t => {
+  const fixture = await startFixtureServer();
+  t.after(fixture.close);
+  const workspace = await createWorkspace();
+  t.after(() => fs.rm(workspace.root, { recursive: true, force: true }));
+  await fs.writeFile(workspace.scenarioPath, `export const metadata = {
+  apiModeSchemaVersion: 1,
+  apiMode: 'mock',
+  apiTargets: [{ id: 'status', method: 'GET', pathname: '/api/status' }],
+  scenes: ['mock-status']
+};
+export default async function ({ scene }) {
+  await scene('mock-status', async ({ page, route, check, baseUrl }) => {
+    await route('**/api/status', requestRoute => requestRoute.fulfill({
+      status: 200, contentType: 'application/json', body: JSON.stringify({ source: 'mock' })
+    }));
+    await page.goto(baseUrl);
+    await check({ id: 'mock-status', specSnippet: '模拟 API 返回状态。', scene: 'mock-status',
+      errorType: '功能缺陷', expect: '模拟 API 响应可用' }, async () => {
+      const data = await page.evaluate(async () => (await fetch('/api/status')).json());
+      if (data.source !== 'mock') throw new Error('响应来源错误');
+      return '模拟 API 响应可用';
+    });
+  });
+}\n`, 'utf8');
+
+  const result = await runFeatureE2E({
+    workspaceRoot: workspace.root,
+    scenarioPath: path.relative(workspace.root, workspace.scenarioPath),
+    baseUrl: fixture.baseUrl,
+    outputDir: 'feature/e2e/runs/api-mock',
+    apiMode: 'mock',
+    timeoutMs: 10000
+  });
+
+  assert.equal(result.status, 'passed');
+  assert.equal(result.apiMode, 'mock');
+  assert.equal(result.apiCalls[0].targetId, 'status');
+});
+
 test('runFeatureE2E 能执行冻结场景并写入可审查证据', async t => {
   const fixture = await startFixtureServer();
   t.after(fixture.close);
@@ -123,6 +255,153 @@ export default async function ({ check }) {
   assert.match(result.blockers[0].detail, /reportModule/);
 });
 
+test('报告截图 schema v1 生成声明截图后通过', async t => {
+  const fixture = await startFixtureServer();
+  t.after(fixture.close);
+  const workspace = await createWorkspace();
+  t.after(() => fs.rm(workspace.root, { recursive: true, force: true }));
+  await fs.writeFile(workspace.scenarioPath, `export const metadata = {
+  reportSchemaVersion: 1,
+  reportCaptureSchemaVersion: 1,
+  traceabilitySchemaVersion: 1,
+  requirementIds: ['REQ-PD-001'],
+  scenes: ['initial'],
+  reportCaptures: [{
+    requirementId: 'REQ-PD-001', scene: 'initial', capture: 'detail-desktop.png',
+    locator: 'main', reportModule: '详情页', reportGroup: 'detail',
+    reportTitle: '详情内容', reportDevice: 'desktop'
+  }],
+  visualMappings: []
+};
+export default async function ({ scene }) {
+  await scene('initial', async ({ page, check, capture, baseUrl }) => {
+    await page.goto(baseUrl);
+    await check({
+      id: 'detail-visible', requirementId: 'REQ-PD-001', specSnippet: '详情可见。',
+      scene: 'initial', reportModule: '详情页', reportGroup: 'detail',
+      reportTitle: '详情内容', reportMethod: '检查详情内容和运行状态。',
+      errorType: '功能缺陷', expect: '详情可见'
+    }, async () => '详情可见');
+    await capture(page.locator('main'), 'detail-desktop.png');
+  });
+}\n`, 'utf8');
+
+  const result = await runFeatureE2E({
+    workspaceRoot: workspace.root,
+    scenarioPath: path.relative(workspace.root, workspace.scenarioPath),
+    baseUrl: fixture.baseUrl,
+    outputDir: 'feature/e2e/runs/report-capture-valid',
+    timeoutMs: 10000
+  });
+
+  assert.equal(result.status, 'passed');
+  assert.equal(result.captures.length, 1);
+  assert.equal(result.metadata.reportCaptures[0].requirementId, 'REQ-PD-001');
+});
+
+test('报告截图 schema v1 拒绝未生成的声明截图', async t => {
+  const workspace = await createWorkspace();
+  t.after(() => fs.rm(workspace.root, { recursive: true, force: true }));
+  await fs.writeFile(workspace.scenarioPath, `export const metadata = {
+  reportSchemaVersion: 1,
+  reportCaptureSchemaVersion: 1,
+  scenes: ['initial'],
+  reportCaptures: [{
+    scene: 'initial', capture: 'missing.png', locator: 'main', reportModule: '详情页',
+    reportGroup: 'detail', reportTitle: '详情内容', reportDevice: 'desktop'
+  }],
+  visualMappings: []
+};
+export default async function ({ scene }) {
+  await scene('initial', async ({ check }) => {
+    await check({
+      id: 'detail-visible', specSnippet: '详情可见。', scene: 'initial',
+      reportModule: '详情页', reportGroup: 'detail', reportTitle: '详情内容',
+      reportMethod: '检查详情内容。', errorType: '功能缺陷', expect: '详情可见'
+    }, async () => '详情可见');
+  });
+}\n`, 'utf8');
+
+  const result = await runFeatureE2E({
+    workspaceRoot: workspace.root,
+    scenarioPath: path.relative(workspace.root, workspace.scenarioPath),
+    baseUrl: 'http://127.0.0.1:1',
+    outputDir: 'feature/e2e/runs/report-capture-missing',
+    timeoutMs: 10000
+  });
+
+  assert.equal(result.status, 'blocked');
+  assert.match(result.blockers[0].detail, /报告截图未生成/);
+});
+
+test('报告截图 schema v1 拒绝没有截图的报告功能组', async t => {
+  const fixture = await startFixtureServer();
+  t.after(fixture.close);
+  const workspace = await createWorkspace();
+  t.after(() => fs.rm(workspace.root, { recursive: true, force: true }));
+  await fs.writeFile(workspace.scenarioPath, `export const metadata = {
+  reportSchemaVersion: 1,
+  reportCaptureSchemaVersion: 1,
+  scenes: ['initial'],
+  reportCaptures: [{
+    scene: 'initial', capture: 'detail.png', locator: 'main', reportModule: '详情页',
+    reportGroup: 'detail', reportTitle: '详情内容', reportDevice: 'desktop'
+  }],
+  visualMappings: []
+};
+export default async function ({ scene }) {
+  await scene('initial', async ({ page, check, capture, baseUrl }) => {
+    await page.goto(baseUrl);
+    for (const [id, group] of [['detail-visible', 'detail'], ['action-visible', 'action']]) {
+      await check({ id, specSnippet: '功能可见。', scene: 'initial', reportModule: '详情页',
+        reportGroup: group, reportTitle: group, reportMethod: '检查功能。',
+        errorType: '功能缺陷', expect: '功能可见' }, async () => '功能可见');
+    }
+    await capture(page.locator('main'), 'detail.png');
+  });
+}\n`, 'utf8');
+
+  const result = await runFeatureE2E({
+    workspaceRoot: workspace.root,
+    scenarioPath: path.relative(workspace.root, workspace.scenarioPath),
+    baseUrl: fixture.baseUrl,
+    outputDir: 'feature/e2e/runs/report-group-missing-capture',
+    timeoutMs: 10000
+  });
+
+  assert.equal(result.status, 'blocked');
+  assert.match(result.blockers[0].detail, /action/);
+});
+
+test('报告截图 schema v1 拒绝未知需求 ID', async t => {
+  const workspace = await createWorkspace();
+  t.after(() => fs.rm(workspace.root, { recursive: true, force: true }));
+  await fs.writeFile(workspace.scenarioPath, `export const metadata = {
+  reportCaptureSchemaVersion: 1,
+  traceabilitySchemaVersion: 1,
+  requirementIds: ['REQ-PD-001'],
+  scenes: ['initial'],
+  reportCaptures: [{
+    requirementId: 'REQ-PD-002', scene: 'initial', capture: 'detail.png',
+    locator: 'main', reportModule: '详情页', reportGroup: 'detail',
+    reportTitle: '详情内容', reportDevice: 'desktop'
+  }],
+  visualMappings: []
+};
+export default async function () {}\n`, 'utf8');
+
+  const result = await runFeatureE2E({
+    workspaceRoot: workspace.root,
+    scenarioPath: path.relative(workspace.root, workspace.scenarioPath),
+    baseUrl: 'http://127.0.0.1:1',
+    outputDir: 'feature/e2e/runs/report-capture-unknown-requirement',
+    timeoutMs: 10000
+  });
+
+  assert.equal(result.status, 'blocked');
+  assert.match(result.blockers[0].detail, /未知需求 ID/);
+});
+
 test('runFeatureE2E 将已完成的断言失败报告为 failed', async t => {
   const fixture = await startFixtureServer();
   t.after(fixture.close);

package/plugins/autobest-delivery/skills/delivery-loop/SKILL.md

@@ -12,6 +12,7 @@ description: 围绕功能 spec 调度相互隔离的实现者、E2E 测试编写
 - 必需的功能 `spec.md`，并定位同目录的 `scope.md`；存在时必须读取 `spec-traceability.json`。
 - 可选的实现者最大回合数，默认 `3`，包含首次实现。
 - 可选的审计固定点，默认为启动时的 `HEAD`。
+- E2E API 模式：`real` 或 `mock`。用户命令明确包含“真实 API”“执行真实API”等表述时取 `real`；明确包含“模拟 API”“mock”等表述时取 `mock`。
 
 只有交付通过且用户明确要求时，才允许提交或推送。
 
@@ -22,13 +23,14 @@ description: 围绕功能 spec 调度相互隔离的实现者、E2E 测试编写
 ## 流程
 
 1. **预检：**阅读 spec、scope、仓库规则、视觉映射、固定审查点和当前工作树。存在 `spec-traceability.json` 时先校验输入哈希、active ID 集合和规格章节；校验失败即阻断，不得启动实现者。在启动实现者前调用 `autobest-delivery` MCP 的 `check_environment` 工具。若环境未就绪，保留工具证据、保持实现者回合数为零并进入 `awaiting-decision`，由用户选择重试、跳过环境验收并记录 waiver，或停止。按契约自行解析可发现的 URL、命令、路由变体、数据准备和定位器，不为这些可发现信息询问用户。
-2. **状态：**将 `delivery/delivery-state.json` 写为 `running`，记录当前阶段、回合数、固定审查点、既有改动和当前产物。每次状态流转都更新该文件。
-3. **实现者：**启动全新的 `$code-craft` 子代理。首回合传入 spec、scope 和已有的 traceability；修复回合只额外传入最新验收失败结果、实现阻断项或代码审计阻断结果。启动时增加实现者回合计数。
-4. **测试编写者：**缺少 `e2e/e2e.feature.mjs` 时，启动全新的 `$e2e-gen-spec` 子代理。旧 `.spec.ts` 不是标准输入，应保持不变。测试编写者必须使用隔离 scene，并在冻结前通过同一运行器 preflight；场景代码、定位器、弹窗、fixture 或等待条件造成的 preflight Blocked 由测试编写者在草稿阶段自行修正并重跑。报告 `ready` 后才冻结 `.mjs`。环境、spec 或实现阻断进入 `awaiting-decision`，由用户选择补充输入、重试、分类、记录 waiver 或停止。
-5. **验收者：**启动全新的 `$e2e-ui-checker` 子代理，并传入 spec、scope、traceability、冻结场景和迭代编号。验收者必须通过隔离 MCP 运行器以 headed 模式执行全部场景，然后只审查 spec 已映射的视觉基准。`passed` 时继续；`failed` 且仍有回合时返回实现者。
-6. **Blocked 决策：**验收者返回 `awaiting-decision` 时，先确认运行器已在阻断 scene 后继续尝试其余独立 scene，再将交付状态写为同名状态，记录该验收代理，保留可见浏览器与证据，并把契约定义的六个决策及其 effect 交给用户。必须明确 `skip` 是接受阻断 scene 的缺失证据并继续审计，不是从异常语句下一行恢复。收到选择后，把决议回传给同一个验收代理，由它调用 `resolve_blocked_run`；验证 `human-decision.json` 后再按其 `effect` 继续。不得自行修改冻结场景、替用户接受风险或把 Blocked 当作终止；只有 `stop` 是终止决策。
-7. **代码审计：**验收通过，或用户 `accept`/`skip` 形成 waiver 后，从固定审查点启动全新的 `$code-audit` 子代理。存在阻断项且仍有回合时返回实现者，修复后重新执行完整验收。没有阻断项时完成交付。
-8. **完成：**标准场景、最新验收、最新代码审计、人工决议、状态与产物必须一致且不存在未授权提交。完整验收通过写入 `passed`；存在 `accept`/`skip` waiver 且审计通过写入 `passed-with-waivers`；只有用户明确选择 `stop` 才写入终止态 `blocked`。Maker 回合耗尽时先进入 `awaiting-decision`，不得替用户停止。
+2. **API 模式确认：**在启动测试编写者或运行任何 E2E 前锁定 `real` 或 `mock`。用户命令已明确模式时直接采用；否则将状态写为 `awaiting-decision`、阶段写为 `api-mode-confirmation`，询问用户选择真实环境 API 还是模拟 API，在得到答复前不得生成场景或运行 preflight。`real` 模式还要确认唯一可解析的目标环境、认证和测试数据；涉及创建、修改、删除、下单、支付或其他外部副作用时，必须再次说明具体操作并取得明确授权。缺少真实环境条件时保持阻断，不得自行改用 mock。
+3. **状态：**将 `delivery/delivery-state.json` 写为 `running`，记录当前阶段、回合数、固定审查点、既有改动、`apiMode`、选择来源、目标环境和当前产物。每次状态流转都更新该文件。
+4. **实现者：**启动全新的 `$code-craft` 子代理。首回合传入 spec、scope 和已有的 traceability；修复回合只额外传入最新验收失败结果、实现阻断项或代码审计阻断结果。启动时增加实现者回合计数。
+5. **测试编写者：**将已确认的 API 模式和目标环境传给全新的 `$e2e-gen-spec` 子代理。缺少 `e2e/e2e.feature.mjs` 时创建；现有冻结场景未声明相同 API 模式时，不得直接复用，启动新的测试修订回合并记录旧、新 SHA-256。旧 `.spec.ts` 不是标准输入，应保持不变。测试编写者必须使用隔离 scene，为每个报告功能组声明并生成代表性 UI 证据截图，并在冻结前使用相同 API 模式通过同一运行器 preflight；场景代码、定位器、截图或等待条件造成的 preflight Blocked 由测试编写者在草稿阶段自行修正并重跑。`mock` 模式可使用经声明的 fixture；`real` 模式禁止任何请求拦截。报告 `ready` 后才冻结 `.mjs`。环境、spec 或实现阻断进入 `awaiting-decision`，由用户选择补充输入、重试、分类、记录 waiver 或停止。
+6. **验收者：**启动全新的 `$e2e-ui-checker` 子代理，并传入 spec、scope、traceability、冻结场景、已确认 API 模式、目标环境和迭代编号。验收者必须把相同 `apiMode` 传给隔离 MCP 运行器，以 headed 模式执行全部场景，核对 API 响应证据，然后只审查 spec 已映射的视觉基准。`passed` 时继续；`failed` 且仍有回合时返回实现者。
+7. **Blocked 决策：**验收者返回 `awaiting-decision` 时，先确认运行器已在阻断 scene 后继续尝试其余独立 scene，再将交付状态写为同名状态，记录该验收代理，保留可见浏览器与证据，并把契约定义的六个决策及其 effect 交给用户。必须明确 `skip` 是接受阻断 scene 的缺失证据并继续审计，不是从异常语句下一行恢复。收到选择后，把决议回传给同一个验收代理，由它调用 `resolve_blocked_run`；验证 `human-decision.json` 后再按其 `effect` 继续。不得自行修改冻结场景、替用户接受风险或把 Blocked 当作终止；只有 `stop` 是终止决策。
+8. **代码审计：**验收通过，或用户 `accept`/`skip` 形成 waiver 后，从固定审查点启动全新的 `$code-audit` 子代理。存在阻断项且仍有回合时返回实现者，修复后重新执行完整验收。没有阻断项时完成交付。
+9. **完成：**标准场景、最终 Runner、最新验收、最新代码审计、人工决议、状态与产物必须一致且不存在未授权提交。最终 Runner 的 `apiMode` 必须与用户确认值一致，所有声明 API 都有响应证据；同时必须实际执行非空检查，并为每个报告功能组生成已声明的截图。只存在 Trace、preflight、空 API 证据或空截图列表不能算完成。完整验收通过写入 `passed`；存在 `accept`/`skip` waiver 且审计通过写入 `passed-with-waivers`；只有用户明确选择 `stop` 才写入终止态 `blocked`。Maker 回合耗尽时先进入 `awaiting-decision`，不得替用户停止。
 
 ## 控制规则
 
@@ -39,5 +41,6 @@ description: 围绕功能 spec 调度相互隔离的实现者、E2E 测试编写
 - 可见 Blocked 会话过期后按 `retry` 处理，不得推断用户已接受或跳过。
 - `resolve_blocked_run` 必须由创建 `blockedSessionId` 的同一个验收代理调用；返回 `not-found` 时记录会话失效并按 `retry` 处理。
 - 任何业务代码修复都会使之前的验收证据失效。
+- API 模式或目标环境变化会使场景、preflight、Runner 和 Checker 证据失效，必须重新生成或修订场景并完整验收。
 - 实现者和验收者将 spec、scope、视觉基准、冻结场景和既有角色产物视为只读。
 - 只管理和清理由本流程或当前角色启动的进程。

package/plugins/autobest-delivery/skills/delivery-loop/references/delivery-contract.md

@@ -34,6 +34,15 @@
 
 JSON 字段名、状态枚举、检查 ID、scene、`reportGroup`、文件路径、命令、代码标识符和协议值保持原始机器格式。浏览器、控制台、网络和工具返回的英文原始错误必须原样保留，但角色应在相邻字段用简体中文解释其含义，不得篡改证据。
 
+## API 数据模式
+
+任何 E2E 场景生成或执行前必须由用户确认 `real` 或 `mock`。用户命令已明确“真实 API”时视为选择 `real`，明确“模拟 API”或 `mock` 时视为选择 `mock`；命令未明确时，编排器进入 `awaiting-decision`，在用户答复前不得让测试编写者自行选择。选择结果、来源和目标环境写入 `delivery-state.json`，并传给测试编写者、Runner 和 Checker。
+
+- `real`：浏览器调用已确认环境的真实 API。场景不得使用 `route()`、`page.route()`、HAR 或 fetch/XHR 替换来伪造响应。无法获得认证、测试数据或端点响应时阻断，不得自动降级到 `mock`。涉及外部写入或不可逆副作用时，需要额外明确授权。
+- `mock`：场景可以通过 `route()` 提供受控 fixture，但必须在 metadata、Runner、Checker 和人读报告中明确标记为模拟证据，不得描述成真实环境联调结果。
+
+新建或修订场景声明 `apiModeSchemaVersion: 1`、`apiMode` 和非空 `apiTargets`。每个 target 包含稳定 `id`、大写 HTTP `method` 和不带 query/hash 的绝对 `pathname`。Runner 调用必须显式传入相同 `apiMode`，记录每个声明端点的响应状态；模式不一致、真实模式发生拦截或任一声明端点没有响应证据时均为 `blocked`。旧场景仅为历史证据兼容；进入新的 Delivery 验收时必须先按已确认模式修订并重新冻结。
+
 ## 运行器接口
 
 任何实现者回合开始前，都必须调用插件 MCP 工具 `check_environment`。就绪结果证明插件自带的 Node、Playwright 和 Chromium 可以启动。不得检查或依赖目标仓库中的 Playwright 包。
@@ -46,6 +55,7 @@ JSON 字段名、状态枚举、检查 ID、scene、`reportGroup`、文件路径
   "scenarioPath": ".scratch/feature/e2e/e2e.feature.mjs",
   "baseUrl": "http://localhost:6060",
   "outputDir": ".scratch/feature/e2e/runs/iteration-01",
+  "apiMode": "real",
   "iteration": 1,
   "timeoutMs": 300000,
   "headed": true,
@@ -87,11 +97,29 @@ JSON 字段名、状态枚举、检查 ID、scene、`reportGroup`、文件路径
 
 ```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: []
 };
 
@@ -111,19 +139,23 @@ export default async function run({
 }
 ```
 
-场景不得使用 `require`、`process`、`__dirname`、包导入或文件系统写入，也不得额外创建 browser、page 或 context。所有能力都由运行器注入。每个 `metadata.scenes` 项必须通过 `scene(id, callback)` 恰好执行一次；运行器为每个 scene 创建独立 page，scene 内未捕获的定位器、弹窗、fixture 或准备步骤错误只阻断该 scene，记录后继续执行后续 scene，并在全部独立 scene 尝试完毕后返回 `blocked`。scene 必须自包含其页面导航、路由 fixture 和必要状态，不能依赖前一个 scene 的 page 或临时状态。
+场景不得使用 `require`、`process`、`__dirname`、包导入或文件系统写入，也不得额外创建 browser、page 或 context。所有能力都由运行器注入。每个 `metadata.scenes` 项必须通过 `scene(id, callback)` 恰好执行一次；运行器为每个 scene 创建独立 page，scene 内未捕获的定位器、弹窗、fixture 或准备步骤错误只阻断该 scene，记录后继续执行后续 scene，并在全部独立 scene 尝试完毕后返回 `blocked`。scene 必须自包含其页面导航、数据准备和必要状态，不能依赖前一个 scene 的 page 或临时状态。只有 `mock` 模式可安装路由 fixture；`real` 模式调用注入的 `route` 或 `page.route` 会被运行器拒绝。
 
 新建或修订场景必须声明 `metadata.reportSchemaVersion: 1`；运行器据此校验通用报告分组字段，未声明版本的历史冻结场景继续兼容。每条原子运行预期通过 `check(definition, assertion)` 记录。新建或修订的检查定义必须同时包含 `reportModule`、`reportGroup`、`reportTitle` 和 `reportMethod`：`reportModule` 是人读的页面或模块名称，`reportGroup` 是当前功能目录内稳定且唯一的功能组 ID，`reportTitle` 是该组在报告中的简短中文标题，`reportMethod` 是该组件或完整功能合并后的中文检查方式。属于同一 UI 组件、同一页面位置或同一完整用户操作流的文案、样式、布局、响应式行为和相关功能检查共用同一组及同一套模块、标题和检查方式；不同组件、独立业务能力、状态转换或风险边界不得为了减少行数而合并。分组只表达产品功能语义，不表达 E2E scene 或执行顺序。可能失败的用户操作和等待应放在所属的 `check` 或 `scene` 内，不能作为未归属的顶层 await。
 
-存在追踪输入的新场景必须声明 `metadata.traceabilitySchemaVersion: 1` 和完整、唯一的 `metadata.requirementIds`。每个 `check` 和 `visualMappings` 项必须包含一个已声明的 `requirementId`；运行器拒绝格式错误、未知编号和完全没有运行或视觉覆盖的声明编号。`reportGroup` 用于报告聚合，不能替代 REQ ID。
+存在追踪输入的新场景必须声明 `metadata.traceabilitySchemaVersion: 1` 和完整、唯一的 `metadata.requirementIds`。每个 `check`、`reportCaptures` 和 `visualMappings` 项必须包含一个已声明的 `requirementId`；运行器拒绝格式错误、未知编号和完全没有运行或视觉覆盖的声明编号。`reportGroup` 用于报告聚合，不能替代 REQ ID。
+
+新建或修订场景必须声明 `metadata.reportCaptureSchemaVersion: 1` 和非空 `metadata.reportCaptures`。每项报告截图包含 `requirementId`、`scene`、简单 PNG 文件名 `capture`、稳定组件 `locator`、`reportModule`、`reportGroup`、`reportTitle` 和 `reportDevice`。每个运行检查的报告功能组至少有一张代表性截图；scope 明确支持且可稳定复现桌面端和移动端时分别保留。场景必须在对应 UI 达到已验证状态后调用 `capture`，最终 Runner 必须记录所有声明截图。缺少声明截图、功能组无截图或出现未声明截图均属于证据链阻断。未声明该 schema 的历史场景继续兼容。
+
+`reportCaptures` 是报告中的运行时 UI 证据，不要求 Figma 基准，也不产生视觉一致性结论。`visualMappings` 是设计基准到实际组件截图的映射，只在 spec 要求视觉比对且本地基准存在时使用。一个截图可以同时承担两种用途，但必须分别满足两份 metadata 契约。
 
-spec 声明的每个视觉对比都必须在 `metadata.visualMappings` 中出现且只出现一次，并包含检查定义、场景、截图文件名、定位器说明、仓库相对路径基准、`reportDevice`（`desktop` 或 `mobile`）以及同样的 `reportModule`、`reportGroup`、`reportTitle`。视觉映射与它证明的运行检查必须复用同一功能组。运行检查与视觉映射必须完整且不重复地划分所有原子 spec。
+spec 声明的每个视觉对比都必须在 `metadata.visualMappings` 中出现且只出现一次，并包含检查定义、场景、截图文件名、定位器说明、仓库相对路径基准、`reportDevice`（`desktop` 或 `mobile`）以及同样的 `reportModule`、`reportGroup`、`reportTitle`。视觉映射与它证明的运行检查必须复用同一功能组。运行检查与视觉映射必须完整且不重复地划分所有原子 spec；报告截图不替代任一原子检查或视觉映射。
 
 旧版直接使用顶层 `page` 的默认函数仍可执行，但它不具备 scene 级故障隔离；测试编写者创建或修订场景时必须使用 `scene()`。
 
 ## 冻结前 Preflight
 
-测试编写者拥有场景草稿，必须在写入 `ready` 和冻结 SHA-256 前通过同一 `run_feature_e2e` 运行器执行 preflight。preflight 使用独立输出目录和 `keepBrowserOpenOnBlock: false`，只验证场景机械可执行性、scene 覆盖、运行检查可达性、fixture、弹窗和定位器，不给出最终视觉结论。
+测试编写者拥有场景草稿，必须在写入 `ready` 和冻结 SHA-256 前通过同一 `run_feature_e2e` 运行器执行 preflight。preflight 使用独立输出目录和 `keepBrowserOpenOnBlock: false`，只验证场景机械可执行性、scene 覆盖、运行检查可达性、fixture、弹窗、定位器以及声明的报告截图全部生成，不给出最终视觉结论。
 
 - `passed` 或证据完整的 `failed` 证明测试代码可以完整执行；业务断言失败留给独立验收者判定。
 - `blocked` 且证据指向场景代码、定位器、弹窗处理、fixture 或等待条件时，测试编写者在冻结前自行修正并重跑，不需要人工 `test_defect` 决议。
@@ -163,6 +195,16 @@ fixture 应提供足以触发目标布局和状态的代表性数据，不需要
   "scenarioPath": ".scratch/feature/e2e/e2e.feature.mjs",
   "scenarioSha256": "64 个小写十六进制字符",
   "metadata": {},
+  "apiMode": "real",
+  "apiCalls": [
+    {
+      "targetId": "product-detail",
+      "method": "GET",
+      "origin": "https://test.example.com",
+      "pathname": "/api/product/detail",
+      "status": 200
+    }
+  ],
   "checks": [],
   "captures": [],
   "tracePath": ".scratch/feature/e2e/runs/iteration-01/trace.zip",
@@ -176,7 +218,7 @@ fixture 应提供足以触发目标布局和状态的代表性数据，不需要
 }
 ```
 
-`passed` 表示所有运行检查均通过。`failed` 表示执行完整结束，但至少一个业务断言失败。`blocked` 表示至少一个 scene、运行器、浏览器、超时、路径策略或证据链阻止了完整证据；使用 `scene()` 时其余独立 scene 会继续执行，全部尝试后再触发人工决议。
+`passed` 表示 API 模式一致、所有声明 API 均有响应证据且全部运行检查通过。`failed` 表示证据完整，但至少一个业务断言失败。`blocked` 表示 API 模式或响应证据、scene、运行器、浏览器、超时、路径策略或其他证据链阻止了完整证据；使用 `scene()` 时其余独立 scene 会继续执行，全部尝试后再触发人工决议。
 
 ## 角色结果
 
@@ -203,6 +245,8 @@ fixture 应提供足以触发目标布局和状态的代表性数据，不需要
   "scenes": [],
   "scenarioSha256": "64 个小写十六进制字符",
   "preflightRunnerResult": ".scratch/feature/e2e/preflight/attempt-01/runner-result.json",
+  "apiMode": "real",
+  "apiCalls": [],
   "preflightChecks": [],
   "blockers": []
 }
@@ -215,6 +259,8 @@ fixture 应提供足以触发目标布局和状态的代表性数据，不需要
   "status": "passed",
   "iteration": 1,
   "runnerResult": ".scratch/feature/e2e/runs/iteration-01/runner-result.json",
+  "apiMode": "real",
+  "apiCalls": [],
   "checks": [],
   "blockers": []
 }
@@ -247,4 +293,4 @@ Excel 只包含一个名为 `自测报告` 的工作表，每行代表一个真
 
 ## 编排状态
 
-`delivery/delivery-state.json` 记录 `status`、`phase`、`makerTurns`、`maxMakerTurns`、`fixedPoint`、`preExistingChanges`、最新产物路径，以及等待决议时的验收代理、`blockedSessionId`、过期时间和 waiver。`status` 可为 `running`、`awaiting-decision`、`passed`、`passed-with-waivers` 或 `blocked`。该文件只记录结论，不得覆盖角色自行拥有的结果。
+`delivery/delivery-state.json` 记录 `status`、`phase`、`makerTurns`、`maxMakerTurns`、`fixedPoint`、`preExistingChanges`、`apiMode`、`apiModeSource`、目标环境、最新产物路径，以及等待决议时的验收代理、`blockedSessionId`、过期时间和 waiver。`status` 可为 `running`、`awaiting-decision`、`passed`、`passed-with-waivers` 或 `blocked`。API 模式尚未确认时使用 `status: "awaiting-decision"` 和 `phase: "api-mode-confirmation"`。该文件只记录结论，不得覆盖角色自行拥有的结果。

package/plugins/autobest-delivery/skills/e2e-gen-spec/SKILL.md

@@ -12,6 +12,7 @@ description: 在首版实现可运行后，为 Autobest Delivery 运行器编写
 - `featureDir/spec.md` 及同目录的 `scope.md`。
 - 仓库规则、路由、fixture、运行事实，以及 spec 已映射的本地视觉基准。
 - 可运行的首版实现。
+- 编排器已确认的 `apiMode`（`real` 或 `mock`）及目标环境；不得由测试编写者自行选择或切换。
 - 仅在修订回合读取 `test_defect` 人工决议及其指向的 Blocked runner/checker 证据。
 
 存在 `featureDir/spec-traceability.json` 时必须读取并校验；它定义本场景允许使用的完整 active REQ ID 集合。
@@ -20,15 +21,15 @@ description: 在首版实现可运行后，为 Autobest Delivery 运行器编写
 
 ## 流程
 
-追踪模式下，每项运行检查和视觉映射都写入所属 `requirementId`，不得创建或重编号。`metadata` 必须声明 `traceabilitySchemaVersion: 1` 和完整、唯一的 `requirementIds`；冻结前确认每个 active ID 至少有一项运行或视觉覆盖。
+追踪模式下，每项运行检查、报告截图和视觉映射都写入所属 `requirementId`，不得创建或重编号。`metadata` 必须声明 `traceabilitySchemaVersion: 1` 和完整、唯一的 `requirementIds`；冻结前确认每个 active ID 至少有一项运行或视觉覆盖。
 
 1. 将每条原子 spec 预期准确映射到一个运行检查或一个视觉映射。为每项分配通用的 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod`，让同一 UI 组件、页面位置或完整用户操作流的文案、样式、布局、响应式行为和相关功能检查在报告中合并；同组的模块、标题和检查方式必须完全一致。不同组件、独立业务能力、状态转换或风险边界保持不同组。分组只表达当前 spec 的功能语义，不得按 scene 或执行顺序分组，不得写死特定页面族词汇或依赖导出器猜测业务语义。覆盖所有必需页面变体、状态转换、空态或错误态、导航结果和响应式变体。
-2. 解析并探测具体 URL、启动行为、受控 API 数据、持久化状态和面向用户的稳定定位器。通过解码后的状态或受控 fixture 确认通配路由变体。
-3. 首次编写只写入 `featureDir/e2e/e2e.feature.mjs`，保持旧 `.spec.ts` 不变。该文件不得包含 import，只导出 `metadata` 和一个默认异步函数，并且只能使用运行器注入的 `scene`、`page`、`expect`、`check`、`route`、`capture`、`artifact`、`baseUrl` 和 `parseUrl`。新建或修订场景在 metadata 中声明 `reportSchemaVersion: 1`，使运行器校验所有检查和视觉映射的通用报告分组字段。每个 `metadata.scenes` 项通过 `scene(id, callback)` 恰好执行一次；每个 scene 自包含页面导航、API fixture 和必要状态。冻结后只有用户通过 `resolve_blocked_run` 明确选择 `test_defect` 才能修订；修订结果必须记录旧、新 SHA-256 和决议证据路径。
+2. 解析并探测具体 URL、启动行为、API 端点、持久化状态和面向用户的稳定定位器。`real` 模式使用已确认环境的真实账号和测试数据，不得调用 `route()`、`page.route()`、HAR 回放或在浏览器内替换 fetch/XHR；无法取得所需真实数据时返回 `environment` 阻断，不得改用 fixture。`mock` 模式才允许使用受控 fixture 确认数据变体。涉及外部写入副作用但未获得明确授权时停止并交回编排器。
+3. 首次编写只写入 `featureDir/e2e/e2e.feature.mjs`，保持旧 `.spec.ts` 不变。该文件不得包含 import，只导出 `metadata` 和一个默认异步函数，并且只能使用运行器注入的 `scene`、`page`、`expect`、`check`、`route`、`capture`、`artifact`、`baseUrl` 和 `parseUrl`。新建或修订场景在 metadata 中声明 `apiModeSchemaVersion: 1`、已确认的 `apiMode`、非空 `apiTargets`、`reportSchemaVersion: 1` 和 `reportCaptureSchemaVersion: 1`。`apiTargets` 列举本次必须真实命中的 HTTP method 和 pathname；不把遥测、配置等无关请求当作业务 API 证据。每个 `metadata.scenes` 项通过 `scene(id, callback)` 恰好执行一次；每个 scene 自包含页面导航、数据准备和必要状态。冻结后只有用户通过 `resolve_blocked_run` 明确选择 `test_defect` 或明确改变 API 模式/环境时才能修订；修订结果必须记录旧、新 SHA-256 和决议证据路径。
 4. 在 metadata 中冻结桌面宽度 `1400px`、移动端宽度 `375px` 和明确稳定的高度。spec 声明的每个组件视觉对比都要映射场景、截图文件名、定位器说明、仓库相对路径基准、`reportDevice`（`desktop` 或 `mobile`）、`reportModule`、`reportGroup`、`reportTitle`，以及完整的验收检查定义。视觉映射与它证明的运行检查复用同一功能组。截图定位器必须与 Figma 基准指向同一语义节点；fixture 只需提供能触发目标布局和状态的代表性数据，不复刻文字长度、业务文案或图片主体，视觉比较边界遵循共享契约。
-5. 通过 `check(definition, assertion)` 记录功能和 DOM 预期；定义中的 `reportModule`、`reportTitle` 和 `reportMethod` 使用简体中文，`reportGroup` 使用稳定的 ASCII ID。把可能失败的点击、选择、弹窗、等待和状态准备放在所属的 `check` 或 `scene` 内，不在两个检查之间留下未归属的可失败 await。`capture` 仅用于已映射的组件根节点，`artifact` 用于结构化 DOM 测量。不得创建其他浏览器、context 或 page，不得直接写文件、使用 Node 全局变量、导入包、截取未映射的整页截图或自行给出视觉结论。
-6. 使用 `node --check` 检查草稿语法后，启动必需服务并调用同一隔离运行器执行冻结前 preflight，输出到 `e2e/preflight/attempt-NN`，使用 `headed: false`、`keepBrowserOpenOnBlock: false`。`blocked` 若源于场景代码、定位器、弹窗处理、fixture 或等待条件，在冻结前自行修正并重跑；不得放宽 spec 断言。环境、spec 或实现阻断按真实类型报告。
-7. 只有 preflight 返回 `passed`，或返回证据完整且所有声明 scene 和预期检查均已到达的 `failed`，才能冻结当前 SHA-256。核对 metadata、检查项覆盖和路径所有权，将最终 preflight 路径、SHA-256、scene 和检查覆盖写入 `e2e/author-result.json` 并标记 `ready`。preflight 只证明测试代码可执行，不替代独立最终验收或视觉审查。
+5. 通过 `check(definition, assertion)` 记录功能和 DOM 预期；定义中的 `reportModule`、`reportTitle` 和 `reportMethod` 使用简体中文，`reportGroup` 使用稳定的 ASCII ID。每个报告功能组在 `metadata.reportCaptures` 中至少声明一张代表性组件截图，并在对应 scene 达到已验证状态后调用 `capture`；scope 明确支持且能稳定复现两种设备时分别保留 desktop/mobile。报告截图用于证明运行状态，不因缺少 Figma 基准而省略，也不参与视觉一致性判定。把可能失败的点击、选择、弹窗、等待和状态准备放在所属的 `check` 或 `scene` 内，不在两个检查之间留下未归属的可失败 await。`artifact` 用于结构化 DOM 测量。不得创建其他浏览器、context 或 page，不得直接写文件、使用 Node 全局变量、导入包、截取与报告功能无关的整页截图或自行给出视觉结论。
+6. 使用 `node --check` 检查草稿语法后，启动必需服务并调用同一隔离运行器执行冻结前 preflight，显式传入编排器确认的 `apiMode`，输出到 `e2e/preflight/attempt-NN`，使用 `headed: false`、`keepBrowserOpenOnBlock: false`。`blocked` 若源于场景代码、定位器、弹窗处理、mock fixture 或等待条件，在冻结前自行修正并重跑；不得放宽 spec 断言。真实环境 API 不可用时按 `environment` 报告，不得通过补 mock 使 preflight 通过。
+7. 只有 preflight 返回 `passed`，或返回证据完整且所有声明 API、scene、预期检查和报告截图均已到达的 `failed`，才能冻结当前 SHA-256。核对 API 模式、`apiCalls`、metadata、检查项覆盖、截图覆盖和路径所有权，将最终 preflight 路径、SHA-256、API 模式、API 响应证据、scene、检查及截图覆盖写入 `e2e/author-result.json` 并标记 `ready`。`reportMethod` 必须如实注明“真实环境 API”或“模拟 API”，不得让两类结果在报告中无法区分。preflight 只证明测试代码可执行，不替代独立最终验收或视觉审查。
 
 ## 阻断条件
 

package/plugins/autobest-delivery/skills/e2e-ui-checker/SKILL.md

@@ -13,17 +13,18 @@ description: 使用 Autobest Delivery MCP 运行器在可见浏览器中独立
 - spec 已映射的本地视觉基准。
 - 迭代编号；单独使用时默认为 `1`。
 - 可发现的开发启动命令和基础 URL。
+- 编排器已确认的 `apiMode` 和目标环境。
 
 ## 流程
 
 存在 `spec-traceability.json` 时，先确认冻结场景声明的 REQ ID 与 active 集合完全一致。合并 Runner 和视觉结果时原样保留每项 `requirementId`，逐个汇总 passed、failed 或 blocked；未知编号、缺失编号或 active 需求无证据都属于证据链阻断，不能判为通过。
 
-1. 建立原子 spec 检查清单，确认冻结运行检查和 metadata 视觉映射完整且不重复地划分了全部检查项。`reportSchemaVersion: 1` 的场景须核对每个运行检查包含 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod`，同组字段一致且表达真实组件或完整功能，而不是 E2E scene；同时核对视觉映射的同组字段和 `reportDevice` 正确区分桌面端与移动端。历史场景没有报告 schema 时不据此阻断。
+1. 建立原子 spec 检查清单，确认冻结场景的 `apiMode` 与编排器确认值一致，`apiTargets` 覆盖本次业务 API；不一致或缺失时不得运行。确认冻结运行检查和 metadata 视觉映射完整且不重复地划分了全部检查项。`reportSchemaVersion: 1` 的场景须核对每个运行检查包含 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod`，同组字段一致且表达真实组件或完整功能，而不是 E2E scene；同时核对视觉映射的同组字段和 `reportDevice` 正确区分桌面端与移动端。`reportCaptureSchemaVersion: 1` 的场景还须核对 `metadata.reportCaptures`：每个报告功能组至少有一张已声明的代表性 UI 截图，scene、locator、设备及 REQ 映射有效。历史场景没有对应 schema 时不据此阻断。
 2. 调用 `autobest-delivery` MCP 的 `check_environment` 工具并传入 `headed: true`。环境未就绪时，以返回的版本和错误证据形成 `tool` 阻断；不得降级使用通用 Playwright MCP 或目标仓库依赖。
 3. 只解析并启动仓库已声明且本次必需的开发服务，记录其 PID，并确认基础 URL。复用冻结的 `1400px` 和 `375px` 视口及受控路由或 API 状态。
-4. 调用 `run_feature_e2e`，传入工作区绝对路径、标准场景路径、基础 URL、`featureDir/e2e/runs/iteration-NN`、迭代编号、有界超时、`headed: true` 和 `keepBrowserOpenOnBlock: true`。将运行器返回结果视为不可修改的证据。
-5. 运行器返回 `blocked` 时，确认 `blockedSessionId`、过期时间、当前页面和 Trace，并核对每个独立 scene 的已执行检查、缺失检查和 blocker；scene 级阻断不应阻止其余独立 scene 留下证据。验收结果写为 `awaiting-decision` 并交回编排器；保留本验收代理供决议 follow-up 使用。编排器回传用户选择后，由同一个验收代理调用 `resolve_blocked_run` 并复读决议产物。明确说明 `skip` 只接受阻断 scene 的缺失证据，不会从异常语句恢复执行。不得自行修改测试、选择决议或给出验收结论。返回 `failed` 时取得功能失败项。运行器返回 `passed` 或 `failed` 时，检查每个已映射组件的实际截图、基准截图和已记录的叶子 DOM 测量。只比较映射指定的组件、状态和设备，并按共享契约执行语义视觉比较：忽略业务文字的内容和长度及业务图片主体，检查结构、几何、间距、对齐、响应式排列和视觉样式。文案正确性由运行检查判定。默认 `1px` 几何容差仅用于视口、语义节点和组件状态一致的可比元素；捕获边界不一致应判为视觉映射缺陷，不得判为实现缺陷。
-6. 合并运行检查和视觉检查，确保每条原子 spec 只出现一次。证据完整但存在失败项时为 `failed`；全部通过时为 `passed`；缺失任一必要证据时为 `awaiting-decision`。
+4. 调用 `run_feature_e2e`，传入工作区绝对路径、标准场景路径、基础 URL、`featureDir/e2e/runs/iteration-NN`、已确认的 `apiMode`、迭代编号、有界超时、`headed: true` 和 `keepBrowserOpenOnBlock: true`。将运行器返回结果视为不可修改的证据。
+5. 运行器返回 `blocked` 时，确认 `blockedSessionId`、过期时间、当前页面和 Trace，并核对每个独立 scene 的已执行检查、缺失检查和 blocker；scene 级阻断不应阻止其余独立 scene 留下证据。验收结果写为 `awaiting-decision` 并交回编排器；保留本验收代理供决议 follow-up 使用。编排器回传用户选择后，由同一个验收代理调用 `resolve_blocked_run` 并复读决议产物。明确说明 `skip` 只接受阻断 scene 的缺失证据，不会从异常语句恢复执行。不得自行修改测试、选择决议或给出验收结论。返回 `failed` 时取得功能失败项。运行器返回 `passed` 或 `failed` 时，先确认每个 `metadata.reportCaptures` 声明的截图都真实存在于本轮 Runner 结果中；缺少任一报告截图均为证据链阻断并进入 `awaiting-decision`。报告截图只证明对应运行状态，不作为视觉一致性结论。随后检查每个已映射组件的实际截图、基准截图和已记录的叶子 DOM 测量；只有 `visualMappings` 才执行视觉比较。只比较映射指定的组件、状态和设备，并按共享契约执行语义视觉比较：忽略业务文字的内容和长度及业务图片主体，检查结构、几何、间距、对齐、响应式排列和视觉样式。文案正确性由运行检查判定。默认 `1px` 几何容差仅用于视口、语义节点和组件状态一致的可比元素；捕获边界不一致应判为视觉映射缺陷，不得判为实现缺陷。
+6. 核对 Runner 的 `apiMode` 和每个 `apiTargets` 对应的 `apiCalls`。`real` 模式出现请求拦截、缺少真实响应证据或环境不可用时为 `awaiting-decision`，不得改用 mock 重跑；`mock` 模式必须在报告中明确标为模拟。合并运行检查和视觉检查，确保每条原子 spec 只出现一次。证据完整但存在失败项时为 `failed`；全部通过时为 `passed`；缺失任一必要证据时为 `awaiting-decision`。
 7. 写入并复读 `checker/checker-result.json` 和 `.md`，确保两份报告结论一致，且所有证据路径均为仓库相对路径。合并 Runner 检查时原样保留 `reportModule`、`reportGroup`、`reportTitle` 和 `reportMethod`。角色撰写的检查说明、期望、实际结果和全部 Markdown 内容必须使用简体中文；Markdown 使用共享契约规定的中文标题、中文表头和中文展示状态。JSON 的字段名、机器状态、ID、scene 和路径保持协议格式，英文原始错误原样引用并附中文解释。
 8. 普通完成时关闭浏览器资源；存在 `blockedSessionId` 时保留浏览器和当前验收者启动的开发服务，直到编排器完成决议。决议后只清理由本轮启动的资源；会话过期也必须清理。
 

package/plugins/autobest-delivery/skills/export-report/SKILL.md

@@ -9,7 +9,7 @@ description: 从已完成或已阻断的 Autobest Delivery Maker、Runner 和 Ch
 
 ## 输入
 
-- 用户指定的功能目录，其中包含 `spec.md`、`checker/checker-result.json` 和对应 Runner 结果。
+- 用户指定的功能目录，其中包含 `spec.md`、`checker/checker-result.json` 和对应 Runner 结果。`spec.md` 可以是旧版 `## 用户故事` 结构，也可以是按 `## REQ-<SCOPE>-<序号>` 分节的新追踪结构。
 - 可选的报告输出路径；必须位于功能目录内。默认写入 `featureDir/delivery-report.xlsx`。
 
 ## 执行
@@ -27,13 +27,13 @@ node <plugin-root>/scripts/export-delivery-report.mjs <feature-dir> \
   [--grouping <feature-dir>/report/report-groups.json]
 ```
 
-4. 复读脚本的 JSON 输出，向用户报告文件路径、Runner iteration、Checker/Runner 状态、功能行数、状态计数、唯一嵌入截图数、截图放置数和分组来源。
+4. 复读脚本的 JSON 输出，向用户报告文件路径、Runner iteration、Checker/Runner 状态、API 模式、功能行数、状态计数、唯一嵌入截图数、截图放置数和分组来源。
 
-报告固定使用插件资产 `assets/delivery-report-template.xlsx`，且只能生成一个名为 `自测报告` 的工作表。列固定为：页面/模块、自测点、自测方式、通过、截图1（桌面端）、截图2（移动端）。不得生成原子检查明细 Sheet，不得在可见单元格中输出 story ID、scene 名、历史场景或其他执行结构。
+报告固定使用插件资产 `assets/delivery-report-template.xlsx`，且只能生成一个名为 `自测报告` 的工作表。列固定为：页面/模块、自测点、自测方式、通过、截图1（桌面端）、截图2（移动端）。导出器根据 Runner 的 `apiMode` 自动在“自测方式”中标注“真实环境 API”或“模拟 API”；历史 Runner 没有 API 模式时不推断。不得生成原子检查明细 Sheet，不得在可见单元格中输出 story ID、scene 名、历史场景或其他执行结构。
 
 每一行代表一个用户能识别的真实 UI 组件或完整业务功能。属于同一组件、同一页面位置或同一完整操作流的文案、样式、布局、响应式行为和相关功能检查必须合并到一行；仅仅修改了文字、颜色、间距或设备变体，不得拆成多行。不同组件、独立业务能力、状态转换或风险边界不得为了减少行数而强行合并。分组依据是 `spec.md` 描述的产品语义，不是 E2E scene、检查数量、story 顺序或截图文件名。
 
-新证据由测试编写者在每个运行检查中提供 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod`，并在视觉映射中提供同组字段和 `reportDevice`。同一 `reportGroup` 的模块、标题和自测方式必须一致。组内状态按 `Blocked > 不通过 > 通过` 取最严重值；桌面端和移动端代表截图放在同一行，每种设备最多一张。相同截图二进制只嵌入一次。
+新证据由测试编写者在每个运行检查中提供 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod`，其中 `reportMethod` 必须明确说明使用“真实环境 API”或“模拟 API”，并与 Runner 的 `apiMode` 一致；不得把 mock 报告描述为真实联调。通过 `metadata.reportCaptures` 提供同组的运行时代表截图和 `reportDevice`。`reportCaptures` 不要求 Figma 基准，只用于报告展示已验证的 UI 状态；`visualMappings` 只用于存在本地设计基准的视觉一致性验收，两者不得混为一种结论。同一 `reportGroup` 的模块、标题和自测方式必须一致。组内状态按 `Blocked > 不通过 > 通过` 取最严重值；桌面端和移动端代表截图放在同一行，每种设备最多一张。相同截图二进制只嵌入一次。
 
 ## 历史证据
 
@@ -62,7 +62,7 @@ node <plugin-root>/scripts/export-delivery-report.mjs <feature-dir> \
 }
 ```
 
-清单必须与当前 spec、iteration 和冻结场景哈希完全一致，并让每个 story 恰好出现一次。截图字段只能指向 Runner 已记录且能唯一匹配的截图。脚本负责验证清单和生成工作簿，不对缺失的业务语义进行自动猜测。
+清单必须与当前 spec、iteration 和冻结场景哈希完全一致，并让每个旧版 story 或新版运行检查恰好出现一次。截图字段只能指向 Runner 已记录且能唯一匹配的截图。脚本负责验证清单和生成工作簿，不对缺失的业务语义进行自动猜测。历史 Runner 没有截图时仍允许导出无截图报告；新建或修订的 Delivery 场景应由运行器确保报告截图完整。
 
 ## 完成条件