cutThenThink/docs/settings.md

配置管理文档

概述

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

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

配置文件位置

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

配置结构

1. AI 配置 (ai)

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)

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)

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)

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)

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）

使用方法

基本用法

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()

使用配置管理器

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() 方法，用于验证配置的有效性：

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 不能为负数

环境变量支持

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

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

配置迁移

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

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

from src.config.settings import get_config

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

注意事项

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

示例配置文件

# 开发环境配置示例
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(): 获取当前配置对象