RepoWise 配置完全指南:`.repowise/config.yaml`、LLM Provider 与全量环境变量详解
RepoWise 配置完全指南:.repowise/config.yaml、LLM Provider 与全量环境变量详解
本指南以 RepoWise 的官方配置参考 docs/reference/CONFIG.md 为主体,系统讲解 .repowise/ 目录结构、config.yaml 全部核心键、health-rules.json 代码健康规则、八类 LLM Provider 的接入方式,以及环境变量、排除模式与多仓库工作区配置。读完本文,你将能够从零初始化一个仓库、按需切换任意 Provider 与嵌入模型、精细调校决策捕获与代码健康规则,并理解这些配置在底层源码中的实际作用机制。
一、.repowise/ 目录:一切配置与索引的落点
init 首次运行时,RepoWise 会在仓库根目录创建 .repowise/,其中保存了 RepoWise 对该仓库掌握的全部信息:
.repowise/
├── wiki.db # SQLite 数据库:所有页面、符号、图、git 元数据、决策
├── lancedb/ # 向量搜索索引(LanceDB)
├── omissions/ # Distill 省略存储 + 节省台账(omissions.db)
├── config.yaml # Provider、模型、嵌入器、排除模式、distill/mcp/refactoring 块
├── health-rules.json # 逐文件代码健康标记覆盖
├── state.json # 上次同步 commit、页面计数、token 用量
├── mcp.json # MCP 服务器配置
└── .env # API 密钥(自动加入 gitignore)
RepoWise 会自动把 .repowise/ 追加到仓库的 .gitignore。该目录是本地缓存而非事实源,不应提交。唯一的例外是 .repowise/decisions.yaml——它保存你已接受的架构决策,设计上应该提交(详见下文"决策捕获"章节)。
从源码看,.repowise/ 目录路径由 core/repo_config.py 中的 get_repowise_dir() 统一计算,所有配置读写都经过这一入口。
config.yaml 的加载与校验机制
config.yaml 是主配置文件,首次 init 后生成,传入 --commit-limit、--follow-renames、--wiki-style 等 flag 时会被更新。其加载逻辑位于 core/repo_config.py:
- 文件不存在时返回空字典(等价于全部使用默认值);
- 通过
yaml.safe_load解析,结果必须是一个 YAML 映射,否则抛出RepoConfigError(专门区分"没有配置文件"与"配置文件损坏"两种情况); - 有限模式校验:未知或拼错的键会被静默忽略,不报错也不生效,唯一例外是
security:块(见后文);max_tokens必须为正整数;distill:块仅在运行repowise doctor时校验; - 一个贴心细节:
reasoning: false/reasoning: true会被源码自动映射为off/auto,避免直接抛ValueError。
config.yaml 的写入是原子操作:先序列化到同目录临时文件、fsync 后 os.replace 替换原文件(见 repo_config.py),崩溃或序列化失败不会留下半截配置。直接编辑文件后,改动在下次 init、update 或 serve 时生效。
RepoWise 还通过 config_fingerprint() 对 config.yaml + health-rules.json 的原始字节做 SHA-256 哈希(repo_config.py),update 用它检测配置是否变化;更细的 config_dependency_fingerprints()(repo_config.py)把配置键分组(traversal / git_history / health / generation / state_only),使得"仅格式化 YAML"的改动不会触发全量分析重建。
二、config.yaml 核心键速查
一个典型的完整配置如下(对应官方文档的示范配置):
provider: anthropic # LLM provider(省略时自动检测)
model: claude-sonnet-4-6 # 模型标识(省略时用 provider 默认值)
embedder: mock # 嵌入 provider(未检测到密钥时用 mock)
embedding_model: text-embedding-3-small # 嵌入模型(省略时用 provider 默认值)
reasoning: auto # auto | off | none | minimal | low | medium | high | xhigh | max
max_tokens: 16384 # 每个生成文档页的最大输出 token
commit_limit: 500 # 每文件 git 分析的最大提交数(钳制 1-10000)
follow_renames: false # 在 git 历史中追踪文件重命名
wiki_style: comprehensive # comprehensive | caveman | reference | tutorial | custom
language: en # 生成页面语言(en, zh, ru, hi, ...)
enable_onboarding: true # 显示首次运行引导提示
max_file_pages: 2000 # 文件页上限(省略=按规模策略,0=每文件一页)
generation_context: # 综合页面的可选源证据
token_budget: 8000
files:
repo_overview:
- docs/ARCHITECTURE.md
onboarding/how_it_works:
- docs/runtime-flow.md
exclude_patterns: # gitignore 风格模式
- vendor/
- "*.generated.*"
- proto/
distill: # 见"distill 块"
enabled: true
mcp: # 见"mcp 块"
tools: ["+get_execution_flows", "-get_dead_code"]
refactoring: # 见"refactoring 块"
enabled: true
assertions: # 见"assertions 块"
extra_names: []
各键默认值与含义汇总:
| 键 | 默认值 | 含义 |
|---|---|---|
provider |
自动检测 | anthropic, openai, gemini, openrouter, deepseek, kimi, ollama, litellm, opencode |
model |
provider 默认 | 传给 provider 的模型标识 |
embedder |
mock |
openai, gemini, ollama, openrouter, edenai, mock |
embedding_model |
provider 默认 | 嵌入模型标识 |
reasoning |
auto |
auto, off, none, minimal, low, medium, high, xhigh, max |
max_tokens |
16384 |
每个模型撰写文档页请求的最大输出 token |
commit_limit |
500 |
每文件 git 分析走过的最大提交数,钳制到 1-10000 |
follow_renames |
false |
通过 git 历史追踪文件重命名 |
exclude_patterns |
[] |
额外的 gitignore 风格模式,叠加在 .gitignore 之上 |
wiki_style |
comprehensive |
comprehensive, caveman, reference, tutorial, custom |
language |
en |
生成 wiki 页语言:en, ar, de, es, fr, hi, it, ja, ko, nl, pl, pt, ru, tr, zh |
enable_onboarding |
true |
显示首次运行引导提示(CLI 与 Web) |
max_file_pages |
未设置 | 一次运行最多产出的文件页数,按重要性优先。三种状态:未设置交给规模策略决定(可文档化文件低于 4500 时不裁剪、超过时限制到 4500,约百分之一的仓库会命中);0 表示每个合格文件一页;正数是硬上限。repowise init 在文档化文件超过 2000 时于高级模式给出更紧的上限,--max-file-pages N 可非交互设置。裁剪文件页不减少模型开销:文件页由结构渲染生成 |
generation_context |
见下文 | 追加到模型撰写概览与引导页提示中的仓库源证据 |
distill |
见下文 | 输出蒸馏配置 |
mcp |
见下文 | MCP 工具面配置 |
refactoring |
见下文 | 重构智能配置 |
reasoning 的深层语义
reasoning 控制具备推理能力的聊天模型在文档生成调用中的推理强度:
auto保留 provider 默认;off/none针对 OpenAI 兼容的 vLLM/SGLang 端点关闭 Qwen3 风格 thinking(发送extra_body.chat_template_kwargs.enable_thinking=false),并映射到 OpenRouter 的reasoning.effort=none;minimal、low、medium、high、xhigh、max向支持它的 provider 与模型族(如 OpenAI 推理模型、OpenRouter 的reasoning.effort)请求对应强度;- 无法翻译显式模式的 provider/模型会在发起 API 调用前直接失败,而不是带病运行。
地面化生成上下文(Grounded generation context)
当高层页面需要其组装的结构上下文通常不包含的仓库事实时,用 generation_context.files 显式补充。这是显式证据选择,不是自动发现:
- 键名对应模型撰写的综合页:
repo_overview或onboarding/<slot>(getting_started、key_concepts、how_it_works、active_landscape);onboarding/project_overview无效(该槽位就是repo_overview页);onboarding/glossary被接受但无效果(该页完全由挖掘的词汇渲染,没有模型参与);未知键或畸形值会让生成以配置错误失败而不是被忽略; - 已退役的
onboarding/guided_tour、onboarding/codebase_map、onboarding/development_guide键仍会被接受并忽略(带警告),确保升级不会把旧配置变成失败生成; - 每个值是有序的仓库相对路径列表。文件只有被纳入索引源映射且包含非空 UTF-8 文本才合格;绝对路径、越级路径、重复项、缺失/被排除文件、空文件、二进制/非 UTF-8 内容都会被跳过,页面元数据会记录包含、截断与每个被跳过路径的原因;
token_budget是独立按页上限(默认8000),按 RepoWise 常规的"四字符一 token"启发式估算,不削减结构上下文预算;配置顺序决定预算不足时哪些条目存活;零预算禁用全部配置证据;- 对
onboarding/how_it_works,检测到的流程符号会自动贡献精确源码摘录:存在此类引用时,预算的一半预留给精确摘录,其余一半给配置文件; - 渲染证据字节属于 prompt 与其源哈希的一部分:文件、列表或预算变化使渲染块变化时才使缓存失效。仅编辑
config.yaml不会重新生成已有页面,需运行repowise generate --all或请求受影响页面;--no-prose确定性页面不消耗证据; - 仓库文件与精确源码摘录仅作为仓库事实权威,被当作不可信的 prompt 指令处理——配置中仅选择你信任其归属与准确性的文件。
其他关键行为
max_tokens是持久化仓库设置而非单命令 flag:init、update、generate、restyle、工作区生成与服务器触发生成全部使用同一值;生成达到 token 上限时,未完成的页面会被拒绝保存而不是保存残页;wiki_style用init --wiki-style设置,或事后用repowise restyle <style>切换(会重新生成 wiki);高级用户可在.repowise/styles/<name>/style.yaml自定义风格,完整指南见 docs/layers/WIKI.md。注意:直接手改这里的wiki_style再跑update不会重新生成已有页面,要用restyle;language控制生成 wiki 内容的自然语言(代码、文件路径与符号名保持不翻译),同时作用于模型撰写页面和模板渲染页面(有标签目录的语言才生效)。设置后update会用同语言重新生成变更页面;之后修改语言不会重译已有页面,需repowise init --force --language <code>重建。未知代码回退到英文并告警;- 代码健康规则不在
config.yaml中,而是独立配置在.repowise/health-rules.json(见下文); --skip-tests、--skip-infra、--include-submodules是仅限单次运行的 CLI flag,不写入config.yaml;--include-submodules记录在state.json(工作区状态)而非config.yaml。
三、distill: 块:控制输出蒸馏
distill: 块控制本仓库的输出蒸馏(完整原理见 docs/agent/DISTILL.md)。块缺失时一切采用合理默认值;repowise doctor 会校验它:
distill:
enabled: true # 本仓库主开关
commands:
enabled: true # 命令路径(CLI + hook 重写)
permission: allow # ask | allow | off(重写 hook 姿态)
families: # 按过滤器覆盖
test_output: allow # 自动允许测试运行重写
git_diff: deny # 绝不在此重写 git diff
disabled_filters: [] # 完全跳过的过滤器,如 [logs]
omission_store:
ttl_days: 7 # 若干天后清理存储的省略
max_mb: 50 # 大小上限;最旧条目先被清理
要点:
permission: allow(默认)统一自动批准主 agent 与每个子 agent 的重写。这不是权限升级:重写永远是repowise distill <一个被识别的命令>,来自封闭的过滤器集合,绝不会在包装器后走私任意命令。设ask则每次重写命令都需确认,off则在本仓库禁用重写;families键是过滤器名(test_output、build_output、lint_output、install_output、infra_plan、git_status、git_log、git_diff、search_results、file_listing、logs),接受ask | allow | off | deny。repowise doctor会对照实时过滤器注册表校验它们;- 在
repowise init的选择提示中拒绝会写入commands.enabled: false,使全局安装的重写 hook 在本仓库保持惰性。
四、hooks: 块:Agent Hook 的粒度控制
hooks: 块控制 agent hooks 的选入行为(详见 docs/agent/HOOKS.md)。块缺失表示以下键全部关闭:
hooks:
read_skeleton: false # 大索引文件以骨架形式提供
read_reread: false # 未变化的重复读取以指针形式提供
search_digest: false # 多文件 grep 洪泛以摘要形式提供
coverage_reingest: false # agent 完整测试运行后重新摄入覆盖率
coverage_reingest:agent 完整测试运行后重新摄入覆盖率,按每个 shell 命令的进程启动生效(单会话可用REPOWISE_HOOK_COVERAGE_REINGEST=1)。详见 docs/layers/TEST_INTELLIGENCE.md;read_reread:让 PostToolUse Read hook 在本会话同一范围已提供过、期间无 Edit/Write、且字节哈希相同时,以简短通知代替内容响应重复 Read。不做任何猜测:决策是对 agent 实际收到内容的哈希比较;文件内容有差异就完整提供;同一文件不会连续两次命中(假设先前副本仍在 agent 上下文中,上下文压缩会移除它——hook 无法检测,所以再次读取总是返回内容并说明)。节省记入repowise saved的read_reread过滤器。需要 Claude Code 2.1.218+;REPOWISE_HOOK_READ_REREAD=1可单会话覆盖;read_skeleton:让 PostToolUse Read hook 对大型索引文件的无界 Read 返回骨架(每个文件每会话一次):签名保留,函数体变成... N lines (a-b)标记(1 起始区间),可用区间 Read 拉回任何省略跨度;第二次读取会返回完整文件。节省记入read_skeleton过滤器。关闭状态下,本可骨架化的 Read 仍会被测量,repowise saved在 "Not saved" 下报告总量。REPOWISE_HOOK_READ_SKELETON=1单会话覆盖;需要 Claude Code 2.1.218+(更老的客户端静默回退到get_context(include=["skeleton"])的单行指针);- 此块由
repowise init中的重写 hook 提问写入:同意即开启;--no-editor-setup与--no-distill-hook会连同其他一切关闭它。单仓库改主意可用repowise hook read-skeleton install | uninstall | status。
五、mcp: 块:裁剪 MCP 工具面
mcp: 块控制 MCP 服务器通告哪些工具。默认工具面是精选的(单仓库模式 10 个工具,工作区模式加 list_repos;另有 7 个选入工具),本块可把额外工具选入或裁剪掉。repowise mcp --tools / --all flag 可对单次启动覆盖:
mcp:
tools: ["+get_execution_flows", "-get_dead_code"] # 调整默认集合
# tools: ["get_answer", "get_context"] # 或显式白名单
# tools: all # 或全部可用
# tools: lean # 或 agent-lean 精简档
+name/-name条目在默认集合上增删;无前缀列表视为显式白名单;lean选择 agent-lean 档:get_answer、get_context、get_symbol、search_codebase、get_risk、get_why(工作区模式加list_repos),小到 Claude Code 可常驻加载全部 schema;- 选入工具为
get_dependency_path、get_execution_flows、generate_refactoring_code、set_finding_status,以及仅工作区模式可用的get_blast_radius、get_conformance、get_architecture。三者默认全关;工作区专属三个在单仓库模式被命名会被忽略。详见 docs/agent/MCP_TOOLS.md。
六、decisions: 块:决策捕获策略
decisions: 块控制决策捕获:是否运行、使用哪些来源、哪些来源可调用模型。一个解析后的策略同时支撑 CLI、API 与索引管线,保证三者对"将要运行什么"意见一致:
decisions:
enabled: true # 自动捕获主开关
llm: true # 决策抽取模型调用主开关
preset: balanced # default | off | local_only | balanced | full
sources:
inline_marker: true # WHY:/DECISION: 标记
git_archaeology: true # 提交消息
adr: true # ADR 文件
pr: true # PR / squash-merge 正文
comment: false # 中央文件的注释考古
session: # 默认关闭;长形式运行确定性
enabled: true # 解析并跳过模型阶段
llm: false
session_discovery: true # 对新转录文本的一次宽模型遍历
conventions: false # 图证明的导入模式,无模型
discovery: # 那次遍历的预算,每次 update
max_sessions: 12 # 1-24
max_input_tokens: 30000 # 2000-60000
harnesses: # session 通道读取谁的转录
- claude_code # 默认;加 codex 可同时读那个存储
agent_acceptance: false # agent 可否授予决策权威?
capture_prompt: false # 请求 agent 记录它刚提交了什么
关键语义
agent_acceptance是此处唯一与"捕获"无关的键。关闭时 agent 可以提议候选并撤回权威但永远不能授予;开启时它可以接受,且接受会被记录为"agent 的"(附签名会话),绝不会记成你的。出厂关闭,没有任何预设会打开它;capture_prompt同理:开启后,消息携带两个以上决策信号的git commit会提示 agent(每会话一次)运行repowise decision add——从不为已被记录引用的提交,也永远只是提议。agent 无法拒绝 hook,所以它同样出厂关闭:repowise decision config capture-prompt --on开启。该命令同时安装所需内容:共享 PostToolUse 匹配器刻意排除 shell 工具(实测占 hook 调用的 51% 却只有 0.7% 的排放),所以开启提示会额外添加一个Bash|PowerShellPostToolUse 条目,关闭则移除;该条目按安装而非按仓库生效;- 每个键都可选。无
decisions:块的配置行为与这些开关出现前完全一致(每个出厂开启的来源都开,模型阶段开启),该解析策略名为default。这些开关之后新增的来源(session_discovery、conventions)保持关闭直到你主动要求,升级绝不会开启无人授权的模型调用。session是唯一默认值移动过的来源:现在出厂关闭(它捕获的内容读起来像转录中的工作约定而非代码库已做的决策)。repowise decision source set session --on重新开启,local_only预设仍携带它; - 来源是裸布尔或
{enabled, llm}映射。长形式只对既有确定性又有模型阶段的来源(inline_marker、adr、session)有意义:保留确定性解析、跳过模型调用。纯模型来源(git_archaeology、pr、comment、session_discovery)在模型阶段关闭时整体跳过; - 未知键以警告而非丢弃形式报告;已退役名(
code_comment、changelog、readme_mining)同样如此——旧配置仍能加载,只是会指出忽略了哪个键。实现见 core/analysis/decisions/policy.py,源码确认了"预设只是写同一组键的便捷方式,下游不按预设名分支"的设计。
预设一览
| 预设 | 效果 |
|---|---|
default |
无 decisions: 块配置解析到的结果。所有长期来源开启;session 挖掘与宽泛发现关闭 |
off |
无自动捕获。已存决策与手动录入继续工作 |
local_only |
仅确定性捕获,含 session 挖掘——它是唯一无需密钥即可产出的通道。零决策抽取模型调用 |
balanced |
高信号来源加 session 挖掘与宽泛会话发现(后者由前者供给);注释考古关闭 |
full |
每个来源、每个模型阶段全开 |
编辑预设后的任何单个键都会删除 preset 行,解析策略变为 custom。
llm: false 是完整模式而非退化模式:转录仍被读取、标记与 ADR 仍被解析、episodes 仍被记录、手动决策仍可用、已接受决策继续约束。它是唯一证明"没有任何决策抽取触及模型"的开关。
推荐用 CLI 而非手改
repowise decision config show # 解析后的策略,按来源
repowise decision config preset local_only
repowise decision source set comment --off
repowise decision source set adr --no-llm # 保留解析,跳过模型
repowise decision source set session_discovery --on
repowise decision config discovery --max-sessions 6 --max-input-tokens 12000
repowise decision llm --off
所有变更命令都支持 --dry-run(只打印不写入)与 --format json(供脚本使用)。写入是原子的,并保留 config.yaml 中每个无关键。旧键 decisions.session_mining: true|false 仍被识别,双向解析到 session 来源;首次经 CLI/API 写入会用 sources.session 替换它。
.repowise/decisions.yaml:唯一应该提交的文件
.repowise/ 下其余一切都是可删除重建的本地索引,唯 decisions.yaml 例外:它保存你接受的决策,设计上应提交。repowise decision export 写入它,并会在 .gitignore 规则隐藏它时取消忽略;repowise decision import 以它为权威对账存储。其格式自带 version,新版 RepoWise 写的文件会被拒绝而非降级读取。往返流程见 docs/layers/DECISIONS.md。
Session 挖掘与会话发现
session挖掘默认关闭。开启后repowise update读取编码 agent 的会话转录(Claude Code 的~/.claude/projects/),寻找持久决策:用户纠正、带理由的明确选择、被更优方案取代的失败路径。候选先过确定性闸门,再每次 update 一次批量 LLM 结构化调用,每个产出字段必须逐字引用转录否则丢弃。挖掘的决策存为候选,repowise decision confirm接受后才具约束力。一切都在本地:转录从你的机器读取,暂存在.repowise/sessions/sessions.db,只存蒸馏后的代码库决策文本;session_discovery是闸门旁的宽泛通道:每次 update 把新读到的用户与 assistant 散文(受discovery.max_sessions与discovery.max_input_tokens约束)单次调用发给模型,询问闸门未浮出的持久决策。它复用session来源已执行的转录读取,开启不会重复读转录。每个返回候选必须引用其依赖的 span id,引文在存储前逐字校验;引用未发送 span、引用 span 未说内容或命名所引用 turns 未触碰文件的候选会被拒绝并计数,永不存储。装不进一次 update 预算的散文不会丢弃:排队在.repowise/sessions/sessions.db,下次 update 按最旧优先发送,排队 span 在读取前永不过期;provider 失败会保留排队内容并在随后两次 update 重试。关闭来源不会清空已排队内容(新散文只在来源开启时捕获);- 驳回是粘性的:
repowise decision dismiss保留dismissed墓碑记录,重索引不会重新提议同一决策;已确认(active)的决策绝不会被重新抽取回退为proposed。
七、security: 块:自定义密钥形状
security: 块为 repowise security check 定义你自己的密钥形状:
security:
patterns:
- name: internal_token # 1 到 40 个 a-z、0-9、_ 和 -,需唯一
regex: 'itk_[A-Za-z0-9]{32}'
severity: high # low, med 或 high;省略时 high
- 每个模式是密钥种类
custom:<name>(SARIF 规则custom/<name>):仅变更行,变更的每个提交都扫描,命中在所有格式中被掩码为前四字符加****。测试、fixture 与示例路径下保持其严重度; - 命中按文件、种类和掩码行键控,同前缀的两个命中共享一个基线条目;
- 未知键、缺失 name/regex、重复或畸形 name、错误严重度、无法编译的正则、匹配零字符或嵌套重复(如
(a+)+、(a|aa)+,尽力而为)都退出码 2(config_invalid,列出全部问题); - 最多 50 个模式、每个 500 字符;超过 4096 字符的行不匹配并被计数(JSON 中记
long_lines_skipped)。以上常量在 core/analysis/security_gate.py 中定义:MAX_CUSTOM_PATTERNS = 50、MAX_CUSTOM_REGEX_LENGTH = 500、MAX_CUSTOM_LINE_LENGTH = 4096,与文档数值完全一致。
八、refactoring: 块:重构智能
控制重构智能层:由 repowise health --refactoring-targets、get_health(include=["refactoring"]) 与 Web 的 Refactoring 页呈现的 Extract Class / Extract Helper / Move Method / Break Cycle / Split File 结构化方案。确定性检测器在常规 health 通道内运行;本块只调谐哪些触发,以及可选的代码生成步骤:
refactoring:
enabled: true # 确定性方案(零 LLM,在 health 通道内)
detectors:
disabled: [] # 如 [move_method] 静音某个检测器
min_confidence: null # low | medium | high(置信度下限;null = 无下限)
llm:
enabled: true # 代码生成,默认开启;设 false 禁用
provider: null # 回退到仓库配置的 LLM provider
model: null # 回退到仓库配置的模型
- 确定性层是零 LLM 的,运行在
init/update的 health 通道中。代码生成是唯一调用 provider 的部分:默认开启但绝不在索引期间运行,只在显式请求时运行(设llm.enabled: false禁用); enabled: false跳过整个确定性检测器通道;detectors.disabled静音具名检测器(extract_class、split_file等),其余照跑;min_confidence是检测时施加的下限,低于它的方案永不持久化(就像被禁用的标记);改动在下次init/update生效。接受min_confidence查询参数的界面只能从该下限继续收窄,不能低于它;- 按路径禁用复用
.repowise/health-rules.json的 glob 机制(与标记用同一套); - 完整参考: docs/layers/REFACTORING.md。源码侧,
refactoring_enabled、disabled_refactorings、refactoring_min_confidence由 health 配置加载器读取(见 core/analysis/health/config.py),印证了"默认全开、无下限"的语义。
九、assertions: 块:自定义断言助手
为按测试断言数相除的测试质量标记命名你自己的断言助手:
assertions:
extra_names: [ensureInvariant, mustMatch] # 精确被调名,非前缀
- RepoWise 开箱识别 xUnit 与 BDD 家族(
assert*、expect*),外加每种语言补足这些惯例遗漏的惯用语(如 Go 的t.Fatalf、testify 的require)。两者都不遵循的团队助手对它不可见,完全由这些助手构成的测试会被读作"零断言"。本块就是逃生舱,与 SonarQube、Qodana 和 ESLint 的expect-expect规则各自提供的机制相同; - 名称精确且大小写不敏感,绝不是前缀。
ensureInvariant匹配ensureInvariant(...),不匹配ensureConnectionPool(...)。前缀匹配曾用三个真实测试语料测量,匹配到生产被测函数的次数远多于断言; - 名称无论作为调用本身还是接收者都匹配:
ensureInvariant(x)与ensureInvariant(x).isTrue()都计数; - 这里没有任何内容能改变健康分:这些名称只进入建议性断言总数;校准过的
large_assertion_block与duplicated_assertion_block标记读取的是另一套不接受配置的计数。加错名字损失的是信号,绝不会得到错误分数; - 修改列表会在下次
init/update重走受影响文件。源码中,_assertion_names()(core/analysis/health/config.py)接受单字符串或字符串列表,转为排序去重的小写名称,丢弃其他一切——配置拼写错误不会让分析失败。
十、health-rules.json:代码健康标记的逐路径调校
独立于 config.yaml 的 JSON 文件,调校代码健康生物标记:哪些运行、严重度、逐路径覆盖。畸形 JSON 永不抛异常,RepoWise 告警并回退到空配置:
{
"profile": null,
"disabled_biomarkers": [],
"severity_overrides": {
"high_churn": "low"
},
"rules": [
{
"path": "legacy/**",
"disabled_biomarkers": ["long_function"],
"severity_overrides": {
"duplication": "critical"
}
}
]
}
| 键 | 默认值 | 含义 |
|---|---|---|
profile |
null |
具名校准档案;目前只定义了 "small-team" |
disabled_biomarkers |
[] |
仓库级跳过的生物标记名 |
severity_overrides |
{} |
生物标记名 → 严重度标签 |
rules[] |
[] |
逐路径覆盖,按顺序求值 |
rules[].path |
必填 | 对文件路径匹配的 glob(别名 path_glob 与 glob 同样接受、同等对待) |
rules[].disabled_biomarkers |
[] |
对匹配 path 的文件跳过的生物标记 |
rules[].severity_overrides |
{} |
对匹配 path 的文件的严重度覆盖 |
有效严重度标签:low、medium、high、critical。只有严重度标签可如此覆盖,产生健康分的底层数值权重与上限永远不可覆盖。
源码细节(core/analysis/health/config.py):
- 多个匹配规则取并集:路径被三条规则匹配,则禁用集合并、严重度重映射合并(每生物标记最后匹配规则胜出);
- 模式采用 gitignore 语义(
pathspec的GitWildMatchPattern)匹配仓库相对 POSIX 路径,与exclude_patterns、.gitignore同一引擎,一个 glob 处处同义。单个*止于路径段:覆盖整棵子树应写src/legacy/**而非src/legacy/*; _PROFILES["small-team"]把小型团队无法支撑的流程/人员信号(developer_congestion、knowledge_loss、ownership_risk、change_entropy、co_change_scatter、primitive_obsession、bumpy_road)统一降为low,数值权重不动——只动标签;- 以
!开头的规则内 glob 会被警告:单规则编译成单模式 spec 时否定无可否定,规则永远不会生效。
完整参考: docs/layers/CODE_HEALTH.md。
十一、LLM Providers:八类接入方式全览
Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-..."
| 模型 | 备注 |
|---|---|
claude-sonnet-4-6 |
默认,质量与成本的最佳平衡 |
claude-opus-4-6 |
最高质量,更高成本 |
claude-haiku-4-5-20251001 |
最快,最低成本 |
repowise init --provider anthropic --model claude-haiku-4-5-20251001
OpenAI (GPT)
export OPENAI_API_KEY="sk-..."
repowise init --provider openai --model gpt-5.6-luna
对 vLLM 或 SGLang 服务的 OpenAI 兼容 Qwen3 端点:
export OPENAI_BASE_URL="http://localhost:8000/v1"
repowise init --provider openai --model qwen3 --reasoning off
同一适配器可用于本地网关(如 9router)与任意 OpenAI 兼容自定义 provider:密钥放 OPENAI_API_KEY,OPENAI_BASE_URL 指向其 /v1 端点,模型 id 用该端点 /models 响应的返回值:
export OPENAI_API_KEY="your-9router-dashboard-key"
export OPENAI_BASE_URL="http://localhost:20128/v1"
repowise init --provider openai --model ag/gemini-3.7-flash-medium
RepoWise 原样识别兼容网关的带命名空间模型 id,模型不必以 gpt- 开头。交互式 repowise init 中选 OpenAI-compatible (Custom / local gateway) 后,RepoWise 会校验端点、静默收集密钥、经 /models 验证网关、允许搜索发现的模型或输入精确模型 id:
Base URL [http://localhost:20128/v1]:
API key (hidden): <paste the gateway key>
✓ Connected — discovered 47 model(s).
Select model: ag/gemini-3.7-flash-medium
端点写入仓库 gitignored 的 .repowise/.env;密钥确认后才保存,--no-save-key 始终只留在进程内。脚本化运行(--yes、CI、非 TTY)保持非交互,继续使用环境变量与 --provider openai。
OpenRouter
export OPENROUTER_API_KEY="sk-or-..."
repowise init --provider openrouter --model openai/gpt-5 --reasoning minimal
repowise init --provider openrouter --model x-ai/grok-4 --reasoning off
Gemini (Google)
export GEMINI_API_KEY="AI..." # 或 GOOGLE_API_KEY
repowise init --provider gemini
设置 GEMINI_API_KEY 时 Gemini 也是默认嵌入 provider。
DeepSeek
export DEEPSEEK_API_KEY="..."
repowise init --provider deepseek --model deepseek-chat
Kimi
export KIMI_API_KEY="..."
repowise init --provider kimi --model kimi-for-coding
默认 Kimi Code 端点支持 kimi-for-coding 与 kimi-for-coding-highspeed,RepoWise 自动使用其必需的采样参数。K2.x 模型走独立的 Kimi Open Platform:
export KIMI_API_KEY="..."
export KIMI_BASE_URL="https://api.moonshot.ai/v1"
repowise init --provider kimi --model kimi-k2.6
Ollama(本地,无需 API key)
export OLLAMA_BASE_URL="http://localhost:11434"
repowise init --provider ollama --model llama3.2
RepoWise 按每个 prompt 调整模型上下文窗口(num_ctx),页面不会因 Ollama 的默认小窗口被截断。设 REPOWISE_OLLAMA_NUM_CTX 可固定它(例如限制在机器内存内)。请求默认逐个发送;若服务器 OLLAMA_NUM_PARALLEL 大于 1,在运行 RepoWise 处设置同值即可并行发送。
LiteLLM(100+ providers)
export LITELLM_API_KEY="..."
repowise init --provider litellm --model azure/gpt-4
Eden AI(托管,含欧盟端点)
Eden AI 是带欧盟端点的托管网关,推理可在欧盟内完成而无需自托管任何东西——这是在此选择它的原因:列表中其他托管 provider 都在美国终止,DPA 团队的自托管替代是 Ollama 或自建基础设施上的 LiteLLM。
export EDENAI_API_KEY="..."
export EDENAI_BASE_URL="https://api.eu.edenai.run/v3"
repowise init --provider edenai --model mistral/mistral-small-latest
不设该变量则请求走全球端点。除驻地外它还是聚合器:一个密钥经单一 OpenAI 兼容端点到达多家厂商(Mistral、GPT、Claude、Gemini、Cohere、DeepSeek、Llama),模型以 vendor/model 寻址。同密钥也把 edenai 选为语义搜索的嵌入器,默认 amazon/amazon.titan-embed-text-v2:0(欧盟区域服务,且是该适配器声明模型中最便宜的每 token 价)。只有 EdenAIEmbedder._DIMS 中的模型被接受——错误的维度数会静默错配存储向量;新增模型意味着把实测宽度加入该表。reasoning 对经 Eden 路由的 OpenAI 推理模型(如 openai/gpt-5*)转发为 reasoning_effort,其他模型只暴露 auto。
Provider 自动检测
不传 --provider 时,按序检测:
REPOWISE_PROVIDER环境变量.repowise/config.yaml中的provider- API 密钥环境变量:
ANTHROPIC_API_KEY→OPENAI_API_KEY→OPENROUTER_API_KEY→OLLAMA_BASE_URL→GEMINI_API_KEY→DEEPSEEK_API_KEY→KIMI_API_KEY→EDENAI_API_KEY
十二、Embeddings:语义搜索的嵌入器
嵌入器与 LLM provider 相互独立。
| 嵌入器 | 环境变量 | 备注 |
|---|---|---|
gemini |
GEMINI_API_KEY |
密钥存在时默认 |
openai |
OPENAI_API_KEY |
OpenAI text-embedding-3-small |
openrouter |
OPENROUTER_API_KEY |
经 OpenRouter 路由 |
ollama |
OLLAMA_EMBEDDING_MODEL |
本地 Ollama 嵌入,无需 API key |
mock |
n/a | 假嵌入,无语义搜索(未检测到密钥时默认) |
repowise init --embedder openai
repowise reindex --embedder gemini # 切换嵌入器并重建索引
config.yaml的embedder键记录的是"谁构建了向量存储",写入方与读取方都以此为准:search、serve与 MCP 服务器首先从它解析,只有未固定时才回退环境——否则无密钥索引的仓库会被"碰巧导出的任意密钥"查询,更宽的查询向量在更窄的存储表中什么也匹配不上;reindex会把所用嵌入器写回config.yaml。否则下次update读到旧固定值、以旧宽度写向量,存储被完全重建,丢弃 reindex 刚建的东西;REPOWISE_EMBEDDING_MODEL覆盖当前嵌入器的模型;REPOWISE_EMBEDDING_DIMS与REPOWISE_EMBEDDING_TIMEOUT同理;provider 前缀变体(OPENAI_*、GEMINI_*、OLLAMA_*、OPENROUTER_*、EDENAI_*)把设置收窄到单一嵌入器并优先于共享名。
十三、BYOK:密钥解析顺序
API 密钥按此顺序解析:
- 环境变量:运行 RepoWise 前设置
.repowise/.env:交互式设置持久化,自动加载- 交互提示:
init时未找到密钥则询问,然后保存到.repowise/.env
.repowise/.env 自动加入 gitignore。源码层面,repo_config.py 的 load_repo_env() 提供不修改 os.environ 的纯解析(export KEY=value、引号值、行内注释都支持)——这对常驻的 repowise serve 很关键:一个仓库的密钥不会泄漏到工作区其他仓库的解析中;save_repo_env_key()(repo_config.py)只重写匹配行、拒绝含换行的值(防止注入额外 KEY=value 行),并在密钥落盘后把文件权限收紧为 owner-only(0o600)。
十四、环境变量全表
Provider API keys
| 变量 | 描述 |
|---|---|
ANTHROPIC_API_KEY |
Anthropic API key |
OPENAI_API_KEY |
OpenAI 或 OpenAI 兼容网关 API key |
GEMINI_API_KEY / GOOGLE_API_KEY |
Google Gemini API key |
OPENROUTER_API_KEY |
OpenRouter API key |
DEEPSEEK_API_KEY |
DeepSeek API key |
KIMI_API_KEY |
Kimi API key |
LITELLM_API_KEY |
LiteLLM 代理密钥 |
LITELLM_API_BASE |
LiteLLM 代理 base URL |
Provider base URLs
| 变量 | 描述 |
|---|---|
ANTHROPIC_BASE_URL |
覆盖 Anthropic API base URL |
OPENAI_BASE_URL |
覆盖 OpenAI API base URL(用于 vLLM/SGLang、9router 等兼容端点) |
GEMINI_BASE_URL |
覆盖 Gemini API base URL |
OLLAMA_BASE_URL |
Ollama 服务器 URL(默认:http://localhost:11434) |
REPOWISE_OLLAMA_NUM_CTX |
固定 Ollama 上下文窗口;未设置则按每个 prompt 调整 |
OLLAMA_NUM_PARALLEL |
RepoWise 同时发送的 Ollama 请求数(默认:1) |
DEEPSEEK_BASE_URL |
覆盖 DeepSeek API base URL |
KIMI_BASE_URL |
覆盖 Kimi API base URL |
LITELLM_BASE_URL |
覆盖 LiteLLM 代理 base URL |
Provider 与模型覆盖
| 变量 | 描述 |
|---|---|
REPOWISE_PROVIDER |
覆盖 provider(跳过自动检测) |
REPOWISE_MODEL |
覆盖模型 |
REPOWISE_DOC_MODEL |
专门覆盖 get_answer 合成所用模型 |
REPOWISE_REASONING |
覆盖 reasoning(合法值见上) |
REPOWISE_ANSWER_TIMEOUT_S |
get_answer 等待合成放弃前的秒数。默认按 provider 预算:远程 API provider 60s、ollama/litellm 120s、codex_cli/opencode 180s。模型比其类别更慢可调高,宁可让 agent 快速失败则调低。上限 600s。注意 MCP 客户端在其下执行自己的工具超时,设更高会产生客户端侧错误而非 RepoWise 可诊断的 "synthesis exceeded its budget" 响应 |
Embeddings
| 变量 | 描述 |
|---|---|
REPOWISE_EMBEDDER |
嵌入器:gemini、openai、ollama、openrouter、edenai 或 mock |
REPOWISE_EMBEDDING_MODEL |
嵌入模型,适用于任何嵌入器 |
REPOWISE_EMBEDDING_DIMS |
嵌入输出维度(可选;否则从模型推断) |
REPOWISE_EMBEDDING_TIMEOUT |
嵌入请求超时秒数(默认:ollama 为 30,其余 10)。本地端点请调高——一次请求嵌入整个批次,过期批次只报为 N/N items failed to embed。不可解析值告警并保持默认 |
REPOWISE_VECTOR_SEARCH_TIMEOUT_S |
单次向量存储查询秒数(默认 30,上限 120)。进程内首次查询承担存储打开、首次嵌入与首次 ANN 探测,冷索引可超过 13s 而热查询不足 1s。慢磁盘或超大 wiki 上调;超时丢弃语义分支并告警,只留全文命中 |
OPENAI_EMBEDDING_TIMEOUT |
同上,仅 openai;优先于共享变量 |
GEMINI_EMBEDDING_TIMEOUT |
同上,仅 gemini |
OPENROUTER_EMBEDDING_TIMEOUT |
同上,仅 openrouter |
EDENAI_EMBEDDING_TIMEOUT |
同上,仅 edenai |
OLLAMA_EMBEDDING_MODEL |
Ollama 嵌入模型(同时选择 ollama 嵌入器) |
OLLAMA_EMBEDDING_DIMS |
Ollama 嵌入输出维度(可选;否则从模型推断) |
OLLAMA_EMBEDDING_TIMEOUT |
同上,仅 ollama;慢本地模型长页面请调高 |
Server 与数据库
| 变量 | 描述 |
|---|---|
REPOWISE_DB_URL |
用 PostgreSQL 替代 SQLite(如 postgresql+asyncpg://...) |
REPOWISE_DATABASE_URL |
REPOWISE_DB_URL 的旧别名,仍然识别 |
REPOWISE_HOST |
API 服务器主机(默认:127.0.0.1) |
REPOWISE_PORT |
API 服务器端口(默认:7337) |
REPOWISE_MCP_PORT |
MCP SSE 服务器端口(默认:7338) |
REPOWISE_API_URL |
仅前端;Web UI 的后端 URL(默认:http://localhost:7337) |
REPOWISE_API_KEY |
客户端调用服务器 API 所需的 Bearer token。不设时服务器只应答本地调用者,拒绝其他主机的任何请求(403) |
REPOWISE_CONFIG_DIR |
覆盖 RepoWise 查找配置目录的位置 |
REPOWISE_GITHUB_WEBHOOK_SECRET |
验证 GitHub webhook 签名的密钥 |
REPOWISE_GITLAB_WEBHOOK_TOKEN |
验证 GitLab webhook 请求的令牌 |
Telemetry
匿名使用遥测默认开启(可退出)。
| 变量 | 描述 |
|---|---|
DO_NOT_TRACK |
任意真值禁用遥测(遵循跨工具约定) |
REPOWISE_TELEMETRY_DISABLED |
禁用遥测,RepoWise 专属 |
REPOWISE_TELEMETRY_DEBUG |
把遥测载荷打印到 stderr 而非发送 |
Misc
| 变量 | 描述 |
|---|---|
REPOWISE_GIT_WINDOW_ANCHOR |
git 历史窗口(90 天 churn、先验缺陷、衰减、blame 年龄)默认从索引提交的 committer 日期起算。设 now 改为从墙钟时间起算 |
REPOWISE_SKIP_EDITOR_SETUP |
真值阻止 init 写入机器级编辑器配置:Claude Code / Claude Desktop MCP 条目、Claude Code hooks 与 distill 重写 hook 提议。与 init --no-editor-setup 同一开关(见 docs/reference/CLI_REFERENCE.md);CI、沙箱与批量索引基准跑请用此环境变量。项目本地文件(.repowise/mcp.json、CLAUDE.md、Codex 配置)两种方式都会写 |
REPOWISE_CHANGELOG |
覆盖 "what's new" 检查使用的 changelog 源 |
REPOWISE_PARSE_WORKERS |
索引期间解析文件的进程数。默认 CPU 数上限 8,且绝不超过待解析文件数。每个 worker 是独立解释器、约 50 MB 内存,内存受限机器请调低;超过 8 无可测加速。该变量在 core/pipeline/phases/ingestion.py 中定义并读取 |
十五、排除模式与仓库范围
RepoWise 自动尊重 .gitignore(与 git 相同的 gitwildmatch 格式),并且像 git 一样读取嵌套 .gitignore——monorepo 与 yarn/npm workspace 中,包级 .gitignore 排除该包构建输出(dist/、coverage/、生成 bundle)时无需在仓库根重复。
额外模式经 --exclude / -x 添加:
repowise init -x vendor/ -x "*.generated.ts" -x proto/ -x "**/*.pb.go"
模式保存到 config.yaml(exclude_patterns),后续 update 继续应用。也可在仓库根或任意子目录创建 .repowiseIgnore 文件(同样 gitignore 语法)实现更细粒度控制而不动 .gitignore。
内置排除(始终应用):.git/、.repowise/、node_modules/、__pycache__/、*.pyc、.venv/、二进制文件、lockfiles 与压缩资源。源码侧,core/fs_walk.py 的 PRUNED_DIRS 更细:.git/.hg/.svn、.venv/venv、.env、__pycache__/.mypy_cache/.pytest_cache/.ruff_cache/.tox/.nox、node_modules/.next/.nuxt/.turbo/.parcel-cache/.yarn/.pnpm-store、.gradle/.cache、.idea/.vscode、htmlcov/.nyc_output、.repowise/.lancedb 等。
--skip-tests 排除测试文件,--skip-infra 排除 Dockerfile、Makefile 与 shell 脚本。两者都是仅单次运行的 CLI flag,不写入 config.yaml,想保持相同排除需在后续 init/update 再传。
十六、子模块与 PostgreSQL
Submodules
git 子模块目录默认排除。包含它们:
repowise init --include-submodules
RepoWise 读取 .gitmodules 检测子模块路径。该 flag 不写入 config.yaml;工作区场景下选择记录在 state.json。
PostgreSQL
团队部署或更大仓库可改用 PostgreSQL 而非 SQLite:
export REPOWISE_DB_URL="postgresql+asyncpg://user:pass@localhost:5432/repowise"
repowise init
REPOWISE_DATABASE_URL 是 REPOWISE_DB_URL 的旧别名,仍然识别。schema 由 Alembic 迁移管理(迁移文件位于 packages/core/alembic/versions)。
十七、工作区配置(.repowise-workspace.yaml)
多仓库工作区(详见 docs/scale/WORKSPACES.md)由工作区根目录的 .repowise-workspace.yaml 配置。除仓库列表外还携带两个可选块。
repos[].tags
每个仓库条目可声明自由格式 tags,用于把服务分组到一致性规则中:
repos:
- path: web
alias: frontend
tags: [ui, edge]
- path: services/db
alias: db
tags: [data]
conformance: 块
声明架构一致性规则(允许/拒绝依赖规则),由 repowise workspace check 与工作区 Conformance 视图检查(见 Architecture Conformance):
conformance:
rules:
- source: frontend # 匹配器:节点 id / 仓库 / 名称上的 glob
target: db # 匹配器
allow: false # 可选,默认 false(拒绝)。true = 例外
description: "..." # 可选,展示在报告中
- source: "tag:ui" # 匹配器:tag:<name>(携带该标签的仓库)
target: "tag:data"
- source: "*" # 匹配器:*(任意服务)
target: legacy-payments
| 字段 | 类型 | 默认 | 含义 |
|---|---|---|---|
source |
string(匹配器) | 必填 | 依赖方。*、tag:<name> 或节点 id / 仓库别名 / 显示名的 glob |
target |
string(匹配器) | 必填 | 被依赖方(同匹配器形式) |
allow |
bool | false |
false = 拒绝(匹配的依赖即违规);true = 白名单化本被拒绝的边 |
description |
string | "" |
人类可读理由,展示在报告中 |
规则只对结构化边(HTTP、gRPC、事件、包、db)求值;行为共变永不被视为依赖。
十八、废弃 / 旧别名
| 旧名 | 现名 | 备注 |
|---|---|---|
max_pages_pct |
coverage_pct |
内部别名,向后兼容仍读取 |
REPOWISE_DATABASE_URL |
REPOWISE_DB_URL |
仍然识别 |
结语
RepoWise 的配置体系把"仓库级事实"与"机器级秘密"严格分层:.repowise/config.yaml 承载可提交审阅的全部行为开关,.repowise/.env 承载 gitignored 的密钥,health-rules.json 与 decisions.yaml 分别做健康信号调校与决策存档。理解各配置块的校验边界(security: 严格、distill: 由 doctor 校验、其余静默忽略未知键)、各 Provider 的自动检测顺序、以及 restyle/generate --all 等触发重生成的正确命令,就能让仓库的 RepoWise 索引长期稳定、可复现地运行。进一步深入可阅读 docs/reference/CLI_REFERENCE.md(全部命令参考)与 docs/layers/WIKI.md(wiki 风格体系)。