在这里插入图片描述

AI Agent 通识课 · 第 6 篇 / 共 9 篇

一句话记住：改动在哪，重算到哪。

我给 ChatGPT 问了个简单问题：

“我项目里的 UserService 是怎么实现登录的？”

它回答：“我看不到你的代码。”

换 Claude 问同样问题：“请把相关文件内容粘贴给我。”

换 Cursor 问：3 秒后给出准确答案，还引用了 3 个相关文件的具体行。

为什么同样是 GPT-4，一个能懂我项目，一个不行？

答案在一个很少被提及、但决定 Agent 可用性的底层能力——

代码索引系统。

这是今天的主题。你不一定写代码，但这个设计思想适用于任何大数据量场景——搜索引擎、知识库、文档助手、企业内部 AI。

01 · 为什么 AI 不懂你的项目？

LLM 有个根本限制：上下文窗口。

  • GPT-4o：128K tokens（约 10 万字）
  • Claude 3.5：200K tokens（约 15 万字）
  • Gemini 1.5：1M tokens（约 75 万字）

听起来很多？

一个正经项目的代码轻松超 100 万行，500MB+。

根本塞不进 LLM 的上下文。

怎么办？

02 · 生活化对比：Word 改一个字

你用 Word 编辑一个 500 页的文档。

改了第 100 页的一个字。

Word 需要重新加载整个文档吗？

当然不需要。

它只更新那一处，前后 99 页和 400 页完全不动。

AI 处理代码库应该是同样的逻辑：

你改了一个函数 → AI 只需要重新认识这个函数，其他文件不用重建。

但实际上很多 AI 产品做不到这一点。

它们要么完全不懂你的代码（ChatGPT），要么每次都重扫全库（慢/贵），

只有精心设计的产品才做到"改动在哪，重算到哪"。

03 · 如果让你来做，你会怎么设计？

场景：项目有 1 万个文件，总计 500MB 代码。

AI 要能快速找到"登录相关代码"。

你会怎么做？

朴素方案 A：全量扫描

每次搜索 → 读 10000 个文件 → 全扔给 LLM

问题：

  • ❌ 慢死（500MB 数据流过 LLM）
  • ❌ 贵死（LLM 按 token 收费，爆表）
  • ❌ 撑爆上下文窗口（塞不下）

方案 B：关键词搜索

搜"登录" → 用 grep 找所有包含这个词的文件

问题：

  • ❌ 不理解语义（“login” / “auth” / “签到” 都是登录，但关键词不同）
  • ❌ 代码里到处是"login"，噪音大
  • ❌ 找不到调用关系

方案 C：向量索引

提前给所有文件生成"语义向量"（Embedding）
搜索时把问题也转成向量，找最相似的 5 个文件

效果：能找到语义相关的代码。

但问题：

  • ❌ 你改了一个文件，要不要重建所有向量？
  • ❌ 重建全量很贵（1 万文件跑一遍 Embedding）
  • ❌ 不重建又会漏

正确方向：增量更新

提前给每个文件生成一个"指纹"（hash）
改了文件 → 比较新旧指纹 → 只重建变化的部分

省 90% 的时间和钱。

04 · 四种主流代码索引方案

方案 A：无索引（ChatGPT 路线）

做法：不维护任何索引，用户要问代码问题就自己复制粘贴。

谁在用：ChatGPT 基础版、豆包、文心一言

优点：

  • ✅ 实现简单
  • ✅ 没有维护成本

缺点：

  • ❌ 完全不懂你的代码
  • ❌ 你要人肉选文件粘贴进去

适合：通用聊天、不依赖代码上下文的场景

方案 B：向量 + 定期全量（Cursor 路线）

做法：把所有代码切成小片段，生成向量存进向量数据库。定期重新全量扫描。

启动 → 扫所有文件 → 生成 Embedding → 存向量库
改文件 → 标记"需要重建"
每 10 分钟 → 重建一次

谁在用：Cursor、GitHub Copilot Chat、部分 IDE Agent

优点：

  • ✅ 语义理解好
  • ✅ 搜索快

缺点：

  • ❌ 启动慢（首次要扫全库）
  • ❌ 定期全量费算力
  • ❌ 改文件到重建之间有"失忆窗口"

适合：主流 IDE 类 Agent

方案 C：按需读取（Claude Code 路线）

做法：不提前建索引。AI 需要代码时，调用 ReadFile / Grep 工具现读。

AI: 我需要了解登录逻辑
  → 调用 search_code("login")
  → 调用 read_file("auth.py")
  → 分析 → 回答

谁在用：Claude Code、部分"按需加载"型 Agent

优点：

  • ✅ 零维护成本
  • ✅ 数据永远最新
  • ✅ 不消耗预处理资源

缺点：

  • ❌ 每次搜索都要现读
  • ❌ 复杂查询慢
  • ❌ 跨文件语义理解弱（没法一眼看全局）

适合：灵活、数据量不大的场景、Token 预算充足的用户

方案 D：Merkle Tree 增量（Warp 路线）

