From f6e20df2be86fca17c8474848f31ccd2d0f1d657 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=AD=99=E8=AF=9A?= <cheng2.sun@ly.com>
Date: Wed, 14 Jan 2026 11:22:03 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/SmartHandleServiceV2_Architecture.md | 97 +++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 docs/SmartHandleServiceV2_Architecture.md

diff --git a/docs/SmartHandleServiceV2_Architecture.md b/docs/SmartHandleServiceV2_Architecture.md
new file mode 100644
index 0000000..d3cf408
--- /dev/null
+++ b/docs/SmartHandleServiceV2_Architecture.md
@@ -0,0 +1,97 @@
+# 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)