15 KiB
15 KiB
业务域接入评估
版本：v1.0
评估日期：2026-09-09
评估对象：客服、风控、投顾、运营四个业务域接入公共 Agent 底座的可行性
评估依据：四份业务域工作流程文档 +jr-agent-platform底座代码现状核对
评估结论：四个域 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.py43 行，只有ModelGatewayProtocol、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仅有ModelGatewayProtocol、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 缺口闭环更新：模型/工具/适当性/意图分类/组装/契约测试全部闭环，四域可开工判定更新，综合由"全阻塞"改为"风控投顾可开工" |