diff --git a/docs/superpowers/specs/2026-05-18-ai-agent-breakthrough-design.md b/docs/superpowers/specs/2026-05-18-ai-agent-breakthrough-design.md new file mode 100644 index 0000000..5a1e9de --- /dev/null +++ b/docs/superpowers/specs/2026-05-18-ai-agent-breakthrough-design.md @@ -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 个 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 + +```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, + pub db: DatabaseConnection, +} + +pub struct ToolResult { + pub output: String, + pub display_hint: Option, +} +``` + +### 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 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 |