BugPack
30 秒将 Bug 截图打包为 AI 可读的修复指令
快速开始 · MCP 配置 · OpenClaw · 功能特性 · 平台集成
English | 中文
---
---
## 什么是 BugPack？
BugPack 是一个**本地优先**的工具，将 Bug 截图打包为结构化的、AI 可读的修复指令。
测试人员在群里发了截图 → 你 `Ctrl+V` 粘贴到 BugPack → 标注问题区域 → 生成结构化指令 → 喂给 AI 编程助手。
或者跳过复制粘贴：BugPack 内置 **MCP Server**，让任何兼容 MCP 的 AI 编程工具（Claude Code、Cursor、Windsurf、Cline 等）**直接读取 Bug 上下文并自动修复代码**。
## 为什么用 BugPack？
AI 编程助手改变了我们写代码的方式，但没有改变我们**传递 Bug 上下文**的方式。
每次修 Bug 仍然需要：保存截图 → 创建文件 → 写路径 → 描述问题 → 粘贴给 AI。
一天 10 个 Bug = **1-2 小时的纯重复劳动**。
BugPack 把这个过程压缩到 **30 秒**。
## 环境要求
- **Node.js** >= 18
- **操作系统** — Windows / macOS / Linux
- **浏览器** — Chrome / Edge / Firefox（推荐 Chrome）
## 快速开始
```bash
npx bugpack-mcp
```
打开 `http://localhost:3456`，`Ctrl+V` 粘贴你的第一张 Bug 截图即可开始。
## MCP 配置
BugPack 兼容**任何支持 MCP 的 AI 编程工具**。以下是常见配置示例。
**Claude Code** — 添加到 `~/.claude.json`：
```json
{
"mcpServers": {
"bugpack": {
"type": "stdio",
"command": "npx",
"args": ["bugpack-mcp", "--mcp"]
}
}
}
```
Cursor / Windsurf / VS Code / Cline / Roo Code / Trae / MarsCode / Augment
**Cursor** (`.cursor/mcp.json`)：
```json
{
"mcpServers": {
"bugpack": {
"command": "npx",
"args": ["bugpack-mcp", "--mcp"]
}
}
}
```
**Windsurf** (`~/.codeium/windsurf/mcp_config.json`)：
```json
{
"mcpServers": {
"bugpack": {
"command": "npx",
"args": ["bugpack-mcp", "--mcp"]
}
}
}
```
**VS Code** (`.vscode/mcp.json`)：
```json
{
"servers": {
"bugpack": {
"command": "npx",
"args": ["bugpack-mcp", "--mcp"]
}
}
}
```
**Cline / Roo Code**（VS Code 设置）：
```json
{
"cline.mcpServers": {
"bugpack": {
"command": "npx",
"args": ["bugpack-mcp", "--mcp"]
}
}
}
```
**Trae** (`trae/mcp.json`)：
```json
{
"mcpServers": {
"bugpack": {
"command": "npx",
"args": ["bugpack-mcp", "--mcp"]
}
}
}
```
**MarsCode**（设置 → MCP）：
```json
{
"mcpServers": {
"bugpack": {
"command": "npx",
"args": ["bugpack-mcp", "--mcp"]
}
}
}
```
**Augment** (`augment/mcp.json`)：
```json
{
"mcpServers": {
"bugpack": {
"command": "npx",
"args": ["bugpack-mcp", "--mcp"]
}
}
}
```
所有兼容 MCP 的工具配置方式相同 — `command` 指向 `npx`，`args` 设为 `["bugpack-mcp", "--mcp"]`。
配置完成后，直接告诉你的 AI：
- **"显示待修复的 Bug"** → AI 调用 `list_bugs`
- **"修复 Bug #3"** → AI 调用 `get_bug_context`，定位代码并修复
- **"标记 Bug #3 为已修复"** → AI 调用 `mark_bug_status`
## OpenClaw 技能
BugPack 提供 [OpenClaw](https://github.com/openclaw/openclaw) 技能包，支持 OpenClaw 协议的 AI 助手可直接使用。
**通过 CLI 安装：**
```bash
clawhub install bugpack
```
**或添加到 `~/.openclaw/openclaw.json`：**
```json
{
"skills": {
"entries": {
"bugpack": {
"enabled": true
}
},
"extraDirs": ["./skills"]
}
}
```
**或手动安装**：将本仓库的 `skills/` 目录复制到你的工作区或 `~/.openclaw/skills/`。
BugPack 包含 3 个内置技能：
| 技能 | 触发方式 | 说明 |
|------|----------|------|
| `bugpack-list-bugs` | "显示 Bug" / "列出 Bug" | 列出所有 Bug，支持状态过滤 |
| `bugpack-view-bug` | "查看 Bug" / "Bug 详情" | 获取完整 Bug 详情，包含截图和关联文件 |
| `bugpack-fix-bug` | "修复 Bug" / "修 Bug" | 读取上下文 → 定位代码 → 修复 → 更新状态 |
> **注意：** OpenClaw 技能需要 BugPack 服务运行中（`npx bugpack-mcp`）。技能通过 REST API 与本地服务通信（`http://localhost:3456`）。
## 功能特性
### 截图与标注
- **剪贴板粘贴** — `Ctrl+V` 从任何聊天工具直接粘贴截图
- **拖放上传** — 拖放图片文件到画布
- **9 种标注工具** — 拖拽/平移、选择、矩形、箭头、文字、编号、高亮、画笔、马赛克
- **对比模式** — 并排对比"当前效果"与"预期效果"
- **撤销/重做** — 完整操作历史
### AI 指令生成
- **一键生成** — 生成结构化 Markdown 修复指令
- **通用 MCP 支持** — 兼容任何支持 MCP 的 AI 编程工具
### MCP Server
内置 MCP Server 让 AI 编程助手**直接访问 Bug 上下文**：
| 工具 | 说明 |
|------|------|
| `list_bugs` | 列出所有 Bug，支持状态/项目过滤 |
| `get_bug_context` | 获取完整 Bug 上下文（描述 + 截图 + 环境 + 文件） |
| `get_bug_screenshot` | 获取单张标注截图（base64） |
| `mark_bug_status` | 更新 Bug 状态 |
| `add_fix_note` | 修复后添加备注 |
### 平台集成
从项目管理平台导入 Bug，同步修复状态：
- **禅道** · **Jira** · **Linear** · **TAPD**
### 更多
- **100% 本地** — 数据不离开你的机器，SQLite 存储
- **多项目管理** — 按项目独立管理 Bug
- **深色/浅色主题** — 跟随你的偏好
- **国际化** — 中文 / 英文
- **快捷键** — 高效工作流
## 工作流
```
粘贴截图 → 描述问题 → 生成指令 → AI 修复代码
│ │ │
│ ┌────────────┘ │
▼ ▼ ▼
BugPack 复制 Markdown MCP Server
画布 粘贴给 AI 工具 AI 直接读取并修复
```
## 数据存储
所有数据存储在本地：
- **数据目录**：`~/.bugpack/data/`
- **数据库**：`bugpack.db`（SQLite）
- **截图**：`uploads/{项目名}/{uuid}.{ext}`
## 技术栈
| 层级 | 技术 |
|------|------|
| 前端 | React 18 · TypeScript · Tailwind CSS · Zustand |
| 标注 | Fabric.js v6 |
| 后端 | Node.js · Express |
| 数据库 | SQLite (better-sqlite3, WAL 模式) |
| MCP | @modelcontextprotocol/sdk |
## 贡献
请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南。
## 许可证
[MIT](LICENSE)
---
**如果 BugPack 帮到了你，请给个 Star！**
[](https://ko-fi.com/W7W51W5EN5)