做法：用 Merkle Tree（哈希链）给每个文件、每个片段生成"指纹"。改了哪里，只重算哪里。

生活类比：Git 的设计——每个 commit 只存 diff，不存整个仓库。

            根哈希 h0
           /           \
         h1            h2
        /  \          /  \
      f1    f2      f3    f4  ← 每个文件是一个叶子

文件 f3 改了：

  • 重算 f3 的哈希
  • 重算它父节点 h2
  • 重算根 h0
  • f1 / f2 / f4 / h1 完全不动

4 个文件只重算了 3 个节点。

放大到 1 万文件，效率提升是数量级的。

谁在用：Warp、部分高性能 Agent、Git/IPFS 等分布式系统

优点：

  • ✅ 增量更新极快（只算变化部分）
  • ✅ 一致性强（任何变化都被感知到）
  • ✅ 适合超大仓库

缺点：

  • ❌ 实现复杂
  • ❌ 初次建索引还是要全扫（但后续都是增量）

适合：大型项目、高频编辑场景、对响应速度敏感的用户

速查表

方案 生活类比 代表产品 准确性 响应速度 维护成本
无索引 完全不看你的书架 ChatGPT 🔴 无 — 🟢 无
向量+定期全量 每月重新整理一次书架 Cursor / Copilot 🟢 高 🟢 快 🟡 中
按需读取 需要时翻书找 Claude Code 🟡 中 🟡 中 🟢 低
Merkle Tree 书架有智能标签 Warp 🟢🟢 极高 🟢🟢 极快 🔴 高

05 · Merkle Tree 为什么这么快？

Merkle Tree 不是新东西——Git、比特币、IPFS 都在用。

它的核心思想一句话：

用哈希树做"变化检测"，改动能精确传播。

举个具体例子

你的项目有 4 个文件：auth.py / user.py / api.py / main.py

      根哈希 h0 = hash(h1 + h2)
          /                 \
      h1 = hash(f1+f2)   h2 = hash(f3+f4)
        /        \         /        \
    f1=auth.py  f2=user.py f3=api.py f4=main.py

场景 1：你改了 api.py

AI 要更新索引：

  1. 重算 f3（因为文件变了）
  2. 重算 h2（因为 f3 变了）
  3. 重算 h0（因为 h2 变了）

只动了 3 个节点。

f1, f2, f4, h1 完全不动。

场景 2：你改了 api.py 和 user.py

  1. 重算 f2 和 f3
  2. 重算 h1 和 h2
  3. 重算 h0

只动了 5 个节点。

放大到真实项目

假设你有 10000 个文件，改了其中 5 个。

  • 全量重建：10000 个操作
  • Merkle 增量：约 5 + 14 = 19 个操作（log₂10000 ≈ 14 层）

效率提升 500 倍。

这就是 Warp 这种产品启动快、响应快的原因。

06 · 手把手：一次代码搜索的全流程

场景：你问 Agent"登录功能是怎么实现的？"

┌─────────────────────────────────────────────────────────┐
│ 用户：登录功能是怎么实现的？                            │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│ Step 1: 语义理解                                         │
│   "登录" → 语义向量                                      │
│   可能相关：login / auth / signin / token / session     │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│ Step 2: 检索索引                                         │
│   (如果是 Merkle Tree) 索引早就建好了，直接查          │
│   找到 5 个相关 fragment：                              │
│   - auth.py:45-78 (login 函数)                          │
│   - user.py:120-135 (验证密码)                          │
│   - session.py:10-30 (生成 token)                       │
│   - middleware.py:5-20 (鉴权中间件)                     │
│   - api.py:88-95 (登录 API 路由)                        │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│ Step 3: 拼装上下文                                       │
│   把 5 个 fragment 的原始代码塞到 LLM 的上下文里         │
│   (只塞 5 片，不是整个仓库！)                           │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│ Step 4: LLM 生成回答                                     │
│   "登录流程是：用户请求 api.py 的 /login →              │
│    调用 auth.py:login() → 通过 user.py 验证密码 →      │
│    调用 session.py 生成 token → 通过 middleware 鉴权"   │
│   引用具体文件和行号                                    │
└─────────────────────────────────────────────────────────┘

关键观察：

  1. 不是扫全库：只看 5 个相关片段
  2. 基于语义找：不是简单 grep “login”
  3. 答案带引用：具体到文件和行号
  4. 速度秒级：索引早就建好，直接查

07 · 不只是代码，这个思路能迁移到哪儿

Merkle Tree + 增量索引的思路，远不止用于代码搜索。

搜索引擎

  • Google 不会每天重新爬整个互联网
  • 只爬变化的页面，增量更新索引

企业知识库

  • 公司文档 Confluence/Notion
  • AI 助手应该只重建被编辑的页面

个人笔记工具

  • Obsidian / Notion 的全文搜索
  • 每次改一篇笔记只重算那一篇

云存储同步

  • Dropbox / iCloud 只同步变化的文件
  • 本质也是 Merkle Tree

