Files

T

Windows a4499defee feat: add Nailong Fund advisor capabilities

2026-09-11 09:47:40 +08:00

15 KiB

Raw Permalink Blame History

业务域接入评估

版本：v1.0
评估日期：2026-09-09
评估对象：客服、风控、投顾、运营四个业务域接入公共 Agent 底座的可行性
评估依据：四份业务域工作流程文档 + 奶龙基金底座代码现状核对
评估结论：四个域 100% 阻塞在同样两个公共出口上（模型调用、工具调用）。补完这两个出口前，交付给组员做业务实现会大面积返工。

1. 结论摘要

判定项	结论
底座公共能力（鉴权、运行闭环、SSE、会话、审计、配置）	✅ 就绪，四域可直接依赖
模型生成 / 意图分类出口	❌ 缺失，四域全部依赖
工具执行器	❌ 缺失，四域全部依赖
适当性校验（C1-C5/R1-R5）	❌ 缺失，投顾合规红线
Milvus 知识检索	❌ 缺失，客服 RAG 阻塞
是否可交付组员做业务实现	暂不可，建议先补 3 项 P0 公共能力
组员可并行开展的工作	✅ 业务 API、业务表、Agent 声明、契约测试

2. 评估依据

2.1 需求来源（四份业务域文档）

文档	规模	性质	详细度
`智能客服Agent专项设计方案(2).html`	191 KB / 42,166 字符 / 2,250 行	设计方案（含 Milvus 三集合路由代码、Go/No-Go 清单）	★★★★★
`投资顾问流程+(2).docx`	16 KB / 1,688 字符 / 74 行	流程规范（四阶段 10 环节 + 适当性矩阵）	★★★★
`风控模块详细业务流程.md`	5.5 KB / 175 行	当前系统现状描述（8 个流程）	★★★
`基金运营流程.docx`	13 KB / 905 字符 / 24 行	需求要点（2 个功能）	★★

docx 与 html 的纯文本已提取至 _tmp_extract/（临时产物，可删除）。

2.2 底座现状核对方法

逐文件核对 app/ 下 82 个源文件的服务、仓储、契约层实现；
关键词检索：ToolExecutor / tool_executor / milvus / suitab / classify；
复用 docs/06-底座代码测试报告.md 附录 D 的独立验收结论。

3. 底座能力就绪度矩阵

能力	实现证据	状态	四域可用性
鉴权 / RBAC / 数据范围	`identity_repository.py`、`agent/authorizer.py`	✅	全部
运行受理 + 幂等	`agent_run_application_service.py`、`request_idempotency`	✅	全部
Outbox + 独立 Worker	`worker/runtime.py`、`worker/__main__.py`	✅	全部
SSE（`start/tools/delta/replace/done`）	`api/views/agent_run_sse.py`	✅	风控文档事件序列与底座完全对齐
会话状态 + 澄清轮次	`model/session.py`、`svc_conversation_session`	✅	客服、风控
转人工工单	`svc_handover_ticket`、`public_platform_service.py`	✅	客服
审计留痕	`interaction_audit`、`AgentPersistenceService`	✅	投顾"可追溯可举证"可满足
禁止表达合规	`agent_negative_word` + `agent/governance.py`	✅	客服 7 个零容忍词、投顾红线
配置发布 + 模型路由 + Prompt 版本	`admin_service.py`、`config_release` 等 5 张表	✅	全部
记忆召回（含跨客户越界校验）	`memory_service.py`、`base.py:77`	✅	投顾客户认知
模型生成 / 意图分类	仅 `model_gateway.py` 的 Protocol + 调度，无 adapter、无 BaseAgent 出口	❌	全部阻塞
工具执行器	`app/service/` 下无 `tool/` 目录	❌	全部阻塞
适当性校验	全项目检索无实现	❌	投顾阻塞
Milvus 知识检索	仅 `config.py:28-30` 配置项	❌	客服阻塞

4. 四域需求映射

4.1 客服域

需求要点：5 类意图（faq/product_inquiry/policy_explain/chitchat/transfer_human）、3 个 Milvus 集合（FAQ/产品/政策）、转人工分级触发、负面词零容忍、七步骨架对齐。

需求	底座支撑	状态
5 类意图声明	`AgentDefinition.supported_intents`	✅ 可声明
意图分类	无分类器实现	❌
三集合 RAG 检索	无 Milvus 实现；`knowledge_service.py` 为空壳	❌
账户/持仓只读查询	无工具执行器	❌
转人工工单	`svc_handover_ticket` + 接口	✅
负面词拦截	已审核规则真实生效	✅
会话状态机	`svc_conversation_session`	✅
SSE 流式	`delta` 分块 + `replace` 恢复	✅
低置信三档兜底	阈值逻辑待确认	⚠️

4.2 风控域

注意：该文档描述的是当前系统现状（文末"程序只能由用户通过 python -m app.main 手动启动"），非新需求。迁移到 FastAPI 底座时需重新对齐启动方式。

