企业官网建设流程全解析

Beads 的哈希 ID 约定与相邻项目生态：任务图与知识回忆层的互补设计

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

Beads 是一个为 AI 编码代理设计的、基于 Dolt 的分布式图式问题追踪器，其核心卖点之一是“零冲突”的哈希型 ID（如bd-a1b2）。本文以仓库中 docs/related-projects.md 为骨架，梳理 Beads 与相邻独立项目（以 scry 为代表的 Recall / knowledge graph 工具）的定位差异，并从源码层面剖析双方不约而同采用哈希 ID 约定的原因与底层实现，帮助你理解在多代理、多分支协作下 ID 设计的关键决策，以及如何在自己的工作流中运用这套约定。

Beads 在相邻项目生态中的定位：任务图，而非回忆层

仓库的 docs/related-projects.md 明确区分了两类外部项目：

• 相邻或互补工具（adjacent / complementary tools）：解决与 Beads 同一“街区”内不同问题的独立项目，用户往往同时使用两者。这类项目被收录在related-projects.md。
• Beads 集成（integrations）：直接与bdCLI 打通、读取 Beads 数据的工具，例如各类终端 UI、Web UI、编辑器插件、SDK 等，被收录在 docs/community-tools.md。

文档以 scry 为例阐述了这种互补关系。scry 是一个为 AI 编码代理设计的marker-indexed（标记索引）知识与回忆图：文件通过行内@scry.entry标记声明身份，索引系统让设计、经验教训与决策可以按“含义、标签、种子问题”被检索到，而不是按文件路径查找。它与 Beads 的分工完全不同：

• Beads 是一个task graph（任务图），回答的是“接下来该做什么（what to do next）”；
• scry 是一个recall layer（回忆层），回答的是“当时决定了什么、为什么（what was decided and why）”。

两者天然可组合：Beads 负责推进工作、管理依赖与就绪边界，scry 负责在工作间隙沉淀和召回决策上下文。这种“任务推进”与“知识回忆”的分离，正是 Beads 所提倡的持久结构化记忆架构的一部分——正如 docs/core-concepts/index.md 所说，Beads 用持久的工作图替代会腐烂的 Markdown 计划，让“工作熬过代理的会话结束”。

独立的哈希 ID 约定：殊途同归的bd-a1b2与~hash

related-projects.md中特别指出一个耐人寻味的事实：Beads 与 scry 是两个独立发展的项目，却出于相同的原因，各自得出了基于哈希的 ID 约定（Beads 的bd-a1b2与 scry 的~hash风格 ID），而这个原因就是：防止多代理、多分支协作中的 ID 碰撞。

传统顺序 ID（#1、#2、#3）在多代理场景下必然失效：

• 多个代理同时创建问题时，编号互相冲突；
• 不同分支各自独立编号，合并时产生两个“#7”；
• 仓库 fork 分叉后再合并，编号体系无法收敛。

哈希 ID 则完全不同：ID 由内容推导而来，创建者之间无需任何协调即可保证全局唯一，分支合并时两边创建的 ID 都能存活，不存在重编号问题。docs/core-concepts/hash-ids.md 用一张 mermaid 图直观对比了这两种路径——顺序 ID 合并时出现“两个 #7 ✗”，而哈希 ID 合并时“两个 ID 都存活 ✓”。README.md 中也将“Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows”列为 Beads 的核心特性之一。

源码级剖析：bd-a1b2是如何生成的

哈希 ID 并非随机的 UUID，而是对问题内容做 SHA-256 摘要后取前缀编码而来。核心实现在 internal/idgen/hash.go：

