EmailBill/docs/SmartHandleServiceV2_Architecture.md

SmartHandleServiceV2 & Agent Framework 架构文档

1. 概述

SmartHandleServiceV2 是本项目中负责智能处理的核心服务，它基于 Agent Framework 重构，旨在通过 AI 代理（Agents）实现复杂的业务逻辑自动化。目前主要包含以下功能：

• 智能分类：自动识别交易记录并归类。
• 单行账单解析：从非结构化文本中提取账单信息。

2. 架构设计

本项目采用 Agent 模式，将复杂的业务流程封装为独立的 Agent，每个 Agent 继承自基类 BaseAgent，具备统一的执行流、日志记录、步骤追踪和错误处理能力。

2.1 核心组件

• ISmartHandleServiceV2 / SmartHandleServiceV2: 服务入口，负责协调各个 Agent 的执行。它不包含具体的业务逻辑，而是作为 Facade 层调用具体的 Agent。
• BaseAgent (Service.AgentFramework): Agent 的基类，提供了以下核心能力：
  • 步骤记录 (RecordStep): 记录执行过程中的关键步骤，用于调试和可视化。
  • 工具调用 (CallToolAsync): 统一封装工具调用，包含性能监控和异常处理。
  • 结果封装 (CreateResult): 返回标准化的 AgentResult<T>。
  • 可观测性: 集成了 ActivitySource ("Microsoft.Agents.Workflows")，支持分布式追踪。
• AgentResult<T>: 标准化的返回结果，包含数据 (Data)、摘要 (Summary)、执行步骤 (Steps)、元数据 (Metadata) 和 错误信息 (Error)。

3. 详细工作流

3.1 智能分类 Agent (ClassificationAgent)

该 Agent 负责对未分类的交易记录进行批量智能分类。其执行流程 (ExecuteAsync) 分为四个阶段：

1. 数据采集 (Data Collection)

   • 调用 QueryUnclassifiedRecordsAsync 获取待分类的交易记录。
   • 如果没有待分类记录，直接返回。

2. 分析阶段 (Analysis)

   • 分组: 将交易记录按摘要 (Reason) 分组，计算每个组的总金额和样本类型。
   • 关键词提取: 对每个分组的摘要提取关键词。
   • 相似度匹配: 根据关键词查询历史已分类的相似记录，作为 AI 的参考依据。

3. 决策阶段 (Decision)

   • 构建 Prompt：包含分类列表 (categoryInfo) 和待分类的分组信息 (billsInfo)。
   • 调用 AI (_aiTools.ClassifyTransactionsAsync) 进行批量分类决策。
   • AI 返回 NDJSON 格式的分类结果。

4. 结果保存 (Result Saving)

   • 遍历 AI 的分类结果，更新数据库中的交易记录 (UpdateTransactionClassifyAsync)。
   • 生成多轮执行总结。

3.2 单行账单解析 Agent (ParsingAgent)

该 Agent 负责将一段文本解析为结构化的交易记录。其执行流程 (ExecuteAsync) 如下：

1. 文本分析: 分析文本结构（如分隔符、行数等）。
2. 关键词提取: 提取文本中的关键信息（如金额、商家、日期）。
3. AI 解析: 调用 AI 模型将非结构化文本转换为结构化数据。
4. 结果封装: 返回解析后的 TransactionParseResult 对象。

4. 关键类与模型

4.1 数据模型

• ClassificationResult: 分类结果，包含摘要、分类名称、交易类型、置信度和参考记录。
• TransactionParseResult: 解析结果，包含金额、摘要、日期、类型和分类。
• ExecutionStep: 执行步骤记录，包含步骤名、描述、状态、耗时和输出。

4.2 依赖服务

• IToolRegistry: 工具注册表，用于管理和调用各种工具。
• ITransactionQueryTools: 交易查询工具，用于数据库交互。
• ITextProcessingTools: 文本处理工具，用于关键词提取和结构分析。
• IAITools: AI 工具，用于与 LLM 交互。

5. 维护与扩展指南

5.1 添加新的 Agent

1. 在 Service.AgentFramework 目录下创建新的 Agent 类，继承自 BaseAgent。
2. 在构造函数中注入所需的工具和服务。
3. 实现 ExecuteAsync 方法，定义 Agent 的工作流。
4. 使用 RecordStep 记录关键步骤。
5. 在 SmartHandleServiceV2 中注入并调用新的 Agent。

5.2 调试与排错

• 查看日志: Agent 会记录详细的执行日志，包括每个步骤的输入输出。
• 检查 AgentResult.Steps: 返回结果中包含了完整的执行步骤链，可以查看每一步的状态和耗时。
• Activity 追踪: 利用 ActivitySource 可以结合 APM 工具（如 OpenTelemetry）进行链路追踪。

5.3 修改 AI 逻辑

• Prompt 调整: ClassificationAgent 中的 BuildSystemPrompt and BuildUserPrompt 方法定义了与 AI 的交互逻辑。修改这些 Prompt 可以调整 AI 的行为。
• 模型参数: AI 调用的具体参数（如温度、模型版本）通常在 IAITools 的实现中配置。

6. 代码引用

• SmartHandleServiceV2.cs
• BaseAgent.cs
• ClassificationAgent.cs
• ParsingAgent.cs