Beads 语义查重实战bd find-duplicates命令的机械相似度与 AI 判定机制解析【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd find-duplicates是 Beads 提供的语义查重命令用于从既有 issue 中找出措辞不同、但描述同一主题的潜在重复项与只做精确内容匹配的bd duplicates形成互补。本文将基于仓库文档与源码docs/cli-reference/find-duplicates.md、cmd/bd/find_duplicates.go完整讲解命令用法、两种检测方法的底层算法、AI 调用链与降级策略以及结果输出格式帮助你直接用它维护一个无重复的 issue 库。命令定位语义查重与精确查重的分工在 Beads 中查重能力由两条命令共同承担bd duplicates按内容哈希对 issue 分组只匹配内容完全相同的 issue标题、描述、设计、验收标准全部参与哈希并会建议合并目标先按被引用数最多、再按 ID 字典序最小详见 docs/cli-reference/duplicates.md。bd find-duplicates面向语义相似但文本不同的场景例如同一 bug 被人用不同措辞报了两次两条 issue 的标题和描述没有一行相同的字符却指向同一个问题。从源码看命令注册在cmd/bd/find_duplicates.go中别名find-dups属于views命令组find_duplicates.go。bd duplicates解决完全一样的问题bd find-duplicates解决其实是一回事的问题两者配合使用才能覆盖真实的重复上报场景。安装与前置条件Beads 提供机械mechanical与 AIai两种检测方法mechanical默认基于 token 的文本相似度计算不需要任何 API Key离线即可运行ai基于 LLM 的语义比较需要配置 Anthropic 兼容的 API KeyANTHROPIC_API_KEY、MINIMAX_API_KEY或配置文件中的ai.api_key。AI 模式并不要求额外安装 SDK——Beads 已内置对 Anthropic 兼容接口的调用能力源码直接使用github.com/anthropics/anthropic-sdk-go见 find_duplicates.go你只需提供凭据。API Key 与模型的解析优先级AI 模式的 Key 解析实现在 internal/config/config.go优先级固定为环境变量ANTHROPIC_API_KEY环境变量MINIMAX_API_KEY配置文件中的ai.api_key--model未显式指定时默认模型按 DefaultAIModelFor 决定只要ai.model被显式配置就优先使用否则若 Key 来自 MiniMax 环境变量则使用MINIMAX_MODEL环境变量或内置默认模型MiniMax-M2因为 MiniMax 的 Anthropic 兼容端点并不提供 Claude 默认模型其余情况回落为ai.model的配置值。当 Key 来自MINIMAX_API_KEY时请求 Base URL 的解析DefaultAIBaseURL顺序为ai.base_url或BD_AI_BASE_URL→MINIMAX_BASE_URL→ MiniMax 默认端点https://api.minimax.io/anthropic其余来源则直接使用 Anthropic SDK 默认端点。快速上手五个典型用法官方文档给出的使用示例find-duplicates.mdbd find-duplicates # 机械相似度默认 bd find-duplicates --threshold 0.4 # 降低阈值 更多结果 bd find-duplicates --method ai # 使用 AI 语义比较 bd find-duplicates --status open # 只检查 open 状态的 issue bd find-duplicates --limit 20 # 只显示前 20 对结果 bd find-duplicates --json # JSON 输出基本语法为bd find-duplicates [flags]命令别名是find-dups。最简单的情况下直接在仓库目录执行bd find-duplicates即可得到默认阈值下的潜在重复对列表零配置、零成本。关于状态筛选的默认行为一个容易忽略的细节--status不指定时命令默认只分析非 closed 状态的 issue。这一逻辑在 filterClosedIfNoStatus 中实现——状态过滤在拉取数据之后进行凡是StatusClosed的 issue 都会被剔除。若显式传入--status open、--status in-progress等值则按传入值过滤传入--status all表示不做状态过滤。Beads 支持的 issue 状态定义见 internal/types/types.goopen、in-progress、blocked、deferred、closed、pinned、hooked 等。完整 Flags 参考表以下是命令支持的全部参数来自 find-duplicates.md 与 init() 注册代码Flag缩写类型默认值说明--limit-nint50最多显示的结果对数--method无stringmechanical检测方法mechanical或ai--model无string来自配置ai.modelAI 使用的模型仅在--method ai时生效--status-sstring非 closed按状态过滤all表示不过滤--threshold无float0.5相似度阈值0.0–1.0越低结果越多--max-rows无int0禁用行数硬上限超限以退出码 2 报错见下文--json无boolfalse以 JSON 输出结果全局 flag阈值参数的直观理解--threshold取值范围为 0.0–1.0默认 0.5。阈值越低被判定为重复的对越多即召回更高、误报更多阈值越高结果越保守精确率更高、可能漏掉措辞差异大的重复。控制台文本输出会以百分比形式展示实际使用的阈值例如Found 3 potential duplicate pair(s) (threshold: 50%)。防御性行数上限--max-rows / BEADS_MAX_ROWSfind-duplicates还注册了防御性行数上限 flag代码注释标记为 be-x42v见 find_duplicates.go实现在 cmd/bd/max_rows.go通过--max-rows N或环境变量BEADS_MAX_ROWSN设置硬上限0 表示禁用默认当存储层返回的行数超过上限时命令打印明确错误并以退出码 2 退出适合 CI/Agent 场景防止病态查询优先级--max-rows显式指定 BEADS_MAX_ROWS环境变量 禁用--max-rows 0可显式覆盖环境变量注意在--proxied-server模式下显式设置非零上限会直接报错拒绝执行该模式下上限无法被强制执行拒绝比静默忽略更安全method参数非法非mechanical/ai时同样返回错误并影响退出码。方法一机械相似度mechanical的算法拆解机械方法是默认检测方式其核心思想在文档中已有概述find-duplicates.md将 issue 的标题与描述做 token 化然后对所有 issue 两两计算 Jaccard 相似度。源码实现比概述更进一步实际综合了两种相似度指标。整条流水线如下1. 文本组装issueText将被比较的文本定义为标题 空格 描述若描述为空则仅使用标题见 issueText。2. Token 化tokenizetokenize 的规则全文转小写以非字母、非数字、非连字符的字符作为分隔符切分单词连字符词如auto-import会被保留为完整 token过滤掉长度为 1 的单字符 token返回 token 到出现次数的计数映射multiset。测试用例对以上行为给出了明确断言find_duplicates_test.goFix: Authentication BUG!会被规整为fix、authentication、bug三个 tokena b c hello只保留hello。3. 两种相似度指标Jaccard 相似度jaccardSimilarity基于计数版本的多重集 Jaccard交集计数 / 并集计数。测试中{fix, bug, auth}与{fix, auth, login}得分为 0.5交集 2、并集 4余弦相似度cosineSimilarity把 token 计数视为向量计算两向量夹角的余弦值对词频差异更敏感。4. 综合评分与配对findMechanicalDuplicates 先对全部 issue 一次性预 token 化再对i j的每一对计算(Jaccard Cosine) / 2作为最终相似度凡是 ≥ 阈值的组合都被收进结果。测试TestFindMechanicalDuplicates验证了两条描述同一登录认证 bug、措辞互换的 issue 在阈值 0.3 下会被识别为相似而无关联的暗色模式 issue 不会被误判。机械方法的边界文档明确指出find-duplicates.md机械方法快速、免费但可能漏掉措辞差异极大的语义相似项——这正是 AI 方法存在的意义。方法二AI 语义判定ai的工作流AI 方法并非把所有 issue 对一股脑发给 LLM而是采用机械预过滤 LLM 精判的两段式流水线以控制 API 调用成本find_duplicates.go预过滤以threshold × 0.5下限 0.15的低阈值运行机械相似度撒一张更大的网捞取候选对候选上限候选对最多保留 100 对超出时按机械相似度排序取 Top 100避免 API 费用失控分批调用候选对按每批 10 对batchSize 10分组逐批发送给 LLManalyzeWithAI判定过滤LLM 返回每对的is_duplicate、confidence与reason仅当判定为重复且confidence ≥ threshold时进入最终结果降级策略若 API 调用失败、响应格式异常或 JSON 解析失败命令打印 stderr 警告并回落使用机械相似度得分保证命令可用性。LLM 提示词与请求细节analyzeWithAI 揭示了具体的请求构造方式提示词要求模型判定每对 issue 是否描述相同的问题/任务/功能并以纯 JSON 数组回复字段为pair_index0 基索引、is_duplicate布尔、confidence0.0–1.0、reason简述每个 issue 的描述在入参时截断为前 500 字符控制 token 消耗请求MaxTokens为 2048解析响应时先剥离 Markdown 代码块再截取首个[到最后一个]之间的 JSON整个请求通过 OpenTelemetry 埋点anthropic.messages.newspan记录模型、操作名find_duplicates、批大小、输入/输出 token 数与耗时见 find_duplicates.go。方法参数校验--method只接受mechanical或ai传入其他值会返回错误invalid method %q (use: mechanical, ai)。选择ai但未配置任何 Key 时命令会直接报错提示需要ANTHROPIC_API_KEY、MINIMAX_API_KEY或ai.api_keyfind_duplicates.go。结果排序、输出格式与后续处置统一排序与截断无论哪种方法得到的候选对都会按相似度从高到低排序再应用--limit截断0 表示不限制见 reportFindDuplicates。文本输出默认文本输出find_duplicates.go若候选对为空打印No similar issues found (threshold: 50%)否则打印总对数与阈值然后逐对展示相似度百分比、两条 issue 的 ID 与标题、AI 模式的判定理由Reason最后给出Compare: bd show ID-A ID-B的对比命令提示方便你直接在终端用 bd show 人工复核。JSON 输出--json模式下返回结构化数据find_duplicates.go顶层结构为{ pairs: [ { issue_a_id: bd-001, issue_b_id: bd-002, issue_a_title: Fix authentication bug in login flow, issue_b_title: Authentication login bug fix, similarity: 0.68, method: mechanical, reason: Both describe SSO login failures } ], count: 1, method: mechanical, threshold: 0.5 }字段说明pairs为结果数组similarity为相似度/置信度reason仅 AI 模式可能非空count为对数method与threshold回显本次调用的参数。该格式便于在脚本、CI 或 Agent 管道中进一步加工。特殊边界issue 数量不足 2 时命令提示Not enough issues to compare (need at least 2)JSON 模式下则返回{pairs: [], count: 0}。对应的单 issue 测试见 TestFindMechanicalDuplicatesMinIssues。代理服务器--proxied-server模式支持命令同样适配 Beads 的代理服务器模式当检测到走代理路径时会通过runFindDuplicatesProxiedServer从代理会话中拉取 issue 列表find_duplicates_proxied_server.go复用相同的状态过滤与相似度报告逻辑此模式下最大行数上限会被强制拒绝见上文--max-rows说明。完整的 flag 校验、AI Key 校验与最大行数解析在任何一条路径上都会先执行保证行为一致。最佳实践建议基于以上机制给出几条可直接落地的使用建议日常巡检用默认机械模式bd find-duplicates零成本运行适合高频执行把阈值设在 0.4–0.5 之间可在误报与漏报之间取得平衡。重要批次用 AI 精判对机械模式产生的边界案例运行bd find-duplicates --method ai让 LLM 基于语义给出is_duplicate与reason先配置ai.api_key或ANTHROPIC_API_KEY并按需通过bd config set ai.model model指定模型。用 --status 缩小扫描范围默认已排除 closed新增 issue 较多时可先--status open聚焦活跃项。接入自动化时使用 --json将 JSON 输出交给下游脚本再结合输出的bd show id id对比提示人工复核后用 bd duplicates --auto-merge 完成合并清理。在 CI/Agent 中设置 BEADS_MAX_ROWS防止意外全库扫描拖垮环境超限即失败退出码 2并提示调整。通过机械与 AI 两级检测、可调阈值、JSON 输出与完整的状态/数量过滤bd find-duplicates让语义重复 issue从靠人眼翻阅变成可脚本化、可审计的例行任务——这正是它比单纯内容哈希查重更进一步的价值所在。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考