跳至内容
AICodeReviewer

配置总览

AICodeReviewer 通过一个 config.yaml 文件加一个 .env 文件完成全部配置。 本页是一张地图：列出所有顶层命名空间、说明配置如何从全局默认逐层下沉到单个 workspace，并强调密钥规则——提交进版本库的 config.yaml 只放环境变量引用； 明文密钥请配置到数据库配置源（加密落库）或你刻意保持私有的文件中。

每个命名空间都有独立的详情页给出完整字段表，你可以把下表当作入口。

顶层命名空间

Section titled “顶层命名空间”
命名空间 控制内容 详情页
llm 模型提供方、模型链、重试/退避、费用预算，以及 models.dev 元数据目录。 LLM 提供方与模型
triggers 每个 VCS 源（Gitea、GitHub、GitLab、P4、SVN）一个条目——入站 webhook/HMAC 校验与出站 token。 认证与密钥
workspaces 你要评审的代码仓库：源绑定、按 workspace 覆盖，以及克隆缓存。 本页
outputs 输出通道（PR review、IM 机器人、托管 issue）、路由规则，以及零问题策略。 输出通道与路由
agent 驱动哪个 agent CLI、单次运行超时、上下文自动压缩，以及沙箱后端。 Agent 与沙箱
review 文件过滤、label 管理、托管问题 issue 的生命周期上限，以及反思记忆。 本页
queue 内存、SQLite 或 Redis 队列、worker 并发、限流，以及重试策略。 队列与重试
storage 数据库、缓存与对象存储后端，用于可观测性、模型目录及未来特性。 存储
compression AICR 侧的 diff 摘要，在模型看到大任务前先压缩。 LLM 提供方与模型（上下文依赖）
server HTTP 监听器与 /triggers/* 的全局 API key 鉴权。 认证与密钥
admin 可选的管理后台超级管理员登录——后台同时提供可观测性与配置管理（与 webhook/trigger 鉴权相互独立）。 认证与密钥
config_sources 数据库配置源开关、运行时刷新节奏，以及密钥引用授权。 本页（动态配置 API）

文件校验

Section titled “文件校验”

加载器接受不超过 1 MiB 的 YAML 映射，在填入默认值前拒绝重复键、循环别名和原型键。 provider ID、trigger name 和 channel name 必须分别唯一。以 _env 结尾的字段必须填写 符合 [A-Za-z_][A-Za-z0-9_]* 的环境变量名称。旧模型链格式只在内存中转换，原文件不会 改写，详见模型分组。

三层覆盖模型

Section titled “三层覆盖模型”

影响某次评审的配置按三层解析，越往下越具体，下层设置的值总是优先。

全局（config 根）  →  workspaces.defaults  →  workspaces.instances.<id>
  1. 全局 —— 诸如 review、outputs.no_problems、agent、compression 这样的顶层键，是所有 workspace 的兜底。
  2. workspace 默认 —— workspaces.defaults.{review,outputs,agent,prompt,sandbox} 对所有实例生效，但仍可被实例覆盖。当你想在多个仓库间共享一份策略时用这一层。
  3. workspace 实例 —— workspaces.instances.<id> 是最具体的一层，这里设置的 任何值都优先。workspace_id 不能与保留根键 cache、defaults、instances 冲突。

覆盖是按 section 深合并的，不是整体替换。比如在实例里设置 outputs.no_problems，并不会清空该实例的 outputs.summary 列表——只有你显式 设置的字段才会被替换。

# 全局默认 —— 通知类通道保持安静
outputs:
  no_problems: { action: suppress }


workspaces:
  defaults:
    outputs:
      no_problems: { action: suppress }


  instances:
    critical-service:
      source_repo: { trigger: gitea, repo: "my-org/critical-service" }
      outputs:
        summary: [feishu-code-review]
        # 按 workspace + 按通道覆盖：这个仓库需要审计留痕
        channel_overrides:
          feishu-code-review:
            no_problems: { action: publish }
      # 按 workspace 覆盖 review（与全局 review 深合并）
      review:
        problem_issue:
          max_recent_issues: 10

并非每个 section 都能在每一层覆盖。下表列出每一层接受的 section。

Section 全局 workspaces.defaults workspaces.instances.<id>
review ✓ ✓ ✓
outputs（通道列表、no_problems、channel_overrides） ✓ ✓ ✓
model_chain（主链分组） 经由 llm.default_model_chain ✓ ✓
triage_model_chain（生命周期分析分组） 经由 llm.triage_model_chain ✓ ✓
agent.default ✓ ✓ ✓
sandbox 经由 agent.sandbox ✓ ✓
prompt（基础系统提示、force_skills） — ✓ ✓
context_repositories（辅助上下文仓库） — ✓ ✓
auth（按 workspace 的 API key） 经由 server.auth — ✓
compression、queue、storage、llm、server、admin、triggers、config_sources ✓ — —

分组定义统一放在 llm.model_chain；workspace 只填分组名。主链用于审查、 agent 故障切换和压缩摘要；triage 各层都未配置时继承该 workspace 的主链。 完整示例见模型分组配置。

每次运行按 global → defaults → instance 的合并结果选择 agent.default 和 sandbox，并独立创建沙箱实例。workspace 层可以混用不同 agent 或独立沙箱镜像。

context_repositories 声明评审时可引用的辅助仓库（共享库、协议定义等）：每次评审 在确认存在变更文件后全新物化到 <run>/context-repos/<alias>，容器沙箱内以只读 挂载 /workspace/context-repos/<alias> 暴露给 agent，单仓库失败不阻塞评审， max_mb（默认 512）限制物化体积。instance 的列表整体替换 defaults 的列表。 字段细节见配置字段参考。

SVN 未指定 revision 时，先解析版本，再固定该版本导出内容。每次导出尝试都从空目录 开始；无法解析 HEAD 时，该 alias 失败，评审继续但不使用这个辅助仓库。

.env 与 config.yaml —— 密钥约定

Section titled “.env 与 config.yaml —— 密钥约定”

config.yaml 设计为可以提交到版本库，因此提交库的文件不应包含明文密钥。默认 约定是：所有承载密钥的字段都只接受环境变量的名字，AICR 在启动时从环境读取 实际值。已注册的凭据还支持对应的明文字段（api_key 对应 api_key_env、 token 对应 token_env、webhook_url 对应 webhook_url_env 等），二者互斥， 同时设置会校验失败。明文主要用于数据库配置源——发布后经 AES-256-GCM 加密落库 （见下文动态配置 API）——或你刻意不进版本库的私有文件配置。

# config.yaml —— 只存放环境变量名，不放值
llm:
  providers:
    - id: my-llm
      kind: openai_compatible
      api_key_env: AICR_LLM_API_KEY   # 从 $AICR_LLM_API_KEY 读取
      # api_key: sk-xxxxxxxx        # 明文替代形式——与 api_key_env 互斥；
                                    # 发布到数据库后加密落库
终端窗口
# .env（或编排系统的密钥库）—— 存放真正的值
AICR_LLM_API_KEY=sk-xxxxxxxxxxxxxxxx

整个配置里的命名约定是一致的：

字段后缀 含义 示例
*_env 存放密钥（key、token、URL）的环境变量名。 api_key_env、webhook_secret_env、url_env
*_url_env 存放 URL 的环境变量名。 endpoint_url_env、webhook_url_env

请牢记：

  • *_env 字段是一个字符串名字，不是密钥本身。如果写成 api_key_env: sk-xxx，AICR 会去查找名为 sk-xxx 的环境变量并失败。
  • 如果省略某个密钥字段，对应特性会被禁用或以未鉴权方式运行（例如跳过 webhook 的 HMAC 校验——生产环境不建议）。
  • 用 node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" 生成强随机值。

三套相互独立的鉴权层（webhook HMAC、server API key、workspace API key） 如何组合使用，见 认证与密钥。

接下来看哪里

Section titled “接下来看哪里”

多工程 workspace（v2 匹配）

Section titled “多工程 workspace（v2 匹配）”

一个实例可以用 match[] 规则服务多个工程，代替单一的 source_repo 绑定 （两者互斥）。规则之间是 OR，单条规则内的字段是 AND。git 系 webhook （GitHub、GitLab、Gitea、Forgejo）先验凭据、准入时匹配：无规则命中返回 202 repository_not_configured，命中多个定义返回 202 ambiguous_route。 P4/SVN profile 先持久化路由回执，再由后台对照验证过的变更路径完成解析。

命中的实例按 work_path 渲染目录——一个受限 Handlebars 模板（仅允许 segment、default、hash、lower 四个 helper，默认 {{workspace.id}}）。 变量目录见模板变量。命中的实例使用 isolated_v2 布局：所有内容位于 <workspaces.root>/<work_path>/<instance_id>， 每次运行的 source/agent/tmp/context-repos 位于 runs/<runId>/，并随整次评审 清理；legacy 缓存路径保持原样。

路径必须是可移植的相对路径。保存时会拒绝 /{{workspace.id}}、{{workspace.id}}/ 等确定非法的字面量边界；依赖事件的值还会在路径渲染时校验。

匹配还引入了最顶层的覆盖层：每个任务的分析选择按 全局 → workspace 默认 → 实例 → 命中路由的 analysis 块 合并。数据库配置源发布新版本时，文件显式值 仍然优先且保持只读——agent、review、queue.workers|rate_limit|retry|dead_letter 前缀除外：这些共享全局按 数据库 > 文件 > 默认值 合并，管理界面保持可编辑并提供 “重置数据库配置”。一次发布只对发布后新接收的任务生效——已排队和运行中的 任务保留接收时的配置。字段细节见 配置字段参考。

动态配置 API

Section titled “动态配置 API”

启用 config_sources.database.enabled: true 后，/api/admin/config 可发布数据库 补充配置，文件显式值保持只读（agent/review/queue.workers|rate_limit|retry|dead_letter 前缀例外：数据库值优先，可编辑、可重置）。每次 webhook 在读取凭据前检查持久 head，异步处理 始终使用同一 generation。receipt 和新持久化延期任务保留接收时快照；空命名空间 在接收任务前先写入 revision 0 快照。

管理员 API 要求 Bearer session，JSON 请求按 UTF-8 字节限制为 1 MiB，拒绝跨源 写入和不一致的 fileDigest，读取历史凭据时脱敏。凭据既可配环境变量引用，也可 直接配明文：已注册的凭据支持对应字段（如 api_key 对应 api_key_env、 token 对应 token_env、webhook_url 对应 webhook_url_env），二者互斥。 存储连接 URL 等部署字段保持原有环境变量配置。发布到数据库的明文在落库前以 AES-256-GCM 封存——revision 与运行时快照只存 密文——密钥来自部署侧 AICR_CONFIG_SECRETS_KEY（32 字节，hex 或 base64；可用 node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" 生成）。 未配置该密钥时发布明文以 secrets_key_missing fail-closed；只使用 env 引用的配置 无需密钥。AICR_CONFIG_SECRETS_KEY_PREVIOUS 以逗号分隔退役密钥（仅解密），轮换 不影响历史 revision。带凭据 URL、private_key_path 与未注册的 credentia 命名键 仍被拒绝。脱敏字段编辑时不动即保留原值（省略字段保留，显式 null 清除）。 校验与恢复在提交前认证存量密文；相同操作重试复用原 revision 和快照。继承自文件 的明文凭据不能转向不同路径或目的地，变更目的地时须提供对应凭据。读取视图 包含文件/数据库来源、不可变记录 ID、 有效值和 limit/offset 实体分页。无法激活配置时，/readyz 和管理员 /status 返回 503。

changesets 和 restore 请求必须携带当前 SHA-256 fileDigest。operation 端点区分 持久提交与本机激活，status 列出实例心跳及版本。已排队任务和历史无 pin 任务在发布、 重启后保持原版本；历史 null 记录统一解析到持久化的 legacy_import 基线。

环境变量引用按名称、配置路径及目的地授权。原文件引用授权原有用途；新增数据库引用 或修改目的地前，需要在文件 config_sources.secret_refs 中授权，包括 channel、 model override、workspace/route search 继承的凭据。授权格式见 字段参考。

未指定 trigger 的 channel 继承接收事件的兼容 profile。数据库 channel 需要对所有 兼容 profile 的有效凭据与目的地授权；指定 trigger 可缩小这一范围。文件拥有的 channel 保留这些原有用途的授权。GitLab project_id 属于目的地授权字段，修改时 需要匹配的文件授权。

数据库可管理的全局叶子包括 llm.default_model_chain、llm.triage_model_chain、 llm.retry、llm.per_provider_overrides、llm.budget、llm.model_catalog、 review、compression、agent、outputs.template_engine、outputs.templates、 outputs.no_problems、outputs.author_resolution、outputs.routes、prompts.system、 queue.workers、queue.rate_limit、queue.retry、queue.dead_letter、workspaces.cache、 workspaces.defaults、storage.retention.recent_runs、storage.retention.events、 storage.retention.queue，以及 provider、模型组、trigger、channel、workspace、route、 template、prompt 实体集合。历史保留配置采用数据库优先，重置回退到 YAML/默认值。bootstrap 信任边界——server、admin、storage.database|cache|object、 storage.retention.deleted_project_grace_days、config_sources、queue.kind、 queue.sqlite、workspaces.root——永远不可由数据库写入。

v2 路由、Review 策略、agent/search/sandbox、模型目录和 triage 变更对新任务生效。 v2 输出显式空列表关闭该类输出。管理 UI 已随看板 Config 标签发布（见 Dashboard 与日志），API 可独立于统计 store 使用。