企业官网建设流程全解析

Beads Graph Links 完全指南：用 replies-to / relates-to / duplicates / supersedes 构建 Issue 知识图谱

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

Beads（命令行bd）在传统阻塞依赖（blocks）之外，提供了一整套非阻塞的 Issue 链接机制：replies-to用于对话线程、relates-to用于松散的双向关联、duplicates用于去重、supersedes用于版本链。这些链接把离散的 Issue 编织成可查询、可遍历的知识图谱，是 Agent 与 Agent、Agent 与人类协作时记忆与上下文的核心载体。读完本文，你将掌握四种链接类型的语义与全部 CLI 用法，理解它们如何在底层以类型化依赖边（dependency edge）存储，并能独立搭建知识库、Bug 去重、文档版本管理等实战方案。

什么是 Graph Links

Beads 把"一张票"（Issue）作为跟踪工作项的基本单元，但真正让 Issue 形成体系的是它们之间的关系。Graph Links 就是这些关系的统称：与blocks这类会阻塞工作流转的硬依赖不同，Graph Links 是非阻塞的——它们不改变 Issue 的就绪状态，只提供语义化的关联、去重、版本与对话信息。

从当前仓库源码看，这些关系统一收敛到了依赖边（dependency edge）模型。internal/types/types.go 中的Issue结构体明确注释：

NOTE: RepliesTo, RelatesTo, DuplicateOf, SupersededBy moved to dependencies table per Decision 004 (Edge Schema Consolidation). Use dependency API instead.

也就是说，本文讨论的四种链接，在底层都以(issue_id, depends_on_id, type)形式的三元组边存储，type字段区分链接语义。DependencyType常量定义了完整的内置类型集合（internal/types/types.go 中约 L1208-L1260 处）：

DepRepliesTo DependencyType = "replies-to" // Conversation threading DepRelatesTo DependencyType = "relates-to" // Loose knowledge graph edges DepDuplicates DependencyType = "duplicates" // Deduplication link DepSupersedes DependencyType = "supersedes" // Version chain link

这种"统一边表"的设计让查询、导出、跨仓库同步、审计都走同一条依赖 API，这也是理解下面所有命令的关键前提。

四种链接类型详解

replies-to：对话线程

replies-to把多条消息串联成类似邮件或聊天的会话线程，是 Beads 中 Agent 之间异步通信的骨干机制。

创建途径：

• 编排器（orchestrator）的 mail 回复命令（消息由编排器负责收发）；
• 手动链接：bd dep add <new-id> <original-id> --type replies-to。

典型场景：

• Agent 与 Agent 的消息线程；
• Issue 上的讨论链；
• 后续跟进沟通。

示例（编排器 mail 场景）：

# 原始消息（经编排器 mail 发送） # orchestrator mail send worker/ -s "Review needed" -m "Please review issue-xyz" # 创建: msg-a1b2 # 回复（自动设置 replies-to） # orchestrator mail reply msg-a1b2 -m "Done! Approved with minor comments." # 创建: msg-c3d4，其 replies-to 指向 msg-a1b2

查看线程：

bd show gt-a1b2 --thread

--thread标志会沿着replies-to链回溯，渲染完整对话历史。该行为在仓库测试中有直接验证，例如 cmd/bd/cli_coverage_show_test.go 中通过bd show <id> --thread断言输出包含消息 ID 链。

relates-to：松散的双向关联

relates-to是"参见"（see also）语义：两个 Issue 相关，但既不阻塞、也不构成层级。它是构建知识图谱最常用的边。

创建与移除：

# 双向关联两个 Issue bd dep relate bd-auth bd-security # 结果: bd-auth.relates-to 包含 bd-security # bd-security.relates-to 包含 bd-auth # 查看关联 bd show bd-auth # 显示: Related: bd-security # 移除链接（双向删除） bd dep unrelate bd-auth bd-security

双向性的源码实现：cmd/bd/relate.go 中的runRelate会先后写入两条边——id1 → id2与id2 → id1，类型均为types.DepRelatesTo；runUnrelate则对称地删除两条边。同时源码还有两条值得注意的约束：

• 禁止自关联：cannot relate an issue to itself；
• 部分 ID 解析：命令会先用utils.ResolvePartialID把用户输入的缩写前缀解析为完整 ID，所以bd dep relate bd-auth bd-sec（若前缀唯一）同样可用；
• 显式写操作记录历史：relate/unrelate通过AddDependencyWithOptions(..., EmitEvent: true)写入审计事件，只有结构性的边装配才保持静默。

