# X-Financial 智能化财务系统：双层 Agent 架构设计与开发落地全景指南

> **核心设计理念：确定性与概率性的完美解耦**
> 
> 在企业级财务系统中，“合规性”与“准确性”是不可妥协的底线。大语言模型（LLM）天生具有概率性（会产生幻觉），因此不能直接赋予其修改核心财务数据或放行审批的最高权限。
> 
> 本架构设计的核心，在于构建一个**“双层防线”**：
> 1.  **外层 Agent (自研流程大脑)**：提供 100% 的确定性。它是系统的执行者，严格按照预设流程和固化的规则行事，不具备“自我意识”，只负责“路由”、“拦截”和“记录”。
> 2.  **内层 Agent (Hermes 智囊核心)**：提供强大的概率性推理能力。它是系统的思考者，负责处理所有复杂、模糊、非结构化的任务（如阅读长文档、识别潜在风险），但它的输出**不能直接作用于业务**，而是转化为**规则配置**或**建议意见**，交由外层 Agent 或人类管理员执行。
> 
> 这两层架构不是相互独立的两个系统，而是形成一个**“闭环”**：内层提炼规则，外层执行规则；外层收集数据，内层分析数据。这种深度协同，既保障了系统的安全性，又赋予了系统极高的智能化水平。

---

## 一、 系统架构图景与职责边界深度剖析

### 1. 外层 Agent (Outer Agent)：流程与路由的绝对掌控者

**本质：一个高度可配置的业务工作流引擎与意图分发器。**

*   **开发技术栈建议**：FastAPI (后端) + Vue3 (前端) + PostgreSQL (持久化) + Redis (可选，用于状态缓存)。
*   **交互形态**：它直接面对用户。它可以是一个类似对话框的界面，但背后的逻辑是基于**状态机 (State Machine)** 驱动的。
*   **核心模块与职责 (What to do & How to do)**：

    *   **模块 1: 意图漏斗 (Intent Router)**
        *   **职责**：精准捕捉用户请求的第一诉求，并将其导向正确的处理管线。
        *   **方法**：
            *   *规则匹配优先*：使用简单的关键词或正则（例如：匹配到“报销”、“打车”字眼，直接激活报销向导）。
            *   *轻量级分类模型兜底*：对于模糊表述（如：“我上周去上海开会的钱怎么还没发？”），调用一个小参数的分类模型（或内层的快捷接口），将其分类为“状态查询”意图，并提取关键实体（如时间：上周，地点：上海）。
    *   **模块 2: 结构化状态机引擎 (State & Flow Controller)**
        *   **职责**：管理每一个业务对象（如一张报销单）的生命周期。从“草稿” -> “提交” -> “一级审批” -> “财务复核” -> “已打款”。
        *   **方法**：拒绝让大模型控制流程走向。流程流转必须基于代码逻辑中的条件判断（例如：如果金额 < 500，且员工级别为 M1，则跳过一级审批，直接进入财务复核）。外层 Agent 负责维护并推进这个状态。
    *   **模块 3: 确定性规则执行器 (Rule Execution Engine)**
        *   **职责**：财务合规的第一道硬性防线。不讲道理，只看数据。
        *   **方法**：当用户提交报销数据时，该模块会查询本地的 `business_rules` 数据库表。如果用户提交的住宿费是 850，而数据库规则明确上限是 800，则立刻抛出“阻断型错误” (Blocking Error)。**此过程绝对禁止调用大模型进行实时推断。**
    *   **模块 4: 标准化 API 网关 (API Gateway & Handshake Layer)**
        *   **职责**：封装所有对外层系统（如 ERP、HR 系统）和对内层 Hermes 的通信接口。控制并发，记录调用日志。

### 2. 内层 Agent (Hermes)：非结构化信息的提炼者与深度思考者

**本质：一个被严格隔离的智能计算引擎，专门处理人类擅长但传统代码难以处理的“软逻辑”。**

