vibe-bugs

轻量 Bug 记录工具，为 vibe 项目设计。快速提单、状态管理、一键导出 Markdown 给 AI 或开发处理。

快速开始

在任意项目根目录运行：

npx vibe-bugs init
npx vibe-bugs

浏览器会自动打开 Bug Tracker 界面。

安装

方式一：npx（推荐，无需安装）

npx vibe-bugs init
npx vibe-bugs

方式二：安装到项目

如果目录还没有 package.json，先初始化：

npm init -y

然后安装：

npm install --save-dev vibe-bugs

在 package.json 中添加脚本：

{
  "scripts": {
    "bugs:init": "vibe-bugs init",
    "bugs": "vibe-bugs"
  }
}

之后运行：

npm run bugs:init  # 首次初始化
npm run bugs       # 启动服务

配合 AI 修复 Bug

.bugs/bug-tracker.md 以结构化 Markdown 存储，可以直接交给 AI 理解和处理。以下是几个常用提示词：

修复所有 Bug

请阅读 .bugs/bug-tracker.md，其中记录了项目的所有 Bug。逐一分析每个 Bug 的描述，在当前代码库中定位问题并修复。修复完成后将对应 Bug 的状态字段更新为「已修复」。

只修复未修复的 Bug

请阅读 .bugs/bug-tracker.md，找出所有状态不是「已修复」「验收完成」「不需要修复」的 Bug。逐一分析描述，在代码库中定位并修复这些问题。修复完成后将对应 Bug 的状态字段更新为「已修复」。

只修复未修复的 P2 及以上 Bug

请阅读 .bugs/bug-tracker.md，找出所有优先级为 P0、P1 或 P2，且状态不是「已修复」「验收完成」「不需要修复」的 Bug。按 P0 → P1 → P2 的优先级顺序逐一修复，修复完成后将对应 Bug 的状态字段更新为「已修复」。

命令

| 命令 | 说明 | | --- | --- | | npx vibe-bugs init | 初始化，在当前目录创建 .bugs/ 数据目录 | | npx vibe-bugs | 启动服务，自动打开浏览器 | | npx vibe-bugs update | 更新 vibe-bugs 到最新版本，刷新工具文件（不覆盖 Bug 数据） | | npx vibe-bugs --port 9000 | 指定端口启动（默认 8899，端口占用时自动递增） | | npx vibe-bugs server init | 初始化云端服务（交互式配置数据库，生成配置文件） | | npx vibe-bugs server | 启动云端多项目服务 | | npx vibe-bugs server --port 3000 | 指定端口启动云端服务 |

云端多项目模式

适合团队协作场景：统一部署到服务器，所有人访问同一个 Bug 管理系统。

部署步骤

1. 创建服务目录并安装数据库驱动

云端模式需要在当前目录安装数据库驱动（mysql2 或 pg）：

mkdir my-bug-server && cd my-bug-server
npm init -y

# 使用 MySQL
npm install mysql2

# 或使用 PostgreSQL
npm install pg

2. 初始化配置

在服务器上运行（交互式引导）：

npx vibe-bugs server init

会提示输入数据库连接信息，自动测试连接并建表，生成 vibe-bugs-server.json：

{
  "port": 3000,
  "attachmentsDir": "./vb-attachments",
  "db": {
    "type": "mysql",
    "host": "127.0.0.1",
    "port": 3306,
    "user": "root",
    "password": "yourpassword",
    "database": "vibe_bugs"
  }
}

3. 启动服务

npx vibe-bugs server

启动后终端输出：

☁️  vibe-bugs 云端服务已启动
   主页:     http://localhost:3000
   后台管理: http://localhost:3000/admin
   局域网:   http://192.168.1.100:3000
   AI 接口:  http://localhost:3000/api/projects/:id/export/markdown

页面说明

| 页面 | 地址 | 说明 | | -------- | -------- | ------------------------------------------------------------ | | 主页 | / | Bug 列表，所有人可访问；查看、新增、编辑、导出 Bug | | 后台管理 | /admin | 项目管理（新增 / 删除项目），需要管理员密码（若已配置） |

后台管理密码

在 vibe-bugs-server.json 中添加 adminPassword 字段即可开启密码保护：

{
  "port": 3000,
  "attachmentsDir": "./vb-attachments",
  "adminPassword": "your-admin-password",
  "db": { "..." }
}

不设置或留空则后台无需密码。密码验证后会保存在浏览器 sessionStorage，关闭标签页后重新验证。

AI 接口

云端模式提供结构化 Markdown 导出接口，可直接给 AI 处理：

# 导出项目 1 的所有 Bug（Markdown 格式，图片为绝对 URL，AI 可直接访问）
curl http://服务器IP:3000/api/projects/1/export/markdown

