feat(OCR): 添加基于大模型的OCR作为PaddleOCR的替代方案，支持Bot私聊配置

[ModerRAS]

概述

为现有的PaddleOCR添加基于大语言模型(LLM)的OCR作为替代方案，并在Bot私聊中创建状态机来配置OCR设置（参考现有的 editllmconfig 流程）。

背景

目前OCR功能只使用PaddleOCR。用户希望：

1. 添加使用LLM的替代OCR选项
2. 支持通过Bot私聊切换OCR引擎
3. 提供OCR模型选择配置选项

实施计划

第一阶段：核心OCR服务

任务	文件	描述
T1.1	Interface/AI/OCR/IOCRService.cs	创建新的OCR抽象接口和引擎枚举
T1.2	Service/AI/OCR/LLMOCRService.cs	使用现有GeneralLLMService实现基于LLM的OCR
T1.3	添加配置常量	将OCR:Engine、OCR:LLMModelName、OCR:LLMChannelId添加到AppConfigurationItem
T1.4	TelegramSearchBot.Test/AI/OCR/	OCR服务的单元测试

第二阶段：状态机

任务	文件	描述
T2.1	Model/AI/OCRConfState.cs	创建OCR配置状态的新枚举
T2.2	Helper/EditOCRConfRedisHelper.cs	参考EditLLMConfRedisHelper模式的Redis辅助类
T2.3	Service/Manage/EditOCRConfService.cs	状态机逻辑和处理器
T2.4	TelegramSearchBot.Test/Manage/EditOCRConfTest.cs	状态机的单元测试

第三阶段：Bot集成

任务	文件	描述
T3.1	Controller/Manage/EditOCRConfController.cs	OCR配置的Bot控制器（仅私聊，仅管理员）
T3.2	Controller/AI/OCR/AutoOCRController.cs	修改以使用OCR引擎选择
T3.3	View/EditOCRConfView.cs	OCR配置响应的视图

状态机流程

主菜单（发送 \"OCR设置\"）
├── 1. 切换OCR引擎 → 选择引擎 (PaddleOCR/LLM)
│   └── 如果选LLM → 选择渠道 → 选择模型
├── 2. 查看OCR配置 → 显示当前配置
└── 3. 返回 → 退出

配置键（存储在AppConfigurationItem中）

• OCR:Engine - 当前OCR引擎 (PaddleOCR/LLM)
• OCR:LLMModelName - LLM OCR的模型名称
• OCR:LLMChannelId - 可选：OCR专用LLM渠道

关键设计决策

1. IOCRService接口：新接口，扩展OCR能力并添加Engine属性
2. OCRServiceFactory：工厂模式，用于在PaddleOCR和LLMOCR之间选择
3. 向后兼容：如果没有OCR配置，默认使用PaddleOCR
4. LLMOCRService：使用现有的GeneralLLMService.AnalyzeImageAsync进行OCR

需要创建的文件

1. TelegramSearchBot/Interface/AI/OCR/IOCRService.cs
2. TelegramSearchBot/Service/AI/OCR/LLMOCRService.cs
3. TelegramSearchBot/Model/AI/OCRConfState.cs
4. TelegramSearchBot/Helper/EditOCRConfRedisHelper.cs
5. TelegramSearchBot/Service/Manage/EditOCRConfService.cs
6. TelegramSearchBot/Controller/Manage/EditOCRConfController.cs
7. TelegramSearchBot/View/EditOCRConfView.cs

需要修改的文件

1. TelegramSearchBot/Controller/AI/OCR/AutoOCRController.cs - 添加OCR引擎选择逻辑
2. 在现有服务中添加配置常量（GeneralLLMService或新建）

参考

• 现有模式：EditLLMConfService.cs 状态机
• 现有模式：EditLLMConfRedisHelper.cs Redis存储
• 现有模式：LLMConfState.cs 状态枚举

待确认问题

1. 用户应该从现有LLM渠道/模型中选择，还是有单独的OCR专用配置？
2. LLM OCR提示词是否应该可配置？
3. 是否应该有单独的LLM和PaddleOCR超时配置？

---

此Issue用于跟踪实施进度。每个原子变更将创建单独的PR。

[github-actions]

AI Implementation Plan

Problem Summary

Issue #241 requests adding an LLM-based OCR as an alternative to the existing PaddleOCR, along with a state machine for configuring OCR settings via Bot private chat.

Core Requirements:

1. Create an abstraction layer (IOCRService) to support multiple OCR engines
2. Implement LLMOCRService using the existing GeneralLLMService.AnalyzeImageAsync()
3. Create a state machine for OCR configuration in private chat (following the editllmconfig pattern)
4. Add configuration keys: OCR:Engine, OCR:LLMModelName, OCR:LLMChannelId

---

Modules Affected

New Files to Create