多点关联：一个 Issue 可以同时关联任意多个对象：

bd dep relate bd-api bd-auth bd dep relate bd-api bd-docs bd dep relate bd-api bd-tests # bd-api 现在关联 3 个 Issue

典型场景：交叉引用相关功能、把 Bug 链接到关联任务、构建知识图谱、"参见"式连接。

duplicates：去重与合并

duplicates把一条 Issue 标记为另一条"权威 Issue"（canonical）的重复项。标记后，重复的 Issue 会被自动关闭，权威 Issue 保持打开。

创建方式：

# 存在两条相似 Bug 报告 bd show bd-bug1 # "Login fails on Safari" bd show bd-bug2 # "Safari login broken" # 把 bug2 标记为 bug1 的重复 bd duplicate bd-bug2 --of bd-bug1 # 结果: bd-bug2 以 duplicate_of: bd-bug1 的关系被关闭 # 查看关系 bd show bd-bug2 # Status: closed # Duplicate of: bd-bug1

行为特征：

• 重复 Issue 自动关闭；
• 权威（canonical）Issue 保持打开；
• 存储为类型化依赖边duplicates（duplicate → canonical）。

源码实现：cmd/bd/duplicate.go 的runDuplicate分两步完成：先写入DepDuplicates依赖边，再调用store.CloseIssue走完整的生命周期关闭流程。命令还做了防御性检查——不能把 Issue 标记为自身的重复项，且会先校验 canonical Issue 必须存在。--of是必填参数，支持部分 ID 解析。

supersedes：版本链

supersedes标记旧 Issue 已被新版本取代，旧 Issue 自动关闭，新 Issue 保持原状。适合设计文档、Spec、RFC 等会持续演化的工件。

创建方式：

# 原始设计文档 bd create --title "Design Doc v1" --type task # 创建: bd-doc1 # 后续创建新版本 bd create --title "Design Doc v2" --type task # 创建: bd-doc2 # 标记 v1 被取代 bd supersede bd-doc1 --with bd-doc2 # 结果: bd-doc1 以 superseded_by: bd-doc2 被关闭 # 查看版本链 bd show bd-doc1 # Status: closed # Superseded by: bd-doc2

行为特征：

• 旧 Issue 自动关闭；
• 新 Issue 保持当前状态；
• 存储为类型化依赖边supersedes（old → new）。

bd supersede与bd duplicate在 cmd/bd/duplicate.go 中成对定义（同一文件、同一文件组deps），--with为必填参数。需要留意的是边的方向约定：bd supersede old --with new存储(old, new, supersedes)，读作"old 被 new 取代"；而bd duplicate dup --of canonical存储(dup, canonical, duplicates)，读法相反。正如 cmd/bd/dep_relation.go 源码注释所警告的——"方向来自写入它的命令，而不是从左到右读类型名"，理解这一点能避免在展示输出中把关系读反。

展示层的语义映射

每种链接在bd show/bd dep list的渲染中都有专门的分组与箭头符号，定义在 cmd/bd/dep_relation.go 的depRelations映射表中：

由于relates-to与早期related语义相同（双向、对称），渲染层会把两者合并进同一个 RELATED 分区，避免同一组关系被拆成两半。自定义依赖类型则会回退到"用类型名自身作为标题"的通用渲染。

查询与展示

查看 Issue 详情

bd show <id>

一条 Issue 的所有链接类型都会按分区列出：

bd-auth: Implement authentication Status: open Priority: P1 Related to (3): bd-security: Security audit bd-users: User management bd-sessions: Session handling

查看线程

bd show <id> --thread

沿replies-to链展示完整会话历史。

JSON 输出

bd show <id> --json

输出包含全部字段与图链接信息。原文档以如下结构描述这些语义字段：

{ "id": "bd-auth", "title": "Implement authentication", "relates-to": ["bd-security", "bd-users", "bd-sessions"], "duplicate_of": "", "superseded_by": "" }

需要说明的是，在当前仓库实现中，relates-to、duplicate_of、superseded_by、replies-to已按 Decision 004 迁移到依赖边存储，Issue结构体通过Dependencies []*Dependency字段（json:"dependencies,omitempty"）随导出/导入与 JSON 输出携带这些边（见 internal/types/types.go）。因此实际输出中以类型化dependencies数组形式呈现这些关系，语义与上述字段一一对应。

