repowise-dev/repowise · 上手攻略

• 仓库：repowise-dev/repowise
• 链接：https://github.com/repowise-dev/repowise （官网 https://repowise.dev · PyPI https://pypi.org/project/repowise/ · 文档 https://docs.repowise.dev）
• 分类：AI Agent 工具链 / 代码库情报（MCP 服务 + 本地索引）
• 作者：spark
• 更新：2026-09-30

§0 速览

Repowise 是「代码库情报」工具：把仓库一次性索引成结构化数据（依赖图、git 历史、测试覆盖、文档、决策记录），再通过 MCP（Model Context Protocol）把这份索引喂给 Claude Code / Codex / Cursor / OpenCode 等 AI Agent。它本质上解决的是「Agent 每接到一个任务都要从零 grep/读/忘」的问题——把勘探成本前置到一次性的索引构建。

读完这篇你能：①安装并对自家仓库跑一次零 key 的本地索引；②让 Claude Code 通过 MCP 看到这份索引；③用 repowise health / repowise risk / repowise dead-code 三个命令直接拿到可操作的代码健康结论。

⚠️ 诚实标注（不夸大护城河）：以下三处局限需先认清—— 1. 基准数字皆为官方自测：31.6% token 节省、3.8 vs 7.2 tool calls、2.3× defect 检出、p<0.0001 等数字来自 repowise 自家 BENCHMARKS.md，n=43（django/django 单仓）+ 21 仓 2826 文件验证集，并非第三方独立审计；同赛道（如 Sentra、CodeGraph 1.5.0、Graphify 0.9.31、Serena 1.6.2）虽被列为对手，但实验设计与取样规则由 repo 主导。 2. 官网标注 v0.52.0 但 PyPI #history 端点截至本次抓取仅显示至 0.1.2（2026-06-03 起的版本被折叠或端点抓取不全）。社区判断「最新版」应以官网「See what changed」顶部 banner 为准，PyPI 同步可能存在滞后；本文涉及命令以官方文档为准。 3. read-time 索引而非 write-time 记忆：索引在 commit 落库后增量刷新，但不记录「某模式何时起有效 / 何时起失效」的双时态（bi-temporal）信息。MCP 响应里带的「staleness envelope」只是新鲜度警告，不是历史溯源能力。如果你的工作流依赖「为什么这个约束以前成立现在不成立」，需要外接决策日志。

§1 是什么 / 解决什么问题

1.1 它是什么

一个用 Python 写的 CLI + MCP 服务器 + 本地 dashboard 套件。架构上是「一次性建索引、增量更新、按任务暴露 MCP 工具」，核心卖点是：

• 零 LLM 调用也能跑：graph / risk / health / tests / dead-code / PR review 这六层全是确定性算法（基于 AST 解析 + git 历史 + 图论），只在「写 wiki 散文」和「挖掘决策」（comment archaeology）才需要 model provider。
• AGPL-3.0 开源 / 商业双许可：自托管免费，跑在你自己机器上；企业版加了 SLA、安全控制、商业授权。
• 10 个 MCP 工具：围绕「任务」而非「实体」设计——一次性传入多个目标（文件 + symbol + 决策 + 风险），少跑多拿，而不是传统 IDE 那种「每个工具只取一个文件」的串联模式。

1.2 解决什么问题

Agent 开发场景里反复出现的三个痛点：

1. 重复勘探：每个任务开始，agent 都要 grep / read / 重新理解模块边界。在他们自家测试里，43 道 django 题目平均需要 7.2 次工具调用，引入 Repowise 后降到 3.8 次。
2. 上下文膨胀：一次性把一个 commit 的 context 喂给 agent 时，传统做法是贴 commit message + diff + 周边文件 = 13,984 tokens；走 get_context 路径只花 393 tokens（97.2% 节省）。
3. 变更盲改：合并前不知道改这一处会触发什么——「它会破坏哪些调用方 / 哪些测试应该跑 / 哪些同事正在同一文件上改」。Repowise 把这些做成 PR 上的结构化 directive（may_break / missing_cochanges / missing_tests / tests_to_run），不是「读 vibe」的 LLM 判断。

§2 快速安装

2.1 前置条件

• Python 3.11+（必填，老版本 3.10 直接报语法错）
• Git（用于读 git 历史层）
• 可选：LLM provider API key（Anthropic / OpenAI / Gemini / LiteLLM 任一，但只有写 wiki 散文 / 决策挖掘才用得到，首次体验可以完全不要）

