group_fqcd_jr/docs/22-四大Agent流程实现拆解.md

四大 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 件事。