需求	底座支撑	状态
工作台（统计/队列/通知）	业务接口，属 B 类扩展	待组员实现
规则扫描	业务逻辑，不属于 Agent	待组员实现
预警处置（确认/误报/升级）	Agent 不可执行，人工操作 → B 类接口	✅ 边界清晰
Agent 只读工具（预警/证据/概览/列表）	无工具执行器	❌
日报"建议优化方向"	无模型出口	❌
SSE 事件序列	与底座契约完全一致	✅

4.3 投顾域

需求要点：四阶段 10 环节、C1-C5/R1-R5 匹配矩阵（文档标注"硬约束，不可绕过"）、5 条合规红线、全流程留痕。

需求	底座支撑	状态
适当性校验	无实现	❌ 合规红线
产品筛选 / 组合构建	无工具执行器	❌
方案草案生成	无模型出口	❌
审核发布	`client_facing_content` 表在	⚠️ 接口待确认
负面词（禁保本/稳赚）	✅	✅
留痕（操作人/时间/输入/输出/审批）	`interaction_audit`	✅
记忆召回（客户认知）	✅ 含跨客户校验	✅

4.4 运营域

需求要点：场外申购赎回单确认核对（申购 4 项 + 赎回 2 项 + 通用 2 项校验）、新成立产品推介材料自动生成，均需"人在回路确认"。

需求	底座支撑	状态
邮件接入与附件识别	无邮件适配器	❌
关键字段提取	无模型出口	❌
与实际产品比对（NL2SQL）	无工具执行器	❌
人在回路确认	B 类业务接口	待组员实现
异常上报风控	事件/接口	⚠️ 待对接
推介材料生成	无模型出口	❌

该文档仅 905 字符，无接口与字段定义，组员独立开工难度最大，建议补充需求说明。

5. 公共阻塞点

四个域的全部核心功能都落在同样两个出口上：

业务 Agent（客服/风控/投顾/运营）
        │
        ├── 需要「生成/分类」 ──✗── 模型出口缺失
        │                          （model_gateway 只有 Protocol，无 adapter；
        │                            BaseAgent 仅暴露 self.config / self.memories）
        │
        └── 需要「查数据/调业务」 ──✗── 工具执行器缺失
                                   （app/service/ 下无 tool/ 目录，
                                     allowed_tools 仅用于声明与交集校验）

证据：

model_gateway.py 43 行，只有 ModelGateway Protocol、ModelExecution 数据类和 ModelDispatchService 调度逻辑；
base.py:26-27 仅暴露 self.config、self.memories，无模型调用入口；
grep ToolExecutor 仅命中 allowed_tools 的声明与校验（contracts.py:59,71,74、admin_service.py:182,196、runtime_config_service.py:50、governance.py:48），无任何执行器类。

6. 空壳接口与健康检查缺陷

本次核对新发现两处"路由存在但行为不正确"的实现，二者不影响接口覆盖率统计，但影响功能可用性判定。

6.1 `knowledge_service.py` 无条件返回 404

class KnowledgeReferenceService:
    async def resolve(self, context: RequestContext, token: str) -> dict[str, Any]:
        await AuthorizationService.require(context, "knowledge:reference:read")
        pieces = token.split(".")
        ...
        raise ResourceNotFoundError("引用不存在")   # 第 20 行：函数末尾无条件抛出

影响：K001 GET /api/v1/knowledge-references/{reference_token} 路由与 OpenAPI 均存在，但永远不会返回数据；
关联：客服域 RAG 引用链路的消费端为空。

6.2 健康检查硬编码

checks["redis"] = True    # health_service.py:18
checks["milvus"] = True   # health_service.py:19

影响：/internal/health/ready 的 Redis / Milvus 检查为写死 True，非真实探测；Milvus 或 Redis 故障时仍报 ready，生产探针与熔断会失效；
建议：接入真实 ping，或在响应中显式标注为"未接入（optional projection）"而非 True。

6.3 使用文档描述了尚未实现的能力

docs/09-底座使用文档.md §9 写明模型调用链路：

ConfigRelease → ModelRouterService → ModelGateway → 主端点/受控 fallback

§13「当前边界」亦称底座负责"模型路由"。但当前实现中：

app/service/model_gateway.py 仅有 ModelGateway Protocol、ModelExecution 数据类与 ModelDispatchService 调度逻辑，无任何供应商 adapter；
BaseAgent 未暴露模型调用入口（base.py:26-27 仅 self.config、self.memories）；
该文档 §13 未标注"模型 adapter 与工具执行器尚未提供"。

影响：组员按该文档编写 handle() 时会认为可以调用模型，实际无处可调，容易诱发自行直连 HTTP 的绕行实现（违反 01 §16.5）。

建议：在该文档 §9、§13 增加显式缺口说明，或补齐实现后同步更新；两处内容必须与代码现状一致。

7. 补课顺序建议

