bugpatrol

Bugpatrol

Bugpatrol 是一支由 AI Agent 组成的 QA 团队。它会像人工测试人员一样运行用户的应用。CLI 是 npm 包 bugpatrol。使用 npx bugpatrol@latest <command> 运行。不要从源代码构建。

始终添加 @latest，因为 npx 可能会运行缓存中的旧版本。旧版本可能有不同的命令和配置布局。只有一种例外：如果仓库在 package.json 中列出了 bugpatrol，则运行 npx bugpatrol <command>，以使用仓库选定的版本。

源代码和完整文档：https://github.com/agent-labs-dev/bugpatrol

1. Bugpatrol 的功能

Bugpatrol 有以下角色：

• explorer 会启动应用、绘制应用界面地图，并报告看起来不正常的地方。它还会查看应用的控制台错误和失败请求。
• judge 会查看每条发现及其截图。它会创建问题、将发现添加到未解决的问题，或说明原因后忽略该发现。
• fixer（默认关闭）会在自己的 git 工作树中编写修复，使用分支 bugpatrol/fix-<issue>。
• retest 会从修复工作树启动应用。explorer 会重复测试流程，judge 会比较修复前后的截图。
• publish 步骤（默认关闭）会为每个已验证的修复创建 GitHub PR，并为每个尚无修复方案的重大错误创建问题。

平台：web（Playwright）、electron（CDP）、ios 和 android（Maestro）。

explorer、judge 和 fixer 都是大模型 Agent。它们各自在本地 Agent 命令行工具（claude、codex、kimi、opencode 或 pi）上运行，或使用 API 密钥（OpenRouter、Vercel AI Gateway、OpenAI、Anthropic）运行。

Bugpatrol 将所有文件保存在项目根目录下的一个 .bugpatrol/ 文件夹中。配置和应用指南会提交到版本库。本地数据存放在 .bugpatrol/runs/ 中，并由 git 忽略。第一次会话会学习例程（例如 enter-app），让后续会话更快启动，并且无需模型即可重放这些路径。例程（.bugpatrol/routines/）和应用地图（.bugpatrol/appmap.json）会提交到版本库，因此 CI 和全新克隆的仓库都可以重放它们。Bugpatrol 会编写这些文件，但绝不会提交它们：提交工作由用户完成。

2. 为仓库进行配置

按顺序执行以下步骤。只向用户询问无法从仓库中找到的信息。

2.1 必须掌握的两个事实

缺少以下两个事实，Bugpatrol 就无法执行任何操作：

1. 如何在这台机器上启动应用。
2. 如何登录应用（如果应用需要登录）。

不要猜测。在掌握这两项信息之前，不要继续执行步骤 2.3。如果无法获取其中一项，请停止并告知用户。说明你尝试了什么、缺少什么，以及需要用户提供什么。

首先阅读仓库内容。查看 package.json 中的脚本、README、CONTRIBUTING、.env.example、docker-compose.yml、E2E 测试（Playwright、Cypress、Detox、Maestro）、app.json、Info.plist 和 AndroidManifest.xml。找到以下信息：

• 平台：web、Electron、iOS、Android 或命令行应用（cli）。
• 在本地使用时启动应用的命令，例如 npm run dev。
• URL 和端口（web）、CDP 端口（Electron），或移动应用的 bundle ID 或包名。
• explorer 绝不能执行的操作，例如删除数据、向真实用户发送电子邮件或付款。

事实 1：启动应用

自行启动应用，并确认它能够运行：

• Web： 运行启动命令，然后运行 curl -sf <url> >/dev/null && echo up。检查后停止服务器。
• Electron： 使用 --remote-debugging-port=<port> 运行启动命令，然后运行 curl -sf http://127.0.0.1:<port>/json/version。
• iOS： 检查应用是否已安装在已启动的模拟器上：xcrun simctl listapps booted | grep <bundle id>。如果应用需要开发服务器（例如 Metro），也要启动它。
• Android： 检查应用是否已安装在模拟器上：adb shell pm list packages | grep <package>。

同时检查后端。如果 .env 或配置指向某个 API URL，请检查它是否有响应，例如 curl -s -o /dev/null -w '%{http_code}' <api url>。Web 应用通常可以启动，但如果后端宕机，就无法登录。

