repowise CLI 完全指南:安装、命令体系与源码架构解读

原创2026-10-08 18:09:591,910 阅读

repowise CLI 完全指南:安装、命令体系与源码架构解读

repowise 是一个开源的代码库智能层(codebase intelligence layer):它用 tree-sitter 解析源码构建依赖图,结合 git 历史计算代码健康分、发现死代码、抽取架构决策,并自动生成 wiki 文档,最终通过 MCP 协议把这一切暴露给 Claude Code、Codex、Cursor 等 AI 编码代理。repowise 命令行界面(CLI)是这个产品的统一入口——从 init 建立索引、update 增量刷新,到 serve 启动 API/Web UI、mcp 启动 MCP 服务器,再到 risk、health、dead-code、coverage、distill 等分析命令,全部由它驱动。读完本文,你将掌握 repowise CLI 的安装方式、它在 monorepo 中的架构位置、七大命令族的完整使用套路,以及 main.py 懒加载命令注册等底层实现原理。

一、repowise CLI 是什么

repowise CLI 是整个产品的命令行门面,它聚合了以下核心能力:

  • init / update / generate:索引代码库并生成 wiki 文档;
  • serve / mcp:启动 API 服务器、Web UI 与 MCP 服务器(AI 编辑器集成);
  • risk / health / dead-code / coverage / distill:变更风险评估、代码健康打分、死代码检测、测试覆盖摄取与命令输出蒸馏。

