refactor: 重构 config 模块

Author: xerrors

docs/.vitepress/config.mts

@@ -33,6 +33,7 @@ export default defineConfig({
       {
         text: '高级配置',
         items: [
+          { text: '配置系统详解', link: '/advanced/configuration' },
           { text: '文档解析', link: '/advanced/document-processing' },
           { text: '智能体', link: '/advanced/agents' },
           { text: '品牌自定义', link: '/advanced/branding' },
@@ -42,10 +43,10 @@ export default defineConfig({
       {
         text: '更新日志',
         items: [
+          { text: '版本说明 v0.3', link: '/changelog/0.3-release-notes' },
           { text: '路线图', link: '/changelog/roadmap' },
           { text: '参与贡献', link: '/changelog/contributing' },
-          { text: '常见问题', link: '/changelog/faq' },
-          { text: '版本说明 v0.3', link: '/changelog/0.3-release-notes' }
+          { text: '常见问题', link: '/changelog/faq' }
         ]
       }
     ],

docs/advanced/configuration.md

@@ -0,0 +1,185 @@
+# 配置系统详解
+
+## 概述
+
+Yuxi-Know 从 v0.3.x 版本开始采用了全新的配置系统，基于 Pydantic BaseModel 和 TOML 格式，提供了类型安全、智能提示和选择性持久化等现代化特性。
+
+## 架构设计
+
+### 配置层次结构
+
+```
+配置系统架构
+├── 默认配置 (代码定义)
+│   ├── src/config/static/models.py (模型配置)
+│   └── src/config/app.py (应用配置)
+├── 用户配置 (TOML 文件)
+│   └── saves/config/base.toml (仅保存用户修改)
+└── 环境变量 (运行时覆盖)
+    └── .env 文件
+```
+
+### 核心组件
+
+#### 1. Config 类 (`src/config/app.py`)
+
+主配置类，继承自 Pydantic BaseModel，提供：
+
+- **类型验证**: 自动检查配置项类型
+- **默认值管理**: 内置合理的默认配置
+- **选择性持久化**: 仅保存用户修改的配置项
+- **向后兼容**: 支持旧的字典式访问方式
+
+```python
+class Config(BaseModel):
+    # 功能开关
+    enable_reranker: bool = Field(default=False, description="是否开启重排序")
+    enable_content_guard: bool = Field(default=False, description="是否启用内容审查")
+
+    # 模型配置
+    default_model: str = Field(default="siliconflow/deepseek-ai/DeepSeek-V3.2-Exp")
+    embed_model: str = Field(default="siliconflow/BAAI/bge-m3")
+
+    # 运行时状态 (不持久化)
+    model_provider_status: dict[str, bool] = Field(exclude=True)
+```
+
+#### 2. 模型配置类 (`src/config/static/models.py`)
+
+定义了三种类型的模型配置：
+
+- **ChatModelProvider**: 聊天模型提供商
+- **EmbedModelInfo**: 嵌入模型信息
+- **RerankerInfo**: 重排序模型信息
+
+```python
+class ChatModelProvider(BaseModel):
+    name: str = Field(..., description="提供商显示名称")
+    url: str = Field(..., description="提供商文档或模型列表 URL")
+    base_url: str = Field(..., description="API 基础 URL")
+    default: str = Field(..., description="默认模型名称")
+    env: str = Field(..., description="API Key 环境变量名")
+    models: list[str] = Field(default_factory=list, description="支持的模型列表")
+```
+
+添加配置：
+
+
+```python
+# 1. 在 DEFAULT_CHAT_MODEL_PROVIDERS 中添加
+"new-provider": ChatModelProvider(
+    name="新提供商",
+    url="https://provider.com/docs",
+    base_url="https://api.provider.com/v1",
+    default="default-model",
+    env="NEW_PROVIDER_API_KEY",
+    models=["model1", "model2"],
+),
+
+# 2. 在 .env 中配置 API Key
+# NEW_PROVIDER_API_KEY=your_api_key
+
+# 3. 重启服务或重新加载配置
+```
+
+## 配置管理特性
+
+系统只会保存用户修改过的配置项：
+
+```python
+# 用户只修改了 enable_reranker
+config.enable_reranker = True
+config.save()  # 只保存 enable_reranker 到 TOML 文件
+
+# TOML 文件内容
+# enable_reranker = true
+```
+
+### 默认模型配置 (`src/config/static/models.py`)
+
+包含所有支持的模型提供商的默认配置，开发者可以直接修改此文件添加新的模型：
+
+```python
+DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = {
+    "siliconflow": ChatModelProvider(
+        name="SiliconFlow",
+        url="https://cloud.siliconflow.cn/models",
+        base_url="https://api.siliconflow.cn/v1",
+        default="deepseek-ai/DeepSeek-V3.2-Exp",
+        env="SILICONFLOW_API_KEY",
+        models=[
+            "deepseek-ai/DeepSeek-V3.2-Exp",
+            "Qwen/Qwen3-235B-A22B-Instruct-2507",
+            # ...
+        ],
+    ),
+    # 更多提供商...
+}
+```
+
+### 用户配置 (`saves/config/base.toml`)
+
+只包含用户修改过的配置项，使用 TOML 格式：
+
+```toml
+# 用户只修改了这些配置项
+enable_reranker = true
+default_agent_id = "MyCustomAgent"
+enable_content_guard = true
+
+# 模型配置修改
+[model_names.siliconflow]
+models = [
+    "deepseek-ai/DeepSeek-V3.2-Exp",
+    "custom-model-name",
+]
+```
+
+## 高级配置
+
+### 动态配置更新
+
+```python
+from src.config import config
+
+# 更新配置
+config.enable_reranker = True
+config.default_agent_id = "CustomAgent"
+
+# 更新模型列表
+config.model_names["siliconflow"].models.append("new-model")
+
+# 保存配置
+config.save()
+
+# 或者只保存特定提供商的模型配置
+config._save_models_to_file("siliconflow")
+```
+
+### 配置验证
+
+```python
+# 验证配置
+from src.config import config
+
+# 检查模型提供商可用性
+for provider, status in config.model_provider_status.items():
+    print(f"{provider}: {'✅' if status else '❌'}")
+
+# 获取可用模型列表
+available_models = config.get_model_choices()
+available_embed_models = config.get_embed_model_choices()
+available_rerankers = config.get_reranker_choices()
+```
+
+### 配置导出
+
+```python
+# 导出完整配置（包含运行时状态）
+full_config = config.dump_config()
+
+# 导出用户配置（仅保存到文件的部分）
+user_config = {
+    field: getattr(config, field)
+    for field in config._user_modified_fields
+}

docs/changelog/0.3-release-notes.md

@@ -18,6 +18,56 @@ Yuxi-Know v0.3 是一个重要的里程碑版本，包含了多项架构重构
   cp .env.template .env
   ```
 
+### 配置文件管理调整
+
+配置系统从 YAML 格式迁移到了基于 Pydantic BaseModel + TOML 的现代化配置系统。
+
+| 项目 | v0.2.x | v0.3.x |
+|------|--------|--------|
+| 默认模型配置 | `src/config/static/models.yaml` | `src/config/static/models.py` |
+| 用户配置 | `saves/config/base.yaml` | `saves/config/base.toml` |
+| 配置格式 | YAML | Python 代码 + TOML |
+| 类型安全 | ❌ 无 | ✅ Pydantic 验证 |
+| IDE 支持 | ❌ 基础 | ✅ 完整智能提示 |
+| 持久化策略 | 全量保存 | 选择性保存 |
+
+
+示例：迁移自定义模型提供商
+
+假设你的旧 `models.yaml` 中有：
+
+```yaml
+# 旧的 models.yaml
+MODEL_NAMES:
+  custom-provider:
+    name: "My Custom Provider"
+    base_url: "https://api.custom.com/v1"
+    default: "custom-model"
+    env: "CUSTOM_API_KEY"
+    models:
+      - "custom-model"
+      - "another-model"
+```
+
+需要在新的 `src/config/static/models.py` 中添加：
+
+```python
+# 新的 models.py
+DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = {
+    # ... 现有配置 ...
+
+    "custom-provider": ChatModelProvider(
+        name="My Custom Provider",
+        url="https://custom.com/docs",
+        base_url="https://api.custom.com/v1",
+        default="custom-model",
+        env="CUSTOM_API_KEY",
+        models=["custom-model", "another-model"],
+    ),
+}
+```
+
+
 ### 数据库存储架构重构
 - **变更内容**: 重新实现了对话管理的存储与管理，不再依赖于 MemorySaver
 - **影响**: 使用新的存储结构，之前存储的历史记录无法直接迁移

docs/changelog/roadmap.md

@@ -7,8 +7,7 @@
 
 ## Bugs
 
-- [ ] 当前 ReAct 智能体有消息顺序错乱的 bug，且不会默认调用工具
-
+-
 
 ## Next
 
@@ -20,7 +19,6 @@
 - [ ] 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示
 - [ ] 开发与生产环境隔离，构建生产镜像 <Badge type="info" text="0.4" />
 - [ ] 支持 MinerU 2.5 的解析方法 <Badge type="info" text="0.3.5" />
-- [ ] 优化全局配置的管理模型，优化配置管理
 
 ## Later
 
@@ -34,3 +32,5 @@
 - [x] 添加测试脚本，覆盖最常见的功能（已覆盖API）
 - [x] 新建 tasker 模块，用来管理所有的后台任务，UI 上使用侧边栏管理。
 - [x] 优化对文档信息的检索展示（检索结果页、详情页）
+- [x] 当前 ReAct 智能体有消息顺序错乱的 bug，且不会默认调用工具
+- [x] 优化全局配置的管理模型，优化配置管理