# PRD：知识库笔记工坊（new_notemd）v1.0

> 制片人刘通 × Claude Opus 顾问 ｜ 2026-07-09 立项

---

## §1 背景与目标

### 现状

知识库已有 189 条（doco 22 篇 + Obsidian 164 篇 + 零散上传），但存在三个问题：

1. **只能看标题列表，不能点开看内容**——编导无法阅读和修改已入库的笔记
2. **入库门槛高**——需要手写 yaml frontmatter + md 格式，只有制片人跑脚本才能批量导入
3. **只有制片人能操作**——6 名编导各有专长领域的素材，无法自助贡献

### 目标

把知识库从"制片人单人维护的静态仓库"升级为"全组 8 人共建的活知识库"：

- 编导能**浏览、编辑**已有笔记
- 编导能**自助提交**新素材（多种输入格式），AI 加工成规范笔记
- 制片人/责编**审核把关**，防止质量污染
- 知识库持续生长，为 Phase 4a 对话式选题策划提供更丰富的检索底座

---

## §2 用户角色与权限

| 操作 | 制片人 (zhipianren) | 责编 (zebian) | 编导 (biandao) |
|------|:---:|:---:|:---:|
| 浏览笔记（点标题看全文） | ✅ | ✅ | ✅ |
| 编辑已有笔记 | ✅ | ✅ | ✅（仅自己提交的，或制片人授权的） |
| 新建笔记（AI 加工流程） | ✅ | ✅ | ✅ |
| 审核（通过/驳回） | ✅ | ✅ | ❌ |
| 删除 | ✅ | ❌ | ❌ |

---

## §3 功能模块

### 3.1 笔记查看与编辑（在现有知识库列表页增强）

**交互方式**：点击标题 → 打开右侧抽屉（Drawer）

抽屉内容：
- **上半部分**：渲染后的 md 预览（react-markdown，与诊断报告详情页复用渲染器）
- **下半部分**：元信息卡片（作者、来源、类型、入库时间、审核状态）
- **操作按钮**：「编辑」→ 切换为编辑模式（左编辑右预览双栏）；「保存」→ 写回数据库 + 自动重算 embedding 向量

编辑模式：
- 左栏：md 文本编辑区（textarea，等宽字体）
- 右栏：实时预览
- 元信息字段用表单编辑（标题、作者、来源等）
- 保存时后端自动调 MiniMax embo-01 重算向量

### 3.2 新建笔记（AI 加工流程）——核心新功能

**入口**：知识库页面新增「新建笔记」按钮（与「上传 md 文件入库」并列）

#### 步骤一：选择输入方式 + 提交素材

支持五种输入类型：

| 输入类型 | 操作方式 | 后端处理 |
|---------|---------|---------|
| 粘贴文本 | 文本框粘贴文章内容 | 直接传给 LLM |
| PDF 上传 | 上传 .pdf 文件 | OCR 提取文字（PyMuPDF/pdfplumber） |
| Word 上传 | 上传 .docx 文件 | python-docx 提取正文 |
| 网页链接 | 输入 URL | 后端抓取正文（requests + BeautifulSoup） |
| md 文件 | 上传 .md 文件 | 直接读取（现有功能增强） |

编导还需填写：
- **素材类型**（下拉选择：杂志文章 / 军报文章 / 装备资料 / 技术文献 / 节目文稿 / 动态消息 / 其他）
- **来源说明**（如"航空知识 2026 年第 3 期"）——选填，有则 AI 会参考

#### 步骤二：AI 加工

后端调用 LLM（MiMo，复用现有 MST_knowledge_base 规则），自动：
- 生成规范的 yaml frontmatter（title / author / date / source_type / source_detail / tags / related_entities）
- 整理正文格式（分段、去噪、提取关键信息）
- 生成内容摘要

加工过程显示 loading 状态（"AI 正在整理笔记..."），预计 10-30 秒。

#### 步骤三：编导预览 & 修改

AI 加工完成后展示结果：
- 上方：表单形式展示 frontmatter 字段（可改）
- 下方：左编辑右预览双栏（可改正文）
- 底部：「提交审核」按钮

编导可以：
- 修改 AI 生成的标题、标签、摘要
- 修改正文内容
- 觉得 AI 加工不好可以点「重新加工」

#### 步骤四：提交审核

编导点「提交审核」→ 笔记以 `pending` 状态入库（算向量，但不参与正式搜索）

#### 步骤五：审核（制片人/责编）

审核入口：知识库页面新增「待审核」标签页（或筛选项），显示待审核笔记列表

审核操作：
- **通过**：状态改为 `approved`，进入正式搜索池
- **驳回 + 理由**：状态改为 `rejected`，退回编导修改（编导在"我的笔记"里能看到驳回理由）
- **通过并编辑**：审核人可以直接改完再通过

---

## §4 数据模型变更

### knowledge_items 表新增字段（006 迁移）

```sql
ALTER TABLE knowledge_items
  ADD COLUMN status VARCHAR(20) DEFAULT 'approved' NOT NULL,
  ADD COLUMN submitted_by INTEGER REFERENCES users(id),
  ADD COLUMN reviewed_by INTEGER REFERENCES users(id),
  ADD COLUMN reviewed_at TIMESTAMP,
  ADD COLUMN review_note TEXT;

-- 存量数据全部标记为 approved（制片人历史导入，已审核）
UPDATE knowledge_items SET status = 'approved' WHERE status = 'approved';

-- status 枚举：draft / pending / approved / rejected
-- draft: 编导编辑中未提交
-- pending: 已提交待审核
-- approved: 审核通过，参与搜索
-- rejected: 驳回，需修改
```

