cutThenThink/docs/settings.md

# 配置管理文档

## 概述

配置管理模块提供了完整的配置管理功能，包括：

- AI 配置（API keys, 模型选择, 提供商）
- OCR 配置（本地/云端选择, API keys）
- 云存储配置（类型, endpoint, 凭证）
- 界面配置（主题, 快捷键）
- 高级配置（调试、日志等）

## 配置文件位置

默认配置文件路径：`~/.cutthenthink/config.yaml`

## 配置结构

### 1. AI 配置 (ai)

```yaml
ai:
  provider: anthropic          # AI 提供商: openai, anthropic, azure, custom
  api_key: ""                  # API 密钥
  model: claude-3-5-sonnet-20241022  # 模型名称
  temperature: 0.7             # 温度参数 (0-2)
  max_tokens: 4096            # 最大 token 数
  timeout: 60                  # 请求超时时间（秒）
  base_url: ""                 # 自定义/Azure 的 base URL
  extra_params: {}            # 额外参数
```

**可用的 AI 提供商：**
- `openai`: OpenAI (GPT-4, GPT-3.5 等)
- `anthropic`: Anthropic (Claude 系列)
- `azure`: Azure OpenAI
- `custom`: 自定义端点

### 2. OCR 配置 (ocr)

```yaml
ocr:
  mode: local                  # 模式: local(本地) 或 cloud(云端)
  api_key: ""                  # 云端 OCR API key
  api_endpoint: ""            # 云端 OCR 端点
  use_gpu: false              # 本地 OCR 是否使用 GPU
  lang: ch                    # 语言: ch(中文), en(英文)
  timeout: 30                 # 请求超时时间（秒）
```

**OCR 模式：**
- `local`: 使用本地 PaddleOCR（需要安装 PaddlePaddle）
- `cloud`: 使用云端 OCR API（需要配置 api_endpoint）

### 3. 云存储配置 (cloud_storage)

```yaml
cloud_storage:
  type: none                   # 存储类型: none, s3, oss, cos, minio
  endpoint: ""                # 存储端点
  access_key: ""             # 访问密钥
  secret_key: ""             # 密钥
  bucket: ""                 # 存储桶名称
  region: ""                 # 区域
  timeout: 30                # 请求超时时间（秒）
```

**云存储类型：**
- `none`: 不使用云存储
- `s3`: AWS S3 兼容存储
- `oss`: 阿里云 OSS
- `cos`: 腾讯云 COS
- `minio`: MinIO

### 4. 界面配置 (ui)

```yaml
ui:
  theme: auto                 # 主题: light, dark, auto
  language: zh_CN            # 界面语言
  window_width: 1200         # 窗口宽度
  window_height: 800         # 窗口高度
  hotkeys:                   # 快捷键
    screenshot: Ctrl+Shift+A  # 截图
    ocr: Ctrl+Shift+O        # OCR 识别
    quick_capture: Ctrl+Shift+X  # 快速捕获
    show_hide: Ctrl+Shift+H  # 显示/隐藏窗口
  show_tray_icon: true       # 显示托盘图标
  minimize_to_tray: true     # 最小化到托盘
  auto_start: false          # 开机自启
```

### 5. 高级配置 (advanced)

```yaml
advanced:
  debug_mode: false          # 调试模式
  log_level: INFO           # 日志级别: DEBUG, INFO, WARNING, ERROR, CRITICAL
  log_file: ""              # 日志文件路径（空为控制台输出）
  max_log_size: 10          # 单个日志文件最大大小（MB）
  backup_count: 5           # 保留的日志文件数量
  cache_dir: ""             # 缓存目录（空为默认）
  temp_dir: ""              # 临时文件目录（空为默认）
  max_cache_size: 500       # 最大缓存大小（MB）
```

## 使用方法

### 基本用法

