AIclinicalresearch/docs/03-业务模块/ADMIN-运营管理端/02-技术设计/03-Prompt管理系统快速参考.md

Prompt管理系统快速参考

版本： v1.0
优先级： P0（核心通用能力）
状态： 待开发

---

📌 核心概念

什么是Prompt管理系统？

一个允许专业人员在生产环境安全调试AI Prompt的灰度预览系统。

为什么需要它？

• ❌ 痛点1： 测试环境无法模拟真实医学数据（20篇文献、真实病历）
• ❌ 痛点2： 每次调整Prompt需要改代码→部署→等待（5分钟）
• ❌ 痛点3： 临床专家无法参与调试（他们不会写代码）
• ✅ 解决： 生产环境灰度预览 + 调试者角色 + DRAFT/ACTIVE版本隔离

---

🗂️ 数据库Schema

位置：capability_schema

// --- Prompt Management System ---

model PromptTemplate {
  id          Int       @id @default(autoincrement())
  code        String    @unique                       // 'ASL_SCREENING_TitleAbstract'
  name        String                                  // "ASL标题摘要筛选"
  module      String                                  // ASL, DC, IIT, AIA, PKB, RVW
  description String?
  variables   Json?                                   // ["title", "abstract"]
  
  versions    PromptVersion[]

  createdAt   DateTime  @default(now()) @map("created_at")
  updatedAt   DateTime  @updatedAt @map("updated_at")

  @@map("prompt_templates")
  @@schema("capability_schema")
}

model PromptVersion {
  id          Int            @id @default(autoincrement())
  templateId  Int            @map("template_id")
  version     Int                                     // 版本号
  content     String         @db.Text                 // Prompt内容
  modelConfig Json?                                   // {"temperature": 0.1}
  status      PromptStatus   @default(DRAFT)
  changelog   String?                                 // "增加了排除标准"
  createdBy   String?        @map("created_by")      // UserID（审计）
  
  template    PromptTemplate @relation(fields: [templateId], references: [id])

  createdAt   DateTime       @default(now()) @map("created_at")

  @@map("prompt_versions")
  @@schema("capability_schema")
  
  @@index([templateId, status])
}

enum PromptStatus {
  DRAFT       // 草稿（仅Debug模式可见）
  ACTIVE      // 生产版本
  ARCHIVED    // 归档
  
  @@schema("capability_schema")
}

---

🔐 权限与角色

新增权限

权限 Code	描述	适用角色
prompt:view	查看Prompt列表和历史	SUPER_ADMIN, PROMPT_ENGINEER
prompt:edit	创建/修改DRAFT版本	SUPER_ADMIN, PROMPT_ENGINEER
prompt:debug	⭐ 开启调试模式	SUPER_ADMIN, PROMPT_ENGINEER
prompt:publish	发布DRAFT→ACTIVE	SUPER_ADMIN, PROMPT_ENGINEER

新增角色

enum UserRole {
  SUPER_ADMIN      = 'SUPER_ADMIN',
  PROMPT_ENGINEER  = 'PROMPT_ENGINEER',    // 🆕 核心角色
  HOSPITAL_ADMIN   = 'HOSPITAL_ADMIN',
  PHARMA_ADMIN     = 'PHARMA_ADMIN',
  USER             = 'USER'
}

---

🚀 核心API

管理端接口

方法	路径	权限	描述
GET	/api/admin/prompts	prompt:view	获取所有模板
GET	/api/admin/prompts/:id	prompt:view	获取详情+历史版本
POST	/api/admin/prompts/draft	prompt:edit	保存草稿
POST	/api/admin/prompts/publish	prompt:publish	发布
POST	/api/admin/prompts/debug	prompt:debug	开关调试模式

业务模块集成

// backend/src/modules/asl/services/screening.service.ts

import { promptService } from '@/common/capabilities/prompt/prompt.service';

export class ScreeningService {
  async screenPaper(paper: any, userId: string) {
    // 🎯 核心调用：自动处理灰度逻辑
    const prompt = await promptService.get(
      'ASL_SCREENING_TitleAbstract',
      { title: paper.title, abstract: paper.abstract },
      userId   // ⭐ 必须传入userId
    );

    return await llmGateway.chat(prompt);
  }
}

---

🎨 前端组件

全局调试开关

// frontend-v2/src/modules/admin/components/PromptDebugSwitch.tsx