File	Description
TelegramSearchBot/Interface/AI/OCR/IOCRService.cs	New OCR interface with Engine enum
TelegramSearchBot/Service/AI/OCR/LLMOCRService.cs	LLM-based OCR implementation
TelegramSearchBot/Model/AI/OCRConfState.cs	State enum for OCR configuration
TelegramSearchBot/Helper/EditOCRConfRedisHelper.cs	Redis helper for state machine
TelegramSearchBot/Service/Manage/EditOCRConfService.cs	State machine logic
TelegramSearchBot/Controller/Manage/EditOCRConfController.cs	Bot controller for OCR config
TelegramSearchBot/View/EditOCRConfView.cs	View for OCR config responses
TelegramSearchBot.Test/Manage/EditOCRConfTest.cs	Unit tests for state machine
TelegramSearchBot.Test/AI/OCR/LLMOCRServiceTest.cs	Unit tests for LLM OCR

Files to Modify

File	Changes
TelegramSearchBot/Controller/AI/OCR/AutoOCRController.cs	Add OCR engine selection logic
TelegramSearchBot.LLM/Service/AI/LLM/GeneralLLMService.cs	Add OCR config constants
TelegramSearchBot/AppBootstrap/OCRBootstrap.cs	Register new services

---

Step-by-Step Implementation Plan

Phase 1: Core OCR Service

T1.1: Create IOCRService Interface

File: TelegramSearchBot/Interface/AI/OCR/IOCRService.cs

namespace TelegramSearchBot.Interface.AI.OCR {
    public enum OCREngine {
        PaddleOCR,
        LLM
    }

    public interface IOCRService {
        OCREngine Engine { get; }
        Task<string> ExecuteAsync(Stream file);
    }
}

Dependencies: None (new file)

T1.2: Add Configuration Constants

File: TelegramSearchBot.LLM/Service/AI/LLM/GeneralLLMService.cs

Add new constants after existing ones:

public const string OCREngineKey = "OCR:Engine";
public const string OCRLLMModelNameKey = "OCR:LLMModelName";
public const string OCRLLMChannelIdKey = "OCR:LLMChannelId";

T1.3: Create LLMOCRService

File: TelegramSearchBot/Service/AI/OCR/LLMOCRService.cs

• Use IGeneralLLMService.AnalyzeImageAsync() method
• Read OCR config from AppConfigurationItem
• Implement IOCRService interface
• Handle file stream to temp path conversion

T1.4: Unit Tests for LLMOCRService

File: TelegramSearchBot.Test/AI/OCR/LLMOCRServiceTest.cs

• Test OCR with valid image
• Test fallback to default model when not configured
• Test error handling

---

Phase 2: State Machine

T2.1: Create OCRConfState Enum

File: TelegramSearchBot/Model/AI/OCRConfState.cs

Follow pattern from LLMConfState.cs:

public enum OCRConfState {
    [Description("main_menu")]
    MainMenu,
    
    [Description("selecting_engine")]
    SelectingEngine,
    
    [Description("selecting_llm_channel")]
    SelectingLLMChannel,
    
    [Description("selecting_llm_model")]
    SelectingLLMModel,
    
    [Description("viewing_config")]
    ViewingConfig
}

T2.2: Create EditOCRConfRedisHelper

File: TelegramSearchBot/Helper/EditOCRConfRedisHelper.cs

Follow pattern from EditLLMConfRedisHelper.cs:

• Key prefix: ocrconf:{chatId}
• Methods: GetStateAsync, SetStateAsync, GetDataAsync, SetDataAsync, DeleteKeysAsync

T2.3: Create EditOCRConfService

File: TelegramSearchBot/Service/Manage/EditOCRConfService.cs

State Handlers:

1. HandleMainMenuAsync - Show main menu options
2. HandleSelectingEngineAsync - Process engine selection (PaddleOCR/LLM)
3. HandleSelectingLLMChannelAsync - Process channel selection
4. HandleSelectingLLMModelAsync - Process model name input
5. HandleViewingConfigAsync - Display current OCR config

Direct Commands:

• "OCR设置" / "OCR配置" - Enter main menu
• "切换OCR引擎" - Start engine selection
• "选择渠道" - Start channel selection (only when LLM selected)
• "选择模型" - Start model selection (only when LLM selected)
• "查看配置" - Display current configuration
• "返回" / "退出" - Exit to main menu

T2.4: Unit Tests for State Machine

File: TelegramSearchBot.Test/Manage/EditOCRConfTest.cs

• Test main menu display
• Test engine switching
• Test LLM channel selection
• Test LLM model configuration
• Test viewing current config
• Test state persistence in Redis

---

Phase 3: Bot Integration

T3.1: Create EditOCRConfController

File: TelegramSearchBot/Controller/Manage/EditOCRConfController.cs

Constraints:

• Only respond to private chats (Chat.Id < 0)
• Only respond to admin (From.Id == Env.AdminId)

Flow:

1. Check if message is private chat
2. Check if user is admin
3. Pass command to EditOCRConfService.ExecuteAsync
4. Render response via EditOCRConfView

T3.2: Modify AutoOCRController

