npm - @autobest-ui/agent - Versions diffs - 1.0.8 → 1.0.11 - Mend

@autobest-ui/agent 1.0.8 → 1.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

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

@@ -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/mcp-smoke.test.mjs CHANGED Viewed

@@ -35,6 +35,21 @@ test('stdio MCP 能暴露环境信息并执行功能场景', async t => {
   await client.connect(transport);
   t.after(() => client.close());
+  const { tools } = await client.listTools();
+  const toolNames = tools.map(tool => tool.name);
+  for (const toolName of [
+    'start_fast_check',
+    'fast_browser_snapshot',
+    'fast_browser_action',
+    'mock_fast_check_route',
+    'fast_browser_check',
+    'capture_fast_check',
+    'finish_fast_check',
+    'abort_fast_check'
+  ]) {
+    assert.ok(toolNames.includes(toolName), `缺少 MCP 工具 ${toolName}`);
+  }
   const environment = await client.callTool({
     name: 'check_environment',
     arguments: {}
@@ -57,6 +72,62 @@ test('stdio MCP 能暴露环境信息并执行功能场景', async t => {
   assert.equal(execution.structuredContent.status, 'passed');
   assert.equal(execution.structuredContent.checks.length, 2);
+  const fastStarted = await client.callTool({
+    name: 'start_fast_check',
+    arguments: {
+      workspaceRoot,
+      baseUrl: fixture.baseUrl,
+      outputDir: 'feature/fast-check/runs/iteration-01'
+    }
+  });
+  const fastSessionId = fastStarted.structuredContent.sessionId;
+  const fastSnapshot = await client.callTool({
+    name: 'fast_browser_snapshot',
+    arguments: { sessionId: fastSessionId }
+  });
+  assert.match(fastSnapshot.structuredContent.snapshot, /显示结果/);
+  await client.callTool({
+    name: 'fast_browser_action',
+    arguments: { sessionId: fastSessionId, action: 'click', locator: '#reveal' }
+  });
+  const fastCheck = await client.callTool({
+    name: 'fast_browser_check',
+    arguments: {
+      sessionId: fastSessionId,
+      id: 'story-01',
+      reportModule: '交付测试页',
+      reportGroup: 'reveal-result',
+      reportTitle: '结果展示',
+      reportMethod: '通过交互式 Playwright 点击按钮并检查结果文案。',
+      specSnippet: '点击按钮后显示结果。',
+      expect: '结果文案可见',
+      checkType: 'text',
+      locator: '#result',
+      expected: '运行器运行正常'
+    }
+  });
+  assert.equal(fastCheck.structuredContent.check.isPass, true);
+  await client.callTool({
+    name: 'capture_fast_check',
+    arguments: {
+      sessionId: fastSessionId,
+      reportModule: '交付测试页',
+      reportGroup: 'reveal-result',
+      reportTitle: '结果展示',
+      reportMethod: '通过交互式 Playwright 点击按钮并检查结果文案。',
+      capture: 'result-desktop.png',
+      locator: 'main',
+      reportDevice: 'desktop'
+    }
+  });
+  const fastFinished = await client.callTool({
+    name: 'finish_fast_check',
+    arguments: { sessionId: fastSessionId }
+  });
+  assert.equal(fastFinished.structuredContent.status, 'passed');
+  assert.equal(fastFinished.structuredContent.scenarioPath, null);
   const rejectedPath = await client.callTool({
     name: 'run_feature_e2e',
     arguments: {

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

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { createHash } from 'node:crypto';
-import { mkdtemp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
@@ -164,6 +164,112 @@ 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('交互式快速自测结果无需 E2E 场景和 Checker 即可导出报告', async t => {
+  const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), 'autobest-fast-report-'));
+  t.after(() => rm(workspaceRoot, { recursive: true, force: true }));
+  await mkdir(path.join(workspaceRoot, '.git'));
+  const featureDir = path.join(workspaceRoot, '.scratch', 'fast-feature');
+  const runDir = path.join(featureDir, 'fast-check', 'runs', 'iteration-01');
+  const capturePath = path.join(runDir, 'captures', 'heading-desktop.png');
+  await mkdir(path.dirname(capturePath), { recursive: true });
+  await writeFile(capturePath, png);
+  await writeFile(
+    path.join(featureDir, 'spec.md'),
+    '# 页面规格\n\n## 用户故事\n\n1. 页面显示标题。\n'
+  );
+  const relativeCapture = path.relative(workspaceRoot, capturePath).split(path.sep).join('/');
+  await writeFile(
+    path.join(runDir, 'fast-check-result.json'),
+    JSON.stringify({
+      evidenceSchemaVersion: 1,
+      evidenceSource: 'interactive-playwright',
+      status: 'passed',
+      iteration: 1,
+      scenarioPath: null,
+      scenarioSha256: null,
+      apiMode: 'none',
+      metadata: {
+        apiMode: 'none',
+        reportCaptures: [{
+          capture: 'heading-desktop.png',
+          locator: 'h1',
+          reportModule: '示例页面',
+          reportGroup: 'page-heading',
+          reportTitle: '页面标题',
+          reportMethod: '通过交互式 Playwright 检查标题并截图。',
+          reportDevice: 'desktop'
+        }],
+        visualMappings: []
+      },
+      checks: [{
+        id: 'story-01',
+        specSnippet: '页面显示标题。',
+        reportModule: '示例页面',
+        reportGroup: 'page-heading',
+        reportTitle: '页面标题',
+        reportMethod: '通过交互式 Playwright 检查标题并截图。',
+        expect: '标题可见',
+        actual: '标题可见',
+        isPass: true
+      }],
+      captures: [relativeCapture]
+    })
+  );
+  const result = await exportDeliveryReport({ featureDir, workspaceRoot, templatePath });
+  assert.equal(result.evidenceSource, 'interactive-playwright');
+  assert.equal(result.checkerStatus, null);
+  assert.equal(result.runnerStatus, null);
+  assert.equal(result.fastCheckStatus, 'passed');
+  assert.equal(result.apiMode, 'none');
+  assert.equal(result.rows, 1);
+  assert.equal(result.embeddedScreenshots, 1);
+  const workbook = new ExcelJS.Workbook();
+  await workbook.xlsx.readFile(result.outputPath);
+  const worksheet = workbook.getWorksheet('自测报告');
+  assert.equal(worksheet.getCell('B2').value, '页面标题');
+  assert.match(worksheet.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 CHANGED Viewed

@@ -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/code-audit/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: code-audit
-description: 在独立验收者通过后，从固定审查点检查交付改动是否符合仓库规范和功能规格。
+description: 在标准独立验收或快速交互式自测通过后，从固定审查点检查交付改动是否符合仓库规范和功能规格。
 ---
 # 代码审计
@@ -11,12 +11,12 @@ description: 在独立验收者通过后，从固定审查点检查交付改动
 - 可解析的固定审查点。
 - 功能规格及同目录的 scope。
-- 同目录存在时的 `spec-traceability.json`，以及 Maker、Checker 的逐项需求结果。
+- 同目录存在时的 `spec-traceability.json`。标准模式读取 Maker、Checker 的逐项需求结果；快速模式读取 `delivery-state.json` 和最新 `fast-check-result.json`。
 - 默认审查 `worktree`，也可审查用户明确指定的 `committed` 改动。
 ## 流程
-追踪模式下，Spec 审查轴必须逐个核对 active REQ ID 是否同时出现在 spec、Maker 结论、相关代码和 Checker 证据中；不得用整体通过代替单项覆盖，也不得接受未知或重编号的需求。
+追踪模式下，Spec 审查轴必须逐个核对 active REQ ID 是否同时出现在 spec、实现结论、相关代码和 Checker 或快速自测证据中；不得用整体通过代替单项覆盖，也不得接受未知或重编号的需求。快速模式证据只能称为实现者交互式自测，不能表述成独立 Checker 验收。
 1. 只冻结一次审查范围。审查工作树时纳入与任务相关的暂存、未暂存及新增文件，保留并排除无关的既有改动。
 2. 阅读适用的仓库规则、spec、scope、提交列表、改动文件和完整 diff。

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

@@ -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、视觉基准、冻结场景和既有角色产物视为只读。
 - 只管理和清理由本流程或当前角色启动的进程。