bugtracker-cli

BugTracker 缺陷管理系统命令行工具 — AI-first CLI，支持人类直接使用和 AI Agent 自动调用。

特性

• 15 个命令覆盖缺陷全生命周期：查询、修复、验证、拒绝、转派、评论、分配、项目管理
• AI-first 设计：--format json 输出结构化数据，--dry-run 预览操作，schema 枚举自省
• 多 Agent 兼容：安装时自动部署 Skill 到 Qoder / Claude Code / Cursor / Codex
• 安全保障：Token 使用 AES-256-CBC 加密存储
• 灵活输出：支持 json / table / pretty 三种格式

安装

npm install -g bugtracker-cli

安装完成后会自动将 Agent Skill 部署到已检测到的 AI Agent 目录（~/.qoder/skills/、~/.claude/skills/ 等）。

也可以使用 npx 直接运行（无需全局安装）：

npx bugtracker-cli get APP-0001 --format json

快速开始

# 1. 登录
bug-cli login

# 2. 设置默认项目（后续命令可省略 -p 参数）
bug-cli config set projectId <你的项目GUID>

# 3. 查看状态
bug-cli status

# 4. 查询待办
bug-cli list --quick-filter assignedToMe

# 5. 获取详情
bug-cli get APP-0042

# 6. 开始修复（预览模式）
bug-cli fix APP-0042 --dry-run

# 7. 确认执行
bug-cli fix APP-0042

全局选项

所有命令共享以下选项：

| 选项 | 说明 | 默认值 | |------|------|--------| | -f, --format <json\|table\|pretty> | 输出格式 | pretty | | -p, --project <GUID> | 项目 ID | config 中配置的 projectId | | --base-url <url> | API 基础地址 | https://testwxgzh.ezhisoft.com:9916/api/v1 | | -n, --dry-run | 试运行模式，仅预览不执行 | false |

命令参考

查询命令

# 获取 Bug 详情（支持 APP-0001 可读 ID 或 GUID）
bug-cli get <bugId>

# 查询 Bug 列表
bug-cli list [筛选参数]

list 命令筛选参数：

| 参数 | 说明 | 示例 | |------|------|------| | -k, --keyword | 标题/BugId 模糊搜索 | -k "登录" | | -s, --status | 状态筛选（逗号分隔） | -s "ToDo,InProgress" | | -pri, --priority | 优先级 | -pri "High,Urgent" | | -sev, --severity | 严重度 | -sev "Critical,High" | | -a, --assignee | 负责人 ID | -a "<GUID>" | | -r, --reporter | 报告人 ID | -r "<GUID>" | | -m, --module | 模块 ID | -m "<GUID>" | | -qf, --quick-filter | 快捷筛选 | -qf assignedToMe | | --sort-by | 排序字段 | --sort-by priority | | --sort-order | 排序方向 | --sort-order asc | | --page / -ps | 分页参数 | --page 1 -ps 20 | | --created-from / --created-to | 创建日期范围 | --created-from 2026-01-01 |

写操作命令

所有写操作支持 --dry-run 预览：

# 开始修复（ToDo → InProgress）
bug-cli fix <bugId>

# 提交验证（InProgress → QA）
bug-cli verify <bugId> [-n "验证备注"]

# 拒绝 Bug（仅 Requirement 类型可被拒绝）
bug-cli reject <bugId> -r "拒绝原因"

# 转派负责人
bug-cli transfer <bugId> -t <新负责人GUID> [-r "转派原因"]

# 通用状态变更（直接指定目标状态）
bug-cli status-change <bugId> -s <目标状态>

# 分配负责人
bug-cli assign <bugId> -a <用户GUID>

# 添加评论
bug-cli comment <bugId> -c "评论内容" [-t Normal|VerificationNote]

账号与配置命令

bug-cli login                          # 登录（交互式输入邮箱和密码）
bug-cli logout                         # 登出（清除本地 Token）
bug-cli status                         # 查看登录状态和当前配置
bug-cli config set <key> <value>       # 设置配置项
bug-cli config get <key>               # 获取配置项
bug-cli config list                    # 列出所有配置