如果应用无法启动，请找出原因：缺少依赖、缺少 .env 值、数据库或后端未运行，或者应用构建尚未安装。只修复安全且仅影响本地的问题，例如 npm install。对于其他问题，请停止并询问用户。例如：

• “应用需要 DATABASE_URL。Bugpatrol 可以使用哪个数据库进行测试？”
• “iOS 应用尚未安装在模拟器上。请先使用 npx expo run:ios 构建一次。”
• “应用会调用 API_URL 中的后端。是否有可供我使用的开发或预发布后端？”

除非用户确认安全，否则绝不要让 Bugpatrol 连接生产系统。

事实 2：登录

确认应用是否需要登录：打开应用，或在代码中查找登录路由、身份验证中间件和身份验证提供方。如果应用不需要登录，请转到步骤 2.2。

如果应用需要登录，请按以下优先顺序寻找一种可行方式：

1. 应用启动时已登录。 例如：开发环境身份验证绕过、预置会话、环境变量中的会话令牌，或可安装会话的深层链接。将命令写入 app.setup。
2. 设置命令可创建测试用户。 例如：种子脚本，或 E2E 测试使用的仅限测试环境的登录端点。将其写入 app.setup，并使用 capture 从其输出中读取一个值。
3. 测试账号。 用户将电子邮件和密码设为环境变量。在 app.secrets 中列出这些变量名，并在 .bugpatrol/instructions.md 中使用 {{NAME}} 占位符编写登录步骤。

探索器无法通过一次性验证码、CAPTCHA、硬件密钥或第三方 SSO 页面。如果登录流程包含其中任何一项，应用就需要提供测试绕过方式。

许多应用使用一次性验证码登录，其 E2E 测试会使用仅限测试环境的端点来返回会话令牌。请在 E2E 设置文件中查找该端点（例如 e2e/setup/、auth.setup.ts 或 global-setup）。然后找到一个可通过令牌安装会话的 URL：OAuth 或魔法链接回调路由通常会完成此操作。在 app.setup 和应用指南中同时使用这两者：

app:
  setup:
    # One command can capture more than one value.
    - run: >-
        curl -sf -X POST "$API_URL/auth/test-login"
        -H "X-Test-Secret: $TEST_LOGIN_SECRET" -d '{"email":"[email protected]"}'
      capture:
        SESSION_TOKEN: '"token":\s*"([^"]+)"'
        USER_ID: '"userId":\s*"([^"]+)"'

## Sign in
Open http://localhost:3000/auth/callback#token={{SESSION_TOKEN}}&user_id={{USER_ID}}. Do not use the sign-in form.

模型只能看到 {{NAME}} 占位符。只有在探索器对应用执行操作时（例如打开 URL），Bugpatrol 才会填入真实值。Bugpatrol 会在所有日志和文件中隐藏该值。

测试账号的状态

测试账号决定了探索器可以测试什么：

• 引导流程。 新账号通常会先进入引导流程。引导流程可以使用探索器的大多数步骤。如果账号必须完成引导流程，请在应用指南中填写引导流程的答案，或在巡查前为账号完成一次引导流程。
• 引导流程 Bug。 要重新测试引导流程中的修复，需要使用尚未完成引导流程的账号。每次会话都创建一个新的测试用户：在设置命令中填入唯一的电子邮件地址，例如 bugpatrol-$(date +%s)@example.test。
• 数据。 新账号没有数据，因此许多页面只会显示空状态。如果主要流程需要数据，请将种子命令添加到 app.setup。

请为 Bugpatrol 使用单独的账号，不要使用 E2E 测试共用的账号，因为探索器会更改账号的数据。

如果你不知道如何登录，请停止并询问用户。提供以下选项：

• “能给我一个测试账号吗？请在 shell 中设置 TEST_EMAIL 和 TEST_PASSWORD。不要在这里粘贴它们。”
• “能否登录一次，让 Bugpatrol 使用该会话？”（例如，将会话令牌设为环境变量，或使用保持登录状态的模拟器。）
• “我可以为 Bugpatrol 添加创建测试用户的方式：种子脚本，或仅在开发环境中可用的测试专用登录端点。你希望我这样做吗？”

未经许可，不要使用他人的账号。不要在生产系统上创建测试用户。

2.2 检查机器

