fastapi/docs/09_prompt_template_catalog.md

# 提示词模板目录

本文档说明当前项目中 Markdown 提示词模板的用途、调用位置、输入数据和输出要求。新增或修改提示词时，需要同步更新本文档。

## 1. 提示词加载规则

当前提示词分为两类：

1. 文件模板：存放在 `app/prompts`，由对应 Agent 或服务读取。
2. 代码内系统提示：部分 Agent 会在代码中拼接系统提示，同时结合病例、会话、检查结果和评分规则构造输入。

维护要求：

- 医疗问诊训练类提示词不得替代真实临床诊疗。
- AI 病人不得主动泄露病例隐藏信息。
- 检查检验结果只能来自数据库。
- 评分提示词必须要求结构化 JSON，不能返回纯长文本。
- 学习助手命中知识库时必须引用来源；未命中时必须说明未检索到机构知识库参考。

## 2. 模板清单

| 提示词模板 | 文件路径 | 使用场景 | 调用模块 | 触发接口 | 输入数据 | 输出格式 | 说明 |
|---|---|---|---|---|---|---|---|
| 练习病例提示 | `app/prompts/hint/practice_case_hint.md` | 生成结构化练习提示 | `app/agents/hint_agent.py::HintAgent.generate` | `POST /api/v1/sessions/{session_id}/hints` | 病例标题、主诉、关键症状、关键检查、当前会话 memory、已申请检查、最后一句用户问题 | JSON | 返回 `hints`、`missing_dimensions`、`next_questions`、`recommended_orders`；LLM 失败时使用兜底提示 |
| AI 病人通用模板 | `app/prompts/patient/free_chat.md` | AI 病人通用问诊风格参考 | 当前 `PatientAgent` 主要在代码内拼接系统提示 | `POST /api/v1/sessions/{session_id}/chat/stream` | 病例、隐藏信息、初始化配置、短期 memory、医生问题 | 纯文本 | 文件作为模板资产保留；实际回复规则见 `PatientAgent._build_messages` |
| 百分制评分 | `app/prompts/scoring/default_percentage.md` | 训练评价百分制评分模板 | 当前 `ScoringAgent` 在代码内拼接评分系统提示，文件作为模板资产 | `POST /api/v1/sessions/{session_id}/evaluation` | 病例、问诊 memory、检查、诊断治疗、评分规则、指南引用 | JSON | 输出 `total_score`、`dimension_scores`、`score_details`、`errors`、`improvement_plan` 等 |
| 五分制评分 | `app/prompts/scoring/default_five_point.md` | 训练评价五分制评分模板 | 当前 `ScoringAgent` 支持五分制转换，文件作为模板资产 | `POST /api/v1/sessions/{session_id}/evaluation` | 同百分制 | JSON | `score_type=five_point` 时将百分制结构转换为五分制 |
| 儿科肺炎评分 | `app/prompts/scoring/pediatrics_pneumonia.md` | 儿科支气管肺炎病例评分参考 | 当前评分依赖 `scoring_rule` 和病例数据，文件作为病例专科提示资产 | `POST /api/v1/sessions/{session_id}/evaluation` | 儿科病例、检查、诊断、治疗、评分规则 | JSON | 用于病例专科评分要求维护 |
| 教学互动评分 | `app/prompts/scoring/teaching_interaction_evaluation.md` | 教学互动答题评价 | `app/agents/scoring_agent.py::ScoringAgent.score_teaching` | `POST /api/v1/teaching/evaluation` | 病例、教学题、标准答案、解析、学生作答、评分规则 | JSON | 评价答题正确率、错误原因、学习建议和教学维度表现 |
| 报告整理 | `app/prompts/report/evaluation_report.md` | 评价报告整理模板资产 | `app/agents/report_agent.py::ReportAgent.build_report` 使用代码内校验整理 | 评价生成、PDF 下载 | Scoring Agent 输出 | JSON | Report Agent 不重新评分，只补齐报告字段 |
| 学习助手命中知识库 | `app/prompts/learning_assistant/rag_answer.md` | RAG 命中时的回答模板资产 | 当前 `LearningAssistantAgent._messages` 在代码内拼接同等规则 | `POST /api/v1/learning-assistant/sessions/{assistant_session_id}/chat/stream` | 用户问题、学习助手短期上下文、知识库片段、PDF 名称、页码、chunk_uid | 流式纯文本 | 回答中必须引用来源编号，不得编造 PDF 和页码 |
| 学习助手未命中知识库 | `app/prompts/learning_assistant/no_reference_answer.md` | 未命中知识库时的回答模板资产 | 当前 `LearningAssistantAgent._messages` 在代码内拼接同等规则 | `POST /api/v1/learning-assistant/sessions/{assistant_session_id}/chat/stream` | 用户问题、学习助手短期上下文 | 流式纯文本 | 开头必须说明“未检索到本机构知识库参考” |

