# AISP

**Repository Path**: Meridian_pole/aisp

## Basic Information

- **Project Name**: AISP
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AISP - AI 标准化病人

> 中医辨证论治训练系统 | Traditional Chinese Medicine Syndrome Differentiation Training System

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
[![React](https://img.shields.io/badge/React-19.2-cyan.svg)](https://react.dev/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com/)
[![License](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)

## 项目概述

**AISP (AI Standardized Patient)** 是一个基于**纯 LLM 驱动多智能体架构**的中医辨证论治训练系统。系统通过模拟真实患者问诊场景，让中医学生在交互式对话中练习四诊合参、辨证论治，并获得实时、个性化的反馈。

当前版本已接入完整角色体系：

- **学生端**：病例选择、问诊实训、辨证提交、评估报告、历史记录
- **教师端**：学生成绩查看、训练详情复盘、病案新增/编辑/归档
- **管理员端**：用户创建、角色调整、账号启停、系统运营概览

### 核心理念

- **LLM-First 架构**：所有智能决策由 LLM 完成，无规则引擎
- **流式优先设计**：所有 LLM 调用采用 SSE 流式传输
- **多智能体协作**：六大专业智能体协同完成训练流程
- **渐进式信息披露**：模拟真实患者的"问了才说"特性

### 核心训练流程

```
病例选择 → 四诊采集(十问歌) → 症状确认 → 证候分析 → 诊断提交 → 评估报告 → 历史回顾
```

## 运行截图

### 1. 登录界面
![登录界面](image.png)

### 2. 案例选择界面
![案例界面](image-16.png)

### 3. 病人信息展示
![病人信息](image-2.png)

### 4. 操作提示面板
![操作提示](image-3.png)

### 5. 问诊对话界面
![问诊界面](image-5.png)

### 6. 实时进度监控

#### 侧边栏问诊进度 + 顶部患者情绪变化
![侧边栏问诊进度+顶部患者情绪变化](image-6.png)

#### 多维信息收集完整度监控
![多维信息收集完整度监控](image-7.png)
<p align="center">左侧：问诊对话，右侧：多维信息收集完整度监控</p>

#### 十问歌覆盖率监控
![十问歌覆盖率监控](image-8.png)
<p align="center">右侧：十问歌覆盖率监控</p>

### 7. 辨证提交流程

#### 四诊摘要
![四诊摘要](image-9.png)

#### 辨证构建
![辩证构建](image-11.png)

#### 治法输入
![治法输入](image-12.png)

#### 开方选药
![开方选药](image-13.png)

### 8. 辨证评估
![辩证评估](image-14.png)

### 9. 辨证实训报告
![辩证实训报告](image-15.png)

---

## 系统架构

### 整体架构图

```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              前端层 (React 19 + TypeScript + SSE)                    │
├─────────────────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐            │
│  │ 十问歌面板    │  │ 进度追踪面板  │  │ 证候构建器   │  │ 评估视图     │            │
│  │ TenQuestions │  │  Progress    │  │ SyndromeBldr │  │ Evaluation   │            │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘            │
│  ┌──────────────────────────────────────────────────────────────────────────────┐   │
│  │                         问诊室 (多流式 SSE 通信)                              │   │
│  │                     ConsultationRoom (Multi-Stream)                         │   │
│  └──────────────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────────────┘
                                          ↓ 多路 SSE 流
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                           API 层 (FastAPI + Pipeline Layer)                        │
├─────────────────────────────────────────────────────────────────────────────────────┤
│  PipelineCoordinator.execute_pipeline() → Agent.stream_xxx()                       │
│  POST /api/v1/streaming/pipeline/execute                                           │
└─────────────────────────────────────────────────────────────────────────────────────┘
                                          ↓
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                           隔离 SSE 流层 (v2.1)                                      │
├─────────────────────────────────────────────────────────────────────────────────────┤
│  GET /api/v1/streaming/agent/progress/stream   (ProgressTracker)                   │
│  GET /api/v1/streaming/agent/guide/stream     (InquiryGuide)                       │
│  GET /api/v1/streaming/agent/patient/stream   (PatientReAct)                       │
│  GET /api/v1/streaming/agent/syndrome/stream  (SyndromeGuide)                      │
│  GET /api/v1/streaming/agent/evaluate/stream (EvaluationLLM)                       │
│  GET /api/v1/streaming/agent/tutor/stream     (TutorLLM)                           │
└─────────────────────────────────────────────────────────────────────────────────────┘
                                          ↓
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                           智能体层 (纯 LLM 驱动)                                     │
├─────────────────────────────────────────────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │ Patient  │ │Progress  │ │ Inquiry  │ │Syndrome  │ │Evaluation│ │  Tutor   │   │
│  │ (ReAct)  │ │(Tracker) │ │  Guide   │ │  Guide   │ │  (CoT)   │ │  (CoT)   │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘   │
│         ↓            ↓            ↓            ↓            ↓          ↓           │
│  ┌─────────────────────────────────────────────────────────────────────────────┐   │
│  │                   共享 LLM 客户端 (StreamingLLMClient)                       │   │
│  │                  状态持久化于 PipelineSession (每会话)                       │   │
│  └─────────────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────────────┘
                                          ↓
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                           DeepSeek API (流式调用)                                   │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

### 六大智能体说明

| 智能体 | 位置 | 模式 | 职责 |
|--------|------|------|------|
| **Patient** | `agents/patient_react_agent.py` | ReAct | 模拟患者对话、控制信息披露、情绪状态管理 |
| **ProgressTracker** | `agents/progress_tracker_agent.py` | 多维度 | 实时完整性评分（4维度）、可推进检测 |
| **InquiryGuide** | `agents/inquiry_guide_agent.py` | 十问歌 | 覆盖度检测、建议问题、优先级排序 |
| **SyndromeGuide** | `agents/syndrome_guide_agent.py` | TCM 模式 | 治法推荐、证据链构建 |
| **Evaluation** | `agents/evaluation_llm_agent.py` | CoT | 诊断评估（可见推理过程） |
| **Tutor** | `agents/tutor_llm_agent.py` | CoT | 基于学生历史的个性化反馈 |

### SSE 流式事件类型

| 事件类型 | 来源 | 用途 |
|----------|------|------|
| `token` | Patient | 文本令牌（打字机效果） |
| `metadata` | 全部 | 响应元数据 |
| `thinking` | Evaluation/Tutor | LLM 推理过程可视化 |
| `result` | Evaluation | 最终评估数据 |
| `coverage_update` | InquiryGuide | 十问歌覆盖度变化 |
| `suggestion` | InquiryGuide | 建议问题 |
| `completeness_update` | ProgressTracker | 进度分数更新 |
| `phase_suggestion` | ProgressTracker | 阶段转换建议 |
| `emotion_update` | Patient | 情绪状态变化 |
| `proactive_info` | Patient | 主动信息披露 |
| `done` | 全部 | 流完成信号 |
| `error` | 全部 | 错误信息 |

---

## 技术栈

### 后端

| 组件 | 技术 | 版本 |
|------|------|------|
| Web 框架 | FastAPI | 0.104+ |
| ORM | SQLAlchemy | 2.0+ |
| 数据库 | PostgreSQL | 16+ |
| 缓存 | Redis | 7+ |
| AI 编排 | LangChain + LangGraph | 0.1.0+ |
| LLM 提供商 | DeepSeek API | - |
| 数据迁移 | Alembic | 1.13+ |
| 测试 | pytest | - |

### 前端

| 组件 | 技术 | 版本 |
|------|------|------|
| 框架 | React | 19.2+ |
| 构建工具 | Vite | 6.2+ |
| 语言 | TypeScript | 5.8+ |
| 测试 | Vitest + Playwright | - |

---

## 项目结构

```
AISP/
├── backend/
│   ├── app/
│   │   ├── agents/                      # 六大 LLM 智能体
│   │   │   ├── patient_react_agent.py   # 患者 (ReAct)
│   │   │   ├── evaluation_llm_agent.py  # 评估 (CoT)
│   │   │   ├── tutor_llm_agent.py       # 导师 (CoT)
│   │   │   ├── inquiry_guide_agent.py   # 问诊引导 (十问歌)
│   │   │   ├── syndrome_guide_agent.py  # 证候引导 (TCM模式)
│   │   │   └── progress_tracker_agent.py # 进度追踪
│   │   ├── api/v1/endpoints/
│   │   │   ├── streaming.py             # SSE 流式端点
│   │   │   ├── student.py               # 学生训练端点
│   │   │   ├── teacher.py               # 教师端点
│   │   │   └── admin.py                 # 管理员端点
│   │   ├── services/
│   │   │   ├── llm_streaming.py         # 流式 LLM 客户端
│   │   │   ├── state_extractor.py       # 状态提取
│   │   │   └── symptom_extractor.py     # 症状提取
│   │   ├── core/
│   │   │   └── config.py                # 配置管理
│   │   ├── models/                      # SQLAlchemy 模型
│   │   ├── schemas/                     # Pydantic 模式
│   │   └── main.py                      # FastAPI 应用入口
│   ├── tests/                           # 测试套件
│   ├── alembic/                         # 数据库迁移
│   ├── Dockerfile                       # 容器定义
│   ├── docker-compose.yml               # 完整服务编排
│   ├── requirements.txt                 # Python 依赖
│   ├── Makefile                         # 构建自动化
│   └── README.md                        # 后端文档
├── frontendv9.0/
│   ├── components/
│   │   └── ReasoningStepsPanel.tsx      # 推理链组件
│   ├── services/
│   │   └── apiClient.ts                 # 认证、角色、训练 API 客户端
│   ├── App.tsx                          # 三端工作台入口
│   ├── types.ts                         # 类型定义
│   ├── package.json                     # 依赖配置
│   └── README.md                        # 前端文档
├── docs/
│   ├── API.md                           # 完整 API 文档
│   ├── AISP开发文档.md                  # 开发指南
│   ├── AISP运行流程手册_v2.0.md         # 运行流程
│   └── 中医诊疗的规范过程.md            # 业务规范
├── scripts/
│   └── demo-setup.sh                    # 快速部署脚本
├── CLAUDE.md                            # 开发原则与架构指南
└── README.md                            # 本文件
```

---

## 快速开始

### 前置要求

- **Python**: 3.11+
- **Node.js**: 18+
- **PostgreSQL**: 16+
- **Redis**: 7+
- **Docker & Docker Compose** (可选)

### Docker 部署 (推荐)

1. **克隆项目**
```bash
git clone <repository-url>
cd AISP
```

2. **配置环境变量**
```bash
cp backend/.env.example backend/.env
# 编辑 backend/.env，配置 DEEPSEEK_API_KEY
```

3. **启动所有服务**
```bash
docker-compose up -d
```

4. **运行数据库迁移**
```bash
docker-compose --profile migration up migration
```

5. **访问应用**
- 前端: http://localhost:5173
- 后端 API: http://localhost:8086
- API 文档: http://localhost:8086/docs

### 本地开发

**后端:**
```powershell
cd D:\AISP\backend

# 创建虚拟环境
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 安装依赖
python -m pip install -r requirements.txt

# 本地开发必需环境变量
$env:SECRET_KEY="dev-secret-key-change-before-production"
$env:DEBUG="true"

# 启动开发服务器
python -m uvicorn app.main:app --host 0.0.0.0 --port 8086 --reload
```

> Windows PowerShell 中如果提示 `uvicorn` 不是可识别命令，使用 `python -m uvicorn ...`。这会直接调用当前 Python 环境中已安装的 Uvicorn，不依赖脚本目录是否加入 PATH。

**前端:**
```powershell
cd D:\AISP\frontendv9.0

# 安装依赖
npm install

# 启动开发服务器
npm run dev -- --host 127.0.0.1 --port 5173
```

本地访问：

- 前端: http://127.0.0.1:5173
- 后端 API: http://localhost:8086
- API 文档: http://localhost:8086/docs

默认开发账号需要先写入数据库：

```powershell
cd D:\AISP\backend
python scripts\dev.py seed
```

执行完成后可使用以下账号登录前端：

| 角色 | 用户名 | 密码 |
| --- | --- | --- |
| 管理员 | `admin` | `admin123` |
| 教师 | `teacher1` | `password123` |
| 学生 | `student1` | `password123` |
| 学生 | `student2` | `password123` |

数据库连接账号见 `backend/.env`：`aisp` / `password`，这是 PostgreSQL 账号，不是网页登录账号。

---

## 核心特性

### 0. 完整角色体系

系统使用 JWT 登录态和后端 RBAC 校验。公开注册强制创建学生账号；教师和管理员账号由管理员创建。前端登录后根据 `/auth/me` 返回角色自动进入学生端、教师端或管理员端。

角色边界：

- 学生只能访问学生训练、个人历史和已发布病案
- 教师可查看学生训练记录、管理病案资源
- 管理员可管理用户、角色、账号状态和系统概览
- 学生训练流式接口只允许学生角色访问

### 1. 多智能体流水线

六大专业智能体通过 PipelineCoordinator 协同工作，每个智能体拥有独立的 SSE 流，互不阻塞。

### 2. SSE 流式响应

所有 AI 交互采用 Server-Sent Events 实时流式传输，提供流畅的用户体验。

### 3. 十问歌问诊框架

InquiryGuide 基于 16 维度框架（寒热、汗、头身、二便、饮食口渴、胸腹、听力感官、既往史、病因诱因、服药、睡眠、情志、职业环境、妇女经期等）进行问诊覆盖度追踪。

### 4. LLM 驱动的评估

完全基于 LLM 的多维度评估，包括：
- 信息采集完整度
- 辨证准确性
- 证据链质量
- 治法匹配度

### 5. 教师病案闭环

教师端创建或编辑的数据库病案会同步进入病案列表，并可被学生端用于患者模拟、问诊进度评估、辨证评估和训练记录保存。教师删除病案采用归档方式，避免误删历史训练数据。

---

## 开发进度

> 详细开发计划参见 [AISP运行流程手册_v2.0.md](./docs/AISP运行流程手册_v2.0.md)

### 已完成阶段

| 阶段 | 状态 | 完成时间 | 主要成果 |
|------|------|----------|----------|
| **Phase 1** | ✅ 完成 | 2026-01-26 | 测试框架、Agent Coordinator、Inquiry Guide Agent、TenQuestionsPanel、SSE 事件集成 |
| **Phase 2** | ✅ 完成 | 2026-01-26 | Progress Tracker Agent、Patient Agent 优化（主动性披露、情绪状态管理） |
| **Phase 3** | ✅ 完成 | 2026-01-26 | Syndrome Guide Agent（辨证方法推荐、证据链构建） |
| **Phase 4** | ✅ 完成 | 2026-01-26 | E2E 测试、性能优化、文档完善 |

### 测试覆盖

| 模块 | 后端测试 | 前端测试 |
|------|---------|---------|
| Inquiry Guide Agent | 17 tests ✅ | 14 tests ✅ |
| Progress Tracker Agent | 14 tests ✅ | 13 tests ✅ |
| Patient Agent | 16 tests ✅ | - |
| Syndrome Guide Agent | 15 tests ✅ | - |
| **总计** | **52+ tests** | **45+ tests** |

### 新增文件 (Phase 1-4)

**后端:**
- `backend/app/agents/inquiry_guide_agent.py` - 问诊向导智能体
- `backend/app/agents/syndrome_guide_agent.py` - 辨证向导智能体
- `backend/app/agents/progress_tracker_agent.py` - 进度追踪智能体
- `backend/app/core/pipeline_coordinator.py` - Pipeline 核心协调器（v2.1 隔离流）
- `backend/app/core/coordination.py` - 智能体协调层
- `backend/app/api/v1/endpoints/agent_streams.py` - 独立 SSE 端点

**前端:**
- `frontend/components/TenQuestionsPanel.tsx` - 十问歌面板
- `frontend/components/ProgressPanel.tsx` - 进度评分面板
- `frontend/components/EmotionalStateIndicator.tsx` - 情绪状态指示器
- `frontend/components/SyndromeBuilder.tsx` - 辨证构建界面
- `frontend/services/multiAgentStreamingClient.ts` - 多 Agent 流式客户端

---

## 系统运行流程

### 完整训练流程图

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              用户登录                                             │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              病例选择                                             │
│  • 浏览可用病例列表                                                               │
│  • 查看病例基本信息（姓名、年龄、主诉）                                            │
│  • 选择病例开始训练                                                               │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Phase 1: INQUIRY_PREPARED                                     │
│  • 展示病例详细背景                                                               │
│  • 生成初始问诊框架                                                               │
│  • 初始化各智能体状态                                                             │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Phase 2: COLLECTING (四诊采集)                                 │
│  ╔═════════════════════════════════════════════════════════════════════════════╗ │
│  ║                    用户发送问题 → Patient 智能体                                ║ │
│  ║                           ↓                                                   ║ │
│  ║  ┌────────────────────────────────────────────────────────────────────────┐  ║ │
│  ║  │           Patient.stream_chat() - ReAct 推理                              │  ║ │
│  ║  │   1. 分析用户意图 (LLM)                                                   │  ║ │
│  ║  │   2. 检查已披露信息 (state.disclosed_facts)                                │  ║ │
│  ║  │   3. 决定披露内容 (LLM)                                                    │  ║ │
│  ║  │   4. 生成回复 (LLM streaming)                                              │  ║ │
│  ║  │   5. 更新情绪状态 (LLM)                                                    │  ║ │
│  ║  └────────────────────────────────────────────────────────────────────────┘  ║ │
│  ║                           ↓                                                   ║ │
│  ║                   SSE 流式返回患者响应                                          ║ │
│  ╚═════════════════════════════════════════════════════════════════════════════╝ │
│  ╔═════════════════════════════════════════════════════════════════════════════╗ │
│  ║              同时触发后台智能体（非阻塞）                                        ║ │
│  ║  ┌─────────────────────┐  ┌─────────────────────┐                            ║ │
│  ║  │ ProgressTracker     │  │ InquiryGuide        │                            ║ │
│  ║  │ • 四诊覆盖度分析    │  │ • 十问歌维度检测     │                            ║ │
│  ║  │ • 完整性评分        │  │ • 生成建议问题       │                            ║ │
│  ║  │ • can_advance 检测  │  │ • 优先级排序         │                            ║ │
│  ║  └─────────────────────┘  └─────────────────────┘                            ║ │
│  ║           ↓                        ↓                                          ║ │
│  ║    SSE 推送进度更新          SSE 推送问诊建议                                    ║ │
│  ╚═════════════════════════════════════════════════════════════════════════════╝ │
│  • 循环直到学生完成信息采集                                                         │
│  • 完整性 >= 80% 时可进入下一阶段                                                   │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Phase 3: CONFIRMING_SYMPTOMS (症状确认)                        │
│  • LLM 提取四诊信息点                                                              │
│  • 学生确认/补充/修正                                                              │
│  • 生成最终采集证据清单                                                            │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Phase 4: SYNDROME_ANALYSIS (证候分析)                          │
│  ╔═════════════════════════════════════════════════════════════════════════════╗ │
│  ║                    SyndromeGuide 智能体                                       ║ │
│  ║  • 基于已采集信息进行证候分析 (LLM)                                            ║ │
│  ║  • 推荐可能的证候类型 (TCM 知识库 + LLM)                                       ║ │
│  ║  • 构建证据链：信息 → 症状 → 证候                                              ║ │
│  ║  • 提供治法建议                                                               ║ │
│  ╚═════════════════════════════════════════════════════════════════════════════╝ │
│  • 学生选择/输入证候诊断                                                           │
│  • 学生选择/输入治法                                                               │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Phase 5: EVALUATING (诊断评估)                                 │
│  ╔═════════════════════════════════════════════════════════════════════════════╗ │
│  ║                    Evaluation 智能体 (CoT)                                     ║ │
│  ║  ┌────────────────────────────────────────────────────────────────────────┐  ║ │
│  ║  │                     思考链 (可见)                                        │  ║ │
│  ║  │  1. 对比学生诊断与金标准 (LLM)                                            │  ║ │
│  ║  │  2. 分析信息采集完整度 (LLM)                                              │  ║ │
│  ║  │  3. 评估辨证逻辑合理性 (LLM)                                               │  ║ │
│  ║  │  4. 计算多维度得分                                                         │  ║ │
│  ║  └────────────────────────────────────────────────────────────────────────┘  ║ │
│  ║           ↓                                                                   ║ │
│  ║        SSE 流式推送思考过程                                                   ║ │
│  ║           ↓                                                                   ║ │
│  ║  ┌────────────────────────────────────────────────────────────────────────┐  ║ │
│  ║  │                     评估报告                                            │  ║ │
│  ║  │  • 证候准确性得分                                                         │  ║ │
│  ║  │  • 治法匹配度得分                                                         │  ║ │
│  ║  │  • 信息采集完整度                                                         │  ║ │
│  ║  │  • 证据链质量分析                                                         │  ║ │
│  ║  │  • 改进建议                                                               │  ║ │
│  ║  └────────────────────────────────────────────────────────────────────────┘  ║ │
│  ╚═════════════════════════════════════════════════════════════════════════════╝ │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Phase 6: TUTORING (导师反馈)                                   │
│  ╔═════════════════════════════════════════════════════════════════════════════╗ │
│  ║                    Tutor 智能体 (CoT)                                         ║ │
│  ║  • 分析学生当前表现 (LLM)                                                     ║ │
│  ║  • 查阅学生历史表现记录                                                        ║ │
│  ║  • 生成个性化反馈 (LLM)                                                       ║ │
│  ║  • 识别能力短板，给出针对性建议                                                 ║ │
│  ╚═════════════════════════════════════════════════════════════════════════════╝ │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Phase 7: COMPLETED (完成)                                     │
│  • 生成最终综合报告                                                               │
│  • 可视化展示评估结果                                                             │
│  • 展示完整证据链                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Phase 8: HISTORY (历史回顾)                                   │
│  • 查看历史训练记录                                                               │
│  • 能力成长追踪                                                                   │
│  • 薄弱环节分析                                                                   │
└─────────────────────────────────────────────────────────────────────────────────┘
```

#### 阶段详解

![alt text](da2e696d8a35f91d2a908c449418b7a0.jpg)

**Phase 1: 问诊准备 (INQUIRY_PREPARED)**

学生选择病例后，系统进入问诊准备阶段。Inquiry Guide Agent 分析病例主诉和患者基本信息，生成初始问诊框架。前端展示病例详细背景（姓名、年龄、性别、职业、主诉等），并在侧边栏初始化十问歌框架（所有维度显示为"未覆盖"状态）。此阶段各智能体的内部状态被初始化，包括 Patient Agent 的情绪状态（通常为"平静"或"配合"）和 disclosed_facts 空集。

**Phase 2: 四诊采集 (COLLECTING)**

这是核心的对话交互阶段，学生通过自然语言向患者提问。Patient Agent 采用 ReAct 推理模式：
1. **分析意图**：理解学生问题的核心关注点
2. **检查披露状态**：查询已披露信息集合，避免重复回答
3. **决定披露内容**：基于问题相关性决定透露哪些信息
4. **生成回复**：通过 LLM 流式生成自然语言回复
5. **更新情绪**：根据对话上下文调整患者情绪状态

同时，后台智能体并行工作：
- **ProgressTracker**：分析四诊覆盖度，计算完整性评分（0-100%），当达到 80% 时提示可进入下一阶段
- **InquiryGuide**：逐项检测十问歌维度覆盖情况，高亮未覆盖项，生成优先级排序的建议问题

此阶段循环进行，直到学生完成信息采集或主动进入下一阶段。

**Phase 3: 症状确认 (CONFIRMING_SYMPTOMS)**

系统通过 LLM 从完整对话历史中提取结构化的四诊信息点，按"望、闻、问、切"分类展示。学生可以确认、补充或修正这些信息。ProgressTracker 重新评估完整性，如果低于 80% 则建议返回继续问诊。此阶段确保学生和系统对采集到的信息有一致的理解。

**Phase 4: 证候分析 (SYNDROME_ANALYSIS)**

Syndrome Guide Agent 基于已采集信息进行证候分析：
1. **辨证方法推荐**：根据疾病类别（外感/内伤、温病等）推荐最合适的辨证方法（八纲、脏腑、六经、卫气营血等），并说明推荐理由
2. **证据链构建**：将已采集的症状关联到证候结论，形成可追溯的证据链
3. **治法建议**：基于证候给出相应的治法建议

学生根据系统引导，选择或输入自己的证候诊断和治法。

**Phase 5: 诊断评估 (EVALUATING)**

Evaluation Agent 采用链式思考（CoT）模式，其推理过程对学生可见：
1. **信息采集分析**：评估四诊信息的完整性和质量
2. **诊断对比**：将学生诊断与金标准对比，分析差异
3. **辨证逻辑评估**：检查从症状到证候的推理链条是否合理
4. **多维度评分**：计算准确性、完整性、证据质量等得分

思考过程通过 SSE 流式输出，让学生看到评估的推理过程，最终生成结构化评估报告。

**Phase 6: 导师反馈 (TUTORING)**

Tutor Agent 基于学生历史表现和本次训练结果，生成个性化反馈：
1. **表现分析**：对比学生历史水平，识别进步和退步
2. **短板识别**：找出学生薄弱的知识点或技能
3. **反馈生成**：肯定做得好的地方，指出不足，解释原因
4. **改进建议**：提供针对性的学习建议（如经典条文、相关病例等）

**Phase 7: 完成 (COMPLETED)**

生成最终综合报告，包含：
- 多维度评分（准确性 40% + 完整性 30% + 证据质量 30%）
- 缺失项清单（十问歌/四诊哪些没问到）
- 辨证结论对比（学生 vs 标准）
- 可视化证据链
- 导师反馈总结

**Phase 8: 历史回顾 (HISTORY)**

学生可查看历史训练记录，包括对话回放（带知识点标注）、多次训练数据对比、能力雷达图等，帮助追踪学习进度。

### 智能体协作流程

```
用户发送消息
      ↓
POST /api/v1/streaming/pipeline/execute
      ↓
PipelineCoordinator.execute_pipeline()
      ↓
┌────────────────────────────────────────────────────────────────────────┐
│                         智能体执行编排                                    │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  1. ProgressTracker.stream_track()    [后台非阻塞]                      │
│     └── 分析对话历史 → 计算完整性 → 推送进度更新                         │
│                                                                        │
│  2. InquiryGuide.stream_guide()      [后台非阻塞]                       │
│     └── 检测十问歌覆盖 → 生成建议问题 → 推送问诊建议                     │
│                                                                        │
│  3. Patient.stream_chat()             [阻塞，等待完成]                   │
│     └── ReAct 推理 → 生成回复 → 更新状态 → SSE 流式输出                 │
│                                                                        │
│  4. SyndromeGuide.stream_analyze()   [当进入证候分析阶段]                │
│     └── 分析症状 → 推荐证候 → 构建证据链 → 推送分析结果                  │
│                                                                        │
│  5. Evaluation.stream_evaluate()     [当提交诊断时]                      │
│     └── CoT 推理 → 多维评分 → 推送思考过程和最终结果                    │
│                                                                        │
│  6. Tutor.stream_feedback()          [评估完成后]                        │
│     └── 分析表现 → 查阅历史 → 生成个性化反馈 → 推送建议                 │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘
      ↓
PipelineSession 持久化状态
      ↓
返回各智能体的 SSE 端点 URL
      ↓
前端连接多个 SSE 流
```

#### 协作机制详解

![alt text](993e172d6e750ae2ed5b47a945980e14.png)

**1. Pipeline 触发**

当用户发送消息时，前端调用 `POST /api/v1/streaming/pipeline/execute`，携带会话 ID、病例 ID、用户消息和历史对话记录。后端 PipelineCoordinator 接收请求，创建或恢复 PipelineSession，然后按预定义顺序依次执行智能体。

**2. 串行执行，并行推送**

虽然智能体按固定顺序串行执行（Progress → Guide → Patient），但它们通过独立的 SSE 队列推送结果。这意味着：
- ProgressTracker 和 InquiryGuide 作为"后台分析型"智能体，执行较快且不阻塞
- Patient Agent 作为"对话型"智能体，需要等待 LLM 流式生成完成
- 前端同时连接多个 SSE 端点，按接收到的事件顺序更新 UI

**3. 状态隔离与共享**

每个智能体维护自己的状态（如 Patient 的 disclosed_facts、InquiryGuide 的 coverage_map），通过 PipelineSession 的 context 字段共享必要信息。这种设计确保：
- 智能体之间相互独立，一个崩溃不影响其他
- 共享上下文（如对话历史）在智能体间传递
- 状态可持久化到 Redis，支持会话恢复

**4. SSE 事件路由**

每个智能体有独立的 SSE 端点 URL：
- `/api/v1/streaming/agent/progress/stream` → ProgressTracker 事件
- `/api/v1/streaming/agent/guide/stream` → InquiryGuide 事件
- `/api/v1/streaming/agent/patient/stream` → Patient 事件
- `/api/v1/streaming/agent/syndrome/stream` → SyndromeGuide 事件
- `/api/v1/streaming/agent/evaluate/stream` → Evaluation 事件
- `/api/v1/streaming/agent/tutor/stream` → Tutor 事件

前端通过 EventSource API 连接这些端点，根据事件类型（token、coverage_update、suggestion、completeness_update 等）分发到不同的 UI 组件。

**5. 阶段感知的智能体激活**

并非所有智能体在每轮对话中都会激活：
- **COLLECTING 阶段**：ProgressTracker + InquiryGuide + Patient 活跃
- **CONFIRMING_SYMPTOMS 阶段**：ProgressTracker 活跃（重新评估完整性）
- **SYNDROME_ANALYSIS 阶段**：SyndromeGuide 活跃
- **EVALUATING 阶段**：Evaluation 活跃
- **TUTORING 阶段**：Tutor 活跃

这种按需激活机制减少了不必要的 LLM 调用，提高系统效率。

### 状态持久化机制

每个会话的状态通过 `PipelineSession` 持久化：

```python
# 每个智能体的独立状态
{
  "session_id": "uuid",
  "patient_agent_state": {
    "disclosed_facts": set(),
    "dialogue_history": [],
    "emotion_state": "neutral"
  },
  "progress_tracker_state": {
    "coverage": {...},
    "completeness": 0.65,
    "can_advance": false
  },
  "inquiry_guide_state": {
    "十问歌_coverage": {...},
    "suggested_questions": []
  },
  "syndrome_guide_state": {
    "evidence_chain": [],
    "recommended_syndromes": []
  }
}
```

### 会话恢复机制

- 每次交互后持久化状态到 Redis
- 下次请求时自动恢复智能体状态
- 支持断点续训

---

## 开发指南

### 核心开发原则

详见 [CLAUDE.md](./CLAUDE.md)：

1. **LLM-First**: 所有智能决策由 LLM 完成，禁止规则引擎
2. **Streaming-First**: 所有 LLM 调用使用流式传输
3. **No Fallback**: 单一代码路径，无降级策略
4. **Single Source**: 每个功能只有一个实现

### 相关文档

- **[后端开发指南](./backend/README.md)** - FastAPI 后端详细说明
- **[前端集成指南](./frontendv9.0/README.md)** - React 前端 API 集成
- **[开发原则](./CLAUDE.md)** - 架构与编码规范
- **[API 文档](./docs/API.md)** - 完整 API 接口文档
- **[开发文档](./docs/AISP开发文档.md)** - 中文开发指南
- **[运行流程手册](./docs/AISP运行流程手册_v2.0.md)** - 详细业务流程

---

## 测试

### 后端测试

```powershell
cd D:\AISP\backend
$env:SECRET_KEY="test-secret-key-for-local-tests"
$env:DEBUG="true"

# 运行所有测试
python -m pytest

# 运行特定测试文件
python -m pytest tests/test_patient_agent_enhancements.py

# 运行角色体系与三端权限回归测试
python -m pytest tests/test_role_management.py -q -rs

# 运行特定测试
python -m pytest -k "test_proactive_disclosure"

# 带覆盖率报告
python -m pytest --cov=app
```

### 前端验证

```powershell
cd D:\AISP\frontendv9.0

# 生产构建验证
npm run build

# 本地开发服务
npm run dev -- --host 127.0.0.1 --port 5173
```

> 当前 `frontendv9.0/package.json` 暂未配置 Vitest/Playwright 脚本，前端交付前以 `npm run build` 作为基础构建验证。

---

## 部署

### 环境配置

**后端 `.env`**:
```bash
# 数据库
DATABASE_URL=postgresql+asyncpg://aisp:password@localhost:5432/aisp

# DeepSeek API (必需)
DEEPSEEK_API_KEY=sk-...
DEEPSEEK_API_BASE=https://api.deepseek.com/v1

# Redis
REDIS_URL=redis://localhost:6379/0

# JWT 密钥
SECRET_KEY=your-secret-key-change-in-production

# 本地开发可开启 docs 与宽松 CORS
DEBUG=true
```

**前端 `frontendv9.0/.env.local`**:
```bash
VITE_API_BASE_URL=http://localhost:8086
```

### Docker 部署

```bash
# 构建并启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f backend

# 停止服务
docker-compose down

# 重新构建
docker-compose up -d --build
```

---

## 贡献指南

欢迎贡献！请遵循以下原则：

1. 遵循项目的开发原则 ([CLAUDE.md](./CLAUDE.md))
2. 为新功能编写测试
3. 更新相关文档
4. 使用规范的 commit message

---

## 许可证

本项目为专有软件，版权所有。

---

## 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue
- 发起 Pull Request