# 业务域接入评估

> 版本：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. 公共阻塞点

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

```text
业务 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

```python
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 健康检查硬编码

```python
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 写明模型调用链路：

```text
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 缺口闭环更新：模型/工具/适当性/意图分类/组装/契约测试全部闭环，四域可开工判定更新，综合由"全阻塞"改为"风控投顾可开工" |