File: TelegramSearchBot/Controller/AI/OCR/AutoOCRController.cs

Changes:

1. Inject IOCRServiceFactory or IOCRService instead of IPaddleOCRService
2. Read OCR:Engine from config at runtime
3. Select appropriate OCR service based on config
4. Keep backward compatibility: default to PaddleOCR if not configured

T3.3: Create EditOCRConfView

File: TelegramSearchBot/View/EditOCRConfView.cs

Follow pattern from EditLLMConfView.cs:

• Chainable methods: WithChatId, WithReplyTo, WithMessage
• Use ISendMessageService.SplitAndSendTextMessage

T3.4: Register Services in OCRBootstrap

File: TelegramSearchBot/AppBootstrap/OCRBootstrap.cs

Add registrations:

• IOCRService, PaddleOCRService
• IOCRService, LLMOCRService
• IOCRServiceFactory (or use IEnumerable injection)

---

Testing Strategy

Unit Tests

1. LLMOCRServiceTest:

   • Mock IGeneralLLMService
   • Test OCR execution with mock image
   • Test configuration reading

2. EditOCRConfTest:

   • Mock IConnectionMultiplexer
   • Mock DataDbContext
   • Test state transitions
   • Test command parsing

3. EditOCRConfHelperTest (if needed):

   • Test configuration CRUD operations

Integration Tests

1. Test full flow: send "OCR设置" → receive menu → select "切换OCR引擎" → select "LLM" → configure channel → verify config saved

Manual Testing

1. Private message to Bot as admin
2. Test engine switching
3. Test viewing current configuration
4. Verify OCR uses selected engine

---

Key Design Decisions

1. Interface Segregation: IOCRService extends OCR capability with Engine property

2. Factory Pattern: Use IOCRServiceFactory to select between PaddleOCR and LLMOCR based on config

3. Backward Compatibility: Default to PaddleOCR if no OCR config exists

4. State Machine Pattern: Follow exact pattern from EditLLMConfService for consistency

5. Admin-Only Access: OCR config only accessible to admin in private chat

---

Implementation Order

1. T1.1 → T1.2 → T1.3 → T1.4 (Core OCR Service)
2. T2.1 → T2.2 → T2.3 → T2.4 (State Machine)
3. T3.1 → T3.2 → T3.3 → T3.4 (Bot Integration)
4. End-to-end testing

---

References

• EditLLMConfService.cs - State machine pattern
• EditLLMConfRedisHelper.cs - Redis storage pattern
• LLMConfState.cs - State enum pattern
• EditLLMConfController.cs - Controller pattern
• EditLLMConfView.cs - View pattern
• GeneralLLMService.AnalyzeImageAsync() - LLM image analysis method
• AutoOCRController.cs - Current OCR controller

[github-actions]

AI Implementation Plan

Issue #241: Add LLM-based OCR Alternative with Bot Configuration State Machine

1. Problem Summary

Currently, the OCR functionality only uses PaddleOCR. This issue requests:

1. Add an LLM-based OCR as an alternative engine using the existing GeneralLLMService
2. Create a state machine in Bot private chat to configure OCR settings (similar to editllmconfig)
3. Support switching between PaddleOCR and LLM engines
4. Allow configuration of LLM model and optional dedicated channel for OCR

2. Modules Affected

New Files to Create

File	Description
TelegramSearchBot/Interface/AI/OCR/IOCRService.cs	New OCR interface with Engine enum
TelegramSearchBot/Service/AI/OCR/LLMOCRService.cs	LLM-based OCR implementation
TelegramSearchBot/Model/AI/OCRConfState.cs	State enum for OCR configuration
TelegramSearchBot/Helper/EditOCRConfRedisHelper.cs	Redis helper for state machine
TelegramSearchBot/Service/Manage/EditOCRConfService.cs	State machine logic
TelegramSearchBot/Controller/Manage/EditOCRConfController.cs	Bot controller (private only, admin only)
TelegramSearchBot/View/EditOCRConfView.cs	View for responses
TelegramSearchBot.Test/AI/OCR/LLMOCRServiceTests.cs	Unit tests for LLMOCRService
TelegramSearchBot.Test/Manage/EditOCRConfTest.cs	Unit tests for state machine

Files to Modify

File	Changes
TelegramSearchBot/Controller/AI/OCR/AutoOCRController.cs	Add OCR engine selection logic
TelegramSearchBot/Service/AI/OCR/PaddleOCRService.cs	Implement IOCRService interface
Dependency injection registration	Register new OCR services

3. Step-by-Step Implementation Plan

Phase 1: Core OCR Service (T1.1 - T1.4)

T1.1: Create IOCRService Interface

File: TelegramSearchBot/Interface/AI/OCR/IOCRService.cs

namespace TelegramSearchBot.Interface.AI.OCR {
    public enum OCREngine {
        PaddleOCR,
        LLM
    }

    public interface IOCRService {
        OCREngine Engine { get; }
        Task<string> ExecuteAsync(Stream file);
    }
}

