feat: 实现CutThenThink P0阶段核心功能
项目初始化 - 创建完整项目结构（src/, data/, docs/, examples/, tests/） - 配置requirements.txt依赖 - 创建.gitignore P0基础框架 - 数据库模型：Record模型，6种分类类型 - 配置管理：YAML配置，支持AI/OCR/云存储/UI配置 - OCR模块：PaddleOCR本地识别，支持云端扩展 - AI模块：支持OpenAI/Claude/通义/Ollama，6种分类 - 存储模块：完整CRUD，搜索，统计，导入导出 - 主窗口框架：侧边栏导航，米白配色方案 - 图片处理：截图/剪贴板/文件选择/图片预览 - 处理流程整合：OCR→AI→存储串联，Markdown展示，剪贴板复制 - 分类浏览：卡片网格展示，分类筛选，搜索，详情查看 技术栈 - PyQt6 + SQLAlchemy + PaddleOCR + OpenAI/Claude SDK - 共47个Python文件，4000+行代码 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
congsh
292
docs/settings.md
Normal file
292
docs/settings.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# 配置管理文档
|
||||
|
||||
## 概述
|
||||
|
||||
配置管理模块提供了完整的配置管理功能，包括：
|
||||
|
||||
- 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()`: 获取当前配置对象
|
||||
Reference in New Issue
Block a user