@autobest-ui/agent 1.0.8 → 1.0.11

package/bin/sync-assets.test.mjs

@@ -23,6 +23,7 @@ test("installs common skills into the user-level skills directory", async () =>
       "code-pr-submit",
       "figma-ui-capture",
       "make-spec",
+      "repo-setup",
       "review-from-docs",
       "ui-prd-scope",
     ]);
@@ -33,6 +34,7 @@ test("installs common skills into the user-level skills directory", async () =>
     await access(
       path.join(result.targetRoot, "make-spec", "scripts", "validate-spec-traceability.mjs")
     );
+    await access(path.join(result.targetRoot, "repo-setup", "SKILL.md"));
     await access(
       path.join(result.targetRoot, "review-from-docs", "references", "review-result-schema.md")
     );

package/mcp/code-mcp-pr/README.md

@@ -9,7 +9,7 @@ export AZURE_DEVOPS_PAT="your-personal-access-token"
 export DINGDING_ALERT_TOKEN="your-dingtalk-robot-access-token"
 ```
 
-`AZURE_DEVOPS_PAT` 是所有工具访问 Azure DevOps 的必需配置。`DINGDING_ALERT_TOKEN` 仅在 `code-mcp-pr` 同时收到钉钉 markdown 标题和正文时使用。两个 token 都不会作为 MCP 工具参数接收。
+`AZURE_DEVOPS_PAT` 是访问 Azure DevOps 的工具所需配置。`DINGDING_ALERT_TOKEN` 在 `code-mcp-pr` 创建新 PR 后发送通知，或 `send_pr_dingtalk` 为已有 PR 补发通知时使用。两个 token 都不会作为 MCP 工具参数接收。
 
 ## 启动
 
@@ -30,7 +30,8 @@ Codex 配置示例见 [config.toml.example](config.toml.example)。
 
 ## 工具
 
-- `code-mcp-pr`：`businessTargetBranch` 作为 ADO `sourceRefName`，`businessSourceBranch` 作为 `targetRefName`。仅在 PR 创建成功且两个 markdown 字段都有值时发送钉钉通知。
+- `code-mcp-pr`：`businessTargetBranch` 作为 ADO `sourceRefName`，`businessSourceBranch` 作为 `targetRefName`。目标为 `main/master` 时要求显式传入 `targetBranchConfirmed=true`。创建前检查相同方向的 active PR；已存在时返回 `alreadyExists=true` 和 `prWebUrl`，不重复发送钉钉。仅在新 PR 创建成功且两个 markdown 字段都有值时发送钉钉通知。
+- `send_pr_dingtalk`：在用户确认后，为一个已存在的 PR 链接补发钉钉 markdown 通知；不会创建或修改 PR。
 - `get_repo_default_branch`：读取仓库默认分支。
 - `guess_parent_branch`：以默认分支和 ADO merge-base 信息进行启发式推测。
 - `get_branch_diff`：读取 source 相对 target 的文件列表和受限 diff 片段。

package/mcp/code-mcp-pr/azure-devops.js

@@ -28,6 +28,7 @@ const DIFF_FILE_CONCURRENCY = 5;
  * @property {string} prTitle
  * @property {string=} prDescription
  * @property {string[]=} reviewers
+ * @property {boolean=} targetBranchConfirmed
  * @property {string=} dingtalkMarkdownTitle
  * @property {string=} dingtalkMarkdownContent
  */
@@ -35,6 +36,9 @@ const DIFF_FILE_CONCURRENCY = 5;
 /**
  * @typedef {object} CreatePullRequestResult
  * @property {boolean} success
+ * @property {boolean} created
+ * @property {boolean} alreadyExists
+ * @property {boolean} confirmationRequired
  * @property {string|null} prId
  * @property {string|null} prWebUrl
  * @property {JsonObject} adoApiPayload
@@ -43,6 +47,13 @@ const DIFF_FILE_CONCURRENCY = 5;
  * @property {string|null} errorMsg
  */
 
+/**
+ * @typedef {object} SendPullRequestDingtalkInput
+ * @property {string} prWebUrl
+ * @property {string} dingtalkMarkdownTitle
+ * @property {string} dingtalkMarkdownContent
+ */
+
 /**
  * @typedef {object} DefaultBranchResult
  * @property {boolean} success
@@ -203,6 +214,37 @@ function pullRequestWebUrl(input, responseBody, prId) {
   return `https://dev.azure.com/${encodeURIComponent(input.orgName)}/${encodeURIComponent(input.projectName)}/_git/${encodeURIComponent(repositoryName)}/pullrequest/${encodeURIComponent(prId)}`;
 }
 
