Skip to content

CONFIG_REFACTORING.md

Latest commit

 

History

History
367 lines (272 loc) · 9.19 KB

CONFIG_REFACTORING.md

File metadata and controls

367 lines (272 loc) · 9.19 KB

Claude Code 配置系统重构说明

概述

本文档详细说明了 Claude Code Rust 重构项目中配置系统的系统性重构，基于《Claude Code 源码深度分析（2026-03-31）.md》文档中的最佳实践。

重构背景

原配置系统存在的问题

  1. 缺少配置验证机制 - 没有对配置值的有效性进行验证
  2. 缺少版本管理 - 没有配置版本号，无法处理配置升级
  3. 缺少迁移机制 - 配置格式变化时无法自动迁移
  4. 缺少模块化管理 - 所有配置项混合在一起，难以维护
  5. 缺少热重载 - 配置变更需要重启应用
  6. 缺少特性标志 - 没有统一的特性开关管理

重构目标

  1. ✅ 实现完整的配置验证机制
  2. ✅ 添加配置版本管理
  3. ✅ 实现配置自动迁移系统
  4. ✅ 实现 System Prompt 组装流程
  5. ✅ 模块化配置管理
  6. ✅ 配置变更监听和热重载
  7. ✅ 特性标志系统

架构设计

模块结构

src/config/
├── mod.rs              # 主配置模块，整合所有功能
├── api_config.rs       # API 配置（原有的）
├── mcp_config.rs       # MCP 配置（原有的）
├── validation.rs       # 配置验证模块（新增）
├── migration.rs        # 配置迁移模块（新增）
└── system_prompt.rs    # System Prompt 组装模块（新增）

核心功能模块

1. 配置验证模块 (validation.rs)

功能特性

  • 验证器接口：统一的 ConfigValidator trait

  • 内置验证器：

    • RequiredValidator - 必填验证
    • StringRangeValidator - 字符串长度验证
    • NumberRangeValidator - 数值范围验证
    • EnumValidator - 枚举值验证
    • UrlValidator - URL 格式验证
    • PathValidator - 路径存在性验证

  • 验证模式：ValidationSchema 用于定义验证规则

  • 验证结果：包含错误和警告的详细信息

使用示例

let mut schema = ValidationSchema::new();
schema.required("api_key");
schema.string_range("model", Some(1), Some(50));
schema.number_range("timeout", Some(10.0), Some(300.0));
schema.url("base_url");

let result = schema.validate(&config_value);
if !result.is_valid {
    for error in result.errors {
        println!("{}", error);
    }
}

2. 配置迁移模块 (migration.rs)

功能特性

  • 版本管理：ConfigVersion 结构体，支持语义化版本
  • 迁移管理器：MigrationManager 用于管理迁移流程
  • 简化迁移：目前实现了从 0.0.0 到 1.0.0 的基本迁移

版本格式

pub struct ConfigVersion {
    pub major: u32,
    pub minor: u32,
    pub patch: u32,
}

迁移流程

  1. 从配置中读取版本号
  2. 如果版本低于当前版本，执行迁移
  3. 自动添加缺失的配置字段
  4. 更新版本号到当前版本

3. System Prompt 组装模块 (system_prompt.rs)

功能特性

完全基于文档中的 System Prompt 组装流程实现：

静态内容部分（可缓存）：

  1. getSimpleIntroSection() - 身份与安全指令
  2. getSimpleSystemSection() - 系统规则
  3. getSimpleDoingTasksSection() - 任务执行指南
  4. getActionsSection() - 安全操作指南
  5. getUsingYourToolsSection() - 工具使用指南
  6. getSimpleToneAndStyleSection() - 语气风格
  7. getOutputEfficiencySection() - 输出效率

动态内容部分（每个会话不同）： 8. getSessionSpecificGuidanceSection() - 会话特定指南 9. loadMemoryPrompt() - 持久记忆 10. computeSimpleEnvInfo() - 环境信息 11. getLanguageSection() - 语言偏好 12. getOutputStyleSection() - 输出样式 13. getMcpInstructionsSection() - MCP 服务器指令 14. getScratchpadInstructions() - 临时目录 15. getFunctionResultClearingSection() - 结果清理 16. SUMMARIZE_TOOL_RESULTS_SECTION - 工具结果总结

身份前缀

支持三种身份前缀：

  • Default - 默认交互模式
  • AgentSdkPreset - Agent SDK 预设
  • AgentSdk - Agent SDK 模式

使用示例

let settings = Settings::load()?;
let mut builder = settings.create_system_prompt_builder();

builder.add_session_guidance("This is a special session");
builder.add_memory("User likes Rust programming");
builder.set_env_info("os", "Windows");
builder.set_language("zh");
builder.set_brief_mode(true);

let system_prompt = builder.build();

4. 主配置模块 (mod.rs)

