语义搜索与关系上下文：发现隐藏依赖但保留验证

重构认证模块时，搜索能找到直接讨论 JWT 的笔记，关系扩展还可能带来权限、刷新任务或密钥管理的上下文。但“被扩展出来”不等于“代码一定依赖它”。下面使用构造场景说明如何把检索线索变成待验证清单。

实现依据是固定提交 7642768 的 向量搜索 与 关系服务。下面的认证重构场景用于说明方法，不是实测结果。

先建立直接命中基线

先用已知的目标词查询，再用同义表述和无答案问题重复：

curl --get http://localhost:3721/api/search \
  --data-urlencode 'q=JWT 认证 token 校验' \
  --data-urlencode 'limit=5'

HTTP 返回的 data 包含 note_id、conversation_id、标题、项目、分数、标签和 via_relation。直接结果的 via_relation 为空；分数已经经过应用候选、词项和去重规则处理，不要把它当成概率或真实依赖强度。拿 ID 再读取笔记和原始会话，记录每条结果是否真的涉及当前模块。

再打开一跳关系扩展

扩展开关是 expand=true：

curl --get http://localhost:3721/api/search \
  --data-urlencode 'q=JWT 认证 token 校验' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'expand=true'

当前实现从直接命中的笔记读取一跳关系，只扩展 confidence 至少 0.5 的边；关联分数按“直接分数 × 0.7 × confidence”折扣。已经在结果中的笔记会跳过，扩展可能使总结果超过直接查询的上限。它不走多跳路径，也不会为每个目标寻找最强路径。

用关系类型组织排查清单

搜索会沿关系的两个方向扩展，而 via_relation 只返回类型，不返回方向。先通过关系详情核对 source、target，再把类型转成问题，而不是结论：

• DEPENDS_ON：在当前代码和配置中查找真实调用、共享字段或生命周期约束。
• LEADS_TO：检查下游流程是否由这一步触发，避免只凭主题相似判断因果。
• RESOLVED_BY：确认旧方案的前提在当前版本仍成立。
• REFERENCES 或 SIMILAR_TO：作为阅读入口，不能当成运行时依赖。

关系服务的候选最多 20 条，找不到语义候选时退回最近笔记；模型输出还会经过候选 ID、confidence 和最多 5 条的过滤。因此图谱覆盖率受候选和模型输出影响，不是完整静态依赖图。

把隐藏依赖变成验证动作

对每个间接候选记录三个字段：笔记原文证据、当前代码位置、验证命令。运行测试或构造最小复现，确认重构前后行为；若版本、部署或项目不同，重新检查条件。无答案查询和误匹配也要保留，它们能揭示检索边界。

关系扩展适合扩大阅读范围，不能替代 IDE 引用分析、代码搜索、测试和人工审查。需要回忆任务经验时，先按 Claude Code 记忆工作流执行回忆和预检；关系和图投影的接口差异见 笔记关系与图视图。