AIclinicalresearch/docs/03-业务模块/AIA-AI智能问答/06-开发记录/2026-01-18-Prompt管理系统集成.md

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	论文翻译

执行命令：

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 } 结构
  • 失败时降级到硬编码兜底

关键代码：

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 } 结构
• 添加调试模式日志

关键代码：

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 类型定义，添加缺失的阶段值：

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. 功能测试

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

---

🔮 后续可优化

1. 变量支持

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

2. A/B 测试

   • 按用户比例分流不同 Prompt 版本
   • 收集效果数据进行对比

3. Prompt 模板

   • 提供常用 Prompt 模板库
   • 支持一键套用和自定义修改

---

📚 相关文档

• ADMIN 模块状态
• Prompt 管理系统快速参考
• 通用能力层清单

---

📝 备注

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