# 只导出未解决的 Bug
curl http://服务器IP:3000/api/projects/1/export/markdown?filter=unresolved

# 打包下载（含附件图片）
curl http://服务器IP:3000/api/projects/1/export/zip -o bugs.zip

AI 修复完成后同步状态：

curl -X POST http://服务器IP:3000/api/projects/1/sync \
  -H "Content-Type: application/json" \
  -d '{"bugs":[{"bugId":"BUG-001","status":"已修复"},{"bugId":"BUG-002","status":"不需要修复"}]}'

可用状态值：新建 / 修复中 / 已修复 / 验收完成 / 不需要修复

返回示例：

{ "ok": true, "updated": 2, "updatedIds": ["BUG-001","BUG-002"], "notFound": [], "invalid": [] }

AI 提示词示例：

📌 修复项目中所有未解决的 Bug

请访问 http://服务器IP:3000/api/projects/1/export/markdown?filter=unresolved
获取「项目名称」项目所有未解决的 Bug 列表（含截图）。
逐一分析每个 Bug 的描述和图片，在代码库中定位问题并修复。
全部修复完成后，调用以下接口批量更新状态：
POST http://服务器IP:3000/api/projects/1/sync
{"bugs":[{"bugId":"BUG-001","status":"已修复"},{"bugId":"BUG-002","status":"已修复"}]}

📌 只修复 P0/P1 高优先级 Bug

请访问 http://服务器IP:3000/api/projects/1/export/markdown?filter=unresolved
获取「项目名称」项目所有未解决的 Bug，筛选出优先级为 P0 或 P1 的条目。
按 P0 → P1 顺序逐一修复，修复完成后调用：
POST http://服务器IP:3000/api/projects/1/sync
将已修复的 Bug 状态更新为"已修复"。

📌 分析 Bug 并给出修复建议（不直接修改代码）

请访问 http://服务器IP:3000/api/projects/1/export/markdown?filter=unresolved
获取「项目名称」项目所有未解决的 Bug，结合截图逐一分析可能的原因，
给出每个 Bug 的修复思路和建议，不需要直接修改代码。

📌 修复单个指定 Bug

请访问 http://服务器IP:3000/api/projects/1/export/markdown
获取「项目名称」Bug 列表，找到 BUG-XXX，根据描述和图片在代码库中修复该问题。
修复完成后调用：
POST http://服务器IP:3000/api/projects/1/sync
{"bugs":[{"bugId":"BUG-XXX","status":"已修复"}]}

升级

npx 用户（推荐）：

npx vibe-bugs@latest update

本地安装用户：

npm install --save-dev vibe-bugs@latest
npx vibe-bugs update

update 命令只刷新工具自身的文件（如 README），不会覆盖你的 Bug 数据和配置。

init 做了什么

your-project/
  .bugs/
    bug-tracker.md        # Bug 记录文件（建议提交 git）
    status-data.json      # 状态数据
    priority-data.json    # 优先级数据
    config.json           # 项目配置
    attachments/          # 图片附件（自动加入 .gitignore）

• 自动从 package.json 读取项目名称
• 自动将 .bugs/attachments/ 写入 .gitignore

配置

.bugs/config.json：

{
  "projectName": "我的项目",
  "port": 8899,
  "deletePassword": "9527"
}

| 字段 | 说明 | 默认值 | | --- | --- | --- | | projectName | 项目名称，显示在页面标题 | 目录名 | | port | 服务端口 | 8899 | | deletePassword | 删除 Bug 时的验证密码 | 9527 |

功能

记录 Bug

• 点击「+ 新增 BUG」填写描述，支持粘贴 / 拖拽上传截图
• 每条 Bug 自动分配编号（BUG-001、BUG-002…）

优先级

• 每条 Bug 可设置优先级：P0 / P1 / P2 / P3
• 新建时可选择，页面上也可直接修改

状态流转

• 新建 → 修复中 → 已修复 → 验收完成
• 或标记为「不需要修复」
• 支持「只看未修复」快速过滤

导出

• 单条 Bug：点击「下载」，有截图时打包为 ZIP
• 全部 Bug：「下载全部 (ZIP)」，支持只导出未修复的

数据说明

Bug 记录以 Markdown 格式存储在 .bugs/bug-tracker.md，结构清晰，可以直接：

• 提交到 git 与代码一起管理
• 复制给 AI 直接理解和处理
• 用任意编辑器查看和编辑

示例：

## BUG-001

**编号**：BUG-001
**优先级**：P1
**状态**：修复中
**描述**：点击登录按钮无响应
**附件**：![截图](attachments/screenshot.png)

局域网访问

启动后终端会输出局域网地址，团队成员可以在同一网络下访问：

🐛 Bug Tracker — my-project
   本机: http://localhost:8899
   局域网: http://192.168.1.100:8899

License

MIT