fastapi/docs/05_agent_prompt_design.md

# Agent 编排与提示词模板

## 1. 当前编排结构

```mermaid
flowchart LR
    API["FastAPI Router"] --> Service["Session / Order / Evaluation Service"]
    Service --> Orchestrator["MedicalConsultationOrchestrator"]
    Orchestrator --> Patient["Patient Agent"]
    Orchestrator --> Hint["Hint Agent"]
    Service --> Order["Order Engine"]
    Service --> Knowledge["Knowledge Retrieval"]
    Orchestrator --> Scoring["Scoring Agent"]
    Scoring --> Report["Report Agent"]
```

## 2. Agent 职责

| 模块 | 文件 | 调用时机 | 输出 |
|---|---|---|---|
| Orchestrator | `backend/app/agents/orchestrator.py` | Service 需要调用子 Agent 时 | 统一调度结果 |
| Patient Agent | `backend/app/agents/patient_agent.py` | Chat / SSE Chat | AI 病人文本回复 |
| Hint Agent | `backend/app/agents/hint_agent.py` | 练习模式点击“查看提示” | 结构化提示 JSON |
| Order Engine | `backend/app/services/order_service.py` | 申请检查/检验 | 数据库检查结果 |
| Knowledge Retrieval | `backend/app/services/knowledge_service.py` | 生成评价前 | 评分指南命中片段 |
| Scoring Agent | `backend/app/agents/scoring_agent.py` | 生成 AI 评价 | 结构化评分 JSON |
| Report Agent | `backend/app/agents/report_agent.py` | Scoring Agent 之后 | 报告字段归一化 |

## 3. 模板目录

```text
backend/app/prompts/
├─ hint/
├─ knowledge/
├─ patient/
├─ polish/
├─ report/
└─ scoring/
```

`prompt_templates` 表保存模板元数据和 Markdown 路径。第一版 Demo 中，`HintAgent` 已直接读取 Markdown 模板；`PatientAgent` 和 `ScoringAgent` 当前由代码内置结构化提示拼接，Markdown 模板作为标准资产和后续热加载基础保留。

## 4. 模板清单

| 模板文件 | agent_type | 当前调用状态 | 调用时机 |
|---|---|---|---|
| `hint/novice_case_hint.md` | `hint` | 已调用 | `POST /sessions/{session_id}/hints` |
| `patient/practice.md` | `patient` | 标准资产 | 练习模式 AI 病人回复规则 |
| `patient/teaching.md` | `patient` | 标准资产 | 教学互动模式 AI 病人回复规则 |
| `patient/free_chat.md` | `patient` | 保留 | 早期自由问诊模板 |
| `patient/novice.md` | `patient` | 保留 | 早期新手模式模板，当前归并到 practice |
| `scoring/pediatrics_pneumonia.md` | `scoring` | 标准资产 | 儿科支气管肺炎评分规则 |
| `scoring/default_percentage.md` | `scoring` | 标准资产 | 百分制评分输出约束 |
| `scoring/default_five_point.md` | `scoring` | 标准资产 | 五分制评分输出约束 |
| `report/evaluation_report.md` | `report` | 标准资产 | 评价报告整理规则 |
| `knowledge/guideline_search_query.md` | `knowledge` | 标准资产 | 评分指南检索查询生成 |
| `polish/doctor_question_polish.md` | `polish` | 保留 | 后续医生提问润色 |
| `hint/novice_hint.md` | `hint` | 保留 | 早期提示模板 |

## 5. Markdown 模板字段规范

所有新增模板使用同一结构：

```markdown
---
template_code: novice_case_hint
agent_type: hint
version: v1
scene: practice
model_type: fast
output_format: json
---

# Role

# Task

# Inputs

# Rules

# Output Format

# Safety Boundaries
```

## 6. Patient Agent 运行规则

输入：

- `case_base` 基础病例。
- `traditional_case` 或 `teaching_case` 扩展信息。
- runtime memory 最近对话。
- 已申请检查结果。
- 医学生最新问题。

约束：

- 只扮演患儿家属或 AI 病人。
- 每次回答 1-3 句话。
- 不输出 JSON、Markdown、思考过程。
- 不主动泄露未被问到的隐藏信息。
- 不给诊断或治疗方案。
- 不编造检查结果。

## 7. Hint Agent 运行规则

调用入口：`POST /api/v1/sessions/{session_id}/hints`。

输入 JSON：

```json
{
  "case": {},
  "session": {},
  "conversation_summary": [],
  "ordered_results": [],
  "last_user_message": ""
}
```

输出 JSON：

```json
{
  "hints": [],
  "missing_dimensions": [],
  "next_questions": [],
  "recommended_orders": []
}
```

缺失字段由后端补空数组；LLM 返回非法 JSON 时使用稳定 fallback。提示只在练习模式中由用户手动点击触发，不自动弹出。

## 8. Scoring Agent 运行规则

评分上下文拼接顺序固定：

1. 病例基础信息：`case_base`。
2. 模式扩展信息：`traditional_case` 或 `teaching_case`。
3. 基础评分规则：`scoring_rule`。
4. 指南检索结果：`knowledge_chunks`，未命中时为空数组。
5. 用户作答情况：runtime memory、`training_order`、`training_submission`。
6. 输出格式约束：百分制或五分制。

Scoring Agent 必须输出结构化 JSON：

```json
{
  "score_type": "percentage",
  "total_score": 82,
  "dimension_scores": [],
  "errors": [],
  "improvement_plan": [],
  "evidence_summary": [],
  "guideline_refs": [],
  "overall_comment": ""
}
```

`ReportAgent` 只做字段校验和整理，不重新评分。

## 9. 安全边界

- 本系统只用于医学教学训练，不替代真实临床诊疗。
- 检查结果只来自数据库。
- LLM 不接收真实患者身份信息。
- 历史记录只保存完整训练后的评价结果。
- 未完成训练不会生成长期聊天历史。