Backlog.md 将任何包含 Git 仓库的文件夹变成一个 自包含的项目看板
由纯 Markdown 文件和零配置 CLI 驱动。
✨ 功能特性
- 📝 Markdown 原生任务 ------ 每个问题都用
.md文件管理 - 🔒 100% 私有 & 离线 ------ backlog 完全存在于你的仓库内部
- 📊 即时终端看板 ------
backlog board在终端中绘制实时看板 - 📤 看板导出 ------
backlog board export创建可分享的 Markdown 报告 - 🌐 现代化 Web 界面 ------
backlog browser启动简洁的网页 UI，进行任务可视化管理 - 🤖 AI 就绪 CLI ------ "Claude，请接手任务 33"
- 🔍 丰富的查询命令 ------ 轻松查看、筛选、归档任务
- 💻 跨平台支持 ------ 可运行在 macOS、Linux、Windows
- 🆓 MIT 许可开源 ------ 免费用于个人或商业
🚀 五分钟上手
markdown
# 1. 安装 Backlog.md
bun/npm i -g backlog.md 或 brew install backlog-md
# 2. 初始化仓库和 backlog
backlog init "我的项目"
# 3. 捕捉任务
backlog task create "将 markdown 渲染为看板"
# 4. 查看进展
backlog board view 或 backlog browser
# 5. 使用 Claude、Gemini、Codex 或 Jules 创建任务
Claude，我想在 Web 界面里增加搜索功能，搜索范围包括：
* 任务
* 文档
* 决策
请创建相应的任务。
# 6. 将任务交给 AI 执行
Claude，请实现与 Web 搜索功能相关的所有任务 (task-10, task-11, task-12)
* 在写代码前使用 'ultrathink mode' 规划实现方案
* 任务允许时使用多个子代理并行所有数据都会保存在 backlog 文件夹下，格式为 task-<task-id> - <task-title>.md（例如 task-10 - 添加核心搜索功能.md）。
🌐 Web 界面
r
# 启动 Web 服务（自动打开浏览器）
backlog browser
# 自定义端口
backlog browser --port 8080
# 不自动打开浏览器
backlog browser --no-open
Web 界面功能：
- 交互式看板，支持拖拽
- 任务创建与编辑，带表单与验证
- 实时更新
- 响应式设计，桌面/移动端兼容
- 任务归档，带确认提示
- 无缝 CLI 集成 ------ 与 Markdown 文件保持同步
🖥️ CLI 参考
项目初始化
| 操作 | 示例 |
|---|---|
| 初始化项目 | backlog init [project-name] |
| 重新初始化 | backlog init |
任务管理
| 操作 | 示例 |
|---|---|
| 创建任务 | backlog task create "添加 OAuth 系统" |
| 带描述 | backlog task create "功能" -d "添加认证系统" |
| 带负责人 | backlog task create "功能" -a @sara |
| 带状态 | backlog task create "功能" -s "进行中" |
| 带标签 | backlog task create "功能" -l auth,backend |
| 带优先级 | backlog task create "功能" --priority high |
| 带计划 | backlog task create "功能" --plan "1. 调研\n2. 实现" |
| 带验收标准 | backlog task create "功能" --ac "必须可用,必须测试" |
| 带备注 | backlog task create "功能" --notes "已开始初步调研" |
| 带依赖 | backlog task create "功能" --dep task-1,task-2 |
| 创建子任务 | backlog task create -p 14 "支持 Google 登录" |
| 所有选项 | backlog task create ... |
| 列出任务 | backlog task list [-s <状态>] [-a <负责人>] [-p <父任务>] |
| 查看详情 | backlog task 7 |
| 编辑任务 | backlog task edit 7 -a @sara -l auth,backend |
| 添加计划 | backlog task edit 7 --plan "实现方案" |
| 添加/删除/勾选验收标准 | backlog task edit 7 --ac "..." --remove-ac 2 --check-ac 1 |
| 添加备注 | backlog task edit 7 --notes "完成了 X，正在做 Y" |
| 添加依赖 | backlog task edit 7 --dep task-1 --dep task-2 |
| 归档任务 | backlog task archive 7 |
草稿工作流
| 操作 | 示例 |
|---|---|
| 创建草稿 | backlog task create "功能" --draft |
| 草稿流 | backlog draft create "GraphQL 调研" → backlog draft promote 3.1 |
| 降级为草稿 | backlog task demote <id> |
看板操作
| 操作 | 示例 |
|---|---|
| 打开看板 | backlog board |
| 导出看板 | backlog board export [文件名] |
| 带版本导出 | backlog board export --export-version "v1.0.0" |
统计 & 概览
| 操作 | 示例 |
|---|---|
| 项目概览 | backlog overview |
文档管理
| 操作 | 示例 |
|---|---|
| 创建文档 | backlog doc create "API 指南" |
| 带路径 | backlog doc create "安装指南" -p guides/setup |
| 带类型 | backlog doc create "架构设计" -t technical |
| 列出文档 | backlog doc list |
| 查看文档 | backlog doc view doc-1 |
决策记录
| 操作 | 示例 |
|---|---|
| 创建决策 | backlog decision create "使用 PostgreSQL 作为主库" |
| 带状态 | backlog decision create "迁移到 TypeScript" -s proposed |
AI 代理指令
| 操作 | 示例 |
|---|---|
| 更新代理文件 | backlog agents --update-instructions |
维护
| 操作 | 示例 |
|---|---|
| 清理已完成任务 | backlog cleanup |
⚙️ 配置
配置命令
| 操作 | 示例 |
|---|---|
| 查看所有配置 | backlog config list |
| 获取单个配置 | backlog config get defaultEditor |
| 设置配置值 | backlog config set defaultEditor "code --wait" |
| 启用自动提交 | backlog config set autoCommit true |
| 跳过 git hooks | backlog config set bypassGitHooks true |
| 开启跨分支检查 | backlog config set checkActiveBranches true |
| 设置活跃分支天数 | backlog config set activeBranchDays 30 |
可用配置选项
| 键 | 作用 | 默认值 |
|---|---|---|
defaultAssignee |
默认负责人 | [] |
defaultStatus |
第一个列状态 | To Do |
statuses |
看板列 | [To Do, In Progress, Done] |
dateFormat |
日期时间格式 | yyyy-mm-dd hh:mm |
timezonePreference |
时区 | UTC |
includeDatetimeInDates |
新建日期是否包含时间 | true |
defaultEditor |
编辑器 | 平台默认 |
defaultPort |
Web UI 端口 | 6420 |
autoOpenBrowser |
是否自动打开浏览器 | true |
remoteOperations |
启用远程 git 操作 | true |
autoCommit |
自动提交任务变更 | false |
bypassGitHooks |
跳过 git hooks | false |
zeroPaddedIds |
ID 是否零填充 | (禁用) |
checkActiveBranches |
跨分支检查任务状态 | true |
activeBranchDays |
活跃分支天数 | 30 |
📤 共享与导出
看板导出
| 操作 | 示例 |
|---|---|
| 导出到默认文件 | backlog board export |
| 导出到自定义文件 | backlog board export project-status.md |
| 强制覆盖已有文件 | backlog board export --force |
| 导出到 README.md | backlog board export --readme |
| 导出并带版本号 | backlog board export --export-version "v1.2.3" |
| 导出到 README 并带版本号 | backlog board export --readme --export-version "Release 2024.12.1-beta" |
📊 项目状态示例 (v1.8.3)
由 Backlog.md 自动生成
| 待办 | 进行中 | 已完成 |
|---|---|---|
| TASK-228 - 替换 @uiw/react-md-editor 为 TOAST UI Editor #web-ui #enhancement #editor | └─ TASK-24.1 - CLI: 看板里程碑视图 [@codex] | TASK-232 - 修复 Nix 构建缺失 libstdc++.so.6 |
| TASK-227 - Web UI: 交互式验收标准编辑器 | TASK-231 - 修复状态分组大小写不敏感问题 | |
| TASK-222 - 改进 Web UI 中任务与子任务可视化 | TASK-230 - CLI 添加 --plain 参数 | |
| TASK-217 - 拖拽式 Web UI 序列视图 | TASK-226 - CLI 验收标准按索引增删 | |
| TASK-216 - 序列 API 与 Web UI | TASK-225 - 修复 CLI board 忽略配置问题 | |
| TASK-215 - 序列 TUI 界面 | ||
| TASK-214 - CLI 列出序列（纯文本） | ||
| TASK-213 - 从任务依赖计算序列 | ||
| TASK-208 - Web UI 支持粘贴为 Markdown | ||
| TASK-200 - 初始化时集成 Claude Code |