bugAgent

官方

将bugAgent连接到任何兼容MCP的AI客户端。直接从AI编码助手中提交、分类和管理缺陷、功能请求等。无需切换上下文，无需复制粘贴——只需描述问题，bugAgent会处理其余部分。

访问 bugagent.com

你可以用 bugAgent MCP 做什么？

用通俗英语描述一个 bug，bugAgent 会为你归档、分类并管理它。

归档并自动分类 bug — 用自然语言让助手提交 bug 或功能请求；create_bug_report 会自动将其归入 19 种类型之一。
列出并筛选报告 — 查询项目中最近或严重的 bug；list_bug_reports 可按项目、严重程度、状态等条件筛选。
认领并处理队列 — 让代理用 pick_next_bug 选取下一个优先 bug，并通过 claim_bug 原子化认领。
运行安全扫描 — 使用 run_security_scan 对 URL 触发漏洞扫描，并通过 get_security_results 查看结果。
生成开发者笔记 — 针对任何 bug 报告，通过 push_to_claude 获取 AI 生成的根因分析和修复建议。

文档

MCP v1

导航

模型上下文协议

MCP

将 bug_Agent_ 连接到任何兼容 MCP 的 AI 客户端。

直接从你的 AI 编程助手中提交、分类并管理缺陷、功能请求以及更多内容。无需切换上下文，无需复制粘贴——只需描述问题，bug_Agent_ 会处理其余部分。

Discord 社区 support@bugagent.com

快速开始

bug_Agent_ MCP 服务器让 AI 客户端能够通过模型上下文协议创建、查询并管理缺陷报告、功能请求、增强项等。它在本地运行，并与 bug_Agent_ 的云 API 通信。

获取你的 API 密钥

创建一个免费账户；新工作区所有者会直接进入 API 密钥设置页面。回归用户可以从设置 → 开发者 → API 密钥生成密钥。

配置你的 AI 客户端

在客户端的配置中将 bug_Agent_ 添加为 MCP 服务器（参见下面的设置）。

开始提交缺陷

用自然语言描述一个缺陷，bug_Agent_ 会自动分类、丰富并存储它。

快速示例

# Create a bug report
"File a bug: Login button is unresponsive on iOS Safari.
Steps: tap login, nothing happens. Expected: navigate to
dashboard. Severity: high."

# bugAgent auto-classifies as UI bug, severity high

# File a feature request
"Feature request: Add dark mode toggle to the
settings page. Users have asked for this in surveys."

# Auto-classified as feature-request, severity medium

设置

安装

无需全局安装。使用 npx 按需运行 MCP 服务器：

npx @bugagent/mcp-server

配置你的 API 密钥

首次连接时，bug_Agent_ 会提示你输入 API 密钥。你也可以通过环境变量设置它：

export BUGAGENT_API_KEY=ba_live_your_key_here

从 bug_Agent_ 控制台获取你的 API 密钥。

MCP 客户端配置

将以下内容添加到你的 MCP 客户端配置文件中：

mcp.json

{
  "mcpServers": {
    "bugagent": {
      "command": "npx",
      "args": ["-y", "@bugagent/mcp-server"],
      "env": {
        "BUGAGENT_API_KEY": "ba_live_your_key_here"
      }
    }
  }
}

💡

将 ba_live_your_key_here 替换为控制台中的实际 API 密钥。

连接到服务器

bug_Agent_ MCP 服务器运行在 https://mcp.bugagent.com/mcp 上，采用 Streamable HTTP 传输。可从下面八个客户端中的任意一个连接——选择适合你工作流程的那一个。

对于一份小型可直接复制的配置、范围限定密钥指南以及安全的入门提示，请使用公共 MCP 快速入门。

🔑

首先获取你的 API 密钥。 登录设置 → 开发者，点击 创建 API 密钥，并复制该值（以 ba_live_ 开头）。你只会看到一次，所以请将其粘贴到安全的地方。下面的每个示例都使用此密钥。

选项 1 — MCP Inspector（Web UI，推荐首次测试使用）

官方的 Anthropic 工具。它会启动一个本地 Web UI，你可以在其中点击浏览每个工具、填写参数并查看响应。零配置，无需 IDE。

macOS（终端）

终端

npx @modelcontextprotocol/inspector

Windows（PowerShell 或 CMD）

PowerShell

在打开的浏览器 UI 中：

传输类型：选择 Streamable HTTP
URL：https://mcp.bugagent.com/mcp
连接类型：选择代理（默认——Inspector 通过本地 Node 进程代理以绕过浏览器 CORS）
点击 身份验证 选项卡 → 添加自定义标头：
- 标头名称：Authorization
- 值：Bearer ba_live_YOUR_KEY_HERE
点击连接。你会在左侧面板中看到所有 110 多个 bug_Agent_ 工具。
点击任意工具（例如 list_bug_reports），填写参数，点击 运行工具。响应显示在右侧。

先决条件：Node.js 18 或更高版本。如果你没有，请从 nodejs.org 安装。

选项 2 — Claude Desktop（Mac + Windows）

如果你使用 Claude Desktop 应用，可以将 bug_Agent_ 添加为永久 MCP 服务器。之后 Claude 将在每次对话中都能使用所有 bug_Agent_ 工具。

macOS

打开 Claude Desktop → 菜单栏 Claude → 设置 → 开发者 → 编辑配置。这会打开 ~/Library/Application Support/Claude/claude_desktop_config.json。
在 mcpServers 下添加 bug_Agent_ 条目： claude_desktop_config.json

{  
  "mcpServers": {  
    "bugagent": {  
      "type": "http",  
      "url": "https://mcp.bugagent.com/mcp",  
      "headers": {  
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"  
      }  
    }  
  }  
}

保存文件并完全退出 Claude Desktop（Cmd+Q，不只是关闭窗口）。
重新启动 Claude Desktop。聊天输入框底部的工具锤子图标现在应该会显示 bug_Agent_ 工具。
试试看：输入*"列出我最近的 5 个缺陷报告"*——Claude 会自动调用 list_bug_reports。

Windows

打开 Claude Desktop → 文件 → 设置 → 开发者 → 编辑配置。这会打开 %APPDATA%\Claude\claude_desktop_config.json（通常为 C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json）。
添加与 macOS 部分所示相同的 JSON 代码块。
保存文件并从系统托盘中完全退出 Claude Desktop（右键点击 Claude 图标 → 退出），然后重新启动。
工具锤子图标将显示 bug_Agent_ 工具。

选项 3 — Claude Code（CLI）

如果你从终端使用 Claude Code（Claude 的 CLI 版本），可以用一条命令注册 bug_Agent_ 服务器。在 macOS、Linux 和 Windows 上操作方式相同。

终端 / PowerShell

claude mcp add --transport http bugagent https://mcp.bugagent.com/mcp \
  --header "Authorization: Bearer ba_live_YOUR_KEY_HERE"

然后重启你的 Claude Code 会话。验证它已连接：

claude mcp list

你应该会在列表中看到 bugagent 并带有一个绿点。在任何聊天中开始使用工具："显示我本月的探索使用量。"

以后要移除它：

claude mcp remove bugagent

选项 4 — OpenAI Codex CLI

如果你使用 OpenAI Codex CLI，请将 bug_Agent_ 添加到 ~/.codex/config.toml 以进行永久注册，或内联传递配置以进行一次性会话。

永久注册（添加到配置）

~/.codex/config.toml

[[mcp_servers]]
name = "bugagent"
type = "http"
url  = "https://mcp.bugagent.com/mcp"

[mcp_servers.headers]
Authorization = "Bearer ba_live_YOUR_KEY_HERE"

内联——单次会话

终端

codex \
  --mcp-server '{"name":"bugagent","type":"http","url":"https://mcp.bugagent.com/mcp","headers":{"Authorization":"Bearer ba_live_YOUR_KEY_HERE"}}' \
  "list the last 5 bug reports"