运行环境要求 Python >= 3.11,采用 AGPL-3.0-or-later 开源协议。根目录 pyproject.toml 中定义了统一分发包 repowise(当前仓库版本为 0.55.0),依赖了全套 tree-sitter 语法(Python、TypeScript、Go、Rust、Java、C++、Dart、Kotlin、Ruby、C#、Swift、Scala、PHP、COBOL、Bash、Lua、GDscript、VB.NET、Elixir、F#、Objective-C 等)、networkx/scipy(依赖图)、lancedb(向量检索)、sqlalchemy/alembic(持久化)以及 anthropic/openai/google-genai/litellm(LLM 供应商 SDK,全部随包捆绑,无需额外 extras)。

二、安装产品

官方安装方式非常简单,三选一:

uv tool install repowise      # 或: pipx install repowise / pip install repowise
cd your-repo
repowise init

uv tool install 会把 repowise 安装为独立工具;pipx install 同样隔离在独立环境;pip install repowise 适合已有虚拟环境的场景。装好后进入任意代码仓库目录,运行 repowise init 即开始索引并生成 wiki。

注意:repowise CLI 不会单独发布到 PyPI。用户拿到的是由根 pyproject.toml 构建的单一 repowise 发行包,CLI 只是其中一部分。包内同时包含 repowise-core(分析管线)与 repowise-server(API/MCP 服务端)两个工作区包——这正是 packages/cli/pyproject.toml 中 dependencies = ["repowise-core", "repowise-server"] 的来源。

三、它在 monorepo 中的位置

repowise 是一个 Python monorepo,CLI 包位于 packages/cli/:

  • 驱动核心管线:init/update 等命令调用 packages/core 中的分析管线(依赖图构建、死代码检测、决策抽取、健康打分);
  • 启动服务端:serve 与 mcp 命令从 packages/server 拉起 API 服务器与 MCP 服务器;
  • 命令实现位置:所有子命令的 Click 实现位于 packages/cli/src/repowise/cli/commands/,目录下可见 init_cmd/、update_cmd/、health_cmd/、generate_cmd/、decision_cmd.py、risk_cmd.py、dead_code_cmd.py、mcp_cmd.py、serve_cmd.py、workspace_cmd.py 等四十多个模块;
  • 入口点:packages/cli/src/repowise/cli/main.py 定义根 Click 组 cli。

python -m repowise.cli.main 是控制台脚本被遮蔽时的文档化回退入口:main.py 的 if __name__ == "__main__": cli() 保证该用法真正执行命令而不是静默无操作。

四、命令全景:七大命令族

CLI 参考文档(docs/reference/CLI_REFERENCE.md)按"你想做什么"而非字母序对命令分组,注册顺序如下:augment、init、delete、generate-claude-md、costs、update、generate、dead-code、doc-drift、health、risk、overlap、decision、coverage、impacted-tests、search、ask、context、symbol、why、distill、expand、saved、savings、security、corrections、export、hook、agents、uninstall、status、next、doctor、watch、serve、mcp、reindex、restyle、wiki-styles、whats-new、telemetry、login、logout、whoami、workspace。另有 repowise-augment、repowise-rewrite 两个独立控制台脚本(钩子入口,不面向手工调用)。

关于 LLM key 的重要事实:绝大多数命令是纯索引/分析,从不调用 LLM;init 从不强制要求 key——没有 key 时它直接从结构渲染 wiki。需要 LLM 的例外是:update(除非 --index-only 或 --no-docs)、generate、restyle、watch(当它重新生成页面时)、health --generate-code、workspace add --docs。而 search、dead-code、doc-drift、health、risk、impacted-tests、decision、coverage、security、export、mcp、reindex、doctor 等全部无需配置任何提供商即可工作。

工作区自动检测(跨切面机制)

多数命令会自动探测当前是否位于 workspace 根目录并相应路由,触发时会打印一行 [workspace] … 提示。可用旗标:

Flag 效果
--workspace / -w 强制工作区模式;找不到 .repowise-workspace.yaml 时报错
--no-workspace 即使从工作区根目录调用也强制单仓库模式
--repo <alias> 把工作区命令限定到某一个仓库
--all 在所有工作区仓库间扇出(用于 costs、search)

带这些旗标的命令包括:update、status、watch、doctor、costs、search、dead-code、doc-drift、decision、coverage、generate-claude-md、hook install/status/uninstall。

五、核心命令详解

5.1 repowise init [PATH]:索引与文档生成起点

单仓库:

cd your-project
repowise init

多仓库工作区(父目录包含多个 git 仓库):

cd my-workspace/
repowise init .

四个阶段:

  1. Ingestion(摄取):遍历每个文件,用 tree-sitter 解析 AST,构建"文件 + 符号"两层依赖图,索引 git 历史(churn、热点、所有权、bus factor);
  2. Analysis(分析):检测死代码,从内联标记、README 与 git 历史抽取架构决策,运行 Leiden 社区检测与执行流追踪;
  3. Generation(生成):生成文件级、模块级、仓库级 wiki 页面——要么提示 LLM,要么用 --no-prose 从解析结构直接渲染;
  4. Persistence(持久化):全部存入 .repowise/wiki.db,构建搜索索引,生成编辑器指令文件,注册 MCP 服务器与 hooks。

工作区模式下额外增加:仓库扫描、逐仓索引、跨仓库分析(共同变更、契约、包依赖)与 workspace 级 CLAUDE.md 生成。

交互式菜单:在 TTY 上运行裸 repowise init(未传 --provider、--prose/--no-prose 或 --yes)会弹出菜单:Everything(索引 + 模型写文档)、Index only(无 LLM 无成本的结构化 wiki)、Advanced(完全控制,先选"Generate model-written wiki docs?",再按索引/生成分两组提问)。若首个提示读到 EOF(常见于 agent 管道 stdin 场景),init 会打印提示并按默认值继续而不是中止。

页面体积策略:文件页从结构渲染、不消耗模型 token,真正限制它的是 wiki 体积、嵌入调用量与检索噪声。超过 2,000 个可文档化文件(p95)时,交互式高级模式会改为按重要性提供前 2,000 页;超过 4,500 个文件页(约 40 MB,近 p99)时每次运行都强制限制到 4,500 并明示。--max-file-pages N 直接设置上限,0 表示拒绝限制;结果保存为 config.yaml 的 max_file_pages,update --full 与 generate 均遵循。

成本闸门:花费任何 token 前先展示估算并要求确认。stdin 不是 TTY 时永不提示:自动拒绝、保留已建索引并渲染结构化 wiki。默认在 25 美元以内回答 Yes,超过则翻转为 No。

主要选项(完整表格见 docs/reference/CLI_REFERENCE.md):

Flag 说明
--provider LLM 提供商:anthropic、openai、openrouter、gemini、deepseek、kimi、ollama、litellm、codex_cli、opencode、edenai、mock
--model 模型名覆盖(如 claude-sonnet-4-6)
--embedder 语义搜索嵌入器:gemini、openai、openrouter、ollama、edenai、mock(默认自动检测)
--prose / --no-prose LLM 花费的总开关。文件/符号/SCC/API/infra 页无论哪种都从结构渲染;模型手写集是子系统(概念)树 + 仓库概览 + 架构图 + 入门合集。--no-prose 让整个 wiki 无需 key 且免费
--mode 管线深度:standard(默认)或 fast(仅图 + 关键 git,无逐文件 blame/co-change,无 LLM 文档;之后用 update --full 升级)
--skip-tests / --skip-infra 排除测试文件 / 基础设施文件(Dockerfile、Makefile、Terraform)
--exclude / -x gitignore 风格排除模式,可重复
--concurrency 最大并发 LLM 调用(默认 10)
--reasoning 支持的提供商的推理模式:auto/off/minimal/low/medium/high/xhigh/max
--max-file-pages 最多输出的文件页数,按重要性排序;0 表示每个合格文件一页
--coverage-report 要摄取的测试覆盖报告(LCOV/Cobertura/Clover/JaCoCo/Go coverprofile),可重复
--onboarding / --no-onboarding 生成精选 Onboarding 合集(最多 8 个概览页),默认开
--wiki-style 文档风格:comprehensive(默认)、caveman、reference、tutorial
--language 输出语言:en(默认)及 zh、ja、de、fr、es 等二十余种;代码与符号名保持不翻译
--resume 续跑上次中断/有失败页的运行,按页匹配,不会为已写页面二次付费
--force 全部重新生成;从不触发模型(--force --no-prose 免费重渲染整个 wiki)
--commit-limit 每文件最多分析的提交数(默认 500,上限 10000)
--hook / --no-hook 安装/跳过 post-commit 自动 update 钩子(默认开)
--editor-setup / --no-editor-setup 是否接线编辑器(Claude Code/Claude Desktop MCP 入口、.mcp.json、.vscode/ 等);--no-editor-setup 只写 .repowise/,适合临时 checkout、CI
--save-key / --no-save-key 是否把本次认证的 API key 存入 .repowise/.env(默认开);CI 用 --no-save-key 或环境变量 REPOWISE_NO_SAVE_KEY=1
--seed-from / --no-seed 工作树(worktree)索引播种控制,见 docs/scale/WORKTREES.md
--yes / -y、--dry-run、--test-run 跳过确认 / 预览生成计划与成本 / 仅生成 PageRank 前 10 文件

常用示例:

repowise init                                         # 交互式
repowise init --provider anthropic --yes              # 自动化
repowise init --provider codex_cli --codex --yes       # 使用已认证的 Codex CLI
repowise init --no-prose                              # 免费,从结构渲染 wiki
repowise init --dry-run                               # 预览成本
repowise init --provider openai --model qwen3 --reasoning off
repowise init --language zh                           # 中文 wiki 文档
repowise init -x vendor/ -x "*.gen.go"               # 排除模式
repowise init --no-editor-setup --yes                 # 只索引,不动全局 MCP 配置
repowise init --provider openai --yes --no-save-key    # CI:索引但不落盘 key
repowise init .                                       # 工作区模式

嵌入失败的退出状态:使用真实嵌入器(非 mock)时,若页面向量写入失败(如 LanceDB 安装损坏),运行仍保存页面与全文索引但以退出码 1 结束,在索引作用域记录 search.semantic: unavailable,并给出修复命令:重装依赖后 repowise reindex。无 key 的 mock 嵌入器永远不会因此失败运行。

5.2 repowise update [PATH]:增量刷新

对比上次同步以来变更的文件,增量刷新依赖图、git 元数据、健康与死代码结论;图结构变化时还更新知识图谱(layers、guided tour、入口点)与导出的 knowledge-graph.json。文档模式下重新生成受影响的 wiki 页面;索引模式则沿用已生成的层名与节点摘要——不做文档模式就不会有任何 LLM 调用。

关键旗标:--since(git ref,覆盖 state.json)、--cascade-budget(最多重生成页数)、--working-tree(也索引未提交改动;watch 总是如此)、--docs/--no-docs、--index-only、--full(把 fast 索引增量升级为 full:回填 git 层、复用持久化图、生成缺失 prose、重建全文搜索,单仓库专用)、-v/--verbose、--progress rich|json。文档模式更新还能挖掘本地编码 agent 会话记录中的持久决策(source: session,默认关闭,用 repowise decision source set session --on 开启)。

repowise update                        # 上次同步以来的 diff
repowise update --dry-run              # 预览
repowise update --since v1.0.0         # 从标签 diff
repowise update --working-tree         # 包含未提交编辑
repowise update --workspace            # 所有工作区仓库
repowise update --workspace --docs     # 强制所有过期仓库重生成文档
repowise update --repo backend         # 指定工作区仓库
repowise update --full --provider anthropic   # 把 fast 索引升级为 full

state.json 中的 index_scope 是规范机器可读描述,被 status --format json、/api/repos、生成的 agent 指南与 MCP _meta.index_scope 使用;它分开记录运行模式、内容来源(none/template/model)、Git tier、配置的 commit 上限与实际覆盖、文件页配额与生成数、分析可用性、搜索可用性、提供商选择与升级状态。

5.3 generate / restyle / wiki-styles:按需补写与换风格

repowise generate [PATH] 是 --no-prose 仓库的升级路径:用模型按需写子系统(概念)页。选择旗标 --unwritten(默认,非交互)、--all、--stale、--path <glob>、--page <id>;--cascade none|dependents|full 决定被汇总页的级联策略(默认 dependents)。嵌入方面,若仓库以 embedder: mock 索引,generate 会从环境重解析真实嵌入器并自动重嵌入整个 wiki。

repowise generate                           # 写未写的子系统页
repowise generate --dry-run                 # 会写什么、成本多少?
repowise generate --path src/api            # 只写 src/api 下的子系统页
repowise generate --page module_page:src/api --cascade none

repowise restyle <a href="https://link.gitcode.com/i/f526b954928c371d5c7d3a85f7ca13a3" target="_blank">STYLE] [PATH] 切换 wiki 风格并重生成所有页面,复用既有索引(从 SQL 重水合图与 git 元数据,不重新解析、不重新 blame)。四种风格仅语音与密度不同,Markdown 结构不变,因此搜索、目录与交叉链接保持可用,详见 [docs/layers/WIKI.md。

repowise restyle caveman               # 压缩、AI 优先
repowise restyle reference --yes       # API 手册风

手工改 config.yaml 的 wiki_style 再跑 update 不会重生成既有页面(那条路径只重新打分健康)。请使用 restyle。

repowise wiki-styles [PATH] 列出可用风格(内置 + .repowise/styles/ 下的自定义风格)与当前风格。

5.4 serve 与 watch

repowise serve [PATH] 启动 API 服务器与 Web UI:

Flag 说明
--port API 端口(默认 7337;环境变量 REPOWISE_PORT)
--host 绑定主机(默认 127.0.0.1)
--workers Uvicorn 工作进程(默认 1)
--ui-port Web UI 端口(默认 3000)
--no-ui 只启动 API
--refresh-ui 强制重新下载 Web UI tarball,忽略缓存
repowise serve                           # API + Web UI
repowise serve --no-ui                   # 仅 API
repowise serve --port 8080 --ui-port 8081

Web UI 需要 Node >= 20,否则 serve 回退为仅 API。UI 来源按优先级:本地 monorepo 构建(packages/web/.next/standalone/...,源码更新时自动 npm run build)→ ~/.repowise/web/ 缓存 → 按 CLI 版本从 release 下载 repowise-web.tar.gz。

repowise watch [PATH] 监听文件变化并自动更新 wiki 页面,Ctrl+C 停止。与 post-commit 钩子不同,它索引未提交的工作(staged/unstaged/untracked 都进索引)。--debounce 默认 2000ms;.repowise/、.git/、node_modules/、构建产物以及 repowise 自己管理的文件(CLAUDE.md、AGENTS.md、.mcp.json)的写入不会触发更新。--index-only 让每次触发只免费更新索引/图/健康,prose 留给后续 update。

六、查询命令:问代码库问题

  • repowise search QUERY [PATH]:关键词/语义/符号搜索,与 search_codebase MCP 工具共用同一检索。--mode fulltext|semantic|symbol 加工具自身的 auto、concept、path、hybrid;fulltext 与 semantic 现在都跑融合后的 concept 检索。--limit(默认 10)、--format table|json、--full(完整工具载荷)。
  • repowise ask QUESTION:带引用的合成回答(即 MCP get_answer),代价是一次 LLM 调用。--scope 限定路径前缀。confidence: high 是内容落地的,可直接引用。
  • repowise context TARGETS...:文件/模块/符号的"分诊卡"——标题、摘要、架构层、热点与修 bug 历史、文档新鲜度。默认不含源码字节;--include skeleton 一次取回整文件(去正文、行号校验)。--include 可加 callers、callees、metrics、decisions 等块。
  • repowise symbol SYMBOL_ID:读取单个函数/类/常量,带实时校验的行界;verified: true 表示行界已对照真实文件。可传 文件::符号、文件:行段 或蒸馏省略引用 repowise#a1b2c3d4e5f6。--context-lines(0-50)、--query(过滤恢复的行)。
  • repowise why [QUERY]:为什么代码长成这样——决策记录、理由与 git 考古。--target 锚定文件。路径无决策时回退到 git 考古,绝不空手而归。
  • repowise status [PATH]:wiki 同步状态、页面统计与覆盖;repowise next [PATH]:从索引排出的"接下来值得做的事",与 Web 概览、MCP get_overview 的 next_actions 同源一致。--horizon quarter 看 90 天窗口,--all 最多 20 行。

ask、context、symbol、why 是 MCP 同名工具的精简适配器,共享 --path、--repo、--no-workspace、--format、--full。--format json 输出的是精简 CLI 投影而非工具完整响应(实测本仓库:ask 3.4 KB vs --full 19.5 KB,context 单文件 0.9 KB vs 12.4 KB,symbol 0.7 KB vs 1.0 KB);但改变答案的东西(错误、未找到、did-you-mean 列表、截断标记、continuation token、歧义信号)在任何格式下都完整保留。

七、分析与健康命令

  • repowise health <a href="https://link.gitcode.com/i/a74e5d0bbdd451ce7aa63bec5c7f5af9" target="_blank">PATH]:由 51 个确定性检测器计算逐文件代码健康分(McCabe 复杂度、嵌套、脑方法、LCOM4 内聚、上帝类、原生克隆检测、未测试热点、覆盖梯度、组织风险、测试质量气味等),默认零 LLM 调用。--file 深挖单文件、--module 限定前缀、--scope all|production、--counts code_shape(忽略 git 派生的一半扣分)、--refactoring-targets(打印索引存储的重构队列)、--generate-code(唯一调用 LLM 的 health 旗标,为单个目标生成重构补丁)、--trend(最近 10 个快照 + 告警)、--badge(shields.io 徽章)。init/update 自动填充健康表,status 显示一行摘要。详见 [docs/layers/CODE_HEALTH.md 与 docs/architecture/code-health.md。
  • repowise risk <a href="https://link.gitcode.com/i/f5e47bb8098c4fe53a858b5d01b1ffdc" target="_blank">REVSPEC]:即时变更风险评分,纯 git + 学习常数,无需 init 也能跑。无 REVSPEC 时给未提交工作打分(树干净则回退 HEAD)。头条是仓库相对的:变更在仓库近期提交中的百分位与评审优先级(Below typical/Typical/Elevated)。--ext 限定后缀、--exclude/-x 排除、--baseline(默认 200)、--target/-t 改问"关于这些文件的历史"(读索引,需 init)、--changed-file(PR 模式 + 指令)、--fail-above-percentile(CI 门禁)。--target 报告 bug 修复压力、churn 趋势、依赖者、共同变更伙伴与所有权,是 get_risk MCP 工具。评分模型见 [docs/layers/CHANGE_RISK.md。
  • repowise dead-code [PATH]:死代码与未使用代码检测。--min-confidence(默认 0.4)、--safe-only、--kind unreachable_file|unused_export|unused_internal|zombie_package、--format table|json|md。
  • repowise doc-drift [PATH]:找出仓库自身文档树不再满足的引用(消失的路径、被重命名的标题锚点、清单中不再声明的 make 目标)。默认读上次 init/update 存储的结果,--check 直接读工作树、无需索引、门禁失败时非零退出——正是 CI 模式。--format 支持 table|json|markdown|github|sarif|gitlab(GitLab Code Quality 报告),--baseline/--write-baseline 支持基线,--since 只门禁本次变更应负责的漂移。
  • repowise security:安全信号扫描。security scan --history 走完整 git 历史找泄露的密钥与后来被删除的危险模式;security check <a href="https://link.gitcode.com/i/d43a007892a894b18ab60fecef1219c4" target="_blank">REVSPEC] 是 CI 门禁——只依赖 git,无索引、无数据库、无 API key,秘密片段在所有格式下打码。repowise-security-ignore 行注释可静默某行;自定义密钥形状配置在 security.patterns(见 [docs/reference/CONFIG.md)。CI 用法详见 docs/layers/SECURITY.md。
  • repowise impacted-tests [REVSPEC]:打印变更真正触达的测试,让 CI 只跑"这 40 个"而不是全部 4,000 个。基于 repowise coverage add 建立的逐测试 test-to-code 映射;无 LLM 无网络。每种路径都诚实标注 via:(coverage/changed-test/import-graph/filename-pattern),无法判断时明确报告"unknown, run the full suite"。--format list|args 可直接喂给 xargs pytest。
  • repowise coverage:摄取与检查测试覆盖报告(LCOV/Cobertura/Clover/JaCoCo/Go coverprofile/coverage.py .coverage),add/status/check/suggest-gates 四个子命令。coverage check 门禁补丁覆盖:变更的可执行行中被测试跑过的比例。支持 --fail-under、--fail-under-risky、--fail-under-branches、--max-drop(配合 --base-report 防止项目覆盖倒退)、coverage.gates 路径级门禁与 --min-coverable-lines 小变更容差。CI 配方见 docs/start/CI.md。
  • repowise decision:管理架构决策记录。子命令覆盖 list、show、add、candidates(评审队列)、confirm(唯一把记录提升为 active 的接受事件)、dismiss、merge、dedupe、split、deprecate、health、status、export/import/migrate、config show|preset|discovery|agent-acceptance|capture-prompt、source list|set、llm。confirm 拒绝接受空记录:需要 reason、scope 与 evidence,缺失时以 {"error": "acceptance_refused", "blockers": [...]} 文档 + 退出码 1 拒绝,脚本化评审可区分拼写错误与失败。
  • repowise overlap:哪些其他打开的 branch 也在编辑这个变更触及的文件。纯 git 即可回答(无索引的新 clone 也能跑);可读索引时排序共享文件并附加历史共同变更对。

八、Agent 接线、蒸馏与钩子

  • repowise mcp <a href="https://link.gitcode.com/i/5f1128a85f969b220deaf544d47a8e8f" target="_blank">PATH]:启动 MCP 服务器(AI 编辑器集成)。省略 PATH 时向上找最近的已初始化 .repowise 仓库。--transport stdio(默认,编辑器用)/streamable-http/sse(默认端口 7338);--tools 覆盖暴露的工具(逗号列表为显式白名单,+/- 调整默认集,lean 选六工具 agent-lean 档)。工具全集见 [docs/agent/MCP_TOOLS.md。
  • repowise distill <command>:运行命令并输出紧凑、可逆的渲染;丢弃噪声(pass 游行、进度刷屏、样板),错误/失败/摘要总是保留,命令退出码不变。被丢弃内容存 .repowise/omissions/,以内联 <a href="https://link.gitcode.com/i/6a617f3576fe66a99e8264c2193ae19e" target="_blank">repowise#<ref>: ...] 标记引用。repowise expand REF 还原标记背后的原始输出。机制详解见 [docs/agent/DISTILL.md。
  • repowise saved [PATH]:报告你的编码 agent 省下的输入 token 及其价值,走与 dashboard 概览同一报告服务(三者不可能不一致)。--by operation|surface|agent|model|day,--missed 报"本可蒸馏却没被改写"的命令。repowise savings sync 把 agent 会话里显示过但未记账的节省补记入账(--budget 秒数、--dry-run)。
  • repowise corrections [PATH]:挖掘本地 agent 会话中的重复命令失误(首个失败、后续变体成功的同基命令)。默认只报告、完全本地;--write 维护 .claude/CLAUDE.md/AGENTS.md 的"已知命令修正"块。
  • repowise hook install|status|uninstall|stats|backfill|rewrite:自动同步命令组。install 装 post-commit 钩子(后台跑 repowise update),--security 额外加 pre-commit 安全检查块(repowise security check --staged,high 级发现阻断提交,git commit --no-verify 可跳过)。hook rewrite install 管理 Distill 命令改写钩子(Claude Code + Codex PreToolUse),把 git status、pytest 等噪声命令改写为 repowise distill <command>。同步方法全景(hooks、文件监听、webhooks、轮询)见 docs/scale/AUTO_SYNC.md。
  • repowise generate-claude-md [PATH]:生成/更新 CLAUDE.md(默认 .claude/CLAUDE.md),Repowise 标记之上的自定义指令保留、标记间的受管段自动更新;--workspace 生成带跨仓契约的工作区级文件。repowise init --codex 生成受管 AGENTS.md。
  • repowise agents:管理机器上已接线的 agent 集成(Claude Code、Codex、Cursor、OpenCode、Hermes 等):add、remove、refresh、print-config(为 repowise 无专用集成的宿主打印 MCP 配置片段,不写文件)。支持矩阵见 docs/agent/INTEGRATIONS.md。
  • repowise augment:钩子驱动的上下文富集引擎,由 init 安装的 Claude Code/Codex 钩子调用,不面向手工调用(另有 repowise-augment/repowise-rewrite 两个独立控制台脚本支撑钩子热路径)。

九、Workspace 多仓库命令

repowise workspace 组管理多仓库工作区:

  • workspace list:列出全部仓库与索引状态;
  • workspace add <path>:加入新仓库并索引;默认 --index --docs(配置了 provider 时一步完成索引 + LLM 文档,花 token 前有成本闸门提示);provider/model/embedder/排除模式继承自主仓库 config;--no-docs 跳过生成、--no-index 只登记;
  • workspace remove <alias>:从工作区移除(不删文件);workspace scan [PATH]:重扫目录发现未加入仓库(--yes 自动添加);workspace set-default <alias>:切换 MCP 查询默认仓;
  • workspace diagnostics:解释跨仓契约链接数(provider/consumer 计数、未匹配消费者分类、孤立 provider);
  • workspace check:架构 lint——按 conformance: 规则对照系统图查依赖环,发现即非零退出,可门禁 CI;
  • workspace metrics [PATH]:系统图上的架构复杂度指标(传播成本、循环核心、1-10 确定性分数),需先跑 update --workspace 建系统图;
  • workspace impacted-tests <repo:path>...:给定变更的 provider 文件,列出消费者仓库值得跑的测试(--call-depth 默认 3、--import-depth 默认 1、--min-confidence 默认 0)。

多仓库完整指南见 docs/scale/WORKSPACES.md。

十、维护、成本与生命周期命令

  • repowise doctor [PATH]:wiki 设置健康检查。--repair 修复:重建 FTS、重嵌缺失页面、同步漂移的工作区状态、丢弃死条目。还包含 CLI 版本对比行(对照 PyPI 最新 release,仅建议、从不自动更新)与 distill: 配置校验。升级后请重启 Claude/Codex/Cursor 或任何 MCP 客户端以加载新可执行文件。
  • repowise reindex [PATH]:重嵌全部 wiki 页面重建向量索引。--embedder、--batch-size(默认 32)。真实嵌入器写入全部条目后,index_scope 会重新标记语义搜索可用,清除失败的 init/update 留下的记录。
  • repowise costs:LLM 花费跟踪。--by operation|model|day、--repo、--all。repowise export <a href="https://link.gitcode.com/i/10817ba5383d4587196217a791301b9a" target="_blank">PATH]:导出 wiki 页为 markdown/html/json,或把架构模型导出为 Structurizr DSL(--standalone 生成带默认视图的完整 workspace;--components 加组件层;见 [docs/architecture/structurizr-export.md)。
  • repowise whats-new:离线从安装自带的变更日志读未见过的版本说明。repowise telemetry status|enable|disable:匿名、可随时关闭的使用遥测。repowise config hints on|off:关闭偶发的一行提示(也可用 REPOWISE_NO_HINTS=1)。
  • repowise login(浏览器 OAuth + PKCE,--with-token 支持无头机器粘贴 rw_live_... key)/ logout / whoami:托管 repowise.dev 账户(与 LLM provider key 无关,本地功能不需要登录)。repowise publish [PATH]:把当前仓库发布到 repowise.dev(读 GitHub origin remote,本地不传任何内容,仅索引已推送的部分)。
  • repowise delete [REPO_ID]:删除仓库索引与全部存储智能(wiki、图、嵌入、git 元数据),不碰源文件;支持共享 REPOWISE_DB_URL(PostgreSQL)下的 --path 选择。
  • repowise uninstall [PATH]:移除 repowise 写过的东西,四组独立选择(agents/repo-files/index/global)。没有 --yes——部分卸载不是安全默认值,作用域必须具名;--keep-index 是重装场景(只拆接线与生成块)。退出码:0 全移除、1 有失败、3 有拒绝、4 未给作用域且无人可问。它永不触碰:pip/uv/pipx 管理的包本体与 Claude Code 插件(各打印对应卸载命令)。
  • repowise cost 之外的 next/status 上文已述。完整升级流程见 docs/reference/UPGRADING.md。

十一、源码级深入:main.py 与懒加载命令注册

CLI 根组定义在 main.py,有几处值得注意的实现细节:

1. BLAS 线程上限先行。模块第一行就是 from repowise.core.blas_threads import limit_blas_threads 并立即调用——必须在任何其他 repowise import 之前执行。原因注释写得很清楚:numpy 的 BLAS 运行时会按宿主机核数分配私有的每线程工作区,32 核机器上约 750 MB 常驻内存永不归还,而这套管线单线程工作在亚秒级。limit_blas_threads() 正是为阻止"某个 import 抢先触达 numpy"的 bug。

2. 懒加载命令注册(InstrumentedGroup)。_OSS_COMMANDS 元组保存 命令名 -> "module:attr" 映射,通过 register_lazy_command 注册到共享 registry,由 InstrumentedGroup(见 packages/cli/src/repowise/cli/_instrumented_group.py)逐个解析。注释指出:过去注册对象会触发全部约 35 个命令模块的 import(1.1 秒),而每次调用——包括每次 agent 钩子触发和 MCP 启动——都要付出这个代价;改为字符串懒加载后,单次 --help、分发或 shell 补全只需导入被调用的模块。元组左侧名字必须等于 Click 命令自身的 name(--help、分发与补全都依赖它),并有对应单测断言(tests/unit/cli/test_lazy_commands.py)。

3. 启动自愈(self-heal)。cli() 在被调用时会静默运行 run_editor_migrations(),修复旧版本写坏、新版本改型的 agent 钩子条目,幂等且打上迁移戳记。两个例外:augment(钩子热路径,由 augment_hook.main 处理)与 uninstall(修复钩子正是用户想删除的东西,且迁移戳记会落在 uninstall 即将删除的 ~/.repowise/ 目录里)。

4. 模块回退。python -m repowise.cli.main 是控制台脚本被遮蔽时的文档化回退,__main__ 分支保证它真正执行 cli()。

本地开发时,从仓库根目录执行 uv sync --all-packages 会以 editable 模式安装全部包(详见 CONTRIBUTING.md,位于仓库 .github/ 目录),随后即可直接运行 python -m repowise.cli.main 或已装入虚拟环境的 repowise 命令调试。

十二、延伸阅读

登录后查看全文
repowise