AIclinicalresearch/docs/03-业务模块/ADMIN-运营管理端/02-技术设计/Prompt管理后台设计.md

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

文档版本： 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 效果进行调优，完美适配医疗场景对准确性的高要求。