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`

```prisma
// --- 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 |

### 新增角色

```typescript
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 | **开关调试模式** |

### 业务模块集成

```typescript
// 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);
  }
}
```

---

## 🎨 前端组件

### 全局调试开关

```tsx
// 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）

```typescript
// 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` - 架构梳理

---

**🚀 准备开始开发了吗？**