核心观点：AI 写代码的瓶颈往往不是模型不够聪明，而是它看不到项目的结构。靠关键词搜索捞文件的 Agent，捞到什么全凭运气；而人接手项目时靠的是 IDE 里的跳转和找引用——本质上是一张代码关系图。Semibot 把这张图做成内置的「原生代码图谱」，让 Agent 沿着符号关系导航：改之前看清影响面，改之后顺着关系去审查。
是什么 / 不是什么
是什么
- 代码库的符号级索引：函数调用关系、导入导出链、类型引用、类与接口的层级。不是文本匹配，是语法树级别的理解。
- Agent 的导航系统：Agent 可以在图谱上连续查询——找定义、找调用方、找同类实现、找受影响文件——就像工程师在 IDE 里跳转那样。
- 本地构建、本地存储：打开项目时在本机建索引，代码不因建图离开你的电脑。
不是什么
- 不是给人类看的可视化挂件：图谱不画花哨的关系图，它服务于 Agent 的检索和工作流。
- 不是运行时分析：它不知道程序跑起来会发生什么，动态行为要靠测试验证。
- 不是全语言等深的百科：TypeScript/JavaScript 最深，其他语言的关系数据较浅（详见下文边界）。
理念：为什么 Agent 需要一张图
观察 AI 编码工具的失败案例，大部分不是「模型写错了代码」，而是「模型改错了地方」。根因通常相同：它对项目的理解来自零散的文本检索。
grep 加猜，赌的是运气
传统做法是关键词搜索：搜函数名、搜报错字符串、搜注释词。这种方式有三个结构性问题。第一，命名与语义脱节——项目里叫 handleRequest 的函数未必处理你想改的请求；第二，噪声挤占上下文——搜回十个文件，九个不相关，真正相关的那个可能没被搜到；第三，看不见间接关系——改了一个类型的字段，靠搜索找不到所有消费方。
人怎么读项目：跳转和引用
工程师接手陌生项目时，很少从头读到尾。我们从入口开始跳转：这个函数在哪定义、被谁调用、实现了哪个接口、类型从哪来。这套动作的底层是一张符号关系图——只是工程师靠 IDE 在脑子里维护它。
Semibot 的理念是：把这套导航能力完整交给 Agent。先建图，再干活。Agent 的每次检索可以沿着确定的关系边走，而不是靠关键词碰运气。
「原生」的两个含义
- 内置而非外挂：图谱是 Semibot 的原生实现（TypeScript 编写，无 Python sidecar，无需配置语言服务器）。打开项目即可用，不用搭建任何索引服务。
- 一等公民而非附属品：图谱不是产品演示用的可视化，而是 Agent 工作流的检索原语——查图谱和读文件、跑命令一样，是 Agent 干活的基本动作。查询结果直接进入修改计划和 ChangeSet 审查。
特色：图谱改变 Agent 行为的四个场景
场景一：接手陌生项目
让 Agent「修复这个报错」。没有图谱时，它搜报错文本、翻目录、猜入口。有图谱时，它从报错位置出发：跳到定义 → 找到调用链上游 → 确认真正抛错的条件分支 → 定位根因。翻的文件少了，路径对了，耗时和 token 都显著下降。
场景二：改代码之前看清影响面
「把这个字段改成可选的」。图谱先回答：谁在引用这个字段、哪里做了非空判断、哪些类型定义会连锁变化。Agent 可以在动手前把影响面列出来，修改方案直接覆盖所有受影响位置，而不是改完主调用点再等着测试爆出遗漏。
场景三：审查变更时顺着关系看
ChangeSet 展示 diff，图谱回答「这个 diff 够不够」。Agent 审查自己（或同事）的改动时，沿被改符号的关系边检查：调用方都适配了吗？有没有同构实现需要同步修改？审查从「看 diff 像不像对的」变成「沿影响面验证是对的」。
场景四：把上下文花在刀刃上
模型上下文是稀缺资源。图谱检索把「真正相关的少量代码」交给模型，替代「大量低相关文件硬塞」。同样的任务，上下文更干净意味着更少的干扰、更低的成本和更稳定的输出质量。
边界与局限
这部分和 Semibot 其他文章一样直说：图谱有明确的适用边界，知道边界才能正确使用。
- 语言深度不均：图谱原生面向 TypeScript/JavaScript，对这类项目提供最深的关系数据。其他语言的项目，Agent 仍能正常读写文件、执行命令，但影响分析的精度会下降。
- 静态分析的天然边界：动态分发、反射调用、字符串拼接的引用、运行时生成的代码，图谱都追踪不到。这些情况需要测试兜底。
- 超大仓库有取舍：monorepo 的索引时间和关系覆盖度需要平衡，冷启动索引需要一点耐心。
- 图谱不替代测试：图谱告诉你「哪里可能受影响」，测试告诉你「是否真的受影响」。两者互补，缺一不可。
适合谁 / 不适合谁
图谱价值最大的场景
- 中大型 TypeScript/JavaScript 项目：关系密度越高，图谱相对 grep 的优势越大。
- 频繁接手他人代码的团队：Agent 沿关系导航快速建立上下文，缩短「读懂」的时间。
- 对变更质量要求高的代码库：改动前先看影响面，审查时沿影响面验证。
图谱帮助有限的场景
- 脚本和小工具：几十个文件的项目，直接搜索就够了，图谱收益不明显。
- 以动态语言为主的项目：关系数据较浅时，图谱只是辅助，别指望它兜底影响分析。
- 重运行时验证的任务：性能调优、并发问题这类要靠运行数据的工作，静态图谱帮不上忙。
FAQ
什么是原生代码图谱？
代码库的符号级索引：函数调用关系、导入导出链、类型引用、类与接口层级。Semibot 在本地构建这张图，Agent 沿关系导航而不是靠关键词反复猜测。
和 IDE 的「查找引用」有什么区别？
底层能力类似，区别在使用者：IDE 的引用查找给人看，结果是一次列表；图谱是 Agent 的工作原语，Agent 在图上连续导航，并把查询结果用于制定修改计划和审查变更。
需要额外安装或配置吗？
不需要。图谱是 Semibot 内置能力，原生 TypeScript 实现，无 Python sidecar、无需配置语言服务器，打开项目即可用。
图谱数据存在哪里？
和 Semibot 的其他工作数据一样，索引在你的电脑本地构建和存储，代码不因建图离开本机。
有了图谱还要写测试吗？
要。图谱是静态分析，追踪不到运行时行为（动态分发、反射、字符串拼接引用）。它负责「找出可能受影响的地方」，测试负责「验证是否真的受影响」。
和把整个仓库塞给模型有什么区别？
仓库远大于模型上下文。图谱的价值在上下文经济学：先用关系检索找出真正相关的代码，再把少量高质量上下文交给模型——比硬塞大量文件更快、更省、更准。