如何从Go版beads（bd）迁移到beads_rust：完整迁移指南与JSONL互通要点-育师

【免费下载链接】beads_rust

Fast Rust port of Steve Yegge's beads: local-first, non-invasive issue tracker storing tasks in SQLite with JSONL export for git collaboration

项目地址：https://gitcode.com/gh_mirrors/be/beads_rust

点击查看免费下载

beads_rust是一个用 Rust 重写的本地优先（local-first）issue 跟踪工具，命令名为br。它将任务存储在仓库内的 SQLite 数据库中，并导出issues.jsonl供 git 协作，完全离线可用。如果你之前一直在用 Go 版 beads（命令bd），好消息是：两者的数据架构一脉相承，迁移本质上是一次机械式的改名 + 一个行为差异的适配，绝大多数人 10 分钟即可完成。

本文带你走一遍完整流程：安装初始化、JSONL 数据互通、命令映射、文档迁移，最后附常见坑点清单。

为什么要迁移到 br？

原版 beads 正在向新的 GasTown 方向演进，而br冻结了经典的 "SQLite + JSONL" 混合架构，保持长期稳定：

维度	bd（Go 版 beads）	br（beads_rust）
存储	SQLite + JSONL	SQLite + JSONL（同构）
`sync`行为	自动提交 git	永不执行 git 命令，仅导出 JSONL
守护进程 / RPC	有	无
速度	快	更快（Rust 原生，冷启动低延迟）
数据目录	`.beads/`	`.beads/`（完全兼容）

核心结论：数据不用搬，格式不用改——因为 JSONL 互通就是为互操作设计的。

一键安装并初始化 br 工作区

安装脚本会自动检测平台并下载对应二进制（支持 Linux、macOS、Windows WSL），仓库内的 install.sh 即为入口：

curl -fsSL <install.sh 地址> | bash

进入你的项目目录后执行：

cd my-project br init # 在 .beads/ 初始化工作区 ls -la .beads/ # beads.db # SQLite 数据库（本地权威存储） # issues.jsonl # git 友好的导出文件

💡 如果.beads/是旧 bd 留下的目录，br可以直接打开它——这就是 JSONL 互通的基础。

数据互通：JSONL 是 bd 与 br 之间的桥梁

br对数据目录采用JSONL 为 git 协作权威、SQLite 为本地索引的双轨模型，配置见 README.md 的 Configuration 一节（.beads/config.yaml中auto_flush与auto_import默认开启）。

导入旧 beads 数据

如果.beads/issues.jsonl中存在 bd 时代的数据，而beads.db缺失或希望以 JSONL 为准，一条命令重建：

# 以 JSONL 为权威，重建 SQLite 并清理库内多余条目 br sync --import-only --rebuild # 若旧数据的 issue ID 前缀不是 br-（例如仍是 bd-xxx），导入时自动改写前缀 br sync --import-only --rebuild --rename-prefix

关于--rename-prefix的三个要点（详见 docs/CLI_REFERENCE.md 的 sync 章节）：

只替换前缀段，ID 的 slug 与 hash 部分原样保留：bd-cargo-license-spdx-ay8→br-cargo-license-spdx-ay8；
旧 ID 会存入新条目的external_ref字段，输出中的prefix_renames列表会完整报告每次改写，方便你修正外部引用；
即使不改前缀，br也容忍bd-前缀的旧 ID（如br show bd-abc123可正常工作），属于刻意保留的跨工具兼容特性。

导出与提交：唯一的"行为差异"

这是迁移中唯一需要改变肌肉记忆的地方：

# bd 时代：bd sync 会自动 commit bd sync # br 时代：只导出 JSONL，git 操作由你自己执行 br sync --flush-only git add .beads/ git commit -m "sync beads"

br是非侵入式（non-invasive）工具，永不执行任何 git 命令、不安装 hook——这既更安全，也意味着文档里必须显式写清 git 步骤（下面会讲）。日常使用中，变更默认会自动 flush 到 JSONL，br sync --flush-only只作为提交前的最终检查。

命令映射表：把 bd 换成 br 就对了

除 sync 外，其余命令都是纯改名（s/bd/br/g即可），完整对照参考 skills/bd-to-br-migration/SKILL.md 的 Command Map：

bd	br	变更类型
`bd ready`/`bd list`/`bd show <id>`	`br ready`/`br list`/`br show <id>`	仅改名
`bd create`/`bd update`/`bd close`	`br create`/`br update`/`br close`	仅改名
`bd dep add`/`bd stats`	`br dep add`/`br stats`	仅改名
`bd sync`	`br sync --flush-only`+ 手动 git	⚠️ 行为变更

优先级体系（P0-P4）、issue 类型、依赖跟踪、.beads/权威地位全部保持不变，无需额外学习成本。

文档与 AGENTS.md 迁移：7 步机械式转换

如果你的仓库里AGENTS.md、工作流文档或 agent 提示词中写满了bd指令，仓库内置了完整的迁移技能包，路径在 skills/bd-to-br-migration/，按 SKILL.md 规定的顺序执行 7 步转换：

章节标题：bd (beads)→br (beads_rust)
标题后补充非侵入式说明（"br 永不执行 git，sync 后需手动git add .beads/ && git commit"）
命令改名：bd X→br X（ready/list/show/create/update/close/dep/stats）
sync 转换：bd sync→br sync --flush-only
每处sync 后补上git add .beads/+git commit
issue ID 改写：bd-###→br-###
彻底删除 daemon、auto-commit、hook 安装、RPC 模式的描述（这些在 br 中不存在）

改完立即验证，bd残留必须为 0：

grep -c '`bd ' AGENTS.md # 必须为 0 grep -c 'bd sync' AGENTS.md # 必须为 0 grep -c 'br sync --flush-only' AGENTS.md # 必须 > 0 # 或使用官方脚本 ./skills/bd-to-br-migration/scripts/verify-migration.sh AGENTS.md

前后可对照示例见 references/TRANSFORMS.md。

批量迁移（10 个文件以上）

多文件项目建议按批处理：先用 scripts/find-bd-refs.sh 列出所有需要迁移的文件，然后每批约 10 个文件交给一个 subagent 顺序转换，每批之间必须跑一次验证再进入下一批。策略细节在 references/BULK.md。

五大常见坑点（附排查方法）

以下内容整理自 references/PITFALLS.md：

#	坑点	症状	排查命令
1	sync 后漏写 git 步骤（最大坑）	会话结束后数据"丢失"	`grep 'br sync --flush-only' f.md && ! grep 'git add .beads/' f.md`
2	只改成`br sync`，漏掉`--flush-only`	行为不符合预期	`grep -n 'br sync$' f.md`
3	同一文件里`bd-123`与`br-123`混用	文档混乱	`grep -n 'bd-[0-9]' f.md`
4	漏加"非侵入式"说明	读者仍期待自动提交	`grep -c 'non-invasive' f.md`应为 > 0
5	残留 daemon / hook / RPC 描述	误导 agent	`grep -in 'daemon\\|hook\\|rpc' f.md`