# AIA 模块开发记录 - Prompt 管理系统集成

> **日期：** 2026-01-18  
> **开发者：** AI Assistant (Claude)  
> **版本：** V2.1  
> **状态：** ✅ 已完成

---

## 📋 开发目标

将 AIA 智能问答模块的 10 个智能体 Prompt 从硬编码迁移到 PromptService，实现：
- 在管理端可视化配置和调试提示词
- 灰度预览（调试者看 DRAFT，普通用户看 ACTIVE）
- 版本管理和回滚
- 三级容灾（数据库 → 缓存 → 兜底）

---

## 🎯 完成内容

### 1. 数据库迁移脚本

**文件：** `backend/scripts/migrate-aia-prompts.ts`

将 10 个智能体的 Prompt 插入 `capability_schema.prompt_templates` 和 `prompt_versions` 表。

**Prompt Code 命名规则（语义化）：**

| 智能体 ID | Prompt Code | 名称 |
|-----------|-------------|------|
| TOPIC_01 | `AIA_SCIENTIFIC_QUESTION` | 科学问题梳理 |
| TOPIC_02 | `AIA_PICO_ANALYSIS` | PICO 梳理 |
| TOPIC_03 | `AIA_TOPIC_EVALUATION` | 选题评价 |
| DESIGN_04 | `AIA_OUTCOME_DESIGN` | 观察指标设计 |
| DESIGN_05 | `AIA_CRF_DESIGN` | 病例报告表设计 |
| DESIGN_06 | `AIA_SAMPLE_SIZE` | 样本量计算 |
| DESIGN_07 | `AIA_PROTOCOL_WRITING` | 临床研究方案撰写 |
| REVIEW_08 | `AIA_METHODOLOGY_REVIEW` | 方法学评审智能体 |
| WRITING_11 | `AIA_PAPER_POLISH` | 论文润色 |
| WRITING_12 | `AIA_PAPER_TRANSLATE` | 论文翻译 |

**执行命令：**
```bash
cd backend && npx tsx scripts/migrate-aia-prompts.ts
```

### 2. 兜底 Prompt

**文件：** `backend/src/common/prompt/prompt.fallbacks.ts`

添加 `AIA_FALLBACKS` 对象，包含 10 个智能体的兜底提示词，当数据库和缓存都不可用时使用。

### 3. agentService 改造

**文件：** `backend/src/modules/aia/services/agentService.ts`

**改动：**
- 添加 `AGENT_TO_PROMPT_CODE` 映射表
- 修改 `getAgentSystemPrompt()` 函数：
  - 新增 `userId` 参数（用于灰度预览）
  - 调用 `PromptService.get()` 获取提示词
  - 返回 `{ content, isDraft }` 结构
  - 失败时降级到硬编码兜底

**关键代码：**
```typescript
export async function getAgentSystemPrompt(
  agentId: string,
  userId?: string
): Promise<{ content: string; isDraft: boolean }> {
  const promptCode = AGENT_TO_PROMPT_CODE[agentId];
  
  if (promptCode) {
    try {
      const promptService = getPromptService(prisma);
      const result = await promptService.get(promptCode, {}, { userId });
      
      if (result.isDraft) {
        logger.info('[AIA] 使用 DRAFT 版本 Prompt（调试模式）', { agentId, userId });
      }
      
      return { content: result.content, isDraft: result.isDraft };
    } catch (error) {
      logger.warn('[AIA] PromptService 获取失败，使用兜底', { agentId });
    }
  }

  // 兜底：使用硬编码
  const agent = await getAgentById(agentId);
  return { content: agent?.systemPrompt || '', isDraft: false };
}
```

### 4. conversationService 改造

**文件：** `backend/src/modules/aia/services/conversationService.ts`

**改动：**
- 调用 `getAgentSystemPrompt()` 时传递 `userId`
- 处理返回的 `{ content, isDraft }` 结构
- 添加调试模式日志

**关键代码：**
```typescript
const { content: systemPrompt, isDraft } = await agentService.getAgentSystemPrompt(
  conversation.agentId,
  userId  // 传递 userId 以支持灰度预览
);

if (isDraft) {
  logger.info('[AIA:Conversation] 使用 DRAFT 版本 Prompt（调试模式）', { 
    userId, 
    agentId: conversation.agentId 
  });
}
```

### 5. 类型定义修复

**文件：** `backend/src/modules/aia/types/index.ts`

修复 `AgentStage` 类型定义，添加缺失的阶段值：

```typescript
export type AgentStage = 'topic' | 'design' | 'review' | 'data' | 'writing';
```

---

## 📁 修改文件清单

| 文件路径 | 操作 | 说明 |
|----------|------|------|
| `backend/scripts/migrate-aia-prompts.ts` | 新增 | 数据库迁移脚本 |
| `backend/src/common/prompt/prompt.fallbacks.ts` | 修改 | 添加 AIA 兜底 Prompt |
| `backend/src/modules/aia/services/agentService.ts` | 修改 | 集成 PromptService |
| `backend/src/modules/aia/services/conversationService.ts` | 修改 | 传递 userId |
| `backend/src/modules/aia/types/index.ts` | 修改 | 修复类型定义 |

---

## 🧪 测试验证

### 1. 迁移脚本执行结果

```
✅ 共迁移 10 个 AIA Prompt:
  📋 AIA_CRF_DESIGN - 病例报告表设计 - v1 (ACTIVE)
  📋 AIA_METHODOLOGY_REVIEW - 方法学评审智能体 - v1 (ACTIVE)
  📋 AIA_OUTCOME_DESIGN - 观察指标设计 - v1 (ACTIVE)
  ...
```

### 2. 功能测试

- [x] 管理端可以看到 AIA 的 10 个 Prompt
- [x] 可以编辑和保存草稿
- [x] 开启调试模式后可以预览 DRAFT 版本
- [x] 发布后普通用户使用新版本
- [x] 数据库不可用时自动降级到兜底

---

## 🔮 后续可优化

1. **变量支持**
   - 数据库层面已支持（`variables` 字段）
   - 代码层面暂未传入变量
   - 后续可添加：`{{目标期刊}}`、`{{研究类型}}` 等

2. **A/B 测试**
   - 按用户比例分流不同 Prompt 版本
   - 收集效果数据进行对比

3. **Prompt 模板**
   - 提供常用 Prompt 模板库
   - 支持一键套用和自定义修改

---

## 📚 相关文档

- [ADMIN 模块状态](../../ADMIN-运营管理端/00-模块当前状态与开发指南.md)
- [Prompt 管理系统快速参考](../../../02-技术设计/03-Prompt管理系统快速参考.md)
- [通用能力层清单](../../../02-通用能力层/00-通用能力层清单.md)

---

## 📝 备注

本次开发遵循了现有 PromptService 的设计模式，与 RVW 模块集成方式保持一致。