RepoWise 配置完全指南:`.repowise/config.yaml`、LLM Provider 与全量环境变量详解

原创2026-10-08 14:32:512,150 阅读

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|PowerShell PostToolUse 条目,关闭则移除;该条目按安装而非按仓库生效;
  • 每个键都可选。无 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 时,按序检测:

  1. REPOWISE_PROVIDER 环境变量
  2. .repowise/config.yaml 中的 provider
  3. 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 密钥按此顺序解析:

  1. 环境变量:运行 RepoWise 前设置
  2. .repowise/.env:交互式设置持久化,自动加载
  3. 交互提示: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 风格体系)。

登录后查看全文
repowise