majiayu000 Sage 配置系统开发指南
模块概览
配置模块是 Sage 的核心基础设施，代码量 11083 行，包含：
crates/sage-core/src/config/
├── mod.rs # 公开接口
├── config.rs # 主配置结构 (393行)
├── defaults.rs # 默认配置加载
├── model_params.rs # 模型参数 (658行)
├── provider.rs # Provider 配置 (882行)
├── provider_defaults.rs # Provider 默认值 (173行)
├── provider_registry.rs # Provider 注册表 (501行)
├── persistence.rs # 运行时持久化 (437行)
├── timeouts.rs # 超时配置 (157行)
├── tool_config.rs # 工具配置 (100行)
├── mcp_config.rs # MCP 配置 (274行)
├── logging_config.rs # 日志配置 (105行)
├── trajectory_config.rs # 轨迹配置 (48行)
├── lakeview_config.rs # Lakeview 配置
├── loader/ # 配置加载器
│ ├── mod.rs # 入口
│ ├── builder.rs # 构建器模式 (74行)
│ ├── loading.rs # 加载逻辑
│ ├── types.rs # ConfigSource 类型
│ └── tests.rs # 测试
├── credential/ # 凭证管理系统
│ ├── mod.rs # 入口
│ ├── resolver.rs # 凭证解析器
│ ├── resolved.rs # 解析结果
│ ├── source.rs # 凭证来源
│ ├── status.rs # 配置状态
│ ├── hint.rs # 状态提示
│ └── unified_loader.rs # 统一加载器
├── validation/ # 配置验证
│ ├── mod.rs # ConfigValidator (156行)
│ ├── provider.rs # Provider 验证
│ ├── model.rs # 模型验证
│ ├── limits.rs # 限制验证
│ ├── paths.rs # 路径验证
│ ├── tools.rs # 工具验证
│ ├── logging.rs # 日志验证
│ └── lakeview.rs # Lakeview 验证
├── onboarding/ # 引导流程
│ ├── mod.rs # 入口
│ ├── manager.rs # 引导管理器 (702行)
│ └── state.rs # 引导状态 (511行)
├── args_loader.rs # 命令行参数加载
├── env_loader.rs # 环境变量加载
└── file_loader.rs # 文件加载
一、核心架构：Config
1.1 主配置结构
// crates/sage-core/src/config/config.rs
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct Config {
/// 默认 LLM Provider
pub default_provider: String,
/// 最大执行步数 (None = 无限)
pub max_steps: Option<u32>,
/// 总 Token 预算
pub total_token_budget: Option<u64>,
/// 每个 Provider 的模型参数
pub model_providers: HashMap<String, ModelParameters>,
/// Lakeview 配置
pub lakeview_config: Option<LakeviewConfig>,
pub enable_lakeview: bool,
/// 工作目录
pub working_directory: Option<PathBuf>,
/// 子配置
pub tools: ToolConfig,
pub logging: LoggingConfig,
pub trajectory: TrajectoryConfig,
pub mcp: McpConfig,
}
impl Default for Config {
fn default() -> Self {
Self {
default_provider: "anthropic".to_string(),
max_steps: None, // 无限制
total_token_budget: None,
model_providers: create_default_providers(),
// ...
}
}
}
1.2 深度合并机制
关键设计：字段级覆盖而非全量替换
impl Config {
/// 合并配置（other 优先）
///
/// 使用深度合并 - 对 model_providers 进行字段级覆盖，
/// 而不是替换整个 provider 配置。
pub fn merge(&mut self, other: Config) {
// 非空才覆盖
if !other.default_provider.is_empty() {
self.default_provider = other.default_provider;
}
// Option 类型：有值才覆盖
if other.max_steps.is_some() {
self.max_steps = other.max_steps;
}
// 深度合并 model_providers
for (provider, other_params) in other.model_providers {
if let Some(existing) = self.model_providers.get_mut(&provider) {
existing.merge(other_params); // 字段级合并
} else {
self.model_providers.insert(provider, other_params);
}
}
// 子配置也使用 merge
self.tools.merge(other.tools);
self.logging.merge(other.logging);
self.mcp.merge(other.mcp);
}
}
二、配置加载系统
2.1 多源加载器
// crates/sage-core/src/config/loader/builder.rs
pub struct ConfigLoader {
sources: Vec<ConfigSource>,
}
impl ConfigLoader {
pub fn new() -> Self {
Self { sources: Vec::new() }
}
/// 链式添加配置源
pub fn with_file<P: AsRef<Path>>(self, path: P) -> Self {
self.add_source(ConfigSource::File(path.as_ref().to_path_buf()))
}
pub fn with_env(self) -> Self {
self.add_source(ConfigSource::Environment)
}
pub fn with_args(self, args: HashMap<String, String>) -> Self {
self.add_source(ConfigSource::CommandLine(args))
}
pub fn with_defaults(self) -> Self {
self.add_source(ConfigSource::Default)
}
/// 加载并合并所有配置源
pub fn load(self) -> SageResult<Config> {
let mut config = Config::default();
for source in &self.sources {
let source_config = load_from_source(source)?;
config.merge(source_config);
}
config.validate()?;
Ok(config)
}
}
2.2 配置源类型
// crates/sage-core/src/config/loader/types.rs
pub enum ConfigSource {
/// 文件源（JSON/TOML/YAML）
File(PathBuf),
/// 环境变量
Environment,
/// 命令行参数
CommandLine(HashMap<String, String>),
/// 默认配置
Default,
}
2.3 典型加载流程
// 使用示例
let config = ConfigLoader::new()
.with_defaults() // 1. 默认值
.with_file("~/.sage/config.json") // 2. 全局配置
.with_file("./sage_config.json") // 3. 项目配置
.with_env() // 4. 环境变量
.with_args(cli_args) // 5. CLI 参数
.load()?;
加载优先级（后者覆盖前者）：
Default → Global File → Project File → Env → CLI Args
三、凭证管理系统
3.1 多源凭证解析
// crates/sage-core/src/config/credential/resolver.rs
pub struct CredentialResolver {
config: ResolverConfig,
}
impl CredentialResolver {
/// 解析所有凭证
pub fn resolve_all(&self) -> ResolvedCredentials {
let mut credentials = ResolvedCredentials::new();
// 按优先级顺序解析
for source in self.config.sources_in_order() {
let found = self.resolve_from_source(&source);
credentials.merge(found);
}
credentials
}
}
3.2 凭证来源与优先级
// crates/sage-core/src/config/credential/source.rs
pub enum CredentialSource {
/// CLI 参数 --api-key
CliArg,
/// 环境变量 ANTHROPIC_API_KEY
Environment,
/// 项目配置 ./sage_config.json
ProjectConfig,
/// 全局配置 ~/.sage/credentials.json
GlobalConfig,
/// 自动导入（如 ~/.anthropic/credentials）
AutoImport,
}
pub enum CredentialPriority {
Highest = 0, // CLI
High = 1, // Env
Medium = 2, // Project
Low = 3, // Global
Lowest = 4, // AutoImport
}
3.3 解析结果
// crates/sage-core/src/config/credential/resolved.rs
pub struct ResolvedCredential {
pub value: String,
pub source: CredentialSource,
pub priority: CredentialPriority,
}
pub struct ResolvedCredentials {
credentials: HashMap<String, ResolvedCredential>,
}
impl ResolvedCredentials {
/// 获取特定 Provider 的 API Key
pub fn get_api_key(&self, provider: &str) -> Option<&str> {
self.credentials.get(provider).map(|c| c.value.as_str())
}
}
3.4 统一配置加载器
// crates/sage-core/src/config/credential/unified_loader.rs
pub struct UnifiedConfigLoader {
config_file: Option<PathBuf>,
cli_overrides: CliOverrides,
}
impl UnifiedConfigLoader {
/// 加载配置（永不失败）
pub fn load(self) -> LoadedConfig {
// 1. 加载配置文件
let mut config = self.load_config_file();
// 2. 应用 CLI 覆盖
self.apply_cli_overrides(&mut config);
// 3. 解析凭证
let resolver = CredentialResolver::with_defaults();
let credentials = resolver.resolve_all();
// 4. 注入凭证到配置
self.inject_credentials(&mut config, &credentials);
// 5. 获取配置状态
let status = resolver.get_status();
LoadedConfig {
config,
credentials,
status,
}
}
}
四、配置验证
4.1 验证器设计
// crates/sage-core/src/config/validation/mod.rs
pub struct ConfigValidator;
impl ConfigValidator {
/// 完整验证
pub fn validate(config: &Config) -> SageResult<()> {
validate_providers(config)?;
validate_models(config)?;
validate_limits(config)?;
validate_paths(config)?;
validate_tools(config)?;
Ok(())
}
/// 单项验证
pub fn validate_providers(config: &Config) -> SageResult<()>;
pub fn validate_models(config: &Config) -> SageResult<()>;
pub fn validate_limits(config: &Config) -> SageResult<()>;
pub fn validate_paths(config: &Config) -> SageResult<()>;
pub fn validate_tools(config: &Config) -> SageResult<()>;
pub fn validate_logging(config: &Config) -> SageResult<()>;
}
4.2 验证规则示例
// crates/sage-core/src/config/validation/provider.rs
pub fn validate_providers(config: &Config) -> SageResult<()> {
// 1. 默认 Provider 必须存在
if !config.model_providers.contains_key(&config.default_provider) {
return Err(SageError::config(format!(
"Default provider '{}' not found",
config.default_provider
)));
}
// 2. 验证每个 Provider 的配置
for (name, params) in &config.model_providers {
params.validate().map_err(|e| {
SageError::config(format!("Invalid '{}': {}", name, e))
})?;
}
Ok(())
}
五、运行时持久化
5.1 持久化管理器
// crates/sage-core/src/config/persistence.rs
pub struct ConfigPersistence {
config_path: PathBuf, // ~/.sage/config.json
credentials_path: PathBuf, // ~/.sage/credentials.json
}
impl ConfigPersistence {
/// 使用点号路径设置字段
pub fn set_field(&self, path: &str, value: Value) -> SageResult<()> {
let mut config = self.load_config_json()?;
set_nested_value(&mut config, path, value);
self.save_config_json(&config)
}
/// 获取字段值
pub fn get_field(&self, path: &str) -> Option<Value> {
let config = self.load_config_json().ok()?;
get_nested_value(&config, path)
}
/// 设置 API Key
pub fn set_api_key(&self, provider: &str, api_key: &str) -> SageResult<()> {
let mut creds = self.load_credentials_json()?;
if !creds.get("api_keys").map(|v| v.is_object()).unwrap_or(false) {
creds["api_keys"] = Value::Object(serde_json::Map::new());
}
creds["api_keys"][provider] = Value::String(api_key.to_string());
self.save_credentials_json(&creds)
}
/// 设置默认 Provider
pub fn set_default_provider(&self, provider: &str) -> SageResult<()> {
self.set_field("default_provider", Value::String(provider.to_string()))
}
}
5.2 ConfigUpdate 类型
pub struct ConfigUpdate {
pub path: String,
pub value: Value,
pub description: String,
}
impl ConfigPersistence {
/// 批量更新
pub fn apply_updates(&self, updates: &[ConfigUpdate]) -> SageResult<()> {
let mut config = self.load_config_json()?;
for update in updates {
set_nested_value(&mut config, &update.path, update.value.clone());
}
self.save_config_json(&config)
}
}
六、Provider 注册表
6.1 Provider 信息
// crates/sage-core/src/config/provider_registry.rs
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderInfo {
pub id: String, // "anthropic"
pub name: String, // "Anthropic"
pub description: String,
pub api_base_url: String,
pub env_var: String, // "ANTHROPIC_API_KEY"
pub help_url: Option<String>,
pub models: Vec<ModelInfo>,
pub requires_api_key: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelInfo {
pub id: String, // "claude-sonnet-4-20250514"
pub name: String, // "Claude 4 Sonnet"
pub default: bool,
pub context_window: Option<u32>,
pub max_output_tokens: Option<u32>,
}
6.2 注册表与缓存
pub struct ProviderRegistry {
cache_dir: PathBuf,
cache_ttl: Duration, // 默认 24 小时
providers: Option<Vec<ProviderInfo>>,
}
impl ProviderRegistry {
/// 获取所有可用 Provider
pub fn get_providers(&mut self) -> &[ProviderInfo] {
if self.providers.is_none() {
self.providers = Some(self.load_providers());
}
self.providers.as_ref().unwrap()
}
/// 强制刷新
pub fn refresh(&mut self) {
self.providers = None;
let providers = self.embedded_providers();
self.save_cache(&providers).ok();
self.providers = Some(providers);
}
}
七、模型参数配置
7.1 ModelParameters
// crates/sage-core/src/config/model_params.rs
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct ModelParameters {
pub model: String,
pub api_key: Option<String>,
pub max_tokens: Option<u32>,
pub temperature: Option<f32>,
pub top_p: Option<f32>,
pub top_k: Option<u32>,
pub parallel_tool_calls: Option<bool>,
pub max_retries: Option<u32>,
pub base_url: Option<String>,
pub api_version: Option<String>,
pub stop_sequences: Option<Vec<String>>,
}
impl ModelParameters {
/// 深度合并
pub fn merge(&mut self, other: ModelParameters) {
// 非空字符串才覆盖
if !other.model.is_empty() {
self.model = other.model;
}
// Option 类型：Some 才覆盖
if other.api_key.is_some() {
self.api_key = other.api_key;
}
if other.max_tokens.is_some() {
self.max_tokens = other.max_tokens;
}
// ... 其他字段
}
/// 验证
pub fn validate(&self) -> SageResult<()> {
if self.model.is_empty() {
return Err(SageError::config("Model name cannot be empty"));
}
if let Some(temp) = self.temperature {
if !(0.0..=2.0).contains(&temp) {
return Err(SageError::config("Temperature must be 0.0-2.0"));
}
}
Ok(())
}
}
八、开发指南
8.1 添加新配置字段
- 在
Config结构添加字段（带#[serde(default)]）：
pub struct Config {
// ...
#[serde(default)]
pub new_feature: bool,
}
在
Config::merge中处理合并逻辑如需要，在
validation/添加验证规则更新
sage_config.json.example
8.2 添加新 Provider
- 在
provider_registry.rs的embedded_providers()添加：
ProviderInfo {
id: "new_provider".to_string(),
name: "New Provider".to_string(),
env_var: "NEW_PROVIDER_API_KEY".to_string(),
models: vec![
ModelInfo {
id: "new-model".to_string(),
name: "New Model".to_string(),
default: true,
..Default::default()
}
],
..Default::default()
}
在
provider_defaults.rs添加默认参数在
credential/resolver.rs添加环境变量映射
8.3 配置文件格式
sage_config.json 示例：
{
"default_provider": "anthropic",
"max_steps": 100,
"total_token_budget": 1000000,
"model_providers": {
"anthropic": {
"model": "claude-sonnet-4-20250514",
"max_tokens": 8192,
"temperature": 0.7
},
"openai": {
"model": "gpt-4o",
"max_tokens": 4096
}
},
"tools": {
"max_execution_time": 300,
"allow_parallel_execution": true
},
"mcp": {
"servers": [
{
"name": "filesystem",
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-filesystem"]
}
]
}
}
credentials.json 示例：
{
"api_keys": {
"anthropic": "sk-ant-xxx",
"openai": "sk-xxx"
}
}
九、配置层次结构
┌─────────────────────────────────────────────────────────────┐
│ CLI Args │
│ (最高优先级) │
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────┐
│ Environment Vars │
│ SAGE_*, ANTHROPIC_API_KEY, ... │
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────┐
│ Project Config │
│ ./sage_config.json │
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────┐
│ Global Config │
│ ~/.sage/config.json │
│ ~/.sage/credentials.json │
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────┐
│ Defaults │
│ (代码内置默认值) │
└─────────────────────────────────────────────────────────────┘
十、相关模块
sage-llm-integration- LLM 客户端（使用 ProviderConfig）sage-session-management- 会话管理（使用配置）sage-mcp-protocol- MCP 协议（使用 McpConfig）sage-agent-execution- Agent 执行（使用 ExecutionOptions）
最后更新: 2026-01-10