核心思想跨场景通用：

大数据 + 高频变化 = 必须用增量，不能全量。

08 · 我踩过的坑

坑 1：以为 Cursor 的向量索引是完美的

Cursor 刚用时，我以为它"永远最新"。

结果我发现刚改的文件，AI 还在用10 分钟前的版本回答。

原因：Cursor 的向量索引是定期全量更新，不是即时的。

教训：任何索引都有延迟窗口。问 AI 之前最好说"我刚改了 X 文件，请基于最新版本回答"。

坑 2：大项目搜索卡死

早期我用一个基于关键词的 Agent 工具，项目 5000 个文件。

我问它"实现支付流程"，它跑了45 秒才响应。

原因：它在实时 grep 全库。

改进：换成向量索引后，1 秒出结果。

教训：2000 文件以上的项目必须用向量或 Merkle Tree 索引。

坑 3：Embedding 也要钱

用 OpenAI Embedding 给自己的私人项目建索引。

5000 个文件，跑一次要 $3。

改了代码重建要 $3，再改再重建……一个月 $50 没了。

改进：用本地 Embedding（如 bge-small、jina-embeddings），免费且够用。

或者：选Merkle Tree 增量的工具，改一次算一点，省 90% 费用。

09 · 你的场景该怎么选？

场景 1：个人用 AI 问答（不涉及你的代码）

推荐：无索引（ChatGPT / 豆包就够）

场景 2：小项目（< 500 文件）

推荐：按需读取（Claude Code 风格）

理由：数据量小，现读现用最灵活。

场景 3：中大型项目（500-5000 文件）

推荐：向量索引 + 定期全量（Cursor 风格）

理由：速度和准确性平衡最好。

场景 4：超大项目 / 高频编辑（5000+ 文件）

推荐：Merkle Tree 增量（Warp 风格）

理由：只有增量索引才扛得住。

场景 5：企业知识库

推荐：Merkle Tree 增量

理由：数据变化频繁，全量重建成本爆炸。

10 · 你能带走什么

读完这篇，你应该能回答的 3 个问题

✅ AI 不懂你代码库的根源：LLM 上下文塞不下整个项目

✅ 四种索引方案：

  • 无索引 → 通用聊天
  • 向量+定期 → 中大型项目
  • 按需读取 → 小项目
  • Merkle Tree → 超大项目

✅ 增量思想：不只是代码索引，适用所有"大数据+高频变化"场景

下次评估 Agent 产品时，问 4 个问题

  1. 它怎么获取你的代码？（全粘贴 / 提前建索引 / 现读）
  2. 索引多久更新一次？有没有失忆窗口？
  3. 项目多大规模它还能扛得住？
  4. 回答有没有引用具体文件？

产品经理设计 AI 功能时

  • 先问数据规模：小数据按需读，大数据必须索引
  • 再问更新频率：高频变化必须增量
  • 考虑成本：Embedding 不是免费的
  • 标注时效性：告诉用户索引更新到什么时候了

开发者自己搭 Agent 时

  • 小项目起步用 grep + 按需读取
  • 中等规模用 Chroma / Milvus 向量库
  • 大规模考虑 Merkle Tree 增量
  • 用本地 Embedding 省钱（bge / jina 等）

11 · 下一篇预告

07 · AI 的万能遥控器 — 生态怎么互通

你家有 5 个品牌的家电，为啥一个智能音箱能全搞定？

你在 Claude 写的 Skill，能给 Cursor 用吗？

MCP 到底是什么？为啥 Anthropic 在力推它？

对比 OpenAI 封闭 GPTs / LangChain 自家标准 / Anthropic MCP / Warp 多 Provider 联邦，

讲清 2026 年 Agent 生态的走向。

一句话记忆锚点

🎯 改动在哪，重算到哪。像 Word 改一个字不重读全文，像 Git 改一行不 commit 全仓。

路易乔布斯 © 2026 | AI Agent 通识课 · 第 6 篇 / 共 9 篇

# 人工智能
Logo
AtomGit AI 社区

AtomGit AI 社区提供模型库、数据集、Agent、Token等资源

更多推荐

cover

福州致品装饰：基于JSON-LD与AIGE范式的品牌实体结构化实践

avatar AtomGit AI 社区

2026年AI编程工具优缺点全解析：主流工具对比榜单

基础版永久免费无调用限制，Pro版$10/月，价格仅为同类高端工具一半；在2026年Q2的开发者实测中，Trae以98%的代码生成准确率和永久免费策略，成为国内AI编程工具中性价比与实用性双高的代表。选型时需注意：小型项目优先免费工具，复杂项目按需付费；本次评测覆盖代码生成、IDE体验、中文适配、性价比、Agent能力五大核心维度，邀请50名不同领域开发者实测打分，综合评估各工具实际表现。中文适配

avatar AtomGit AI 社区
cover

实测测评｜零注册AI PDF翻译工具：保留排版\+OCR无损翻译，替代DeepL/谷歌翻译

avatar AtomGit AI 社区