repowise：给仓库建本地索引，让 Agent 的工具调用砍掉近一半

背景：Agent 正在用 token 重新"读"仓库

用 Claude Code、Codex、Cursor 在真实代码库里干活的人，大概都见过这样的场景：你让 Agent 改一个看起来不大的需求，它先 grep 一遍全仓，再逐个打开文件翻依赖关系，把同一个结论在每一轮对话里重新推导一遍，最后的 token 账单里，"探索阶段"占了大头。

问题的本质不在模型笨，而在仓库的结构性知识没有被持久化：谁调用了谁、为什么这样设计、哪些文件最近总在修 bug——这些信息每次都要 Agent 现场重新发现。repowise 的思路就是把"理解仓库"这件事提前做一次：建一次本地索引，Agent 和开发者都能直接查询，不用反复翻整个仓库。

repowise 是什么

repowise（repowise-dev/repowise，GitHub 上约 7100 star，2026 年 3 月创建，AGPL-3.0 或商业授权）把代码的依赖图、git 历史、测试、文档、架构决策一次性建成可查询的本地索引，然后从三个入口交付：给人看的本地 dashboard 和 VS Code 插件、给 Agent 的 MCP 服务、以及 PR 阶段的风险分析。

它的口号很直白：Understand your codebase without paying your agent to rediscover it.（理解你的代码库，别再为 Agent 的重复探索买单。）

索引构建完成后，默认全程本地运行、不需要 API Key——建图、算风险、查健康、找死代码、做 PR 评审都零 LLM 调用，只有可选的文档散文生成才需要模型。

十个按任务设计的 MCP 工具

repowise 给 Claude Code、Codex、Cursor 等提供 10 个 MCP 工具。它的设计和传统代码工具不一样：大多数工具围绕数据实体组织（一个文件、一个符号），这逼着 Agent 做长串的顺序调用；而 repowise 的工具围绕任务组织，一次调用可以带多个目标，直接返回完整上下文。

README 里提到的几个工具能看出这种风格：

• get_overview —— 一句话问清"这个仓库是干什么的"
• get_context —— 取某个提交或文件的完整上下文（实测 393 token 替代 13984 token 的检索载荷）
• get_why —— 追问"为什么这段代码是这么写的"，答案带到架构决策的引用

更进一步，它还提供可选的 hooks，把上下文在最关键的时刻主动推进会话：当 Agent 编辑被某条架构决策覆盖的文件、当它触碰到近期 bug 修复密集的文件、当会话刚开始需要一份简报。它甚至能从真实索引里生成你的 CLAUDE.md 和 AGENTS.md，让不支持 MCP 的 Agent 也能带着信息上场。

为什么"按任务组织"这么重要？可以做个简单对比：

传统方式下，Agent 问"改这个文件会影响谁"，要先查定义、再查引用、再翻测试，任何一步返回过多噪声都会污染后续推理。repowise 把这些探索提前算好，Agent 拿到的就是答案本身，而不是找答案的原材料。

合并前就知道风险：0 到 10 的变更评分

这是我觉得最工程化的部分。repowise risk main..HEAD 会对一次变更打出 0 到 10 的风险分，分数按仓库自己近期的提交分布排名，而不是拍脑袋的阈值。

# 对比分支变更的风险
repowise risk main..HEAD

在 PR 模式下，它返回的是指令而非感觉：may_break（可能破坏什么）、missing_cochanges（以前总一起改、这次可能漏掉的文件）、missing_tests（缺失的测试）、tests_to_run（这次该跑哪些测试）。配套的 PR bot 是免费的，会在 PR 里留下带引用页的评论。

bug 历史分析也做得很实在：先把 doc、test、config 类提交过滤掉，让"修复次数"真正代表缺陷；一个文件如果近期被反复修 bug，编辑它时会被直接标记为"bug 磁石"。

还有一个被低估的能力：不用覆盖率报告，就能知道哪些测试覆盖了这个文件。它从图和测试的调用关系里推断出"这个 diff 实际会 exercise 哪些测试"，让你只跑真正相关的测试，而不是全量跑一遍碰运气。对于测试动辄十几分钟的大型仓库，这个能力省下来的时间可能比 token 还值钱。

