# 四大 Agent 流程实现拆解（基于现有底座）

> 输入：`智能客服Agent专项设计方案`(v1.3, 1664 行)、`基金运营流程`、`风控模块详细业务流程`、`投资顾问流程`。
> 目的：在动手前说清「哪些能直接用底座、哪些要新写、哪些必须你们先定」。
>
> ---
> ## ⚠️ 本文是**开工前评估稿**（2026-09-09），多处结论已被实现推翻
>
> **保留此文是为了留"当时怎么判断的"证据，不要用它判断当前进度。** 下列三处已作废：
>
> | 本文原话 | 当前实际 |
> |---|---|
> | 「底座的 **52 张表**」 | **90 张表 = 89 张业务表 + `alembic_version`**（场内 51 + 场外/推广 17 + 投顾 21） |
> | §3 表里「基金运营（场外）＝**无场外表**」 | **已建 17 张**（`offsite_*` / `promotion_*`），见 `docs/28` |
> | §5「**必须新建场外一组表**」 | **已建成**；且对应 Agent 已注册（`OffsiteFundAgent` / `PromotionMaterialAgent`），接口已挂载 |
> | §5.2 核对规则按**金额**（「单日申购金额上限」「赎回金额 vs 可用金额」） | 实现改为**份额口径**：单笔申购上限＝份额 **10%**、巨额赎回＝份额 **20%** |
>
> **当前状态以 `docs/验收与审计/phase1-acceptance-report.md` 为准。**

## 0. 一句话结论

**能实现。** 决定性原因是：**底座当时的 52 张表与这几份流程的设计高度吻合**，
绝大部分工作是「填 Service / Agent 逻辑」，而不是「重建表结构」——后者才是真正贵的部分。

举几个直接对上的例子（均为实际字段名）：

| 流程要求 | 底座已有的字段 |
| --- | --- |
| 风控「确认接收 / 关闭误报 / 升级处理」 | `fin_risk_alert.ack_status / handler_id / is_escalated / escalation_reason / close_reason / trigger_rule_codes` |
| 风控「站内通知 + 邮件，发送失败不影响预警」 | `fin_risk_notification.channel / send_status / fail_reason / receiver_email` |
| 客服「转人工携带意图与置信度」 | `svc_handover_ticket.intent / confidence / reason_code / conversation_summary / source_references` |
| 投顾「输出为草稿，须投顾审核签发」 | `client_facing_content.draft_content / review_status / reviewer_user_id / published_at` |
| 投顾「双录 / 风险揭示 / 二次确认」 | `biz_work_order.recording_reference / risk_disclosure_ack_at / second_confirmation_at / risk_rule_hits` |
| 投顾「C1-C5 ↔ R1-R5 最严口径」 | **已实现**：`app/service/suitability_service.py`（255 行，风险等级只取最新测评、不接受调用方传值） |
| 客服「7 个负面词零容忍」 | `agent_negative_word` 表 + 底座合规检查步骤 |
| 客服「回复模板 / 免责声明话术」 | `agent_reply_template` 表 |
| 客服「同义问法」 | `agent_faq_synonym` 表 |
| 客服「意图阈值 0.6」 | `agent_intent_config.confidence_threshold`（已生效） |

另外，客服方案的**七步骨架（①输入鉴权②记忆召回③意图路由④核心逻辑⑤结果生成⑥数据沉淀⑦事件广播）与底座的
`BaseAgent` 骨架完全一致**——这份方案就是按底座设计的，`__init_subclass__` 已强制⑥⑦不可被子类绕过。

## 1. 覆盖度总览

| 模块 | 所需表 | Service 现状 | 主要缺口 | 相对工作量 |
| --- | --- | --- | --- | --- |
| **智能客服** | 全部就绪 | 覆盖最好（意图/知识/转人工/负面词/模板/会话） | 三集合知识检索、客服 Agent 本体、脱敏工具、状态机 | 中 |
| **投资顾问** | 全部就绪 | 适当性已实现；组合/报告无 | 策略配置、组合构建、报告生成、审核签发流 | 中 |
| **风控监测** | 全部就绪 | **几乎为零**（`risk_alert` 仅 4 处命中，多为 ORM） | **规则引擎**、扫描服务、预警处置 API、日报、邮件 | 大 |
| **基金运营（场外）** | ~~**无场外表**~~ **已建 17 张**（`offsite_*`/`promotion_*`） | 已注册 `OffsiteFundAgent` | 单据解析 + 核对规则 | 已落地 |

## 2. 智能客服 Agent

### 2.1 底座直接可用的

七步骨架、鉴权与画像、RBAC、审计、幂等、限流、事件（Outbox 现成）、配置发布、
意图配置与阈值、负面词、回复模板、同义问法、转人工工单、会话与消息、SSE 流式、
记忆读写、知识元数据表。

> 值得注意：风控文档定义的 SSE 事件 `start / tools / delta / replace / done`
> **与底座现有实现完全一致**；而客服方案通篇只写「SSE 流式」、未定义事件类型——
> 这一项以底座现成为准即可，不需要新设计。

### 2.2 需要新写的