• Follow existing pattern: Interface/AI/OCR/IPaddleOCRService.cs
• Add Engine property to identify the OCR engine

T1.2: Create LLMOCRService

File: TelegramSearchBot/Service/AI/OCR/LLMOCRService.cs

• Use existing GeneralLLMService.AnalyzeImageAsync() for OCR
• Use a system prompt optimized for OCR (e.g., "Extract all text from this image")
• Follow pattern: Service/AI/OCR/PaddleOCRService.cs
• Constructor injection: IGeneralLLMService, DataDbContext

T1.3: Add Configuration Constants

In GeneralLLMService or new location, add config keys:

• OCR:Engine - Current OCR engine (PaddleOCR/LLM)
• OCR:LLMModelName - LLM model for OCR
• OCR:LLMChannelId - Optional: dedicated channel for OCR

Reference pattern: LLM:AltPhotoModelName in GeneralLLMService

T1.4: Unit Tests for OCR Services

File: TelegramSearchBot.Test/AI/OCR/LLMOCRServiceTests.cs

• Test LLMOCRService.ExecuteAsync with mocked GeneralLLMService
• Test default engine fallback (PaddleOCR if no config)

---

Phase 2: State Machine (T2.1 - T2.4)

T2.1: Create OCRConfState Enum

File: TelegramSearchBot/Model/AI/OCRConfState.cs

Reference: Model/AI/LLMConfState.cs

namespace TelegramSearchBot.Model.AI {
    public enum OCRConfState {
        [Description("selecting_engine")]
        SelectingEngine,

        [Description("selecting_channel")]
        SelectingChannel,

        [Description("selecting_model")]
        SelectingModel,

        [Description("viewing_config")]
        ViewingConfig
    }
}

T2.2: Create EditOCRConfRedisHelper

File: TelegramSearchBot/Helper/EditOCRConfRedisHelper.cs

Reference: Helper/EditLLMConfRedisHelper.cs

• Keys: ocrconf:{chatId}:state, ocrconf:{chatId}:data
• Methods: GetStateAsync(), SetStateAsync(), GetDataAsync(), SetDataAsync(), DeleteKeysAsync()

T2.3: Create EditOCRConfService

File: TelegramSearchBot/Service/Manage/EditOCRConfService.cs

Reference: Service/Manage/EditLLMConfService.cs (580 lines)

Main Menu Commands (no state):

• "OCR设置" - Enter OCR config menu
• "切换OCR引擎" - Switch between PaddleOCR/LLM
• "查看OCR配置" - View current OCR configuration

State Handlers:

• SelectingEngine - User selects PaddleOCR or LLM
• SelectingChannel - If LLM, select channel (use existing LLM channels)
• SelectingModel - Select model from the channel
• ViewingConfig - Display current configuration

Configuration Persistence:

• Store in AppConfigurationItem table
• Use AppConfigurationService or direct DbContext

T2.4: Unit Tests for State Machine

File: TelegramSearchBot.Test/Manage/EditOCRConfTest.cs

Reference: TelegramSearchBot.Test/Manage/EditLLMConfTest.cs (460 lines)

Test scenarios:

• Enter menu with "OCR设置"
• Switch to LLM engine
• Select channel and model
• View current configuration
• Exit/return

---

Phase 3: Bot Integration (T3.1 - T3.3)

T3.1: Create EditOCRConfController

File: TelegramSearchBot/Controller/Manage/EditOCRConfController.cs

Reference: Controller/Manage/EditLLMConfController.cs

• Private chat only: if (e?.Message?.Chat?.Id < 0) return;
• Admin only: if (e?.Message?.From?.Id != Env.AdminId) return;
• Dependencies: None (entry point)

T3.2: Modify AutoOCRController

File: TelegramSearchBot/Controller/AI/OCR/AutoOCRController.cs

Current: Uses IPaddleOCRService directly

Changes:

1. Inject IEnumerable<IOCRService> or use factory
2. Read OCR:Engine config
3. Select appropriate OCR service based on config
4. Fall back to PaddleOCR if no config

T3.3: Create EditOCRConfView

File: TelegramSearchBot/View/EditOCRConfView.cs

Reference: View/EditLLMConfView.cs

• Simple text response view
• Use ISendMessageService.SplitAndSendTextMessage()

---

Phase 4: Dependency Injection

Register services in appropriate location (Program.cs or startup):

// OCR Services
services.AddScoped<IPaddleOCRService, PaddleOCRService>();
services.AddScoped<IOCRService>(sp => sp.GetRequiredService<IPaddleOCRService>());
services.AddScoped<LLMOCRService>();
services.AddScoped<IOCRService>(sp => sp.GetRequiredService<LLMOCRService>());

// Or use factory pattern
services.AddScoped<OCRServiceFactory>();

---

4. State Machine Flow

User sends "OCR设置"
    │
    ▼
