group_fqcd_jr/docs/03-平台端到端流程文档.md

MVC+S Agent 平台端到端流程文档

版本：v3.1
修订日期：2026-09-09
数据库约束：只允许新增表和新增字段，不修改已有表名及已有字段定义

1. 文档目的

本文描述 MVC+S 通用 Agent 底座从请求进入到结果返回、归档、记忆沉淀和人工处理的完整流程。底座采用“厚平台、薄 Agent”，统一承担会话、幂等、长期记忆、Neo4j 关系推理、配置快照、多模型调度、合规、审计和事件可靠投递。数据库结构以新版设计为准，当前交易能力限定为场内基金模拟交易；基金运营的场外申赎流程作为独立业务流程，不影响场内系统运行。

2. 参与者与职责

参与者	职责	禁止事项
客户	提问、测评、确认方案、发起交易	查询他人数据
客服人员	处理咨询、投诉和转人工工单	代替投顾进行产品推荐
持证投顾	审核方案、解释风险、确认适当性	绕过适当性或承诺收益
运营人员	核对业务数据、处理运营异常	让 Agent 自动完成最终确认
风控专员	调查预警、排除、升级、结案	修改交易、资金和持仓事实
规则引擎	确定性扫描并产生预警	使用模型判断替代规则
Agent	检索、分析、生成、摘要和分流	代客交易、越权查询、作最终业务决定
通用平台	鉴权、记忆、工具、合规、审计、事件	绕过统一执行骨架

3. MVC+S 平台总流程

MVC+S 中各层固定分工：Controller 接收请求，Service 编排业务，Model 映射数据库，View 统一输出。AgentFactory、BaseAgent 和所有业务 Agent 都属于 Service 层。

用户或员工提交请求
  -> Controller 接收请求并生成 trace_id
  -> 认证用户并计算 RBAC / data_scope
  -> AgentRunApplicationService 抢占幂等并创建 agent_run
  -> 同事务保存用户消息、request_idempotency、agent_run 和 agent.run_requested Outbox
  -> 返回 202、run_id 和查询/订阅地址
  -> Worker 获取 agent_run 租约
  -> SessionService 加载会话状态与澄清轮次
  -> AgentFactory 创建业务 Agent
  -> ConfigCenter 固定本次请求配置快照
  -> BaseAgent.execute() 校验输入
  -> MemoryService 召回记忆和受控关系视图
  -> BaseAgent 使用通用分类器识别意图
  -> 调用允许的知识或业务工具
  -> ModelRouter 选择模型生成或模板直返
  -> ComplianceService 脱敏和合规检查
  -> complete_run() 同事务保存助手消息、interaction_audit、幂等完成状态和领域事件 Outbox
  -> View 根据 agent_run 和 conversation_message 返回 JSON 或 SSE 结果
  -> Worker 异步消费转人工/敏感意图/记忆提取事件

SSE start 可在输入、权限、会话和配置校验完成后提前发送；包含业务结果的 tools、delta 和 done 只能在上述持久化事务成功提交后发送。事务失败时不得向客户端发送最终成功内容。

API 受理与 Agent 执行解耦。Worker 重启或租约过期时，其他 Worker 使用同一 run_id 从最近的持久化检查点安全重试，不承诺从模型中间 Token 续写。客户端通过 GET /api/v1/agent-runs/{run_id} 查询状态，通过 /events 获取结果级恢复 SSE。

3.1 工厂底座与组员 Agent 的关系

底座负责人提供
  BaseAgent + AgentFactory + AgentService
  + 统一上下文/返回值/工具/记忆/合规/审计
                     |
                     v
组员只新增
  XxxAgent(BaseAgent)
  + AgentDefinition
  + handle()
  + 经底座负责人批准后可选的自定义意图分类钩子
  + 一行注册代码和测试数据

工厂不是用来承载客服、投顾、风控或运营的具体业务判断，而是保证所有组员的 Agent 由同一入口创建、获得同一组依赖并执行同一生命周期。组员不得绕开工厂直接在 Controller 中实例化 Agent，也不得重写基础类的 run_stream()。

4. 请求接入流程

4.1 请求模型

客户端至少提交：

{
  "agent_type": "customer_service",
  "session_id": "session-uuid",
  "message": "基金赎回多久到账？",
  "idempotency_key": "client-request-uuid"
}

