miniapp-api/test/BugPack-main/README.zh-CN.md

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）

快速开始

npx bugpack-mcp

打开 http://localhost:3456，Ctrl+V 粘贴你的第一张 Bug 截图即可开始。

MCP 配置

BugPack 兼容任何支持 MCP 的 AI 编程工具。以下是常见配置示例。

Claude Code — 添加到 ~/.claude.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)：

{
  "mcpServers": {
    "bugpack": {
      "command": "npx",
      "args": ["bugpack-mcp", "--mcp"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json)：

{
  "mcpServers": {
    "bugpack": {
      "command": "npx",
      "args": ["bugpack-mcp", "--mcp"]
    }
  }
}

VS Code (.vscode/mcp.json)：

{
  "servers": {
    "bugpack": {
      "command": "npx",
      "args": ["bugpack-mcp", "--mcp"]
    }
  }
}

Cline / Roo Code（VS Code 设置）：

{
  "cline.mcpServers": {
    "bugpack": {
      "command": "npx",
      "args": ["bugpack-mcp", "--mcp"]
    }
  }
}

Trae (trae/mcp.json)：

{
  "mcpServers": {
    "bugpack": {
      "command": "npx",
      "args": ["bugpack-mcp", "--mcp"]
    }
  }
}

MarsCode（设置 → MCP）：

{
  "mcpServers": {
    "bugpack": {
      "command": "npx",
      "args": ["bugpack-mcp", "--mcp"]
    }
  }
}

Augment (augment/mcp.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 技能包，支持 OpenClaw 协议的 AI 助手可直接使用。

通过 CLI 安装：

clawhub install bugpack

或添加到 ~/.openclaw/openclaw.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 了解贡献指南。

许可证

MIT

---

如果 BugPack 帮到了你，请给个 Star！