SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场beads

beads

智能体与模型

查看项目

更新于 10-15 14:48

技能介绍

用途

Beads 为 AI 智能体提供持久化的任务记忆。它用存储在 git 中的、带依赖关系的图结构议题追踪器，替代传统的 Markdown 任务清单，使任务状态在对话压缩（compaction）后依然保留。

核心区分：

  • bd / br：多会话工作、依赖关系、可跨压缩存活、由 git 支撑。
  • bv：图分析、优先级分诊、瓶颈检测、并行执行规划。
  • 任务工具（TaskCreate/TaskUpdate/TaskList）：单会话任务、状态追踪、会话范围内。

决策规则：如果两周后恢复工作会因缺少 bd 而困难，就应使用 bd。

br 与 bd：br 是 Rust 重写版，命令基本相同，区别在于 br 从不自动提交（git 操作由用户负责），且 bd sync 变为 br sync --flush-only。使用已安装的任一版本即可。

主要能力

  • 以依赖图方式追踪议题，支持多会话与依赖管理。
  • bv 图分诊：PageRank 表示“所有东西都依赖它”（应优先修复）；中介中心性表示瓶颈（阻塞多条路径）；两者都高则为关键瓶颈。
  • 将 Markdown 计划转换为依赖完整的 beads。
  • 提供可执行规范、反模式、边界、集成模式、迁移、可恢复性等参考文档。

使用方式

运行规则要点：

  • 以实时 bd 读取为权威，使用 bd show、bd ready、bd list、bd export 检查当前追踪器状态；有实时数据时不要以 .beads/issues.jsonl 作为主要决策来源。
  • 在 CI、发布或上线活动后选择新的就绪工作前，优先使用 ao reconcile --json（若可用）。
  • .beads/issues.jsonl 是便于 git 的导出产物；若仓库跟踪该文件且改动了追踪器状态，需用 bd export -o .beads/issues.jsonl 显式刷新。
  • 关闭或实质性更新子议题后，在同一会话中协调开放的父议题。
  • 关闭子议题前，在 bd close --reason 文本中包含限定范围的关闭证据（涉及文件或明确的无文件证据产物、验证命令、父议题协调结果），不要使用“done”“implemented”等笼统理由。
  • 若 bd ready 返回宽泛的总括议题，不要直接按模糊父级措辞实现，应先将剩余缺口收窄为可执行的子议题。
  • 追踪器状态变更后的操作序列：bd ...（变更状态）；bd export -o .beads/issues.jsonl（若 git 跟踪）；bd vc status；bd dolt commit -m "..."（若有待提交变更）；bd dolt push（仅当配置了 Dolt 远程）。

会话结束模式（br，同步是显式的，绝不自动）：

git pull --rebase
br sync --flush-only                # DB → JSONL（反向：pull 后用 --import-only）
git add .beads/ && git commit -m "Update issues"
git push

bv 安全：绝不要运行裸 bv，它会启动交互式 TUI 并阻塞终端。始终使用 --robot-* 标志（--robot-triage、--robot-next、--robot-plan、--robot-insights、--robot-priority、--robot-alerts）。

计划转 Beads 工作流：

  1. 阅读完整计划、AGENTS.md、README、关联的意图议题与验收标准。
  2. 用 br create 为每个议题创建 bead，描述中包含完整上下文。
  3. 对每个功能、缺陷或面向产品的行为，包含围栏 gherkin 块或链接到已填写的意图议题；仅当验收标准完全基于命令/文件时，机械性杂务才可省略 Gherkin。
  4. 对实质性 bead，包含来自 docs/architecture/intent-to-loop-hexagon.md 的 hexagon: boundary 块：入站端口、限界上下文、适配器、上下文包与完成状态。
  5. 用 br dep add / bd dep add 连接依赖，不要手工编辑 JSONL 或数据库文件。
  6. 迭代打磨（通常 6-9 轮）至稳态，检查丢失功能、过度简化、缺失测试、边界不清、缺少端到端覆盖与日志薄弱。
  7. 验证：br dep 循环必须为空；运行 bv --robot-insights 检查图健康；用 bv --robot-next 找第一个 bead。绝不运行裸 bv。
  8. 提交前显式同步：br sync --flush-only，然后 git add .beads/ 并在适当时提交追踪器变更。

就绪的 bead 应足够详细，使新智能体无需查阅原始计划即可实现：范围清晰、依赖明确、有 BDD 或机械验收、有单元/端到端测试预期、有详细日志预期、有明确的完成状态、无依赖循环。

适用场景

  • 需要跨多个会话持续推进、且对话可能被压缩的复杂任务。
  • 需要依赖管理与优先级分诊的议题追踪。
  • 将 Markdown 计划落地为可执行、依赖完整的任务图。
  • 与 /validate、/implement 等命令配合，自动读取议题元数据并管理议题生命周期。

限制

  • 前置条件：bd CLI 版本 0.34.0+ 且位于 PATH；当前目录必须是 git 仓库；需先由人工运行一次 bd init。
  • 绝不要运行裸 bv，必须使用 --robot-* 标志。
  • br 不会自动提交，同步方向需显式指定（--flush-only 与 --import-only）。
  • 不要手工编辑 JSONL 或数据库文件。
  • 常见问题（命令未找到、非 git 仓库、缺少 init、ID 前缀错误、bv 挂起、依赖循环、同步方向混淆）见 TROUBLESHOOTING.md；bv 挂起通常意味着遗漏了 robot 标志，br sync 混淆通常意味着未指定方向。

参考文档

references/beads.feature（可执行规范）、ANTI_PATTERNS.md、BOUNDARIES.md、composition-over-invention.md、BR_REFERENCE.md、BV_TRIAGE.md、CLI_REFERENCE.md、DEPENDENCIES.md、INTEGRATION_PATTERNS.md、ISSUE_CREATION.md、MIGRATION.md、MOLECULES.md、PATTERNS.md、PLAN_TO_BEADS.md、RESUMABILITY.md、ROUTING.md、STATIC_DATA.md、tracker-migration-and-triage.md、TROUBLESHOOTING.md、WORKFLOWS.md。