定义：Semibot 的原生代码图谱是一个 TypeScript 代码知识图谱引擎，它索引代码库中的调用、引用、类型关系和结构连接。它内建在核心运行时中——不依赖 Python sidecar，不依赖外部 MCP。Agent 用它来更快地导航陌生项目、少读无关文件，并在代码审查时追踪变更的影响范围。代码图谱是导航辅助工具，不是正确性预言机。
为什么关键词搜索不够用
关键词搜索（grep、find、语义搜索）回答「哪些文件包含这个词？」代码图谱回答「这个函数和什么相连，怎么相连的？」这个区别在三类任务中至关重要。
第一类是上手陌生项目。当你第一次打开一个代码库时，你需要的不是找到某个关键词出现的位置，而是理解项目的结构：哪些模块负责什么功能、模块之间怎么调用、数据怎么流动。关键词搜索给你一堆零散的命中点，代码图谱给你一张结构地图。
第二类是规划变更。当你想修改一个函数时，你需要知道：还有谁在调用它？修改它的返回值会影响哪些下游模块？关键词搜索只能靠函数名匹配来猜测调用关系，代码图谱通过静态分析直接给出确切的调用链和引用链。
第三类是审查代码。审查者需要评估一个变更的影响范围——不只是被直接修改的文件，还有通过依赖关系间接受影响的文件。代码图谱能自动计算变更的影响范围（blast radius），让审查者不会遗漏间接影响。
Schema v4 与四层工具契约
代码图谱使用 Schema v4：统一的结构节点、能力级别的就绪状态，以及为社区检测、数据流、拓扑和代码质量派生的索引。Schema v4 的设计目标是用一个统一的数据模型覆盖代码库的多种结构关系，避免为每种分析需求维护独立的索引。
引擎向 Agent 暴露四个工具层（G1–G5），每一层覆盖不同复杂度的查询需求：
- G1：基础查询——查找定义、引用和调用点。这是最常用的层级，每次代码导航几乎都会用到。
- G2：结构查询——模块边界、依赖方向、层级违规。用于理解项目架构和发现设计问题。
- G3：影响分析——如果节点 X 发生变更，哪些其他节点会受影响？用于变更影响评估和风险判断。
- G4/G5：质量和拓扑指标——复杂度、耦合度、社区结构。用于全局的代码健康度分析和架构重构规划。
Agent 不需要选择使用哪一层——Tool Gateway 会根据任务和 Agent 的请求自动路由。这可以防止 Agent 在简单的引用查找就能解决问题时，意外运行昂贵的全局图谱分析。G4/G5 层级的查询可能涉及整个代码库的遍历和计算，如果没有路由控制，一次简单的「谁调用了这个函数」就可能触发不必要的全图分析，浪费计算资源。
导航 vs 正确性
图谱展示的是关系，而不是代码是否正确。它能告诉你函数 A 调用了函数 B，B 有三个调用者，B 位于某个模块的边界上。但它不能告诉你 B 的逻辑是否正确、是否存在边界条件 bug、或者性能是否可接受。高风险的结论——bug、安全漏洞、性能瓶颈——必须回到源代码或可复现的命令来验证。
这条边界是设计强制的，不是文档建议。代码图谱在 Tool Gateway 中严格以导航工具的形态暴露。它不产出「分析报告」或「质量评分」这类可能被误读为裁决的东西。它产出的是结构化的关系数据——谁调用谁、谁依赖谁、哪些节点形成循环——由 Agent 来解读和使用。这种设计避免了一个常见的陷阱：让工具的输出看起来像是最终判断。
Agent 在实践中怎么用它
审查代码变更时，Agent 可以问图谱：「还有谁调用了这个函数？」「哪些模块依赖这个文件？」这会产出一个影响范围（blast radius）——可能受到变更影响的代码集合。然后 Agent 读取相关文件，评估变更是否安全，并在 ChangeSet 中报告影响分析。没有图谱时，Agent 需要靠 grep 和猜测来推断调用关系；有了图谱，它沿着静态分析确认的关系行走，结果更可靠。
在日常编码中，图谱也帮助 Agent 更高效地阅读代码。面对一个陌生函数，Agent 可以先通过图谱了解它的调用者和被调用者，建立上下文后再阅读实现细节。这比从头到尾逐行阅读一个文件高效得多——尤其在大型代码库中，一个函数的上下游关系可能分布在十几个文件中。
为什么是「原生」
「原生」意味着代码图谱引擎用 TypeScript 实现，和 Semibot 的核心运行时是同一种语言。不需要启动额外的 Python 进程、不需要配置外部的 MCP 服务、不需要在两个运行时之间做序列化和反序列化。这降低了部署复杂度，减少了出错的可能，也让索引和查询的延迟更低。
另一个好处是版本一致性。原生引擎随客户端一起更新，不需要用户单独维护图谱引擎的版本。升级 Semibot 就自动升级了代码图谱，不需要额外操作。
局限性
- 图谱索引的是静态关系。动态分发（如函数指针、回调）、反射（如运行时类型查询）和元编程（如代码生成、宏展开）只能被部分捕获或完全无法捕获。
- 索引时效性很重要。如果代码库在上次索引后发生了重大变化，图谱中的关系可能已过时。Agent 可以在检测到代码变化后请求重新索引，但这需要额外的时间。
- 语言支持目前限于 TypeScript 和 JavaScript。其他语言（Python、Rust、Go 等）回退到 Agent 的通用搜索能力和用户的手动指引。未来版本可能会扩展语言支持。
- 图谱用于导航，不用于验证。它无法证明代码是否正确、是否安全、或是否满足某些规范。
- 全局图谱分析（G4/G5）成本高昂，受速率限制以防止资源耗尽。在大型代码库上运行拓扑分析可能需要较长时间。
基准测试与诚实的失败记录
Semibot 的代码图谱是原生 TypeScript 实现：不依赖 Python、不启动语言服务器、不附带任何 sidecar 进程。语法层用 Tree-sitter 的 WASM 语法，模块解析复用 TypeScript 编译器 API。图模型包含 15 种节点与 10 种关系（包含、导入、导出、调用、引用、继承、实现、测试、依赖、解析指向），每条边携带解析等级（语法精确 / 解析器精确 / 启发式 / 未解析）、置信度与证据指纹——置信度由解析器规则生成，不允许由模型填写。符号键经过规范化，行号移动不会破坏引用稳定性。
查询分四层共 26 个工具：符号搜索、关系遍历（找调用方/被调方/影响面）、全库质量与拓扑（社区发现用 Louvain，环检测用 Tarjan，均为确定性算法），以及显式面向变更的辅助层。前三层拿不到变更集与 Git 信息，也拒绝模型提供的 SQL 或任意遍历 DSL——查询能力是产品定义的，不是模型即兴生成的。设计文档保留了基准数据：10 万文件的完整索引中位耗时约 10.4 秒，对照的第三方 Python 方案约 43.4 秒；索引体积约为后者的 49%；符号与影响查询的 p95 在 1 毫秒量级。
同样值得引用的是文档里逐项保留的失败记录：热查询延迟与内存占用两项指标在自测中未达标（包括观测到资源压力下的 I/O 停顿），发行门禁因此把热查询 p95 比基线快 20%、峰值内存不超过第三方 80% 定为硬性验收项。正确性门禁同样量化：精确符号检索的 top-1 精确率须 ≥99%、二跳影响分析的召回率须 ≥98%。把失败写进设计文档并转为验收条款，是这个引擎最「研究」的部分。
FAQ
代码图谱需要 Git 才能工作吗？
不需要。代码图谱索引的是文件系统中的源代码，不是 Git 历史。即使你的项目没有使用版本控制，图谱也能正常工作。Git 在 Semibot 中是可选的源码管理工具，和代码图谱是独立的。
支持 Python/Rust/Go 吗？
目前原生支持 TypeScript 和 JavaScript。对于其他语言，Agent 回退到通用搜索（grep、find、语义搜索）和用户的指引。图谱引擎的架构支持扩展到更多语言，但目前优先保证 TypeScript/JavaScript 的深度支持。
我能直接查询图谱吗？
不能。Agent 通过 Tool Gateway 查询图谱，没有面向用户的图谱可视化界面或查询控制台。这是设计决定——图谱是给 Agent 用的导航工具，不是给用户用的分析平台。如果你想了解代码结构，直接问 Agent 即可。
索引存储在本地吗？
是的。图谱索引在本地 SQLite 数据库中，与会话和知识库存放在一起。索引数据不会离开本机，不需要网络连接即可使用图谱功能。
索引更新是自动的吗？
Agent 会在工作过程中检测到代码变化并触发增量索引。如果代码库发生了大规模重构，Agent 可以请求全量重建索引。索引过程在后台运行，不影响你正常使用工作台。