qarunbook

qarunbook

弄清楚需要测试什么，然后真正开始测试。

大多数团队都知道发布前应该进行测试。阻碍他们的不是缺乏自律，而是没人愿意坐下来写出 300 项检查内容；而且即使有人写好了，也没有合适的地方记录每一项的结果。

qarunbook 同时解决这两件事：

1. 列出检查项。 让 AI 助手查看你的代码库，它会找出每个平台上值得测试的所有模块、功能和用户流程，并将它们写成非技术人员也能按步骤操作的检查项。你也可以自行编写，或上传已有的计划。
2. 测试并跟踪。 测试人员从上到下逐项测试，将每项标记为通过或失败，并报告问题。你可以随时查看发布进度，以及有哪些问题阻碍发布。

它专为用户验收测试打造——也就是发布前由真人在实际构建版本上进行的测试。不是单元测试，也不是 CI，而是有人打开应用、注册账号，并尝试实际使用的那种测试。

https://qarunbook.com — 免费使用。

---

为什么需要 MCP 服务

因为交接时，整个流程往往会断掉。测试人员发现 Bug 后，把它写进电子表格或发到 WhatsApp，然后就得有人去读懂、修复，并记得通知测试人员问题已解决。

qarunbook 通过 MCP 提供运行手册，让你的编码助手直接参与这个流程：

list_issues            what did the testers actually find (and what they attached)
list_checks failing    what is broken right now
edit_issue             that report was vague — here is what actually happens
resolve_issue          I fixed it

测试人员可以在网页应用中为问题附上截图、屏幕录制和日志。视频会直接在页面中播放，因此你可以直接观看 Bug，而不只是阅读相关描述。

问题标记为已修复后，检查项不会悄悄恢复为通过，而是显示 R — 重新测试，因为上次通过检查的人看到的构建版本还没有包含修复内容。有人再次实际检查后，这个状态才会清除。状态由标记和问题推导得出，而非单独存储，因此运行手册绝不会在无人察觉的情况下出现自相矛盾的状态。

安装

选择你的助手。对于 Claude Code、Cursor 和 Codex，该仓库是一个插件市场，因此安装一次即可同时获得 MCP 连接和两个技能；你只需手动添加令牌。你可以在 qarunbook 主页的连接 AI下找到令牌。令牌属于你，而非工作区。它会以你的身份和角色运行，移除你的账号后也只会撤销这个令牌。

Claude Code

/plugin marketplace add Ifeanyiejindu/qarunbook
/plugin install qarunbook@qarunbook

（也可以在终端中运行：claude plugin marketplace add Ifeanyiejindu/qarunbook，然后运行 claude plugin install qarunbook@qarunbook）

然后设置你的令牌：

export QARUNBOOK_TOKEN="qarb_…"

Cursor

Cursor 安装的是插件，而不是独立的技能文件夹，因此该仓库提供了 .cursor-plugin 市场清单。在 Cursor 中：

1. 在侧边栏打开自定义，选择来自 GitHub 存储库 （或选择插件 → 添加市场）。
2. 粘贴 https://github.com/Ifeanyiejindu/qarunbook。
3. 安装 qarunbook。
4. 在插件 → 配置中，将 QARUNBOOK_TOKEN 设为你的令牌。

安装到此完成：qa-runbook MCP 服务和两个技能会一并安装。

Codex

该仓库也是 Codex 插件市场（.agents/plugins/marketplace.json）。 在启动 Codex 的 shell 中：

export QARUNBOOK_TOKEN="qarb_…"
codex plugin marketplace add Ifeanyiejindu/qarunbook

然后在 Codex 中运行 /plugins，找到 qarunbook 并安装。Codex 连接时会从环境中读取令牌，并将其作为 bearer 令牌发送。稍后可通过 codex plugin marketplace upgrade 更新。

其他 Agent — Gemini CLI、OpenCode、Cline 等

分为两部分：技能和 MCP 连接。

任何能读取 SKILL.md 文件的工具都可以通过 skills CLI 获取这些技能：

npx skills add Ifeanyiejindu/qarunbook --global

