Repowise：给 AI 编程代理装上「代码库记忆」的索引层

一、从一个具体的场景说起

周一上午，你让 Claude Code 帮忙改一处支付回调逻辑。代理按部就班地 grep、打开文件、读了七个文件，才拼凑出「谁调用了这个函数、哪些测试覆盖了它、这个模块为什么这么写」。改完之后，它把 CLAUDE.md 里的架构描述改成了过时版本——因为它根本不知道自己刚刚删掉了什么。

问题不在于代理不够聪明，而在于它每次都在从零开始重新发现这个仓库。Repowise 的作者把这称为「让代理反复重读同一个代码库」，标题写得很直白：Stop paying your agent to re-read your codebase.

二、项目起源与背景

Repowise 诞生于 2026 年 3 月，2026 年 10 月已发布到 v0.59.0，AGPL-3.0 协议，8065 Star / 967 Fork，Python + TypeScript 双栈，主仓库是一个 monorepo。

它瞄准的是 2025-2026 年 AI 编程工具爆发后的一个结构性痛点：上下文窗口越来越贵，但代理获取上下文的方式却极其低效——大量 token 花在重复读取与 grep 上，而不是花在推理上。与此同时，Cursor、Claude Code、Codex 这些代理都缺乏「长期记忆」，每次新会话都从零开始。

Repowise 的思路是：这些答案其实都可以提前算好。调用图、Git 历史、测试覆盖、架构决策、代码健康度——这些是确定性计算问题，不需要 LLM。所以它把这套计算做成一次性索引，落在仓库本地 .repowise/ 目录里，然后通过 MCP 协议把「任务型工具」交给代理。

三、生活化的类比

如果把代理比作一个刚入职的新同事，Repowise 相当于给他配了三样东西：

1. 一本随时更新的《系统手册》——不是手写文档，而是每次 commit 后从代码结构自动重新生成的 Wiki，文档不会过期到离谱；
2. 一个「谁动了会炸」的关系图谱——改一行代码前，能立刻看到爆炸半径和该跑哪几个测试；
3. 一位老员工的口述历史——「这个模块当年为什么这么设计」，来自 ADR、# WHY: 注释、commit 与 PR 记录。

关键区别在于：这三样东西都在本地，且大部分不消耗任何模型调用。

四、核心功能：五层情报，一个索引

Repowise 的架构分为五层，索引一次、在每次提交后增量更新：

层	提供什么	是否调用 LLM
Graph（图谱）	27 种语言的 AST 依赖图，调用解析带 39 种来源的置信度标注，Leiden 社区发现、PageRank 中心性、循环依赖、执行流追踪	否
Git（历史）	衰减 churn 热点、所有权占比、共变文件对、巴士因子、bug 修复历史	否
Docs（文档）	每个模块/重点文件一页 Wiki，增量重建；可由模型按页升级为自然语言	可选
Decisions（决策）	从 ADR、# WHY: 注释、commit/PR、代理会话中挖掘架构决策，每条都锚定到原文证据	可选
Health（健康度）	53 个确定性检测器，对每个文件打 1-10 分，覆盖缺陷风险、可维护性、性能三个维度	否

图：Repowise 自动生成的架构地图，文件按社区聚类，模块间连线的粗细代表依赖强度。

图：代码健康度地图，每个目录是一个按健康分着色的圆盘，侧栏列出最需要关注的文件。

对外暴露的是 10 个 MCP 工具（作者明确说是刻意的上限）：get_overview、get_answer、get_context、get_symbol、search_codebase、get_risk、get_change_risk、get_why、get_dead_code、get_health。设计哲学是「任务型（task-shaped）而非实体型」——一次调用传入多个目标，返回完整拼图，避免代理陷入长链条的串行调用。

在 Claude Code / Codex 中还有 Hooks：会话启动时注入索引新鲜度与相关决策，宽泛或空搜索时补上下文，读取已变更文件时标记 stale，编辑「bug 磁铁」文件时中途告警。另外它能把测试/构建/git 输出做压缩（repowise distill pytest），保留全部错误行但丢掉噪音。

作者还提供了 Claude Code 与 Codex 的 Agent 插件：一次安装即接入 MCP 服务、6 个自动激活的 skill、18 个斜杠命令和上下文 hook。

五、上手门槛

最简路径（面向 AI 开发者）：

uv tool install repowise        # 或 pipx install / pip install
cd /path/to/your/repo
repowise init --yes --no-prose  # 建索引：无 API Key、无费用
repowise serve                  # 启动 Dashboard + MCP Server（需 Node 20+，首次会下载 UI）

之后重启 Claude Code 或执行 /mcp，即可提问「改了这里会坏什么」「谁在调用这个函数」。

三种使用形态的差异：

