cutThenThink/docs/P0-8_quick_reference.md

处理流程整合 - 快速参考指南

快速开始

1. 处理单张图片（最简单）

from src.core.processor import process_single_image
from src.config.settings import get_settings

settings = get_settings()

result = process_single_image(
    image_path="/path/to/image.png",
    ai_config=settings.ai,
    db_path="data/cutnthink.db"
)

if result.success:
    print(f"成功! 分类: {result.ai_result.category.value}")

2. 使用处理器（更多控制）

from src.core.processor import ImageProcessor, ProcessCallback

# 创建回调
callback = ProcessCallback()
callback.on_complete = lambda r: print(f"完成! 成功={r.success}")

# 创建处理器
processor = ImageProcessor(
    ocr_config={'mode': 'local', 'lang': 'ch'},
    ai_config=settings.ai,
    db_path="data/cutnthink.db",
    callback=callback
)

# 处理
result = processor.process_image("/path/to/image.png")

3. 创建 Markdown 结果

from src.core.processor import create_markdown_result

markdown = create_markdown_result(
    ai_result=result.ai_result,
    ocr_text=result.ocr_result.full_text
)

print(markdown)

4. 复制到剪贴板

from src.utils.clipboard import copy_to_clipboard

copy_to_clipboard("要复制的文本")

5. 在 GUI 中显示结果

import tkinter as tk
from src.gui.widgets import ResultWidget

root = tk.Tk()
widget = ResultWidget(root)
widget.pack(fill=tk.BOTH, expand=True)
widget.set_result(result)
root.mainloop()

6. 显示对话框

from src.gui.widgets import show_info, show_error, ask_yes_no

show_info("标题", "消息")
show_error("错误", "错误消息")

if ask_yes_no("确认", "继续吗？"):
    print("用户选择是")

7. 初始化日志

from src.utils.logger import init_logger, get_logger

init_logger(log_dir="logs", level="INFO")
logger = get_logger(__name__)

logger.info("信息日志")
logger.error("错误日志")

常用参数

ImageProcessor 初始化参数

参数	类型	默认值	说明
ocr_config	dict	None	OCR 配置 (mode, lang, use_gpu)
ai_config	AIConfig	None	AI 配置对象
db_path	str	None	数据库路径
callback	ProcessCallback	None	回调对象

process_image 参数

参数	类型	默认值	说明
image_path	str	必需	图片路径
save_to_db	bool	True	是否保存到数据库
skip_ocr	bool	False	是否跳过 OCR
skip_ai	bool	False	是否跳过 AI 分类
ocr_text	str	None	直接提供的 OCR 文本

ProcessResult 属性

属性	类型	说明
success	bool	是否处理成功
image_path	str	图片路径
ocr_result	OCRBatchResult	OCR 结果
ai_result	ClassificationResult	AI 结果
record_id	int	数据库记录 ID
process_time	float	处理耗时（秒）
steps_completed	list	已完成的步骤
warnings	list	警告信息

配置示例

OCR 配置

ocr_config = {
    'mode': 'local',      # 'local' 或 'cloud'
    'lang': 'ch',          # 'ch', 'en', 'chinese_chinese'
    'use_gpu': False       # 是否使用 GPU
}

AI 配置（从设置获取）

from src.config.settings import get_settings

settings = get_settings()
ai_config = settings.ai

# 或手动创建
from src.config.settings import AIConfig, AIProvider

ai_config = AIConfig(
    provider=AIProvider.ANTHROPIC,
    api_key="your-api-key",
    model="claude-3-5-sonnet-20241022",
    temperature=0.7
)

回调方法

ProcessCallback 可实现的方法

class MyCallback(ProcessCallback):
    def on_start(self, message): pass
    def on_ocr_start(self, message): pass
    def on_ocr_complete(self, result): pass
    def on_ai_start(self, message): pass
    def on_ai_complete(self, result): pass
    def on_save_start(self, message): pass
    def on_save_complete(self, record_id): pass
    def on_error(self, message, exception): pass
    def on_complete(self, result): pass
    def on_progress(self, step, progress, message): pass

错误处理

try:
    result = processor.process_image(image_path)
except Exception as e:
    print(f"处理失败: {e}")

# 检查结果
if not result.success:
    print(f"错误: {result.error_message}")

# 检查警告
for warning in result.warnings:
    print(f"警告: {warning}")

常见问题

Q: 如何跳过 OCR？

result = processor.process_image(
    image_path="/path/to/image.png",
    skip_ocr=True,
    ocr_text="直接提供的文本"
)

Q: 如何只运行 OCR 不进行 AI 分类？

result = processor.process_image(
    image_path="/path/to/image.png",
    skip_ai=True
)

Q: 如何不保存到数据库？

result = processor.process_image(
    image_path="/path/to/image.png",
    save_to_db=False
)

Q: 如何批量处理？

image_paths = ["img1.png", "img2.png", "img3.png"]
results = processor.batch_process(image_paths)

文件位置

文件	路径
处理器	src/core/processor.py
日志工具	src/utils/logger.py
剪贴板工具	src/utils/clipboard.py
结果组件	src/gui/widgets/result_widget.py
消息处理	src/gui/widgets/message_handler.py
使用文档	docs/P0-8_processor_integration.md
命令行示例	examples/processor_example.py
GUI 示例	examples/gui_integration_example.py
基本测试	tests/test_integration_basic.py