优先级	补什么	解锁范围	预估
P0	模型网关 adapter（先接一个真实模型）+ `BaseAgent` 暴露调用入口	客服、投顾、运营、风控日报全部	1.5 天
P0	公共 `ToolExecutor` + 工具注册表 + 只读工具契约	客服查询、风控取证、投顾选基、运营 NL2SQL	2 天
P0	适当性校验服务（C1-C5/R1-R5 矩阵）	投顾合规红线（不可绕过）	1 天
P1	意图分类器（接模型路由）	客服 5 类意图、风控意图分流	1 天
P1	Milvus 知识检索 + 修复 `knowledge_service` 空壳	客服 RAG	2 天
P2	健康检查真实探测 Redis / Milvus	运维	0.5 天

总计约 8 人日，其中 P0 三项约 4.5 人日。

8. 组员可并行开展的工作

以下工作不依赖模型与工具出口，可立即启动：

工作项	说明
业务域 Controller / Service / Repository	B 类扩展，须遵守公共信封、幂等、分页、审计与 AST 分层约束
业务表设计与 Alembic 迁移	对照 `00-新数据库基线设计.md`，只增不改
`AgentDefinition` 声明	角色、入口、意图集合、工具白名单（工具暂只声明不实现）
业务 API 鉴权与契约测试	复用 `tests/unit/service/test_agent_authorization.py` 的参数化模式
前端联调	业务接口层（非 Agent 对话）
需求补全	运营域文档过简，建议先补接口与字段定义

不可开展：handle() 中任何需要模型生成或工具调用的业务逻辑。

9. 风险提示

#	风险	说明
1	业务 Agent 绕开底座	若模型/工具出口长期缺失，组员可能自行在 `handle()` 内直连 HTTP 或数据库，违反 `01 §16.5` 与 `AGENTS.md` 第 7 条
2	接口覆盖率被误读	50/50 只代表路由存在，`knowledge_service` 空壳说明需按行为验收，而非按路由计数
3	风控文档与底座启动方式冲突	现状文档为旧系统描述，迁移时需重新对齐
4	运营域需求不足	905 字符无字段定义，直接派发会导致返工

10. 缺口闭环更新（v1.1）

本节记录 v1.0 所列缺口在后续两轮开发中的闭环情况。§1-§9 保留为历史证据，不再代表当前状态。

10.1 缺口状态对照

原缺口	v1.0	当前	证据
模型生成出口	❌ 缺失	✅ 闭环	`OpenAICompatibleGateway`、`DatabaseModelGateway`、`BaseAgent.generate_with_model`
工具执行器	❌ 缺失	✅ 闭环	`ToolExecutor` + `ToolRegistry`，`bootstrap` 注册 2 个内置工具
适当性校验	❌ 缺失	✅ 闭环	`SuitabilityService`（C1-C5/R1-R5 + 有效期 + 双向留痕）
意图分类器	❌ 缺失	✅ 闭环	`base.py:104` 骨架调用 `classify_intent()`
生产组装入口	❌ 空工厂	✅ 闭环	`bootstrap.get_agent_factory()` 完整组装并注入
骨架契约测试	❌ 缺失	✅ 已补	`tests/contract/test_agent_factory_contract.py`
业务工具样板	❌ 无	✅ 已提供	`fund_quote_service.py`（基金行情，209 行）
健康检查 redis	❌ 硬编码	✅ 已修	真实 ping
健康检查 milvus	❌ 硬编码	⚠️ 保留	有注释说明，建议改 `not_probed`
Milvus 知识检索	❌ 缺失	⚠️ 未闭环	客服 RAG 仍阻塞
`knowledge_service` 空壳	⚠️ 无条件 404	⚠️ 未处理	同上一项

10.2 四域可开工判定（更新）

业务域	v1.0 判定	当前判定	说明
客服	❌ 阻塞	⚠️ 部分可开工	意图分类、转人工、负面词、SSE 已就绪；RAG 检索仍缺 Milvus 实现
风控	❌ 阻塞	✅ 可开工	只读工具机制就绪；日报模型建议可用
投顾	❌ 阻塞	✅ 可开工	适当性硬约束、方案生成、工具调用均已就绪
运营	❌ 阻塞	⚠️ 部分可开工	模型提取/生成可用；邮件接入与 NL2SQL 需组员自建工具；需求文档仍过简

10.3 剩余待办

优先级	事项	解锁范围
P1	Milvus 知识检索 + 修复 `knowledge_service` 空壳	客服 RAG
P2	`milvus` 健康检查改为 `not_probed` 或真实探测	运维
P2	运营域需求文档补充接口与字段定义	运营域开工

10.4 结论

底座的两个公共出口（模型、工具）已闭环，并有首个业务工具样板可照抄。§5 的"四域 100% 阻塞"结论在 v1.1 后不再成立：风控与投顾已具备完整开工条件，客服与运营除各自一项外部依赖（Milvus / 邮件与 NL2SQL）外均可开工。

11. 变更记录

版本	日期	变更
v1.0	2026-09-09	首版：四域需求映射、公共阻塞点分析、空壳接口与健康检查缺陷、补课顺序建议
v1.1	2026-09-09	新增 §10 缺口闭环更新：模型/工具/适当性/意图分类/组装/契约测试全部闭环，四域可开工判定更新，综合由"全阻塞"改为"风控投顾可开工"

15 KiB Raw Permalink Blame History Unescape Escape