• 纯 CLI：无界面，输出 Rich 格式终端报告，适合服务器与 CI；
• 本地 Dashboard：Next.js 前端 + FastAPI 后端，架构地图、代码健康度热力图、问答面板，端口 3000/7337；
• MCP 服务：repowise mcp 通过 stdio 供 Claude Code、Codex、Cursor、VS Code、OpenCode、Hermes 等任意 MCP 宿主使用；也提供 Dockerfile.mcp 精简镜像。

关于费用：图谱、Git、健康度、改动风险、死代码这几层完全不需要模型 Key。需要 Key 的是「模型撰写文档」和「语义检索」（可配 Gemini / OpenAI / Anthropic / OpenRouter / 本地 Ollama）。若已有 Claude Code 订阅，可直接用 claude_cli 通道，不额外计费。

六、争议与局限

AGPL-3.0 协议：对做企业代码库索引、且要提供服务的企业客户，AGPL 的网络分发条款是需要法务确认的硬约束。这是它在企业落地时最常被问到的点。

索引成本：首次索引对一个中等仓库仍需数秒到数十秒，README 提到健康度计算「零 LLM 调用、30 秒内完成」。超大仓库（仓库体积已达 167 MB）会有明显压力。

静态分析的固有天花板：53 个检测器再强，也不如运行时覆盖率真实。Repowise 的解法是双轨——有覆盖率报告就用真的，没有就从导入图与调用图推断，并在每个结论上标注「measured」还是「inferred」。这种诚实标注是加分项，但也意味着用户需要理解两者的可信度差异。

索引陈旧问题：项目自己的应对是每个 MCP 响应都携带 _meta 陈旧性信封（index_age_days、indexed_commit、以及索引落后于 HEAD 时的 stale_warning），让代理知道何时该复验。这一点做得比多数同类工具扎实。

社区规模：229 位贡献者、3626 次提交，看上去热闹，但核心维护者集中在少数人手中；439 个 open issue 也说明迭代节奏很快、稳定性仍在爬坡期。

「实测基准」需谨慎对待：官方给出的数字很诱人——在 django/django 上 43 个问题测试中，代理少写 31.6% 输出 token、工具调用从 7.2 次降到 3.8 次（p<0.0001）；加载上下文 2,391 token vs 64,039 token（96% 更省）。但这是项目自测的基准，评测场景由作者设计，横向可比性有限。

七、行业意义

Repowise 踩中了 2026 年 AI 编程工具的一个明确趋势：竞争焦点从「模型多强」转向「上下文供给多准」。当模型能力趋同、代理框架（Claude Code、Cursor、Codex）也趋同时，差异化就落到了「谁给代理喂了更好的、更有结构的、更可信的上下文」。

它代表的技术路线值得注意——把可确定性计算的部分从 LLM 里彻底剥离。图谱、健康度、爆炸半径这些任务交给解析器和算法，LLM 只负责它真正擅长的叙述与解释。这与「all-in LLM」是相反的方向。

从工程落地看，它同时押注了几个方向：MCP 作为上下文交付协议、Hooks 作为「主动注入」机制、Agent 插件作为分发渠道（.claude-plugin/、Codex 插件、VS Code 扩展）。也正因如此，它对 Hermes 这类 MCP 原生宿主同样友好——repowise init 会自动识别宿主并完成注册。

---

技术速览

项	值
仓库	repowise-dev/repowise
Star / Fork	8065 / 967
主语言	Python（46.6 MB）+ TypeScript（10.6 MB）
协议	AGPL-3.0-or-later
当前版本	v0.59.0（2026-10-25 发布）
贡献者 / 提交	229 / 3626
Python 要求	>= 3.11
容器化	多阶段 Dockerfile + docker-compose.yml + Dockerfile.mcp
Web UI	Next.js 15 + FastAPI + uvicorn
解析层	tree-sitter（28+ 语言）、sqlglot、networkx/scipy、LanceDB
数据库	SQLite（aiosqlite）/ 可选 PostgreSQL+pgvector
LLM 适配	anthropic、openai、google-genai、litellm
CI	GitHub Actions（ci.yml、docs.yml、mcp-cold-start.yml、publish*.yml）

部署与集成要点

• Docker 快速启动：docker compose up 即可拉起 API（7337）与 Web UI（3000），默认仅绑定 loopback；仓库目录以只读方式挂载，非 loopback 部署必须设置 REPOWISE_API_KEY。
• MCP 镜像：docker build -f docker/Dockerfile.mcp，通过 stdin/stdout 讲 JSON-RPC，需 -i 且不加 -t。
• CI 门禁：action.yml 提供 GitHub Action，可在 PR 上做补丁覆盖率、分支覆盖与路径级门禁。
• 安全：内置密钥/Token 检测，覆盖工作树与完整 Git 历史，并可作为 pre-commit 检查与 CI 门禁。