1. 运行 node --version。Bugpatrol 需要 Node 22 或更高版本。
2. 在应用仓库中运行 git remote -v。Bugpatrol 需要 git 和 origin 远程仓库：每个巡查周期都会拉取 origin/main。如果默认分支不是 main，请设置 agents.patrol.pull（例如 origin/master）。
3. 如果用户需要 GitHub PR 和 issue：运行 gh auth status。如果缺少 gh，请告知用户从 https://cli.github.com 安装。如果 gh 尚未登录，请告知用户运行 gh auth login。
4. 对于 Web：运行 PLAYWRIGHT_SKIP_BROWSER_GC=1 npx -y [email protected] install chromium。必须使用此确切版本，因为该捆绑包固定使用 Playwright 1.48.2。保留 PLAYWRIGHT_SKIP_BROWSER_GC=1：否则 Playwright 会删除仓库自身 Playwright 版本的浏览器。
5. 对于 iOS 或 Android：运行 maestro --version。如果缺少 Maestro，请告知用户从 https://maestro.mobile.dev 安装。确保模拟器已启动（xcrun simctl list devices booted），或仿真器正在运行（adb devices）。
6. 对于 Electron：确保应用使用 --remote-debugging-port=<port> 启动，并且启动命令会输出端口。
7. 运行 npx bugpatrol@latest --version。这可以确认该软件包能够运行。

2.3 使用你自己作为大模型运行 init

你是一个大模型 Agent，因此请使用你自己作为所有 Agent 的提供方。这样用户就不需要为这些 Agent 提供 API 密钥。

1. 找出你自己的 CLI 名称：

   你使用的是	--agent
   Claude Code	claude
   Codex	codex
   Kimi CLI	kimi
   opencode	opencode
   pi	pi（需要运行 pi install npm:pi-mcp-adapter）

2. 确认 CLI 已在 PATH 中，例如运行 command -v claude。

3. 如果你使用的是其他 Agent（例如 Cursor 或 Gemini），请使用已安装的这些 CLI 之一。如果都未安装，请向用户询问 API 密钥提供方，并使用 --agent openrouter 或 --agent vercel。

4. 在仓库根目录中运行 init，并使用 2.1 步中的启动命令以及 URL 或应用 ID：

   npx bugpatrol@latest init --yes --agent claude \
     --platform web --start "npm run dev" --url http://localhost:3000
   

   其他标志：--app-id <id>（移动端）、--explorer、--judge 和 --fixer（为某个 Agent 指定不同的提供方）。

init 会写入以下文件。它不会覆盖任何文件：

.bugpatrol/
  bugpatrol.yml     # the config: commit it
  instructions.md    # the app guide template: commit it
  runs/              # the local data: init adds .bugpatrol/runs/ to .gitignore

如果 .bugpatrol/bugpatrol.yml 已存在，请改为编辑该文件。不要在项目根目录中写入 bugpatrol.yml：Bugpatrol 不会在那里读取它。如果在那里找到旧文件，运行 npx bugpatrol@latest doctor 会显示用于移动它的命令。

2.4 修正 .bugpatrol/bugpatrol.yml

阅读 init 写入的文件，并修正它无法获知的值。文件中的路径（source、cwd、instructions）相对于项目根目录，也就是包含 .bugpatrol/ 的文件夹。命令可在项目中的任意文件夹运行。

带开发服务器的 Web 应用：

version: 1

app:
  platform: web
  source: .                          # the repo that the fixer edits
  setup:
    - run: npm run dev
      background: true               # keep the server alive for the session
      readyWhen: 'Local:|ready|listening'   # regex on the output; start when it matches
      timeoutMs: 120000
  connect:
    url: http://localhost:3000
  instructions: .bugpatrol/instructions.md
  secrets: [TEST_EMAIL, TEST_PASSWORD]   # env vars; the explorer sees {{TEST_EMAIL}}

如果用户已在运行应用，或应用已部署，请省略 setup，只设置 connect.url。

Electron 应用：

version: 1

app:
  platform: electron
  source: .
  setup:
    - run: ./scripts/start-test-app.sh
      capture: { CDP_PORT: 'CDP :(\d+)' }    # first regex group becomes ${CDP_PORT}
  teardown:
    - run: ./scripts/stop-test-app.sh
  connect:
    cdp: http://127.0.0.1:${CDP_PORT}
  instructions: .bugpatrol/instructions.md

iOS 或 Android 应用：

version: 1