• 输入组合（GenerateHashID，见 hash.go#L55-L85）：将title（标题）、description（描述）、creator（创建者）、timestamp（纳秒级创建时间）和一个nonce（碰撞随机盐）拼成一个稳定的内容串，再做sha256.Sum256。文档 hash-ids.md 中概括为“标题 + 创建时间戳 + 随机盐”，源码里进一步加入了描述与创建者，并用 nonce 显式处理哈希碰撞。
• Base36 编码（EncodeBase36，见 hash.go#L16-L50）：把哈希字节串转换为 base36 字符集（0-9a-z），比十六进制信息密度更高，前缀不足时补零、超长时截断保留低位。注释明确说明这与 “bd hash IDs” 所用算法一致。
• 长度映射：根据期望输出长度（3~8 位）选择参与哈希的字节数（2~5 字节），其他值回退到 3 字符宽度。测试 internal/idgen/hash_test.go 中的TestGenerateHashIDMatchesJiraVector给出了同一输入在不同长度下的确定性输出向量（如 4 位 →bd-8d8e、6 位 →bd-8bi3tk），证明生成过程是可复现、可验证的。

因此，两个代理同时执行bd create "Fix authentication bug"得到的是不同 ID——时间戳与随机盐保证了差异性；即使极端情况下内容完全碰撞，GenerateHashID也通过nonce参数与bd info --schema --json中的碰撞检测（详见 hash-ids.md 的 Collision Handling 小节）进行消歧，保证两条问题都被保留。

把哈希 ID 约定用到自己的项目中

哈希 ID 的价值只有在正确的使用方式下才能完全兑现，docs/core-concepts/hash-ids.md 给出了一套可直接落地的最佳实践：

1. 使用短引用：bd-a1b2这类 4 位哈希在绝大多数情况下已经足够唯一，不必等待完整 ID；
2. 脚本一律用--json：程序化访问时通过bd list --json、bd show <id> --json解析完整 ID，避免依赖显示格式；
3. 在提交信息中引用哈希：如Fixed bd-a1b2，让 git 历史与工作图互相锚定；
4. 让层级自然形成：先创建 epic，再按需追加子任务，层级 ID（如bd-a3f8e9.1）的父哈希天然唯一，不会发生命名空间碰撞，且最多支持 3 层嵌套。

此外，ID 的前缀与长度均可配置，以适应不同团队或仓库的命名风格：

# 设置前缀（默认 bd） bd config set id.prefix myproject # 设置哈希长度（默认 4） bd config set id.hash_length 6 # 新创建的问题即采用新格式 bd create "Test" # 返回: myproject-a1b2c3

在典型的多代理会话中，这套约定配合bd ready（只列出无未关闭阻塞项的就绪工作）、bd update <id> --claim（原子认领）与bd close <id>（完成并释放阻塞），可以让多个代理在各自的分支上并行推进，而合并时 ID 永不冲突——这正是 README.md 中“创建 → 依赖图 → 就绪 → 认领 → 关闭”主循环得以成立的基础。

与集成工具生态的边界

需要再次强调related-projects.md划定的边界：scry 这类相邻项目不是 Beads 的集成，二者面向不同问题；而 docs/community-tools.md 收录的才是真正与bdCLI 打通的生态工具（终端 UI、Web UI、编辑器插件、SDK、协调服务器等），并且该文档明确提示：这些工具应当通过bd list --json等 CLI 访问数据，直接读取旧版.beads/issues.jsonl格式的工具与当前版本不兼容。

小结

Beads 与 scry 的案例说明了一个有趣的工程设计共识：当多个独立参与者（无论是代理还是分支）需要并发地创造全局标识符时，基于内容的哈希 ID 比任何中心化发号器都更简单、更健壮——它把“协调”从运行时移到了算法里。对 Beads 用户而言，理解bd-a1b2背后的 SHA-256 + base36 实现，以及“任务图负责推进、回忆层负责沉淀”的生态分工，将有助于你在自己的多代理工作流中正确使用 Beads，并为知识沉淀工具预留出自然的协作位置。

进一步阅读：Hash-based IDs（ID 配置与碰撞处理全览）、How Beads Works（就绪计算与同步模型）、Community Tools（与bd打通的集成生态）、internal/idgen/hash.go（ID 生成源码）。

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads