本页说明运行时配置如何从文件和 CLI overrides 进入已校验的运行时状态。
- 解析配置路径如果提供 --config 则使用它；否则使用 app directory 位置。
- 生成本地示例首次运行可创建本地示例文件，但不会覆盖仓库追踪的示例。
- 解析 config.toml把 TOML 加载到 typed config schema。
- 校验不变量启动完成前检查 required providers、routes、protocols 和 timeout values。
- 构造运行时状态校验后的配置成为请求处理使用的 AppState。
| 关注点 | 归属 |
|---|
| 配置 schema | src/config.rs |
| App directory 解析 | src/paths.rs |
| CLI flags 和临时 overrides | src/cli/ |
| 从配置中选择 provider | src/routing/ 和 pipeline routing step |
| 运行时请求访问 | src/lib.rs 中的 AppState |
| 用户可见示例 | config.example.toml、using/configuration、reference/configuration |
| 不变量 | 原因 |
|---|
| 无效配置导致启动失败 | 部分有效的代理比启动错误更难诊断。 |
| Provider protocol 控制出站 wire 行为 | Provider 名称是任意标签，不能暗示协议语义。 |
Route request_protocol guard 严格执行 | Endpoint-specific routing 不应静默 fallback。 |
tool_calls.timeout_secs 必须为正 | 工具调用卡住需要有界语义超时。 |
| 本地私有配置不提交 | config.toml、captures 和 logs 可能包含 secrets 或 prompts。 |
- 在
src/config.rs 添加 typed field。
- 在
config.example.toml 添加简洁示例/注释。
- 接入
src/main.rs、src/lib.rs 或归属模块。
- 如果行为面向用户，更新用户文档。
- 更新 reference 文档和默认值/校验测试。