app:
  platform: ios                      # or android
  source: .
  setup:
    - run: npx expo start --port 8083
      background: true
      readyWhen: 'Waiting on http'
      timeoutMs: 180000
  connect:
    appId: com.example.app           # bundle ID (iOS) or package name (Android)
    # device: <simulator UDID or emulator serial>   # default: the booted one
  instructions: .bugpatrol/instructions.md

设置命令字段：

字段	用途
run	Shell 命令
cwd	相对于项目根目录的文件夹
capture	{ NAME: 'regex' }。第一个分组会在后续命令和 connect 中变为 ${NAME}，在浏览器探索器中变为 {{NAME}}。Bugpatrol 会将其视为机密
background	对于持续运行的服务器，设为 true
readyWhen	对于后台命令：匹配其输出的正则表达式
timeoutMs	时间限制。默认值为 600000

teardown 使用相同的字段。如果 setup 启动的进程不会自行停止，请用它来停止该进程。

2.5 编写 .bugpatrol/instructions.md

此文件是面向浏览器探索器的纯英文内容。init 会写入一个模板。将模板替换为写给新的人类测试人员的说明。这是根据代码库编写的初稿：在运行的第 3 步中，浏览器探索器查看应用后，你需要修正它。请包括：

• 用一两句话说明应用的用途及其主要区域。
• 如何登录。机密信息使用 {{NAME}} 占位符。切勿在此文件中写入真实密码。
• 如果应用有引导流程，说明如何完成该流程。
• 最重要的工作流。
• 一个绝不可执行的操作列表。

# Acme
Acme is a project tracker. The sidebar lists the projects. Each project has a board and a settings page.

## Sign in
Sign in with the email {{TEST_EMAIL}} and the password {{TEST_PASSWORD}}.

## Important flows
- Make a project, add three tasks, and move a task across the board.

## Never do these things
- Do not delete a project that you did not make.
- Do not invite a person by email.
- Do not open the billing page.

2.6 检查密钥

检查哪些密钥已设置。不要打印密钥值：

for k in OPENROUTER_API_KEY AI_GATEWAY_API_KEY OPENAI_API_KEY ANTHROPIC_API_KEY; do
  test -n "$(printenv $k)" && echo "$k set" || echo "$k missing"
done

• API 密钥 Agent。 如果某个 Agent 使用 runtime: model，则必须设置其密钥。OpenRouter 密钥：https://openrouter.ai/keys。Vercel AI Gateway 密钥：https://vercel.com/ai-gateway。

如果缺少密钥，请让用户在 shell 中设置。不要要求用户将密钥粘贴到聊天中。

每个 Agent 的提供方都在 agents.<role>.use 中：

use:	提供方	所需条件
claude、codex、kimi、opencode、pi	本地 Agent CLI（包含适用于该角色的正确标志的预设）	CLI 位于 PATH 中，且已登录
{ runtime: model, via: openrouter, model: z-ai/glm-5.3-flash }	OpenRouter	OPENROUTER_API_KEY
{ runtime: model, via: vercel, model: <id> }	Vercel AI Gateway	AI_GATEWAY_API_KEY
{ runtime: model, via: openai, model: <id> }	OpenAI	OPENAI_API_KEY
{ runtime: model, via: anthropic, model: <id> }	Anthropic	ANTHROPIC_API_KEY
{ runtime: model, via: custom, model: <id>, endpoint: <url> }	兼容 OpenAI 的端点	BUGPATROL_MODEL_API_KEY
{ runtime: cli, command: '...' }	完整命令，可添加额外标志	CLI 位于 PATH 中

用户询问该使用哪个模型时，请从此表中推荐。为 judge 选择最强的模型，为 explorer 选择快速、低成本的模型。每个 Agent 应使用哪个模型中提供了各模型对应的 use: 配置。

Agent	所需能力	Anthropic	OpenAI	其他实验室（OpenRouter）
Explorer	视觉能力、计算机操作、可靠的工具调用、低成本	claude-sonnet-5	gpt-6-luna	google/gemini-3.8-flash
Judge	精准度、精细的视觉细节、清晰的写作	claude-opus-5-5	gpt-6-sol	moonshotai/kimi-k3
Fixer	强大的编码能力，以 Agent CLI 运行	使用 --model claude-opus-5-5 的 claude	使用 -m gpt-6-astra 的 codex	使用 Kimi K3 的 kimi

