name: bd-to-br-migration description: >- 将文档从bd（beads）迁移到br（beads_rust）。当更新AGENTS.md、转换bd命令、“bd sync” → “br sync --flush-only”或beads迁移时使用。
<!-- TOC: 哲学 | 确切提示 | 决策树 | 命令映射 | 转换模式 | 验证循环 | 风险层级 | 参考 -->
bd → br 迁移
核心哲学： 一个行为变化，机械转换。唯一的区别是git处理——其他所有内容都是查找替换。
为什么这很重要
不完整的迁移会导致文档损坏。代理遵循过时的bd sync指令，期望自动提交，并丢失工作。这个技能确保完整、验证的迁移。
确切提示 — 单文件迁移
将此文件从bd（beads）迁移到br（beads_rust）。
按此顺序应用转换（顺序重要）：
1. 部分标题："bd (beads)" → "br (beads_rust)"
2. 在beads部分标题后添加非侵入性注释
3. 命令：`bd X` → `br X` 用于ready/list/show/create/update/close/dep/stats
4. 同步命令：`bd sync` → `br sync --flush-only`
5. 在每次同步后添加git步骤：
git add .beads/
git commit -m "sync beads"
6. 问题ID：bd-### → br-### 在thread_ids、subjects、reasons、commits中
7. 链接：beads_viewer → beads_rust（如果存在）
完全删除：
- 守护进程引用
- 自动提交假设
- 钩子安装提及
- RPC模式
保持不变：
- SQLite/WAL警告
- bv集成
- 优先级系统（P0-P4）
编辑后验证：
grep -c '`bd ' file.md # 必须为0
grep -c 'bd sync' file.md # 必须为0
grep -c 'br sync --flush-only' file.md # 必须 > 0
为什么这个提示有效
- 有序转换： 存在依赖关系（同步必须在添加git步骤前更改）
- 明确删除： br中没有守护进程/RPC——保留它们会混淆代理
- 保留列表： 防止意外删除仍有效的模式
- 内置验证： Grep命令捕获遗漏的转换
- 无自由度： 这是一个低自由度任务——需要精确转换
决策树：你在迁移什么？
你在迁移什么？
│
├─ 单文件（AGENTS.md）
│ │
│ └─ 遵循上述确切提示
│ 使用：./scripts/verify-migration.sh file.md
│
├─ 多文件（批量）
│ │
│ ├─ <10 文件 → 顺序：对每个应用提示
│ │
│ └─ 10+ 文件 → 并行子代理
│ 每代理约10个文件
│ 参见：[BULK.md](references/BULK.md)
│
└─ 验证现有迁移
│
└─ 运行：./scripts/find-bd-refs.sh /path
任何输出 = 迁移不完整
一个行为差异
┌─────────────────────────────────────────────────────────────────┐
│ bd (Go) br (Rust) │
├─────────────────────────────────────────────────────────────────┤
│ bd sync → br sync --flush-only │
│ (自动提交到git) (仅导出JSONL) │
│ │
│ + git add .beads/ │
│ + git commit -m "..." │
└─────────────────────────────────────────────────────────────────┘
其他所有内容字面上是 s/bd/br/g
命令映射
| bd | br | 更改类型 |
|---|---|---|
bd ready |
br ready |
仅名称 |
bd list |
br list |
仅名称 |
bd show <id> |
br show <id> |
仅名称 |
bd create |
br create |
仅名称 |
bd update |
br update |
仅名称 |
bd close |
br close |
仅名称 |
bd dep add |
br dep add |
仅名称 |
bd stats |
br stats |
仅名称 |
bd sync |
br sync --flush-only + git |
行为 |
转换模式
模式1：非侵入性注释
在beads部分标题后立即添加：
**注意：** `br` 是非侵入性的，从不执行git命令。在 `br sync --flush-only` 后，你必须手动运行 `git add .beads/ && git commit`。
模式2：同步命令转换
之前：
bd sync
之后：
br sync --flush-only
git add .beads/
git commit -m "sync beads"
模式3：会话结束转换
之前：
git add <files>
bd sync
git push
之后：
git add <files>
br sync --flush-only
git add .beads/
git commit -m "..."
git push
模式4：问题ID转换
之前：
thread_id: bd-123
subject: [bd-123] 功能实现
reason: bd-123
之后：
thread_id: br-123
subject: [br-123] 功能实现
reason: br-123
验证循环
┌─────────────────────────────────────────────────────────────────┐
│ 验证是强制性的 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. 应用转换 │
│ ↓ │
│ 2. 运行验证： │
│ ./scripts/verify-migration.sh file.md │
│ ↓ │
│ 3. 如果失败 → 读错误 → 修复特定问题 → 转到 2 │
│ ↓ │
│ 4. 仅当通过时才继续 │
│ │
│ ⚠️ 永远不要跳过验证。不完整的迁移会破坏代理。│
└─────────────────────────────────────────────────────────────────┘
快速验证命令
# 必须返回 0：
grep -c '`bd ' file.md
grep -c 'bd sync' file.md
grep -c 'bd ready' file.md
# 必须返回 > 0（如果文件有同步部分）：
grep -c 'br sync --flush-only' file.md
grep -c 'git add .beads/' file.md
风险层级
| 操作 | 风险 | 自由度 |
|---|---|---|
命令重命名（bd → br） |
低 | 机械——无需判断 |
| 同步转换 + git步骤 | 中等 | 必须添加git步骤 |
| 移除守护进程引用 | 中等 | 验证不删除有效内容 |
| 批量迁移（10+ 文件） | 高 | 使用带验证的子代理 |
自由度：低
这是一个确定性转换。每个输入只有一个正确输出。
- 无创造性解释
- 无可选改进
- 无风格选择
- 按指定精确应用转换
移除内容
| 模式 | 为什么移除 | 验证不存在 |
|---|---|---|
| “bd daemon” | br 没有守护进程 | grep -i daemon |
| “auto-commits” | br 从不提交 | grep -i "auto.*commit" |
| “git hooks” | br 不安装钩子 | grep -i "hook" |
| “RPC mode” | br 没有 RPC | grep -i "rpc" |
保持不变内容
| 模式 | 为什么保留 |
|---|---|
| SQLite/WAL 警告 | br 仍使用 WAL |
| bv 集成 | 两者都适用 |
| 优先级 P0-P4 | 相同系统 |
| 问题类型 | 相同系统 |
| 依赖跟踪 | 相同系统 |
.beads/ 作为真相来源 |
相同系统 |
之前/之后示例
之前（bd）
## 使用 bd（beads）进行问题跟踪
关键不变式：
- `.beads/` 是权威的
### 代理工作流：
1. `bd ready` 查找工作
2. `bd update <id> --status in_progress`
3. 实现
4. `bd close <id>`
5. `bd sync` 提交更改
之后（br）
## 使用 br（beads_rust）进行问题跟踪
**注意：** `br` 是非侵入性的，从不执行git命令。在 `br sync --flush-only` 后，你必须手动运行 `git add .beads/ && git commit`。
关键不变式：
- `.beads/` 是权威的
### 代理工作流：
1. `br ready` 查找工作
2. `br update <id> --status in_progress`
3. 实现
4. `br close <id>`
5. 同步并提交：
```bash
br sync --flush-only
git add .beads/
git commit -m "sync beads"
---
## 参考
| 需求 | 参考 |
|------|-----------|
| 完整之前/之后示例 | [TRANSFORMS.md](references/TRANSFORMS.md) |
| 批量迁移策略 | [BULK.md](references/BULK.md) |
| 常见错误与修复 | [PITFALLS.md](references/PITFALLS.md) |
---
## 脚本
| 脚本 | 目的 |
|--------|---------|
| `./scripts/find-bd-refs.sh /path` | 查找需要迁移的文件 |
| `./scripts/verify-migration.sh file.md` | 验证迁移完成 |
---
## 验证
```bash
# 完整验证
./scripts/verify-migration.sh /path/to/AGENTS.md
# 快速检查（应该返回空）
grep '`bd ' /path/to/AGENTS.md
如果任何 bd 引用存在 → 迁移不完整 → 重新应用转换。