HaHafeng
5523ef36ea
Summary: - Implement Prompt management infrastructure and core services - Build admin portal frontend with light theme - Integrate CodeMirror 6 editor for non-technical users Phase 3.5.1: Infrastructure Setup - Create capability_schema for Prompt storage - Add prompt_templates and prompt_versions tables - Add prompt:view/edit/debug/publish permissions - Migrate RVW prompts to database (RVW_EDITORIAL, RVW_METHODOLOGY) Phase 3.5.2: PromptService Core - Implement gray preview logic (DRAFT for debuggers, ACTIVE for users) - Module-level debug control (setDebugMode) - Handlebars template rendering - Variable extraction and validation (extractVariables, validateVariables) - Three-level disaster recovery (database -> cache -> hardcoded fallback) Phase 3.5.3: Management API - 8 RESTful endpoints (/api/admin/prompts/*) - Permission control (PROMPT_ENGINEER can edit, SUPER_ADMIN can publish) Phase 3.5.4: Frontend Management UI - Build admin portal architecture (AdminLayout, OrgLayout) - Add route system (/admin/*, /org/*) - Implement PromptListPage (filter, search, debug switch) - Implement PromptEditor (CodeMirror 6 simplified for clinical users) - Implement PromptEditorPage (edit, save, publish, test, version history) Technical Details: - Backend: 6 files, ~2044 lines (prompt.service.ts 596 lines) - Frontend: 9 files, ~1735 lines (PromptEditorPage.tsx 399 lines) - CodeMirror 6: Line numbers, auto-wrap, variable highlight, search, undo/redo - Chinese-friendly: 15px font, 1.8 line-height, system fonts Next Step: Phase 3.5.5 - Integrate RVW module with PromptService Tested: Backend API tests passed (8/8), Frontend pending user testing Status: Ready for Phase 3.5.5 RVW integration
250 lines
12 KiB
Markdown
250 lines
12 KiB
Markdown
# **提示词管理系统与生产环境灰度预览方案技术设计**
|
||
|
||
文档版本： 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\. 需要配置Prompt的所有模块列表**
|
||
|
||
| 业务模块 | 调用场景 | 核心 Prompt 优化方向 | 复杂度 |
|
||
| :---- | :---- | :---- | :---- |
|
||
| **ASL (AI 智能文献)** | **1\. 标题摘要初筛** | **二分类判别**：需要极高的精准度（Recall 优先）。Prompt 需要包含明确的纳入/排除标准（PICOS），并要求输出 JSON 格式的 bool 值。 | ⭐⭐⭐⭐⭐ |
|
||
| | **2\. 全文复筛** | **复杂信息提取**：从 PDF 提取 PICO 具体数值。Prompt 需要处理长文本（Context Window 限制），并且要有很强的抗幻觉机制（Verification）。 | ⭐⭐⭐⭐⭐ |
|
||
| | **3\. 证据合成** | **逻辑推理**：综合多篇文献生成 Meta 分析结论。需要 Chain-of-Thought (CoT) 提示词。 | ⭐⭐⭐⭐ |
|
||
| **DC (数据清洗)** | **1\. Tool B (双模型提取)** | **结构化抽取**：从病历文本提取字段。Prompt 需要包含医学术语定义、同义词映射规则。 | ⭐⭐⭐⭐⭐ |
|
||
| | **2\. Tool C (数据清洗)** | **代码生成/规则判断**：如“将 A 列的文本映射为标准值”。Prompt 需要精确理解数据上下文，甚至生成 Python/JS 代码片段。 | ⭐⭐⭐⭐ |
|
||
| | **3\. 冲突检测** | **逻辑仲裁**：判断两个模型提取结果哪个更可信。 | ⭐⭐⭐ |
|
||
| **AIA (智能问答)** | **1\. 10+ 智能体** | **角色扮演 (Persona)**：不同的 Agent（如统计师、临床专家）需要不同的 Tone (语气) 和知识边界。 | ⭐⭐⭐ |
|
||
| | **2\. 意图识别** | **路由分发**：判断用户是在闲聊、问诊还是查文献。 | ⭐⭐⭐ |
|
||
| **PKB (知识库)** | **1\. RAG 问答** | **基于上下文回答**：严格限制仅根据检索到的 chunks 回答，杜绝外部知识幻觉。 | ⭐⭐⭐⭐ |
|
||
| | **2\. 批处理阅读** | **摘要生成**：高度浓缩的学术摘要。 | ⭐⭐⭐ |
|
||
| **IIT (IIT Manager)** | **1\. 质控检查** | **规则匹配**：根据 Protocol 检查入组数据。Prompt 需将自然语言的入排标准转化为逻辑判断。 | ⭐⭐⭐⭐⭐ |
|
||
| | **2\. 意图识别** | **数据库查询生成**：将自然语言转为 Prisma 查询或 SQL（需极高安全性）。 | ⭐⭐⭐⭐ |
|
||
| **RVW (稿件审查)** | **1\. 规范性检查** | **Checklist 对照**：逐条核对 CONSORT/STROBE 声明。 | ⭐⭐⭐ |
|
||
|