2.2 安装命令

# 标准安装（Linux / macOS）
pip install repowise

# Windows 上 pip 可能被锁，用模块调用方式
python -m pip install repowise

# 验证
repowise --version

安装即把 Anthropic / OpenAI / Gemini / LiteLLM 全部 SDK 一并带进来，无需 extras_require。模型选型推到「index time」决定，随时可换。

§3 核心用法

3.1 三步上手（零 key、零网络）

cd /path/to/your-repo

# 第一次推荐「不要 prose」模式：纯结构化 wiki，零 LLM 调用、零 spend
repowise init --no-prose -y

# 启动 dashboard 与 MCP server
repowise serve

init 阶段会发生的事（按官方 QUICKSTART 描述）： - 把仓库每个文件解析到 AST（声称 26 种语言） - 跑依赖图 + git 历史 + 文档漂移检查 + dead-code 扫描 + 51 条 code-health 检测器 - 渲染 file / symbol / layer / cycle 页面、架构图、仓库概览、API 页面 - 生成 .mcp.json（除非传 --no-editor-setup 或 REPOWISE_SKIP_EDITOR_SETUP=1） - 注册到 Claude Code 的 ~/.claude/settings.json

最后会弹一个费用预估，确认才花 API 钱；不确认 = 走 --no-prose 默认行为。

3.2 直接看的几个命令

# 健康分最低的那些文件 + 为什么（包含与 git bug-fix 历史自检的对比）
repowise health

# 死代码：什么已经没人引用了
repowise dead-code

# 改动的风险评分 0–10（含 may_break / missing_cochanges / missing_tests / tests_to_run 指令）
repowise risk main..HEAD
repowise risk HEAD~5..HEAD

# shell 输出蒸馏：把 pytest 输出从噪声压缩成「错误优先」的紧凑块
repowise distill pytest
repowise distill git log -50
repowise saved   # 本次会话累计节省多少 tokens / 美元

