@autobest-ui/agent 1.0.0

package/mcp/rag-mcp-bridge/index.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+
+/**
+ * RAG MCP bridge for the local PRD knowledge Express API.
+ *
+ * Responsibilities are deliberately limited to:
+ * 1. Expanding file, file-array, and directory inputs into Markdown paths.
+ * 2. Forwarding MCP tool calls to the local HTTP API.
+ *
+ * Database access, Markdown parsing, embeddings, and RAG stay in Express.
+ */
+
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const DEFAULT_HTTP_TIMEOUT_MS = 120_000;
+
+function apiBaseUrlFromEnvironment() {
+  const configuredUrl = process.env.RAG_API_BASE_URL?.trim();
+  if (!configuredUrl) {
+    throw new Error(
+      "RAG_API_BASE_URL is required; configure it in the MCP server environment",
+    );
+  }
+
+  let url;
+  try {
+    url = new URL(configuredUrl);
+  } catch {
+    throw new Error("RAG_API_BASE_URL must be a valid URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("RAG_API_BASE_URL must use http or https");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+function httpTimeoutFromEnvironment() {
+  const configuredTimeout =
+    process.env.RAG_MCP_HTTP_TIMEOUT_MS ?? String(DEFAULT_HTTP_TIMEOUT_MS);
+  const timeout = Number(configuredTimeout);
+  if (!Number.isSafeInteger(timeout) || timeout <= 0) {
+    throw new Error("RAG_MCP_HTTP_TIMEOUT_MS must be a positive integer");
+  }
+  return timeout;
+}
+
+const API_BASE_URL = apiBaseUrlFromEnvironment();
+const HTTP_TIMEOUT_MS = httpTimeoutFromEnvironment();
+
+const pathsSchema = z
+  .union([
+    z.string().min(1),
+    z.array(z.string().min(1)).min(1),
+  ])
+  .describe("单个Markdown文件、Markdown文件数组或文件夹的绝对路径");
+const platformSchema = z
+  .enum(["app", "california-web", "shared"])
+  .describe("知识所属平台；必须明确指定，防止APP与加州网站需求串库");
+const moduleSchema = z
+  .string()
+  .min(1)
+  .optional()
+  .describe("可选业务模块标识，例如vehicle-selector");
+const pageSchema = z
+  .string()
+  .min(1)
+  .optional()
+  .describe(
+    "业务页面键，例如home、pl、pn、pd、name-search；录入多个文件时不要传，由后端按文件名分别推断",
+  );
+const docKeySchema = z
+  .string()
+  .min(1)
+  .optional()
+  .describe("需要限定到单一文档时传knowledge_doc.doc_key绝对路径");
+
+/** Recursively collects Markdown files from a directory in stable order. */
+async function scanMarkdownDirectory(directoryPath) {
+  const markdownFiles = [];
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+
+  for (const entry of entries) {
+    const entryPath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      markdownFiles.push(...(await scanMarkdownDirectory(entryPath)));
+    } else if (entry.isFile() && path.extname(entry.name).toLowerCase() === ".md") {
+      markdownFiles.push(path.resolve(entryPath));
+    }
+  }
+  return markdownFiles;
+}
+
+/** Normalizes all supported path inputs to a unique array of absolute .md files. */
+async function expandMarkdownPaths(pathsInput) {
+  const inputs = Array.isArray(pathsInput) ? pathsInput : [pathsInput];
+  const markdownFiles = [];
+
+  for (const input of inputs) {
+    if (typeof input !== "string" || !input.trim()) {
+      throw new Error("paths中的每一项都必须是非空字符串");
+    }
+    if (!path.isAbsolute(input.trim())) {
+      throw new Error(`必须使用绝对路径: ${input}`);
+    }
+
+    const absolutePath = path.resolve(input.trim());
+    const pathStat = await stat(absolutePath);
+    if (pathStat.isDirectory()) {
+      markdownFiles.push(...(await scanMarkdownDirectory(absolutePath)));
+    } else if (
+      pathStat.isFile() &&
+      path.extname(absolutePath).toLowerCase() === ".md"
+    ) {
+      markdownFiles.push(absolutePath);
+    } else {
+      throw new Error(`路径不是Markdown文件或文件夹: ${absolutePath}`);
+    }
+  }
+
+  const uniquePaths = [...new Set(markdownFiles)].sort((left, right) =>
+    left.localeCompare(right),
+  );
+  if (uniquePaths.length === 0) {
+    throw new Error("指定路径中没有找到任何.md文件");
+  }
+  return uniquePaths;
+}
+
+/** Posts JSON to Express and returns its parsed response body. */
+async function postJson(endpoint, body) {
+  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+  });
+  const responseText = await response.text();
+  let responseBody;
+  try {
+    responseBody = responseText ? JSON.parse(responseText) : null;
+  } catch {
+    responseBody = responseText;
+  }
+
+  if (!response.ok) {
+    const details =
+      typeof responseBody === "string"
+        ? responseBody
+        : JSON.stringify(responseBody);
+    throw new Error(`Express后端返回HTTP ${response.status}: ${details}`);
+  }
+  return responseBody;
+}
+
+/** Sends a GET request to Express and returns its parsed JSON response. */
+async function getJson(endpoint, query) {
+  const url = new URL(`${API_BASE_URL}${endpoint}`);
+  for (const [name, value] of Object.entries(query)) {
+    if (value === undefined || value === null || value === "") continue;
+    url.searchParams.set(name, value);
+  }
+  const response = await fetch(url, {
+    method: "GET",
+    signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+  });
+  const responseText = await response.text();
+  let responseBody;
+  try {
+    responseBody = responseText ? JSON.parse(responseText) : null;
+  } catch {
+    responseBody = responseText;
+  }
+  if (!response.ok) {
+    const details =
+      typeof responseBody === "string"
+        ? responseBody
+        : JSON.stringify(responseBody);
+    throw new Error(`Express后端返回HTTP ${response.status}: ${details}`);
+  }
+  return responseBody;
+}
+
+function toolSuccess(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}
+
+function toolError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }],
+  };
+}
+
+const server = new McpServer(
+  { name: "rag-mcp-bridge", version: "1.0.0" },
+  {
+    instructions:
+      "Use retrieve_knowledge before implementing requirement-sensitive code. " +
+      "Every tool call requires an explicit platform: app, california-web, or shared. " +
+      "add_prd_file and update_spec_file accept one file, an array of files, or a directory. " +
+      "Only call update_spec_file after the PR is merged and leader review confirms the spec is effective.",
+  },
+);
+
+server.registerTool(
+  "add_prd_file",
+  {
+    title: "录入或更新PRD基线",
+    description:
+      "录入/更新PRD基线。paths支持单个md绝对路径、md绝对路径数组或文件夹绝对路径；文件夹会递归扫描全部.md文件。后端负责解析截图并将旧文档标记为作废。",
+    inputSchema: {
+      paths: pathsSchema,
+      platform: platformSchema,
+      module: moduleSchema,
+      page: pageSchema,
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+  },
+  async ({ paths, platform, module, page }) => {
+    try {
+      const expandedPaths = await expandMarkdownPaths(paths);
+      return toolSuccess(
+        await postJson("/add-prd", {
+          paths: expandedPaths,
+          platform,
+          module,
+          page,
+        }),
+      );
+    } catch (error) {
+      return toolError(error);
+    }
+  },
+);
+
+server.registerTool(
+  "update_spec_file",
+  {
+    title: "录入迭代变更Spec",
+    description:
+      "仅在PR合并且leader review确认生效后调用。paths支持单个spec.md绝对路径、路径数组或文件夹；只需传改动spec。sprintVersion必须递增，数值越大需求越新。",
+    inputSchema: {
+      paths: pathsSchema,
+      sprintVersion: z.number().int().positive(),
+      iterationTag: z.string().min(1),
+      platform: platformSchema,
+      module: moduleSchema,
+      page: pageSchema,
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+  },
+  async ({ paths, sprintVersion, iterationTag, platform, module, page }) => {
+    try {
+      const expandedPaths = await expandMarkdownPaths(paths);
+      return toolSuccess(
+        await postJson("/add-spec", {
+          paths: expandedPaths,
+          sprintVersion,
+          iterationTag,
+          platform,
+          module,
+          page,
+        }),
+      );
+    } catch (error) {
+      return toolError(error);
+    }
+  },
+);
+
+server.registerTool(
+  "retrieve_knowledge",
+  {
+    title: "检索PRD与迭代Spec",
+    description:
+      "Codex编写需求相关代码前调用。后端执行向量+BM25-RRF混合检索并按sprint_version业务排序。enableStruct=true时才生成结构化PRD；includeImages=true时才保留图片并替换为数据库图片URL，两者默认均为false。",
+    inputSchema: {
+      query: z.string().min(1),
+      platform: platformSchema,
+      module: moduleSchema.describe(
+        "可选业务模块硬过滤，例如vehicle-selector",
+      ),
+      page: pageSchema.describe(
+        "可选页面硬过滤，例如首页传home；不传时后端会从明确的查询词自动推断",
+      ),
+      docKey: docKeySchema,
+      enableStruct: z
+        .boolean()
+        .default(false)
+        .describe("是否调用LLM生成structuredPrd，默认false"),
+      includeImages: z
+        .boolean()
+        .default(false)
+        .describe("是否返回可供UI显示的数据库图片URL，默认false"),
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  async ({
+    query,
+    platform,
+    module,
+    page,
+    docKey,
+    enableStruct = false,
+    includeImages = false,
+  }) => {
+    try {
+      return toolSuccess(
+        await getJson("/search", {
+          query: query.trim(),
+          platform,
+          module,
+          page,
+          docKey,
+          enableStruct: String(enableStruct === true),
+          includeImages: String(includeImages === true),
+        }),
+      );
+    } catch (error) {
+      return toolError(error);
+    }
+  },
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error("Failed to start rag-mcp-bridge:", error);
+  process.exitCode = 1;
+});

package/mcp/rag-mcp-bridge/index.test.js

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const directory = path.dirname(fileURLToPath(import.meta.url));
+
+test("initializes and exposes the RAG tools over stdio", async () => {
+  const client = new Client({ name: "rag-mcp-bridge-test", version: "1.0.0" });
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [path.join(directory, "index.js")],
+    cwd: path.resolve(directory, "../.."),
+    env: {
+      RAG_API_BASE_URL: "http://127.0.0.1:3000/api/knowledge",
+    },
+    stderr: "pipe",
+  });
+
+  try {
+    await client.connect(transport);
+
+    assert.equal(client.getServerVersion()?.name, "rag-mcp-bridge");
+    assert.match(client.getInstructions() ?? "", /retrieve_knowledge/);
+
+    const { tools } = await client.listTools();
+    assert.deepEqual(
+      tools.map(({ name }) => name),
+      ["add_prd_file", "update_spec_file", "retrieve_knowledge"],
+    );
+    assert.equal(
+      tools.find(({ name }) => name === "retrieve_knowledge")?.annotations
+        ?.readOnlyHint,
+      true,
+    );
+  } finally {
+    await client.close();
+  }
+});
+
+test("fails to start when RAG_API_BASE_URL is not configured", () => {
+  const environment = { ...process.env };
+  delete environment.RAG_API_BASE_URL;
+
+  const result = spawnSync(process.execPath, [path.join(directory, "index.js")], {
+    cwd: path.resolve(directory, "../.."),
+    env: environment,
+    encoding: "utf8",
+  });
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /RAG_API_BASE_URL is required/);
+});