命令会通过 stdin 和 {prompt}（一个文件）接收提示词，通过 {mcp}（一个配置文件）或 {mcpUrl} 接收该角色的 MCP 工具，并通过 {workdir} 接收工作树。

每个 Agent 命令启动应用前，Bugpatrol 都会检查该 Agent 的 LLM。如果缺少密钥或 CLI，命令会停止并说明如何修复。

3. 运行

在项目中运行每条命令。Bugpatrol 会在当前文件夹或其上级文件夹中查找 .bugpatrol/。

1. 先运行一个简短会话。这样可以验证 Bugpatrol 能否启动应用并登录：

   npx bugpatrol@latest explore --steps 10 --goal "Sign in, then open the main screen"
   

   阅读输出。如果设置失败，或浏览器停留在登录界面，请修改 .bugpatrol/bugpatrol.yml 或 .bugpatrol/instructions.md，然后重新运行。如果无法解决问题，请停止并告知用户失败原因。

   只有当浏览器到达应用主界面时才继续。如果它停留在引导流程中，请阅读测试账号的状态。

2. 运行完整的浏览器会话：

   npx bugpatrol@latest explore
   npx bugpatrol@latest explore --goal "Test the checkout flow" --steps 40
   

   该命令会运行 setup、探索、生成报告并运行 teardown。这可能需要几分钟。阅读输出。如果设置失败，请修改 .bugpatrol/bugpatrol.yml 并重新运行。

3. 根据浏览器的实际观察修正 .bugpatrol/instructions.md。你最初是根据源代码写的草稿。现在浏览器已经使用过该应用，因此草稿可能有误或不完整。

   1. 阅读 .bugpatrol/appmap.json（页面及其连接方式）和 npx bugpatrol@latest memory list 的输出（经验教训）。这些经验教训会保留在这台机器上，因为 git 会忽略 .bugpatrol/runs/。浏览器会在每次会话开始时读取 instructions.md，而且该文件会提交到版本库，因此要把每台机器都必须知道的内容写在里面。
   2. 重新编写该文件：
      • 按照应用中的显示名称列出主要区域，并说明如何进入每个区域。
      • 将登录和引导步骤修正为实际可行的路径。
      • 添加页面显示、但草稿中遗漏的流程。
      • 将你观察到的、会删除数据、向真实用户发送消息或产生费用的操作，添加到 绝不可执行的操作 列表中。
   3. 继续之前，先向用户展示新文件。询问两个问题：哪些流程最重要，以及 绝不可执行的操作 列表中还遗漏了什么。用户对此比代码库更了解。
   4. 根据用户的回答进行修改。保留机密信息的 {{NAME}} 占位符。

4. 评估会话：

   npx bugpatrol@latest judge
   

   评估器会读取最近包含候选项的浏览器会话，并跳过已评估过的候选项。第一行会列出会话和新增候选项数量。若只评估一个会话，请添加 --session <id>。

5. 显示问题：

   npx bugpatrol@latest issue list
   

6. 向用户展示仪表板。仪表板会显示截图、步骤和页面关系图：

   1. 检查仪表板是否已在运行：

      curl -fsS http://127.0.0.1:4311/api/overview > /dev/null && echo running
      

   2. 如果尚未运行，请在后台启动。它不会自动停止：

      npx bugpatrol@latest dashboard
      

   3. 等待出现 Bugpatrol dashboard on http://127.0.0.1:4311 这一行。

   4. 在用户的浏览器中打开该 URL：macOS 使用 open，Linux 使用 xdg-open，Windows 使用 start。

   5. 告诉用户要查看哪个页面。请参阅仪表板中的表格。

   6. 同时提供简短的文字摘要：各严重级别的问题数量，以及每个 critical 或 major 问题的标题。

   7. 告诉用户下一步可以做什么：启用修复器、启用 GitHub，或启动巡查。启用修复器或 GitHub 前，请先征求用户同意。

   会话结束时，仪表板会实时更新。你可以在运行 explore 前启动仪表板，让用户观看浏览器的操作。

可选：让它修复 Bug

只有在用户同意后才启用修复器，因为修复器会写入代码：

agents:
  fixer:
    enabled: true
    minSeverity: minor
    commitMessage: 'fix(app): {title}'     # match the repo's commit style and hooks: read `git log --oneline`
    retest: { prepare: npm ci }            # installs the dependencies in each new worktree
    verify: npm run typecheck && npm test  # Bugpatrol runs this after each fix
    use: claude                            # or codex, kimi, opencode, pi

