---
title: 语义搜索与关系上下文：发现隐藏依赖但保留验证
description: 用构造的重构场景组合直接检索和一跳关系扩展，解释分数、候选和来源字段，不把关联线索写成依赖证明。
image: "https://zengliangyi.com/og/blog/semantic-search-relation-context.png"
---

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

实现依据是固定提交 [`7642768`](https://github.com/ZengLiangYi/ChatCrystal/tree/764276814e5c5a33ecbfeae63754f74b9261a3a8) 的 [向量搜索](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/services/embedding.ts) 与 [关系服务](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/services/relations.ts)。下面的认证重构场景用于说明方法，不是实测结果。

## 先建立直接命中基线

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



```bash
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`：



```bash
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 记忆工作流](/blog/claude-code-memory-workflow)执行回忆和预检；关系和图投影的接口差异见 [笔记关系与图视图](/blog/note-relations-and-graph)。

分享：

##  相关文章

[##  笔记关系与图视图：从候选发现到可验证扩展

按 ChatCrystal 当前关系 API、候选筛选与图投影说明自动发现、手动关系和标签图的实际边界。          曾亮懿       2026年10月3日      阅读约 3 分钟

#ChatCrystal

#知识图谱

#关系](/blog/note-relations-and-graph)    [##  找回调试方案：从搜索候选到验证可复用条件

用一个明确标注的调试场景，检查笔记、向量和检索返回，再核对原始对话与当前项目，避免把相关分数当作正确答案。          曾亮懿       2026年10月3日      阅读约 4 分钟

#ChatCrystal

#语义搜索

#调试](/blog/recover-debugging-notes)    [##  语义搜索流程：请求、候选去重与关系扩展

沿 ChatCrystal 实现检查查询向量、候选升级、词项加分和关系扩展，用实际 API 区分笔记列表筛选与语义检索。          曾亮懿       2026年10月3日      阅读约 3 分钟

#ChatCrystal

#语义搜索

#RAG](/blog/semantic-search-workflow)

##  从文章到代码

到我的 GitHub 看看 ChatCrystal、开发者工具和日常学习记录，欢迎交流实现细节。

[访问我的 GitHub](https://github.com/ZengLiangYi)

```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "ZengLiangYi Blog",
  "alternateName": [
    "Zeng Liangyi",
    "ZengLiangYi",
    "zengliangyi.com"
  ],
  "url": "https://zengliangyi.com",
  "description": "曾亮懿的个人网站。记录 AI Native 探索、开发者工具与全栈产品实践。"
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "语义搜索与关系上下文：发现隐藏依赖但保留验证",
  "description": "用构造的重构场景组合直接检索和一跳关系扩展，解释分数、候选和来源字段，不把关联线索写成依赖证明。",
  "url": "https://zengliangyi.com/blog/semantic-search-relation-context/",
  "image": "https://zengliangyi.com/images/blog/semantic-search-relation-context.svg",
  "datePublished": "2026-10-03T00:00:00.000Z",
  "dateModified": "2026-10-03T00:00:00.000Z",
  "author": {
    "@type": "Person",
    "name": "曾亮懿",
    "url": "https://zengliangyi.com/about"
  },
  "publisher": {
    "@type": "Organization",
    "name": "ZengLiangYi Blog",
    "logo": {
      "@type": "ImageObject",
      "url": "https://zengliangyi.com/favicon-96x96.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://zengliangyi.com/blog/semantic-search-relation-context/"
  }
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "首页",
      "item": "https://zengliangyi.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "文章",
      "item": "https://zengliangyi.com/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "语义搜索与关系上下文：发现隐藏依赖但保留验证",
      "item": "https://zengliangyi.com/blog/semantic-search-relation-context/"
    }
  ]
}
```