配置参考
配置分三处：conf/agent.yml（全局）、.trove/datasources.yml
（每个数据源）、以及环境变量。这一页把三处说明白，并指出一个常见的找错地方。
配置放在哪
| 文件 | 管什么 | 优先级 |
|---|---|---|
| ./conf/agent.yml | 全局：模型、开关、记忆、评测 | 高 |
| ~/.trove/conf/agent.yml | 同上，作为个人覆盖 | 低（前者优先） |
| .trove/datasources.yml | 每个数据源：连接、检索参数 | — |
| ~/.trove/settings.db | 管理台改的运行时设置 | 启动时合入 |
conf/agent.yml:1 搜索顺序 config.py:38 CONFIG_SEARCH_PATHS
flowchart LR
C1["./conf/agent.yml
全局 · 优先级高"]:::entry --> EFF["生效配置"]:::core
C2["~/.trove/conf/agent.yml
个人覆盖 · 优先级低"]:::entry -. "前者缺项时兜底" .-> C1
C3[".trove/datasources.yml
每个数据源：连接 · 检索参数"]:::entry --> EFF
C4["~/.trove/settings.db
管理台改的运行时设置"]:::entry -- "启动时合入" --> EFF
classDef entry fill:#71717a14,stroke:#71717a59,stroke-width:1px;
classDef core fill:#6366f11f,stroke:#6366f1,stroke-width:2px;
datasources.yml：rrf_k、rrf_weights、rerank 是每个数据源的配置，不在 agent.yml 里。
上面这段以源码显示：图渲染库没加载起来（离线、CDN 被拦或浏览器禁用了 JavaScript 时会这样）。这段 Mermaid 文本本身就说明了上面那些框与连线。
rrf_k、rrf_weights、rerank_backend、rerank_endpoint
不在 agent.yml 里——它们是每个数据源的配置，
写在各数据源条目下。
理由很自然：不同库的检索特性不同，一套全局权重不可能对谁都最优。这也正是
混合检索那套调参脚本产出「可以写回
datasources.yml」的原因。
agent 段：常用项
| key | 默认 | 说明 |
|---|---|---|
| target | — | 主力模型 |
| model_fast | — | 轻量任务用的快速模型 |
| model_draft | 空 = 关闭 | 起草 / 判定类结构化短输出的便宜档（KB 建档注释、扩展草稿、偏好抽取等六处；空 = 逐字节回落） |
| language | zh | 回答语言 |
| hitl | false | 执行前人工确认 |
| date_parser | true | 相对时间解析 |
| insights / conclusion / chart_llm | false | 要点、结论、图表三个增强节点 |
| result_cache | false | 结果缓存 |
| reflect_skip | simple | 哪一档复杂度可以跳过反思 |
| git_kb | true | KB 变更走 git 提交，留审计历史 |
| scheduler_poll_seconds | 30 | 内置调度轮询间隔；≤0 关闭 |
| confidence_score | true | 答案级置信度披露；关掉 = 退回枚举式披露 |
| observability.tracing.enabled | true | 追踪撤回开关：false 时即便凭证齐全也不录 |
conf/agent.yml:4 target conf/agent.yml:41 hitl
注意代码默认值与配置文件里的值可能不同。比如 reflect_skip
在代码里是 simple，配置里写的是 standard；
insights 等在代码里是 False，配置里开启了。
以配置文件为准（它覆盖代码默认），但排查时要知道有两层。
config.py:408 AgentConfig config.py:428 model_draft config.py:451 confidence_score config.py:56 TracingConfig conf/agent.yml:91 reflect_skip
memory 段
| key | 默认 | 说明 |
|---|---|---|
| enabled | true | 记忆子系统总开关 |
| episodes | true | 情节记忆 |
| auto_examples | true | 成功问答回写成 pending 示例 |
| auto_preferences | true | 偏好抽取 |
| promotion | false | 自动晋升（默认关） |
| promotion_threshold | 0.8 | 晋升阈值 |
| profile_boost | false | 把画像作为生成提示（默认关） |
| schema_drift_check | true | 周期漂移检测 |
| retention_days | 空 | 空 = 不清理 |
conf/agent.yml:159 auto_examples conf/agent.yml:161 promotion models.py:58 MemoryConfig
两个默认关闭的开关值得单独说：
promotion 是「证据够了就自动把 pending 教训转正」，
默认关是为了保护人工门禁；profile_boost 是把用户画像
注入生成提示，默认关是因为画像的优先级最低、收益不确定。
eval 段
| key | 默认 | 说明 |
|---|---|---|
| gate_enabled | true | 回归门总开关 |
| questions_path | eval/baseline/questions.jsonl | 基线问题集 |
| baseline_path | eval/baseline/results.jsonl | 基线结果 |
| min_n | 0 | 样本下限，不足则判为不可比（0 = 不设限；conf/agent.yml 示例里写的是 10） |
| tolerances | {} | 逐指标容差覆盖 |
conf/agent.yml:233 gate_enabled config.py:177 gate_enabled
--ci 模式下如果 gate_enabled 是 false，门会拒绝执行而不是放行——
「门被关掉了」不该被 CI 读成「通过」。
authz 段：执行前的授权门
| key | 默认 | 说明 |
|---|---|---|
| table_enforcement | enforce | 表级判定（A3）的档位：enforce 拒绝；warn 只记日志与指标、放行（存量部署的回退阀） |
| require_principal | true | 执行路径缺主体时拒绝；关掉等于整层强制点不装配 |
两个键都可以写在顶层或 agent: 段内，两种写法等价。
这个开关只影响表级判定。数据源级判定（A2，「这个用户能不能用这个源」）
与「必须有主体」（A1）不受它影响，恒为拒绝——读错这个开关只会让 A3 变宽，
不会把鉴权关掉。默认 warn 也不是心软：存量 grants 只到数据源级，
直接 enforce 会把正常查询大面积 403，先跑一段收集「哪些表会被拒」。
细节见安全。
masking 段：字段级脱敏
| key | 默认 | 说明 |
|---|---|---|
| enabled | true | 是否装配脱敏节点；关掉只影响这一步，不改变任何声明 |
| hash_salt_ref | 空 | 部署级 salt 引用（env:NAME）；模型级 masking.hash_salt_ref 优先 |
masking:
enabled: true
hash_salt_ref: env:TROVE_MASK_SALT
hash_salt_ref 是引用而不是值：salt 走环境变量，
不进 YAML、不进 git。两处都解析不出来而确有字段声明了 hash 模式时，
执行被拒绝——按设计不得降级为明文。
retention 段
| key | 默认 | 说明 |
|---|---|---|
| max_sessions_per_user | 100 | 每用户会话配额，0 = 关闭 |
| active_grace_min | 10 | 活跃宽限期（分钟） |
| max_checkpoints_per_thread | 50 | 每线程检查点上限 |
| sweep_interval_hours | 24 | 清扫间隔，≤0 = 关闭 |
conf/agent.yml:130 max_sessions_per_user config.py:71 RetentionConfig
环境变量
| 变量 | 作用 | 默认 |
|---|---|---|
| TROVE_ADMIN_PASSWORD | 初始管理员密码 | 随机生成并打印一次 |
| TROVE_STORAGE_URL | 内部状态存储后端 | 未设 → SQLite |
| TROVE_SECRET_KEY | 连接串加密密钥（Fernet） | — |
| TROVE_TOKEN_TTL_HOURS | token 有效期 | 720 |
| TROVE_LOGIN_MAX_ATTEMPTS | 登录失败次数上限 | 5 |
| TROVE_LOGIN_WINDOW_MINUTES | 登录限流窗口 | 15 |
| TROVE_GIT_KB_AUTHOR | KB git 提交作者 | trove <trove@local> |
| LANGFUSE_PUBLIC_KEY / SECRET_KEY / HOST | 追踪上报 | 两个 key 都设才启用 |
| <厂商>_API_KEY | 模型凭证 | litellm 回落解析 |
secrets.py:123 TROVE_SECRET_KEY service.py:111 TROVE_TOKEN_TTL_HOURS git_versioning.py:95 TROVE_GIT_KB_AUTHOR
配置文件里可以写 ${ENV_VAR} 占位符，加载时展开。
凭证建议一律走这个形式，这样配置文件本身可以安全提交。
config.py:580 resolve_env_vars
继续读
| 想了解 | 去哪 |
|---|---|
| 命令行参数 | CLI 参考 |
| 接口清单 | API 参考 |
| 记忆开关的语义 | 记忆子系统 · 配置 |
| 检索参数配在哪 | 混合检索 |