Codex 会自动根据你的自然语言提示解析工具调用。试试看："按严重性排序列出我未解决的缺陷。"

选项 5 — Cursor（Mac + Windows）

Cursor 内置 MCP 支持。添加 bug_Agent_ 一次，Cursor 内的 AI 助手就可以提交缺陷、列出报告、运行扫描等，而无需离开编辑器。

打开 Cursor → 设置（Mac 上 Cmd+, / Windows 上 Ctrl+,）→ 左侧边栏中的 MCP。
点击 + 添加新的 MCP 服务器。
选择 HTTP 传输类型。
填写：
- 名称：bugagent
- URL：https://mcp.bugagent.com/mcp
- 标头名称：Authorization
- 标头值：Bearer ba_live_YOUR_KEY_HERE
点击保存。连接时 Cursor 会显示绿色指示器。
打开 Cursor 的聊天（Cmd+L / Ctrl+L）并输入*"创建一个标题为 '登录已损坏' 且严重性为高的缺陷报告。"* Cursor 将调用 create_bug_report。

替代方案：Cursor 也会读取 ~/.cursor/mcp.json（Mac）或 %USERPROFILE%\.cursor\mcp.json（Windows）。添加与 Claude Desktop 部分所示相同的 JSON 格式。

选项 6 — 带有 Continue 扩展的 VS Code（Mac + Windows）

如果你更喜欢 VS Code，Continue 扩展原生支持 MCP 服务器。

从 VS Code 市场安装 Continue 扩展。
打开 Continue 的配置：命令面板（Cmd+Shift+P / Ctrl+Shift+P）→ Continue: 打开 config.json。文件位于：
- macOS：~/.continue/config.json
- Windows：%USERPROFILE%\.continue\config.json
添加一个 mcpServers 条目： ~/.continue/config.json

{  
  "mcpServers": [  
    {  
      "name": "bugagent",  
      "type": "streamable-http",  
      "url": "https://mcp.bugagent.com/mcp",  
      "requestOptions": {  
        "headers": {  
          "Authorization": "Bearer ba_live_YOUR_KEY_HERE"  
        }  
      }  
    }  
  ]  
}

保存。Continue 将自动重新加载并在侧边栏中显示 bug_Agent_ 工具。
打开 Continue 聊天面板并尝试："列出我的安全扫描。"

其他支持 MCP 的 VS Code 扩展：Cline、Roo Code 和 Windsurf（分支）都遵循类似的 JSON 配置模式，包含 mcpServers 键和 HTTP 传输。

选项 7 — 支持 OAuth 的主机（以 Claude.ai 网页版为例）

某些 MCP 主机通过 OAuth 2.0 进行身份验证，并要求预先提供静态的 client_id 和 client_secret，而不是接受不记名 API 密钥。对于这些主机，你需要从 bug_Agent_ 仪表板生成一对工作区范围的 OAuth 凭据，并将其粘贴到主机的连接器表单中。这些凭据与 MCP 主机无关——任何支持授权码 + PKCE 的 OAuth 客户端都可以使用它们。下面的演练使用 Claude.ai 网页应用作为最常见的示例。

在 bug_Agent_ 中：打开 设置 → 开发者 → MCP 连接器。点击 生成连接器，为其命名以描述主机（例如*"Claude.ai（工作）"*），粘贴你的 MCP 主机要求的重定向 URI（对于 Claude.ai 网页应用，那是 https://claude.ai/api/mcp/auth_callback——有关其他主机，请查看你的主机连接器文档），并选择机密作为身份验证方法。复制成功屏幕上仅显示一次的 client_id 和 client_secret。
在你的 MCP 主机的连接器 / OAuth 设置中，粘贴：
- 服务器 URL：https://mcp.bugagent.com/mcp
- 客户端 ID + 客户端密钥：来自步骤 1
- 授权 URL：https://mcp.bugagent.com/authorize
- 令牌 URL：https://mcp.bugagent.com/token 对于 Claude.ai 特别说明：转到 claude.ai/customize/connectors 并点击 添加 MCP 连接器。
保存。主机将你重定向到 bug_Agent_ 进行登录（Google 或电子邮件/密码——无论你使用哪种方式登录仪表板）并批准同意，然后完成 OAuth 握手。
从相同的“设置”页面管理并撤销已生成的连接器。撤销是立即生效的——该连接器的下一个请求将返回 invalid_client。

注意：Claude Code、Cursor、VS Code 和 MCP Inspector 不需要此流程——它们会自动处理动态客户端注册（RFC 7591），并通过如上所示的 API 密钥进行身份验证。MCP 连接器表单仅适用于需要静态 OAuth 凭据的主机。

选项 8 — 使用 curl 直接 HTTP（终端）

如果你想在没有客户端的情况下直接测试服务器，或将其集成到脚本中，可以使用 curl 访问 HTTP 端点。MCP 协议是在 Streamable HTTP 上的 JSON-RPC 2.0。

macOS / Linux

终端

# Set your API key as a variable
export BUGAGENT_API_KEY="ba_live_YOUR_KEY_HERE"

# 1. List all available tools
curl -N -s https://mcp.bugagent.com/mcp \
  -H "Authorization: Bearer $BUGAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 2. Call a tool — list 5 reports from a specific project
curl -N -s https://mcp.bugagent.com/mcp \
  -H "Authorization: Bearer $BUGAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"list_bug_reports",
      "arguments":{"project":"bugagent","limit":5}
    }
  }'

Windows（PowerShell）

PowerShell

# Set your API key
$env:BUGAGENT_API_KEY = "ba_live_YOUR_KEY_HERE"

# Use Invoke-RestMethod (PowerShell's curl equivalent)
$headers = @{
  "Authorization" = "Bearer $env:BUGAGENT_API_KEY"
  "Content-Type" = "application/json"
  "Accept" = "application/json, text/event-stream"
}

# 1. List all tools
$body = '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Invoke-RestMethod -Uri "https://mcp.bugagent.com/mcp" `
  -Method Post -Headers $headers -Body $body