• 将 prepare 设置为仓库包管理器的安装命令，例如 pnpm install --frozen-lockfile。Bugpatrol 会在修复器启动前以及每次重新测试前，在每个新的工作树中运行该命令。
• 将 verify 设置为修复必须通过的检查。claude 修复器预设可以编辑文件，但无法运行命令，因此由 Bugpatrol 自行运行 verify。如果 verify 失败，修复就会失败，修复器也会收到包含错误信息的经验教训。下一次修复尝试会获得完整输出，并修复同一处更改。经过 fixer.attempts（默认值为 3）次尝试后，修复器会放弃该问题。

npx bugpatrol@latest fix                     # fix the worst open issues, then retest each fix
npx bugpatrol@latest fix --issue <id>
npx bugpatrol@latest retest --issue <id>

该命令会列出每项修复及其状态和分支。修复器只会在 .bugpatrol/runs/worktrees/ 中工作，绝不会更改用户的检出目录。

重新测试后，每项修复都会得到一个判定：✅ 已修复、❌ 未修复（修复器会重试）或 ❔ 不明确。不明确表示探索器在重新测试时无法访问该屏幕，通常是因为测试账户的状态。请告知用户每项修复的判定结果。

可选：发布到 GitHub

只有在用户同意后才启用 GitHub，因为这会向团队的仓库写入内容。启用前请告知用户它会执行的操作：

• 为每项修复创建一个 PR；对于严重性达到 issueMinSeverity 或更高且没有修复方案的每个 Bug，创建一个 GitHub issue。
• 创建 bugpatrol 标签，并推送包含报告截图的孤立分支 bugpatrol-assets。
• 为每项修复推送一个分支：bugpatrol/fix-<issue>。

这需要已登录且拥有仓库推送权限的 gh CLI。使用 gh auth status 或 npx bugpatrol@latest doctor 检查。

agents:
  github:
    enabled: true
    pullRequests: draft          # draft | ready
    issueMinSeverity: major

请按以下顺序执行：

1. 在本地生成报告，不会向 GitHub 发布任何内容：

   npx bugpatrol@latest publish --dry-run
   

2. 向用户展示草稿列表，并告知每个草稿文件在 .bugpatrol/runs/publish/ 中的路径。

3. 询问用户是否允许发布。只有得到肯定答复后才发布：

   npx bugpatrol@latest publish
   

4. 告知用户每个 PR 和 issue 的 URL。该命令会打印这些 URL。

5. 持续监控 CI，直到每个 PR 的检查都通过。修复器会修复失败的检查并推送新的提交：

   npx bugpatrol@latest ci --wait
   

   如果输出显示 A person must look at it，请向用户提供 PR URL 和失败检查的名称。

要从 GitHub 读取 PR 和 issue 的状态，请运行 npx bugpatrol@latest github sync。团队关闭且未合并的 PR 会成为一条经验教训；团队以“暂不计划”为由关闭的 issue 会被视为驳回。完整参考文档：https://github.com/agent-labs-dev/bugpatrol/blob/main/docs/github.md

可选：审查拉取请求

review 会在运行中的应用里测试团队的一个拉取请求。它会分别从拉取请求提交和其合并基点启动应用，在两者上重复相同的流程，并发布 GitHub 审查。拉取请求引入的每个问题，都会作为评论发布在导致该问题的变更行上。审查不会阻止合并，除非启用了 agents.review.block，且重放两次都证实某项声明不成立。

npx bugpatrol@latest review <pr> --dry-run   # write the review to .bugpatrol/runs/reviews/pr-<pr>.md
npx bugpatrol@latest review <pr>             # post the review; it edits the same PR comment on each push

