企业官网建设流程全解析

beads_rust 是一个用 Rust 编写的本地优先（local-first）issue 追踪工具，命令名为br。它把 Issue 存储在仓库内的 SQLite 数据库中，并自动导出为 Git 友好的 JSONL 文件，让你无需联网、无需账号，就能在代码仓库旁完成依赖感知的任务管理。本文带你用 7 步走完从br init到创建、追踪、关闭第一个 Issue 的完整流程。

1️⃣ 安装 br 命令

br 支持 Linux、macOS 与 Windows（WSL），需要 Rust Nightly 工具链。最简单的方式是通过 Cargo 从源码仓库安装：

git clone https://gitcode.com/gh_mirrors/be/beads_rust.git cd beads_rust cargo build --release sudo cp target/release/br /usr/local/bin/

安装完成后，用下面的命令验证是否成功：

br --version

💡 更完整的安装方式（含预编译二进制、包管理器渠道）可参考官方安装指南：docs/INSTALLING.md

2️⃣ 用 br init 初始化项目

进入你的项目目录，执行初始化：

cd my-project br init

br init会在项目根目录创建隐藏的.beads/目录，里面存放两个核心文件：

这种SQLite + JSONL 双存储设计是 beads_rust 的精髓：SQLite 负责高性能本地读写，JSONL 则能被git diff清晰追踪、干净合并。

3️⃣ 创建你的第一个 Issue

br create "Set up database schema" --type task --priority 1 # Created: br-e9b1d4

几个常用参数：

• --type：任务类型，如feature、task、bug
• --priority：优先级，0最高（critical），4为 backlog

再创建一个功能 Issue：

br create "Implement user auth" --type feature --priority 1 # Created: br-7f3a2c

每个 Issue 都会获得一个类似br-7f3a2c的唯一短 ID，后续所有操作都靠它定位。

4️⃣ 建立 Issue 依赖关系

Issue 之间可以声明"谁阻塞谁"。比如认证功能依赖数据库 Schema 完成：

br dep add br-7f3a2c br-e9b1d4

执行后，br-7f3a2c（auth）会被标记为blocked，直到br-e9b1d4（schema）关闭。这是外部工具很难做到的依赖感知能力——待办清单和 Jira 里都常缺这一环。

5️⃣ 用 br ready 查看可执行任务

br ready # br-e9b1d4 P1 task Set up database schema

br ready只列出未被阻塞的任务，帮你一眼看清"现在该做什么"。对于 AI 编码代理，还可以用机器可读输出：

br ready --json

6️⃣ 认领、完成并关闭 Issue

开始处理时，把状态改为进行中：

br update br-e9b1d4 --status in_progress

完成后关闭并附上原因，JSONL 会自动刷新：

br close br-e9b1d4 --reason "Schema implemented"

再次运行br ready，你会发现依赖被解除，auth 任务自动变为可执行：

br ready # br-7f3a2c P1 feature Implement user auth

这一"依赖链自动流转"的体验，正是本地 issue 追踪工具的核心价值。

7️⃣ 同步导出并提交到 Git

所有变更都会写入 SQLite 并自动导出 JSONL。提交代码前，可运行一次幂等的最终导出检查：

br sync --flush-only git add .beads/ && git commit -m "Update issues"

⚠️ 注意：br 坚持"非侵入"原则——它永远不会替你 commit、push 或 pull，Git 操作始终由你显式执行。

📚 延伸学习

学完 7 步后，推荐按顺序阅读这些仓库内文档：

• 代理工作流快速入门：docs/agent/QUICKSTART.md
• 完整命令参考：docs/CLI_REFERENCE.md
• 同步与恢复机制：docs/SYNC_SAFETY.md
• 项目整体架构：docs/ARCHITECTURE.md
• 故障排查：docs/TROUBLESHOOTING.md

底层存储实现位于 src/storage/sqlite.rs，同步逻辑在 src/sync/，有兴趣了解 SQLite + JSONL 混合引擎内部运作的读者可以深入阅读。

从br init到第一个 Issue 关闭，你只需要 7 条命令。本地、快速、零成本——这就是 beads_rust 带来的极简 issue 追踪体验。