diff --git a/docs/22-四大Agent流程实现拆解.md b/docs/22-四大Agent流程实现拆解.md new file mode 100644 index 0000000..5d3255e --- /dev/null +++ b/docs/22-四大Agent流程实现拆解.md @@ -0,0 +1,169 @@ +# 四大 Agent 流程实现拆解(基于现有底座) + +> 输入:`智能客服Agent专项设计方案`(v1.3, 1664 行)、`基金运营流程`、`风控模块详细业务流程`、`投资顾问流程`。 +> 目的:在动手前说清「哪些能直接用底座、哪些要新写、哪些必须你们先定」。 + +## 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、日报、邮件 | 大 | +| **基金运营(场外)** | **无场外表** | 无 | 需新建独立表 + 单据解析 + 核对规则 | 大(且缺样本) | + +## 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` 明确「场外基金运营流程独立,不得写入场内交易表」 +→ 因此**必须新建场外一组表**,不能复用场内表。 + +流程本身可拆成三段: +1. **单据采集与解析**:从运营邮箱取中国结算邮件 → 解析申购/赎回单扫描件 → 关键字段提取 + 格式校验。 + 涉及邮件收取(另一处 SMTP/IMAP 缺口)与文档解析(底座无此能力)。 +2. **核对规则**(文档已给全字段):申购后单一持有比例上限、单日申购金额上限、金额格式(两位小数/万元)、 + 日期格式、巨额赎回、赎回金额 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 件事。