不止一个仓库：estate 级的理解

repowise 还有个 Workspace 概念：把多个仓库组成一个工作区，用同一个 MCP 端点查询。比如前后端分离的项目，可以匹配前后端 contract、发现 breaking 的 provider、画出下游服务的依赖地图、对所有仓库执行统一的架构规则。对同时维护 5、6 个仓库的团队（比如微服务），这比"每个仓库各建各的索引"要实用得多。

代码健康：53 个确定性检测器

repowise 内置 53 个确定性检测器（据官方 README，2026 年 10 月），把缺陷风险、可维护性、性能三个维度分开打分，找出最容易出问题的文件，并且给出可以直接丢给 Agent 执行的重构方案——从"发现问题"到"修复计划"形成闭环，而不是甩给你一份静态报告。

支撑这一切的是底层图：26 种语言的 AST 解析，带置信度的调用关系解析，还能发现循环依赖和模块社群。

实测数据：敢公开样本、方法和输掉的比较行

很多 AI 工具的 benchmark 只晒赢的数字，repowise 的做法值得单独拎出来说：每个 benchmark 都公开样本、方法、局限，以及输掉的比较行。README 首页的数据（2026 年 10 月核实）：

• 43 个问题 × django/django：Agent 的工具调用从 7.2 次降到 3.8 次，Agent 自身输出减少 31.6%（p<0.0001）
• 上下文载荷：一次 get_context 检索 393 token 替代 13984 token，小 97.2%——作者明确声明这是单次检索载荷，不是总 token 节省，这种诚实很难得
• 缺陷检出：同等行数预算下是基线的 2.3 倍（2770 个文件，p=0.003）
• 图准确度：5 个工具、37853 条 oracle 边的对比中，在覆盖率相当的前提下精度领先

数字漂亮，但更重要的是方法论：样本量、p 值、局限都写在明处，读者可以自己判断这个 -31.6% 在你的仓库上能复现几成。

五分钟上手

pip install repowise

cd /path/to/your/repo

repowise init --no-prose -y   # 建图、git 历史、健康、决策层；不用 LLM，不花钱
repowise serve                # 本地 dashboard + MCP server

init 会自动把 Claude Code 接上线。想压缩 Agent 读命令输出的噪声，还有个顺手的小工具：

repowise distill pytest       # token 少 61%，11 条失败行全部保留
repowise distill git log -50  # token 少 89%

隐私方面：索引全部留在本地（.repowise/ 目录），免费自托管，AGPL-3.0 或商业授权二选一。

延伸：和 refactoring-ui-skill 的对照

之前写过一篇《当 Claude 读完〈Refactoring UI〉》，讲的是 gnurio 的 refactoring-ui-skill——把 UI 审美经验固化成 Skill，约束 AI 的"审美输出"。repowise 做的是对称的另一面：约束 AI 的"代码理解"。

两个项目其实在回答同一个问题：怎么把专家经验变成可复用的工程资产，而不是每次都靠 prompt 重新描述一遍？一个管输出的美学，一个管输入的理解，合在一起就是"让 Agent 在正确的上下文里，做正确的事"。

结论

repowise 适合三类人：经常让 Agent 在大型单体或多仓库上干活的团队、对 token 账单敏感的个人开发者、以及想在合并前就量化变更风险的 reviewer。它的核心赌注是：仓库的结构性知识值得被提前计算一次，而不是让每个 Agent 会话重复支付探索成本。

需要注意三点：一是 AGPL-3.0 许可，企业内部分发或二次开发前先过一遍合规；二是指数是快照，需要随仓库演进持续更新（它支持增量更新和自动同步）；三是它解决的是"理解"问题，写代码的最终质量还是取决于模型本身和你的任务描述——索引能让 Agent 少走弯路，但走不走对路，还得看方向盘在谁手里。

当 Agent 越来越多地参与真实代码库开发，"先索引、后提问"很可能成为标配动作。repowise 至少证明了一件事：这条路不仅走得通，还能量化出 31.6% 的账单差异。