1. **三集合知识检索**：`fin_faq_collection`(TopK 3) / `fin_product_collection`(TopK 5) /
   `fin_policy_collection`(TopK 5)。底座的 Milvus 适配器目前服务于**记忆向量**，
   知识检索的集合 schema、三级路由、按 `score` 排序、md5 去重、`expire_date` 过滤都要新写。
   维度 1024 / `COSINE` / `IVF_FLAT`(nlist=128, nprobe=16) 已在方案里给定。
2. **客服 Agent 本体**：5 类意图分支（product_inquiry / policy_explain / faq / chitchat / transfer_human），
   `faq` 走「检索直返不经 LLM」，其余走 RAG + 生成 + 来源引用。
3. **强制免责声明注入**：方案要求「基类强制注入、子类不得绕过」——需挂到底座的结果生成阶段。
4. **脱敏工具 `mask_tool`**：身份证/卡号/手机号不回显，仅掩码。
5. **会话状态机 5 态**：`idle / processing / clarifying / answering / transferring`。
6. **三档兜底判定**：高/中/低置信分别对应直接回答 / 加不完整提示 / 兜底话术+转人工。
7. **澄清机制**：≤2 轮、每轮追问 1 个槽位；**闲聊边界**：≤3 轮后强制引导业务。
8. **suggestions 生成**：接口已有该字段但无生成逻辑。

### 2.3 方案自己写了「未明确」、必须你们补的

| 项 | 说明 |
| --- | --- |
| 「RAG 混合判定」公式与阈值 | 方案写「绝对阈值 AND（相对间隙 OR 分布优势）」，**公式、数值、三档分数区间全文未给** |
| 熔断次数 N | 「连续失败 N 次熔断」，N 未给 |
| QPS 限流阈值 | 只写「令牌桶/滑动窗口」，数值未给 |
| 业务侧表名 | 方案只写「MySQL LIKE 检索」「画像直连 MySQL」，**未给任何表名** |
| 跨 Agent 联动规则 | 客服识别「高净值/大额意愿/敏感话题」后的联动规则未定义 |
| 合规校验是否前置 | §0.4 评审点自己提出「是否应前置到答案生成之前」，**未定论** |

### 2.4 ⚠️ 与底座接口形态的冲突（必须决策）

方案设计的是 **`POST /api/chat/customer`，同步返回 `reply`**；
底座 `docs/05` 规定的是 **`POST /api/v1/agent-runs` → 202 + `run_id` → SSE 订阅结果**。

两者不是简单改名，是**调用模型不同**：底座是「受理即返回、Worker 异步执行」，方案是「同步等答案」。

- 采用底座形态：前端要改成「提交后订阅 SSE」，但天然获得审计、重试、限流、可观测、多 Worker 扩展。
- 采用方案同步形态：与底座现有 `docs/05` 冲突，且长耗时请求会占满连接。

**建议采用底座形态**，把「同步返回」作为 SSE 的首包体验（首 token <800ms 目标可达成），
但这需要你确认，因为会影响前端联调方式。

## 3. 投资顾问 Agent

| 流程步骤 | 现状 |
| --- | --- |
| 1 客户认知 / 问卷采集 | 表就绪（`fin_customer_profile`、`fin_risk_assessment`），问卷入口需新写 |
| 2 风险测评与适当性匹配 | **已实现**（`suitability_service`，C1-C5 × R1-R5 硬约束） |
| 3 投资目标与期限 | 需新写（目标书、回撤约束、期限分档） |
| 4 匹配投顾策略 | 需新写（保守/稳健/平衡/进取/激进 + 大类资产配置比例） |
| 5 筛选基金构建组合 | 需新写（核心+卫星、集中度检查、重复持仓检查、推荐理由） |
| 6 签署协议与授权范围 | 表就绪（`biz_work_order` 的授权/双录字段），流程需新写 |
| 7 申购赎回 | **底座是场内模拟交易**（`fin_sim_order`）；投顾流程的申赎若指场外，需与运营模块统一 |
| 8 持续监控 | 表就绪（`fin_holding`、`fin_nav_history`），监控看板需新写 |
| 9 调仓再平衡 | 需新写（偏离阈值、调仓建议、**重新适当性校验**） |
| 10 报告与陪伴 | 表就绪（`client_facing_content`），报告生成+审核签发需新写 |

**合规要点都已映射到表**：草稿态 + 投顾审核（`review_status`）、免责声明、脱敏、
留痕（操作人/时间/输入/输出/判断依据/审批意见）。

## 4. 风控监测 Agent —— 表最全，但代码最少

底座有 `fin_risk_alert`(29 列) / `fin_risk_notification`(14 列) / `biz_work_order`(30 列) /
`fin_capital_flow` / `fin_transaction` / `fin_holding` / `sys_login_record` / `interaction_audit`，
**风控文档 §2 要求的七类数据源全部覆盖**。

但代码侧几乎为零，必须新写：

