企业官网建设流程全解析

如何用repowise Workspaces索引多仓库项目：跨仓库契约匹配与协同变更完全指南

【免费下载链接】repowiseCodebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.项目地址: https://gitcode.com/gh_mirrors/re/repowise

repowise Workspaces 是代码智能平台 repowise 的多仓库索引模式：把后端、前端、共享库等多个 Git 仓库放在一起统一索引，自动完成跨仓库契约匹配（HTTP/gRPC/消息主题），分析协同变更（哪些文件总是一起改），并在你改动一个服务时告诉你哪些下游仓库受影响。本文面向新手，带你用 10 分钟从零完成多仓库索引，并看懂每一份分析结果。

一、什么是 Workspace：什么场景该用多仓库索引？

单个仓库用repowise init即可；但当你的项目横跨多个仓库时——比如后端 + 前端分仓、微服务之间通过 HTTP/gRPC/消息队列通信——单仓库模式就看不到"仓库之间"的依赖了。Workspaces 正是为此设计：

• 🗂️ 每个仓库独立索引（文档、图谱、搜索互不影响）
• 🔗 跨仓库契约匹配：谁调用了谁，证据链完整
• 🔄 协同变更检测：跨越仓库边界找"总是一起改"的文件
• 💥 跨仓库爆炸半径 + 破坏性变更守卫
• 🎨 一个 Web UI 看全部，一个 MCP 服务供 AI 代理查询

官方文档：docs/scale/WORKSPACES.md

二、三步完成多仓库项目索引（最快上手路径）

第 1 步：把相关仓库放在同一个父目录下

my-workspace/ backend/ # git 仓库 frontend/ # git 仓库 shared-libs/ # git 仓库

第 2 步：在父目录执行一条命令

cd my-workspace repowise init .

repowise 会自动向下扫描（最多 3 层深度）找出所有 git 仓库，让你勾选要索引的仓库、指定一个主仓库（MCP 查询默认目标），然后逐个索引、生成文档，最后跑完全部跨仓库分析。常用选项：--no-prose（不用 LLM，免费纯结构分析）、-x "node_modules/"（排除目录）、--yes（跳过确认提示）。

第 3 步：验证并探索

repowise status --workspace # 查看 workspace 状态 repowise workspace list # 列出所有已索引仓库 repowise serve # 启动 Web UI repowise search "authentication flow" # 跨全部仓库搜索

完成后的目录结构：每个仓库有自己的.repowise/索引，父目录多出一份共享配置 .repowise-workspace.yaml 和数据目录.repowise-workspace/（存放 contracts.json、system_graph.json、breaking_changes.json 等分析产物）。

💡仓库不在同一目录下？完全没问题：repowise workspace add /path/to/external-repo --alias api-gateway可以把任意路径的仓库加入 workspace；用repowise workspace scan可随时重扫新仓库。

三、跨仓库契约匹配：它如何找到"谁调用谁"

这是 Workspaces 最核心的能力。初始化时 repowise 会扫描各仓库源码，提取服务提供方（Provider）与消费方（Consumer），然后把它们配对成带置信度的链接。支持的契约类型：

几个新手容易踩坑的细节：