## 3. 训练问诊提示词调用链

```text
POST /api/v1/sessions/{session_id}/chat/stream
  -> app/api/sessions.py::chat_stream
  -> app/services/session_service.py::stream_chat
  -> app/agents/patient_agent.py::PatientAgent.stream_reply
  -> PatientAgent._build_messages
  -> LLM stream_chat
```

输入包括：

- `case_base.chief_complaint`
- `case_base.ai_patient_profile`
- `case_base.hidden_patient_info`
- `patient_config`
- Redis 短期 memory
- 医学生当前问题

输出要求：

- 纯文本
- 1 到 3 句话
- 患者或家属口吻
- 不输出 JSON / Markdown / 思考过程
- 不主动泄露隐藏信息
- 不编造检查结果

## 4. 王主任练习提示调用链

```text
POST /api/v1/sessions/{session_id}/hints/stream
  -> app/api/sessions.py::stream_hints
  -> app/services/session_service.py::stream_hints
  -> HintAgent 或业务兜底逻辑
```

结构化提示接口：

```text
POST /api/v1/sessions/{session_id}/hints
  -> app/api/sessions.py::generate_hints
  -> app/services/session_service.py::generate_hints
  -> app/agents/hint_agent.py::HintAgent.generate
  -> app/prompts/hint/practice_case_hint.md
```

输出字段：

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

LLM 输出非法 JSON 或调用失败时，`HintAgent._fallback_output` 会根据病例关键点和已申请检查生成稳定提示。

## 5. 训练评价提示词调用链

```text
POST /api/v1/sessions/{session_id}/evaluation
  -> app/api/sessions.py::create_evaluation
  -> app/services/evaluation_service.py::create_evaluation
  -> app/agents/scoring_agent.py::ScoringAgent.score
  -> app/agents/report_agent.py::ReportAgent.build_report
```

输入包括病例、Redis 问诊 memory、`training_order` 检查结果、`training_submission` 诊断治疗提交、`scoring_rule` 评分规则和预留指南引用。

输出必须包含 `score_type`、`total_score`、`dimension_scores`、`score_details`、`errors`、`improvement_plan`、`evidence_summary`、`guideline_refs`、`overall_comment`。

异常处理：

- LLM 异常、JSON 解析失败、字段缺失时，`ScoringAgent._fallback_score` 返回稳定结构。
- `ReportAgent` 只整理字段，不重新评分。

## 6. 教学互动评价提示词调用链

```text
POST /api/v1/teaching/evaluation
  -> app/api/teaching.py::create_teaching_evaluation
  -> app/services/teaching_service.py::create_evaluation
  -> app/agents/scoring_agent.py::ScoringAgent.score_teaching
```

输入包括病例信息、教学题列表、标准答案、解析文本、学生作答和评分规则。输出复用训练评价结构，写入 `training_record` 和 `training_score_detail`。

## 7. AI 学习助手提示词调用链

```text
POST /api/v1/learning-assistant/sessions
  -> app/api/learning_assistant.py::create_learning_assistant_session
  -> app/services/learning_assistant_service.py::create_session
  -> app/services/learning_assistant_session_store.py::LearningAssistantSessionStore.create

POST /api/v1/learning-assistant/sessions/{assistant_session_id}/chat/stream
  -> app/api/learning_assistant.py::stream_learning_assistant_session_chat
  -> app/services/learning_assistant_service.py::stream_session_chat
  -> app/agents/learning_assistant_agent.py::LearningAssistantAgent.stream_answer
```

命中知识库时：

- 输入用户问题、学习助手短期上下文和检索到的知识片段。
- 每个来源包含 PDF 名称、页码、chunk_uid、引用文本。
- 回答必须标注来源编号，例如 `【来源1】`。

未命中知识库时：

- 开头必须说明未检索到机构知识库参考。
- 不得伪造 PDF、页码或指南名称。
- 回答仅作为医学学习参考。

## 8. 后续维护规则

新增提示词时必须同时确认：

- 是否有明确调用接口。
- 是否有明确 Agent。
- 输入字段是否来自可信数据源。
- 输出格式是否可被前端或服务稳定解析。
- 是否有 fallback。
- 是否需要同步 `prompt_templates` 元数据。
- 是否需要新增 API 测试或 Agent 单元测试。