user_id、角色和数据范围从服务端认证上下文获得，不接受客户端自行声明。

4.2 接入步骤

1. 网关限制请求大小、频率和来源。
2. FastAPI 认证依赖解析令牌，并重新加载有效角色。
3. 服务端生成或校验 trace_id 和幂等键。
4. 以 user_id + agent_type + idempotency_key 抢占 request_idempotency；同键不同请求正文返回冲突。
5. 已完成请求直接返回原助手消息，处理中请求返回处理中状态，租约过期才允许接管。
6. 从 svc_conversation_session 校验会话归属并加载状态、澄清轮次和配置版本。
7. 根据 agent_type、portal 和权限调用 AgentFactory。
8. 配置中心解析一个不可变配置快照，工厂拒绝未知 Agent、非法入口和角色不匹配请求。
9. 通过校验后发送 SSE start 事件。

鉴权失败不进入模型，不创建对话记忆，只记录必要的安全审计。

5. 通用 Agent 七步流程

5.1 输入接收与校验

• 清理不可见控制字符，但保留用户原始语义。
• 校验消息非空、长度和编码。
• 检测 Prompt 注入、敏感凭证和恶意工具参数。
• 确认请求数据范围和客户归属。
• 保存一条用户 conversation_message；其 intent、confidence 和 source_references 为空。

5.2 记忆召回

1. 从 Redis 读取当前会话近期消息。
2. 从 MySQL 读取有效中期记忆和当前画像。
3. 有必要时从 Milvus 查语义相关长期记忆。
4. 根据 Agent 声明的关系视图，从 Neo4j 执行审核过的参数化查询，最多一至二跳。
5. 使用 MySQL 正式风险测评、交易和持仓事实校验召回结果。
6. 按 Token 预算裁剪，形成只属于当前客户的 RecalledContext。

5.3 意图识别

1. 读取当前启用的 agent_intent_config。
2. BaseAgent 默认使用消息、近期上下文、AgentDefinition.supported_intents 和配置示例分类。
3. 返回意图、置信度和实体。
4. 置信度低于阈值时，每轮只追问一个关键槽位。
5. 返回澄清问题时条件更新 svc_conversation_session.clarification_round；达到最大次数仍失败时写转人工事件。

业务 Agent 默认不实现自己的分类器，只在 handle() 中消费分类结果。通用分类器无法满足领域需求时，须经底座负责人确认后覆盖 _classify_intent()，且仍受意图集合、置信度范围和统一低置信流程约束。

5.4 核心业务处理

业务 Agent 根据意图选择知识检索或业务工具。工具执行器再次校验白名单、参数、数据范围、超时和调用次数。

5.5 生成与合规

1. FAQ 可以返回已审核标准答案。
2. 产品和政策类使用检索内容生成，并携带来源引用。
3. 业务查询使用 API 或数据库精确结果，不使用向量相似度代替事实查询。
4. 输出进行字段脱敏、禁止表达、适当性和跨客户检查。
5. 可修复的措辞问题只允许重生成一次。
6. 再次失败或命中硬性规则时使用安全模板替换。
7. 对客开放式回答注入 AI 标识和必要免责声明。

5.6 数据沉淀

助手最终消息写入 conversation_message，保存：

• 最终实际返回的 content。
• intent 和 confidence。
• source_references。
• 脱敏后的 tool_calls。
• trace_id 和创建时间。

同时向 interaction_audit 追加执行结果、模型和 Prompt 版本、合规动作、降级原因及耗时。

助手消息、执行审计、幂等完成状态和 domain_event_outbox 必须在同一个 MySQL 短事务中提交。需要提取记忆时，memory.extraction_requested 也在该事务内写入 Outbox，提交后由 Worker 消费；请求线程不得在事务提交后直接发起记忆提取。模型、Milvus、Neo4j、邮件和消息中间件调用均不得位于该事务内。

5.7 事件广播

可能发布的事件包括：

• conversation.completed
• conversation.transfer_requested
• conversation.negative_feedback
• memory.extraction_requested
• risk.suspicious_intent_detected
• knowledge.faq_candidate_created

关键事件通过 Outbox 或具有等价可靠性的机制投递，不能只依赖进程内发布。

Outbox 消费者以 event_id 幂等处理，失败写入重试次数和下次执行时间；超过阈值进入 dead 并告警。事件发送失败不回滚已经提交的对话结果，但绝不能删除待发送事件。