┌─────────────────────────────────────┐
│         Main Menu                   │
│ 1. 切换OCR引擎                      │
│ 2. 查看OCR配置                      │
│ 3. 返回                              │
└─────────────────────────────────────┘
    │
    ├── "1" ──► SelectingEngine ──► [PaddleOCR/LLM]
    │                    │
    │                    └── If LLM ──► SelectingChannel ──► [Channel List]
    │                                               │
    │                                               └── SelectingModel ──► [Model List]
    │
    ├── "2" ──► ViewingConfig ──► Display current config
    │
    └── "3" ──► Exit (DeleteKeysAsync)

---

5. Configuration Keys

Key	Type	Default	Description
OCR:Engine	string	"PaddleOCR"	Current OCR engine
OCR:LLMModelName	string	null	LLM model for OCR
OCR:LLMChannelId	int?	null	Optional dedicated channel

---

6. Testing Strategy

Unit Tests

1. LLMOCRServiceTests

   • Mock IGeneralLLMService
   • Test ExecuteAsync() calls correct LLM method
   • Test OCR prompt is appropriate

2. EditOCRConfRedisHelperTests

   • Test state/data get/set
   • Test key deletion

3. EditOCRConfServiceTests

   • Test main menu commands
   • Test state transitions
   • Test configuration persistence (using InMemoryDatabase)
   • Test error handling

4. AutoOCRControllerTests

   • Test OCR engine selection based on config
   • Test fallback to PaddleOCR

Integration Tests

• Full state machine flow (manual testing)
• OCR result comparison (PaddleOCR vs LLM)

---

7. Key Design Decisions

1. Factory vs IEnumerable: Use factory pattern for OCR service selection to keep selection logic centralized

2. Backward Compatibility: Default to PaddleOCR if no config exists

3. LLM Channel Selection: Reuse existing LLM channels instead of creating separate OCR-only channels (user can select any channel)

4. OCR Prompt: Hardcode for now, can be made configurable in future

5. State Machine Cleanup: Always call DeleteKeysAsync() when exiting or completing configuration

---

8. Reference Files

Purpose	File
OCR Interface	Interface/AI/OCR/IPaddleOCRService.cs
OCR Service	Service/AI/OCR/PaddleOCRService.cs
State Enum	Model/AI/LLMConfState.cs
Redis Helper	Helper/EditLLMConfRedisHelper.cs
State Machine	Service/Manage/EditLLMConfService.cs
Controller	Controller/Manage/EditLLMConfController.cs
View	View/EditLLMConfView.cs
LLM Service	TelegramSearchBot.LLM/Service/AI/LLM/GeneralLLMService.cs
Config Model	TelegramSearchBot.Database/Model/Data/AppConfigurationItem.cs
Tests	TelegramSearchBot.Test/Manage/EditLLMConfTest.cs

---

9. Implementation Order

1. Create IOCRService interface and update PaddleOCRService
2. Create LLMOCRService using GeneralLLMService
3. Create OCRConfState enum
4. Create EditOCRConfRedisHelper
5. Create EditOCRConfService (state machine)
6. Create EditOCRConfView
7. Create EditOCRConfController
8. Modify AutoOCRController to use OCR engine selection
9. Add DI registration
10. Write unit tests

---

10. Open Questions (from Issue)

1. Q: Should users select from existing LLM channels/models or have separate OCR-specific config?

   • A: Use existing LLM channels (simpler, reuses infrastructure)

2. Q: Should LLM OCR prompt be configurable?

   • A: Start with hardcoded prompt, can make configurable later

3. Q: Should there be separate timeout configs for LLM and PaddleOCR?

   • A: Use existing timeout configs for now, can add later if needed

[github-actions]

AI Implementation Plan

Problem Summary

