# **提示词管理系统与生产环境灰度预览方案技术设�?*

文档版本�?v1.1  
状态： 待开�? 
优先级： P1 (核心通用能力)  
适用环境�?阿里�?SAE (生产环境)  
核心架构�?Postgres-Only \+ Hot Reload \+ Preview Mode \+ RBAC

## **1\. 核心理念：把生产环境变成调试者的“超级游乐场�?*

传统的开发流程是 开发环�?\-\> 测试环境 \-\> 生产环境。对于大模型应用（LLM App），这种流程存在致命缺陷�?*测试环境很难模拟真实的文献数据、复杂的上下文和 Token 消�?*�?
本方案采�?**“生产环境灰度预�?(Production Preview Mode)�?* 策略，并引入 **“调试�?(Debugger)�?* 角色�?
1. **代码与配置分�?*：Prompt 不再是硬编码的字符串，而是数据库中的动态配置�? 
2. **角色化调�?(RBAC)**：不局限于管理员，系统支持 **“调试者�?*（如临床专家、Prompt 工程师）角色。只要拥�?prompt:debug 权限，即可在生产环境开启调试模式�? 
3. **灰度路由**：系统根据当前操作者的身份（是否开启调试模式），动态决定加�?**“正式版 (Active)�?* 还是 **“草稿版 (Draft)�?* 的提示词�? 
4. **真实验证**：调试者可以直接使用生产环境的真实数据（如 ASL �?20 篇文献）来验证新 Prompt 的效果，确认无误后一键发布�?
## **2\. 系统架构设计**

### **2.1 架构�?*

graph TD  
    User\[普通用户\] \--\>|请求业务| API\_Gateway  
    Debugger\[调试�?专家\] \--\>|请求业务| API\_Gateway  
    Debugger \--\>|管理 Prompt| Admin\_Dashboard

    subgraph "阿里�?SAE (生产环境)"  
        API\_Gateway\[Nginx\] \--\> Backend\_App  
          
        subgraph "Node.js Backend Pods (多实�?"  
            Backend\_App\[Backend Service\]  
              
            PromptService\[Prompt Service\]  
            MemoryCache\[内存缓存 (Map)\]  
            DebugSet\[调试会话集合 (Set)\]  
              
            Backend\_App \--\>|1. 获取 Prompt| PromptService  
            PromptService \--\>|2. 查缓�?DB| MemoryCache  
            PromptService \--\>|3. 校验 Debug 权限| DebugSet  
        end  
    end

    subgraph "RDS PostgreSQL"  
        DB\[(Database)\]  
        PlatformTable\[Users & Permissions Table\]  
        PromptTable\[Prompt Versions Table\]  
          
        PromptService \--\>|4. 拉取 Active/Draft| DB  
        Admin\_Dashboard \--\>|5. 更新/发布| DB  
        DB \--\>|6. NOTIFY prompt\_update| PromptService  
    end

### **2.2 核心特�?*

1. **Postgres-Only**：利�?PostgreSQL �?LISTEN/NOTIFY 机制实现多实例缓存同步，无需引入 Redis�? 
2. **无状态设�?*：DebugSet �?MemoryCache 均存储在内存中，配合数据库实现最终一致性�? 
3. **零侵入�?*：普通用户完全感知不�?Prompt 正在被调整，只有开启了 Debug 模式的特定角色能看到变化�?
## **3\. 数据库与权限设计**

### **3.1 提示�?Schema (capability\_schema)**

请将以下 Schema 添加�?backend/prisma/schema.prisma �?capability\_schema 部分�?
// \--- Prompt Management System \---

model PromptTemplate {  
  id          Int       @id @default(autoincrement())  
  code        String    @unique // 唯一标识符，�?'ASL\_SCREENING\_TitleAbstract'  
  name        String    // 人类可读名称  
  module      String    // 所属模�? ASL, DC, AIA, IIT  
  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            // 版本�?1, 2, 3...  
  content     String         // 提示词内�?(Handlebars/Mustache 格式)  
  modelConfig Json?          // 模型参数: { "temperature": 0.1, "model": "deepseek-chat" }  
  status      PromptStatus   @default(DRAFT)  
  changelog   String?        // 修改说明  
  createdBy   String?        @map("created\_by") // 记录是哪个调试者修改的  
    
  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")  
}

### **3.2 权限定义 (platform\_schema)**

利用现有�?RBAC 系统，需要在 permissions 表中预置以下权限�?
| 权限 Code | 描述 | 适用角色 |
| :---- | :---- | :---- |
| prompt:view | 查看 Prompt 列表和详�?| 管理�? 调试�?|
| prompt:edit | 创建草稿、修�?Draft 版本 | 管理�? 调试�?|
| **prompt:debug** | **核心权限**：开�?关闭调试模式 | **管理�? 调试�?* |
| prompt:publish | �?Draft 发布�?Active | 管理�? 资深调试�?|

建议创建一个新角色 **PROMPT\_ENGINEER**，赋予上述所有权限�?
## **4\. 后端核心实现 (PromptService)**

文件路径：backend/src/common/capabilities/prompt/prompt.service.ts

### **4.1 核心逻辑**