稍后可通过 npx skills update -g 更新技能。然后手动连接 MCP 服务：这是一个 Streamable HTTP 服务，地址为 https://qarunbook.com/api/mcp，使用 Authorization: Bearer <your token> 进行身份验证。

不安装插件的连接方式

如果你只需要 MCP 连接，不需要技能，可以直接添加服务器。

Claude Code：

claude mcp add qa-runbook --transport http https://qarunbook.com/api/mcp \
  --header "Authorization: Bearer qarb_…"

Codex — ~/.codex/config.toml：

[mcp_servers.qa-runbook]
url = "https://qarunbook.com/api/mcp"
bearer_token_env_var = "QARUNBOOK_TOKEN"

Cursor — ~/.cursor/mcp.json：

{
  "mcpServers": {
    "qa-runbook": {
      "url": "https://qarunbook.com/api/mcp",
      "headers": { "Authorization": "Bearer qarb_…" }
    }
  }
}

更新

Claude Code：打开 /plugin，选择 Marketplaces，选中 qarunbook，然后 开启自动更新——Claude Code 会在启动时检查更新。也可以手动更新：

/plugin marketplace update qarunbook
/plugin update qarunbook@qarunbook
/reload-plugins

Cursor 会从 Plugins 面板更新市场插件。Codex： codex plugin marketplace upgrade。

目录结构（供感兴趣的人参考）

同一个插件目录 plugins/qarunbook/，有三种读取方式：

工具	清单	MCP 配置
Claude Code	.claude-plugin/plugin.json	内嵌于清单中
Cursor	.cursor-plugin/plugin.json	mcp.json（令牌来自插件变量）
Codex	.codex-plugin/plugin.json	.codex-plugin/mcp.json（bearer_token_env_var）

技能本身只存放一份，位于 plugins/qarunbook/skills/，并遵循 Agent Skills 格式，因此任何能够读取 SKILL.md 的 Agent 都可以直接使用。

两项技能

/test-checklist	阅读应用代码，判断哪些内容值得测试——涵盖每个模块、功能和用户流程，以及应用发布到的每个平台。将其写成非技术测试人员也能照着执行的步骤，放入你的运行手册（新建应用的运行手册，或为现有应用补上缺失的检查项），然后询问你是否要立即开始测试。
/qa-runbook	执行测试。确定测试范围，创建真实账号，操作 Web 和移动端，记录每项结果及其证据，并验证修复。

两项技能都不是必需的。你可以手动编写计划、上传 Markdown 文件，或 逐项添加检查——这些技能只是让繁琐的部分变得更快。

与其他人协作

工作区用于存放你的应用。成员加入后会获得相应角色：

• 测试人员——记录结果、提出问题
• 管理员——拥有上述权限，还可以编辑计划、导入计划、解决问题、邀请成员
• 所有者——拥有上述权限，还可以管理所有者和工作区

Web 应用和 MCP 工具都会执行角色权限——测试人员的令牌无法编辑计划。

你还可以选择成员能看到哪些应用：全部应用，或你指定的应用。被邀请来测试某个产品的人，不会看到你正在开发的其他所有产品的列表。

每个人都有自己的 MCP 令牌，因此通过令牌操作的助手会以该成员的身份执行操作——写入的内容会记录其姓名；移除该成员即可撤销其全部访问权限。

工具

读取：list_apps · progress · list_checks · get_check · list_issues 写入：set_result · add_issue · edit_issue · resolve_issue · update_check · add_check · add_section · create_app · import_plan

import_plan 一次调用即可接收完整的 Markdown 测试计划并据此创建应用，这也是将实际运行手册导入系统的方式——一份计划可能包含数百项检查，逐项添加并不可取。

自托管

服务器是一个基于 MongoDB 的小型 Next.js 应用。设置 QA_MONGO_URI 和 QA_SESSION_SECRET，部署后，将 QARUNBOOK_URL 指向你自己的实例。 电子邮件（邀请、密码重置）是可选的——未配置邮件服务提供商时，账号会自行验证，不会因此将任何人拒之门外。

许可协议

MIT——请参阅 LICENSE。qarunbook.com 上的托管服务在新推出期间免费。

状态

正在使用，持续改进。新推出期间免费。如有功能损坏或缺失， 请提出 issue。