The issue (#241) requests adding a LLM-based OCR as an alternative to the existing PaddleOCR, along with a state machine for configuring OCR settings through Bot private chat. This involves:

1. Creating LLM-based OCR service - A new OCR engine using existing GeneralLLMService.AnalyzeImageAsync
2. Creating OCR configuration state machine - Allow users to switch between OCR engines via Bot private chat
3. Configuration management - Store OCR engine, LLM model, and channel settings in AppConfigurationItem

Modules/Files Affected

New Files to Create

File	Description
TelegramSearchBot/Interface/AI/OCR/IOCRService.cs	New OCR interface with Engine enum
TelegramSearchBot/Service/AI/OCR/LLMOCRService.cs	LLM-based OCR implementation
TelegramSearchBot/Service/AI/OCR/OCRServiceFactory.cs	Factory for engine selection
TelegramSearchBot/Model/AI/OCRConfState.cs	State enum for OCR config
TelegramSearchBot/Helper/EditOCRConfRedisHelper.cs	Redis helper for state machine
TelegramSearchBot/Service/Manage/EditOCRConfService.cs	State machine logic
TelegramSearchBot/Controller/Manage/EditOCRConfController.cs	Bot controller (private chat only)
TelegramSearchBot/View/EditOCRConfView.cs	View for OCR config responses
TelegramSearchBot.Test/AI/OCR/LLMOCRServiceTests.cs	Unit tests
TelegramSearchBot.Test/Manage/EditOCRConfServiceTests.cs	Unit tests

Files to Modify

File	Changes
TelegramSearchBot/Controller/AI/OCR/AutoOCRController.cs	Add OCR engine selection logic
TelegramSearchBot/Service/AI/OCR/PaddleOCRService.cs	Add [Injectable] attribute for DI
TelegramSearchBot.LLM/Service/AI/LLM/GeneralLLMService.cs	Add OCR-related config constants

Step-by-Step Implementation Plan

Phase 1: Core OCR Service (T1.1 - T1.4)

T1.1: Create IOCRService Interface and OCREngine Enum

File: TelegramSearchBot/Interface/AI/OCR/IOCRService.cs

public enum OCREngine {
    [Description("PaddleOCR")]
    PaddleOCR,
    [Description("LLM")]
    LLM
}

public interface IOCRService {
    OCREngine Engine { get; }
    Task<string> ExecuteAsync(Stream file, CancellationToken cancellationToken = default);
}

T1.2: Implement LLMOCRService

File: TelegramSearchBot/Service/AI/OCR/LLMOCRService.cs

• Inject IGeneralLLMService
• Read config: OCR:Engine, OCR:LLMModelName, OCR:LLMChannelId
• Use GeneralLLMService.AnalyzeImageAsync(PhotoPath, ChatId) for OCR
• Save image to temp file before passing to LLM

T1.3: Add OCR Configuration Constants

File: TelegramSearchBot.LLM/Service/AI/LLM/GeneralLLMService.cs

Add constants:

public const string OCREngineKey = "OCR:Engine";
public const string OCRLLMModelNameKey = "OCR:LLMModelName";
public const string OCRLLMChannelIdKey = "OCR:LLMChannelId";

T1.4: Create OCR Service Factory

File: TelegramSearchBot/Service/AI/OCR/OCRServiceFactory.cs

• Read OCR:Engine from config
• Return PaddleOCRService or LLMOCRService based on config
• Default to PaddleOCRService if no config exists

T1.5: Unit Tests for OCR Services

File: TelegramSearchBot.Test/AI/OCR/

• Test OCRServiceFactory engine selection
• Test LLMOCRService basic functionality with mocked LLM

---

Phase 2: State Machine (T2.1 - T2.4)

T2.1: Create OCRConfState Enum

File: TelegramSearchBot/Model/AI/OCRConfState.cs

States:

• MainMenu - Main OCR config menu
• SelectingEngine - Choose OCR engine (PaddleOCR/LLM)
• SelectingLLMChannel - Choose LLM channel (if LLM selected)
• SelectingLLMModel - Choose LLM model (if LLM selected)
• ViewingConfig - Display current OCR configuration

T2.2: Create EditOCRConfRedisHelper

File: TelegramSearchBot/Helper/EditOCRConfRedisHelper.cs

• Redis key pattern: ocrconf:{chatId}:state, ocrconf:{chatId}:data
• Methods: GetStateAsync, SetStateAsync, GetDataAsync, SetDataAsync, DeleteKeysAsync

T2.3: Implement EditOCRConfService

File: TelegramSearchBot/Service/Manage/EditOCRConfService.cs

Direct Commands:

• OCR设置 - Enter OCR config menu
• 查看OCR配置 - Show current OCR configuration

State Handlers:

• SelectingEngine - Handle engine selection, update OCR:Engine
• SelectingLLMChannel - Handle channel selection, update OCR:LLMChannelId
• SelectingLLMModel - Handle model selection, update OCR:LLMModelName

T2.4: Unit Tests for State Machine

File: TelegramSearchBot.Test/Manage/EditOCRConfServiceTests.cs

• Test state transitions
• Test config read/write

---

Phase 3: Bot Integration (T3.1 - T3.3)

T3.1: Create EditOCRConfController

File: TelegramSearchBot/Controller/Manage/EditOCRConfController.cs

• Check Env.AdminId for admin authorization
• Only respond in private chat (e.Message.Chat.Type == ChatType.Private)
• Call EditOCRConfService.ExecuteAsync() with command
• Use EditOCRConfView to render response

T3.2: Modify AutoOCRController

File: TelegramSearchBot/Controller/AI/OCR/AutoOCRController.cs

• Replace IPaddleOCRService with IOCRService (factory-injected)
• OR inject OCRServiceFactory and select service based on config
• Add fallback logic: if LLM fails, try PaddleOCR

T3.3: Create EditOCRConfView

File: TelegramSearchBot/View/EditOCRConfView.cs

• Implement fluent builder pattern (like EditLLMConfView)
• Methods: WithChatId(), WithReplyTo(), WithMessage(), Render()

---

State Machine Flow

User sends "OCR设置"
    │
    ▼
MainMenu
    │
    ├─[1] 切换OCR引擎 → SelectingEngine
    │       │
    │       ├─PaddleOCR → Update config → MainMenu
    │       │
    │       └─LLM → SelectingLLMChannel
    │               │
    │               └─(select channel) → SelectingLLMModel
    │                       │
    │                       └─(select model) → Update config → MainMenu
    │
    ├─[2] 查看OCR配置 → ViewingConfig → Display → MainMenu
    │
    └─[3] 返回 → Exit (delete Redis keys)

---

Configuration Keys

Key	Type	Default	Description
OCR:Engine	string	PaddleOCR	Current OCR engine
OCR:LLMModelName	string	-	LLM OCR model name
OCR:LLMChannelId	int	-	Optional dedicated LLM channel ID

---

Testing Strategy

Unit Tests

1. OCR Service Tests

   • OCRServiceFactoryTests: Test engine selection based on config
   • LLMOCRServiceTests: Test LLM OCR with mocked IGeneralLLMService

2. State Machine Tests

   • EditOCRConfServiceTests: Test state transitions and config updates
   • Test direct commands: "OCR设置", "查看OCR配置"
   • Test state handlers: engine selection, channel selection, model selection

Integration Tests (Manual)

1. Bot private chat with "OCR设置" command
2. Switch between PaddleOCR and LLM
3. Verify OCR results with both engines

---

Key Design Decisions

1. Factory Pattern: Use OCRServiceFactory to select OCR engine at runtime based on config
2. Backward Compatibility: Default to PaddleOCR if no config exists
3. Error Handling: In AutoOCRController, if LLM OCR fails, fall back to PaddleOCR
4. Admin Only: OCR config only accessible to Env.AdminId in private chat
5. State Cleanup: Delete Redis keys on exit/return

[github-actions]

AI Implementation Plan

Issue Summary

Issue #241: Add LLM-based OCR as an alternative to PaddleOCR with Bot private chat configuration state machine.

Problem: Currently OCR functionality only uses PaddleOCR. Users want:

1. LLM-based OCR as an alternative option
2. Ability to switch OCR engine via Bot private chat
3. OCR model selection configuration options

---

Modules Affected

New Files to Create (7 files)

File	Purpose
TelegramSearchBot/Interface/AI/OCR/IOCRService.cs	OCR abstraction interface with Engine enum
TelegramSearchBot/Service/AI/OCR/LLMOCRService.cs	LLM-based OCR using GeneralLLMService
TelegramSearchBot/Model/AI/OCRConfState.cs	State enum for OCR configuration
TelegramSearchBot/Helper/EditOCRConfRedisHelper.cs	Redis helper for OCR state machine
TelegramSearchBot/Service/Manage/EditOCRConfService.cs	State machine logic and handlers
TelegramSearchBot/Controller/Manage/EditOCRConfController.cs	Bot controller for OCR config (private chat only)
TelegramSearchBot/View/EditOCRConfView.cs	View for OCR configuration responses

Existing Files to Modify (4 files)

File	Changes
TelegramSearchBot/Controller/AI/OCR/AutoOCRController.cs	Add OCR engine selection logic
TelegramSearchBot/Service/AI/OCR/PaddleOCRService.cs	Implement IOCRService interface
TelegramSearchBot/Service/AI/LLM/GeneralLLMService.cs	May need to expose OCR-specific config keys
TelegramSearchBot/Service/Manage/EditLLMConfController.cs	Add entry point for OCR settings

---

Implementation Steps

Phase 1: Core OCR Service (T1.1 - T1.4)

T1.1: Create OCR Interface and Engine Enum

File: Interface/AI/OCR/IOCRService.cs

// Create IOCRService interface extending existing IPaddleOCRService
// Add OCREngine enum: PaddleOCR, LLM
// Add Engine property to IOCRService

T1.2: Implement LLMOCRService

File: Service/AI/OCR/LLMOCRService.cs

• Implement IOCRService
• Use GeneralLLMService.AnalyzeImageAsync() for OCR
• Add timeout handling specific to LLM OCR

T1.3: Add Configuration Constants

Location: Add to existing config section or new file

Config Key	Type	Default	Description
OCR:Engine	string	"PaddleOCR"	Current OCR engine
OCR:LLMModelName	string	""	LLM model for OCR
OCR:LLMChannelId	string	""	Optional dedicated channel for OCR

T1.4: Unit Tests

Directory: TelegramSearchBot.Test/AI/OCR/

• Test IOCRService interface
• Test LLMOCRService with mocked GeneralLLMService
• Test OCRServiceFactory selection logic

---

Phase 2: State Machine (T2.1 - T2.4)

T2.1: Create OCR Configuration State Enum

File: Model/AI/OCRConfState.cs

OCRConfState:
  - MainMenu              → "主菜单"
  - AwaitingEngineChoice  → "选择引擎"
  - AwaitingChannelSelect → "选择渠道" (if LLM selected)
  - AwaitingModelSelect   → "选择模型"
  - ViewingConfig         → "查看配置"
  - Exit                  → "退出"

Pattern: Use DescriptionAttribute (see LLMConfState.cs)

T2.2: Create Redis Helper

File: Helper/EditOCRConfRedisHelper.cs

• Key pattern: ocrconf:{chatId}:state, ocrconf:{chatId}:data
• Methods: GetStateAsync, SetStateAsync, GetDataAsync, SetDataAsync, DeleteKeysAsync
• Follow EditLLMConfRedisHelper pattern exactly

T2.3: Implement State Machine Service

File: Service/Manage/EditOCRConfService.cs

State Handlers:

State	Handler	Action
MainMenu	HandleMainMenuAsync	Parse input: 1=切换引擎, 2=查看配置, 3=退出
AwaitingEngineChoice	HandleAwaitingEngineChoiceAsync	Save engine, transition to next state
AwaitingChannelSelect	HandleAwaitingChannelSelectAsync	Save channel, transition to model select
AwaitingModelSelect	HandleAwaitingModelSelectAsync	Save model, save to DB, return to main menu
ViewingConfig	HandleViewingConfigAsync	Show current config, return to main menu

T2.4: State Machine Unit Tests

File: TelegramSearchBot.Test/Manage/EditOCRConfTest.cs

• Test state transitions
• Test handler returns
• Test configuration persistence

---

Phase 3: Bot Integration (T3.1 - T3.3)

T3.1: Create OCR Config Controller

File: Controller/Manage/EditOCRConfController.cs

• Implement IOnUpdate
• Dependencies: EditLLMConfController
• Only respond to private chats (check IsPrivateChat)
• Only respond to admin users (check Env.AdminId)
• Entry command: "OCR设置" or from EditLLMConfController menu

Flow:

1. User sends "OCR设置" in private chat (admin only)
2. Controller checks if user has existing state in Redis
3. If no state → Start new session → Show MainMenu
4. If has state → Execute state handler → Return response

T3.2: Modify AutoOCRController

File: Controller/AI/OCR/AutoOCRController.cs

Changes:

1. Add IOCRServiceFactory injection
2. Read OCR:Engine from config
3. Select appropriate OCR service based on config
4. Execute OCR using selected service

T3.3: Create OCR Config View

File: View/EditOCRConfView.cs

Response Templates:

• MainMenuView: Show options 1-3 with keyboard
• EngineChoiceView: Show available engines (PaddleOCR/LLM)
• ChannelSelectView: Show available LLM channels
• ModelSelectView: Show available LLM models
• ConfigView: Display current OCR configuration
• SuccessView: Confirmation messages

---

Testing Strategy

Unit Tests

Component	Test Cases
IOCRService	Interface contract tests
LLMOCRService	Image analysis invocation, timeout handling
OCRServiceFactory	Engine selection logic
OCRConfState	Enum values and descriptions
EditOCRConfRedisHelper	Redis CRUD operations
EditOCRConfService	State machine transitions, handler logic
EditOCRConfController	Command parsing, admin check

Integration Tests

Scenario	Test
OCR with PaddleOCR	Process image → verify text extraction
OCR with LLM	Process image → verify LLM call
State machine flow	Full "切换引擎" flow
Config persistence	Set config → restart → verify persistence

Manual Testing

1. Send "OCR设置" in Bot private chat (as admin)
2. Navigate through all menu options
3. Switch OCR engine to LLM
4. Process image with different engines
5. Verify configuration persists across restarts

---

Configuration Keys (AppConfigurationItem)

Key	Default	Description
OCR:Engine	"PaddleOCR"	Current OCR engine (PaddleOCR/LLM)
OCR:LLMModelName	""	LLM model name for OCR
OCR:LLMChannelId	""	Optional dedicated channel ID

---

Key Design Decisions

1. IOCRService Interface: Extends capability beyond IPaddleOCRService with Engine property
2. OCRServiceFactory: Factory pattern for PaddleOCR vs LLMOCR selection
3. Backward Compatibility: Default to PaddleOCR if no config exists
4. LLMOCRService: Reuse existing GeneralLLMService.AnalyzeImageAsync
5. State Machine Pattern: Follow EditLLMConfService exactly for consistency

---

Dependencies

• Redis: For state machine session storage (existing dependency)
• SQLite/EF Core: For configuration persistence (existing dependency)
• GeneralLLMService: For LLM-based OCR (existing dependency)
• PaddleOCR: For traditional OCR (existing dependency)

---

Risk Mitigation

Risk	Mitigation
LLM OCR slow	Add timeout config, fallback to PaddleOCR
Redis connection failure	Log error, disable state machine gracefully
Admin permission bypass	Double-check admin ID in controller
Config corruption	Validate config values before use

---

Estimated Work Items

Phase	Tasks	Complexity
Phase 1	4 tasks	Medium
Phase 2	4 tasks	Medium
Phase 3	3 tasks	Low
Testing	2 tasks	Medium
Total	13 tasks	-