安装与初始化

安装

通过 npm（推荐）

npm i -g @kuwork/backlog.md

通过 Bun

bun add -g @kuwork/backlog.md

通过 Homebrew（macOS / Linux）

Homebrew formula 目前仍指向上游仓库：

brew install backlog-md

通过 Nix

Nix flake 目前仍指向上游仓库：

nix run github:MrLesk/Backlog.md

GitHub Releases

访问 Releases 页面下载对应平台的二进制文件。

Apple Silicon（M1/M2）提示：如果你通过 Rosetta 运行 x64 版 Node 或 Bun，CLI 启动器会自动检测本机架构与 Rosetta 状态，解析到匹配的 arm64 平台包；若安装的包与 CPU 架构不匹配，会给出明确的架构信息与重装命令，避免 illegal hardware instruction 错误。若遇到二进制解析问题，优先用原生 arm64 运行时重新安装。

初始化项目

进入你的 Git 仓库根目录，执行：

backlog init [project-name]

交互式向导将引导你完成：

• 项目名称
• 默认任务状态列表
• 标签定义
• AI 集成方式选择（MCP / CLI 指令 / 跳过）

自定义任务 ID 前缀（--task-prefix）时只能使用字母，且 doc、decision 为保留名称（分别被文档与决策占用），所有入口都会拒绝。

无 Git 的纯文件系统项目

backlog init --no-git

适用于非代码项目的任务管理。

在其他目录初始化（BACKLOG_CWD）

backlog init 不识别 --cwd 这个命令行 flag（只有 mcp start 接受 --cwd）；它只支持两种目标目录指定方式：一是切换 shell 当前目录后运行，二是由 BACKLOG_CWD 环境变量钉死目录（优先级高于 process.cwd()，最后回退到当前工作目录）。

# 方式一：切到目标仓库目录后初始化（最直白）
cd /path/to/repo && backlog init my-project

# 方式二：在 CI 或脚本中用环境变量固定工作目录（目录必须已存在）
BACKLOG_CWD=/path/to/repo backlog init my-project

BACKLOG_CWD 要求指向的目录必须已存在，否则会 fail-closed 报错（Invalid directory from BACKLOG_CWD）并退出。init 经由统一的运行时 cwd 解析（requireRuntimeCwd），因此 BACKLOG_CWD 与后续所有命令看到同一个目标目录——init 不再只认进程的当前目录。TUI 与 Web 服务器同样遵循此解析规则。

非交互初始化（CI / 脚本）

--defaults 跳过全部交互提示、使用默认值，适合 CI 与脚本场景；其余参数按需在命令行指定：

# 全部默认值，一次性完成初始化
backlog init "My Project" --defaults

# 指定 AI 集成方式（cli / mcp / none，默认 cli）
backlog init "My Project" --defaults --integration-mode cli

# 指定要生成的代理指令文件（逗号分隔；cursor 会写 AGENTS.md；none 表示跳过）
backlog init "My Project" --defaults --agent-instructions agents,claude

常用非交互参数：

初始化后目录结构

backlog/
├── tasks/          # 任务文件
├── docs/           # 文档
├── decisions/      # 决策记录
├── drafts/         # 草稿
├── milestones/     # 里程碑
├── archive/        # 归档
├── completed/      # 已完成任务
├── assets/         # 附件
├── config.yml      # 项目配置
└── wiki/           # 知识库（可选）

验证安装

backlog --version

裸运行（无子命令）将显示欢迎界面并检测当前目录是否已初始化：

backlog

升级 Backlog.md

升级渠道与安装渠道对应：

npm / Bun：更新全局包到最新版（包名 @kuwork/backlog.md）

npm update -g @kuwork/backlog.md
# 或强制重装最新版
npm i -g @kuwork/backlog.md@latest

Homebrew（上游 formula）：

brew upgrade backlog-md

GitHub Releases 二进制：到 Releases 下载新版替换旧二进制即可。

升级后建议做两件事：

1. backlog --version 确认新版本生效。
2. 在项目根目录重跑 backlog init（无需参数）——它会补建新版本引入的缺失目录（如 memos/、docs/ 等，ensureBacklogStructure()），已有配置与数据不会被覆盖。

配置管理

初始化后可通过高级配置向导调整：

backlog config

可配置项包括：

• 任务 ID 前缀
• 默认状态列表
• Definition of Done 默认清单
• 默认编辑器
• Web UI 端口与自动打开浏览器
• Git 集成选项（自动提交、绕过 hooks 等）

Related Concepts

• 产品概述 — Backlog.md 核心定位与功能概览
• AI 集成设置 — 初始化后的 AI 集成配置
• 配置管理 — 初始化后的配置调整