代码不是文档。把代码当文档塞向量库里能用，但回答"这个函数被谁调用了？""改这一行影响哪些测试？"这种问题，向量检索完全做不到。combo agent 把"代码进库"拆成三档索引能力，每档对应一类问题深度。
一张表看清三档
| 档位 | 你需要做什么 | 多久能用 | 能回答的问题 | 适合谁 |
|---|---|---|---|---|
| 零索引 | 直接扔仓库就能搜 | 即时 | "这个仓库里有处理鉴权的代码吗？""哪些文件提到了某个 API？" | 临时排查、刚接手的代码、不打算长期维护的小仓库 |
| 轻索引 | 等首次同步（仓库大小决定，分钟级） | 改一个文件后秒级就能搜到 | "这个函数定义在哪？""谁调用了它？""它的所有 import 是啥？" | 日常代码评审、新人 onboarding、绝大多数业务仓库 |
| 重索引 | 提前接好编译环境（项目结构决定，10 分钟～小时级） | 全量分析完后才可用 | "改这一行影响哪些下游？""这个继承层级长什么样？""跨编译单元的所有引用" | 老旧 C/C++ 项目、安全审核、跨模块大重构 |
为什么不是"一档解决所有"
很多产品说"我们一档全搞定"，要么是骗你：
- 要么深度不够：只能字面 grep，回答不了调用关系
- 要么等不起：每个仓库都得"半编译"，初始化几十分钟，下次还得等
我们的判断：索引深度和初始化代价是个 trade-off，按场景选档才是工程做法。
零索引：拿来就搜
不建索引，全靠语法层面的智能匹配 + LLM 自己读相关文件。
适合的提问：
- "这个仓库主要做什么？给我一个概览"
- "搜一下处理超时的代码片段"
- "我记得有个文件叫
payment_*.py，帮我找出来"
不适合的：
- "这个函数被谁调用了"——零索引看不到调用关系，只能告诉你字面包含了这个名字的地方
- 跨语言调用、跨文件继承推理
务实建议：如果你只是想让 AI 帮你"看一眼这个仓库"，零索引就够了。最大优点是没有等待。
轻索引：日常用的主力
平台用本地工具（基于 tree-sitter 一类的语法分析）建轻量索引，对每种语言抽出函数、类、变量、import 的位置，存进搜索引擎。
关键升级（M4 / R8 之后）
- 改一个文件，新内容秒级可搜 —— 以前要等几分钟，现在不用了
- 老的"批量等待 / 批量重建"机制取消了，写完代码立刻就能问
适合的提问
- "
processOrder这个函数定义在哪、谁调用了它" - "这个类继承自哪？子类有哪些"
- "整个项目里有几个地方在用
redis.Pipeline" - "这个文件 import 的所有外部模块列一下"
不适合的
- 需要类型推导才能解的问题（C++ 模板实例化、Python 鸭子类型的真实运行时类型）
- 跨编译单元、跨链接边界的引用
- ASIL-D 模块"改这一行影响整个项目哪些下游"
重索引：审计 / 重构 / 老 C/C++ 项目
把项目真的"半编译"一遍，建立类型完整的代码图谱（基于 SCIP 语义图）。这一档最贵也最准。
适合的场景
| 场景 | 必须重索引的原因 |
|---|---|
| 老 C/C++ 项目 | 宏、模板、include 关系复杂，没有类型信息根本审不动 |
| 安全审计 | 跟踪用户输入流到敏感函数的完整路径（污点分析） |
| 跨模块重构 | 改一个核心接口，必须先看清所有下游 |
| 代码合规审核 | MISRA / ASPICE / 26262 要求"完整调用链可追溯" |
| ASIL-D 安全分析 | SOTIF / FMEA 需要精确到行级的影响传播 |
前置条件
- 你的项目能在我们的环境里编过去（CMake / Bazel / Maven 等其中一种）
- 接受一次性 10 分钟到小时级的初始化时间
- 项目语言在 SCIP 支持矩阵里（Java / Python / Go / Rust / TypeScript / C-C++ 部分支持）
实战例子
在汽车 ECU 代码上，能回答**"我改了 can_send_frame 这个函数，最终影响哪几条 CAN 总线、对应哪几个 ASIL 等级的需求条目"**——这种问题轻索引和零索引都给不了答案，必须开重索引。
各场景档位推荐
| 场景 | 推荐档位 | 备注 |
|---|---|---|
| 日常 PR / MR 代码评审 | 轻索引 | 秒级响应 |
| 新人 onboarding 看代码 | 轻索引 | 调用关系够用 |
| 临时排查外包提交 | 零索引 | 不值得等 |
| 快速搜某个开源仓库 | 零索引 | 立等可取 |
| ASPICE 合规审 / BP 评估 | 重索引 | 必须完整调用链 |
| 跨模块大重构 | 重索引 | 必须看清下游 |
| 安全审计 / 污点分析 | 重索引 | 跨编译单元 |
| SOTIF / FMEA 影响分析 | 重索引 | 精度到行级 |
Ragbase 代码索引全栈（L1–L6）
销售层面的"零 / 轻 / 重三档"是产品包装。研发层面真实分层是 6 层：
| 层 | 索引类型 | 来源 | 触发条件 |
|---|---|---|---|
| L1 | 文本分块 + embeddings | 任何 parser | 永远 |
| L2 | BM25 全文倒排 | 任何 parser | 永远 |
| L3 | AST 分块 | tree-sitter | parser_id=code-aware |
| L4 | R8 关键词字段（函数 / 类 / import / fqn） | tree-sitter AST 派生 | L3 跑通 |
| L5 | audit_findings | ast-grep YAML 规则 | ast-grep 二进制可用 |
| L6 | SCIP 语义图（index.scip） | scip-java / scip-python / tree-sitter | index_tier=heavy |
| 销售档位 | 实际包含层 |
|---|---|
| 零索引 | 多数 L1/L2/L3 不写库 — 靠 LLM / grep 兜底 |
| 轻索引 | L1+L2 必开；code-aware 再叠 L3+L4+L5 |
| 重索引 | 轻索引基础上为支持语言再做 L6 SCIP 全图 |
与 L1+L2 双层代码审查的关系
我们的 AI 代码审查 系统也叫 L1 / L2 —— 但那是审查层级，不是索引层级：
- 代码审查 L1：客观静态扫描（cppcheck / Checkstyle / ruff 等本地工具）
- 代码审查 L2：语义评审（LLM + KB + LTM）
- 索引 L1-L6：代码进库的底层分层
不要混淆。L1/L2 代码审查可以在任意索引档位下运行 —— 但 ASIL-D 模块的 L2 审查必须搭配重索引才有意义。
常见问题
Q：能不能从零索引直接升到重索引？ A：能。索引档位是项目级别配置，可在线切换。切到重索引会触发一次完整半编译。
Q：仓库太大（1M+ 行），重索引能跑得动吗？ A：能。但首次初始化可能要几小时。我们建议先评估你的核心模块（10-50 万行），重索引开核心，外围用轻索引。
Q：私有化部署能上重索引吗？ A：能。SCIP 索引完全本地化，不出客户内网。
Q：增量重索引怎么处理？ A：轻索引是真增量（改一个文件秒级生效）；重索引是"批量增量"，按 commit batch 或定时全量。
Q：和 Sourcegraph 比有什么不同？ A：Sourcegraph 的代码索引很强，我们在能力上看齐它（部分场景用了同源的 SCIP 工具链）；但 combo agent 是配合 LLM 检索 + 团队记忆 + 业务规则的整套 Agent 平台，不只是"搜代码"。
完整能力清单看 代码索引三档（docs/concepts/code-index）。
作者
Nox-Lumen Tech-team
发布日期
2026年5月14日