# 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](../Service/SmartHandleServiceV2.cs)
*   [BaseAgent.cs](../Service/AgentFramework/BaseAgent.cs)
*   [ClassificationAgent.cs](../Service/AgentFramework/ClassificationAgent.cs)
*   [ParsingAgent.cs](../Service/AgentFramework/ParsingAgent.cs)