docs(ai): AI Agent 突破口设计规格 — ReAct Agent + Function Calling

erp-ai 客服从简单问答升级为多策略 ReAct Agent:
- Agent Orchestrator 实现 ReAct 循环(最多 5 轮 Tool Call)
- 4 类 12 个 Tool 覆盖数据查询/AI 分析/知识服务/行动操作
- 多策略 System Prompt(安抚/科普/推荐/预警/引导到院)
- 3 张新表(sessions/messages/tool_logs)+ 会话管理 API
- 小程序 + Web 富消息渲染 + SSE 流式输出
- 4 Phase 分阶段实施,总工期 16-23 天
This commit is contained in:
iven
2026-05-18 01:42:13 +08:00
parent 6151fde7c4
commit 1c8319fb4d

View File

@@ -0,0 +1,438 @@
# AI Agent 突破口设计规格
> **日期:** 2026-05-18 | **状态:** Draft | **范围:** erp-ai Agent 改造
> **总工期:** 16-23 天 | **方案:** ReAct Agent + Function Calling
## 1. 背景与动机
### 1.1 当前状态
HMS 健康管理平台综合评分 6.8/10功能完整度 87%,但 AI 能力"有弹药没上膛"
- erp-ai 有 3 个 ProviderClaude/OpenAI/Ollama+ `AiProvider` trait 抽象
- SSE 流式分析已实现(化验解读、趋势分析、报告摘要),但 4 个 SSE 端点无 UI 入口
- Copilot 引擎(风险评分、规则引擎、洞察服务)已实现但未集成到用户触达层
- 知识库框架structured_source、KDIGO 规则)已搭建
- 成本/配额管控usage、quota、cache已就绪
- v2 架构设计已规划 RAG、事件驱动管线、两级缓存
**AI 客服"小华"现状**:一个硬编码 system prompt + 最近 10 条历史拼成上下文的简单问答,无法识别意图、无法查询数据、无法触发分析。
### 1.2 核心问题
1. **AI 能力断裂** — 后端分析能力和前端用户触达之间没有桥接
2. **AI 客服能力单调** — 简单问答无法胜任真实客户服务场景(情绪安抚、医疗科普、引导到院)
3. **缺少差异化竞争力** — 当前系统是工具,不是"主动关怀引擎"
### 1.3 设计目标
- **打通现有 AI 链路** — 通过 Agent Tool 机制将 SSE 分析、Copilot 引擎、知识库串联到对话入口
- **升级 AI 客服为多策略 Agent** — 意图识别→策略选择(安抚/科普/推荐/预警/引导)→ Tool 调用→自然回复
- **纯自研实现** — 在 erp-ai 内用 ReAct Agent 模式,不依赖 Dify 等外部平台
- **复用现有基础设施** — Provider 抽象、配额管控、缓存、知识库全部复用
---
## 2. 整体架构
### 2.1 Agent 核心循环
```
┌─────────────────────────────────────────────────────┐
│ Chat Handler │
│ 接收用户消息 + 会话历史DB 持久化) │
└──────────────────────┬──────────────────────────────┘
┌──────────────────────▼──────────────────────────────┐
│ Agent Orchestrator │
│ 1. 组装 System Prompt角色 + 可用 Tools 描述) │
│ 2. 发送给 LLM获取 Tool Call 或最终回复 │
│ 3. 如果是 Tool Call → 执行 Tool → 结果加入上下文 │
│ 4. 重复 2-3直到 LLM 给出最终回复 │
│ 5. 安全循环上限:最多 5 轮 Tool Call │
└──────────────────────┬──────────────────────────────┘
┌──────────────────────▼──────────────────────────────┐
│ Tool Registry │
│ 注册所有可用 Tool按权限/场景过滤 │
│ ┌──────────┐ ┌───────────┐ ┌───────────────┐ │
│ │ 健康数据 │ │ AI 分析 │ │ 知识库 │ │
│ │ 查询工具 │ │ 触发工具 │ │ 检索工具 │ │
│ ├──────────┤ ├───────────┤ ├───────────────┤ │
│ │ 预约工具 │ │ 服务推荐 │ │ 风险预警 │ │
│ │ │ │ 工具 │ │ 工具 │ │
│ └──────────┘ └───────────┘ └───────────────┘ │
└─────────────────────────────────────────────────────┘
```
### 2.2 关键设计决策
| 决策 | 选择 | 原因 |
|------|------|------|
| Agent 状态管理 | Orchestrator 无状态,会话由 Handler 管理 | 简化 Orchestrator 职责,便于测试 |
| Tool 执行模型 | 同步阻塞,单轮内多个 Tool Call 并行 | LLM 返回多个 call 时并行执行,减少延迟 |
| Provider 复用 | 不改 `AiProvider` trait在调用层传入 function definitions | 最小改动,兼容现有 3 个 Provider |
| 安全循环上限 | 单次对话最多 5 轮 Tool Call | 防止无限循环,控制成本 |
| 分析调用模式 | Agent 内走非流式同步调用 | Agent 需要拿到完整结果再决策 |
---
## 3. Tool 系统
### 3.1 AgentTool Trait
```rust
#[async_trait]
pub trait AgentTool: Send + Sync {
fn name(&self) -> &str;
fn description(&self) -> &str;
fn parameters_schema(&self) -> serde_json::Value; // JSON Schema
async fn execute(&self, ctx: &ToolContext, params: serde_json::Value) -> ToolResult;
}
pub struct ToolContext {
pub tenant_id: Uuid,
pub user_id: Uuid,
pub patient_id: Option<Uuid>,
pub db: DatabaseConnection,
}
pub struct ToolResult {
pub output: String,
pub display_hint: Option<DisplayHint>,
}
```
### 3.2 Tool 清单
#### 第一类:数据查询(只读,从 erp-health 取数据)
| Tool 名称 | 功能 | 对接现有能力 |
|-----------|------|-------------|
| `query_patient_vitals` | 查询患者最近体征数据(血压/血糖/心率等) | `health_indicator` entity |
| `query_lab_reports` | 查询患者最近化验报告及指标 | `health_lab_report` + `lab_report_item` |
| `query_patient_profile` | 查询患者基本信息、病史、过敏史 | `patient` entity |
| `query_appointments` | 查询患者预约记录 | `appointment` entity |
| `query_medication` | 查询患者当前用药情况 | `medication` entity |
#### 第二类AI 分析触发(调用 erp-ai 现有能力)
| Tool 名称 | 功能 | 对接现有能力 |
|-----------|------|-------------|
| `analyze_lab_report` | 分析指定化验报告,返回异常指标解读 | `analysis_service`(非流式调用) |
| `analyze_health_trends` | 分析体征趋势变化,识别异常模式 | `trend_analysis` |
| `get_health_insights` | 获取患者当前风险洞察和 AI 建议 | `copilot_engine` + `insight_service` |
#### 第三类:知识与服务(对话策略支撑)
| Tool 名称 | 功能 | 对接现有能力 |
|-----------|------|-------------|
| `search_medical_knowledge` | 检索医疗知识库(疾病科普、指标解释) | `knowledge_structured_source` |
| `recommend_services` | 根据症状/需求推荐科室或服务 | 新增,基于规则 + 知识库 |
| `check_alert_rules` | 检查是否触发告警阈值 | `local_rules_engine` + `ai_risk_threshold` |
#### 第四类:行动(写入操作,需更高权限)
| Tool 名称 | 功能 | 对接现有能力 |
|-----------|------|-------------|
| `create_appointment` | 帮用户预约挂号 | `appointment_service` |
| `transfer_to_human` | 转接人工客服/值班医生 | 新增WebSocket 通知 |
### 3.3 权限与安全
- **数据查询 Tool**:自动注入 `tenant_id` + `patient_id` 过滤LLM 无法绕过多租户隔离
- **分析触发 Tool**:走现有配额管控(`QuotaService`
- **行动 Tool**需额外权限标记System Prompt 约束 LLM 只在用户明确请求时调用
- **数据脱敏**:所有 Tool 返回数据在 Tool 层做 PII 脱敏,不传给 LLM
- **审计日志**:每次 Tool Call 记录到 `ai_tool_call_logs`
---
## 4. 多策略对话流
### 4.1 策略引导机制
Agent 通过 System Prompt 定义 5 种策略方向LLM 根据用户表达的内容和情绪自主选择和切换:
1. **【情绪安抚】** 用户焦虑/恐惧/沮丧时 → 先共情,用通俗语言解释,分享积极案例
2. **【医疗科普】** 用户询问指标/疾病知识时 → 调用 `search_medical_knowledge` 获取准确信息
3. **【服务推荐】** 用户有就医需求时 → 调用 `recommend_services` 推荐科室,主动提议预约
4. **【风险预警】** 症状或数据异常时 → 调用分析 Tool 评估风险,明确告知风险等级
5. **【引导到院】** 明确就诊意向或高风险时 → 帮助预约,提供科室信息,必要时转接人工
策略之间不互斥,一轮对话中可自然切换。
### 4.2 System Prompt 结构
```
你是 HMS 健康管理平台的 AI 健康顾问"小华"。
## 核心策略
根据用户表达的内容和情绪,自然地采用以下策略方向:
1. 【情绪安抚】当用户表达焦虑、恐惧、沮丧时:
- 先共情认可感受,不急于给建议
- 用通俗语言解释,避免医学术语
- 分享积极案例,降低恐惧感
2. 【医疗科普】当用户询问指标含义、疾病知识时:
- 调用 search_medical_knowledge 获取准确信息
- 用比喻和类比让老年患者也能理解
- 强调"具体请以医生诊断为准"
3. 【服务推荐】当用户表达就医需求或身体不适时:
- 调用 recommend_services 推荐合适科室
- 调用 check_appointments 查看可用时段
- 主动提出帮用户预约
4. 【风险预警】当用户描述的症状或数据异常时:
- 调用 analyze_health_trends 或 get_health_insights 评估风险
- 明确告知风险等级和需要注意的事项
- 高风险时建议尽快就医
5. 【引导到院】当用户有明确就诊意向或高风险预警时:
- 调用 create_appointment 帮助预约
- 提供科室位置、出诊医生信息
- 必要时调用 transfer_to_human 转接值班医生
## 策略不是互斥的,你可以在一轮对话中自然切换。
## 永远不要:推荐具体药物、给出明确诊断、替代医生建议。
```
### 4.3 对话流示例
**场景:老年患者说"最近头有点晕"**
```
[用户] 最近头有点晕,不知道怎么回事
[Agent 思考] 用户描述头晕症状,可能是高血压或其他问题。
应该1) 查看最近体征数据 2) 安抚情绪
[Agent 调用] query_patient_vitals → 获取最近血压数据
[Tool 返回] 最近7天平均血压 155/95较上月升高 10mmHg
[Agent 思考] 血压偏高且趋势上升,存在风险。
应该1) 分析趋势 2) 安抚 + 预警
[Agent 调用] analyze_health_trends → 分析血压趋势
[Tool 返回] 血压持续升高趋势,建议关注,风险等级:中等
[Agent 回复] 张爷爷,我看了您最近的血压记录,确实比之前高了一些。
头晕可能和血压升高有关。不过您先别担心,这个趋势我们
可以通过调整生活方式来改善。我建议您先来看看医生,
要不要我帮您预约个心内科的号?
```
### 4.4 会话记忆
- **短期记忆**当前会话完整对话历史DB 持久化 `ai_chat_messages`
- **长期记忆**:用户画像摘要(偏好、常见问题、健康关注点),每次新会话加载
- **上下文窗口管理**:历史消息按重要性截断,保留最近 10 轮 + 关键上下文摘要
---
## 5. 系统集成
### 5.1 后端集成点
```
现有能力 Agent 集成方式
───────── ──────────────
analysis_service (SSE) → Tool: analyze_lab_report / analyze_health_trends
非 SSE 模式调用,直接拿结果返回给 Agent
copilot_engine (风险评分) → Tool: get_health_insights
调用 scoring + rules返回结构化风险信息
knowledge (structured) → Tool: search_medical_knowledge
查询 KDIGO 规则、科室指南、科普文章
local_rules_engine → Tool: check_alert_rules
评估当前数据是否触发告警
quota_service → Agent Orchestrator 内部调用
每轮 Tool Call 前检查配额
usage_service → Agent Orchestrator 内部调用
记录每轮 token 消耗
cache_service → 分析类 Tool 内部复用
相同参数的重复分析走缓存
```
### 5.2 数据模型新增
#### ai_chat_sessions — AI 会话表
```sql
CREATE TABLE ai_chat_sessions (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
user_id UUID NOT NULL,
patient_id UUID,
title VARCHAR(255),
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active / closed
metadata JSONB,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
created_by UUID,
updated_by UUID,
deleted_at TIMESTAMPTZ,
version INTEGER NOT NULL DEFAULT 1
);
```
#### ai_chat_messages — AI 聊天消息表
```sql
CREATE TABLE ai_chat_messages (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
session_id UUID NOT NULL REFERENCES ai_chat_sessions(id),
role VARCHAR(20) NOT NULL, -- user / assistant / tool
content TEXT,
tool_calls JSONB, -- assistant 消息中的 tool call 列表
tool_call_id VARCHAR(100), -- tool 消息的关联 ID
token_count INTEGER,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
created_by UUID,
updated_by UUID,
deleted_at TIMESTAMPTZ,
version INTEGER NOT NULL DEFAULT 1
);
```
#### ai_tool_call_logs — AI 工具调用日志
```sql
CREATE TABLE ai_tool_call_logs (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
session_id UUID NOT NULL,
message_id UUID NOT NULL,
tool_name VARCHAR(100) NOT NULL,
parameters JSONB,
result_summary TEXT,
execution_ms INTEGER,
success BOOLEAN NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```
### 5.3 API 设计
```
POST /api/v1/ai/chat/sessions — 创建会话
GET /api/v1/ai/chat/sessions — 会话列表
GET /api/v1/ai/chat/sessions/{id} — 会话详情
DELETE /api/v1/ai/chat/sessions/{id} — 关闭会话(软删除)
POST /api/v1/ai/chat/sessions/{id}/messages — 发送消息(触发 Agent
GET /api/v1/ai/chat/sessions/{id}/messages — 消息历史
```
发送消息端点支持 SSE 流式输出Agent 最终回复)和 JSON 响应两种模式。
---
## 6. 前端演进
### 6.1 消息类型扩展
- **文本消息** — 正常对话内容
- **数据卡片** — "这是您最近的血压趋势" + 小图表
- **操作确认** — "帮您预约了周三上午心内科,确认吗?" + 确认/取消按钮
- **转接通知** — "正在为您转接值班医生..."
### 6.2 会话管理
- 会话列表页(历史对话)
- 新建会话 / 继续会话
- 历史从本地 Storage 迁移到 DB 持久化
### 6.3 小程序 + Web 同步
两套前端复用相同的 API 模块UI 各自适配平台规范。
---
## 7. 分阶段实施计划
### Phase 0基础设施3-4 天)
> 目标Agent 核心循环跑通,能用一个 Tool 完成完整对话
| 任务 | 工作量 |
|------|--------|
| `AgentTool` trait + `ToolRegistry` + `ToolContext` | 0.5 天 |
| `AgentOrchestrator` ReAct 循环(含 Function Calling 消息格式) | 1 天 |
| 数据库迁移:`ai_chat_sessions` + `ai_chat_messages` + `ai_tool_call_logs` | 0.5 天 |
| 实现 1 个 Tool`query_patient_vitals`(验证端到端链路) | 0.5 天 |
| 改造 `chat_handler`:接入 Orchestrator替换原有简单逻辑 | 0.5 天 |
| 单元测试 + 集成测试 | 0.5 天 |
**交付标准**Postman 调用 `/ai/chat`Agent 能查到患者体征数据并自然回复。
### Phase 1Tool 扩展 + 策略 Prompt5-7 天)
> 目标:覆盖全部核心 Tool多策略对话流生效
| 任务 | 工作量 |
|------|--------|
| 数据查询类 Tool`query_lab_reports``query_patient_profile``query_appointments``query_medication` | 1.5 天 |
| AI 分析类 Tool`analyze_lab_report``analyze_health_trends``get_health_insights` | 2 天 |
| 知识类 Tool`search_medical_knowledge``recommend_services``check_alert_rules` | 1.5 天 |
| 多策略 System Prompt 设计 + 调优 | 1 天 |
| 每轮 Tool Call 配额检查 + token 计量 | 0.5 天 |
| 测试覆盖 | 1 天 |
**交付标准**:模拟 5 种典型场景(安抚/科普/推荐/预警/引导到院Agent 均能自主选择正确策略和 Tool。
### Phase 2前端升级 + 流式输出5-7 天)
> 目标:小程序 + Web 都有完整 AI 客服体验
| 任务 | 工作量 |
|------|--------|
| 后端:会话 CRUD API创建/列表/历史消息) | 1 天 |
| 后端Agent 最终回复走 SSE 流式输出 | 1 天 |
| 小程序:会话列表页 + 消息历史页 + 富消息渲染 | 2 天 |
| Web同上复用 API 模块 | 1.5 天 |
| 数据卡片渲染(体征趋势小图表) | 1 天 |
| 前端迁移:本地 Storage → DB 持久化 | 0.5 天 |
**交付标准**:小程序打开 AI 客服,能自然对话,能看到数据卡片,能看到流式输出。
### Phase 3行动类 Tool + 人机协作3-5 天)
> 目标AI 客服能帮用户预约、转接人工
| 任务 | 工作量 |
|------|--------|
| `create_appointment` Tool带二次确认机制 | 1 天 |
| `transfer_to_human` Tool + WebSocket 通知值班医护 | 2 天 |
| 操作确认 UI预约确认卡片、转接状态提示 | 1 天 |
| 安全边界加固(行动类 Tool 权限标记、审计日志) | 0.5 天 |
| 端到端测试 | 0.5 天 |
**交付标准**:用户对 AI 说"帮我预约个号"AI 查时段→推荐→确认→创建预约,全流程跑通。
### 总工期
```
Phase 0 ████████ (3-4天)
Phase 1 ████████████████ (5-7天)
Phase 2 ████████████████ (5-7天)
Phase 3 ██████████ (3-5天)
────────────────────────
合计 16-23 天
```
每个 Phase 结束后都有可演示的交付物。
---
## 8. 风险与缓解
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| Function Calling 格式跨 Provider 不统一 | 中 | 高 | Phase 0 就在 3 个 Provider 上验证 |
| LLM 幻觉(编造数据/错误诊断) | 高 | 严重 | System Prompt 强约束 + Tool 返回数据做事实校验 + 免责声明 |
| Token 成本超预期 | 中 | 中 | 每轮配额检查 + 缓存复用 + 5 轮上限 |
| Tool 执行超时 | 低 | 中 | 单个 Tool 超时 10s总轮次超时 60s |
| PII 泄露给 LLM | 低 | 严重 | Tool 层脱敏,敏感字段不传给 Provider |