# Prompt 知识库集成开发计划

> **版本：** v1.1  
> **创建日期：** 2026-01-28  
> **优先级：** P0（核心能力增强）  
> **状态：** 📋 规划中  
> **预计工期：** 6-7 个工作日  
> **前置依赖：** Prompt 管理系统 (已完成)、RAG 引擎 (已完成)

---

## 📋 目录

1. [项目概述](#1-项目概述)
2. [需求分析](#2-需求分析)
3. [技术方案](#3-技术方案)
4. [数据库设计](#4-数据库设计)
5. [UI 设计](#5-ui-设计)
6. [开发任务清单](#6-开发任务清单)
7. [AIA 智能体配置指南](#7-aia-智能体配置指南)
8. [测试计划](#8-测试计划)
9. [风险与应对](#9-风险与应对)

---

## 1. 项目概述

### 1.1 背景

当前 Prompt 管理系统已支持：
- ✅ 数据库存储与版本管理
- ✅ 灰度预览（DRAFT/ACTIVE）
- ✅ 变量渲染（Handlebars）
- ✅ 三级容灾（数据库→缓存→兜底）

**缺失能力：** Prompt 无法动态引用外部知识库（如方法学规范、GCP 指南、统计学手册）。

### 1.2 目标

构建 **Prompt + 知识库** 集成能力，实现：

- 🎯 在 Prompt 管理后台配置知识库绑定（非硬编码）
- 🎯 支持两种注入模式：**RAG 检索** 和 **全量注入**
- 🎯 运行时自动将知识库内容注入到 Prompt 变量中
- 🎯 为 AIA 10 个智能体配置最佳知识库策略

### 1.3 核心价值

| 痛点 | 解决方案 |
|------|---------|
| 专家知识只能硬编码到 Prompt | 知识库绑定，动态引用 |
| RAG 检索可能遗漏关键内容 | 支持 FULL 全量注入模式 |
| 每个智能体配置分散在代码中 | 统一后台配置，运营可调整 |

---

## 2. 需求分析

### 2.1 业务需求

| 需求方 | 需求描述 | 优先级 |
|--------|---------|--------|
| 方法学专家 | 方法学评审需要完整参考 CONSORT 声明 | P0 |
| 统计专家 | 样本量计算需要参考公式手册 | P0 |
| 产品经理 | 可在后台配置和调整知识库绑定 | P0 |
| 运营人员 | 无需开发即可为新 Prompt 配置知识库 | P1 |

### 2.2 技术需求

| 需求 | 描述 |
|------|------|
| 两种注入模式 | RAG（向量检索）+ FULL（全量注入） |
| 配置化 | 在 Prompt 管理后台 UI 配置 |
| 变量注入 | 自动将内容注入到指定 Prompt 变量 |
| 缓存优化 | FULL 模式需要缓存知识库全文 |

### 2.3 已有能力复用

| 能力 | 位置 | 状态 |
|------|------|------|
| PromptService | `backend/src/common/prompt/` | ✅ 可扩展 |
| RAG 引擎 | `backend/src/common/rag/` | ✅ 可复用 |
| PKB 知识库 | `backend/src/modules/pkb/` | ✅ 可复用 |
| Prompt 管理 UI | `frontend-v2/src/pages/admin/` | ✅ 可扩展 |

---

## 3. 技术方案

### 3.1 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                    Prompt 管理后台（运营端）                      │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Prompt 编辑器                                            │   │
│  │ ┌─────────────────┐  ┌─────────────────────────────┐   │   │
│  │ │ 内容编辑区域     │  │ 🆕 知识库增强配置面板        │   │   │
│  │ │ {{context}}     │  │ ☑️ 启用知识库增强            │   │   │
│  │ │ {{question}}    │  │ 📚 知识库：[CONSORT声明]     │   │   │
│  │ │ ...             │  │ 🔄 模式：FULL / RAG          │   │   │
│  │ └─────────────────┘  │ 📝 注入变量：context         │   │   │
│  │                      └─────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────┘   │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                  PromptService（增强版）                         │
│                                                                  │
│  get(code, variables, userId, userQuery?)                        │
│       │                                                          │
│       ▼                                                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ 1. 获取 Prompt 模板 + knowledge_config                    │   │
│  │ 2. 检查 knowledge_config.enabled                          │   │
│  │    ├─ 未启用 → 直接渲染返回                               │   │
│  │    └─ 已启用 → 根据 injection_mode 分支处理               │   │
│  │        ├─ FULL → 全量加载知识库文档                       │   │
│  │        └─ RAG  → 向量检索 Top K                           │   │
│  │ 3. 将内容注入 variables[target_variable]                  │   │
│  │ 4. 渲染完整 Prompt 返回                                   │   │
│  └──────────────────────────────────────────────────────────┘   │
└───────────────────────────┬─────────────────────────────────────┘
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
┌──────────────────────┐     ┌──────────────────────────────────┐
│ FULL 模式            │     │ RAG 模式                          │
│ DocumentService      │     │ RagEngine                         │
│ - 全量加载文档       │     │ - 向量检索                        │
│ - 缓存优化           │     │ - Top K + 相似度过滤              │
└──────────────────────┘     └──────────────────────────────────┘
```

### 3.2 注入模式对比

| 特性 | FULL 全量注入 | RAG 向量检索 |
|------|--------------|-------------|
| **适用场景** | 小型核心知识库（<10 篇） | 大型知识库（>20 篇） |
| **准确率** | ⭐⭐⭐⭐⭐ 最高 | ⭐⭐⭐⭐ 较高 |
| **Token 消耗** | 较多（全文） | 较少（片段） |
| **响应速度** | 略慢（预填充） | 较快 |
| **典型用例** | CONSORT 声明、SPIRIT 清单 | ICD-10 编码、文献库 |

### 3.3 数据流

```
用户提问
    │
    ▼
业务模块调用 promptService.get(code, vars, userId, userQuery)
    │
    ▼
┌─────────────────────────────────────────┐
│ PromptService.get()                      │
│                                          │
│ 1. 查询 prompt_templates 获取配置        │
│ 2. 检查 knowledge_config                 │
└─────────────┬───────────────────────────┘
              │
    ┌─────────┴─────────┐
    │                   │
    ▼                   ▼
enabled: false      enabled: true
    │                   │
    ▼                   ▼
直接渲染         判断 injection_mode
                        │
          ┌─────────────┴─────────────┐
          │                           │
          ▼                           ▼
    mode: "FULL"                mode: "RAG"
          │                           │
          ▼                           ▼
    加载知识库全文            向量检索 Top K
    (DocumentService)          (RagEngine)
          │                           │
          └─────────┬─────────────────┘
                    │
                    ▼
        注入到 variables[target_variable]
                    │
                    ▼
            Handlebars 渲染
                    │
                    ▼
              返回完整 Prompt
```

---

## 4. 数据库设计

### 4.1 Schema 变更

**修改表：** `capability_schema.prompt_templates`

```prisma
model prompt_templates {
  id           Int      @id @default(autoincrement())
  code         String   @unique @db.VarChar(100)
  name         String   @db.VarChar(200)
  description  String?  @db.Text
  module       String   @db.VarChar(50)
  variables    Json?
  model_config Json?    @map("model_config")
  
  // 🆕 知识库配置
  knowledge_config Json?  @map("knowledge_config")
  
  created_at   DateTime  @default(now()) @map("created_at")
  updated_at   DateTime  @updatedAt @map("updated_at")
  
  versions     prompt_versions[]
  
  @@map("prompt_templates")
  @@schema("capability_schema")
}
```

### 4.2 knowledge_config 结构

```typescript
interface KnowledgeConfig {
  enabled: boolean;
  kb_codes: string[];              // 关联的知识库编码
  injection_mode: 'FULL' | 'RAG';
  target_variable: string;         // 默认 'context'
  // RAG 模式配置
  query_field?: string;
  top_k?: number;
  min_score?: number;
}
```

### 4.3 系统知识库表（新建）

```sql
-- 系统知识库
CREATE TABLE capability_schema.system_knowledge_bases (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  code VARCHAR(50) UNIQUE NOT NULL,
  name VARCHAR(100) NOT NULL,
  description TEXT,
  category VARCHAR(50),
  document_count INT DEFAULT 0,
  total_tokens INT DEFAULT 0,
  status VARCHAR(20) DEFAULT 'active',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- 知识库文档
CREATE TABLE capability_schema.system_kb_documents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  kb_id UUID REFERENCES capability_schema.system_knowledge_bases(id),
  filename VARCHAR(255) NOT NULL,
  file_path VARCHAR(500),
  file_size INT,
  token_count INT DEFAULT 0,
  status VARCHAR(20) DEFAULT 'pending',
  created_at TIMESTAMP DEFAULT NOW()
);
```

---

## 5. UI 设计

### 5.1 系统知识库管理

**入口：** 运营管理端 → 系统知识库

| 功能 | 说明 |
|------|------|
| 知识库列表 | 查看、搜索、按分类筛选 |
| 创建知识库 | 编码、名称、分类、描述 |
| 文档管理 | 上传/删除文档 |
| 状态查看 | 文档数、Token 数 |

### 5.2 Prompt 编辑器（方案 A：右侧独立卡片）

在现有右侧面板新增「📚 知识库增强」卡片：

```
┌───────────────────────────────────┬─────────────────────────┐
│  📝 Prompt 内容                    │  ⚙️ 配置                 │
│  ┌─────────────────────────────┐ │  模块 / 状态 / 版本      │
│  │ {{context}}                 │ ├─────────────────────────┤
│  │ 你是一位方法学专家...        │ │  📚 知识库增强           │
│  └─────────────────────────────┘ │  ☑️ 启用                  │
│                                   │  知识库: [CONSORT ▼]    │
│  🧪 测试渲染                      │  模式: ● FULL ○ RAG     │
│                                   │  注入变量: [context ▼]  │
│                                   ├─────────────────────────┤
│                                   │  🔤 变量列表             │
└───────────────────────────────────┴─────────────────────────┘
```

---

## 6. 开发任务清单

### 6.1 总体时间线

```
Day 1:   数据库设计 + 迁移
Day 2:   系统知识库管理（后端 API）
Day 3:   系统知识库管理（前端页面）
Day 4:   PromptService 增强（FULL/RAG）
Day 5:   Prompt 编辑器 UI（知识库配置卡片）
Day 6:   AIA 智能体配置 + 集成测试
Day 7:   优化 + 文档 + 上线
```

### 6.2 详细任务

#### Phase 1: 数据库（Day 1）

| ID | 任务 | 状态 |
|----|------|------|
| 1.1 | prompt_templates 添加 knowledge_config 字段 | ⏳ |
| 1.2 | 创建 system_knowledge_bases 表 | ⏳ |
| 1.3 | 创建 system_kb_documents 表 | ⏳ |
| 1.4 | 执行 Prisma 迁移 | ⏳ |

#### Phase 2: 系统知识库管理（Day 2-3）

| ID | 任务 | 状态 |
|----|------|------|
| 2.1 | 知识库 CRUD API | ⏳ |
| 2.2 | 文档上传/删除 API | ⏳ |
| 2.3 | 文档向量化集成 | ⏳ |
| 2.4 | 知识库列表页 | ⏳ |
| 2.5 | 知识库详情页（文档管理） | ⏳ |

#### Phase 3: PromptService 增强（Day 4）

| ID | 任务 | 状态 |
|----|------|------|
| 3.1 | 扩展 get() 方法支持 knowledge_config | ⏳ |
| 3.2 | 实现 FULL 模式（全量加载） | ⏳ |
| 3.3 | 实现 RAG 模式（向量检索） | ⏳ |
| 3.4 | 添加缓存优化 | ⏳ |

#### Phase 4: 前端 UI（Day 5）

| ID | 任务 | 状态 |
|----|------|------|
| 4.1 | PromptEditor 新增知识库配置卡片 | ⏳ |
| 4.2 | 知识库选择器组件 | ⏳ |
| 4.3 | 注入模式切换 | ⏳ |
| 4.4 | 保存/加载配置联调 | ⏳ |

#### Phase 5: 联调收尾（Day 6-7）

| ID | 任务 | 状态 |
|----|------|------|
| 5.1 | 配置 AIA 智能体的 knowledge_config | ⏳ |
| 5.2 | 端到端测试 | ⏳ |
| 5.3 | 上线部署 | ⏳ |

---

## 7. AIA 智能体配置指南

### 7.1 Phase 1: 选题优化

| Prompt Code | 智能体 | 知识库 | 模式 | 理由 |
|-------------|--------|--------|------|------|
| `AIA_SCIENTIFIC_QUESTION` | 科学问题梳理 | 临床研究方法学导论 | **FULL** | 方法学书籍需要全量理解 |
| `AIA_PICO_ANALYSIS` | PICO 梳理 | ICD-10/11 编码手册 | **RAG** | 编码手册数据量大，需检索 |
| `AIA_TOPIC_EVALUATION` | 选题评价 | 顶级期刊选题指南 | **FULL** | 指南内容精简，全量最佳 |

### 7.2 Phase 2: 方案设计

| Prompt Code | 智能体 | 知识库 | 模式 | 理由 |
|-------------|--------|--------|------|------|
| `AIA_OUTCOME_DESIGN` | 观察指标设计 | COMET 核心指标集 | **RAG** | COMET 数据库较大 |
| `AIA_CRF_DESIGN` | CRF 设计 | CDISC/CDASH 标准 | **FULL** | 字段逻辑需要完整参考 |
| `AIA_PROTOCOL_WRITING` | 方案撰写 | SPIRIT 2013 声明 | **FULL** | 清单必须完整参考 |
| `AIA_SAMPLE_SIZE` | 样本量计算 | 样本量公式手册 | **FULL** | 公式手册内容精简 |

### 7.3 Phase 3: 方案预评审

| Prompt Code | 智能体 | 知识库 | 模式 | 理由 |
|-------------|--------|--------|------|------|
| `AIA_METHODOLOGY_REVIEW` | 方法学评审 | CONSORT 2010 声明 | **FULL** | ⭐ **必须全量**，漏检会导致评审不完整 |

### 7.4 Phase 5: 写作助手

| Prompt Code | 智能体 | 知识库 | 模式 | 理由 |
|-------------|--------|--------|------|------|
| `AIA_PAPER_POLISH` | 论文润色 | - | 无 | 纯语言处理，无需知识库 |
| `AIA_PAPER_TRANSLATE` | 论文翻译 | - | 无 | 纯翻译任务，无需知识库 |

---

## 8. 测试计划

### 8.1 单元测试

| 测试项 | 用例 |
|--------|------|
| PromptService.get() | 知识库未启用时正常返回 |
| PromptService.get() | FULL 模式正确加载全文 |
| PromptService.get() | RAG 模式正确检索 Top K |
| PromptService.get() | 知识库不存在时降级处理 |

### 8.2 集成测试

| 场景 | 步骤 | 预期 |
|------|------|------|
| 方法学评审 | 调用 AIA_METHODOLOGY_REVIEW | 返回包含 CONSORT 全文的 Prompt |
| PICO 梳理 | 输入疾病名称 | 返回包含相关 ICD 编码的 Prompt |
| 无知识库 | 调用 AIA_PAPER_POLISH | 正常返回，无知识库内容 |

### 8.3 效果对比测试

| 智能体 | FULL 模式效果 | RAG 模式效果 | 结论 |
|--------|--------------|-------------|------|
| 方法学评审 | 完整覆盖所有条目 | 可能遗漏 | 使用 FULL |
| PICO 梳理 | Token 超限 | 精准命中 | 使用 RAG |

---

## 9. 风险与应对

### 9.1 技术风险

| 风险 | 影响 | 概率 | 应对 |
|------|------|------|------|
| FULL 模式 Token 超限 | 请求失败 | 中 | 设置 max_tokens 限制，超限警告 |
| RAG 检索不准确 | 内容遗漏 | 中 | 提供 FULL 模式备选 |
| 知识库加载慢 | 用户等待 | 低 | 缓存 + 预加载 |

### 9.2 业务风险

| 风险 | 影响 | 应对 |
|------|------|------|
| 知识库内容过时 | 引用错误规范 | 定期更新机制 |
| 配置错误 | 智能体效果下降 | 灰度预览 + 测试 |

### 9.3 成本分析

| 模式 | 典型场景 | Token 消耗 | 成本估算 |
|------|---------|-----------|---------|
| FULL | 5 篇文档，共 5 万 Token | 5 万 | ¥0.05/次 |
| RAG | Top 5 片段，共 5000 Token | 5000 | ¥0.005/次 |

> DeepSeek-V3 输入价格：约 ¥1/百万 Token

---

## 📎 附录

### A. 相关文档

- [Prompt 管理系统设计方案](../00-系统设计/Prompt管理系统升级：知识库集成方案.md)
- [Prompt 管理系统开发计划](./02-Prompt管理系统开发计划.md)
- [AIA 模块状态文档](../../AIA-AI智能问答/00-模块当前状态与开发指南.md)

### B. 代码位置

| 类型 | 路径 |
|------|------|
| PromptService | `backend/src/common/prompt/prompt.service.ts` |
| RAG 引擎 | `backend/src/common/rag/` |
| 前端编辑器 | `frontend-v2/src/pages/admin/PromptEditorPage.tsx` |
| 数据库 Schema | `backend/prisma/schema.prisma` |

### C. 知识库命名规范

```
{CATEGORY}_{NAME}_{VERSION}

示例：
- METHODOLOGY_CONSORT_2010
- METHODOLOGY_SPIRIT_2013
- STATISTICS_SAMPLE_SIZE_FORMULAS
- CRF_CDASH_V2
```

---

*最后更新：2026-01-28*

**🚀 准备好开始了吗？从 Phase 1 数据库设计开始！**