repowise distill 的特色：所有省略都留一个内联 [repowise#<ref>] 标记，反向用 repowise expand <ref> 还原完整输出。Agent 永远可以「按需回放」而不需要重跑命令。

3.3 接入各类 Agent

Claude Code（默认 init 已配好；如跳过 setup 可重做）：

repowise agents add --target=claude-code
# 或手动
claude mcp add repowise -- repowise mcp

.mcp.json 手工版长这样（可提交到仓库给团队共用）：

{ "mcpServers": { "repowise": { "command": "repowise", "args": ["mcp"] } } }

Codex CLI：

codex mcp add repowise -- repowise mcp
# 或写进 ~/.codex/config.toml

[mcp_servers.repowise]
command = "repowise"
args = ["mcp"]

Cursor：走 repowise agents add --target=cursor，写到 .cursor/mcp.json + .cursor/rules/repowise.mdc。⚠️ 注意 Cursor 不读 .vscode/mcp.json，二者要分别配。

OpenCode：

repowise agents add --target=opencode              # 仓库 + 本机双写
repowise agents add --target=opencode --scope=project  # 仅仓库

Hermes / Cline / Windsurf：都走 repowise agents add --target=<name> 或 repowise agents print-config <name> 拿到手填入口。Hermes 在 Windows 上路径是 %LOCALAPPDATA%\hermes\config.yaml，其他平台是 ~/.hermes/config.yaml 或 $HERMES_HOME/config.yaml。

3.4 Claude Code 的 plugin 模式

init 只写 .mcp.json、不写 hooks / slash commands。要装插件得显式：

/plugin marketplace add repowise-dev/repowise
/plugin install repowise@repowise

这条会装 hooks（在你编辑某个被某条决策覆盖的文件时，把那条决策自动塞进 session），所以比裸 init 体验强一档。

3.5 PR Bot

把 Repowise 装到 GitHub App 上，每条 PR 自动跑 risk + tests_to_run + bug-magnet 标记，零 LLM 调用。CI 场景不需要给 agent 充值。

§4 典型适用场景

1. 接手陌生大型仓库：传统方式 = 先读 README、再翻 architecture doc、然后逐模块 grep。走 Repowise = 让 agent 直接问 get_overview / get_architecture / get_why。
2. 改老旧高风险代码前评估：先 repowise risk HEAD~5..HEAD，看是否被标 may_break 或 missing_tests，再决定要不要拆 commit。
3. CI 阶段只跑相关测试：用 repowise overlap + LCOV / Cobertura / Clover / JaCoCo / Go coverprofile 的「实测覆盖」叠加调用图「图推断覆盖」，比单跑 pytest 慢的部分大幅缩短。
4. 代码健康治理：51 条确定性检测器跨 defect risk / maintainability / performance 三维给 1–10 分，输出可执行的 refactor plan，agent 拿着就能干。
5. 跨仓库视图（Workspaces）：跨 backend ↔ frontend 合约抓 breaking provider、看下游服务映射、在统一 MCP 入口查所有仓库。
6. agent 决策可追溯：开启 repowise decision source set session --on 后，会读你的 agent transcript，从中挖出反复出现的纠正（「用 shared HTTP client，不要 raw requests」），沉淀成「tracked decisions」，下一次执行同一类任务时自动推回。transcript 永不出本机。

§5 坑与注意（6 条具体坑，每坑 = 现象 / 影响 / 修复）

坑 1：init 默认会问问题，CI 环境下卡死

• 现象：repowise init 在 TTY 下进入交互，问「要不要写 prose / 用哪个 provider / 多少预算」。在 CI / cron / agent 自动化里没有 stdin，会卡住。
• 影响：CI 永远 hang 或超时。
• 修复：脚本里强制传 --yes --no-prose（零 spend 路径）或 --yes --prose（带 API key、预算预批路径）。

坑 2：.mcp.json 被默认写进工作树，团队 commit 冲突

• 现象：init 会写 .mcp.json 到仓库根（init 阶段），并注册到 ~/.claude/settings.json。如果团队成员有的用 --no-prose、有的带 prose，init 跑出来内容可能不一致。
• 影响：PR 上反复 merge conflict；或者某些人 init 完看到「mcp」配置但实际 server 没起。
• 修复：在仓库 README / CONTRIBUTING 里写明团队固定配置，统一传 --yes；或者用 --no-editor-setup 让 init 不写 .mcp.json，各自机器上手动配。.repowise/mcp.json 是个例外——它无论怎么走 init 都会被写，因为是 repowise mcp . 命令的来源；这是 by-design。

坑 3：Cursor 不读 .vscode/mcp.json，要走 .cursor/mcp.json

• 现象：从 VS Code 阵营迁移过来的用户惯性会建 .vscode/mcp.json，但 Cursor 读 .cursor/mcp.json，结果 server 起不来。
• 影响：Cursor 内看不到 repowise 工具。
• 修复：直接 repowise agents add --target=cursor，不要手动复制粘贴 mcp 配置到 .vscode/。

坑 4：OpenCode 配置有注释时 init 拒绝重写

• 现象：OpenCode 的 opencode.jsonc 允许注释；如果你的 opencode.json 已经带注释，repowise 不会重写它，会退化成「打印一段 JSON 让你手动 paste」。
• 影响：自动化装不上。
• 修复：要么把 opencode.jsonc 改成严格 JSON（去掉注释），要么跑 repowise agents print-config opencode 拿出手填片段。

坑 5：Hermes 上 platform_toolsets.cli 配错变限制变宽松

• 现象：Hermes 默认把每个启用的 MCP server 都暴露给 CLI；只有当 platform_toolsets.cli 已经是个 allowlist（列了具体名字）时，新加的 server 才会被加进去。repowise 不会把一个原本宽松（无 list）的配置自动转成限制性（带 list）。
• 影响：要么「加不上」，要么「所有人突然发现 CLI 多了一个 server」。两个方向都不直观。
• 修复：先确认你 ~/.hermes/config.yaml 里 platform_toolsets.cli 当前是 allowlist 还是 permissive。allowlist 模式下放心 repowise agents add --target=hermes，permissive 模式下要么手动维护列表，要么别用 hermes CLI 这一面。

坑 6：测试覆盖推断在「没 coverage 报告」时退化成「调用图推断」，并自承认会双向失败

• 现象：在没有 LCOV / Cobertura / Clover / JaCoCo / Go coverprofile 的项目里，repowise 改用「test file imports source file → 视为可达」的方式推断测试覆盖。官方自承认这种推断「双向都可能错」：①真实可达的边被遗漏；②形式上 import 但实际不覆盖。
• 影响：repowise health 给出的「tests_to_run」可能在你的仓库上不那么准。
• 修复：CI 里跑测试时同时生成 coverage 报告并 ingest，repowise 会切换到「实测覆盖 + 调用图推断」双源；纯图推断当作兜底，不要当真相。README 自举例：repowise-dev/repowise 这个仓库自己「6 个最差 bug-magnet 文件里有 5 个没有任何测试 import」，验证的就是这层风险。

坑 7（额外补刀）：指数膨胀的 graph 文件夹

• 现象：本地索引落在 .repowise/，git 仓库几 MB ~ 几百 MB 时索引轻松几十 MB 上百 MB。
• 影响：意外 git add . 把 .repowise/ 提交上去，仓库暴胀。
• 修复：第一件事就是 .gitignore 里加 .repowise/。.repowise/mcp.json 想团队共享就单独 commit，其余一律不入仓。

§6 与同类对比

按官方 BENCHMARKS.md 2026 年 8 月 081a59fa commit 的自测：

⚠️ 同行评分同样来自 repowise 自家 benchmark，未经独立审计。

第三方观察（Sentra 2026 评测）的视角更冷静： - 优势：token discipline 极强（同一 task 96% 节省），健康分「在 21 个开源仓上 2.3× 多挖出缺陷」。 - 边界：「read-time index 不是 write-time memory layer」，没有 bi-temporal provenance，staleness envelope 只是新鲜度警告。

Moxie Docs 自家对比里把 Repowise 定位成「自托管优先 / 完整 daemon」，而 Moxie 自己定位成「零基础设施纯 hosted」。两者目标用户交集不大：你要「代码 + git + 测试 + 决策」全部索引 → Repowise；你只想要「自动写文档 + docs 站」→ Moxie。

§7 一句话推荐结论

Repowise 适合「日常用 Claude Code / Codex / Cursor 干中型以上（≥几千文件）Python 或多语言仓库，且愿意在本地维护一个 SQLite + 向量索引」的个人 / 小团队；不适合「只想跑一次 hosted 服务就拿答案」的人，也不适合需要 bi-temporal 决策溯源的重合规场景。

要不要装？看这三条 yes/no： 1. 你的主力 Agent 是 Claude Code / Codex / Cursor / OpenCode / Hermes 之一？→ yes 才值得装 2. 你一周至少改 1 个陌生模块、要先问「它会被谁调 / 改了会坏什么」？→ yes 才回本 3. 你能接受 pip install 一个 AGPL-3.0 工具并跑一个本地 daemon（不传数据出本机）？→ yes 才合规

三条都 yes → 直接 pip install repowise && repowise init --no-prose -y 体验 5 分钟，零成本。

§8 元信息与溯源

• 数据来源： 1. GitHub 仓库 README（fetched 2026-09-30）：https://github.com/repowise-dev/repowise 2. 官方 QUICKSTART.md（fetched 2026-09-30）：https://github.com/repowise-dev/repowise/blob/main/docs/start/QUICKSTART.md 3. 官网首页（tavily_extract 2026-09-30）：https://repowise.dev（标注 v0.52.0 当前） 4. PyPI 历史（tavily_extract 2026-09-30）：https://pypi.org/project/repowise/#history（端点截至本次抓取显示 0.1.2 等旧版本，更高版本号折叠不可见） 5. 第三方观察 Sentra 2026 评测（web_search 2026-09-30）：https://www.sentra.app/articles/best-codebase-context-memory-tools
• 不确定 / 待复核：
• 最新 PyPI 版本号（官网首页 banner 写 v0.52.0，但 PyPI #history 端点抓取结果最高只到 0.1.2 显式列出，2026-06-03 之后版本折叠；本文以官网 banner 为准，建议读者自行 pip index versions repowise 复核）
• 基准数字（31.6% / 3.8 vs 7.2 / 2.3× / p<0.0001 等）皆为官方自测，未见第三方独立审计
• 跨平台兼容性：QUICKSTART 未明确 Windows 上 pip install repowise 失败时的 fallback 路径，本文按 python -m pip install repowise 给出
• 命令 / 版本核对：所有 repowise 子命令（init / serve / health / dead-code / risk / distill / saved / expand / agents / mcp / doctor）均直接来自 QUICKSTART.md 原文，未自创。
• 写作边界：仅写本文件 guides/repowise-dev-repowise.md；未触及他人目录、未 git、未输出密钥。
• 承接声明：认领段「4.3) spark」仅 1 个仓库（repowise-dev/repowise），写完即空；总榜「待写攻略」仅 3 个仓库，无第 11 名及之后候选。本轮 spark 共写 1 篇（status=idle-after-1）。