• 需要已登录的 gh。要发布审查，还需要 agents.github.enabled: true。
• 它会在这台机器上运行拉取请求的代码，并使用应用的密钥。它会拒绝来自 fork 的拉取请求。只有在用户阅读差异并表示同意后，才添加 --allow-fork。
• 同一台机器上有巡检运行时，它不会启动。
• 先运行 --dry-run，向用户展示文件，并且只有在用户同意后才发布。
• --claims（或 agents.review.claims: true）还会列出拉取请求声称实现的内容：优先取自其描述中的 ## Claims 列表，否则取自标题、描述、提交和已关闭的问题。Bugpatrol 会在两种构建上重放每项声明的流程，并为每项声明给出判定（proven、not-proven、partly-proven、untested）及其证据（判定者为 judge 时为 explored，同时也会使用重放画面）。声明流程保存在 .bugpatrol/runs/reviews/pr-<n>/ 中。在 Web、Electron、iOS 和 Android 上，如果 PATH 中有 ffmpeg，Bugpatrol 会录制每次重放，审查中会显示两种构建的 GIF，并附上完整 MP4 的链接。没有 ffmpeg 时则显示截图。已关闭的 Bugpatrol 问题会作为单独的声明处理，由不使用模型的方式判定，证据为 replay：它已提交的复现流程会在两种构建上重放，其错误检查必须在基准构建上成立、在拉取请求构建上失败。如果该错误在基准构建上没有出现，则判定为 untested。对于 cli 应用，每个步骤都会在终端中运行一条命令（需要 python3）；探索器可以添加针对退出代码和输出的精确检查，并据此判定结果，证据为 assertion。审查会显示每个终端会话的 GIF（无需 ffmpeg 绘制），并附上 .cast 文件链接。对于 api 应用，检查针对最后一次响应（状态代码、正文中的文本）；审查会以相同方式显示每种构建的 HTTP 记录，并对凭据进行脱敏。对于 cli 或 api 应用中声称行为保持不变的声明（例如重构、新增分页），会在两种构建上重放相同的命令或请求，并对输出进行差异比较；比较前会规范化时间、UUID、十六进制 ID、Unix 时间、持续时间和 JSON 键顺序。输出相同则判定为 proven，有差异则判定为 not-proven 并列出变更行，证据为 assertion。启用阻止功能后，必须在两种构建上再次重放，且差异再次出现。
• agents.review.block: true 会设置一个 Bugpatrol claim check 检查运行（令牌需要 checks: write）。只有当某项声明由不使用模型的代码判定为 not-proven，证据为 replay 或 assertion，并且第二次重放再次得到相同结果时，检查才会失败，且 review 以状态码 1 退出。复现声明和行为保持不变的声明会在两种构建上各重放第二次。若第二次重放由代码判定出不同结果，则该声明会变为 untested（“重放结果不稳定”）。judge 给出的判定绝不会导致检查失败。

完整参考：https://github.com/agent-labs-dev/bugpatrol/blob/main/docs/github.md#7-review-a-pull-request

可选：全天运行

npx bugpatrol@latest patrol --once       # one full cycle: setup, explore, judge, teardown, fix, retest, publish
npx bugpatrol@latest patrol --once --force  # the same, also when the commit did not change
npx bugpatrol@latest patrol              # repeat every agents.patrol.intervalMinutes (default 30); a cycle runs only when origin/main has a new commit

patrol 不会自行停止。请在后台或单独的终端中运行。

4. 查看结果

仪表板

npx bugpatrol@latest dashboard               # http://127.0.0.1:4311
npx bugpatrol@latest dashboard --port 5000

仪表板不会自行停止。请在后台运行它，在用户的浏览器中打开该 URL，并将 URL 提供给用户。它仅监听 127.0.0.1，并且是只读的。如果端口 4311 已被其他程序占用，请添加 --port。

页面	显示内容	用户提出以下问题时展示
概览	各 Agent 当前在做什么以及花费了多少、需要人工处理的问题、实时屏幕，以及目前发现的屏幕	“Bugpatrol 在做什么？”
问题	每个问题的截图、步骤、评审者给出的原因、修复差异、修复前后的重新测试结果，以及 GitHub 状态	“它发现了哪些 Bug？”“修复有效吗？”
活动	以时间线形式展示每个会话	“探索器做了什么？”
屏幕	屏幕及其连接关系图	“它测试了应用的哪些部分？”
记忆	Agent 学到的经验	“它对我的应用了解多少？”

终端

命令	用途
npx bugpatrol@latest issue list	按严重程度从高到低列出问题
npx bugpatrol@latest issue dismiss <id> --reason "..."	将问题关闭为非 Bug。此问题不会再次出现
npx bugpatrol@latest issue reopen <id>	重新打开已忽略的问题
npx bugpatrol@latest memory list	列出 Agent 学到的经验
npx bugpatrol@latest memory add --role explorer "text"	添加经验，例如有关应用的提示
npx bugpatrol@latest replay <routine-id>	不使用模型，重放已学习的例程
npx bugpatrol@latest worktrees clean	移除已完成修复的工作树

