Beads `bd duplicate` 命令实战指南：将问题标记为重复、自动关闭并关联规范问题

Beadsbd duplicate命令实战指南将问题标记为重复、自动关闭并关联规范问题【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本篇指南围绕 Beads 开源仓库中的bd duplicate命令文档见 docs/cli-reference/duplicate.md实现见 cmd/bd/duplicate.go展开讲解如何将一条问题Issue标记为另一条规范问题canonical的重复项被标记的问题会自动关闭并建立指向规范问题的duplicates依赖边。读完本文你将掌握bd duplicate的完整用法、参数语义、底层执行链路以及它与bd supersede、bd duplicates、bd find-duplicates等去重/演进命令的配合方式可直接用于大型问题库的日常整理。一、为什么需要重复标记问题库去重的最小闭环在大型 issue 数据库中不同用户反复提交相似问题bug 报告、功能请求是常态。如果放任不管会导致同一个缺陷被分配到多个问题修一个漏一个统计口径混乱无法判断某类问题到底有多少真实存量后续检索与 Agent 分析时被重复内容干扰。bd duplicate提供的正是去重的最小闭环保留一条权威的规范问题把其余重复问题标记为 duplicate 并自动关闭同时保留从重复项指向规范项的依赖边使得历史引用、依赖关系与审计信息都不会丢失。官方帮助文本对此的描述是 This is essential for large issue databases with many similar reports。二、命令用法与参数速查命令基本形式来自 docs/cli-reference/duplicate.mdbd duplicate id --of canonical [flags]官方示例bd duplicate bd-abc --of bd-xyz # Mark bd-abc as duplicate of bd-xyz唯一参数说明参数类型是否必填含义--ofstring是规范问题canonical的 ID即保留作为权威的那条问题id位置参数即被标记为重复的问题 ID。命令同时支持--json输出继承全局 flag方便脚本与 Agent 消费结构化结果。三、执行流程拆解从 ID 解析到自动关闭bd duplicate的完整行为定义在 cmd/bd/duplicate.go 的runDuplicate函数中按顺序经历以下环节模式与只读检查命令在 proxied-server 模式下不被支持返回 duplicate is not supported in proxied-server mode并调用CheckReadonly(duplicate)拒绝在只读存储上执行写操作。命令遥测创建metrics.NewCommandEvent(duplicate)事件命令结束时写入全局 metrics便于追踪使用情况。ID 解析对位置参数id与--of的值分别调用utils.ResolvePartialID将可能的部分 ID 解析为完整 ID。自引用校验若解析后duplicateID canonicalID直接报错cannot mark an issue as duplicate of itself。规范问题存在性校验通过store.GetIssue确认 canonical 存在否则报错canonical issue not found。建立依赖边构造types.Dependency{IssueID: duplicateID, DependsOnID: canonicalID, Type: types.DepDuplicates}并调用store.AddDependency写入存储。生命周期关闭调用store.CloseIssue(ctx, duplicateID, , actor, )关闭重复问题——注意它走的是完整生命周期操作因此会记录完整的关闭状态closed_at等字段。输出标记commandDidWrite按 JSON / 文本两种格式输出结果。文本输出形如✓ Marked bd-abc as duplicate of bd-xyz (closed)JSON 输出结构为{ duplicate: bd-abc, canonical: bd-xyz, status: closed }这为自动化脚本提供了干净的机器可读接口duplicate、canonical、status三个字段。四、深入理解--of的值部分 ID 解析规则--of和位置参数都支持部分 ID解析逻辑位于 internal/utils/id_parser.go 的ResolvePartialID。它接受四种输入形态完整 IDbd-a3f8e9或a3f8e9→bd-a3f8e9无连字符前缀bda3f8e9→bd-a3f8e9部分 IDa3f8→bd-a3f8e9要求唯一匹配层级 IDa3f8e9.1→bd-a3f8e9.1解析时优先走SearchIssues精确匹配快路径与bd list --id使用同一查询路径保证一致性随后按配置的issue_prefix默认bd拼装并支持allowed_prefixes配置做跨前缀查找。解析失败找不到或前缀歧义会返回错误并被runDuplicate包装为failed to resolve ...返回。这意味着你可以在命令行中只敲 ID 前缀如bd duplicate a3f8 --of xyz12只要前缀唯一即可命中。五、duplicates依赖边的语义一种非阻塞的知识图谱关系标记重复在底层写入的是DepDuplicates类型的依赖边类型定义于 internal/types/types.goDepDuplicates DependencyType duplicates // Deduplication link DepSupersedes DependencyType supersedes // Version chain link这两个类型有以下重要语义见 internal/types/types.goIsWellKnown()返回 true属于内置依赖类型可以被bd dep等工具识别AffectsReadyWork()返回 false不会影响就绪工作ready work的计算——这与blocks、parent-child、waits-for等调度边不同。也就是说把问题标记为重复不会阻断工作流它是一条纯粹的信息/归档边用于记录这条问题其实是那条问题的重复而不是这条问题被那条阻塞。从源码结构看这种设计让去重边与调度边在语义上彻底解耦关闭重复问题不会产生级联的阻塞连锁反应保证了去重操作对工作流的侵入性最小。六、兄弟命令bd supersede处理版本演进场景与bd duplicate定义在同一文件 cmd/bd/duplicate.go 的supersedeCmd提供了对称能力——用于设计文档、规格书、不断演进的工件bd supersede id --with new [flags] bd supersede bd-old --with bd-new # Mark bd-old as superseded by bd-new其流程与duplicate完全同构runSupersedecmd/bd/duplicate.go解析oldID与newID同样支持部分 ID拒绝被自身取代cannot mark an issue as superseded by itself校验 replacement 存在写入DepSupersedes依赖边old → new通过生命周期操作关闭被取代的旧问题输出✓ Marked bd-old as superseded by bd-new (closed)JSON 输出字段为superseded/replacement/status。两者的使用场景差异可概括为duplicate面向相同内容的重复报告bug 库整理supersede面向同一工件的新版本取代旧版本文档与规格演进。七、配合命令从精确查重到语义找重bd duplicate是事后人工/半自动去重的手动落点而 Beads 还提供了两个自动发现重复问题的配套命令共同构成完整去重工作流7.1bd duplicates按内容哈希精确查重命令文档见 docs/cli-reference/duplicates.md实现见 cmd/bd/duplicates.go。它按title description design acceptanceCriteria status组成的contentKey分组cmd/bd/duplicates.go只对状态一致open 归 open、closed 归 closed的问题分组。bd duplicates # Show all duplicate groups bd duplicates --auto-merge # Automatically merge all duplicates bd duplicates --dry-run # Show what would be merged--auto-merge触发performMergecmd/bd/duplicates.go其合并策略值得注意先把源问题的子问题 re-parent 到目标问题防止孤儿化见GetDependentsWithMetadata 父-子边重建关闭所有源问题关闭原因为Duplicate of target给每个源问题添加指向目标的related依赖边合并目标选择按chooseMergeTarget的三级优先级结构权重dependents*3 dependencies子问题权重 ×3因为丢弃有子问题的问题会造成灾难性孤儿→文本引用次数其他问题描述/备注中提及该 ID 的次数→字典序最小 ID兜底cmd/bd/duplicates.go。--dry-run只展示将执行的bd close ... bd dep add ... --type related建议命令而不落库。7.2bd find-duplicates语义相似查找命令文档见 docs/cli-reference/find-duplicates.md。它解决措辞不同但主题相同的问题默认mechanical方法用 token 化的 Jaccard 相似度免费、无需 API key--method ai则先用机械方法预筛再交由 Claude 做语义判断减少 API 调用量。相关 flag 包括--threshold默认 0.5调低出更多结果、--status默认非 closed、--limit默认 50 对等。三者关系可以概括为bd find-duplicates负责发现疑似重复bd duplicates负责发现完全重复并批量合并bd duplicate负责逐条手动确认并归档为重复同时bd supersede处理版本演进型取代。八、错误场景与使用注意事项依据源码 cmd/bd/duplicate.go 与测试 cmd/bd/duplicate_embedded_test.go 中bdDuplicateFail验证的用例以下场景会直接失败并返回明确错误场景错误信息待标记问题与规范问题是同一条cannot mark an issue as duplicate of itself规范问题不存在如du-nonexistent999canonical issue not found: id位置参数缺省或多余cobraExactArgs(1)校验失败省略--offlag 已被MarkFlagRequired(of)标记为必填直接报错proxied-server 模式duplicate is not supported in proxied-server mode只读存储CheckReadonly(duplicate)拒绝写操作部分 ID 前缀歧义/未找到failed to resolve id: ...此外duplicateCmd注册了ValidArgsFunction issueIDCompletioncmd/bd/duplicate.go意味着 shell 补全会按现有 issue ID 自动提示位置参数减少手输错误。九、测试验证行为如何被保障嵌入式集成测试 cmd/bd/duplicate_embedded_test.go 通过go:build cgo构建真实嵌入式 Dolt 环境覆盖了六类行为mark_duplicate执行后输出包含 duplicateduplicate_is_closed标记后GetIssue读到status closed且closed_at非空——印证了通过生命周期操作关闭、记录完整关闭状态的实现creates_dep_link通过bd dep list dupe能看到 canonical 出现在依赖列表中——印证duplicates依赖边真实落库json_output解析--json输出断言duplicate与canonical字段正确error_same_id/error_nonexistent_canonical验证两个核心错误分支。并发测试TestEmbeddedDuplicateConcurrent则用 8 个 worker 同时把 8 条问题标记为同一 canonical 的重复项只允许 one writer at a time 类型的锁冲突错误出现验证了写路径的并发安全。十、小结把bd duplicate纳入日常问题库运维bd duplicate是 Beads 依赖图谱体系中负责去重归档的写操作命令一次调用完成 ID 解析、依赖边写入与生命周期关闭天然与bd dep依赖查看、bd graph图谱可视化、bd close关闭语义等命令协同。在大型 issue 库中推荐的工作流是先用bd find-duplicates/bd duplicates --dry-run侦查再用bd duplicate --of canonical逐条确认归档或用bd duplicates --auto-merge批量合并子问题会自动 re-parent。配合--json输出Agent 与脚本也能无缝接入该去重流程。进一步阅读命令实现 cmd/bd/duplicate.go依赖类型定义 internal/types/types.go部分 ID 解析 internal/utils/id_parser.go批量查重 cmd/bd/duplicates.go语义查重 docs/cli-reference/find-duplicates.md集成测试 cmd/bd/duplicate_embedded_test.go【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考