repowise-dev/repowise

当 Claude Code 读取一个包含 3,000 个文件的代码库时，它只是在读取文件。它不知道谁拥有这些文件，哪些文件会一起更改，哪些文件已经废弃，以及它们为什么要以这种方式构建。 repowise 解决了这个问题。它将你的代码库索引为四个智能层——依赖图、Git 历史、自动生成的文档和架构决策——并通过八个精心设计的工具将它们暴露给 Claude Code（以及任何兼容 MCP 的 AI Agent）。 结果是：Claude Code 能够回答*“为什么身份验证以这种方式工作？”*，而不是仅仅告诉你*“auth.ts 包含的内容如下。”* ## repowise 构建的内容 repowise 只需运行一次，就能构建好一切，然后在每次提交时保持同步。 ### ◈ 图智能 tree-sitter 将每个文件解析为符号。NetworkX 构建出一个依赖图——涵盖文件、类、函数、导入、继承和调用关系。PageRank 识别你最核心的代码。社区检测能发现逻辑模块，即使你的目录结构并没有反映出这一点。 ### ◈ Git 智能 将 500 次提交的历史转化为信号：热点文件（高变动率 × 高复杂度）、每位工程师的所有权百分比、共变对（在没有导入链接的情况下一起更改的文件——隐藏的耦合），以及解释代码*为何*演进的重要提交信息。 ### ◈ 文档智能 为每个模块和文件提供 LLM 生成的 wiki，并在每次提交时进行增量重建。覆盖率跟踪。每个页面的新鲜度评分。通过 RAG 进行语义搜索。置信度分数显示每个页面相对于底层代码的更新程度。 ### ◈ 决策智能 这是其他工具都没有的层级。从 Git 历史、内联标记和显式 CLI 中捕获架构决策——链接到它们所管辖的图节点，并随着代码的演进跟踪其是否过期。 ``` # WHY: 选择 JWT 而不是 sessions — API 必须是无状态的，以适应 k8s 水平扩缩容 # DECISION: 在支付提供商发生故障后，所有外部 API 调用都封装在 CircuitBreaker 中 # TRADEOFF: 为了写入吞吐量，接受了偏好设置中的最终一致性 ``` 这些成为了结构化的决策记录，Claude Code 可以通过 `get_why()` 查询。 ## 快速开始 ``` pip install repowise ``` ``` cd your-project repowise init # builds all four intelligence layers (~25 min first time) repowise serve # starts MCP server + local dashboard ``` 添加到你的 Claude Code 配置 (`~/.claude/claude_desktop_config.json`) 中： ``` { "mcpServers": { "repowise": { "command": "repowise", "args": ["mcp", "--path", "/path/to/your/project"] } } } ``` **通过 Claude 插件商店：** 安装 repowise 插件，然后告诉 Claude：“为这个项目设置 repowise。” Claude 会自动处理 `pip install`、`repowise init` 和 MCP 配置。 ## 八个 MCP 工具 大多数工具都是围绕数据实体设计的——一个模块、一个文件、一个符号——这迫使 AI Agent 进行冗长的顺序调用链。而 repowise 的工具是围绕**任务**设计的。在一次调用中传递多个目标。获取完整的上下文返回。 | 工具 | 回答的问题 | Claude Code 何时调用它 | |---|---|---| | `get_overview()` | 架构摘要、模块图、入口点 | 首次接触任何不熟悉的代码库时的调用 | | `get_context(targets, include?)` | 任何目标（文件、模块或符号）的文档、所有权、决策、新鲜度 | 在读取或修改代码之前。在一次调用中传递所有相关目标。 | | `get_risk(targets)` | 热点分数、依赖项、共变伙伴、简明的风险摘要（英文） | 在修改文件之前——了解哪些内容可能会遭到破坏 | | `get_why(query?)` | 三种模式：决策的自然语言搜索 · 基于文件路径的决策 · 无参数健康仪表盘 | 在进行架构更改之前——理解现有的意图 | | `search_codebase(query)` | 对完整 wiki 进行语义搜索。自然语言。 | 当你不知道某物位于何处时 | | `get_dependency_path(from, to)` | 两个文件、模块或符号之间的连接路径 | 当需要追踪两个事物是如何连接的时候 | | `get_dead_code()` | 按置信度和清理影响排序的不可达代码 | 清理任务 | | `get_architecture_diagram(module?)` | 整个仓库或特定模块的 Mermaid 图 | 文档编写和展示 | ### 工具调用对比 —— 一个真实任务 *“为所有 API 端点添加速率限制。”* | 方法 | 工具调用 | 首次更改的耗时 | 遗漏的内容 | |---|---|---|---| | 仅使用 Claude Code (无 MCP) | grep + 读取约 30 个文件 | 约 8 分钟 | 所有权、先前的决策、隐藏的耦合 | | repowise (旧的 16 工具设计) | 16 次顺序调用 | 约 15 分钟 | 没有——但速度很慢 | | **repowise (8 工具)** | **5 次调用** | **约 2 分钟** | **没有** | 该任务的 5 次调用： ``` get_overview() # orient: understand the architecture get_context(["middleware", "api/routes", "payments"]) # understand 3 modules at once get_risk(["middleware/auth.ts"]) # assess: 47 dependents, co-changes get_why("rate limiting") # check: any prior decision? search_codebase("rate limit OR throttle OR retry") # find: any prior implementation? ``` ## Claude Code 如何使用它 ``` User: Implement rate limiting on all API endpoints Claude Code: → get_overview() "Express API. Entry points in api/routes/. Middleware in middleware/." → get_context(["middleware", "api/routes", "payments"]) middleware/: existing chain is cors → auth → routes. Owner: @alex. api/routes/: 23 route files. No existing rate limiting. payments/: Owner @sarah (71%). Decision: all side effects must be idempotent. → get_why("rate limiting") "No prior decision found. No prior implementation detected." → get_risk(["middleware/auth.ts"]) "47 files import this. Co-changes with all 4 service listeners. Risk summary: any interface change here touches 47 dependents." → search_codebase("rate limit throttle retry") "Found: payments/retry.ts already has RetryQueue class. Found: payments/middleware.ts has idempotency key middleware." Implementing rate-limiting middleware, inserting after cors, before auth. Will also update tests/middleware.test.ts — detected as historical co-change partner. Flagging payments/ for @sarah review — hotspot, high ownership concentration. ``` 这就是当 AI Agent 拥有真正的代码库智能时会发生的情况。 ## 本地仪表盘 `repowise serve` 会在启动 MCP Server 的同时启动一个完整的 Web UI。无需单独设置——直接在浏览器中浏览你的代码库智能。 | 视图 | 显示内容 | |---|---| | **Chat** | 用自然语言询问关于你代码库的任何问题 | | **Docs** | 带有语法高亮和 Mermaid 图的 AI 生成 wiki | | **Graph** | 交互式依赖图——可处理 2,000+ 个节点 | | **Search** | 全文和语义搜索，带有全局命令面板 (Ctrl+K) | | **Symbols** | 每个函数、类和方法的可搜索索引 | | **Coverage** | 每个文件的文档新鲜度，支持一键重新生成 | | **Ownership** | 贡献者归属和巴士因子风险 | | **Hotspots** | 按排名排序的高变动文件及提交历史 | | **Dead Code** | 带有置信度分数和批量操作的废弃代码 | | **Decisions** | 带有过期监控的架构决策 | ## 自动生成的 CLAUDE.md 在每次 `repowise init` 和 `repowise update` 之后，repowise 都会根据实际的代码库智能重新生成你的 `CLAUDE.md`——而不是使用模板。无需 LLM 调用。5 秒内完成。 ``` repowise generate-claude-md ``` 生成的部分包括：架构摘要、模块图、热点警告、所有权图、隐藏耦合对、活跃的架构决策和废弃代码候选项。顶部的用户自有部分永远不会被触碰。 ``` ## 架构 Monorepo with 4 packages. Entry points: api/server.ts, cli/index.ts. ## 热点 — 谨慎处理 - payments/processor.ts — 47 commits/month, high complexity, primary owner: @sarah - shared/events/EventBus.ts — 23 dependents, co-changes with all service listeners ## 活跃的架构决策 - JWT over sessions (auth/service.ts) — stateless required for k8s horizontal scaling - CircuitBreaker on all external calls — after payment provider outages in Q3 2024 ## 隐式耦合（无 import 链接，但同步变化） - auth.ts ↔ middleware/session.ts — co-changed 31 times in last 500 commits ``` ## Git 智能 repowise 会挖掘你最近的 500 次提交（可配置），以生成任何静态分析都无法发现的信号。 **热点** —— 变动率和复杂度均位列前 25% 的文件。这是 bug 的藏身之处。在仪表盘、CLAUDE.md 中会被标记，并在 Claude Code 接触它们之前通过 `get_risk()` 显示出来。 **所有权** —— 将 `git blame` 聚合为每位工程师的所有权百分比。知道该联系谁。知道哪里存在知识孤岛。 **共变对** —— 在同一个提交中一起更改但没有导入链接的文件。AST 解析无法检测到的隐藏耦合。`get_context()` 会在显示直接依赖项的同时显示共变伙伴。 **巴士因子** —— 超过 80% 由单个工程师拥有的文件。显示在所有权视图中。在 CLAUDE.md 中作为知识风险显示。 **重要提交** —— 每个文件最近 10 条有意义的提交信息（已过滤：无合并、无依赖项版本更新、无 lint）包含在生成提示中。LLM 会解释代码*为什么*以这种方式构建。 ## 废弃代码检测 纯粹的图遍历和 SQL。无需 LLM 调用。无论仓库大小，均可在 10 秒内完成。 ``` repowise dead-code 23 findings · 4 safe to delete ✓ utils/legacy_parser.ts file 1.00 safe to delete ✓ auth/session.ts file 0.92 safe to delete ✓ helpers/formatDate export 0.71 safe to delete ✓ types/OldUser export 0.68 safe to delete ✗ analytics/v1/tracker.ts file 0.41 recent activity — review first ``` 设计上趋于保守。`safe_to_delete` 要求置信度 ≥ 0.70，并排除了动态加载的模式（`*Plugin`、`*Handler`、`*Adapter`、`*Middleware`）。repowise 只负责列出候选项。由工程师决定是否删除。 ## 架构决策 ``` repowise decision add # guided interactive capture (~90 seconds) repowise decision confirm # review auto-proposed decisions from git history repowise decision health # stale, conflicting, ungoverned hotspots ``` ``` repowise decision health 2 stale decisions → "JWT over sessions" — auth/service.ts rewritten 3 months ago, decision may be outdated → "EventBus in-process only" — 8 of 14 governed files changed since recorded 1 conflict → payments/: two decisions with overlapping scope and contradictory rationale 1 ungoverned hotspot → payments/processor.ts — 47 commits/month, no architectural decisions recorded ``` 决策被链接到图节点，随着代码的演进跟踪其是否过期，并在 Claude Code 涉及受管辖文件时通过 `get_why()` 显示出来。 当资深工程师离开时，“原因”通常也会随之被带走。而决策智能将其保留在了代码库中。 ## 对比分析 | | repowise | Google Code Wiki | DeepWiki | Swimm | CodeScene | |---|---|---|---|---|---| | 可自托管，开源 | ✅ AGPL-3.0 | ❌ 仅限云端 | ❌ 仅限云端 | ❌ 仅限企业版 | ✅ Docker | | 自动生成文档 | ✅ | ✅ Gemini | ✅ | ✅ PR2Doc | ❌ | | 私有仓库 — 无需上云 | ✅ | ❌ 开发中 | ❌ 仅限 OSS forks | ✅ 企业版 | ✅ | | 废弃代码检测 | ✅ | ❌ | ❌ | ❌ | ❌ | | Git 智能（热点、所有权、共变） | ✅ | ❌ | ❌ | ❌ | ✅ | | 巴士因子分析 | ✅ | ❌ | ❌ | ❌ | ✅ | | 架构决策记录 | ✅ | ❌ | ❌ | ❌ | ❌ | | 面向 AI Agent 的 MCP Server | ✅ 8 个工具 | ❌ | ✅ 3 个工具 | ✅ | ✅ | | 自动生成的 CLAUDE.md | ✅ | ❌ | ❌ | ❌ | ❌ | | 文档新鲜度评分 | ✅ | ❌ | ❌ | ⚠️ 仅限过期检测 | ❌ | | 提交时增量更新 | ✅ <30s | ✅ | ❌ | ✅ | ✅ | | 本地仪表盘 / 前端 | ✅ | ❌ | ❌ | ❌ 仅限 IDE | ✅ | | 内部使用免费 | ✅ | ✅ 公共仓库 | ✅ 公共仓库 | ❌ | ❌ | **诚实的总结：** - **对比 Google Code Wiki** —— Google 的产品（于 2025 年 11 月推出）仅限云端，目前尚不支持私有仓库。基于 Gemini 的文档功能很强大，但没有 Git 行为智能、废弃代码检测、MCP Server 和架构决策。 - **对比 DeepWiki** —— 仅限云端，闭源（存在社区可自托管的 forks）。文档和 Q&A 功能强大，带有基础的 3 工具 MCP Server。没有 Git 分析、废弃代码检测和决策功能。 - **对比 Swimm** —— Swimm 的优势在于通过过期检测，将手动编写的文档链接到代码片段。没有图、没有 Git 行为分析、没有废弃代码检测、默认没有 MCP。私有托管需要企业版定价。 - **对比 CodeScene** —— CodeScene 拥有出色的 Git 智能（热点、共变、所有权、巴士因子）。没有文档生成、没有 RAG、没有架构决策。闭源，按作者数量定价。 repowise 是这些特性的交集：CodeScene 级别的 Git 智能 + 自动生成的文档 + 原生支持 Agent 的 MCP + 架构决策，可自托管且完全开源。 ## 托管版 —— 面向团队 自托管的 OSS 版本是完整且可投入生产环境的。面向工程团队的托管版正在积极开发中。 托管版增加了只有在托管的、多用户环境中才有意义的功能： - **共享的团队上下文层** —— 一个由完整的图和决策层支持的 CLAUDE.md，通过 MCP 自动注入到每个团队成员的 Claude Code 会话中 - **会话智能收集** —— 从 AI 编码会话中提取架构决策，并自动提交到团队知识库中 - **工程负责人仪表盘** —— 巴士因子趋势、热点随时间的演变、跨仓库的废弃代码、所有权偏移 - **托管的 Webhooks** —— 零配置，在任何分支的每次提交时自动重新索引 - **集成** *(即将推出)* —— Slack 警报、Notion 同步、Confluence 同步、Jira 和 Linear 决策关联 - **跨仓库智能** —— 跨你所有仓库的热点、废弃代码和所有权概览 [加入托管版等候名单 →](https://repowise.dev) · [联系我们获取企业版](mailto:hello@repowise.dev) ## CLI 参考 ``` # Core repowise init [PATH] # index codebase (one-time) repowise update [PATH] # incremental update (<30 seconds) repowise serve [PATH] # MCP server + local dashboard repowise watch [PATH] # auto-update on file save # Query repowise query "" # ask anything from the terminal repowise search "" # semantic search over the wiki repowise status # coverage, freshness, dead code summary # 死代码 repowise dead-code # full report repowise dead-code --safe-only # only safe-to-delete findings repowise dead-code resolve # mark resolved / false positive # 决策 repowise decision add # record a decision (interactive) repowise decision list # all decisions, filterable repowise decision confirm # confirm a proposed decision repowise decision health # stale, conflicts, ungoverned hotspots # Editor 文件 repowise generate-claude-md # regenerate CLAUDE.md # Utilities repowise export [PATH] # export wiki as markdown files repowise doctor # check setup, API keys, connectivity repowise reindex # rebuild vector store (no LLM calls) ``` ## 支持的语言 **代码：** Python · TypeScript · JavaScript · Go · Rust · Java · C · C++ · Ruby · Kotlin **配置 / 契约：** OpenAPI · Protobuf · GraphQL · Dockerfile · GitHub Actions YAML · Makefile 添加新语言只需一个 `.scm` tree-sitter 查询文件和一个配置项。无需更改解析器。详情请见 [添加新语言](docs/CONTRIBUTING.md#adding-a-new-language)。 ## 隐私 **自托管：** 你的代码永远不会离开你的基础设施。没有遥测。没有分析。零收集。 **BYOK：** 自带 Anthropic 或 OpenAI API 密钥。我们永远不会看到你的 LLM 调用。根据 Anthropic 的 API 政策实行零数据保留——你的代码永远不会被用于训练任何模型。 **存储的内容：** NetworkX 图（文件和符号关系）、LanceDB 嵌入（不可逆向量）、生成的 wiki 页面、Git 元数据。原始源代码仅在处理过程中临时使用，从不持久化保存。 **完全离线：** 使用 Ollama 作为 LLM + 本地嵌入模型 = 零外部 API 调用。 ## 配置 `repowise init` 会生成 `.repowise/config.yaml`。关键选项如下： ``` provider: anthropic # anthropic | openai | ollama | litellm model: claude-sonnet-4-5 embedding_model: voyage-3 git: co_change_commit_limit: 500 blame_enabled: true dead_code: enabled: true safe_to_delete_threshold: 0.7 maintenance: cascade_budget: 30 # max pages fully regenerated per commit background_regen_schedule: "0 2 * * *" ``` 完整配置参考：[docs/CONFIG.md](docs/CONFIG.md) ## 贡献 ``` git clone https://github.com/repowise/repowise cd repowise pip install -e "packages/core[dev]" pytest tests/unit/ ``` 新手推荐：[`good first issue`](https://github.com/repowise/repowise/labels/good%20first%20issue) 包含如何添加语言和 LLM 提供商的完整指南：[CONTRIBUTING.md](CONTRIBUTING.md) ## 许可证 AGPL-3.0。对在内部使用 repowise 的个人、团队和公司免费。 关于商业许可——将 repowise 嵌入产品、白标，或在不受 AGPL 限制的情况下用作 SaaS——请联系 [commercial@repowise.dev](mailto:commercial@repowise.dev)。

为那些厌倦了问*“这段代码为什么存在？”*的工程师而构建。 [repowise.dev](https://repowise.dev) · [在线演示 →](https://repowise.dev/examples) · [Discord](https://discord.gg/repowise) · [X](https://x.com/repowisedev)

标签：AI编程助手, AI辅助开发, DNS解析, Git分析, MCP协议, NetworkX, Python开发, tree-sitter, 代码分析工具, 代码图谱, 代码审查, 代码库智能分析, 代码理解, 代码索引, 依赖图分析, 大模型上下文协议, 工程团队工具, 开发工具链, 开发者体验, 开源项目, 数据管道, 架构决策记录, 死代码检测, 特权检测, 知识库管理, 突变策略, 自动生成文档, 软件工程, 逆向工具