+function activePullRequestsUrl(input, sourceRefName, targetRefName) {
+  const query = new URLSearchParams({
+    'searchCriteria.status': 'active',
+    'searchCriteria.sourceRefName': sourceRefName,
+    'searchCriteria.targetRefName': targetRefName,
+    '$top': '1'
+  });
+  return `${repositoryRoot(input)}/pullrequests?${query.toString()}`;
+}
+
+async function findActivePullRequest(input, sourceRefName, targetRefName, pat) {
+  const result = await adoRequest(activePullRequestsUrl(input, sourceRefName, targetRefName), pat);
+  if (!result.ok) return { pullRequest: null, errorMsg: result.errorMsg };
+  const body = asObject(result.data);
+  const pullRequests = Array.isArray(body.value) ? body.value : [];
+  return { pullRequest: asObject(pullRequests[0]), errorMsg: null };
+}
+
+function existingPullRequestResult(baseResult, input, pullRequest) {
+  const rawPrId = pullRequest.pullRequestId;
+  if (rawPrId === undefined || rawPrId === null) return null;
+  const prId = String(rawPrId);
+  return {
+    ...baseResult,
+    success: true,
+    alreadyExists: true,
+    prId,
+    prWebUrl: pullRequestWebUrl(input, pullRequest, prId)
+  };
+}
+
 async function sendDingtalkMarkdown(title, content) {
   const token = process.env.DINGDING_ALERT_TOKEN?.trim();
   if (!token) {
@@ -239,6 +281,9 @@ export async function createPullRequest(input) {
   };
   const baseResult = {
     success: false,
+    created: false,
+    alreadyExists: false,
+    confirmationRequired: false,
     prId: null,
     prWebUrl: null,
     adoApiPayload,
@@ -251,14 +296,35 @@ export async function createPullRequest(input) {
     return { ...baseResult, errorMsg: 'businessTargetBranch 不能等于 businessSourceBranch' };
   }
 
+  const targetBranch = branchVersion(targetRefName).toLowerCase();
+  if ((targetBranch === 'main' || targetBranch === 'master') && input.targetBranchConfirmed !== true) {
+    return {
+      ...baseResult,
+      confirmationRequired: true,
+      errorMsg: `目标分支 ${targetBranch} 是主分支，需要用户明确确认后才能创建PR`
+    };
+  }
+
   const pat = requirePat();
   if (!pat) return { ...baseResult, errorMsg: missingPatError() };
 
+  const existingLookup = await findActivePullRequest(input, sourceRefName, targetRefName, pat);
+  if (existingLookup.errorMsg) return { ...baseResult, errorMsg: existingLookup.errorMsg };
+  const existingResult = existingPullRequestResult(baseResult, input, existingLookup.pullRequest);
+  if (existingResult) return existingResult;
+
   const createResult = await adoRequest(`${repositoryRoot(input)}/pullrequests`, pat, {
     method: 'POST',
     body: JSON.stringify(adoApiPayload)
   });
-  if (!createResult.ok) return { ...baseResult, errorMsg: createResult.errorMsg };
+  if (!createResult.ok) {
+    if (createResult.status === 409) {
+      const raceLookup = await findActivePullRequest(input, sourceRefName, targetRefName, pat);
+      const racedExistingResult = existingPullRequestResult(baseResult, input, raceLookup.pullRequest);
+      if (racedExistingResult) return racedExistingResult;
+    }
+    return { ...baseResult, errorMsg: createResult.errorMsg };
+  }
 
   const response = asObject(createResult.data);
   const rawPrId = response.pullRequestId;
@@ -268,7 +334,7 @@ export async function createPullRequest(input) {
 
   const prId = String(rawPrId);
   const prWebUrl = pullRequestWebUrl(input, response, prId);
-  const successResult = { ...baseResult, success: true, prId, prWebUrl };
+  const successResult = { ...baseResult, success: true, created: true, prId, prWebUrl };
   const title = input.dingtalkMarkdownTitle;
   const content = input.dingtalkMarkdownContent;
   if (!title?.trim() || !content?.trim()) return successResult;
@@ -282,6 +348,19 @@ export async function createPullRequest(input) {
   };
 }
 
+/** @param {SendPullRequestDingtalkInput} input */
+export async function sendPullRequestDingtalk(input) {
+  const renderedContent = input.dingtalkMarkdownContent.replaceAll('{{PR_WEB_URL}}', input.prWebUrl);
+  const dingtalk = await sendDingtalkMarkdown(input.dingtalkMarkdownTitle, renderedContent);
+  return {
+    success: dingtalk.success,
+    prWebUrl: input.prWebUrl,
+    dingtalkSendSuccess: dingtalk.success,
+    dingtalkResponse: dingtalk.response,
+    errorMsg: dingtalk.success ? null : boundedJson(dingtalk.response) || '钉钉通知发送失败'
+  };
+}
+
 /** @param {RepositoryInput} input @returns {Promise<DefaultBranchResult>} */
 export async function getRepoDefaultBranch(input) {
   const pat = requirePat();

package/mcp/code-mcp-pr/index.js

@@ -8,7 +8,8 @@ import {
   getBranchDiff,
   getRepoDefaultBranch,
   guessParentBranch,
-  readFileAtRef
+  readFileAtRef,
+  sendPullRequestDingtalk
 } from './azure-devops.js';
 
 const server = new McpServer(
@@ -56,6 +57,10 @@ registerJsonTool(
       prTitle: z.string().min(1).describe('PR标题'),
       prDescription: z.string().optional().describe('PR描述，可选，条目化变更详情'),
       reviewers: z.array(z.string().min(1)).optional().describe('评审人ID列表，可选'),
+      targetBranchConfirmed: z
+        .boolean()
+        .optional()
+        .describe('目标分支为main或master时，必须在用户明确二次确认后传true'),
       dingtalkMarkdownTitle: z.string().optional().describe('钉钉通知markdown标题，可选；不传则不发送钉钉'),
       dingtalkMarkdownContent: z
         .string()
@@ -67,6 +72,9 @@ registerJsonTool(
   createPullRequest,
   errorMsg => ({
     success: false,
+    created: false,
+    alreadyExists: false,
+    confirmationRequired: false,
     prId: null,
     prWebUrl: null,
     adoApiPayload: {},
@@ -76,6 +84,31 @@ registerJsonTool(
   })
 );
 
+registerJsonTool(
+  'send_pr_dingtalk',
+  {
+    title: '发送已有 PR 钉钉通知',
+    description: '为已确认的 PR 链接发送钉钉 markdown 通知；不会创建或修改 PR。',
+    inputSchema: {
+      prWebUrl: z.string().url().describe('已存在 PR 的可访问 Web 链接'),
+      dingtalkMarkdownTitle: z.string().min(1).describe('钉钉通知 markdown 标题'),
+      dingtalkMarkdownContent: z
+        .string()
+        .min(1)
+        .describe('钉钉通知 markdown 正文；内部会替换{{PR_WEB_URL}}占位符为 PR 链接')
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+  },
+  sendPullRequestDingtalk,
+  errorMsg => ({
+    success: false,
+    prWebUrl: null,
+    dingtalkSendSuccess: false,
+    dingtalkResponse: null,
+    errorMsg
+  })
+);
+
 registerJsonTool(
   'get_repo_default_branch',
   {

package/mcp/code-mcp-pr/index.test.js

@@ -12,7 +12,8 @@ import {
   getRepoDefaultBranch,
   guessParentBranch,
   normalizeBranchRef,
-  readFileAtRef
+  readFileAtRef,
+  sendPullRequestDingtalk
 } from './azure-devops.js';
 
 const directory = path.dirname(fileURLToPath(import.meta.url));
@@ -57,6 +58,7 @@ test('creates the reverse PR with the required branch direction and sends render
   globalThis.fetch = async (url, options) => {
     calls.push({ url: String(url), options });
     if (String(url).startsWith('https://dev.azure.com/')) {
+      if (!options?.method || options.method === 'GET') return jsonResponse({ value: [] });
       return jsonResponse({
         pullRequestId: 42,
         repository: { name: 'web' },
@@ -75,12 +77,15 @@ test('creates the reverse PR with the required branch direction and sends render
         businessTargetBranch: 'release/with-change',
         businessSourceBranch: 'main',
         prTitle: 'Reverse PR',
+        targetBranchConfirmed: true,
         reviewers: ['reviewer-id'],
         dingtalkMarkdownTitle: 'PR created',
         dingtalkMarkdownContent: '[Open PR]({{PR_WEB_URL}})'
       });
 
       assert.equal(result.success, true);
+      assert.equal(result.created, true);
+      assert.equal(result.alreadyExists, false);
       assert.equal(result.dingtalkSendSuccess, true);
       assert.deepEqual(result.adoApiPayload, {
         sourceRefName: 'refs/heads/release/with-change',
@@ -88,14 +93,14 @@ test('creates the reverse PR with the required branch direction and sends render
         title: 'Reverse PR',
         reviewers: [{ id: 'reviewer-id' }]
       });
-      assert.equal(calls.length, 2);
-      assert.match(calls[0].url, new RegExp(`api-version=${API_VERSION.replaceAll('.', '\\.')}`));
-      assert.deepEqual(JSON.parse(calls[0].options.body), result.adoApiPayload);
+      assert.equal(calls.length, 3);
+      assert.match(calls[1].url, new RegExp(`api-version=${API_VERSION.replaceAll('.', '\\.')}`));
+      assert.deepEqual(JSON.parse(calls[1].options.body), result.adoApiPayload);
       assert.equal(
-        JSON.parse(calls[1].options.body).markdown.text,
+        JSON.parse(calls[2].options.body).markdown.text,
         '[Open PR](https://dev.azure.com/org/project/_git/web/pullrequest/42)'
       );
-      assert.doesNotMatch(calls[0].options.headers.Authorization, /secret-pat/);
+      assert.doesNotMatch(calls[1].options.headers.Authorization, /secret-pat/);
     });
   } finally {
     globalThis.fetch = originalFetch;
@@ -105,8 +110,9 @@ test('creates the reverse PR with the required branch direction and sends render
 test('does not call DingTalk after an Azure DevOps create failure', async () => {
   let callCount = 0;
   const originalFetch = globalThis.fetch;
-  globalThis.fetch = async () => {
+  globalThis.fetch = async (_url, options) => {
     callCount += 1;
+    if (!options?.method || options.method === 'GET') return jsonResponse({ value: [] });
     return jsonResponse({ message: 'denied' }, 401);
   };
 
@@ -119,12 +125,13 @@ test('does not call DingTalk after an Azure DevOps create failure', async () =>
         businessTargetBranch: 'feature',
         businessSourceBranch: 'main',
         prTitle: 'PR',
+        targetBranchConfirmed: true,
         dingtalkMarkdownTitle: 'title',
         dingtalkMarkdownContent: 'content'
       });
       assert.equal(result.success, false);
       assert.equal(result.dingtalkSendSuccess, null);
-      assert.equal(callCount, 1);
+      assert.equal(callCount, 2);
     });
   } finally {
     globalThis.fetch = originalFetch;
@@ -133,7 +140,10 @@ test('does not call DingTalk after an Azure DevOps create failure', async () =>
 
 test('keeps PR success when DingTalk token is missing', async () => {
   const originalFetch = globalThis.fetch;
-  globalThis.fetch = async () => jsonResponse({ pullRequestId: 7 });
+  globalThis.fetch = async (_url, options) =>
+    !options?.method || options.method === 'GET'
+      ? jsonResponse({ value: [] })
+      : jsonResponse({ pullRequestId: 7 });
   try {
     await withEnvironment({ AZURE_DEVOPS_PAT: 'pat', DINGDING_ALERT_TOKEN: undefined }, async () => {
       const result = await createPullRequest({
@@ -143,6 +153,7 @@ test('keeps PR success when DingTalk token is missing', async () => {
         businessTargetBranch: 'feature',
         businessSourceBranch: 'main',
         prTitle: 'PR',
+        targetBranchConfirmed: true,
         dingtalkMarkdownTitle: 'title',
         dingtalkMarkdownContent: 'content'
       });
@@ -155,6 +166,138 @@ test('keeps PR success when DingTalk token is missing', async () => {
   }
 });
 
+test('requires explicit confirmation before targeting main or master', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => assert.fail('fetch must not be called before confirmation');
+  try {
+    for (const targetBranch of ['main', 'refs/heads/master', 'MAIN']) {
+      const result = await createPullRequest({
+        orgName: 'org',
+        projectName: 'project',
+        repoId: 'repo',
+        businessTargetBranch: 'feature',
+        businessSourceBranch: targetBranch,
+        prTitle: 'PR'
+      });
+      assert.equal(result.success, false);
+      assert.equal(result.confirmationRequired, true);
+      assert.match(result.errorMsg, /明确确认/);
+    }
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('returns the existing active PR link without sending DingTalk again', async () => {
+  const calls = [];
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async (url, options) => {
+    calls.push({ url: String(url), options });
+    return jsonResponse({
+      value: [
+        {
+          pullRequestId: 88,
+          repository: { name: 'web' },
+          _links: { web: { href: 'https://dev.azure.com/org/project/_git/web/pullrequest/88' } }
+        }
+      ]
+    });
+  };
+
+  try {
+    await withEnvironment({ AZURE_DEVOPS_PAT: 'pat', DINGDING_ALERT_TOKEN: 'ding-token' }, async () => {
+      const result = await createPullRequest({
+        orgName: 'org',
+        projectName: 'project',
+        repoId: 'repo',
+        businessTargetBranch: 'feature',
+        businessSourceBranch: 'develop',
+        prTitle: 'PR',
+        dingtalkMarkdownTitle: 'title',
+        dingtalkMarkdownContent: '[PR]({{PR_WEB_URL}})'
+      });
+
+      assert.equal(result.success, true);
+      assert.equal(result.created, false);
+      assert.equal(result.alreadyExists, true);
+      assert.equal(result.prId, '88');
+      assert.equal(result.prWebUrl, 'https://dev.azure.com/org/project/_git/web/pullrequest/88');
+      assert.equal(result.dingtalkSendSuccess, null);
+      assert.equal(calls.length, 1);
+      const query = new URL(calls[0].url).searchParams;
+      assert.equal(query.get('searchCriteria.status'), 'active');
+      assert.equal(query.get('searchCriteria.sourceRefName'), 'refs/heads/feature');
+      assert.equal(query.get('searchCriteria.targetRefName'), 'refs/heads/develop');
+      assert.equal(calls[0].options?.method, undefined);
+    });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('returns the existing PR link when creation races with another submitter', async () => {
+  let adoCall = 0;
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => {
+    adoCall += 1;
+    if (adoCall === 1) return jsonResponse({ value: [] });
+    if (adoCall === 2) return jsonResponse({ message: 'active pull request already exists' }, 409);
+    return jsonResponse({
+      value: [
+        {
+          pullRequestId: 99,
+          repository: { name: 'web' },
+          _links: { web: { href: 'https://dev.azure.com/org/project/_git/web/pullrequest/99' } }
+        }
+      ]
+    });
+  };
+
+  try {
+    await withEnvironment({ AZURE_DEVOPS_PAT: 'pat' }, async () => {
+      const result = await createPullRequest({
+        orgName: 'org',
+        projectName: 'project',
+        repoId: 'repo',
+        businessTargetBranch: 'feature',
+        businessSourceBranch: 'develop',
+        prTitle: 'PR'
+      });
+      assert.equal(result.success, true);
+      assert.equal(result.created, false);
+      assert.equal(result.alreadyExists, true);
+      assert.equal(result.prWebUrl, 'https://dev.azure.com/org/project/_git/web/pullrequest/99');
+      assert.equal(adoCall, 3);
+    });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('sends a confirmed DingTalk notification for an existing PR link', async () => {
+  const originalFetch = globalThis.fetch;
+  let markdownText;
+  globalThis.fetch = async (_url, options) => {
+    markdownText = JSON.parse(options.body).markdown.text;
+    return jsonResponse({ errcode: 0, errmsg: 'ok' });
+  };
+
+  try {
+    await withEnvironment({ DINGDING_ALERT_TOKEN: 'ding-token' }, async () => {
+      const result = await sendPullRequestDingtalk({
+        prWebUrl: 'https://dev.azure.com/org/project/_git/web/pullrequest/88',
+        dingtalkMarkdownTitle: 'Existing PR',
+        dingtalkMarkdownContent: '[Open]({{PR_WEB_URL}})'
+      });
+      assert.equal(result.success, true);
+      assert.equal(result.dingtalkSendSuccess, true);
+      assert.equal(markdownText, '[Open](https://dev.azure.com/org/project/_git/web/pullrequest/88)');
+    });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test('rejects identical normalized PR branches without making an HTTP request', async () => {
   const originalFetch = globalThis.fetch;
   globalThis.fetch = async () => assert.fail('fetch must not be called');
@@ -266,7 +409,7 @@ test('returns a structured missing-PAT error', async () => {
   });
 });
 
-test('exposes all five tools over stdio', async () => {
+test('exposes all six tools over stdio', async () => {
   const client = new Client({ name: 'code-mcp-pr-test', version: '1.0.0' });
   const transport = new StdioClientTransport({
     command: process.execPath,
@@ -281,7 +424,14 @@ test('exposes all five tools over stdio', async () => {
     const { tools } = await client.listTools();
     assert.deepEqual(
       tools.map(tool => tool.name),
-      ['code-mcp-pr', 'get_repo_default_branch', 'guess_parent_branch', 'get_branch_diff', 'read_file_at_ref']
+      [
+        'code-mcp-pr',
+        'send_pr_dingtalk',
+        'get_repo_default_branch',
+        'guess_parent_branch',
+        'get_branch_diff',
+        'read_file_at_ref'
+      ]
     );
   } finally {
     await client.close();

package/package.json

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

package/plugins/autobest-delivery/.codex-plugin/plugin.json

@@ -18,6 +18,7 @@
     ],
     "defaultPrompt": [
       "\u9488\u5bf9\u5f53\u524d\u529f\u80fd\u89c4\u683c\u8fd0\u884c\u5b8c\u6574\u4ea4\u4ed8\u95ed\u73af\u3002",
+      "\u4f7f\u7528\u5feb\u901f\u4ea4\u4ed8\u95ed\u73af\u5b9e\u73b0\u5f53\u524d\u529f\u80fd\uff0c\u5b8c\u6210\u4ea4\u4e92\u5f0f Playwright \u81ea\u6d4b\u3001\u622a\u56fe\u548c\u72ec\u7acb\u4ee3\u7801\u5ba1\u8ba1\u3002",
       "\u68c0\u67e5\u9694\u79bb E2E \u8fd0\u884c\u5668\u662f\u5426\u5df2\u7ecf\u5c31\u7eea\u3002"
     ]
   },

package/plugins/autobest-delivery/README.md

@@ -1,12 +1,12 @@
 # Autobest 交付插件
 
-`autobest-delivery` 将 Autobest 交付闭环 Skill 与插件自带的 Playwright MCP 运行器打包在一起。目标业务仓库只需提供应用源码、功能规格和启动命令，不需要安装 Playwright 依赖。
+`autobest-delivery` 将 Autobest 完整及快速交付闭环 Skill 与插件自带的 Playwright MCP 运行器打包在一起。目标业务仓库只需提供应用源码、功能规格和启动命令，不需要安装 Playwright 依赖。
 
 ## 隔离机制
 
-运行器的 Node 依赖位于 `mcp-server/node_modules/`，Chromium 位于 `mcp-server/.runtime/ms-playwright/`，这两个路径均被插件忽略。工具只接受绝对路径形式的目标工作区，并且仅允许读取冻结场景、向指定功能输出目录写入证据。
+运行器的 Node 依赖位于 `mcp-server/node_modules/`，Chromium 位于 `mcp-server/.runtime/ms-playwright/`，这两个路径均被插件忽略。工具只接受绝对路径形式的目标工作区，并且仅允许读取所需输入、向工作区内指定功能输出目录写入证据。标准运行器会额外校验冻结场景在执行前后的 SHA-256。
 
-运行器不会在目标工作区调用包管理器，也不会修改目标仓库的清单、锁文件、`node_modules`、配置或源码。每次执行前后都会校验冻结场景的 SHA-256。
+运行器不会在目标工作区调用包管理器，也不会修改目标仓库的清单、锁文件、`node_modules`、配置或源码。标准 `run_feature_e2e` 每次执行前后都会校验冻结场景的 SHA-256。
 
 ## 使用 npx 安装
 
@@ -65,10 +65,27 @@ 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` 的场景仍可运行，但无法在未捕获异常后继续。
 
+### 快速交互式 Playwright 工具
+
+`$delivery-loop-fast` 使用以下工具直接操作浏览器，不创建或执行 `e2e/e2e.feature.mjs`：
+
+- `start_fast_check`：启动会话并导航到应用；API 模式支持 `real`、`mock` 和无需业务 API 证明的 `none`。
+- `fast_browser_snapshot`：读取当前页面的可访问性快照。
+- `fast_browser_action`：执行导航、点击、填写、选择、按键、等待和视口切换。
+- `mock_fast_check_route`：仅在 `mock` 模式安装受控 JSON 响应。
+- `fast_browser_check`：执行并记录结构化页面检查。
+- `capture_fast_check`：保存按报告功能组映射的桌面端或移动端截图。
+- `finish_fast_check`：写入结果 JSON、中文 Markdown、Trace 和截图索引后关闭会话。
+- `abort_fast_check`：放弃未完成的会话并关闭浏览器。
+
+每轮产物位于 `fast-check/runs/iteration-NN/`，并以 `evidenceSource: interactive-playwright` 明确标识为实现者交互式自测，不属于独立 Checker 证据。后续 `$export-report` 可直接读取最新快速结果和截图。
+
 ### `resolve_blocked_run`
 
 用户查看 Blocked 浏览器后，由创建该会话的验收代理调用此工具。工具将选择写入 `human-decision.json` 并关闭浏览器；`accept` 或 `skip` 会形成 waiver，而不是伪装成完整通过。
@@ -90,10 +107,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 +149,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,19 +159,25 @@ 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 可读取标准 Runner/Checker 证据或快速交互式自测证据，并且只生成一个 `自测报告` 工作表。每行代表一个真实 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` 审查代码规范和规格符合度。
 
+### 快速流程 `$delivery-loop-fast`
+
+快速流程由用户显式选择，不进行风险评分，也不会自动切换为完整流程。当前 Agent 根据 spec 实现代码、执行仓库定向检查，并使用上述交互式 Playwright 工具自测、截图和自查自纠；业务代码或测试步骤变化后开启新的完整自测 iteration。最新快速自测通过后，再由全新的独立 `$code-audit` 代理审查固定范围。审计发现阻断问题时，当前 Agent 修复后必须重新完成仓库检查、快速自测和独立审计。
+
+快速流程不生成持久化 E2E 场景、测试编写者结果或 Checker 结果。完成条件仍包括：最新交互式自测通过、每个报告功能组具备截图、独立代码审计通过，并且证据与状态一致。现有 `$delivery-loop` 的角色隔离、冻结 E2E 和可见验收流程保持不变。
+
 运行器或工具故障不消耗实现者修复回合。隔离 scene 会先继续执行其他场景，再进入 `awaiting-decision`；用户可查看可见浏览器和完整的其余场景证据后重试、确认、跳过、分类为实现/测试缺陷或停止。
 
 ## 源码开发与验证

package/plugins/autobest-delivery/mcp-server/package.json

@@ -7,7 +7,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "lint": "node --check ../scripts/setup.mjs && node --check ../scripts/start-mcp.mjs && node --check ../scripts/export-delivery-report.mjs && node --check src/paths.mjs && node --check src/report.mjs && node --check src/runner.mjs && node --check src/server.mjs && node --check tests/fixture-server.mjs && node --check tests/report.test.mjs && node --check tests/runner.test.mjs && node --check tests/mcp-smoke.test.mjs && node --check tests/fixtures/basic.feature.mjs",
+    "lint": "node --check ../scripts/setup.mjs && node --check ../scripts/start-mcp.mjs && node --check ../scripts/export-delivery-report.mjs && node --check src/paths.mjs && node --check src/report.mjs && node --check src/runner.mjs && node --check src/fast-runner.mjs && node --check src/server.mjs && node --check tests/fixture-server.mjs && node --check tests/report.test.mjs && node --check tests/runner.test.mjs && node --check tests/fast-runner.test.mjs && node --check tests/mcp-smoke.test.mjs && node --check tests/fixtures/basic.feature.mjs",
     "test": "node --test --test-concurrency=1 tests/*.test.mjs",
     "verify": "npm run lint && npm test"
   },