hms/docs/superpowers/specs/2026-05-18-ai-agent-breakthrough-design.md

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 个 Provider（Claude/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

#[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 会话表

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 聊天消息表

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 工具调用日志

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 1：Tool 扩展 + 策略 Prompt（5-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