• 完整路径匹配：路由前缀（如 FastAPI 的APIRouter(prefix=...)）会被自动拼接后再匹配，/api/v1+/users才能对上/api/v1/users。
• 精确 vs 候选：客户端 base URL 是未解析的占位符（如fetch(\${API_BASE}/users`)）时，若整个 workspace 只有一个服务提供该路径，链接标记为exact；目标有歧义则降级为candidate。你也可以在配置的service_bases中显式声明API_BASE: backend`，让这类调用直接精确匹配。
• 测试目录自动排除：tests/、__tests__/等目录和test_*.py、*.spec.*等文件名不会产出契约——只存在于测试里的路由是 fixture，不是真实服务。

核心实现见 packages/core/src/repowise/core/workspace/contracts.py 与各语言提取器 extractors/。

链接数偏少？用 diagnostics 命令诊断原因

repowise workspace diagnostics

这份报告按仓库和契约类型给出：提供方/消费方数量、未匹配消费方及其原因（no_provider无匹配提供方、internal_only仅限内部调用、unlinked有候选但未成链、external_host调用的是 Stripe 等第三方）、以及孤儿提供方（声明了却无人消费）。这是排查"为什么匹配上这么多/这么少"的第一站。

四、协同变更检测：谁和谁总是一起改

协同变更（Co-Change）分析跨越仓库的 git 历史：如果backend/api/routes.py和frontend/src/api/client.ts总在同一时间窗口内被修改，它们就获得高协同分。它揭示的是隐式依赖——代码里没有 import，但历史上总是一起变。

注意 repowise 对两类证据的态度非常"诚实"：结构边（契约、包依赖）表示"真的调用了"，行为边（协同变更）只表示"历史上总一起改"，在系统图中用不同线型渲染，绝不会把"总是一起改"误当"互相调用"。

协同变更数据保存在.repowise-workspace/cross_repo_edges.json，分析逻辑见 packages/core/src/repowise/core/workspace/cross_repo.py。

五、评估协同变更风险：爆炸半径、破坏性变更、受影响测试

改完代码、提交之前，三个问题 repowise 都能答：

1️⃣ 我改这个服务，谁会被波及？（跨仓库爆炸半径）

沿着系统图反向遍历：改提供方可能影响消费方，返回按影响分排序的下游服务列表。结构边全权重传播（"will break"），协同边减半权重（"may drift"），每个受影响服务都带跳数距离和 0-1 分数。实现见 blast_radius.py。

2️⃣ 我的接口改动是否不兼容？（破坏性变更守卫）

每次repowise update --workspace都会把新提取的契约与上一版做 diff，识别：端点删除、字段删除、字段类型变更（如string → int64）、proto 字段编号变更、必填性收紧等。兼容的变更（新增可选字段、新增端点等）保持安静不误报。每条发现都附带受暴露的消费方文件。OpenAPI 3.0/3.1/3.2 的比较覆盖参数、请求体、枚举、可空性等常见子集，规则见 breaking_change.py。

3️⃣ 我该跑哪些测试？（跨仓库测试影响）

repowise workspace impacted-tests backend:app/routers/users.py

给定被改动的提供方文件，命令会沿契约链接找到消费仓库，再走消费方自己的调用图/覆盖率数据，列出"值得运行的测试"，并按证据强度标注measured（覆盖率实测）/inferred（调用图推断）。空结果也会明确说明原因——"没有测试保护这段代码"和"查不到"是两回事。支持--format list直接管道给测试运行器。实现见 test_impact.py。

六、架构治理：声明规则 + 架构指标

架构一致性检查（architecture lint）：在 .repowise-workspace.yaml 的conformance:块中声明"允许谁依赖谁"（支持通配符、tag:xxx标签匹配、例外放行），然后每次更新自动把系统图与规则对账，还能免费获得依赖环检测（A → B → … → A）。

repowise workspace check # 有违规时退出码非 0，可直接卡 CI

架构指标：repowise workspace metrics输出传播成本（平均一个服务能间接触达多少其他服务）、循环核大小、每个服务的角色（Core / Shared / Control / Peripheral），以及一个 1-10 的确定性架构分数——可以长期追踪、跨 workspace 对比。实现分别在 conformance.py 与 architecture_metrics.py。

七、多仓库视图：Web UI 与 MCP 集成

repowise serve启动后，workspace 模式下 Web UI 新增四个视图（源码位于 packages/web/src/app/workspace/）：

• Workspace Dashboard（/workspace）：全部仓库的聚合统计与仓库卡片
• System Map（/workspace/system-map）：代码生成的服务关系图，节点带健康环，边按类型着色、按匹配类型分实线/虚线，支持过滤、爆炸半径叠加、破坏性变更与一致性标注
• Contracts View（/workspace/contracts）：所有契约的提供方/消费方匹配，可按类型和仓库筛选
• Co-Changes View（/workspace/co-changes）：跨仓库文件对按协同强度排序

侧边栏Repositories下列出所有仓库，点进去就是该仓库完整的单仓库页面（文档、图谱、搜索、热点等）。

对 AI 代理同样友好：workspace 初始化会自动向 Claude Desktop 和 Claude Code 注册一个MCP 服务实例，服务所有仓库（懒加载 + LRU 缓存，同时最多驻留 5 个仓库索引）。大多数工具支持repo参数指定目标仓库或"all"跨仓库查询；get_blast_radius、get_conformance、get_architecture等工具让代理在改动高扇出提供方之前先拿到跨仓库影响面。

八、常见问题（新手 FAQ）

Q：更新代码后如何刷新 workspace？

repowise update --workspace # 更新全部仓库 repowise watch --workspace # 或开启 watch 模式自动更新

各仓库按自己的docs_enabled决定是重新生成文档还是仅刷新索引。

Q：能嵌套 workspace 吗？不能。repowise 向上查找第一个.repowise-workspace.yaml作为边界。

Q：.repowise-workspace/要提交到 Git 吗？不要。它含绝对路径和本机生成的分析数据，应加入.gitignore（连同各仓库的.repowise/）。

Q：git worktree 支持吗？自动支持——在 linked worktree 中执行repowise init/update会检测基础检出、增量更新分支差异文件，详见 docs/scale/WORKTREES.md。

写在最后

repowise Workspaces 把"多仓库"从一堆割裂的索引变成了一张统一的系统图：契约匹配回答"谁调用谁"，协同变更回答"谁和谁绑定在一起"，爆炸半径与破坏性变更守卫回答"改了会怎样、该跑哪些测试"。三条命令起步（init .→serve→workspace check卡 CI），就能获得带完整证据链的跨仓库智能。

• 📖 完整文档：docs/scale/WORKSPACES.md
• 🛠️ CLI 命令实现：packages/cli/src/repowise/cli/commands/workspace_cmd.py
• 🧠 跨仓库分析核心：packages/core/src/repowise/core/workspace/
• 📖 快速上手：docs/start/QUICKSTART.md

【免费下载链接】repowiseCodebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.项目地址: https://gitcode.com/gh_mirrors/re/repowise