用 bd dep list 过滤链接

docs/cli-reference/dep.md 说明bd dep list支持按类型过滤并指定方向：

# 列出某 Issue 的关联 bd dep list bd-auth --type relates-to # 列出依赖（默认 down）或依赖者（up） bd dep list bd-auth --direction up

bd dep add的--type标志接受blocks|tracks|related|parent-child|discovered-from|until|caused-by|validates|relates-to|supersedes（默认blocks），默认不带--type的dep add创建的是阻塞依赖。

与阻塞依赖的对比

核心区别：blocks影响就绪度计算与工作流转（被阻塞的 Issue 不会出现在bd ready等就绪视图），而 Graph Links 四兄弟只承载语义信息，不干预调度。这使得你可以放心地用它们编织知识网络，而不必担心意外阻塞 Agent 的工作流。

实战用例

知识库

把相关文档型 Issue 织成网状知识库：

bd dep relate bd-api-ref bd-quickstart bd dep relate bd-api-ref bd-examples bd dep relate bd-quickstart bd-install

Bug 去重（含自动合并）

面对大量相似 Bug 报告，先发现、后合并：

# 查找潜在重复项 bd duplicates # 合并重复项 bd duplicate bd-bug42 --of bd-bug17 bd duplicate bd-bug58 --of bd-bug17

bd duplicates本身是一个功能完备的去重工具（实现见 cmd/bd/duplicates.go）：它按(title, description, design, acceptance_criteria, status)的内容键分组，把完全相同的 Issue 聚合为重复组，并给出建议的合并动作。其合并目标选择算法值得注意：

1. 结构权重优先：dependentCount*3 + dependsOnCount。子 Issue（dependents）权重是普通依赖的 3 倍，因为"丢弃一个有子任务的 Issue 会让子任务成为孤儿（灾难性）"，而丢失一条 depends-on 链接是可恢复的；
2. 文本引用数：其他 Issue 正文中提及该 ID 的次数；
3. 字典序最小 ID：作为稳定决胜项。

还支持自动化：

# 预览将发生的合并 bd duplicates --dry-run # 直接执行全部建议合并 bd duplicates --auto-merge

--auto-merge的执行逻辑（performMerge）会依次完成三件事：把源 Issue 的子任务重新挂到目标 Issue 下（防止孤儿化）、以 "Duplicate of " 为原因关闭所有源 Issue、为每个源 Issue 建立指向目标的related依赖边。

版本历史

跟踪文档与 RFC 的演化链：

bd supersede bd-rfc1 --with bd-rfc2 bd supersede bd-rfc2 --with bd-rfc3 # bd-rfc3 现在是当前版本

消息线程

通过编排器 mail 构建多轮对话链：

# orchestrator mail send dev/ -s "Question" -m "How does X work?" # orchestrator mail reply msg-q1 -m "X works by..." # orchestrator mail reply msg-q1.reply -m "Thanks!"

每条回复都自动带上前一条的replies-to指针，bd show --thread即可回放整条链路。

最佳实践

1. 节制使用 relates-to——关联过多会变成噪声，稀释真正有价值的关系；
2. 优先使用具体类型——语义明确的duplicates/supersedes比泛化的relates-to更有信息量，也更容易被查询与自动处理；
3. 保持线程浅层——过深的回复链难以追踪，必要时开新话题；
4. 为 supersedes 链记录原因——版本变更时注明变更动机（可在关闭原因或正文中体现），便于后人回溯；
5. 创建重复前先查询——先用bd search/bd duplicates确认不存在同内容 Issue，避免重复制造重复。

延伸阅读

• engdocs/messaging.md：Mail 命令与线程机制的完整说明（编排器消息收发的核心设计文档）；
• docs/getting-started/quickstart.md：阻塞依赖（blocks/parent）的快速上手；
• docs/cli-reference/index.md：全部bd命令的 CLI 参考；
• docs/cli-reference/dep.md 与 docs/cli-reference/duplicate.md：依赖管理相关命令的自动生成文档；
• 想深入边模型的读者可直接阅读 cmd/bd/relate.go、cmd/bd/duplicate.go、cmd/bd/duplicates.go 与 internal/types/types.go，对照源码理解双向边写入、自动关闭与合并算法的实现细节。

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