5.8 配置快照与多模型调度

读取当前 active config_release
  -> 校验 AgentDefinition 权限上限
  -> 合并意图、工具、记忆、关系、合规和模型策略
  -> 生成本次请求 ResolvedAgentConfig
  -> 按 agent_type + task_type + model_policy 匹配路由
  -> 过滤不健康、超配额或不允许当前敏感级别的端点
  -> 调用主模型
  -> 从 model_routing_fallback 按 fallback_order 切换备用模型
  -> 记录 release、route、prompt、endpoint 和 model 版本

一次请求从开始到结束只使用同一个配置快照。发布失败时旧版本继续有效；回滚通过重新激活历史审核版本完成，不原地修改历史配置。model_routing_fallback 是备用链权威来源，旧 JSON 字段只作兼容快照。业务 Agent 只能声明策略和任务类型，不能指定模型地址、密钥或绕过路由器。

6. 智能客服流程

6.1 五类意图

意图	数据源	处理方式
faq	FAQ Milvus 集合	标准答案直返或轻量生成
product_inquiry	产品知识集合	RAG、客观介绍、来源引用
policy_explain	政策知识集合	RAG、规则解释、来源引用
chitchat	无业务工具	限定轮次并引导业务问题
transfer_human	会话上下文	创建转人工工单

账户、持仓和交易查询属于精确业务查询。客户端和账户接口完成后，通过只读工具查询本人数据，不新建“操作类向量库”。

6.2 FAQ 和知识问答

识别 faq/product/policy
  -> 查询 fin_knowledge_meta 有效元数据
  -> 按集合、标签、审核状态和有效期过滤
  -> Milvus TopK 检索
  -> 结果重排和去重
  -> 生成或标准答案直返
  -> 合规校验
  -> 返回并保存引用

若 Milvus 超时，改用 fin_knowledge_meta.content_text 和 tags 做 MySQL 降级检索。降级路径仍必须执行 published + active + 有效期 过滤。

6.3 投诉与负面情绪

1. 意图路由前执行轻量情绪和紧急词检测。
2. 命中投诉、纠纷、资金争议或强烈负面情绪时先返回共情和受理话术。
3. 创建 svc_handover_ticket，优先级通常为 P0。
4. 工单携带会话、摘要、意图、置信度和引用来源。
5. 人工接管后不要求客户重复描述已经提供的信息。
6. 涉及赔偿、退款、合同变更或责任认定的结论只能由人工确认。

6.4 转人工状态

pending
  -> assigned
  -> processing
  -> resolved
  -> closed

人工坐席接单使用条件更新，只有 pending/assigned 状态可以被合法接管。每次状态变化写审计。转人工工单不得写入 biz_work_order。

6.5 反馈与知识改进

1. 用户对助手消息点赞或点踩，写入 conversation_feedback。
2. 点踩、投诉和低置信已答会话进入质检池。
3. 高频未解决问法可以生成 FAQ 候选。
4. 候选同义问法写入 agent_faq_synonym，初始状态为 pending。
5. 知识运营人员审核通过后才参与线上路由和检索。

7. 知识发布流程

知识上传至 MinIO
  -> fin_knowledge_meta 写 draft/pending
  -> 文本抽取和条款完整性切分
  -> content_text 回填
  -> 法务或知识运营审校
  -> approved
  -> 生成 Embedding 并写入指定 Milvus collection
  -> published + active
  -> 线上检索生效

更新知识时创建新版本，不原地覆盖已发布版本。新版本成功写入 Milvus 后再切换发布状态。旧版本进入归档或按失效日期自动下线。

8. 投顾流程与公共平台的连接

1. 投顾只能读取 sys_customer_assignment 中归属自己的客户。
2. 获取客户画像、有效风险测评、持仓和历史交易。
3. 确认收益目标、回撤、流动性和期限。
4. 在 C1-C5/R1-R5 适当性范围内生成策略和组合草案。
5. 检查集中度、行业暴露和重复持仓。
6. 草案写入 client_facing_content，状态为待审核。
7. 持证投顾审核后才能发布给客户。
8. 客户确认后才能进入模拟交易申请。
9. 调仓建议重新执行适当性和审核流程。

Agent 只生成分析草案，不能把草稿状态内容直接返回为正式投资建议。

