@autobest-ui/agent 1.0.10 → 1.0.12

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

@@ -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';
@@ -202,6 +202,74 @@ test('REQ 分节规格可从检查映射导出并嵌入报告截图', async () =
   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/skills/code-audit/SKILL.md

@@ -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/references/delivery-contract.md

@@ -19,9 +19,20 @@
 | `review/code-audit-result.json` 和 `.md` | 代码审计者 | 只读 |
 | `delivery/delivery-state.json` | 编排者 | 只读 |
 | `delivery/code-craft-result.json` | 实现者 | 只读 |
+| `fast-check/runs/iteration-NN/fast-check-result.json`、`.md`、Trace 和截图 | 快速模式 MCP | 只读 |
 
 旧 `e2e.feature.spec.ts` 文件不是本契约的可执行输入。保持这些文件不变；缺少标准 `.mjs` 场景时生成新场景。
 
+## 快速交付证据
+
+`delivery-loop-fast` 是用户显式选择的快速模式。当前 Agent 同时实现业务代码并使用 MCP 交互式 Playwright 工具自测，不启动独立测试编写者或 UI Checker，不生成 `e2e/e2e.feature.mjs`、`e2e/author-result.json` 和 `checker/checker-result.*`。这条路径不进行风险分类，也不因改动类型自动切换到完整流程。
+
+每轮快速自测写入 `fast-check/runs/iteration-NN/fast-check-result.json` 和 `.md`、`trace.zip` 及 `captures/`。结果必须使用 `evidenceSchemaVersion: 1`、`evidenceSource: interactive-playwright`，包含实际检查、报告分组、截图映射、API 模式、控制台错误和网络失败。`real` 表示真实 API，`mock` 表示受控响应，`none` 表示本次没有指定需要证明的业务 API；只有 mock 模式能安装请求响应。
+
+每项检查使用稳定 ID，并包含 `specSnippet`、`expect`、`actual`、`isPass`、`reportModule`、`reportGroup`、`reportTitle` 和 `reportMethod`；追踪模式同时包含 manifest 中的 `requirementId`。每个报告功能组至少有一个 `captureRecords` 条目，包含相同的报告字段、`reportDevice`、工作区相对路径和 SHA-256。截图是运行时状态证据，不是独立验收或 Figma 一致性结论。
+
+业务代码或交互步骤修复后必须开始新的 iteration；旧结果保留但失效。最终 `passed` 需要最新快速自测通过和全新独立 `$code-audit` 通过。代码审计读取快速证据，但不能把它升级描述为独立 Checker 证据。`export-report` 可以直接读取最新快速结果，并在摘要中标记 `evidenceSource: interactive-playwright`。
+
 ## 需求追踪
 
 当功能目录包含 `spec-traceability.json` 时，交付必须按其中的 active REQ ID 运行，编号格式为 `REQ-<页面或Scope简称>-<三位序号>`。编号由上游 `ui-prd-scope` 所有；本插件的编排者、Maker、测试编写者、Checker 和 Audit 只能引用，不能创建、修改或重排。开始 Maker 前必须确认 scope、review、spec 及其 SHA-256 一致。

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

@@ -0,0 +1,62 @@
+---
+name: delivery-loop-fast
+description: 快速完成用户明确选择的 UI 交付：当前 Agent 连续实现、自查、使用交互式 Playwright 测试和截图、修复后重测，再交给独立代码审计；保留可由 export-report 导出的标准快速证据，不生成 E2E 场景文件或独立 Checker 结论。
+---
+
+# 快速交付闭环
+
+这是用户主动选择的快速执行模式，不进行风险评分或自动切换到 `$delivery-loop`。当前 Agent 同时拥有业务代码实现和交互式自测，最终代码审计仍由全新的独立代理执行。开始前完整阅读[共享交付契约](../delivery-loop/references/delivery-contract.md)中的“快速交付证据”部分。
+
+## 输入
+
+- 必需的功能 `spec.md` 和同目录 `scope.md`；存在时读取并校验 `spec-traceability.json`。
+- 可选的最大实现/自测回合数，默认 `3`，包含首次实现。
+- 可选的审计固定点，默认启动时的 `HEAD`。
+- API 模式为 `real`、`mock` 或 `none`。没有需要验证的业务 API 时使用 `none`；需要 API 且用户未明确 real/mock 时只询这一项。
+
+真实环境涉及创建、修改、删除、下单、支付或其他外部副作用时，在执行对应浏览器操作前说明具体影响并取得明确授权。完成交付不包含提交、推送或发布，除非用户另行明确要求。
+
+## 流程
+
+1. **预检：**读取 spec、scope、仓库规则、目标模块、视觉资产、固定审查点和当前工作树。追踪模式先校验输入哈希及 active REQ 集合。调用 `autobest-delivery.check_environment`；环境未就绪时进入 `awaiting-decision`，不开始实现。
+2. **状态：**写入 `delivery/delivery-state.json`，记录 `profile: "low"`、状态、固定审查点、既有改动、最大回合数、`apiMode`、当前实现/自测/审计 iteration 和产物路径。只管理与本次功能有关的文件和进程。
+3. **实现：**当前 Agent 直接阅读相邻代码并实现 spec，保留用户既有改动。涉及 React 或 CSS 结构时使用 `$ui-structure-guard`。执行仓库最小充分的 lint、类型检查、构建和现有定向测试；不得为了测试引入业务仓库依赖。
+4. **启动应用：**从仓库配置和 scope 解析启动命令、URL、路由、登录、数据和 fixture。启动并记录本流程拥有的服务 PID，确认 `baseUrl` 可访问。
+5. **交互式自测：**
+   - 调用 `start_fast_check`，输出目录固定为 `fast-check/runs/iteration-NN`，默认 headless；需要人工观察时才使用 headed。
+   - 先用 `fast_browser_snapshot` 读取页面，再用 `fast_browser_action` 完成导航、点击、填写、选择、按键、等待和视口切换。mock 模式可用 `mock_fast_check_route`；real/none 模式不得安装 mock。
+   - 用 `fast_browser_check` 记录每个功能预期。追踪规格使用真实 `requirementId`；旧版编号故事使用对应 `story-NN` 作为检查 ID。每项填写稳定的 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod`。
+   - 每个报告功能组至少用 `capture_fast_check` 保存一张代表性截图。scope 明确覆盖桌面和移动端且本次实现涉及两端时分别截图；截图在对应状态检查完成后生成。
+   - 调用 `finish_fast_check` 写入 JSON、Markdown、Trace 和截图索引。不要创建 `e2e/e2e.feature.mjs`、`e2e/author-result.json` 或 `checker/checker-result.*`，也不要把自测称为独立验收。
+6. **自查自纠：**`failed` 时结合检查、页面快照、Trace、控制台和网络证据判断是实现还是操作问题，直接修复并执行新的完整自测 iteration。业务代码或测试步骤改变后，上一轮证据只保留为历史，不作为最终通过证据。`blocked` 且无法自行解决时写入 `awaiting-decision` 并询问用户。回合耗尽时也进入 `awaiting-decision`，不得自行扩大回合数。
+7. **独立审计：**最新快速自测为 `passed` 后，从固定审查点启动全新的 `$code-audit` 代理，传入 spec、scope、traceability、`delivery-state.json` 和最新 `fast-check-result.json`。审计代理不得修改代码。存在阻断 finding 且仍有回合时，由当前 Agent 修复，重新执行仓库检查和完整快速自测，再启动新的独立审计。
+8. **完成：**只有最新快速自测为 `passed`、报告功能组均有截图、最新代码审计为 `passed`、状态和产物路径一致且没有未授权 Git/外部写操作时，才将交付状态写为 `passed`。否则保持真实的 `failed`、`blocked` 或 `awaiting-decision`。
+
+## 证据要求
+
+快速结果必须保存在：
+
+```text
+featureDir/
+|-- fast-check/
+|   `-- runs/
+|       `-- iteration-NN/
+|           |-- fast-check-result.json
+|           |-- fast-check-result.md
+|           |-- trace.zip
+|           `-- captures/*.png
+|-- review/
+|   |-- code-audit-result.json
+|   `-- code-audit-result.md
+`-- delivery/
+    `-- delivery-state.json
+```
+
+`fast-check-result.json` 的 `evidenceSource` 必须为 `interactive-playwright`。最终答复明确说明这是实现者交互式自测而非独立 Checker，并列出实现文件、仓库检查、最新自测结果、截图、审计结论和剩余缺口。报告只在用户随后明确调用 `$export-report` 时生成。
+
+## 边界
+
+- 用户选择本 Skill 即接受实现者与测试者不隔离；不要以风险判断为由改用完整流程。
+- 不生成持久化 E2E 测试代码，不伪造 Checker 产物，不把截图说成 Figma 视觉一致性结论。
+- 每次工具会话都必须以 `finish_fast_check` 或 `abort_fast_check` 结束；只关闭本流程启动的浏览器和服务。
+- 独立审计是完成条件；同一个实现代理的自我 review 不能替代 `$code-audit`。

package/plugins/autobest-delivery/skills/delivery-loop-fast/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "快速交付闭环"
+  short_description: "实现、自测、自纠、截图并独立审计的快速 UI 交付"
+  default_prompt: "使用 $delivery-loop-fast 根据当前功能规格快速实现，通过交互式 Playwright 自测和截图后完成独立代码审计。"
+
+policy:
+  allow_implicit_invocation: false

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

@@ -1,6 +1,6 @@
 ---
 name: export-report
-description: 从已完成或已阻断的 Autobest Delivery Maker、Runner 和 Checker 产物手动导出自测 Excel 报告。仅用于用户明确要求生成交付报告时。
+description: 从已完成或已阻断的 Autobest Delivery 标准 Runner/Checker 证据或交互式快速自测证据手动导出 Excel 报告。仅用于用户明确要求生成交付报告时。
 ---
 
 # 导出交付报告
@@ -9,7 +9,7 @@ description: 从已完成或已阻断的 Autobest Delivery Maker、Runner 和 Ch
 
 ## 输入
 
-- 用户指定的功能目录，其中包含 `spec.md`、`checker/checker-result.json` 和对应 Runner 结果。`spec.md` 可以是旧版 `## 用户故事` 结构，也可以是按 `## REQ-<SCOPE>-<序号>` 分节的新追踪结构。
+- 用户指定的功能目录，其中包含 `spec.md`，以及 `checker/checker-result.json` 和对应 Runner，或 `fast-check/runs/iteration-NN/fast-check-result.json`。`spec.md` 可以是旧版 `## 用户故事` 结构，也可以是按 `## REQ-<SCOPE>-<序号>` 分节的新追踪结构。
 - 可选的报告输出路径；必须位于功能目录内。默认写入 `featureDir/delivery-report.xlsx`。
 
 ## 执行
@@ -27,7 +27,7 @@ node <plugin-root>/scripts/export-delivery-report.mjs <feature-dir> \
   [--grouping <feature-dir>/report/report-groups.json]
 ```
 
-4. 复读脚本的 JSON 输出，向用户报告文件路径、Runner iteration、Checker/Runner 状态、API 模式、功能行数、状态计数、唯一嵌入截图数、截图放置数和分组来源。
+4. 复读脚本的 JSON 输出，向用户报告文件路径、iteration、证据来源、检查状态、API 模式、功能行数、状态计数、唯一嵌入截图数、截图放置数和分组来源。`interactive-playwright` 必须称为交互式自测，不能称为独立 Checker。
 
 报告固定使用插件资产 `assets/delivery-report-template.xlsx`，且只能生成一个名为 `自测报告` 的工作表。列固定为：页面/模块、自测点、自测方式、通过、截图1（桌面端）、截图2（移动端）。导出器根据 Runner 的 `apiMode` 自动在“自测方式”中标注“真实环境 API”或“模拟 API”；历史 Runner 没有 API 模式时不推断。不得生成原子检查明细 Sheet，不得在可见单元格中输出 story ID、scene 名、历史场景或其他执行结构。
 

package/plugins/autobest-delivery/skills/export-report/agents/openai.yaml

@@ -1,8 +1,7 @@
 interface:
   display_name: "导出交付报告"
-  short_description: "把 Maker、Runner 和 Checker 证据导出为自测 Excel"
+  short_description: "把标准验收或快速交互式自测证据导出为自测 Excel"
   default_prompt: "使用 $export-report 为指定功能目录生成交付自测 Excel 报告。"
 
 policy:
   allow_implicit_invocation: false
-

package/skills/README.md

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

package/skills/common/code-pr-submit/SKILL.md

@@ -21,6 +21,7 @@ to   = 当前分支的父分支（创建该分支时所基于的分支）
 可用 MCP 工具：
 
 - `code-mcp-pr.code-mcp-pr`
+- `code-mcp-pr.send_pr_dingtalk`
 - `code-mcp-pr.get_repo_default_branch`
 - `code-mcp-pr.guess_parent_branch`
 - `code-mcp-pr.get_branch_diff`
@@ -136,7 +137,9 @@ git log --no-merges -1 --format=%s -- "${fromBranch}"
 
 ## 创建授权
 
-如果用户本次请求明确包含“创建 PR”“提交 PR”“提 PR”等写操作意图，该请求本身就是创建授权。完成自动发现和内容生成后直接创建，不再逐项确认分支、描述或重复询问最终授权。
+如果用户本次请求明确包含“创建 PR”“提交 PR”“提 PR”等写操作意图，该请求本身就是普通目标分支的创建授权。完成自动发现和内容生成后直接创建，不再逐项确认分支、描述或重复询问最终授权。
+
+规范化 `toBranch` 后，如果它等于 `main` 或 `master`（大小写不敏感），必须在调用创建工具前单独确认：明确展示 `${fromBranch} -> ${toBranch}`，说明目标是主分支，并询问是否继续。本次请求中的初始创建意图不能代替这次确认；只有用户明确同意后才继续，用户拒绝或未回答时不创建 PR。其他目标分支不增加这一步。
 
 如果用户只要求“准备”“生成”“预览”PR，则展示以下简洁预览并停止，不调用创建工具：
 
@@ -185,15 +188,16 @@ businessSourceBranch: ${toBranch}
 prTitle: ${prTitle}
 prDescription: ${prDescription}
 reviewers: ${reviewers}
+targetBranchConfirmed: ${targetBranchConfirmed}
 dingtalkMarkdownTitle: "ADO PR 已创建"
 dingtalkMarkdownContent: ${markdownWithLiteralPrWebUrlPlaceholder}
 ```
 
-`reviewers` 未提供时省略。创建工具非幂等：调用中断或响应不明确时不自动重试，先查询或请用户核查是否已经创建。
+`reviewers` 未提供时省略。`targetBranchConfirmed` 只在 `toBranch` 为 `main/master` 且用户已经完成上述二次确认时传 `true`，其他目标分支省略；MCP 返回 `confirmationRequired=true` 时停止并向用户确认，不自行补传。创建工具会先检查相同分支方向的 active PR。调用中断或响应不明确时不自动重试，先查询或请用户核查是否已经创建。
 
 ## 返回结果
 
-成功时简洁输出：
+`created=true` 时简洁输出：
 
 ```text
 PR 创建成功
@@ -204,8 +208,25 @@ ${prWebUrl}
 
 `dingtalkSendSuccess=true` 表示已发送，`false` 表示失败，`null` 表示未请求通知；不要把 `null` 说成发送失败。
 
+`alreadyExists=true` 时不得只说“已提交”或“已存在”。明确说明没有新建 PR，并用 MCP 返回的 `prWebUrl` 输出可点击链接：
+
+```markdown
+相同分支方向的 PR 已存在，本次未重复创建：
+[查看 PR](${prWebUrl})
+```
+
+随后询问用户是否为这个已存在的 PR 再发送一次钉钉通知。用户明确同意时，使用原先生成的通知标题和正文调用一次 `code-mcp-pr.send_pr_dingtalk`：
+
+```yaml
+prWebUrl: ${prWebUrl}
+dingtalkMarkdownTitle: "ADO PR 已创建"
+dingtalkMarkdownContent: ${markdownWithLiteralPrWebUrlPlaceholder}
+```
+
+用户拒绝或未确认时停止，不发送通知。补发结果只按 `send_pr_dingtalk` 的真实返回报告；补发失败不改变 PR 已存在的状态。不得为补发通知再次调用 `code-mcp-pr.code-mcp-pr`。
+
 失败时保留 `errorMsg` 的关键信息并说明 PR 未创建、钉钉未触发。钉钉失败不改变 PR 创建成功状态。
 
 ## 完成条件
 
-结束前确认：用户值覆盖自动值；仓库信息来自当前项目；`fromBranch` 是当前或用户指定的开发分支；`toBranch` 是可解释的父分支；远端已有源分支；描述由实际材料支持；MCP 映射为 `businessTargetBranch=fromBranch`、`businessSourceBranch=toBranch`；创建结果与钉钉状态准确呈现。
+结束前确认：用户值覆盖自动值；仓库信息来自当前项目；`fromBranch` 是当前或用户指定的开发分支；`toBranch` 是可解释的父分支；`main/master` 目标已经用户二次确认；远端已有源分支；描述由实际材料支持；MCP 映射为 `businessTargetBranch=fromBranch`、`businessSourceBranch=toBranch`；新建与已存在状态没有混淆；任何已存在 PR 都显示了可点击链接；钉钉状态准确呈现。

package/skills/common/repo-setup/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: repo-setup
+description: 扫描当前代码仓库的技术栈、直接依赖、目录结构、组件库和编码规范，并在仓库根目录生成或刷新 AGENT.md 项目上下文文档。用户要求初始化、生成或更新仓库上下文时使用；只描述仓库事实，不写入 Agent/Skill 调用逻辑。
+---
+
+# 生成仓库上下文
+
+在当前 Git 仓库根目录生成 `AGENT.md`。文档只记录可由仓库文件证明的项目事实和待人工补充项，不记录本 Skill 的工作流、调用方式或其他 Agent 指令。
+
+## 边界
+
+- 开始时执行 `git rev-parse --show-toplevel`，并确认其规范化路径与当前目录一致；不在仓库根目录时停止，返回应切换到的根目录。
+- 除仓库根目录的 `AGENT.md` 外保持工作区不变。`package.json`、lockfile、配置、README 和业务源码全部只读。
+- 目录层级以仓库根目录为第 0 级，只枚举到第 2 级目录。可以读取位于第 0 至第 2 级目录中的目标文件；不递归探索更深目录。
+- 跳过 `.git`、`node_modules`、构建产物、覆盖率目录、缓存目录和二进制文件。不要读取或输出 `.env`、token、证书、registry 凭据及其他秘密值。
+- 写入前执行 `git status --short` 并记录 `AGENT.md` 是否已存在。保留所有现有改动；已存在的 `AGENT.md` 是唯一允许覆盖的文件。
+
+## 仓库扫描
+
+使用结构化解析器读取 JSON，不用正则解析 `package.json` 或 `tsconfig.json`。所有结论都保留文件路径、配置键、依赖名或源码样本作为内部证据；最终文档只写结论和必要的来源说明。
+
+1. 读取根目录 `package.json`：
+   - 提取 `name`、`version`、`private`、`packageManager`、`workspaces` 和全部 `scripts`。
+   - 汇总 `dependencies`、`devDependencies`、`peerDependencies` 和 `optionalDependencies` 中的全部直接依赖及声明版本，不把 lockfile 中的传递依赖写成直接依赖。
+   - 根据依赖和根目录配置识别框架、语言、样式方案、状态管理、UI 组件库、构建工具、包管理/monorepo 工具和测试工具。没有证据的类别标记 `【待人工补充】`。
+   - 如果没有根 `package.json`，记录缺失并继续从可见配置取证；不要猜测项目类型。
+2. 在第 2 级目录界限内识别 workspace/package manifest。只读取已经由根 `workspaces` 声明或目录概览直接发现的 `package.json`，用于确认内部包、内置组件库及其公开名称；不要沿 workspace 继续递归。
+3. 读取根目录 `tsconfig.json`。如果它通过相对路径 `extends` 本地配置，只在被引用文件仍位于仓库内且其所在目录不超过第 2 级时继续解析，直到得到显式 `compilerOptions.strict` 或到达界限。结论写为“已开启”“未开启”或 `【待人工补充】`；缺失、无法解析或继承链没有明确值时不得推断。
+4. 读取根目录 `README.md`，优先摘取标题后的首段项目说明，排除安装步骤、命令清单、徽章和通用模板文字。没有 README 或没有可确认的业务简介时写 `【待人工补充】：项目业务背景、页面用途`。
+5. 生成简化目录树：展示根目录的直接子目录，以及 `src/` 的直接子目录或文件；不要展开其他根目录的内部内容。项目没有根 `src/` 时明确写“未检测到根目录 `src/`”，不要用更深源码树替代。
+6. 识别编码规范：
+   - 检查第 0 至第 2 级内的 ESLint、Prettier、Stylelint、EditorConfig、TypeScript、测试和构建配置，以及根级贡献文档。
+   - 在第 2 级界限内选取少量有代表性的源码文件核对组件范式、类型声明、模块导入和样式组织；源码习惯只有在多个样本一致时才写成“现有代码惯例”，单一样本不升级为强制规则。
+   - 将配置中明确启用的规则写成项目应遵循的编码规则，并注明来源配置。只输出具体规则，不提 Skill 名称、Agent 行为或调用逻辑。
+7. 识别组件能力：结合直接依赖、workspace manifest 和可见源码导入，列出外部 UI 库、内部组件包、图标库、工具包及其证据。仅发现目录名但无法确认公开 API 时说明“检测到目录，公开能力待人工补充”。
+
+同一工具可能同时承担多个角色，例如 Storybook 同时是组件开发环境和测试辅助工具；按仓库证据如实列入相关类别。依赖名只能按其已知用途分类，无法确定用途时保留在直接依赖清单，不强行归类。
+
+## 写入 AGENT.md
+
+按照以下结构覆盖写入仓库根目录的 `AGENT.md`。保留所有标题；某节没有证据时保留 `【待人工补充】`。依赖较多时使用 Markdown 表格或紧凑分组，但不能遗漏直接依赖。
+
+````markdown
+# AGENT.md 项目上下文文档
+> 文件由 $repo-setup 自动生成，请人工复核并补充业务专属信息
+> 文档用途：描述本代码仓库的项目基础信息、技术约束、组件能力，供代码开发时参考
+
+## 项目简介
+<!-- 写入 README 摘要或待人工补充项；同时列出项目名称、版本和可确认的仓库形态 -->
+
+## 技术栈
+- 框架：
+- 语言：JavaScript / TypeScript，严格模式：
+- 样式方案：
+- 状态管理：
+- UI 组件库：
+- 构建工具：
+- 测试工具：
+- 包管理与 Monorepo：
+
+### 可用脚本
+<!-- 完整列出 package.json scripts；缺失时标记待人工补充 -->
+
+## 目录概览
+```text
+<!-- 根目录直接子目录 + src 直接子项，最多 2 层 -->
+```
+
+## 项目编码规范
+<!-- 写入配置明确规定的规则和稳定源码惯例；每组规则附来源 -->
+
+## 项目依赖 & 内置组件库
+<!-- 按 dependencies/devDependencies/peerDependencies/optionalDependencies 完整列出直接依赖和版本，再说明已确认的外部 UI 库、内部组件包及工具包能力 -->
+
+## 业务边界 & 业务特殊规则
+【待人工补充】：业务特殊逻辑、接口约定、页面限制、特殊业务校验规则
+````
+
+写入后重新读取 `AGENT.md`，确认 Markdown 围栏闭合、固定章节齐全，且所有技术结论都能追溯到本次允许范围内的文件。再次执行 `git status --short`，确认除原有工作区改动外，本次只新增或修改 `AGENT.md`。
+
+## 完成响应
+
+返回：
+
+- `AGENT.md` 的绝对路径。
+- 成功识别的技术栈清单。
+- 所有 `【待人工补充】` 字段。
+- `AGENT.md` 原先存在时明确说明旧文件已覆盖；原先不存在时说明已新建。
+- 明确说明未修改业务源码、`package.json` 或 lockfile。
+
+只有 `AGENT.md` 已生成、结构校验通过且写入范围检查通过时才算完成；否则报告具体失败项，不声称已经完成。

package/skills/common/repo-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Repo Setup"
+  short_description: "扫描代码仓库并生成 AGENT.md 项目上下文"
+  default_prompt: "使用 $repo-setup 扫描当前代码仓库，并在仓库根目录生成 AGENT.md 项目上下文文档。"

package/skills/common/trace-recorder/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: trace-recorder
+description: 通过 trace-mcp-recorder 启动或停止 Playwright Trace 人工录制；当用户要求打开页面录制、停止录制或获取 trace 回放链接时使用。
+---
+
+# Trace MCP Recorder
+
+将用户的自然语言请求映射到 `trace-mcp-recorder` 的 MCP 工具。`url` 独立确定被测页面；`title` 是本次录制的标题或功能描述，也可以直接填写 Bug 编号（例如 `bug3452`）。系统不额外传递独立的 Bug 字段。
+
+## 启动录制
+
+当用户要求启动、开始或打开页面进行 trace 录制时：
+
+1. 从原话提取 `url`、`version`、`title`、`operator`。支持 `key=value` 和自然语言表达，不改写用户给出的值。
+2. `url` 必填；缺少时只询问目标页面地址。其他字段缺失时不要阻断录制。
+3. 调用 `start_trace_recording`，只传入用户明确提供的可选字段。服务端会优先使用 MCP 上下文中的操作人身份。
+4. 告知用户浏览器已打开，并保留工具返回的 `uuid` 和最大录制时长；不要代替用户操作页面。
+
+示例：`trace-mcp-recorder 启动Playwright trace 访问https://cpd.dev.autobestdevops.com，version=v2.1.0 title=bug3452 operator=张三`。这里 `title=bug3452` 是本次录制的标题/功能描述，页面由 `url=https://cpd.dev.autobestdevops.com` 确定。
+
+## 停止录制
+
+用户表达“停止录制”“结束 trace”“完成录制”等意图时，调用 `stop_trace_recording`。第一次调用只会停止录制并询问是否上传；不要擅自上传。用户明确回答“上传”后，再次调用 `stop_trace_recording` 并传入 `confirm=upload`。用户回答“不上传”时，调用该工具并传入 `confirm=cancel`。上传成功后，将回放链接和 `version`、`title`、`operator`、`browserVersion` 整理给用户。
+
+若工具返回错误，如没有活动会话、后端不可达或上传失败，原样说明关键原因，不编造回放链接。

package/skills/common/trace-recorder/agents/openai.yaml

@@ -0,0 +1,11 @@
+interface:
+  display_name: "trace-recorder"
+  short_description: "启动或停止 Playwright Trace 人工录制并返回回放链接"
+  default_prompt: "使用 $trace-recorder 启动指定页面的 Playwright Trace 人工录制。"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "trace-mcp-recorder"
+      description: "启动、停止、上传 Playwright Trace 的本地 STDIO MCP 服务"
+