cutThink_lite/docs/PHASE5_SUMMARY.md

Phase 5 - AI 分类系统实现总结

实施日期

2026-02-12

实施内容

1. AI 服务模块 (src-tauri/src/ai/)

模块结构

ai/
├── mod.rs          # 模块定义，导出公共接口
├── client.rs       # AI API 客户端实现
├── prompt.rs       # Prompt 模板引擎
├── template.rs     # 模板管理器
└── classify.rs     # 分类器实现

核心功能

1.1 AI API 集成 (client.rs)

• 支持 Claude API (Anthropic)
• 支持 OpenAI GPT API
• 实现流式响应处理
• API 调用限流（每秒最多 5 个请求）
• 超时控制（120 秒）
• 错误处理（认证失败、限流、网络错误等）

1.2 Prompt 模板引擎 (prompt.rs)

• 变量替换：{{variable_name}}
• 条件块：{{#if var}}...{{/if}}
• 内置模板库：
  • general - 通用分类
  • code - 代码片段分类
  • invoice - 票据发票分类
  • conversation - 对话内容分类

1.3 模板管理器 (template.rs)

• 模板 CRUD 操作
• 模板导入/导出（JSON 格式）
• 模板验证
• 模板测试渲染
• 文件持久化存储

1.4 分类器 (classify.rs)

• 基于模板的内容分类
• 置信度评分
• 流式分类支持
• 分类结果解析（JSON 提取）
• 人工确认机制

2. 数据库扩展 (src-tauri/src/database.rs)

新增表结构

classifications 表

CREATE TABLE classifications (
    id TEXT PRIMARY KEY,
    record_id TEXT NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT,
    tags TEXT NOT NULL,
    confidence REAL NOT NULL,
    reasoning TEXT,
    template_id TEXT,
    confirmed BOOLEAN NOT NULL DEFAULT 0,
    created_at TEXT NOT NULL,
    FOREIGN KEY (record_id) REFERENCES records(id) ON DELETE CASCADE
)

classification_history 表

CREATE TABLE classification_history (
    id TEXT PRIMARY KEY,
    record_id TEXT NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT,
    confidence REAL NOT NULL,
    created_at TEXT NOT NULL,
    FOREIGN KEY (record_id) REFERENCES records(id) ON DELETE CASCADE
)

新增方法

• save_classification() - 保存分类结果
• get_classification() - 获取记录的分类
• confirm_classification() - 确认分类
• get_classification_history() - 获取分类历史
• list_records_by_category() - 按分类查询记录
• get_category_stats() - 获取分类统计

3. Tauri 命令 (src-tauri/src/lib.rs)

AI 配置命令

• ai_save_api_key - 保存 API 密钥
• ai_get_api_keys - 获取 API 密钥状态
• ai_configure_provider - 配置 AI 提供商

分类命令

• ai_classify - 执行 AI 分类
• ai_classify_stream - 流式 AI 分类

模板管理命令

• template_list - 列出所有模板
• template_get - 获取单个模板
• template_save - 保存模板
• template_delete - 删除模板
• template_test - 测试模板渲染

分类结果命令

• classification_get - 获取记录分类
• classification_confirm - 确认分类
• classification_history - 获取分类历史
• classification_stats - 获取分类统计

4. 前端实现

4.1 API 接口 (src/api/ai.ts)

// 分类 API
classifyContent()
classifyContentStream()

// AI 配置 API
saveAiApiKey()
getAiApiKeys()
configureAiProvider()

// 模板管理 API
listTemplates()
getTemplate()
saveTemplate()
deleteTemplate()
testTemplate()

// 分类结果 API
getClassification()
confirmClassification()
getClassificationHistory()
getClassificationStats()

4.2 状态管理 (src/store/ai.ts)

• aiConfig - AI 配置状态
• templates - 模板列表状态
• classification - 分类执行状态
• 派生 stores: builtinTemplates, customTemplates, isConfigured

4.3 UI 组件

AiConfigView.svelte - AI 配置界面

• Claude API Key 配置
• OpenAI API Key 配置
• 模型选择
• Base URL 自定义（兼容服务）
• 配置状态显示

AiTemplatesView.svelte - 模板管理界面

• 内置模板列表
• 自定义模板 CRUD
• 模板测试功能
• 模板导入/导出
• 变量管理

AutoClassifyView.svelte - 自动分类组件

• 模板选择
• 流式/非流式模式切换
• 实时结果预览
• 分类结果展示
• 置信度显示

5. 依赖更新 (Cargo.toml)

# Phase 5 dependencies (AI)
thiserror = "1.0"

技术特点

1. 模块化设计

• AI 功能完全独立，易于维护
• 清晰的职责划分
• 可扩展的架构

2. 多 AI 提供商支持

• 统一的客户端接口
• 可轻松添加新的提供商
• 流式响应支持

3. 灵活的模板系统

• 内置常用模板
• 支持自定义模板
• 模板测试和验证
• 导入/导出功能

4. 智能分类

• 置信度评分
• 人工确认机制
• 分类历史记录
• 统计分析

5. 用户体验

• 流式实时响应
• 进度反馈
• 错误处理
• 直观的 UI

验证标准完成情况

✅ 至少 2 种 AI API 测试通过

• Claude API 集成完成
• OpenAI API 集成完成
• 支持自定义 Base URL（兼容服务）

✅ 流式响应实时显示

• 实现了流式 API 调用
• 前端实时显示响应内容
• 支持 SSE 格式解析

✅ 变量替换正确执行

• 支持 {{var}} 简单变量替换
• 支持 {{#if var}}...{{/if}} 条件块
• 模板测试功能验证

✅ 内置模板可加载

• 4 个内置模板实现
• 启动时自动加载
• 模板分类管理

✅ 模板可创建、编辑、删除

• 完整的 CRUD 操作
• 模板验证
• 文件持久化

✅ 截图后自动触发分类（可选）

• 自动分类组件实现
• 可通过配置启用
• 支持多种内容类型

使用流程

1. 配置 AI

1. 打开 AI 配置界面
2. 选择提供商（Claude 或 OpenAI）
3. 输入 API Key
4. 选择模型
5. 保存并启用

2. 管理模板（可选）

1. 打开模板管理界面
2. 查看内置模板
3. 创建/编辑自定义模板
4. 测试模板渲染
5. 导入/导出模板

3. 执行分类

1. 选择记录
2. 选择分类模板
3. 配置变量
4. 执行分类
5. 查看结果
6. 确认或调整

集成点

与现有功能的集成

1. OCR 集成

   • OCR 结果可作为变量传递给 AI
   • 自动分类图片内容

2. 剪贴板集成

   • 复制后自动触发分类
   • 分类结果自动添加标签

3. 记录管理

   • 分类信息与记录关联
   • 按分类筛选记录
   • 分类历史追踪

扩展点

1. 新 AI 提供商

   • 在 client.rs 中添加新的提供商枚举
   • 实现对应的 API 调用方法

2. 新模板

   • 通过 UI 创建
   • 通过 JSON 导入
   • 在 prompt.rs 中添加内置模板

3. 分类后处理

   • 自动打标签
   • 自动移动到分类
   • 触发自动化流程

性能优化

1. 限流保护

   • 每秒最多 5 个请求
   • 避免触发 API 限制

2. 缓存机制

   • 模板缓存
   • API 密钥缓存

3. 异步处理

   • 所有 AI 调用异步执行
   • 不阻塞主线程

4. 超时控制

   • 请求超时 120 秒
   • 避免长时间等待

安全考虑

1. API 密钥存储

   • 存储在数据库中
   • 未来可加密存储

2. HTTPS 通信

   • 所有 API 调用使用 HTTPS
   • 防止中间人攻击

3. 输入验证

   • 模板变量验证
   • 用户输入清理

已知限制

1. AI 准确性

   • 依赖 AI 模型能力
   • 可能需要人工调整

2. 网络依赖

   • 需要网络连接
   • API 服务可用性

3. 成本考虑

   • API 调用产生费用
   • 需要合理使用

未来改进

1. 离线模式

   • 支持本地 AI 模型
   • Ollama 集成

2. 批量处理

   • 批量分类
   • 后台任务队列

3. 自动化规则

   • 基于分类的自动化
   • 触发器配置

4. 智能建议

   • 基于历史的模板推荐
   • 变量自动填充

5. 性能监控

   • API 调用统计
   • 成本追踪

文件清单

Rust 后端

• src-tauri/src/ai/mod.rs - 模块定义
• src-tauri/src/ai/client.rs - AI 客户端
• src-tauri/src/ai/prompt.rs - Prompt 引擎
• src-tauri/src/ai/template.rs - 模板管理
• src-tauri/src/ai/classify.rs - 分类器
• src-tauri/src/database.rs - 数据库扩展
• src-tauri/src/lib.rs - Tauri 命令
• src-tauri/Cargo.toml - 依赖更新

前端

• src/api/ai.ts - API 接口
• src/store/ai.ts - 状态管理
• src/components/views/AiConfigView.svelte - 配置界面
• src/components/views/AiTemplatesView.svelte - 模板管理
• src/components/views/AutoClassifyView.svelte - 自动分类

总结

Phase 5 成功实现了完整的 AI 分类系统，包括：

• ✅ 多 AI 提供商支持（Claude + OpenAI）
• ✅ 灵活的 Prompt 模板引擎
• ✅ 完整的模板管理系统
• ✅ 智能内容分类
• ✅ 用户友好的界面
• ✅ 数据库集成和持久化

系统采用模块化设计，易于扩展和维护，为 CutThenThink Lite 提供了强大的 AI 能力。