```python
from src.config.settings import get_settings, get_config

# 获取配置对象
settings = get_settings()

# 访问配置
print(f"AI 提供商: {settings.ai.provider}")
print(f"模型名称: {settings.ai.model}")
print(f"界面主题: {settings.ui.theme}")

# 修改配置
settings.ai.api_key = "your-api-key"
settings.ui.theme = "dark"

# 保存配置
config_manager = get_config()
config_manager.save()
```

### 使用配置管理器

```python
from src.config.settings import SettingsManager
from pathlib import Path

# 使用默认路径
manager = SettingsManager()

# 或指定自定义路径
manager = SettingsManager(Path("/path/to/config.yaml"))

# 加载配置
settings = manager.load()

# 保存配置
manager.save()

# 重置为默认配置
manager.reset()

# 获取嵌套值
provider = manager.get('ai.provider')
theme = manager.get('ui.theme', 'auto')  # 带默认值

# 设置嵌套值
manager.set('ai.temperature', 1.0)
manager.set('ui.window_width', 1400)
```

### 配置验证

所有配置类都包含 `validate()` 方法，用于验证配置的有效性：

```python
from src.config.settings import AIConfig, AIProvider, ConfigError

config = AIConfig(
    provider=AIProvider.OPENAI,
    api_key="sk-test",
    temperature=1.0
)

try:
    config.validate()
    print("配置有效")
except ConfigError as e:
    print(f"配置错误: {e}")
```

## 配置验证规则

### AI 配置验证
- API key 不能为空（provider 不是 custom 时）
- temperature 必须在 0-2 之间
- max_tokens 必须大于 0
- timeout 必须大于 0

### OCR 配置验证
- 云端模式需要指定 api_endpoint

### 云存储配置验证
- 非 none 类型需要指定 endpoint
- 需要指定 access_key 和 secret_key
- 需要指定 bucket

### 界面配置验证
- window_width 不能小于 400
- window_height 不能小于 300

### 高级配置验证
- log_level 必须是有效的日志级别
- max_log_size 不能小于 1
- backup_count 不能为负数

## 环境变量支持

可以通过环境变量覆盖配置（未来功能）：

```bash
export CUTTHENTHINK_AI_API_KEY="your-api-key"
export CUTTHENTHINK_AI_PROVIDER="openai"
```

## 配置迁移

如果配置文件损坏或格式错误，可以：

1. 删除配置文件，程序会自动创建默认配置
2. 或使用 `manager.reset()` 重置为默认配置

```python
from src.config.settings import get_config

manager = get_config()
manager.reset()  # 重置为默认配置
```

## 注意事项

1. **安全性**：配置文件包含敏感信息（API keys），请确保文件权限设置正确
2. **备份**：修改配置前建议备份原文件
3. **验证**：修改配置后程序会自动验证，无效配置会抛出 `ConfigError`
4. **版本控制**：配置文件不应提交到版本控制系统（已在 .gitignore 中）

## 示例配置文件

```yaml
# 开发环境配置示例
ai:
  provider: anthropic
  api_key: "sk-ant-xxx"
  model: claude-3-5-sonnet-20241022
  temperature: 0.7
  max_tokens: 4096

ocr:
  mode: local
  use_gpu: false
  lang: ch

cloud_storage:
  type: none

ui:
  theme: auto
  language: zh_CN
  window_width: 1400
  window_height: 900

advanced:
  debug_mode: true
  log_level: DEBUG
```

## API 参考

### 类

- `Settings`: 主配置类
- `SettingsManager`: 配置管理器
- `AIConfig`: AI 配置类
- `OCRConfig`: OCR 配置类
- `CloudStorageConfig`: 云存储配置类
- `UIConfig`: 界面配置类
- `AdvancedConfig`: 高级配置类

### 枚举

- `AIProvider`: AI 提供商枚举
- `OCRMode`: OCR 模式枚举
- `CloudStorageType`: 云存储类型枚举
- `Theme`: 主题枚举

### 异常

- `ConfigError`: 配置错误异常

### 函数

- `get_config()`: 获取全局配置管理器
- `get_settings()`: 获取当前配置对象