可配置项：apiBaseUrl、projectId、projectKey。

项目管理命令

# 查询项目列表
bug-cli project list                   # 表格格式
bug-cli project ls --format json       # JSON 格式

# 设置默认项目
bug-cli project use <项目GUID>         # 设置 projectId
bug-cli project use <GUID> --key APP   # 同时设置 projectKey

也可以使用 config 命令手动设置：

bug-cli config set projectId <GUID>
bug-cli config set projectKey <KEY>

枚举自省命令

bug-cli schema                  # 查看所有枚举值
bug-cli schema status           # 状态枚举
bug-cli schema priority         # 优先级枚举
bug-cli schema severity         # 严重度枚举
bug-cli schema transitions      # 合法状态流转规则
bug-cli schema --format json    # JSON 格式（AI 解析用）

枚举值速查

状态

| 值 | 数字 | 标签 | |----|------|------| | ToDo | 0 | 待办 | | InProgress | 1 | 进行中 | | QA | 2 | 验证中 | | Done | 3 | 已完成 | | Suspended | 4 | 已挂起 | | Closed | 5 | 已关闭 | | Rejected | 6 | 需求驳回 | | PartiallyDone | 7 | 部分完成 |

优先级

| 值 | 数字 | 标签 | |----|------|------| | Low | 0 | 低 | | Medium | 1 | 中 | | High | 2 | 高 | | Urgent | 3 | 紧急 |

严重度

| 值 | 数字 | 标签 | |----|------|------| | Optimization | 0 | 优化 | | Medium | 1 | 中等 | | High | 2 | 高 | | Critical | 3 | 严重 | | Requirement | 4 | 需求 |

状态流转

ToDo → InProgress  (开始处理)
ToDo → Suspended   (挂起)
InProgress → QA    (提交验证)
InProgress → Suspended (挂起)
QA → Done          (验证通过)
QA → InProgress    (验证失败)
QA → ToDo          (驳回待办)
Suspended → ToDo   (恢复处理)
Suspended → Closed (关闭不处理)
Closed/Done/Rejected → InProgress/ToDo (重新打开)
PartiallyDone → QA (全部完成)
PartiallyDone → Suspended (挂起)

环境变量

| 变量 | 说明 | |------|------| | BUGTRACKER_TOKEN | 直接传入 Token，跳过登录步骤 | | BUGTRACKER_API_URL | API 基础地址 |

AI Agent 集成

本工具设计为人类和 AI Agent 均可使用。npm install 时会自动将 Skill 文件安装到检测到的 AI Agent 目录：

| Agent | Skill 目录 | |-------|-----------| | Qoder | ~/.qoder/skills/bug-tracker/ | | Claude Code | ~/.claude/skills/bug-tracker/ | | Cursor | ~/.cursor/skills/bug-tracker/ | | Codex | ~/.codex/skills/bug-tracker/ |

AI Agent 使用规则

1. 始终使用 --format json 获取结构化数据便于解析
2. 写操作前必须 --dry-run 预览效果
3. 状态变更前查 schema transitions 确认合法性
4. 只读命令可并行执行（get/list/schema/status），写命令必须串行

典型 AI 工作流

# 1. 查看登录状态
bug-cli status --format json

# 2. 查询待办
bug-cli list --format json -qf assignedToMe -p <projectId>

# 3. 获取 Bug 详情
bug-cli get APP-0042 --format json -p <projectId>

# 4. 预览操作
bug-cli fix APP-0042 --dry-run -p <projectId>

# 5. 确认执行
bug-cli fix APP-0042 -p <projectId>

# 6. 完成后提交验证
bug-cli verify APP-0042 -n "修复完成并自测通过" -p <projectId>

开发

# 克隆仓库
git clone <repo-url>
cd bugtracker-cli

# 安装依赖
npm install

# 开发运行（tsx 热加载）
npm run dev -- get APP-0042

# 构建
npm run build

# 类型检查
npm run type-check

# 本地测试
npm pack
npm install -g ./bugtracker-cli-1.0.0.tgz

License

MIT