### 搜索过滤

现有 `search_similar()` 和列表查询增加 `WHERE status = 'approved'` 过滤（编导查看自己的笔记不受此限制）。

---

## §5 新增 API

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| GET | `/api/knowledge/{id}` | 获取笔记详情（含 content_md） | 全角色 |
| PATCH | `/api/knowledge/{id}` | 编辑笔记（保存后重算向量） | 见 §2 权限表 |
| POST | `/api/knowledge/extract-text` | 上传文件/链接 → 提取纯文本 | 全角色 |
| POST | `/api/knowledge/ai-process` | 纯文本 → AI 加工成规范笔记 | 全角色 |
| POST | `/api/knowledge/submit-review` | 提交审核（status → pending） | 全角色 |
| PATCH | `/api/knowledge/{id}/review` | 审核操作（通过/驳回） | zhipianren + zebian |
| GET | `/api/knowledge/pending` | 获取待审核列表 | zhipianren + zebian |
| GET | `/api/knowledge/my-notes` | 获取"我的笔记"列表 | 全角色 |

---

## §6 前端页面结构

### 知识库页面改动（KnowledgePage.jsx）

```
知识库
├── 搜索栏（不变）
├── 操作栏
│   ├── [上传 md 文件入库]（现有）
│   ├── [新建笔记]（新增，打开新建流程）
│   └── [待审核 (N)]（新增，仅制片人/责编可见，显示待审数量角标）
├── 左侧树形视图（不变）
├── 右侧列表
│   ├── 标题可点击 → 打开查看抽屉
│   ├── 状态列（新增：已审核/待审核/已驳回）
│   └── 操作列：查看 | 编辑 | 删除（按权限显示）
└── 查看/编辑抽屉（新增）
    ├── 查看模式：md 渲染 + 元信息
    └── 编辑模式：左编辑右预览 + 元信息表单
```

### 新建笔记流程页（NoteWorkshop.jsx 或 Modal）

```
新建笔记
├── Step 1：输入方式选择 + 素材提交
│   ├── Tab 切换：粘贴文本 | PDF | Word | 网页链接 | md 文件
│   ├── 素材类型下拉
│   └── [开始加工] 按钮
├── Step 2：AI 加工中（loading）
├── Step 3：预览 & 修改
│   ├── frontmatter 表单（标题/作者/来源/标签等）
│   ├── 正文编辑（左编辑右预览）
│   └── [提交审核] / [重新加工] 按钮
└── 完成提示："已提交审核，等待制片人/责编审批"
```

---

## §7 验收标准

1. **能看**：点击任意笔记标题，抽屉打开显示完整 md 渲染内容和元信息
2. **能改**：编辑模式下修改内容并保存，搜索结果反映修改后的内容（向量已更新）
3. **能建**：通过粘贴文本创建笔记，AI 加工后 frontmatter 字段完整、正文格式规范
4. **能传**：PDF / Word / 网页链接均能成功提取文字并进入 AI 加工流程
5. **能审**：编导提交后制片人能看到待审核列表，通过后笔记出现在搜索结果中，驳回后编导能看到理由
6. **不污染**：未审核的笔记不出现在语义搜索结果中
7. **权限正确**：编导不能审核、不能删除、不能编辑他人笔记（除非被授权）

---

## §8 分刀实施计划

### 第一刀：查看 + 编辑（纯前端 + 1 个 PATCH 接口）

- 列表标题可点击 → 打开查看抽屉（GET `/api/knowledge/{id}`）
- 抽屉内 md 渲染 + 编辑模式切换
- PATCH 接口保存 + 重算向量
- 不涉及 schema 变更

### 第二刀：新建笔记 AI 加工流程

- 006 迁移（加 status / submitted_by / reviewed_by 等字段，先 pg_dump）
- 文本提取接口（PDF / Word / 链接）
- AI 加工接口（调 LLM）
- 前端新建笔记流程页

### 第三刀：审核流程 + 权限

- 提交审核 / 审核操作接口
- 前端待审核列表 + 审核操作
- 搜索过滤 `status = 'approved'`
- 权限校验（编导不能审核/删除）

### 第四刀：打磨 + 边界

- "我的笔记"视图
- 驳回理由展示 + 退回修改流程
- 网页链接抓取的健壮性（超时/编码/反爬）
- 编辑权限细化（编导仅编辑自己的笔记）

每刀独立验收，制片人真实点页面逐条验。

---

## §9 制片人拍板记录

1. [2026-07-09] **不做独立软件**：笔记生成功能做在网页端，编导打开浏览器就能用，不增加安装成本。
2. [2026-07-09] **五种输入类型**：粘贴文本 / PDF / Word / 网页链接 / md 文件。
3. [2026-07-09] **审核制**：编导提交 → 制片人/责编审核 → 通过才进搜索池。AI 设计哲学红线的延伸。
4. [2026-07-09] **AI 加工复用 MST 规则**：沿用现有 MiMo + MST_knowledge_base prompt 规则，不另起炉灶。