lzf_0626
36c7a9d8d2
## 新入库（`docs/演示用/`）
- `代码库全面审查报告-2026-09-14.md`
- `代码修改方案-2026-09-14.md`
- `记忆系统排查报告-2026-09-14.md`
- `记忆系统修复文档-2026-09-14.md`
- `文档一致性审计报告-2026-09-14.md`
- `多Worker接入方案-2026-09-14.md`
## 全量校对（32 个既有文档 + `AGENTS.md`）
跨 39 个文件、**1125 insertions / 148 deletions**。
⚠️ **这批改动同样不是本次会话写的**。我抽样核对过性质：是**实质内容补充**而不是
格式/换行转换。例如 `docs/44-演示流程.md` 新增两条"2026-09-14 补注"：
- `启动金融Agent平台.bat` 只在**桌面**上，仓库里只有 `启动平台.bat` 这一份
（两份由同一个 `tools/make_launcher_bat.py` 产出，改完 `start.ps1` 重跑它一起更新）；
- `advisor_t`(9020) 与 `offsite_t`(9006) **不在 `tools/seed_test_rbac.py` 的演示用户里**
（那里只有 `cust_t`/`risk_t`/`admin_t`/`review_t` 四个），由 `grant_*.py` 系列创建，
**重跑种子不会重建它们** —— 换机器时这两个账号登录失败，要先查 `sys_user` 有没有这两行，
而不是查密码。
这两条都是对的地方，与我这一路踩到的现象一致（我确实用到了 `advisor_t`/`offsite_t`）。
**我没有逐字审阅全部 39 个文件**，只抽样确认了改动性质与规模。若其中有需要复核的段落，
请指明文件，我逐处核对。
186 lines
14 KiB
Markdown
186 lines
14 KiB
Markdown
# 四大 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 件事。
|