*   **开发技术栈建议**：Hermes 框架 + 向量数据库 (如 Milvus/PGVector) + 强力 LLM (如 GPT-4 或开源大模型)。
*   **交互形态**：对用户不可见，只作为外层 Agent 的“后端服务”存在。
*   **核心模块与职责 (What to do & How to do)**：

    *   **模块 1: 政策蒸馏器 (Policy Distiller) —— 解决“知行合一”的关键**
        *   **职责**：打破知识库（死文件）与业务流（活代码）之间的壁垒。
        *   **方法 (核心思路)**：
            1.  *触发*：管理员上传一份《差旅新规.pdf》。
            2.  *解析*：Hermes 逐段阅读文档。
            3.  *提取*：使用精心设计的 **Few-Shot Prompt 链**，强制模型识别特定的“控制变量”。
                *(Prompt 示例: "你是一个专业的财务合规审计员。请阅读以下段落，如果包含任何关于费用上限、职级限制、审批层级的规定，请严格按照以下 JSON Schema 输出：{category, location, level_req, max_amount, is_hard_limit}。如果未找到，输出空。")*
            4.  *回写*：Hermes 将提炼出的 JSON 结构转化为标准的 SQL Update 指令（或通过专用 API 接口），更新外层 Agent 依赖的 `business_rules` 表。
    *   **模块 2: 深度知识检索 (Deep RAG & Interpretation)**
        *   **职责**：为用户提供复杂制度的个性化解读。
        *   **方法**：当外层 Agent 无法解答用户的合规疑问时（意图识别为“政策咨询”），外层将请求转发给 Hermes。Hermes 在向量库中检索相关段落，并结合用户当前的上下文（如：员工职级、出差地），生成一份连贯、人性化的解答。
    *   **模块 3: 异步风险探针 (Asynchronous Risk Auditor)**
        *   **职责**：像“老会计”一样，在海量已发生或正在发生的业务数据中寻找蛛丝马迹。
        *   **方法**：
            1.  *定时任务*：每天凌晨启动。
            2.  *数据聚合*：从外层数据库提取当天的报销流水（去除敏感个资）。
            3.  *模式识别*：通过特定的 Prompt（例如寻找“拆单报销”、“异常高频的出租车票”）。
            4.  *生成报告*：生成结构化的风险预警报告，存入专用表，供管理员次日早晨审核，而不是直接去冻结员工账号。

---

## 二、 核心通信协议 (The Handshake)：两层的握手与数据交互

双层架构的成败，取决于这两层能否顺畅地交换信息，且保证安全。我们需要定义清晰的接口协议。

### 1. 同步查询接口 (外 -> 内：求知与解惑)

当外层遇到处理不了的“软逻辑”时触发。

*   **Endpoint (示例)**: `POST /hermes/api/v1/consult`
*   **外层 Request 结构**:
    ```json
    {
      "context": {
        "user_id": "emp_1001",
        "current_task": "travel_reimbursement",
        "form_data": {"city": "北京", "amount": 900}
      },
      "query": "因为展会原因酒店全满，只能订900的，能报销吗？"
    }
    ```
*   **内层 Hermes Response 结构**:
    ```json
    {
      "status": "success",
      "interpretation": "根据《差旅管理办法》第15条，展会期间允许上浮 20%。您的标准是800，上浮后为960，可以报销。",
      "action_recommendation": "require_special_approval", // 建议外层采取的动作
      "citations": ["policy_doc_v2_page_4"]
    }
    ```

### 2. 异步任务接口 (外 -> 内：派发耗时任务)

例如请求生成长篇分析报告或进行全量风险巡检。

*   **流程**：
    1.  外层调用 `POST /hermes/api/v1/jobs/generate_report`。
    2.  内层 Hermes 立即返回 `202 Accepted` 和一个 `job_id`。
    3.  内层 Hermes 在后台慢慢算。
    4.  计算完成后，内层通过 Webhook 回调外层的通知接口，外层再通过系统消息通知用户“您的报告已就绪”。

### 3. 规则推送机制 (内 -> 外：自动化立法)

这是最核心的逆向通信。内层提炼出的规则如何生效？

*   **流程**：
    1.  Hermes 提炼出新规则。
    2.  Hermes 调用外层的特权 API (如 `POST /admin/api/rules/sync`)，推送规则 payload。
    3.  外层 Agent 收到后，执行数据库 `UPSERT` 操作更新 `business_rules` 表。
    4.  *(可选但强烈建议)*：进入“待激活”状态，需要人类管理员在系统中点击“确认应用新规则”后，新规才正式生效。