新增配置项

特性标志 (FeatureFlags)：

pub struct FeatureFlags {
    pub proactive: bool,          // 主动模式
    pub bridge_mode: bool,        // IDE 桥接模式
    pub voice_mode: bool,         // 语音模式
    pub coordinator_mode: bool,   // 协调器模式
    pub fork_subagent: bool,      // Fork 子智能体
    pub buddy: bool,              // Buddy 伴侣精灵
}

输出设置 (OutputSettings)：

pub struct OutputSettings {
    pub language: String,         // 语言偏好
    pub style: String,            // 输出样式
    pub brief_mode: bool,         // 简短模式
    pub emoji: bool,              // 启用 emoji
}

配置管理器 (ConfigManager)

提供线程安全的配置管理：

  • new() - 创建配置管理器
  • settings() - 获取当前配置
  • update() - 更新配置
  • reload() - 重新加载配置
  • add_change_listener() - 添加变更监听器

配置版本

所有配置现在都包含版本号：

pub struct Settings {
    #[serde(default = "default_version")]
    pub version: String,
    // ... 其他配置项
}

技术实现

线程安全

使用 Arc<RwLock<Settings>> 实现线程安全的配置访问：

  • 多个读者可以同时读取配置
  • 写操作独占访问
  • 异步友好的锁机制

变更监听

支持配置变更监听，便于热重载：

let mut config_manager = ConfigManager::new()?;
config_manager.add_change_listener(|settings| {
    println!("Configuration updated!");
    // 重新初始化依赖配置的组件
});

错误处理

新增 ConfigError 类型，提供详细的配置错误信息：

  • InvalidSetting - 无效的配置项
  • ValidationFailed - 验证失败
  • MigrationFailed - 迁移失败
  • NotFound - 配置未找到
  • VersionMismatch - 版本不匹配

使用指南

加载配置

use crate::config::Settings;

let settings = Settings::load()?;
println!("Model: {}", settings.model);
println!("Version: {}", settings.version);

修改配置

let mut settings = Settings::load()?;
settings.set("model", "opus")?;
settings.set("output.language", "zh")?;
settings.set("features.buddy", "true")?;
settings.save()?;

使用配置管理器

use crate::config::ConfigManager;

let config_manager = ConfigManager::new()?;

// 读取配置
let settings = config_manager.settings().await;

// 更新配置
config_manager.update(|settings| {
    settings.model = "opus".to_string();
    Ok(())
}).await?;

// 监听配置变更
config_manager.add_change_listener(|settings| {
    println!("Configuration changed to version: {}", settings.version);
});

生成 System Prompt

let settings = Settings::load()?;
let builder = settings.create_system_prompt_builder();
let system_prompt = builder.build();
println!("{}", system_prompt);

测试覆盖

单元测试

每个模块都包含完整的单元测试：

  • validation.rs：测试所有验证器
  • migration.rs：测试版本解析和迁移
  • system_prompt.rs：测试 System Prompt 组装
  • mod.rs：测试 Settings 和 ConfigManager

运行测试

cargo test --package claude-code-rs config

性能优化

配置缓存

  • 配置加载后缓存在内存中
  • 使用 Arc 共享配置实例
  • 避免重复的磁盘 I/O

System Prompt 缓存

  • 静态部分可以跨用户缓存
  • 动态部分每次重新组装
  • 明确的分界线 SYSTEM_PROMPT_DYNAMIC_BOUNDARY

安全性

配置验证

  • 所有配置值在保存前验证
  • 防止无效配置导致的运行时错误
  • URL 和路径验证防止注入攻击

敏感数据

  • API 密钥等敏感信息保持原有的处理方式
  • 配置文件权限设置为用户只读
  • 不记录敏感配置到日志

向后兼容性

配置迁移

  • 旧版本配置自动迁移到新版本
  • 缺失字段自动填充默认值
  • 版本号用于判断迁移需求

类型别名

保持 Config 类型别名，兼容现有代码：

pub type Config = Settings;

未来改进

短期计划

  1. 完善验证器，支持更复杂的验证规则
  2. 实现完整的迁移步骤框架
  3. 添加配置备份和恢复功能
  4. 支持多个配置文件（全局/项目/用户）

长期计划

  1. 配置 schema 定义和代码生成
  2. 远程配置管理
  3. 配置加密（敏感数据）
  4. 配置差异对比和回滚

总结

本次重构实现了：

✅ 完整的配置验证机制
✅ 配置版本管理和迁移
✅ System Prompt 完整组装流程
✅ 模块化配置管理
✅ 特性标志系统
✅ 线程安全的配置管理器
✅ 配置变更监听
✅ 完整的单元测试覆盖

所有功能都基于《Claude Code 源码深度分析（2026-03-31）.md》文档中的最佳实践实现，确保了配置系统的稳定性、可维护性和可扩展性。