9. 场内模拟交易流程

客户确认交易
  -> 获取 Redis 实时行情
  -> 校验行情时间和产品状态
  -> 校验适当性及风控规则
  -> 创建 fin_sim_order
  -> 买入检查可用资金 / 卖出检查可用持仓
  -> 按首版规则立即全额模拟成交
  -> 创建 fin_transaction
  -> 原子更新 fin_sim_account
  -> 写 fin_cash_ledger
  -> 更新 fin_holding
  -> 提交事务

外部行情调用发生在事务之前。成交编号保证幂等；任何一步失败都回滚资金、成交和持仓变更。

Redis 实时行情不可用、行情超过允许时效或产品停牌时，MVP 直接拒绝创建委托并提示行情不可用；不得静默使用最近收盘价模拟成交。失败请求写审计，但不写 fin_sim_order。

10. 风控流程

10.1 规则扫描

1. 风控专员通过 risk_operator 权限进入工作台。
2. 用户主动点击扫描并二次确认。
3. 规则引擎只读客户、产品、委托、成交、资金、持仓、工单和登录数据。
4. 未命中则返回扫描统计。
5. 命中后写入 fin_risk_alert 和审计。
6. 高风险预警写入 fin_risk_notification。
7. 邮件发送失败只记录失败原因，不回滚已经生成的预警和站内通知。

规则引擎决定是否产生预警；模型只可以补充辅助研判。

10.2 人工处置

待处理
  -> 调查中
  -> 已排除 或 已结案

“升级”是独立标记，不是状态终点。需要人工调查、上报或复核时创建 biz_work_order。预警确认、误报原因、升级、工单分配和结论修改全部写入审计。

10.3 风控 Agent

风控 Agent 可以查询当前预警、关联证据、风险概览和预警列表，生成研判、沟通话术和工单摘要。工具全部只读；Agent 不能确认、关闭或升级预警，也不能修改交易、资金和持仓。

10.4 日报

日报前八项由数据库确定性统计，模型只生成“建议优化方向”。模型不可用时使用规则化建议。日报生成行为写入审计。

11. 场外基金运营独立流程

场外流程不进入当前场内模拟交易表：

中国结算或代销机构邮件
  -> Agent 识别附件
  -> 提取基金代码、金额、份额和日期
  -> 格式校验
  -> 与产品、账户和画像比对
  -> 标记限额、巨额赎回、开放期和 AML 异常
  -> 运营人员人在回路确认
  -> 异常提交风控
  -> 汇总结果提交资金清算
  -> 人工确认后反馈中国结算

这条流程可以复用通用 Agent、工具、审计和记忆能力，但应使用独立的运营业务表和接口。未建设独立业务表前，不把场外数据写入 fin_sim_order、fin_transaction 或虚拟资金账户。

12. 记忆形成流程

12.1 短期记忆

每轮完成后把必要的会话内容写入 Redis。缓存设置滑动 TTL、消息数量和 Token 上限，不保存可长期识别客户的敏感原文。

12.2 Episode 和中期记忆

1. 会话结束、转人工、达到上下文阈值，或业务 Agent 明确标记已确认业务节点时创建 episodes；普通问答不逐轮提取。
2. 提取偏好、目标、临时关注和明确事实候选。
3. 去重后写入 memory_unit。
4. 每个独立来源写入 memory_evidence。
5. 新旧内容矛盾时写入 memory_conflict，不直接覆盖。
6. 更新或删除中期记忆后使 Redis 热缓存失效。

12.3 长期记忆晋升

记忆达到配置的置信度、独立证据和冲突条件后才可晋升。画像服务在一个 MySQL 事务中：

1. 写入新的 profile_snapshots。
2. 将旧画像标记为非当前。
3. 分别写入 Milvus 和 Neo4j 的 memory_sync_outbox 事件。

两个消费者独立处理和重试。高版本已经成功时，迟到的低版本事件不能覆盖。

Neo4j 只保存关系推理所需的最小投影。首版节点包括客户、产品、风险画像、偏好、目标、持仓、交易、风险预警和知识主题；关系类型由底座白名单固定。业务 Agent 不编写 Cypher，只声明需要的关系视图。

12.4 召回权威性

Redis 当前会话
  -> MySQL/Redis 中期记忆
  -> Milvus 语义 TopK
  -> Neo4j 一至二跳关系
  -> MySQL 权威事实最终校验