package/mcp/rag-mcp-bridge/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@autobest/rag-mcp-bridge",
+  "version": "1.0.0",
+  "private": true,
+  "description": "MCP bridge for the PRD knowledge RAG API",
+  "type": "module",
+  "main": "index.js",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "lint": "node --check index.js && node --check index.test.js",
+    "test": "node --test index.test.js",
+    "verify": "npm run lint && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "4.4.3"
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@autobest-ui/agent",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Autobest Agent skills/plugins/mcp assets + sync cli",
+  "files": [
+    "skills",
+    "plugins",
+    "!plugins/**/node_modules",
+    "!plugins/**/.runtime",
+    "mcp",
+    "bin"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "autobest-agent-sync": "./bin/sync-assets.mjs",
+    "autobest-azurepr-mcp": "./mcp/azurepr-mcp-bridge/index.js",
+    "autobest-delivery-setup": "./plugins/autobest-delivery/scripts/setup.mjs",
+    "autobest-rag-mcp": "./mcp/rag-mcp-bridge/index.js"
+  },
+  "scripts": {
+    "mcp:azurepr": "node ./mcp/azurepr-mcp-bridge/index.js",
+    "mcp:rag": "node ./mcp/rag-mcp-bridge/index.js",
+    "test": "npm run test:skills && npm run test:mcp && npm run test:plugin",
+    "test:skills": "node --test ./bin/sync-assets.test.mjs",
+    "test:mcp:azurepr": "node --test ./mcp/azurepr-mcp-bridge/index.test.js",
+    "test:mcp:rag": "node --test ./mcp/rag-mcp-bridge/index.test.js",
+    "test:mcp": "npm run test:mcp:azurepr && npm run test:mcp:rag",
+    "test:plugin": "node --test ./plugins/autobest-delivery/scripts/setup.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "diff": "9.0.0",
+    "fs-extra": "11.3.0",
+    "zod": "4.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,25 @@
+{
+  "name": "autobest-delivery",
+  "version": "1.0.0+codex.npm",
+  "description": "\u5728\u4e0d\u5411\u4e1a\u52a1\u4ed3\u5e93\u6dfb\u52a0\u6d4b\u8bd5\u4f9d\u8d56\u7684\u524d\u63d0\u4e0b\uff0c\u8fd0\u884c\u9694\u79bb\u4e14\u7531\u89c4\u683c\u9a71\u52a8\u7684 UI \u4ea4\u4ed8\u95ed\u73af\u3002",
+  "author": {
+    "name": "Autobest \u524d\u7aef\u56e2\u961f"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Autobest \u4ea4\u4ed8\u95ed\u73af",
+    "shortDescription": "\u9694\u79bb\u8fd0\u884c Playwright UI \u4ea4\u4ed8\u95ed\u73af",
+    "longDescription": "\u5c06\u4ea4\u4ed8\u95ed\u73af Skill \u4e0e\u9694\u79bb\u7684 Playwright MCP \u8fd0\u884c\u5668\u6253\u5305\uff0c\u4f7f\u8001\u4e1a\u52a1\u4ed3\u5e93\u65e0\u9700\u5b89\u88c5\u6d4b\u8bd5\u4f9d\u8d56\u3002",
+    "developerName": "Autobest \u524d\u7aef\u56e2\u961f",
+    "category": "Productivity",
+    "capabilities": [
+      "Browser Automation",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "\u9488\u5bf9\u5f53\u524d\u529f\u80fd\u89c4\u683c\u8fd0\u884c\u5b8c\u6574\u4ea4\u4ed8\u95ed\u73af\u3002",
+      "\u68c0\u67e5\u9694\u79bb E2E \u8fd0\u884c\u5668\u662f\u5426\u5df2\u7ecf\u5c31\u7eea\u3002"
+    ]
+  },
+  "mcpServers": "./.mcp.json"
+}

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

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "autobest-delivery": {
+      "command": "node",
+      "args": ["./scripts/start-mcp.mjs"],
+      "cwd": ".",
+      "startup_timeout_sec": 20,
+      "tool_timeout_sec": 900
+    }
+  }
+}

