X-Financial/document/development/plan/ai_agent_dual_layer_arch.md

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 结构:

  {
    "context": {
      "user_id": "emp_1001",
      "current_task": "travel_reimbursement",
      "form_data": {"city": "北京", "amount": 900}
    },
    "query": "因为展会原因酒店全满，只能订900的，能报销吗？"
  }
  

• 内层 Hermes Response 结构:

  {
    "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 反馈。