# 2. Call list_bug_reports for a specific project
$body = @{
  jsonrpc = "2.0"
  id = 2
  method = "tools/call"
  params = @{
    name = "list_bug_reports"
    arguments = @{ project = "bugagent"; limit = 5 }
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri "https://mcp.bugagent.com/mcp" `
  -Method Post -Headers $headers -Body $body

响应以服务器发送事件（MCP Streamable HTTP 标准）的形式到达。每个块都是带有 data: 前缀的一行，后跟一个 JSON 对象。Accept: application/json, text/event-stream 标头是必需的——服务器会拒绝没有它的请求。

ℹ️

排查 401 未授权： 检查你的 API 密钥是否已在设置 → 开发者中被撤销。密钥以 ba_live_ 开头。如果仍然有问题，请重新生成密钥并重试。

试试看——纯英语提示

连接后，你不需要知道工具名称或参数。用纯英语描述你想要的内容，你的 AI 助手会自动调用正确的 bug_Agent_ 工具。

缺陷报告

询问你的 AI 助手

List my 5 most recent bug reports
Show all open critical bugs in the Auth project
Create a bug titled "Login broken on Safari" with severity s2
Update TEST-451 status to in-progress and assign it to me
Add a comment to TEST-451: "root cause confirmed — null check missing in auth middleware"
Show me everything filed this week, grouped by severity

测试管理

Create a test suite called "Smoke Tests" with cases for login, checkout, and account settings
Run the Regression suite and list all failures
Use Hermes to execute the curated "Checkout smoke" suite and report every result to bugAgent
Show failing test cases from the last 7 days
Which test cases have never been run in the past 90 days?
Get a pass-rate trend for this month vs last month

安全与性能

Run a security scan on https://app.example.com
Get this month's security scan results — show only high and critical findings
Create a performance test for the landing page and check Lighthouse scores
What are the Core Web Vitals for our checkout flow?

Playwright 自动化

Create a Playwright script that logs in and verifies the dashboard loads
Run the checkout automation on iPhone 15 Pro on a real device
Optimize the login automation script
Show runs for the checkout automation — any failures?
Schedule the smoke test suite to run every weekday at 6 AM UTC

探索性 AI

Run an exploratory AI session on https://app.example.com with 5 parallel agents
Get the latest exploration run results — list any bugs that were filed
What testing strategies did the agents use and which found the most issues?

使用情况与统计

Check my plan usage for this month
Show team bug stats for this week broken down by severity and type
List all team members and their roles
How many security scans do I have left this month?

快速参考

所有八个客户端的配置文件位置。每个客户端都连接到 https://mcp.bugagent.com/mcp，并在 Streamable HTTP 上使用标头 Authorization: Bearer ba_live_YOUR_KEY_HERE。

客户端配置位置 / 命令

MCP Inspector 无需文件——在浏览器 UI 中 npx @modelcontextprotocol/inspector 之后输入 URL + 身份验证标头

Claude Desktop — macOS ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop — Windows %APPDATA%\Claude\claude_desktop_config.json

Claude Code（CLI） claude mcp add --transport http bugagent https://mcp.bugagent.com/mcp --header "Authorization: Bearer ba_live_..."

Codex CLI ~/.codex/config.toml

Cursor — macOS 设置 → MCP UI，或 ~/.cursor/mcp.json

Cursor — Windows %USERPROFILE%\.cursor\mcp.json

VS Code + Continue ~/.continue/config.json（macOS）/ %USERPROFILE%\.continue\config.json（Windows）

直接 HTTP（curl） curl / Invoke-RestMethod — 包含 Accept: application/json, text/event-stream

故障排除

症状修复方法

401 Unauthorized 密钥错误、已过期或被撤销。检查设置 → 开发者——密钥以 ba_live_ 开头。如有需要请重新生成。

客户端中未显示工具编辑配置后完全退出并重新启动客户端。在 Claude Desktop 中，按 Cmd+Q（不只是关闭窗口）。在 Cursor 中，检查设置 → MCP 是否有绿点。

Accept header required 直接 HTTP 调用必须包含 Accept: application/json, text/event-stream——Streamable HTTP 规范要求如此。没有它，服务器会返回 406。

错误工作区的数据每个 API 密钥都被限定在一个工作区内。在设置 → 开发者中，从你想查询的工作区生成一个新密钥。

工具出现但调用静默失败确认服务器可达：curl -I https://mcp.bugagent.com/health 应返回 200。如果超时，请检查网络/防火墙规则。

MCP Inspector CORS 错误在 Inspector UI 中为“连接类型”选择代理（而不是“直接”）。Inspector 通过本地 Node 进程代理以绕过浏览器 CORS 限制。

Codex CLI — 工具无法识别验证 ~/.codex/config.toml 使用 [[mcp_servers]]（双括号、数组语法）。检查 Codex CLI 版本是否足够新以支持 MCP（codex --version）。

MCP 功能

bug_Agent_ MCP 服务器提供以下工具：

🐛

缺陷报告管理

create_bug_report — 提交新报告，支持跨 19 种类型自动分类——缺陷、功能请求、增强、技术债务等（标题：3-500 个字符）。可选的 attachments 数组接受 base64 编码的文件，每个最大 400 MB：任意图片、视频、音频、PDF 或文本/JSON。设置 format_description: true 可使用 AI 将描述自动重新格式化为结构化模板。传入 time_spent_seconds 以跟踪 QA 工作量。传入 priority（urgent / high / normal / low）可独立于严重级别设置修复优先级。传入 is_epic: true 可创建 Epic，或传入 parent_epic_id（UUID/短 ID）可在同一授权项目中创建子项。响应包含层级字段以及 project_id、project、short_id、legacy_short_id 和 project_short_id。
list_bug_reports — 列出并筛选报告（每页最多 100 条）。项目筛选在分页之前在服务端应用。可按 project（UUID、slug、精确名称或工单前缀）、project_id、project_slug、project_prefix、workspace（UUID、精确名称或工作区工单前缀）、workspace_id/team_id、is_epic、type、severity、status、resolution、root_cause 或 reporter_user_id 进行筛选。每条结果包含租户范围内的人员/项目标识符，以及 is_epic、parent_epic_id、parent_epic 和有界的 epic_progress。报告读取工具不会暴露成员的电子邮件地址。
pick_next_bug — 返回代理循环接下来应处理的缺陷，按优先级排序（S1 → S2 → S3，每个桶内最早优先）。自动限定在你的工作区范围内——返回你团队中所有项目中带有 status new、awaiting-triage 或 confirmed 且严重级别为 S1-S3 的工单。只读——不会原子性地认领工单。可选的 severity（单层）、limit（1-50，默认 1）。返回的行格式与 list_bug_reports 相同，便于工具组合。与 claim_bug 配对使用可实现先读后认领模式。
claim_bug — 将缺陷从 status new、awaiting-triage 或 confirmed 原子地转换为 status='in-progress'，将 assigned_to 设置为调用用户，并加盖 claimed_at=NOW() 时间戳。通过 Postgres 的 UPDATE-WHERE-RETURNING 模式，在并发调用方之间无竞态——如果两个代理几乎同时在同一 id 上调用 claim_bug，恰好一个会获得包含缺陷正文的 claimed:true，另一个会获得带原因字符串的 claimed:false。成功响应包含 reporter_user_id、reporter_name、assigned_to 和 assignee_name。pg_cron 回收器会自动将过期认领（status=in-progress + claimed_at > 30 分钟）释放回 new，因此崩溃代理的工单无需人工干预即可重新进入队列。输入：id（UUID 或短 ID）。
get_bug_report — 按 UUID 或工作区/项目短 ID 获取报告的完整详情。返回标准的人员/项目/质量字段，以及 is_epic、父级身份、聚合进度和 Epic 的有界首个子项页面。
list_epic_children — 使用 id、limit（1–100）和 offset 分页浏览 Epic 的子报告。返回 children、total、has_more 和 SQL 聚合的 epic_progress，无需加载每个子报告。
update_bug_report — 更新标准报告字段以及 is_epic 和 parent_epic_id。传入 parent_epic_id: null 可解除关联；重新关联/解除关联是原子操作，需要同一工作区、同一项目的授权。提升为 Epic 会解除现有父级关联，而带有子项的 Epic 不能被降级。现有的状态/解决方案/根本原因和分配通知规则仍然适用。
add_comment — 向缺陷报告添加评论（UUID 或短 ID，正文 1-10000 个字符）。如果报告已同步到 Jira，评论会自动推送到关联的 Jira 问题。
list_comments — 列出报告的完整评论线程，最早优先——每条评论包含作者姓名、parentId（线程回复）和时间戳。评论不属于 get_bug_report 的一部分，因此这是读取工单讨论的方式。接受 UUID 或短 ID。
link_bug_reports — 在同一授权项目的两个报告之间创建定向语义链接。对于 parent-of，来源报告必须是 Epic，目标报告必须是标准子项。在创建/更新 Epic 分配时，优先使用 parent_epic_id。
unlink_bug_reports — 按 UUID 移除先前创建的缺陷报告链接（link_id，由 link_bug_reports 或 list_bug_report_links 返回）。
list_bug_report_links — 列出触及缺陷报告的每个用户策展链接。每条链接均从所提供报告的视角读取返回——例如，存储的 duplicate-of 行中此报告是目标，则呈现为 duplicated-by；parent-of 中此报告是目标，则呈现为 subtask-of；depends-on 中此报告是目标，则呈现为 blocks；testing-blocked-by 中此报告是目标，则呈现为 blocks-testing。related-to 是对称的。补充由 get_bug_report 返回的自动检测的 similar_reports 字段。
classify_bug — 将描述分类为 19 种报告类型之一（缺陷、功能、增强等），带置信度评分
flush_reports — 批量删除旧报告（仅限管理员）

📊

使用量与分析

get_usage — 检查计划限额内的使用量。API 密钥调用方需要 usage:read。
get_stats — 每日计数、类型/严重级别/状态细分

📁

项目管理

list_projects — 列出可用项目，包含 id、name、slug、ticket_prefix、描述和默认状态。将这些值与 create_bug_report 和 list_bug_reports 一起使用以定位正确的项目。
create_project — 创建新项目（如果是第一个则自动成为默认项目）
delete_project — 永久删除项目及其所有关联数据（缺陷报告、自动化、测试用例、移动应用、调度、地理快照、笔记、时间条目）。仅限所有者/经理。不能删除最后一个项目。存储空间会自动释放
export_okf_bundle — 将项目的 QA 知识——缺陷报告、测试用例、自动化以及性能、安全和探索性测试——导出为 OKF/OQA Markdown 包（oqa.ai 使用的开放查询代理格式）。默认为当前活动项目；传入可选参数 project（slug 或名称）可导出其他项目。返回包中的文件列表以及包本身（base64 编码的 zip）

🔐

认证与账户

register_account — 创建新账户（密码：8-128 个字符，限流：5 次/15 分钟）
login — 登录并接收访问令牌（限流：5 次/15 分钟）
update_profile — 更新显示名称
change_password — 更改账户密码
get_settings / update_settings — 管理偏好设置

🔑

API 密钥管理

generate_api_key — 创建命名 API 密钥
list_api_keys — 列出活动密钥（仅前缀）
regenerate_api_key — 撤销并替换密钥
delete_api_key — 永久撤销密钥

👥

团队管理

list_team_members — 列出工作区的所有成员，包含角色、状态和助推器标志
invite_team_member — 按电子邮件邀请用户（经理可以邀请贡献者和经理；只有所有者可以邀请管理员）。链接 5 天过期

🎯

集成

sync_to_jira — 使用团队的共享连接将报告同步到 Jira
push_to_claude — 生成（或重新生成）缺陷报告的开发者笔记——根本原因、建议修复、验证步骤和风险评估。接受 UUID 或短 ID（WRKID-545）。使用平台密钥——无需每团队单独的 Claude 连接。运行自适应链：对于 s3/medium 或 s4/low 缺陷执行三步（Sonnet 草稿 → OpenAI gpt-5 批判 → Sonnet 综合），对最高两个严重级别的桶——s1/critical 或 s2/high——执行五步（草稿 → 批判 → Sonnet 反驳 → Claude Opus 裁决者读取完整记录并以其独立判断撰写最终笔记）。响应暴露每一轮：analysis、draft、critique、rebuttal、challenger_model、adjudicator_model 以及一个 debated 标志。任何步骤失败都会回退到次优答案。在缺陷创建时自动触发；通常仅手动重新生成时才调用。
analyze_fix_area — 生成（或重新生成）开发者笔记的"可能修复区域"子块——一个精简的 Sonnet 输出，指明修复最可能属于代码库中的哪个位置。接受 UUID 或短 ID。使用平台 Anthropic 密钥。当团队有 github_connections 行且项目映射了 github_repo 时，输出基于已连接仓库的真实文件片段；否则回退到通用指导，并提示连接仓库。返回 likely_fix_area 文本、generated_at、repo_used 和 grounded 标志。在缺陷创建时自动触发——代理通常只需在手动重新生成时调用此功能。
upgrade_plan — 获取销售协助的企业版注册链接

⚡

性能测试

create_performance_test — 创建性能测试配置，包含 URL、设备、虚拟用户、持续时间、分数阈值和自动缺陷创建开关。仅限企业版
run_performance_test — 触发 Web 性能测试的页面审计和负载测试。返回一个运行 ID 以轮询结果。移动应用性能分析运行从仪表板触发
get_performance_results — 获取完整结果，包括 Lighthouse 分数（性能、可访问性、最佳实践、SEO）、Core Web Vitals（LCP、FID、CLS、FCP、TTFB、INP、TBT、SI）和负载测试指标（VU、请求数、RPS、p50/p90/p95/p99 延迟）
list_performance_tests — 列出当前团队的所有性能测试配置
get_performance_usage — 检查每月性能测试使用量。性能测试仅限企业版。免费版=0，企业版=无限制

示例工作流

get_performance_usage → 检查剩余配额
create_performance_test → 为你的 URL 配置测试
run_performance_test → 触发审计 + 负载测试
get_performance_results → 查看分数和核心指标

🛡

安全扫描

create_security_scan — 创建安全扫描配置。Web 扫描使用 Quick Scanner + Nuclei（4,000+ 模板），支持三个深度级别和可选的身份验证扫描。移动扫描使用 MobSF 进行 APK/IPA 二进制分析。可配置基于严重性阈值的自动创建缺陷。仅限企业版
run_security_scan — 触发漏洞扫描。Web 扫描需要 DNS 域名验证。移动扫描需要已上传的应用。返回一个运行 ID 用于轮询结果
get_security_results — 获取完整结果，包括安全评分（0-100）、按严重性分类的发现（严重、高、中、低、信息），附带 CWE 引用、OWASP 映射、证据和修复建议
list_security_scans — 列出当前团队的所有安全扫描配置，包含最近评分和认证/深度徽章
get_security_usage — 检查每月安全扫描用量。安全扫描仅限企业版。企业版=无限量
list_security_schedules — 列出团队的所有计划安全扫描，包含 cron、时区、启用状态、下次运行时间和通知设置。与父扫描配置（名称、scan_type、target_url）关联
create_security_schedule — 为安全扫描创建定期计划。需要 scan_id 和 cron_expression。每个扫描配置一个计划。可选 timezone、notify_on_fail（无/邮件/Slack/两者）、notify_email、slack_channel_id。每次运行都计入月度上限；管理员用户不受上限限制。扫描深度始终在运行时从扫描配置中读取
delete_security_schedule — 删除计划的安全扫描。不影响父扫描配置或已完成的运行

get_security_usage → 检查剩余配额
create_security_scan → 为你的 URL 或仓库配置扫描
run_security_scan → 触发一次性漏洞扫描
create_security_schedule → 自动化定期运行（例如主分支上的每周 SAST）
get_security_results → 查看发现和修复建议

📖

代码审查

list_code_reviews — 列出团队的最近 AI 代码审查。返回质量评分、严重性计数、PR 信息和时间戳。仅限企业版
get_code_review — 获取包含所有发现的代码审查。每个发现包含严重性、类别（缺陷/安全/性能/风格/逻辑/可维护性）、标题、描述、代码建议、文件路径和行号
get_code_review_usage — 检查代码审查用量。AI 代码审查仅限企业版；企业版无限量
get_code_review_analytics — 获取审查分析：趋势、发现类别/来源、严重性分布、速度指标、热门仓库/作者。支持 7/30/90 天回溯

get_code_review_usage → 检查剩余审查次数
在仪表板中审查 PR，位于 /dashboard/code-review
list_code_reviews → 查看最近的审查
get_code_review → 获取发现和建议

🔍

探索式 AI

多智能体自主网站缺陷查找器，最多支持 10 个并行智能体，每个使用不同的测试策略。

list_explorations — 列出团队的探索式 AI 配置
create_exploration — 创建新的探索。接受 agent_count（1–10，最大 10）以运行多个具有独特策略的并行智能体：happy_path、edge_case、security、accessibility、error_path、performance、mobile、data_integrity、navigation、custom
get_exploration — 获取探索配置，包含智能体设置、安全认证元数据和最近运行。密码和密文永远不会返回。
get_exploration_run — 获取运行结果，包含每个智能体的进度、阶段数据、带智能体归属的发现（agent_index、agent_strategy）以及关联的缺陷
get_exploration_usage — 检查每月用量。探索式 AI 仅限企业版；企业版：无限量（10 个智能体）

create_exploration 配合 agent_count: 5 → 配置 5 个并行智能体
从仪表板或通过 POST /api/explorations/run 触发运行
get_exploration_run → 轮询每个智能体的进度和发现
在仪表板中查看带智能体归属的去重发现

📝

笔记

list_notes — 列出笔记，支持可选的关键字搜索、项目筛选、作者筛选和日期范围。返回用户拥有的笔记或团队内共享的笔记。
create_note — 以 5 种格式之一创建笔记：markdown、plain_text、rich_text、checklist、outline。将 visibility 设置为 private 或 shared。如果未提供标题，则自动取前 30 个字符作为标题。可选的 attachments 数组接受 base64 编码的文件，每个最大 400 MB：任何图片、视频、音频、PDF 或文本/JSON。传递 time_spent_seconds 以跟踪 QA 工作量。
get_note — 获取完整笔记详情，包括内容和附件。需要 id。
update_note — 更新标题、内容、格式、可见性、项目或 time_spent_seconds。传递 attachments 数组以将新文件（每个最大 400 MB）追加到笔记的现有附件中，而不替换它们。只有作者可以更新。需要 id。
delete_note — 永久删除笔记及其附件。只有作者可以删除。需要 id。

create_note → 开始一个测试会话笔记
update_note → 在测试时追加观察记录
list_notes → 按关键字或项目搜索过去的笔记
get_note → 检索带附件的完整笔记

🤖

自动化

create_automation — 使用自定义 Playwright 脚本创建新的自动化（无需 FAB 录制）。需要 name。可选：target_url（如果省略，则从脚本中的第一个 page.goto(...) URL 自动推导）、script（Node.js/JavaScript/TypeScript 或 Python — 语言自动检测；默认为占位符）、status（draft 或 active，默认：draft）、project_id。返回自动化 id。需要企业版计划。提示 — 复制自动化： 使用 get_automation 获取原始脚本，然后调用 create_automation，将 name 设置为 "[Copy] Original Name"，并传递原始 script、target_url 和 project_id。副本以 draft 状态启动，没有版本历史。
list_automations — 列出 Playwright 自动化脚本。按 project_id 或 status（draft、active、paused）筛选。返回自动化数组，包含名称、target_url、last_run_status 和 run_count。
get_automation — 获取完整自动化详情，包括 Playwright 脚本和最近运行。需要 id。返回带实时 script 的自动化、script_versions 堆栈（最旧优先，最多 100 条先前条目，每条 { script, source, timestamp }）以及 recent_runs 数组，其中每次运行携带执行的 script_version_label/script_version_source。如果你需要选择特定的历史版本，请在 run_automation 之前调用此方法。
run_automation — 触发 Playwright 测试的立即运行。需要 automation_id。自愈定位器（自动）： 当定位器操作超时时，运行器会向 Claude 请求一个可用的选择器并重试该步骤一次 — 断言永远不会被修复，因此真正的回归仍然会失败 — 每次修复都会记录在运行 stdout 中。虚拟模式（默认）：可选的 device 用于视口模拟（例如 desktop、iphone-15）。实时模式：设置 browserstack: true 配合 bs_browser（chrome、firefox、safari、edge）、bs_os（Windows、OS X）和 bs_os_version 以在真实桌面浏览器上运行。实时真机移动端： 设置 bs_os: "android"（设备："Samsung Galaxy S25 Ultra"、"Google Pixel 10"、"OnePlus 13R"）或 bs_os: "ios"（设备："iPhone 17 Pro Max"、"iPhone 16 Pro Max"、"iPhone 15 Pro Max"），并在 bs_os_version 中传递设备名称。Node.js 脚本通过 browserstack-node-sdk 路由（覆盖桌面 + Android + iPhone）。Python 脚本通过 browserstack-sdk（pytest-playwright）路由，仅覆盖桌面 — 不支持通过 Python 进行真实移动端，因为 pytest-playwright 的 browser_type.connect() 无法驱动 BrowserStack 的真实移动端端点。视频和网络日志自动捕获；控制台日志仅限桌面。版本回放： 传递可选的 version_index（整数，0 索引）以执行自动化 script_versions 历史中的先前条目。默认：当 version_index 被省略或为 null 时，运行当前实时脚本 — 不要仅仅为了"选择当前"而传递占位值。超出范围、负数或非整数值将被拒绝。运行记录存储实际执行的精确快照，任何从失败运行自动创建的缺陷报告都会在编辑器中深度链接回该版本。
list_automation_runs — 列出自动化的最近运行。需要 automation_id。返回带状态、duration_ms 和 error_message 的运行。
list_schedules — 列出所有计划的 Web 自动化运行，包含 cron、时区、设备和通知设置
create_schedule — 创建计划的 Web 自动化运行。需要 automation_id 和 cron_expression。支持设备、时区、notify_on_fail（邮件/Slack/两者）和 Slack 频道选项。计划运行上的 BrowserStack Live：传递 browserstack: true 配合 bs_browser、bs_os 和 bs_os_version — 与 run_automation 相同的设备矩阵（Node = 桌面 + 真实 Android + 真实 iPhone；Python = 仅桌面）。
delete_schedule — 删除计划的 Web 自动化运行
list_mobile_schedules — 列出所有计划的移动自动化运行，包含设备、cron、时区和通知
create_mobile_schedule — 在真实设备上创建计划的移动自动化运行。需要 automation_id、cron_expression 和 devices 数组
delete_mobile_schedule — 删除计划的移动自动化运行
optimize_automation_script — 将 Playwright 脚本发送给 Sonnet 4 进行 AI 驱动的优化。应用 12 点检查清单，修复选择器、等待策略、断言、错误处理、认证模式、移动兼容性和严格模式。需要 automation_id。优化前会保存当前脚本版本。返回优化后的脚本和更改摘要。
undo_automation_script — 将自动化脚本回滚到之前的版本。最多保留 10 个先前版本。需要 automation_id。返回恢复的脚本和剩余版本数。

create_automation → 使用自定义脚本创建测试
list_automations → 浏览可用测试
get_automation → 检查 Playwright 脚本
run_automation → 触发测试
list_automation_runs → 检查结果和持续时间

⏱️

时间跟踪

list_time_entries — 列出团队的时间条目。按 period（today、week、month、all）、project_id、category 和 sort（newest、oldest、most_time、least_time）筛选。仅限企业版计划。
create_time_entry — 记录 QA 任务花费的时间。需要 description、category 和 duration_minutes。可选设置 project_id 和 entry_date（默认为今天）。仅限企业版计划。
update_time_entry — 更新现有时间条目。需要 id。可以更新 description、category、duration_minutes、project_id 或 entry_date。仅限企业版计划。
delete_time_entry — 永久删除时间条目。需要 id。仅限企业版计划。

create_time_entry → 记录 45 分钟的回归测试
list_time_entries → 查看本周的时间条目
update_time_entry → 调整持续时间或类别
delete_time_entry → 删除不正确的条目

☑️

测试用例

测试管理支持层级文件夹、嵌套测试套件（最多 3 层，运行时子套件自动展开）、拖拽排序，以及带有 KPI 趋势、失败分析、套件健康度、覆盖率和测试人员生产力的分析报告标签页。所有工具直接调用 Supabase——无需 HTTP 往返，与仪表盘延迟相同。

免费版限制： 10 个已存储的测试用例、1 个套件、3 个文件夹、每个用例 128 KB 结构化内容、2 个有效的工作区 API 密钥，以及每个 UTC 日历月总共 10 次测试运行。其中最多 3 次运行可使用 Hermes 或其他外部代理，支持 1 个活动外部运行，每个外部计划最多 10 个用例。免费版 API 密钥 MCP 流量限制为每个密钥每分钟 30 个请求、每个工作区每分钟 60 个请求。企业版测试用例存储和运行不受限制，但需遵守平台通用保护措施。

AI 测试用例生成、AI 标签建议、Figma 导入和测试用例文件附件需要企业版。免费版 128 KB 结构化内容限制与企业版文件附件相互独立。免费版可存储 URL 引用。核心 MCP 测试用例工具在免费版上仍可用，但受上述限制约束。

免手动执行：运行审阅页面采用轮播式布局，一次仅显示一个用例，支持键盘快捷键（P 通过 · F 失败 · B 阻塞 · S 跳过）以及语音控制。点击麦克风，然后说出"通过"、"失败"、"阻塞"、"跳过"、"下一个"、"上一个"、"添加备注"（转写到备注字段）、"保存备注"或"关闭语音"。成功结果会自动前进到下一个未测试的用例；失败时停留在当前用例，以便测试人员口述详细信息并创建缺陷。适用于 Chrome、Edge 和 Safari。

用例与文件夹

list_test_cases — 列出测试用例，支持可选的 search、priority（critical、high、medium、low）、type（functional、regression、smoke、integration、performance、security、usability、exploratory）、status（active、draft、deprecated）和 sort（newest、oldest、name、priority）。API 密钥调用方需要 test_cases:read。
create_test_case — 创建测试用例。两种模板变体：steps（默认）——通过 steps 数组生成逐步的 { action, expected } 网格；text ——通过 text_content 生成单个自由格式描述。两个字段可在同一次调用中发送（平台独立存储它们，因此测试人员之后切换 template_type 时不会丢失任一侧的数据）。可选的 urls 数组（最多 10 个 http/https URL）用于附加参考链接，免费版可用。需要 name。可选：description、preconditions、template_type、steps、text_content、urls、priority、type、tags、estimated_time（秒）。文件附件需要企业版，通过仪表盘的 POST /api/test-cases/:id/attachments 端点（multipart）上传——尚未作为 MCP 工具公开。API 密钥调用方需要 test_cases:write。
get_test_case — 获取完整测试用例详情，包括步骤和执行历史。
list_test_case_folders — 列出团队的文件夹（每个用例一个文件夹，通过 folder_id；与套件不同，套件是多对多的测试计划分组）。上限 500 个；遵循 project_id 和 parent_folder_id 过滤器（仅顶层时使用 "root"）。
create_test_case_folder — 创建文件夹（通过 parent_folder_id 最多嵌套 3 层）。使用 bulk_update_test_cases 将用例移入其中。API 密钥调用方需要 test_cases:write。
bulk_update_test_cases — 一次对最多 500 个用例应用一个操作：set_priority、set_status、set_type、add_tags、remove_tags、add_to_suite、pin、unpin。
link_test_case_to_bug — 在测试用例与缺陷报告之间建立可追溯性（verified_by、covers 或 relates）。
list_test_case_links — 列出测试用例的所有可追溯性链接。
list_test_case_review_candidates — 失效测试标记：never_run（创建后 90 天以上）、always_passes（90 天内连续通过 5 次以上）、always_skipped（连续跳过 3 次以上）。
mark_test_case_review_flags — 将当前的归档候选标记持久化到 test_cases.review_flag 上。通过 pg_cron 在每个星期一 09:00 UTC 自动运行。

导入

Figma 导入（企业版）（仪表盘 UI + REST）：上传 Figma 帧的 zip 导出（最多 100 MB），Claude 分析每个屏幕并将测试用例草拟到你选择或创建的文件夹中。多阶段流水线（分类 → 逐屏幕用例 → 跨共享前缀屏幕的流程级用例 → 自我批判），支持提示缓存、429 重试和逐帧错误隔离，因此一个坏帧不会导致整个批次失败。用例以 status=active 形式落地，标记为 ai_generated=true，并通过 source='figma' 和 source_frame_name 保留指向原始帧的链接。使用平台 Anthropic 密钥——无需每团队单独配置 Claude 连接。端点：POST /api/test-cases/import/figma/request、POST /api/test-cases/import/figma/start、GET /api/test-cases/import/figma/:id。

套件与运行

list_test_suites — 列出测试套件，包含项目标识、用例数和上次运行状态。API 密钥调用方需要 test_runs:read。
create_test_suite — 创建套件。通过 parent_suite_id 最多嵌套 3 层。
list_test_runs — 列出测试运行，包含套件名称、执行人和通过/失败摘要。
create_test_run — 创建由仪表盘管理的套件运行。运行父套件会自动包含所有后代子套件中的每个用例（同时关联多个套件的用例只添加一次）。每个 test_run_results 行记录用例来自哪个原始子套件，以便结果页面可按来源分组。

外部代理执行

这些工具允许 Hermes 或其他代理运行时执行已批准的套件，而不会成为 QA 系统记录源。使用仅包含 test_runs:read 和 test_runs:write 的工作区范围密钥。套件提供项目边界；调用方无法覆盖。

start_test_plan — 启动或恢复具有稳定 external_run_id 的不可变套件快照。重复的 ID 返回现有的匹配运行和第一页，而不是创建重复项。
get_test_run_plan — 读取规范运行状态和稳定的计划页。传入上一个 next_cursor；页面默认 100 个用例，上限 200 个。
report_test_results — 提交 1–200 个结果，状态为 passed、failed、blocked 或 skipped。完全相同的重试是安全的；尝试用其他状态覆盖用例会被拒绝。
abort_test_run — 幂等地停止中断的运行，同时保留已接受的局部结果和规范摘要。

配额行为： 使用相同的 external_run_id 重试 start_test_plan 以恢复匹配的运行，而不会消耗另一次运行。删除数据不会重置月度运行用量。

运行时边界： 用例快照排除凭据、文件正文和私有附件路径。结果证据在 MVP 中为文本形式。目标凭据保留在执行运行时中。浏览器、模型和网络成本由客户承担，客户必须限制目标访问和网络出口。人类仍对缺陷和发布决策负责。

Hermes Agent 指南将此循环打包为 bugAgent 维护的社区技能。公开入门套件包含可直接复制的配置和可安装技能。这不是官方的 Nous Research 集成。

报告（Tier 1 + Tier 4 分析）

get_test_reports_overview — 某个时间窗口的关键 KPI（通过率、已完成的运行次数、已执行的用例数），以及与前一等效窗口相比的差异。与报告标签页 KPI 条显示的数字相同。
get_test_reports_failures — 四个"该修复什么？"列表：failing_cases（≥50% 失败，最少 3 次运行）、flaky_cases（通过/失败翻转最多）、failing_suites（≥30% 失败，最少 5 次运行）、regressed_cases（窗口内最近一次失败，但之前有通过记录）。

create_test_case_folder → 创建文件夹树（例如 Smoke → Auth）
create_test_case → 定义用例；使用 bulk_update_test_cases 将其移入文件夹
create_test_suite → 构建测试计划（子套件可选，最多 3 层深）
create_test_run → 从父套件创建人工/仪表盘管理的运行——子套件自动包含
start_test_plan → 启动或恢复可安全重试的外部代理运行
get_test_run_plan → 检索每个不可变计划页，然后在所选运行时中执行
report_test_results → 返回有界的结果批次；如果执行无法安全继续，调用 abort_test_run
get_test_reports_failures → 运行完成后询问"这周该修复什么？"
get_test_reports_overview → 逐周跟踪通过率趋势

⚡

团队加速器

scale_team — 通过加速测试人员即时扩展您的 QA 团队。账户自动配置测试人员访问权限。指定 team_size（1–10）、location、duration、budget，以及可选的 product_url、product_types 和 tech_levels。仅限企业版套餐。在获得批准之前不会向您收费。

scale_team → 在美国配置 5 名高级测试人员，为期 1 个月
list_team_members → 验证新测试人员出现在您的团队中
list_reports → 审阅加速测试人员提交的报告

📱

移动测试（企业版）

移动资源按项目限定范围。在创建、导入和过滤列表时传递 project_id 或灵活的 project 选择器。自动化继承所关联应用的所属项目；否则服务器使用工作区默认项目。未过滤的列表可能仍包含旧版工作区级行，直到其完成迁移。

list_mobile_apps — 列出已上传的应用，支持可选的 project_id/project、platform 和 limit 过滤器。返回每个应用的 project_id，以便代理可以在同一项目中继续后续操作。
upload_mobile_app — 注册 APK（Android）或 IPA（iOS）应用以在真实设备上进行测试。需要 name、platform（android/ios）和 file_url；传入 project_id 将其分配到当前项目。对于 iOS，上传 IPA 用于真实设备运行，然后使用仪表盘上传模拟器 .app 构建以进行录制。
update_mobile_app — 用新版本替换应用二进制文件。清除缓存的 URL 和模拟器构建，以便所有自动化在下次运行时使用新版本。需要 app_id 和 file_url。可选：version。如果关联的自动化使用登录配置文件，调用者必须获得每个配置文件的授权，或者是当前工作区的所有者/管理员；计划继承受保护的自动化默认值。
list_mobile_automations — 列出移动自动化，支持可选的 project_id/project、app_id、status 和 limit 过滤器。结果包含 project_id 和关联的应用 ID。
create_mobile_automation — 创建测试脚本。需要 name、app_id、script_type（maestro 用于 YAML，appium 用于 Appium Python，appium_js 用于 Appium JavaScript）和 script；当应用尚未限定在项目范围内时，传入 project_id。对于单个经过外部验证的自包含 Maestro YAML 流程，将 execution_mode 设置为 browserstack_maestro；否则默认为 appium_actions。YAML appId 必须与关联应用存储的包名或 bundle ID 匹配；如果未存储，则第一个经过验证的原生流程将建立它。占位符应用 ID 和混淆的 Android 资源 ID 将被拒绝。支持内联 runFlow，但 v1 中拒绝外部流程/脚本文件引用。原生 Maestro 保留诸如 inputRandomText 和 copyTextFrom 之类的命令以及诸如 ${maestro.copiedText} 和 ${output.value} 之类的运行时表达式。同一项目的 credential_id 可以提供完整的 inputText 值（${USERNAME}/${PASSWORD}）。同一项目的 variable_profile_id 可以保存所引用 ${DATA_*} 值的默认值；每个引用的键都必须存在。数据配置文件仅限非机密的合成数据。
import_mobile_script — 导入现有的移动测试脚本并将其转换为可运行的自动化，保留开发者自己的定位器，以便运行能够精确解析元素。支持的方言：Appium‑Python、WebdriverIO、Maestro（YAML 流程）和 Playwright（移动 Web）。混淆的 Android 资源 ID 占位符将被跳过并在选择器映射 warnings 中报告。仅限 Android 应用。需要 name、app_id 和 script；可选 target_devices 和 project_id。返回自动化以及 action_count、检测到的 dialect 和选择器映射 warnings。
run_mobile_automation — 在真实设备上启动移动自动化。需要 automation_id；可选 device、os_version、credential_id 和原生 Maestro variable_profile_id。对于数据，省略 variable_profile_id 以继承自动化默认值，传入 null 以不使用配置文件，或传入同一项目的 UUID 以覆盖。每个引用的 ${DATA_*} 键都必须存在。只有活动配置文件的创建者或活动工作区的所有者/管理员才能执行选定的配置文件。已知的精确凭据值会被过滤，精确的数据配置文件值会从持久化的文本证据中获得尽力而为的过滤；转换后、部分、编码或应用派生的数据值可能保留。授权的私有视频/截图仍然可用，并可能显示被测应用渲染的值，因此数据配置文件必须仅包含合成的非机密值。如果凭据编辑上下文不可用或无法证明清理是安全的，则保留详细的凭据文本，同时状态和可用的视觉证据仍然可用。诊断需要工作区和项目授权；媒体链接在五分钟后过期。
list_mobile_runs — 获取授权的移动运行结果（状态、设备、结果摘要、私有视频和截图链接、BrowserStack 会话、经过过滤的凭据原生 Maestro 日志和失败信息（在安全可用时），以及任何自动创建的 bug）。运行诊断强制执行工作区成员资格和项目访问权限。可选过滤器：project_id、automation_id、status（queued、running、passed、failed、error、archived）和 limit。默认排除已归档的运行。
create_mobile_credential — 为项目创建命名登录配置文件（例如“Admin”、“Contributor”）：移动自动化使用的用户名 + 密码。两个值均以 AES‑256‑GCM 加密存储，并且是只写的 — 任何工具或 API 都不会返回它们，其他成员/UI 只能看到名称。只有创建它的活动工作区成员或活动工作区的所有者/管理员才能绑定、运行、轮换或删除它。需要 project_id、name、username、password。仅限企业版。
list_mobile_credentials — 列出登录配置文件（可选一个 project_id）。仅返回非机密字段（id、name、项目、创建者、创建日期）— 绝不返回用户名或密码。使用返回的 id 作为运行自动化时的凭据选择。
update_mobile_credential — 重命名登录配置文件或通过 id 轮换其用户名/密码。仅包含要更改的字段。新的机密值会立即加密，并且永远不会返回。只有创建配置文件的当前工作区成员或当前工作区的所有者/管理员才能更新它。
delete_mobile_credential — 通过 id 软删除登录配置文件。只有创建配置文件的当前工作区成员或当前工作区的所有者/管理员才能删除它。它会保留用于审计和运行历史，但不再可用或列出；自动化默认值被清除，名称可重新使用。
create_mobile_variable_profile — 使用 project_id、name 和 variables 对象（如 {"DATA_EMAIL":"qa@example.test","DATA_REGION":"ca"}）创建可重用的、项目范围的合成测试数据。键必须是大写 DATA_* 标识符。配置文件允许 1–100 个字符串，每个值 4096 个 UTF-8 字节，总计 65536 字节。保留的凭据/运行时名称将被拒绝。切勿存储凭据、令牌、生产个人数据或其他机密。
list_mobile_variable_profiles — 列出一个已授权 project_id 的配置文件及其可读的非机密值。适用项目分配规则。
update_mobile_variable_profile — 通过 id 重命名配置文件或替换其完整的 variables 对象。只有活动的创建者或活动工作区的所有者/管理员才能更新它。
delete_mobile_variable_profile — 通过 id 软删除配置文件。只有活动的创建者或活动工作区的所有者/管理员才能删除它；自动化默认值被清除，而历史运行引用仍然保留。
list_mobile_schedules、create_mobile_schedule、delete_mobile_schedule — 列出、创建和删除真实设备计划。计划从其选定的自动化继承项目上下文、登录配置文件和非机密变量配置文件。使用任一受保护配置文件的计划需要活动配置文件的创建者或活动工作区的所有者/管理员；计划更改和删除仅限于活动计划的创建者或活动工作区的所有者/管理员。

示例工作流 — Android

list_projects → 解析目标 project_id
upload_mobile_app → 在该项目中注册 APK
在仪表盘中安全录制，或使用 import_mobile_script / create_mobile_automation
list_mobile_automations → 在同一项目中解析自动化
run_mobile_automation → 在真实设备上触发它，可选使用登录配置文件
list_mobile_runs → 检查状态、结果摘要、私有视觉链接和 BrowserStack 会话元数据
失败会自动创建带有失败快照和步骤分解的 bug 报告

示例工作流 — iOS

upload_mobile_app → 使用 project_id 注册您的 IPA 以进行真实设备运行
在应用详情页面上传模拟器 .app 构建（用于录制）
在浏览器中录制测试 → 从模拟器捕获操作
run_mobile_automation → 在 iPhone 上触发保存的自动化（使用 IPA）
update_mobile_app → 准备好时用新版本替换 IPA

示例工作流 — 原生 Maestro

upload_mobile_app → 在目标项目中注册 APK 或 IPA
create_mobile_credential → 可选地为经过身份验证的流程创建同一项目的配置文件
create_mobile_variable_profile → 可选地创建流程使用的同一项目合成 DATA_* 值
create_mobile_automation → 传入一个已知可用的 YAML 流程，包含关联应用的精确包名/bundle appId、script_type: maestro 和 execution_mode: browserstack_maestro。使用 ${USERNAME}/${PASSWORD} 进行登录，使用 ${DATA_EMAIL} 风格的占位符进行合成输入；传入配置文件 ID 以保存默认值。
run_mobile_automation → 选择兼容的设备，可选覆盖登录或变量配置文件。省略变量配置文件以继承，或传入 null 以在单次运行中禁用它。
list_mobile_runs → 检查授权的通过/失败摘要、私有视频/截图、过滤的日志、真实步骤名称、详细失败和会话元数据。如果无法为凭据运行建立安全的清理，则保留详细文本，同时状态和可用的视觉证据仍然可用。

Refine with AI： 允许列表测试版可通过仪表盘和 REST 优化端点使用。公开目录中尚不包含 Refine MCP 工具。

✅

合规与证据（企业版）

collect_compliance_evidence — 从连接的服务（Cloudflare、GitHub、Sentry、Supabase、Railway）触发自动证据收集。返回运行 ID。收集 SSL/TLS 设置、WAF 状态、Dependabot 警报、错误趋势、部署历史等。
check_config_drift — 检查所有连接的服务是否存在与基线相比的安全配置漂移（SSL 模式、TLS 版本、HSTS、WAF 规则、安全标头）。
generate_access_review — 创建季度访问审查报告。审计团队成员、角色、MFA 状态、API 密钥使用情况，并生成建议（例如，撤销不活跃的密钥）。
get_security_events — 查询跨服务安全事件时间线。按来源（cloudflare、sentry、github）和严重级别（critical、high、medium、low、info）过滤。事件在服务之间自动关联。

合规覆盖范围

这些工具帮助满足 SOC2（CC4.1、CC6.1、CC7.2、CC8.1）、ISO 27001（A.5.18、A.8.8、A.8.9、A.8.15-16、A.8.29）和 GDPR（第 5、25、32、33 条）合规要求。

兼容客户端

bug_Agent_ 适用于任何支持 Model Context Protocol 的客户端。以下是流行客户端的设置指南：

🤖

Claude Desktop

打开设置 → 开发者 → 编辑配置，然后添加：

claude_desktop_config.json

保存后重启 Claude Desktop。

✳️

Cursor

打开设置 → MCP 服务器 → 添加服务器，或编辑项目根目录中的 .cursor/mcp.json：

.cursor/mcp.json

🌊

Windsurf

打开设置 → MCP → 添加服务器，或编辑您的 MCP 配置文件：

mcp_config.json

💻

Claude Code（CLI）

直接从终端添加 bug_Agent_：

claude mcp add bugagent -- npx -y @bugagent/mcp-server

在启动前使用 export BUGAGENT_API_KEY=ba_live_... 设置您的 API 密钥。

🔧

其他 MCP 客户端

任何支持 MCP stdio 传输的客户端都可以与 bug_Agent_ 配合使用。使用标准配置：

命令：npx
参数：["-y", "@bugagent/mcp-server"]
环境变量：BUGAGENT_API_KEY

CLI

CLI 入门

bug_Agent_ 命令行工具让您可以直接在终端中全面控制错误报告、功能请求、项目和集成。您可以使用它来：

自动化工作流 — 将错误报告集成到 CI/CD 流水线、脚本和定时任务中
批量操作 — 无需离开终端即可列出、筛选和管理报告
适合管道处理的输出 — JSON、YAML 和原始格式，便于与 jq、yq 及其他工具组合使用
快速迭代 — 无需浏览器 — 数秒内即可创建和更新报告

安装

npm install -g @bugagent/cli

验证安装：

bugagent --version

身份验证

将您的 API 密钥设置为环境变量：

或者使用 --api-key 标志直接传入：

bugagent reports list --api-key ba_live_your_key_here

🔑

从 bug_Agent_ 控制台获取您的 API 密钥。密钥以 ba_live_ 开头。

如需持久化身份验证，请将 export 添加到您的 shell 配置文件中（~/.bashrc、~/.zshrc 等）。

使用方法

命令遵循以下模式：

bugagent <resource> <action> [flags]

资源也可以使用冒号语法访问子资源：

bugagent reports comments add --report-id WRKID-545 --body "Reproduced on v2.1"

在任何命令上使用 --help 查看详细信息：

bugagent reports --help
bugagent reports create --help

示例会话

终端

# List your projects
bugagent projects list

# Create a bug report in your default project
bugagent reports create \
  --title "Checkout 500 on discount code" \
  --description "Applying SAVE20 returns HTTP 500" \
  --severity critical \
  --type logic

# View recent reports
bugagent reports list --limit 5 --format pretty

# Get full details on a report (use the short ID or UUID)
bugagent reports get WRKID-545

# Sync a report to Jira
bugagent jira sync --report-id WRKID-545

# Check your usage
bugagent usage get --format json

CLI 功能

该 CLI 提供以下命令：

reports 创建、列出、获取、更新和刷新错误报告

projects 创建、列出、更新和删除项目

keys 生成、列出、重新生成和撤销 API 密钥

jira 连接、同步报告并配置 Jira 设置

usage 检查当前用量与套餐限制

stats 查看分析和明细

profile 查看和更新您的个人资料与设置

auth 登录、注册和管理凭据

全局标志

标志描述

--api-key <key> 覆盖此命令的 API 密钥

--format <fmt> 输出格式：json、yaml、pretty、raw

--debug 显示请求/响应详细信息以进行故障排查

--help 显示任何命令的帮助信息

--version 打印 CLI 版本号

输出格式

该 CLI 支持多种输出格式，适用于不同的使用场景：

`json`

机器可读的 JSON 格式。非常适合通过管道传递给 jq 或其他工具。

`yaml`

适合人类阅读的 YAML 输出，适用于配置文件并具有良好的可读性。

`pretty`

默认格式。为终端设计的彩色格式化输出。

`raw`

未格式化的输出。适用于脚本编写和自动化。

使用 --transform 进行过滤

使用 --transform 配合 GJSON 语法来查询和过滤输出数据：

# Default pretty output
bugagent reports list

# JSON for piping to other tools
bugagent reports list --format json

# YAML
bugagent reports list --format yaml

# Raw (no formatting)
bugagent reports get rpt_abc123 --format raw

# Filter with GJSON syntax
bugagent reports list --format json \
  --transform "items.#(severity==critical).title"

AI 技能

该 CLI 还以 AgentSkill 的形式提供，允许 AI 编程助手代表您使用 bug_Agent_。

✨

什么是 AgentSkill？

AgentSkill 让 AI 编程助手（Claude Code、Cursor 等）能够根据上下文调用 CLI 工具。bug_Agent_ 技能赋予您的 AI 助手提交错误、查看项目状态以及同步到 Jira 的能力——全程无需您手动输入命令。

安装技能

claude skills install bugagent --from @bugagent/mcp-server

安装后，具备上下文感知能力的 AI 助手可以自然地使用 bug_Agent_ 命令——充分了解您的产品、测试指南和上传的文档：

AI 助手提示词

"File a critical bug: the payment webhook is returning
a 403 after the latest deploy. It affects all Stripe
events. Assign it to the payments project."

该技能会将自然语言转换为相应的 CLI 命令并执行它们。

🎬

会话回放 + AI 助手： 当启用会话回放（企业版套餐）时，AI 助手可以引用捕获的用户会话——过去 60 秒内的点击、导航、错误和网络故障——自动起草更丰富、更准确的错误报告，并附带完整的复现上下文。

获取帮助

需要帮助？我们随时为您服务。

Discord 社区

加入我们的 Discord 获取实时支持和社区讨论。

邮件支持

support@bugagent.com — 我们通常在 24 小时内回复。