---

## 三、 分阶段开发落地全景计划 (Implementation Roadmap)

开发应当遵循“先基建后上层、先确定后智能”的原则。

### Phase 1: 骨架搭建与基石铺设 (Foundation & Outer Shell)
*目标：构建一个哪怕没有 AI 也能运转的硬核流程系统，确立两层隔离。*

1.  **架构拆分验证**：在服务器层面，确保 Outer Agent (FastAPI) 和 Inner Hermes 分别在独立的进程（或容器）中运行，仅通过 HTTP/gRPC 通信。
2.  **动态规则引擎实现 (核心基建)**：
    *   在 PostgreSQL 中设计 `business_rules` 表结构。必须支持高度扩展性（例如采用 `JSONB` 字段存储具体约束参数）。
    *   在外层 Agent 开发一个“规则校验服务 (Rule Validation Service)”，该服务能够在任何报销动作发生前，拦截并比对 `business_rules`。
3.  **标准化流程闭环**：开发一个完整的、基于硬规则驱动的差旅报销单据流转全流程（填单 -> 校验 -> 提交 -> 审批）。验证在“硬规则”下系统运转良好。

### Phase 2: 知识注入与基础问答 (Hermes RAG Integration)
*目标：赋予系统“解答疑问”的能力。*

1.  **内层基建**：配置 Hermes 环境，接入向量数据库。
2.  **文档清洗管道 (ETL pipeline)**：将现有的财务政策 PDF/Word 文档清洗、分块 (Chunking) 并向量化入库。
3.  **问答桥接**：
    *   在外层前端 (Vue3) 提供一个“智能咨询”悬浮窗或独立页面。
    *   外层 Agent 接收问题，附带上用户的上下文（角色、权限），一并转发给内层 Hermes。
    *   验证 Hermes 能够根据向量库的内容，给出带出处的准确回答。

### Phase 3: 核心攻坚 —— 自动立法与双层联通 (Policy Distillation & Sync)
*目标：实现从“死文档”到“活规则”的自动化转化。*

1.  **蒸馏 Prompt 工程**：在 Hermes 中反复打磨“政策提炼”的 Prompt。针对你们公司常见的政策描述方式进行微调。
2.  **结构化提取测试**：手动上传不同版本的政策文档，测试 Hermes 能否稳定、准确地输出 JSON 格式的规则参数。
3.  **闭环联调**：
    *   开发 Hermes 向外层推送规则的 API。
    *   完成全链路测试：管理员界面上传新文档 -> Hermes 后台解析 -> 外层规则库自动更新 -> 前端即时生效新的金额限制。

### Phase 4: 高阶进化 —— 异步审计与主动防御 (Proactive Risk Auditing)
*目标：将系统从“被动响应”升级为“主动防护”。*

1.  **数据安全隧道**：建立从外层业务库向内层 Hermes 传递“脱敏业务快照”的通道。
2.  **风险模式定义**：梳理出 3-5 种典型的财务风险模式（如：异常聚集的餐饮发票、连续的单日高额交通费）。
3.  **Hermes 巡检任务**：编写定时任务逻辑，利用大模型的推理能力去比对这些模式和当天的业务快照数据。
4.  **风险看板**：在外层系统的管理后台开发“风险报告台”，展示 Hermes 生成的预警结果。

---

## 四、 关键风险与防范策略总结

1.  **大模型幻觉污染规则库**：
    *   **防范**：Hermes 提炼的所有硬性规则（尤其是金额、审批级数），在写入外层正式库之前，必须增加一个**“人工审核 (Human-in-the-loop)”** 环节。系统提示“检测到政策更新，提炼出 5 条新规则，请管理员确认应用”。
2.  **状态机混乱**：
    *   **防范**：外层 Agent 的流程控制代码必须使用强类型和严格的事务控制 (Transaction)。绝不允许任何组件（包括 AI）在不经过状态机合法校验的情况下直接修改数据库中的 `status` 字段。
3.  **性能瓶颈**：
    *   **防范**：所有外层必须做的事情（拦截、查询）必须在毫秒级完成。所有涉及调用 Hermes 的操作（问答、提炼、分析）全部采用异步设计或提供明确的 Loading 反馈。