* **setDebugMode(userId, enabled)**:  
  1. **鉴权**：首先检查该 userId 是否拥有 prompt:debug 权限（通过 UserContext 或查库）。只有拥有权限的用户允许加入 Debug 集合�? 
  2. **状态维�?*：在内存中维�?Set\<string\>，记录开启了调试模式的用�?ID�? 
* **get(code, variables, userId)**:  
  1. 检�?userId 是否�?debugUsers 集合中�? 
  2. **�?*：优先查询数据库中状态为 DRAFT 的最新版本�? 
  3. **�?*（或�?Draft）：查询内存缓存中的 ACTIVE 版本�? 
  4. **缓存未命�?*：从数据库查�?ACTIVE 版本并写入缓存�? 
  5. 使用 Handlebars 渲染变量�?
### **4.2 热更�?(Hot Reload)**

* 监听 Postgres �?prompt\_update 频道�? 
* 收到通知后，清空内存缓存�?
## **5\. API 接口设计**

### **5.1 管理端接�?(PromptController)**

| 方法 | 路径 | 权限要求 | 描述 |
| :---- | :---- | :---- | :---- |
| GET | /api/admin/prompts | prompt:view | 获取所�?Prompt 模板列表 |
| GET | /api/admin/prompts/:id | prompt:view | 获取特定模板详情及历史版�?|
| POST | /api/admin/prompts/draft | prompt:edit | 保存草稿 (生成新版本，状态为 DRAFT) |
| POST | /api/admin/prompts/publish | prompt:publish | 发布版本 (状�?Draft \-\> Active) |
| POST | /api/admin/prompts/debug | **prompt:debug** | **开关调试模�?* ({ enabled: true }) |

### **5.2 业务集成示例 (ASL 模块)**

�?ASL 模块中调�?Prompt 时，**必须传入 userId**，系统会自动处理灰度逻辑�?
// 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) {  
    // 动态获�?Prompt  
    // 如果 userId 是开启了调试模式的“调试者”，这里会自动拿�?DRAFT �?Prompt  
    const prompt \= await promptService.get(  
      'ASL\_SCREENING\_TitleAbstract',   
      { title: paper.title, abstract: paper.abstract },  
      userId   
    );

    // 调用 LLM...  
    return await llmGateway.chat(prompt);  
  }  
}

## **6\. 前端管理端设�?(Frontend-V2)**

�?frontend-v2/src/modules/admin 下新�?Prompt 管理模块�?
### **6.1 界面功能**

1. **列表�?*：展示所�?Prompt 模板�? 
2. **全局调试开�?*�? 
   * **位置**：界面顶部导航栏或右下角悬浮球�? 
   * **权限控制**：仅当用户拥�?prompt:debug 权限时显示该开关�? 
   * **状态反�?*：开启后，全站顶部出现黄色警告条：“⚠�?调试模式已开启：您当前正在使用草稿版 (DRAFT) 提示词进行操作”�? 
3. **编辑�?*�? 
   * 支持 Markdown 高亮�? 
   * 操作栏根据权限动态显示：如果没有 prompt:publish 权限，则“发布”按钮置灰�?
### **6.2 典型工作�?(Workflow)**

1. **场景**：临床专�?Dr. Wang (角色: Debugger) 觉得文献筛选的准确率不够�? 
2. **修改**：Dr. Wang 登录系统，进�?Prompt 管理页，修改 ASL\_SCREENING 的提示词，增加了一条排除标准，点击“保存草稿”�? 
3. **调试**：Dr. Wang 点击顶部�?**“开启调试模式�?*�? 
4. **验证**：Dr. Wang 切换�?ASL 业务页面，上传几篇之前筛错的文献，点击运行�? 
   * *系统后端检测到 Dr. Wang �?Debug 列表中，加载 Draft �?Prompt�?  
5. **确认**：发现结果正确了�? 
6. **发布**：Dr. Wang 回到管理页，点击“发布”（或者通知管理员发布）�? 
7. **结束**：Dr. Wang 关闭调试模式�?
## **7\. 实施计划**

### **Phase 1: 基础设施建设 (1-2�?**

1. 创建数据库表 prompt\_templates, prompt\_versions�? 
2. �?permissions 表中插入 prompt:\* 相关权限�? 
3. 实现 PromptService 后端逻辑�?
### **Phase 2: 业务模块接入 (�?ASL 开发同�?**

1. 在开�?ASL 模块时，通过 promptService.get() 获取 Prompt�?
### **Phase 3: 管理�?MVP (3-4�?**

1. 开发前端管理界面�? 
2. 实现全局调试开关组件�?
## **8\. 安全与风�?*

1. **权限隔离**：严格检�?prompt:debug 权限，防止普通用户误入调试模式�? 
2. **审计日志**：PromptVersion 表中�?createdBy 字段必须记录实际修改人的 ID，便于追溯是哪位调试者修改了 Prompt�? 
3. **兜底机制**：代码中保留 Hardcoded Prompt 作为系统级兜底�?
## **9\. 结论**

引入 **“调试者�?* 角色�?RBAC 机制，使得该方案不仅是一个技术实现，更是一套完整的 **AIOps 协作流程**。它允许业务专家在不干扰线上用户的前提下，安全、独立地�?AI 效果进行调优，完美适配医疗场景对准确性的高要求