1. **规则引擎**（核心，且是**确定性逻辑**）。风控文档明确写「**规则引擎负责判断是否生成预警，
   Agent 不负责生成预警**」——这条与底座设计一致（Agent 只读），但引擎本身要新做：
   规则定义与存储、规则执行、命中写入 `fin_risk_alert.trigger_rule_codes`、优先级计算。
   **底座目前没有规则表**，只有 `trigger_rule_codes` 这个字段。
2. **扫描服务**（读七类数据 → 执行规则 → 未命中/命中分支 → 高风险生成通知）。
3. **预警处置 API**：确认接收 / 关闭误报（理由 1-500 字）/ 升级（文档注明「后端已有接口，前端弹窗未接入」）。
4. **日报生成**：前八项**确定性统计**，只有第 9 项「建议优化方向」用模型（超时/空/异常时用规则化建议）。
5. **邮件 SMTP**：`grep MAIL|SMTP` 在 `app/` 中**零匹配**，完全没实现；要求「发送失败只记日志，不影响预警和站内通知」。
6. **风控 Agent 对话**：只读工具（预警/证据/风险概览/预警列表），流式 + 模板降级。

## 5. 基金运营（场外）—— 唯一需要新建表的模块

底座 15 张 `fin_*` 全是**场内模拟交易**；运营流程是**场外申购赎回**，
而 `AGENTS.md` 明确「场外基金运营流程独立，不得写入场内交易表」
→ 因此**必须新建场外一组表**，不能复用场内表。
→ ✅ **已完成（2026-09-14）**：场外/推广 17 张表已建（`offsite_*` / `promotion_*`），
   逐表登记见 `docs/28-场外与推广域数据表登记.md`。

流程本身可拆成三段：
1. **单据采集与解析**：从运营邮箱取中国结算邮件 → 解析申购/赎回单扫描件 → 关键字段提取 + 格式校验。
   涉及邮件收取（另一处 SMTP/IMAP 缺口）与文档解析（底座无此能力）。
2. **核对规则**（文档已给全字段；⚠️ **实现已改为份额口径**）：申购后单一持有比例上限、~~单日申购金额上限~~ **单笔申购份额上限（10%）**、金额格式（两位小数/万元）、
   日期格式、~~巨额赎回（金额）~~ **巨额赎回（份额 20%）**、~~赎回金额 vs 可用金额~~、最低申购金额、是否在开放期、反洗钱嫌疑。
   其中 `fin_product.single_investor_max_holding_ratio / min_amount / open_period_start/end` 已就绪，**场外产品使用独立表**。
3. **人在回路**：NL2SQL 确认 → 汇总统计 → 是否上报风控 → 是否给资金清算岗 → 回单给中国结算。

⚠️ **文档自己写了「待工作：不同的申购赎回单子，以作实际操作案例」** —— 也就是说**缺样本数据**。
没有真实单据样本，解析规则只能靠猜，建议先把这段挂起或只做「字段定义 + 表结构 + 人工录入」版本。

## 6. 你必须先决策的 6 件事

| # | 决策点 | 影响 |
| --- | --- | --- |
| 1 | **接口形态**：底座异步 `agent-runs` + SSE，还是方案里的同步 `chat/customer` | 决定前端联调方式；建议用底座的 |
| 2 | **模型选型**：方案写 `qwen-turbo`(意图) + Qwen Embedding(1024 维)；底座现配 `deepseek-flash` | **embedding 维度直接决定 Milvus 集合 schema**，定错了要重建知识库 |
| 3 | **RAG 混合判定公式与三档分数区间** | 方案未给，是客服模块的核心算法 |
| 4 | **规则引擎的规则从哪来**：代码常量、数据库表，还是管理界面配置 | 决定风控模块的架构，也决定业务人员能否自己加规则 |
| 5 | **场外运营是否排在首批** | 它缺样本数据，且要新建一组表 |
| 6 | **合规校验前置还是后置**（方案 §0.4 自己提的待评审点） | 影响链路结构与首响时延 |

## 7. 建议开工顺序

| 顺序 | 模块 | 理由 |
| --- | --- | --- |
| 1 | **智能客服 Agent** | 底座覆盖度最高（表全 + 机制全），最容易做出可演示闭环；缺的只是三集合检索与 Agent 本体 |
| 2 | **投资顾问 Agent** | 硬约束（适当性）已实现，`client_facing_content` 现成，主要补生成与审核流 |
| 3 | **风控 Agent** | 表最全但代码最少，且**规则引擎是全新架构**（确定性逻辑，不能用模型代替），建议单独立项 |
| 4 | **场外运营** | 唯一要新建表 + 缺样本，建议等有真实单据样本再动 |

**每个模块我都建议按同一个节奏交付**：先做只读最小闭环（端到端脚本 + 审计可见）→ 你们验业务逻辑 →
再扩分支与边界；涉及写数据的（风控处置、调仓、场外核对）先给事务/并发/幂等方案再动手。

## 8. 这份拆解的边界

- 四个模块的**表结构就绪度**是我逐表查库确认的（不是读文档推断）。
- 每份需求文档里的**具体业务规则**（阈值、公式、话术）我只做了提取与对照，**正确性未经业务确认**。
- 「工作量」是相对量级（中/大），不是人日估算——那需要先定第 6 节的 6 件事。