← 返回主页

Agent 的代码理解基建（一）：别让 AI 花你的 token 重新发现你的代码库

"让 AI 读得懂你的仓库，比给它换个更大的模型实在。"——这句话我用两个仓库、一台没有 GPU 的 MacBook 验证过了。

一个所有 AI 编程用户都见过的场面

让 Claude Code 改一处半年前写的老代码，它的开场永远是："我先看看项目结构"——然后 ls、grep、cat 一路翻下去，输出里全是"我再看看这个文件"。每一步都在烧 token，每一分钟都在等它重新发现你早就知道的事。

这不是模型的错。模型每次会话都是失忆的，它对代码库的全部理解都要现场重建。重建的成本，就是你账单上那行"上下文 token"。

这个系列讲我做的事：把"现场重建"变成"提前索引 + 随手可查"。第一篇从一个让我立刻装上的开源项目说起。

Repowise：索引一次，AI 查得到

Repowise（7.6k★，今年 3 月建仓）做的事一句话说完：在你本机把代码结构、调用图、Git 历史、测试、文档提前索引好，通过 MCP 暴露给 AI。官方在 Django 的 43 个 issue 上做过配对测试——同样的活，agent 输出量少 31.6%。

最打动我的不是省 token，是这句：图、风险、健康度、死代码全部是确定性计算，一次大模型调用都没有，不用配任何 API key。装完就能用，代码不出门。

三分钟跑起来

uv tool install repowise
cd /path/to/你的仓库
repowise init --yes --no-prose    # 建索引，无 key
repowise serve                    # 本地仪表盘 + MCP server

init 连 Claude Code 的 MCP 配置都自动写好（.repowise/mcp.json）。四个马上有用的命令：health（53 个检测器的健康分）、dead-code（死代码）、ask（带引用的仓库问答）、context（改一个文件前看"分诊卡"：谁调用它、历史 churn）。

拿自己的仓库实测

我拿两个自己的 Kotlin 仓库开了刀（v0.56.0，Apple Silicon 本机）：

仓库	健康分	发现
t1-replay（7 文件）	9.97/10	全文件 excellent；TradingEngine.kt 圈复杂度 7，是全仓最"重"的逻辑——符合事实
kline-vision（8 文件）	9.82/10	Worst 正确锁定 ChartRenderer.kt（手绘 Java2D 渲染器）；死代码检测给出 1 条 40% 置信的保守误报

那条误报值得展开：VisionTools.kt 是 MCP 工具入口，靠运行时注册被调用，静态调用图到不了它，于是被标成"no importers"。但工具自己只给了 40% 置信 + "Ready? ✗"——判断权留给人。这个"知道自己不确定"的设计，比一个自信的误报高级得多。

诚实部门：Kotlin 用户要注意

官方 0.976–0.995 的调用图精度是 Go 和 TypeScript 的基准；Kotlin 走的是通用分析路线。结论：把它当辅助信号，别当真理。对我这个用途（改老代码前看影响面、健康分进 CI）完全够。

为什么说这是"基建"，而不是又一个工具

因为我已经写过它的反面。上个月做 harness-engineering 时，我给 Agent 运行时定了五个组件：OODA 循环、沙箱接缝、自进化技能、任务 DAG、预算护栏。当时漏了一层——Agent 的"知识获取"方式。grep 是物理扫描，RAG 是语义近似，而索引是预先算好的确定性事实：调用图对着编译器校验过（官方数据 0.976–0.995），健康分由 53 个检测器算出，死代码带着置信度。

三层对比：

方式	成本	确定性	适合
grep + 读文件	每次会话现场重建，token 大户	高（所见即所得）	小仓库、一次性任务
RAG / 嵌入检索	索引一次 + 每次查询	近似（语义相似≠真的相关）	文档、非结构化文本
结构化索引	索引一次，查询几乎免费	确定性计算 + 置信度标注	代码这种有严格结构的东西

代码是有编译器和解释器背书的严格结构——对结构化数据用确定性工具，把 LLM 留给它真正擅长的事。这也是 Repowise 自己的设计哲学，我举双手赞成。

接入我的工作流

// .repowise/mcp.json（init 自动生成）
{ "mcpServers": { "repowise": {
      "command": "repowise",
      "args": ["mcp", "/绝对路径/仓库", "--transport", "stdio"] } } }

我的日常变化：

• 改 kline 系列仓库前：repowise health 看分 → context 文件 看影响面 → 再开工
• 提交后：repowise update 刷新索引
• 健康分进 CI：零依赖命令，分数掉了就是代码在腐化

完整中文指南（含 AGPL 合规说明）我放在了 bayshier/repowise-zh。

下一篇预告

索引解决了"AI 知道代码长什么样"，但没解决"AI 知道自己该守什么规矩"。第二篇讲我用 Kotlin 写的 Agent Harness 五组件——以及实测翻车的 macOS 26 沙箱讣告：Agent 的代码理解基建（二）：Harness 五组件与一场沙箱葬礼。第三篇讲让技能自己进化时，git 为什么是所有人都缺的那块拼图。

（系列索引：repowise-zh 指南 · harness-engineering · android-agent-skills）