beads

Beads - AI Agent 的持久任务记忆

基于图的议题跟踪器，可在对话压缩后继续保留。

概述

bd 和 br (beads_rust) 使用存储在 git 中、支持依赖关系的图，取代 Markdown 任务列表。bv 则通过 PageRank 和介数中心性提供图感知分诊。

主要区别：

• bd/br：多会话工作、依赖关系、压缩后仍可保留、由 git 支持
• bv：图分析、优先级分诊、瓶颈检测、并行执行规划
• 任务工具（TaskCreate/TaskUpdate/TaskList）：单会话任务、状态跟踪、限定于对话

决策规则：如果两周后恢复工作时，没有 bd 会很困难，就使用 bd。

br 与 bd：br 是 Rust 重写版。除以下区别外，命令相同：br 从不自动提交（git 操作由你负责），而 bd sync 对应 br sync --flush-only。使用已安装的那个即可。

bv 安全提示：切勿直接运行 bv——它会启动交互式 TUI 并阻塞终端。始终使用 --robot-* 标志。

不要在这里重新学习命令用法。 bd --help / br --help（以及各子命令的 --help）会自行说明每个命令和标志——指定强制执行命令前先运行它们；组合原语，不要凭空创造（composition-over-invention.md）。完整目录见 CLI_REFERENCE.md（bd）、BR_REFERENCE.md（br）和 BV_TRIAGE.md（bv robot 标志）。本技能提供操作准则。

操作规则

• 将实时 bd 读取结果视为权威信息。使用 bd show、bd ready、bd list 和 bd export 检查当前跟踪器状态。如果有实时 bd 数据可用，不要将 .beads/issues.jsonl 视为主要决策依据。
• 在 CI、发布或 rollout 活动之后选择新的就绪工作前，如果可用，优先使用 ao reconcile --json。只有在高严重性 main/release/bead 证据发现项已解决或明确被取代后，才将 bd ready 作为规划输入。
• 将 .beads/issues.jsonl 视为便于 git 使用的导出产物。如果仓库跟踪 .beads/issues.jsonl 且你修改了跟踪器状态，请使用 bd export -o .beads/issues.jsonl 明确刷新。
• 关闭或实质性更新子议题后，在同一会话中协调检查未关闭的父议题。立即更新过时的“剩余差距”说明；如果子议题已解决父议题的最后一个实际差距，则关闭父议题。
• 关闭子议题前，请在 bd close --reason 文本中提供范围明确的关闭证明。 写明改动的文件，或明确说明无文件的证据产物；列出验证命令；并说明父议题 的协调结果。不要为子议题使用“完成”或“已实现”等笼统的关闭原因。
• 如果 bd ready 返回了宽泛的总括议题，不要直接按照含糊的父议题描述实施。先将剩余差距细化为可执行的子议题，然后完成子议题并协调检查父议题。
• 规范过时的队列项，不要默默跳过。将宽泛或已部分涵盖的 beads 改写为实际剩余差距。
• 跟踪器状态发生变化时，使用以下变更后流程：

bd ...                              # mutate tracker state
bd export -o .beads/issues.jsonl    # if tracked in git
bd vc status
bd dolt commit -m "..."             # if tracker changes are pending
bd dolt push                        # only if a Dolt remote is configured

会话结束模式（br——同步是显式操作，绝不会自动进行）：

git pull --rebase
br sync --flush-only                # DB → JSONL (reverse: --import-only after pull)
git add .beads/ && git commit -m "Update issues"
git push

先决条件

• bd CLI：已安装 0.34.0+ 版本并位于 PATH 中
• Git 仓库：当前目录必须是 git 仓库
• 初始化：只需运行一次 bd init（由人类执行，而非 Agent）

示例

用户说： /validate

此技能通过依赖关系加载：Agent 使用 bd show <id> 读取议题元数据，将验证发现项关联到正在检查的议题，并在验证报告中引用议题 ID——无需手动查询 bd。

用户说： /implement ag-xyz-123

此技能加载后会管理议题生命周期：使用 bd show ag-xyz-123 查看正文、检查依赖关系，并在完成后使用 bd close ag-xyz-123（附上范围明确的关闭证明）。

bv 图谱分诊

绝不要直接运行 bv。务必使用 --robot-* 标志（--robot-triage、--robot-next、--robot-plan、--robot-insights、--robot-priority、--robot-alerts——选择指南见 BV_TRIAGE.md）。

关键指标： PageRank = 所有内容都依赖于此（优先修复）。Betweenness = 瓶颈（阻塞多条路径）。两者都高 = 关键瓶颈，立即处理。

计划转 Beads 工作流

将 Markdown 计划转换为依赖关系完整的 beads：

1. 阅读完整计划、AGENTS.md、README、关联的意图 issue 和验收标准。
2. 为每个 issue 使用 br create 创建 beads，并在描述中包含完整上下文。
3. 对于每项功能、错误修复或面向产品的行为，都要包含一个带围栏的 gherkin 代码块，或链接到已填写的意图 issue。只有当验收标准完全基于命令或文件时， 机械性杂务才可以省略 Gherkin。
4. 对于重要的 beads，加入 docs/architecture/intent-to-loop-hexagon.md 中的 hexagon: 边界块：入站端口、有界上下文、适配器、上下文数据包和完成状态。
5. 使用 br dep add / bd dep add 关联依赖项。不要手动编辑 JSONL 或 数据库文件。
6. 反复润色（通常迭代 6-9 轮），直到达到稳定状态。检查是否有功能遗漏、 过度简化、测试缺失、边界不明确、端到端覆盖不足或日志记录薄弱等问题。
7. 验证：br dep cycles 的输出必须为空；运行 bv --robot-insights 检查图谱 健康状况；使用 bv --robot-next 获取第一个 bead。绝不要直接运行 bv。
8. 提交前明确同步：先运行 br sync --flush-only，然后运行 git add .beads/ 并在适当时提交跟踪器更改。

Beads 应当足够详细，让新接手的 Agent 无需查阅原始计划即可实现。可直接开始实现的 beads 应明确范围、列出显式依赖项、包含 BDD 或机械性验收标准、单元测试/端到端测试预期、 详细的日志记录预期、明确命名的完成状态，并且不存在依赖环。

故障排查

症状 → 修复表（找不到命令、不是 git 仓库、缺少 init、ID 前缀错误、bv 卡住、 依赖环、同步方向混淆）：TROUBLESHOOTING.md。最常见的两种情况： bv 卡住表示遗漏了 robot 标志；br sync 混淆表示未指定方向（--flush-only 与 --import-only）。

参考文档

• references/beads.feature — 可执行规范：bd 强制跟踪器、先创建再编写代码、就绪状态检测、discovered-from 链接、实时读取为权威数据（soc-qk4b）

• references/ANTI_PATTERNS.md

• references/BOUNDARIES.md

• references/composition-over-invention.md — 指定强制执行命令前，先运行 bd <subcmd> --help；组合基础操作，不要自行发明

• references/BR_REFERENCE.md

• references/BV_TRIAGE.md

• references/CLI_REFERENCE.md

• references/DEPENDENCIES.md

• references/INTEGRATION_PATTERNS.md

• references/ISSUE_CREATION.md

• references/MIGRATION.md

• references/MOLECULES.md

• references/PATTERNS.md

• references/PLAN_TO_BEADS.md

• references/RESUMABILITY.md

• references/ROUTING.md

• references/STATIC_DATA.md

• references/tracker-migration-and-triage.md

• references/TROUBLESHOOTING.md

• references/WORKFLOWS.md