export const PromptDebugSwitch = () => {
  const { hasPermission } = usePermission();
  const [debugMode, setDebugMode] = useState(false);
  
  if (!hasPermission('prompt:debug')) {
    return null;  // 🔒 权限控制
  }
  
  return (
    <>
      <Switch 
        checked={debugMode} 
        onChange={(enabled) => api.post('/api/admin/prompts/debug', { enabled })}
        checkedChildren="🐛 调试模式"
        unCheckedChildren="生产模式"
      />
      {debugMode && (
        <Alert
          type="warning"
          message="⚠️ 调试模式已开启：您当前正在使用草稿版（DRAFT）提示词"
          banner
        />
      )}
    </>
  );
};

---

📋 涉及模块

模块	核心场景	复杂度	优先级
ASL	标题摘要初筛、全文复筛、证据合成	⭐⭐⭐⭐⭐	P0
DC	Tool B提取、Tool C清洗、冲突检测	⭐⭐⭐⭐⭐	P0
IIT	质控检查、意图识别	⭐⭐⭐⭐⭐	P1
PKB	RAG问答、批处理阅读	⭐⭐⭐⭐	P1
AIA	10+智能体、意图识别	⭐⭐⭐	P2
RVW	规范性检查	⭐⭐⭐	P2

---

⚙️ 核心逻辑（PromptService）

// backend/src/common/capabilities/prompt/prompt.service.ts

export class PromptService {
  private debugUsers = new Set<string>();        // 内存存储调试用户
  private activeCache = new Map<string, string>(); // ACTIVE版本缓存
  
  // 设置调试模式
  async setDebugMode(userId: string, enabled: boolean) {
    if (enabled) {
      this.debugUsers.add(userId);
    } else {
      this.debugUsers.delete(userId);
    }
  }
  
  // 获取Prompt（灰度核心）
  async get(code: string, variables: any, userId: string): Promise<string> {
    // 1. 调试者优先获取DRAFT版本
    if (this.debugUsers.has(userId)) {
      const draft = await this.getDraftVersion(code);
      if (draft) {
        return this.render(draft.content, variables);
      }
    }
    
    // 2. 普通用户获取ACTIVE版本（带缓存）
    let active = this.activeCache.get(code);
    if (!active) {
      const version = await prisma.promptVersion.findFirst({
        where: { 
          template: { code },
          status: 'ACTIVE'
        },
        orderBy: { version: 'desc' }
      });
      active = version?.content || this.getFallback(code);
      this.activeCache.set(code, active);
    }
    
    return this.render(active, variables);
  }
  
  // Postgres LISTEN/NOTIFY 热更新
  async initHotReload() {
    const client = await pool.connect();
    await client.query('LISTEN prompt_update');
    
    client.on('notification', (msg) => {
      this.activeCache.clear();  // 清空缓存
    });
  }
}

---

📅 开发计划

Phase 0: 基础设施（2天）

• 创建数据库表（prompt_templates, prompt_versions）
• 添加prompt:*权限到platform_schema.permissions
• 创建PROMPT_ENGINEER角色
• 实现PromptService核心逻辑

Phase 1: 运营端MVP（3天）

• 前端管理界面（列表、编辑器、版本历史）
• 全局调试开关组件
• 草稿保存/发布功能

Phase 2: 业务模块接入（随业务开发）

• ASL模块调用promptService.get()
• DC模块调用promptService.get()
• 其他模块按需接入

---

🔒 安全与风控

权限隔离

• ✅ 严格检查prompt:debug权限
• ✅ 调试模式状态存储在内存（登出自动失效）

审计日志

• ✅ PromptVersion.createdBy记录修改人
• ✅ AdminOperationLog记录发布行为（module='prompt'）

兜底机制

• ✅ 代码中保留Hardcoded Prompt作为系统级兜底
• ✅ 数据库查询失败时返回默认版本

---

🎯 典型工作流

1. 场景： 临床专家Dr. Wang觉得ASL文献筛选准确率不够

2. 修改： Dr. Wang登录运营管理端，修改ASL_SCREENING的Prompt，增加排除标准，保存草稿

3. 调试： Dr. Wang点击顶部的"开启调试模式"

4. 验证： Dr. Wang切换到ASL业务页面，上传几篇之前筛错的文献
   → 系统后端检测到Dr. Wang在Debug列表中，加载DRAFT版Prompt

5. 确认： 发现结果正确了

6. 发布： Dr. Wang回到管理页，点击"发布"

7. 结束： Dr. Wang关闭调试模式

---

📚 相关文档

• 02-通用能力层_07-运营与机构管理端PRD_v2.1.md - 总体需求
• 02-通用能力层_03-Prompt管理系统与灰度预览设计方案.md - 详细设计
• 00-权限与角色体系梳理报告_v1.0.md - 架构梳理

---

🚀 准备开始开发了吗？