文件

要向用户总结结果，请读取以下文件：

路径	内容
.bugpatrol/runs/issues/<id>.json	单个问题：title、severity、status、body（评审者的报告）、judgement.reason 和 evidence（截图）
.bugpatrol/runs/fixes/<id>.json	单个修复：status、branch、diff、retests 和 pr
.bugpatrol/runs/reviews/pr-<number>.json	单个拉取请求的最新评审：findings（每项均带有一个 verdict）以及 posted.url
.bugpatrol/runs/sessions/<id>/	单个探索器会话及其截图
.bugpatrol/appmap.json	探索器发现的屏幕。请提交此文件
.bugpatrol/routines/<id>.json	例程，以及每个问题的复现例程（repro-<hash>）。请提交这些文件
.bugpatrol/runs/memory.json	经验

严重程度从高到低依次为：critical、major、minor、cosmetic。

问题状态	含义
new	评审者已提交该问题。它尚未出现在 GitHub 上
filed	该问题已出现在 GitHub 上
fixing	修复器正在处理该问题
fix-proposed	修复正在等待评审或等待其拉取请求
fixed	修复已验证，或该问题已在 GitHub 上以已完成状态关闭
dismissed	人工或 GitHub 已将其关闭为非 Bug。此问题不会再次出现

每个 session.json 中的 costUsd 仅统计 Bugpatrol 发起的 API 调用：runtime: model Agent。使用本地 Agent CLI（claude、codex、kimi、opencode、pi）会消耗用户自己的套餐额度，Bugpatrol 无法获知其费用。

每个 session.json 还包含 tokens 和 tokensByModel。概览页面会显示最近 7 天各 Agent 和模型的 Token 用量表格。用户询问费用或想比较模型时，请展示此表格，并提供每个会话的 Token 数量。

规则

• 运行 CLI 时使用 npx bugpatrol@latest，除非仓库在 package.json 中列出了 bugpatrol。
• 如果没有明确的应用启动方式和登录方式，请勿继续。如果没有，请询问用户。
• 切勿打印、记录或提交密钥值。将密钥放入环境变量，并在 app.secrets 中列出其名称。
• 除非用户确认安全，否则切勿让 Bugpatrol 使用生产数据。
• 启用 agents.fixer 或 agents.github 前，请先征求用户同意。
• 请勿手动编辑 .bugpatrol/runs/ 中的文件。请使用 CLI 命令。
• 如果有人类用户已驳回问题或关闭 PR，请勿撤销该决定。

故障排除

问题	操作
Web driver requires app.connect.url or run.url	设置 app.connect.url
设置超时	修正 readyWhen 正则表达式，或增大 timeoutMs
Playwright 找不到 Chromium	运行 PLAYWRIGHT_SKIP_BROWSER_GC=1 npx -y [email protected] install chromium
探索器停留在登录界面	在 .bugpatrol/instructions.md 中写明更清晰的登录步骤，并检查密钥是否已设置
Electron 无法连接	确保应用会打开 CDP 端口，并且 capture 会从输出中读取该端口
移动端无法连接	启动模拟器或仿真器，检查 maestro --version，并检查 connect.appId
No .bugpatrol/bugpatrol.yml found	在项目根目录运行 npx bugpatrol@latest init
Bugpatrol now keeps its config in .bugpatrol/	旧版本会将配置写入根目录。请运行提示中的命令
Judging 0 new candidate(s)	判定器已处理这些候选项。请再次运行 explore 以查找新候选项
探索器将步骤耗在引导流程中	阅读测试账户的状态
重新测试的判定结果为 ❔ 不明确	探索器在重新测试时未到达相应界面。请检查测试账户的状态
GitHub is off 或 The fixer is off	先询问用户，然后将 agents.github.enabled 或 agents.fixer.enabled 设为 true
explore 后没有问题	运行 npx bugpatrol@latest judge。判定器会提交问题
启动时出现 ... is not set 或 ... is not on PATH	设置密钥、安装 CLI，或更改 agents.<role>.use

完整文档：https://github.com/agent-labs-dev/bugpatrol/tree/main/docs