正式风险测评、交易、持仓和产品事实优先于用户自述和 AI 推断。发现冲突时过滤错误记忆或明确标记为历史观点。

关系召回执行以下限制：

1. 使用参数化 Cypher 模板并注入当前用户和数据范围。
2. 默认最多查询 2 跳、100 条结果，超时 2 秒。
3. 返回关系必须携带画像版本、来源和有效状态。
4. 余额、持仓、交易和风险等级必须回查 MySQL 后才能使用。
5. Neo4j 不可用时返回空关系视图并标记降级，不允许模型补造关系。

12.5 删除和遗忘

1. 在 MySQL 将可删除记忆标记为失效。
2. 写入 Milvus 和 Neo4j 删除事件。
3. 清理 Redis 缓存。
4. 消费者执行墓碑或物理删除并记录结果。
5. 依法必须保留的交易、审计和对话归档不删除，但停止用于个性化召回。

13. 异常流程

异常	用户结果	后台动作
意图低置信	澄清或转人工	保存置信度和原因
知识无结果	明确无法确认	转人工或 FAQ 候选
Milvus 故障	MySQL 降级结果	熔断、告警、统计降级
模型故障	审核模板	重试、备用模型、记录原因
Redis 故障	有限上下文服务	MySQL 权威事实继续可用
Neo4j 故障	不扩展关系	Outbox 后续重试
配置中心故障	使用最近已验证快照	无快照时按安全默认值运行或阻断受监管功能
模型主端点故障	切换审核过的备用端点	遵守最多三端点尝试和总超时预算
合规命中	安全替换回复	记录规则和原输出摘要
越权查询	拒绝访问	写安全审计和告警
审计写失败	不返回受监管业务成功	重试并告警
事件发布失败	已提交结果不回滚	保留 Outbox 并指数退避重试
行情不可用或过期	拒绝模拟下单	不创建委托，记录审计和指标
客户端断流	客户端停止展示	服务端完成归档和审计

14. 数据落点

事件	主要写入
用户或助手消息	conversation_message
会话状态与澄清轮次	svc_conversation_session
请求幂等状态	request_idempotency
Agent 运行状态、租约和结果定位	agent_run
客服转人工	svc_handover_ticket、interaction_audit
用户评价	conversation_feedback
FAQ 候选表达	agent_faq_synonym
知识审核发布	fin_knowledge_meta、Milvus、审计
投顾内容草稿和审核	client_facing_content、审计
模拟委托成交	fin_sim_order、fin_transaction、账户、资金、持仓
风险命中	fin_risk_alert、审计
风险人工处置	biz_work_order、预警、审计
高风险通知	fin_risk_notification
会话摘要	episodes
中期记忆	memory_unit、memory_evidence、memory_conflict
长期画像	profile_snapshots、memory_sync_outbox
通用领域事件	domain_event_outbox
配置发布	config_release、platform_config_item
模型和 Prompt 路由	model_endpoint_config、model_routing_rule、model_routing_fallback、prompt_template_version

15. 上线验收

• 四类 Agent 均通过工厂创建且权限隔离正确。
• BaseAgent 七步流程不能被业务子类绕过。
• 客服五类意图均有端到端测试。
• 低置信问题不硬答，转人工上下文完整。
• 知识只使用已发布且有效的版本。
• 客服工单与风险工单没有混用。
• 场内模拟成交满足幂等和事务原子性。
• 规则引擎和风控 Agent 的职责边界正确。
• 正式业务事实不会被记忆内容覆盖。
• 跨客户访问、适当性违规和敏感信息泄漏均为零。
• 每个请求可通过 trace_id 还原输入、工具、来源、输出和审计轨迹。
• 同一幂等键的并发请求只产生一份消息、工单和领域事件。
• 澄清轮次在 Redis 丢失后可从 MySQL 恢复，达到上限后稳定转人工。
• 配置按不可变版本发布、审核、激活和回滚，请求执行期间版本不漂移。
• 主模型失败后只使用审核过的备用端点，模型与 Prompt 版本可审计。
• 长期记忆具备证据、冲突、晋升、同步、删除和低版本防覆盖测试。
• Neo4j 关系查询受视图、深度、数量、超时和数据范围限制，故障时不编造关系。
• 原有数据库表名和已有字段定义在全部迁移中保持不变。