之前我们分享过一篇关于把 CodeGraph 引进项目开发的记录。那次的实测结果是：同一个需求交给 Agent，token 消耗降低50%。
那篇发出去之后，有朋友提出了这个疑问——就为了省点 token，值得单独建一套图吗。
小项目不值得，比如就几个脚本的，但是中大型的项目肯定值得。但省 token 这件事还排不上号。它只是个副作用。
真正的差别在别的地方，得从 CodeGraph 到底改了什么说起。
一、省下来的 token 只是副作用
代码是验证这套思路最省力的地方，因为它的结构本来就摆在那儿，只是从来没人单独抽出来交给模型看。
代码里最值钱的东西，不在代码里
常规做法是这样的：grep 或者向量相似度，找出十几个文件，整段整段塞进去，然后指望模型自己把这些片段之间的调用关系猜明白。
问题在于，一段代码真正值钱的部分，大部分时候不写在任何单个文件里。比如：
UserController.createUser()
│
│ calls
▼
UserService.register()
│
├────────────► PermissionService.assignDefaultRole()
│ depends_on
└────────────► EmailService.sendVerify()
│
▼
Redis（验证码）
UserRepository → user 表
这条链，你把任何一个文件单独翻一遍都读不出来。它是软件的暗结构，靠人靠经验记，靠 AI 靠猜。
CodeGraph 干的事就是把它显式化。解析 AST 和符号表，抽出文件、模块、类、函数、API、数据表、配置项这些节点，再把 calls / imports / inherits / reads / writes / depends_on 这些边连上。
模型拿到的不再是一堆片段，而是一张能顺着走的地图。
拿它来买什么
第一，上下文的规模变得能预算了。
以前是全库搜索 → 几十个候选文件 → 全量塞进去 → 二十万 token → 模型在噪声里捞信号。现在是从需求出发查图 → 定位影响子图 → 剪枝排序 → 八千 token。
省下来的那部分 token 是顺带的。真正买到的是信噪比——同样一个模型，喂二十万 token 全量代码和喂八千 token 精确定位的子图，产出质量能差一个量级，模型没换，换的只是喂进去的东西。
第二，代码修改从生成动作变成规划动作。
AI 改代码翻车，绝大多数不是因为它写不出来，是因为它不知道改这里会不会动到那里。有了调用图，Agent 能先把正向调用链（谁会受影响）和反向依赖链（我依赖谁、会不会被牵连）拉出来，算出影响范围——几个文件、几个接口、几个测试——生成计划，人确认过了再动手。
一个工程师说"改一下注册逻辑，加上手机号验证码"，他需要 AI 知道的是这几件事：注册模块在哪儿，入口有几个（Web、App、开放平台可能各有一套），验证码服务是不是已经存在、谁在调它，改完之后哪几个接口和测试用例得跟着动。
这些信息，没有一条藏在"register"这个关键词的搜索结果里。
第三，Review 的对象变了。
现在 PR 里 Reviewer 看到的是这么一行：
- user.status = pending
+ user.status = active
然后得靠自己的经验去推断谁读了这个字段、有没有副作用、会不会影响计费。在大型系统里这基本靠不住，人脑子里装不下一万条调用边。
基于图表可以直接给：
Change Impact Analysis
─────────────────────────────
修改：UserService.updateStatus()
直接调用方
├─ AdminController.approveUser()
└─ UserTaskScheduler.activatePending()
间接影响
├─ NotificationService（状态变更触发通知）
└─ BillingService（status 参与计费开关判断）
测试覆盖：3 个用例，billing.spec.ts 未覆盖 active 分支
风险等级：HIGH
原因：status 同时参与权限判断和计费判断
Reviewer 关心的问题从"你改了什么"换成"这次改动动了哪些业务能力"。这不是效率提升，是问的问题变了。
这条管道具体怎么搭
能用的 CodeGraph 基本是五层：
① 解析 tree-sitter / 语言服务器 / SCIP-LSIF
→ 增量解析成 AST + 符号表
② 实体 抽出 File / Class / Function / API / Table / Config
③ 关系 调用解析 + 依赖解析 + 数据流分析（CodeQL 那一类）
④ 存储 图库（Neo4j / Memgraph）或关系表 + 倒排索引
⑤ 查询 混合召回：符号精确匹配 + 图遍历 + 向量语义
第⑤层最容易被做砸。纯图遍历有个前提——你得先知道目标叫什么名字；纯向量检索又回答不了"这次改动会波及谁"。三路混着来才可用。
二、建图这条路上有五个坑
只讲好处不讲代价，那就成宣传稿了。这五个坑是公认的，且都很硬。
多语言。 Java、TS、Go 相对好办。Python 的动态特性、C++ 的模板和宏、Shell 和 SQL，基本做不出精确的调用图。一个号称支持全语言的 CodeGraph，通常只在两三种语言上质量过关，剩下的靠正则凑。
增量更新。 大仓库全量解析一次几十分钟到几小时。图上每来一次提交都要增量重建，索引服务本身就已经是个分布式系统问题了，跟建图这件事无关，但你绕不开。
动态语言的类型推断。 obj.method() 里的 obj 到底是什么类型？在 Python 和 JS 里这本身就是研究问题。图的质量上限被它死死卡住，跟你的解析工程做得多漂亮没关系。
图爆炸。 百万行代码的调用图轻松到千万条边，全量遍历一次就超时。必须做剪枝和分层，而剪枝策略本身又是一门手艺。
图漂移。 代码每周都在变，图几个月不重建就失真。而失真的图比没有图更危险——没图的时候模型还会说"我不确定"，有张错的图，它会自信地错。
所以诚实的说法是这样：CodeGraph 是一笔需要长期还的工程债，收益和成本都跟着代码库规模、变更频率一起涨。小而稳的项目上，认认真真做 grep 加分层的上下文，性价比大概率比建图高。
判断标准也就一句话：痛点是"找不到"，上检索；痛点是"看不全、怕改错"，才值得上图。
三、我们做的事，是把这套逻辑搬到代码之外
CodeGraph 面对的是软件世界。我们在试的是更野的一件事：用同样的方式处理人类积累的知识。
先看一个具体的问答。员工问"我下周去深圳出差三天，能住什么标准、走哪个流程、要不要提前审批"。
这两年知识库处理这类问题的标准动作是：切片、向量化、检索出三段包含"差旅""住宿"的文字，交给模型。这条路确实把"模型不知道公司私有信息"这个洞补上了，这一点得承认。
但这位员工真正需要的，是另外四件事：这条标准对他这个职级成不成立、深圳算不算一线城市有没有上浮、跟项目报销的条款冲不冲突、去年那次修订到底改了哪一条。
资料是够的。缺的是"哪些算数"和"它们怎么连着"。
知识从来就不是文本
这是很多知识库产品起步就搞错的地方。他们把知识当成"待检索的文章集合"，可知识大多是一张关系网，只是被压扁成了文档。
一条施工规范，它其实是：
规范条文
↓ 规定
施工工法
↓ 适用于
施工条件（部位 / 环境 / 材料）
↓ 对应
验收标准
↓ 引用
其他规范（这里往往藏着冲突条款）
一个审批流程，它其实是：岗位 → 职责 → 流程节点 → 审批权限（金额、职级、业务类型）→ 例外规则。
一份历史资料，它是人物、事件、时间地点、组织隶属、文献引证。
拍平成 chunk 之后，这些关系全都没了。而关系恰恰是"查到"和"理解"之间的分界线。
从管文档到管结构
对应的，要回答的问题也换了。以前是"存哪儿""怎么搜""谁能看"，现在是"它跟什么相关""在什么条件下成立""改了它会影响什么"。
所以在这个方向上的定位，也就不是"又一个能问答的知识库"，而是试着把文档、规范、流程、模型抽成一张能被程序遍历的结构，再按每次任务的需要切出上下文。
差别用一句话说：普通知识库回答"在哪儿能找到"，结构化知识系统回答"这意味着什么、下一步该做什么"。
四、图谱只是四分之一
这一节是我认为最容易被跳过、也最能看出功力的地方。
先把两个词分清楚。检索负责把资料搬出来，上下文负责决定搬哪些、按什么顺序摆、以及哪些关系得先解释清楚模型才看得懂。很多人把上下文工程等同于"搞个图谱 + 挂个检索"，太窄了。完整的上下文栈至少四层：
┌─────────────────────────────────────────┐
│ L4 反馈层 │
│ 执行结果 / 测试失败 / 用户纠正 → 回流修正 │
├─────────────────────────────────────────┤
│ L3 任务约束层 │
│ 输出格式 / 编码规范 / 禁改文件 / 权限边界 │
├─────────────────────────────────────────┤
│ L2 动态检索层 │
│ 图遍历 + 向量召回 + 符号匹配 → 候选集 │
├─────────────────────────────────────────┤
│ L1 静态结构层 │
│ 架构图 / 领域图谱 / 数据字典 / 核心实体 │
└─────────────────────────────────────────┘
L1 是骨架，不随每次提问变，占预算 10–20%。L2 是血肉，每次现算，占 50–60%，也是最容易做烂的一层。L3 是护栏，成本极低但收益极高——很多"AI 乱改文件"的毛病，加一条约束就解决了，根本不用动检索。L4 是闭环，没有它，系统永远停在第一次尝试的水平。
按我的经验，上下文窗口大致这么分：
| 区块 | 占比 | 内容 |
|---|---|---|
| 任务定义 | 5% | 到底要什么，验收标准是什么 |
| 结构摘要 | 15% | 相关子图的拓扑概览，不是代码全文 |
| 关键代码 / 原文 | 45% | 真正需要被改动或参考的内容 |
| 约束与规范 | 10% | 格式、禁区、命名、权限 |
| 历史与反馈 | 15% | 上次尝试的结果、已知的坑、相关决策记录 |
| 缓冲区 | 10% | 留给推理和输出 |
多数人把 90% 的预算砸在第三行，然后在别的地方裸奔。
一句话给图谱降降温
图谱本身不产出任何价值。它只有在被成功剪枝、排序、压缩、组装成"这轮推理刚好需要的那八千 token"的时候，才产出价值。
见过太多团队建了挺漂亮的图谱，最后的用途是做可视化大屏。那是给人看的。给模型用的图，必须能被程序化地切、排、压、装。
什么时候别建图谱
- • 知识体量小（几百篇以内）、更新极慢 → 好的元数据加向量检索够了，别过度设计
- • 问题形态是单点查找（"这个 API 的参数是什么"）→ 检索优于图谱
- • 没有维护预算 → 图会腐烂，腐烂的图比没有图更糟
- • 领域本体定不下来（概念边界一直在变）→ 先上弱结构，标签加引用链接就行，别一上来就立本体
结构化是手段，不是信仰。该平的地方平着来，该立的地方立起来，这本身就是工程判断力的一部分。
五、模型是公用的，上下文是你自己的
现在聊 AI，注意力基本都在模型侧：谁参数多、谁推理强、谁榜单一。
进了企业场景，很快会发现另外一件事。模型能力正在变成公共基础设施，谁都能调。但你们公司的知识结构、代码结构、流程结构，是独一份的，而且抄不走。
┌──────────────┐
│ AI Agent │
└──────┬───────┘
↑
┌─────────────────┐
│ Context Engine │
└────────┬────────┘
↑
┌──────────────┼──────────────┐
│ │ │
┌────▼───┐ ┌─────▼────┐ ┌─────▼────┐
│CodeGraph│ │Knowledge │ │ModelGraph │
└────┬───┘ └─────┬────┘ └─────┬────┘
│ │ │
代码仓库 文档规范 模型流程
大模型负责推理，Context Engine 负责提供"理解世界的基础设施"。中间那一层，才是每家企业真正能拉开差距的地方。
这条路走到底，产物不是知识库，是企业的世界模型：不只回答"是什么"，还能回答"为什么"、"影响什么"、"下一步该做什么"。到那一步，AI 才从会聊天的检索框，变成能参与业务运转的东西。
CodeGraph 让模型理解代码，我们在做的Molio（已在GitHub开源） 是让模型理解知识。两件事底下是同一条逻辑：模型的推理能力够用之后，决定应用上限的就成了我们能为它搭出什么样的上下文。
信息被结构化之后，模型才有可能从"找到答案"走到"理解这个系统"。
这是我们在知识工程方向的一次梳理。我们关心的一直不是模型又出了什么新能力，而是这些能力落到真实业务里到底是什么形态——上下文工程、知识结构、Agent 的可靠性，都是这条线上的题目。
如果你也在做知识库、代码智能或者 AI Agent 落地，欢迎关注 Molio，一起把方法论做实。