Beads 语义查重实战：`bd find-duplicates` 命令的机械相似度与 AI 判定机制解析-开发者社区

Beads 语义查重实战：`bd find-duplicates`命令的机械相似度与 AI 判定机制解析

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

bd 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）与 AI（ai）两种检测方法：

mechanical（默认）：基于 token 的文本相似度计算，不需要任何 API Key，离线即可运行；
ai：基于 LLM 的语义比较，需要配置 Anthropic 兼容的 API Key（ANTHROPIC_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.md）：

bd 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.go（open、in-progress、blocked、deferred、closed、pinned、hooked 等）。

完整 Flags 参考表

以下是命令支持的全部参数（来自 find-duplicates.md 与 init() 注册代码）：

Flag	缩写	类型	默认值	说明
`--limit`	`-n`	int	50	最多显示的结果对数
`--method`	无	string	`mechanical`	检测方法：`mechanical`或`ai`
`--model`	无	string	来自配置`ai.model`	AI 使用的模型，仅在`--method ai`时生效
`--status`	`-s`	string	非 closed	按状态过滤，`all`表示不过滤
`--threshold`	无	float	0.5	相似度阈值（0.0–1.0，越低结果越多）
`--max-rows`	无	int	0（禁用）	行数硬上限，超限以退出码 2 报错（见下文）
`--json`	无	bool	false	以 JSON 输出结果（全局 flag）

阈值参数的直观理解

--threshold取值范围为 0.0–1.0，默认 0.5。阈值越低，被判定为重复的对越多（即召回更高、误报更多）；阈值越高，结果越保守（精确率更高、可能漏掉措辞差异大的重复）。控制台文本输出会以百分比形式展示实际使用的阈值，例如Found 3 potential duplicate pair(s) (threshold: 50%)。

防御性行数上限（--max-rows / BEADS_MAX_ROWS）

find-duplicates还注册了防御性行数上限 flag（代码注释标记为 be-x42v，见 find_duplicates.go），实现在 cmd/bd/max_rows.go：

通过--max-rows N或环境变量BEADS_MAX_ROWS=N设置硬上限，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 化（tokenize）

tokenize 的规则：

全文转小写；
以"非字母、非数字、非连字符"的字符作为分隔符切分单词，连字符词（如auto-import）会被保留为完整 token；
过滤掉长度为 1 的单字符 token；
返回 token 到出现次数的计数映射（multiset）。

测试用例对以上行为给出了明确断言（find_duplicates_test.go）："Fix: Authentication BUG!"会被规整为fix、authentication、bug三个 token，"a 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）分组，逐批发送给 LLM（analyzeWithAI）；
判定过滤：LLM 返回每对的is_duplicate、confidence与reason，仅当判定为重复且confidence ≥ threshold时进入最终结果；
降级策略：若 API 调用失败、响应格式异常或 JSON 解析失败，命令打印 stderr 警告并回落使用机械相似度得分，保证命令可用性。

LLM 提示词与请求细节

analyzeWithAI 揭示了具体的请求构造方式：

提示词要求模型判定每对 issue 是否描述"相同的问题/任务/功能"，并以纯 JSON 数组回复，字段为pair_index（0 基索引）、is_duplicate（布尔）、confidence（0.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_key（find_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），仅供参考

Beads 语义查重实战：`bd find-duplicates` 命令的机械相似度与 AI 判定机制解析