@autobest-ui/agent 1.0.7 → 1.0.10

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 场景应由运行器确保报告截图完整。
 
 ## 完成条件
 

package/skills/README.md

@@ -18,7 +18,7 @@ npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync common
 - `review-from-docs`
 - `ui-prd-scope`
 
-其中 `ui-prd-scope` 使用 `REQ-<页面或Scope简称>-<三位序号>` 分配稳定需求 ID；`review-from-docs` 以该编号记录质询结论；`make-spec` 生成逐项可验收的 `spec.md` 和机器可校验的映射。后续交付角色只引用编号，不重新编号。
+其中 `ui-prd-scope` 使用 `REQ-<页面或Scope简称>-<三位序号>` 分配稳定需求 ID；`review-from-docs` 为每个 REQ 建立决策树，逐轮询问当前完整 frontier 并记录用户确认的结论；`make-spec` 只从已完成的 review 生成逐项可验收的 `spec.md` 和机器可校验的映射。后续交付角色只引用编号，不重新编号。
 
 ## React
 

package/skills/common/make-spec/SKILL.md

@@ -13,7 +13,7 @@ description: 根据带稳定 REQ 编号的页面 scope 和 review-result 生成
 - `review/review-result.json`，以及它引用的 Figma 和证据。
 - 可选的既有 `spec.md` 与 `spec-traceability.json`；刷新时保留稳定编号和仍适用的验收边界。
 
-Manifest 必须声明 `traceabilitySchemaVersion: 1`。任何 `active` 需求缺少质询记录、仍为 `unresolved`，或 scope、review 的编号和状态不一致时停止，返回需要继续 `$review-from-docs` 或回写 scope 的具体编号。
+Manifest 必须声明 `traceabilitySchemaVersion: 1`，Review 必须使用 Schema v2、`sessionStatus: complete` 且已经由用户确认。任何 `active` 需求缺少质询记录、仍为 `unresolved`，或 scope、review 的编号和状态不一致时停止，返回需要继续 `$review-from-docs` 或回写 scope 的具体编号。
 
 ## 生成
 

package/skills/common/make-spec/scripts/validate-spec-traceability.mjs

@@ -56,6 +56,10 @@ if (trace) {
   if (manifest && manifest.traceabilitySchemaVersion !== 1) {
     fail('Manifest 未启用 traceabilitySchemaVersion: 1');
   }
+  if (review && review.schemaVersion !== 2) fail('Review schemaVersion 必须为 2');
+  if (review && (review.sessionStatus !== 'complete' || review.userConfirmed !== true)) {
+    fail('Review 必须完成多轮质询并由用户确认');
+  }
 
   for (const [label, filePath, expected] of [
     ['Scope', scopePath, trace.scope?.scopeSha256],