package/plugins/autobest-delivery/README.md

@@ -0,0 +1,164 @@
+# Autobest 交付插件
+
+`autobest-delivery` 将 Autobest 交付闭环 Skill 与插件自带的 Playwright MCP 运行器打包在一起。目标业务仓库只需提供应用源码、功能规格和启动命令，不需要安装 Playwright 依赖。
+
+## 隔离机制
+
+运行器的 Node 依赖位于 `mcp-server/node_modules/`，Chromium 位于 `mcp-server/.runtime/ms-playwright/`，这两个路径均被插件忽略。工具只接受绝对路径形式的目标工作区，并且仅允许读取冻结场景、向指定功能输出目录写入证据。
+
+运行器不会在目标工作区调用包管理器，也不会修改目标仓库的清单、锁文件、`node_modules`、配置或源码。每次执行前后都会校验冻结场景的 SHA-256。
+
+## 使用 npx 安装
+
+前置条件：
+
+- Node.js 20 或更高版本；
+- 支持 `codex plugin` 命令的 Codex CLI；
+- 能访问 `@autobest-ui/agent` 所在的 npm registry。
+
+安装或更新插件：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-delivery-setup
+```
+
+安装器会在临时目录中执行 `npm ci` 并下载固定版本的 Chromium。运行时完整就绪后，插件才会替换到以下持久化目录：
+
+```text
+~/.autobest-agent/marketplaces/autobest-team/
+├── .agents/plugins/marketplace.json
+└── plugins/autobest-delivery/
+```
+
+随后安装器会注册 `autobest-team` 本地市场，并执行等效于 `codex plugin add autobest-delivery@autobest-team` 的安装操作。原来从源码仓库注册的同名市场会自动迁移到该持久化目录；重复执行同一命令即为更新，并复用已下载的同版本浏览器运行时。插件版本与 npm 包版本保持一致。安装或更新后需要重启 Codex，并在新会话中使用。
+
+生产环境建议固定 npm 包版本，例如：
+
+```bash
+npx --yes --package=@autobest-ui/agent@1.0.0 autobest-delivery-setup
+```
+
+卸载插件及 Autobest 专用本地市场：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-delivery-setup uninstall
+```
+
+卸载命令只会删除 `~/.autobest-agent/marketplaces/autobest-team` 这一精确路径。查看命令帮助可执行：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-delivery-setup --help
+```
+
+## MCP 工具
+
+### `check_environment`
+
+启动插件自带的 Chromium，返回 Node、运行器、Playwright、浏览器及其存储目录版本。交付闭环会在第一次实现者回合前调用此工具。
+
+### `run_feature_e2e`
+
+必填参数：
+
+- `workspaceRoot`：目标工作区的绝对路径。
+- `scenarioPath`：工作区内冻结的 `.mjs` 场景路径。
+- `baseUrl`：可访问的应用 URL。
+- `outputDir`：工作区内的证据输出目录。
+
+可选参数包括 `iteration`、`timeoutMs`、`headed`、`keepBrowserOpenOnBlock` 和 `blockedSessionTtlMs`。交付验收使用 headed 模式；发生 Blocked 时，工具保留可见浏览器并返回 session ID、过期时间、结构化检查、组件截图、Trace、控制台错误、网络失败和 SHA-256。
+
+新版场景通过 `scene(id, callback)` 隔离页面和执行错误。一个 scene 的定位器、弹窗或准备步骤阻塞时，运行器会记录该 blocker 并继续执行后续独立 scene，全部 scene 尝试结束后再返回 `blocked`。旧版直接使用顶层 `page` 的场景仍可运行，但无法在未捕获异常后继续。
+
+### `resolve_blocked_run`
+
+用户查看 Blocked 浏览器后，由创建该会话的验收代理调用此工具。工具将选择写入 `human-decision.json` 并关闭浏览器；`accept` 或 `skip` 会形成 waiver，而不是伪装成完整通过。
+
+| 决策 | 后续效果 | 代表什么 | 建议使用场景 |
+| --- | --- | --- | --- |
+| `retry` | 使用未修改的冻结场景重新验收 | 本轮证据无效，原样再跑一次 | 服务刚启动、网络抖动、偶发加载超时、Blocked 会话已过期；只有相信同样输入再次执行可能成功时使用 |
+| `accept` | 记录人工确认 waiver，继续代码审计 | 自动证据缺失，但用户已在保留的可见浏览器中亲自确认阻断点符合预期 | 页面实际状态清晰可见且可由人工可靠判断；不适合无法观察的请求、状态污染或后续行为 |
+| `skip` | 记录风险 waiver，继续代码审计 | 不判断阻断点是否正确，接受该 scene 的证据缺失 | 阻断覆盖低风险、非发布关键路径，且用户愿意接受未验证风险；它不会从抛异常的语句下一行恢复执行，后续覆盖来自已隔离并继续执行的其他 scene |
+| `implementation_defect` | 进入新的 Maker 修复回合 | 测试可信，业务页面或接口行为不符合 spec | 页面内容、交互、导航、布局或业务请求确实错误，并且可由业务代码修复 |
+| `test_defect` | 进入新的测试编写者修订回合并重新冻结 | spec 与实现可能正确，冻结场景的定位器、fixture、弹窗处理或等待逻辑错误 | Trace/DOM 表明测试假设不成立，例如把选项错误地定位为 `listitem`、错误等待原生 alert、fixture 未提供所需数据 |
+| `stop` | 终止闭环并写为 `blocked` | 不再继续实现、验收或审计 | 需求取消、环境短期无法恢复、需要外部决策，或继续执行的成本已不合理 |
+
+选择时先判断“同样输入重跑是否可能恢复”：可能则用 `retry`。稳定复现后判断测试本身是否可信：测试机械问题用 `test_defect`，真实业务问题用 `implementation_defect`。只有愿意承担缺失证据时才使用 `accept` 或 `skip`；其中 `accept` 表示已经人工确认，`skip` 表示未确认。`stop` 是唯一终止选项。
+
+## 场景契约
+
+测试编写者创建 `featureDir/e2e/e2e.feature.mjs`。该文件不导入任何包，所需能力全部由运行器注入：
+
+```js
+export const metadata = {
+  scenes: ['initial'],
+  viewports: [{ name: 'desktop', width: 1400, height: 1000 }],
+  visualMappings: []
+};
+
+export default async function run({
+  scene
+}) {
+  await scene('initial', async ({
+    page,
+    expect,
+    check,
+    route,
+    capture,
+    artifact,
+    baseUrl,
+    parseUrl
+  }) => {});
+}
+```
+
+每个 `metadata.scenes` 项必须由 `scene()` 恰好执行一次，并自行完成导航、API fixture 和状态准备。测试编写者在冻结 SHA-256 前使用同一运行器进行 preflight；定位器、弹窗、fixture 和等待条件等测试机械问题应在草稿阶段修正。preflight 只证明测试代码能够完整执行，不替代独立验收和视觉审查。
+
+视觉审查使用 `1400px` 桌面视口和与 Figma 一致的 `375px` 移动视口。截图必须定位到与基准相同的语义节点；比较组件结构、布局和视觉样式，不比较业务文字的字面值、长度或业务图片主体。文案及数据内容由独立功能检查验证。
+
+角色所有权、结果结构、视觉映射规则和状态流转详见 `skills/delivery-loop/references/delivery-contract.md`。
+
+## 人读报告
+
+Checker 和代码审计生成的 Markdown 使用简体中文，包括标题、摘要、表头、检查说明、期望、实际结果和 finding。JSON 字段名、机器状态、ID、路径及原始工具错误保持协议格式；英文原始错误旁提供中文解释。
+
+手动调用 `$export-report` 时，Excel 只生成一个 `自测报告` 工作表。每行代表一个真实 UI 组件或完整业务功能；同一组件或功能的文案、样式、布局、响应式行为和相关检查合并到同一行，桌面端与移动端代表截图也放在该行。报告不展示 story ID、scene 名或原子检查明细。新证据通过 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod` 和 `reportDevice` 提供通用分组；旧证据必须由导出 Skill 分析 `spec.md` 后生成经过哈希和完整覆盖校验的语义分组清单，禁止按 E2E scene 猜测。
+
+## 交付流程
+
+1. `$delivery-loop` 调用 `check_environment` 并记录固定审查点。
+2. `$code-craft` 实现规格。
+3. `$e2e-gen-spec` 创建无依赖场景，运行冻结前 preflight，确认所有 scene 和检查可达后冻结。
+4. `$e2e-ui-checker` 启动声明的应用服务，调用 `run_feature_e2e`，并审查已映射的组件截图。
+5. Blocked 时进入人工决策；只有用户选择 `stop` 才终止。
+6. 验收通过或用户接受 waiver 后，`$code-audit` 审查代码规范和规格符合度。
+
+运行器或工具故障不消耗实现者修复回合。隔离 scene 会先继续执行其他场景，再进入 `awaiting-decision`；用户可查看可见浏览器和完整的其余场景证据后重试、确认、跳过、分类为实现/测试缺陷或停止。
+
+## 源码开发与验证
+
+在 `packages/agents` 目录直接运行源码安装器时，也会使用上述用户级持久化目录：
+
+```bash
+node plugins/autobest-delivery/scripts/setup.mjs
+```
+
+如需只验证插件运行器而不安装插件：
+
+```bash
+cd plugins/autobest-delivery/mcp-server
+npm run verify
+```
+
+测试套件会启动插件自带的真实浏览器，调用 stdio MCP 工具，验证通过、失败和阻断结果，检查超时清理与路径越界保护，确保冻结场景哈希不变，并确认目标仓库的哨兵清单和依赖没有被修改。
+
+CI 可按固定 Playwright 版本缓存 `mcp-server/.runtime/ms-playwright`，然后在 `mcp-server/` 中执行 `npm run verify`。
+
+## 状态含义
+
+- `passed`：所有运行检查均成功完成。
+- `failed`：执行完整结束，但至少一个业务断言失败。
+- `blocked`：运行器证据不完整，等待人工决策，不直接终止编排。
+- `awaiting-decision`：可见浏览器和证据已保留，等待用户选择下一步。
+- `passed-with-waivers`：代码审计通过，但用户明确接受或跳过了不完整验收证据。
+
+通用 Playwright MCP 回放不作为降级方案。冻结场景始终通过本插件的确定性运行器执行。