yawan-workbench/设计文档v4.md

# 雅文内容创造工作台 · 设计文档 v4（开放画布 + RAG 知识库）

> 日期：2026-08-25 ｜ 状态：方案确认稿 ｜ 技术路线：FastAPI + SQLite + React(React Flow) + **RAG 知识库**
> v3 → v4 变更：① **内容标签扩充至 26 个**（6 大类，可自定义）② **知识库升级为 RAG 架构**：导入→解析→分块→向量化→语义检索→引用溯源，不再用纯关键词检索

---

## 1. 项目概述

开放的多 Agent 内容工厂（浏览器访问的独立 Web 工作台）：

- 你建 Agent（不限数量）→ 画布连线编排（顺序/依赖/单独启停）→ 每个 Agent 配规则、配**RAG 知识库挂接**
- 每次生产：给主控主题/导图 → 拆解成内容段（每段一个内容标签，同类可多个）→ 按画布派发 → 质检 → 人工审查 → 组合交付（六色 docx）
- **知识库 = RAG 建库**：素材拖进去，系统自动解析、分块、向量化，Agent 用语义检索取料，答案带引用溯源
- 记忆沉淀必须你确认；段间靠锚点卡对齐；组合 Agent 做一致性总检
- **每个 Agent 可独立选择模型**：主控/生产/质检/组合各配各的模型，画布节点上可见可换，任务成本按 Agent 记账

## 2. 内容标签体系（扩充版：26 个预置，6 大类）

主控拆导图时给每个节点标一个标签；Agent 声明擅长标签；标签可自定义新增。★=高频核心。

### 结构类（5）
| 标签 | 定义 | 典型用法 |
|---|---|---|
| ★ 开场 | 扎心暖场/承诺钩子/开场降档 | 案例/悬念 30 秒入题，第一件产品尽量前置 |
| 转场 | 段间衔接（话题自然滑入，禁报幕） | 组合器优先处理；也可由互动标记 Agent 预埋 |
| ★ 收尾 | 信念收尾：最后 30 秒纯信念不卖货 | "所有的性感都不是天生的…"三段式金句 |
| ★ 钩子 | 收口钩子=导图次日真实框架 | 技法名与导图一致，不写死待确认道具 |
| 预告 | 中途预告/下一场承诺 | 只留一个带日期的承诺，其余"回头安排" |

### 内容类（8）
| 标签 | 定义 | 典型用法 |
|---|---|---|
| ★ 心法 | 认知/心态/信念升级 | 概念有画面、论证有对照；金句只点缀不作产品引入 |
| ★ 痛点 | 焦虑唤醒/扎心一刀/痛点直击 | "你干开门，门都没上润滑你硬推，不哭才怪" |
| ★ 动机铺垫 | 讲解前先讲"为什么要听"（1-2 句动机+原理） | 每个知识点/技法前的"为什么"铺垫，压缩时不删 |
| ★ 案例 | 学员案例/姐妹故事 | 一人分饰两角、具体到细节 |
| 见证 | 产品见证/逆袭故事 | 卖货时的真实感来源（与案例区分开） |
| 冷知识 | 身体冷知识/科学证据 | 射精阈值/前列腺位置/括约肌无天然润滑…必须准确 |
| ★ 金句 | 金句收口/三段式金句 | 扎心话术收口干脆 |
| 共鸣 | 情感共鸣/温柔引导型低声区 | 全稿低谷段，气息写、放慢、压低声 |

### 技法类（4）
| 标签 | 定义 | 典型用法 |
|---|---|---|
| ★ 技法 | 外显手法：手活/口活/体位/步骤骨架 | 第一步…第二步…第三步+画面点，不展开细节 |
| ★ 功法 | 内功练习：凯格尔/缩阴功/八爪鱼收紧术类 | 可跟练、有作业（今晚洗澡从第一个摸到第五个） |
| ★ 跟练 | 现场跟练口令+互动指令 | "吸气收紧、呼气放松→公屏打'咬'" |
| 安全提示 | SM/技法安全提示 | 低温蜡烛、拍肉厚处、安全词定义（玫瑰） |

### 产品类（3）
| 标签 | 定义 | 典型用法 |
|---|---|---|
| ★ 产品销售 | 完整销售话术（痛点→价值→价格锚定→限量） | 一产品一概念不混谈；产品随动作进场 |
| ★ 产品体验 | 产品体验感写作（拿起→第一下→扩散→伴侣反应→欲望结果） | 掌心揉热粉嫩油贴锁骨窝停三秒… |
| 产品回指 | 后段产品回指（"老师前面那瓶油"） | 不二次完整销售 |

### 表现类（5）
| 标签 | 定义 | 典型用法 |
|---|---|---|
| ★ 画面 | 画面感描写（色情小说档画面链） | 动作/对话/快感写到底；腿心/热意/颤/烫 |
| ★ 场景 | 场景演绎：角色扮演/SM红房/水元素 | 环境/衣着/光线/气味/心理/动作过程 |
| 情绪 | 情绪低谷/峰值铺垫/三连跳板 | 拍桌→"我只说一遍"→停顿三秒→开讲 |
| 氛围 | 仪式感氛围（音乐/灯光/道具/舞美） | 灰字表演标记落实，不进正文说教 |
| 互动 | 公屏互动（扣字/选择题/等弹幕） | "选择题→等弹幕→统计转折"真互动 |

### 辅助类（4）
| 标签 | 定义 | 典型用法 |
|---|---|---|
| 答疑 | 弹幕答疑/常见问题 | 从原文库检索真实答疑话术 |
| 双主播 | 男女主播互动 | 一唱一和、插科打诨 |
| 毛边 | 直播毛边（自嘲/断句/笑场/闲聊） | 真人感低谷 |
| 仪式 | 开营仪式/七天巡礼（引流课） | 无产品节点=0产品0红色 |

> 标签是开放体系：新建 Agent 时可自定义新标签；主控拆导图时如遇未知类型，列出来让你定标签。

### 2.1 标签管理（开放：随时自己添加）

| 操作 | 说明 |
|---|---|
| 新建标签 | 工作台【标签管理】页一键添加：名称+所属大类+一句话定义+典型用法；立即出现在 Agent 配置和主控拆解的选项里 |
| 编辑/停用 | 改名/改定义/停用（停用后不再出现在选项里，历史任务数据保留） |
| 分组 | 预置 6 大类可调整，也可自建新大类 |
| 未知标签兜底 | 主控拆导图遇到不认识的内容块 → 列入待确认清单让你定标签（定一个立即生效，或归入"待分类"） |
| 数据一致性 | 标签改名/删除时，历史任务的段标签显示旧名（快照），不影响历史数据 |

## 3. Agent 关系画布（同 v3，不变）

节点=Agent（启停开关/知识库挂接显示/**模型标识**）、连线=锚点卡流向、顺序=图拓扑、模板保存、任务快照。同一 Agent 可放多个节点（同类多段并行）。

## 4. 模型管理（每个 Agent 可选不同模型）🆕

### 4.1 模型注册（工作台设置页）

| 项 | 说明 |
|---|---|
| Provider 管理 | 添加任意 OpenAI 兼容 API：DeepSeek / 硅基流动 / 智谱 / Kimi / 通义 / 本地 Ollama…各配 base_url + API key + 模型列表，可同时挂多个 |
| 全局默认模型 | 未单独配置的 Agent 用全局默认（初始=DeepSeek deepseek-chat，你的密钥） |
| 连通性测试 | 设置页一键测试每个 provider：延迟、速度、可用模型刷新 |

### 4.2 每个 Agent 一个模型选择

- Agent 配置里【模型】下拉：从已注册模型里选，或"跟随全局默认"
- 画布节点显示模型标识（如 🟦DeepSeek / 🟩GLM / 🟧Kimi），点开可快速切换
- 同类型多节点（两个技法 Agent）可各用不同模型并行 → 现场对比文风，选出最像的
- 任务快照固化模型选择：任务开工后改模型不影响已跑任务

### 4.3 推荐分工（初始建议，全部可改）

| 角色 | 推荐模型倾向 | 理由 |
|---|---|---|
| 主控 Agent | 强推理（DeepSeek-R1 类） | 导图解析/任务拆解/波次调度要准 |
| 生产 Agent | 文风强、上下文长 | 心法/画面/场景类吃文风，按实际试跑选 |
| 质检 Agent | 强推理+规则执行 | 五类审查要严格逐条对证 |
| 组合 Agent | 长上下文（128K+） | 拼装全文+一致性总检要读全稿 |

### 4.4 成本与日志

- 任务页按 Agent 记录每次调用的模型 / 输入输出 token / 费用
- 同一内容段换模型重跑的成本和效果可对比（A/B 看板）

## 5. RAG 知识库子系统（🆕 v4 核心）

### 5.1 建库管道（导入即建，全自动）

```
素材文件（docx/srt/md/txt/json/导图）
   │  ① 导入（拖拽上传，后台任务+进度条）
   ▼
② 格式解析：docx 提取正文｜srt 去时间戳合并字幕｜md/txt 直读｜json 按结构抽取
   ▼
③ 清洗：去 BOM/空行/提词备注/表演标记归一；SRT 断句合并成完整语段
   ▼
④ 分块 Chunking：标题感知 + 语义边界（按段落/章节切），块大小 400-600 字，
   相邻块重叠 15%（保上下文连续）；每块带元数据 {库id, 文件, 章节, 序号}
   ▼
⑤ 向量化 Embedding：本地 BGE-M3 模型（中文强/多语种，离线可用）
   ▼
⑥ 入库：ChromaDB（嵌入式向量库，collection=知识库，天然隔离）
   ▼
⑦ 索引完成 → 检索测试页可即时验证命中质量
```

### 5.2 检索（Agent 取料时）

```
Agent 生成请求
   │  query 构造：任务切片 + 上游锚点卡 + Agent 规则里的检索意图
   ▼
混合检索（只在挂接的 collection 内查）
   ├─ 向量检索：语义相似度 top-k（k=8，默认可配）
   └─ 关键词检索：BM25 精确命中 top-k（补专有名词：技法名/产品名/暗语）
   ▼
合并去重 → 可选重排（cross-encoder 或 LLM rerank，v4 后置开关）
   ▼
引用溯源：每条命中带 {库, 文件, 章节, 原文块, 相似度}
   → 注入 Agent 上下文（后台可见来源标注，正文永远不出现"知识库里说"）
```

### 5.3 隔离与挂接

- **每库一个 ChromaDB collection + 独立元数据命名空间**：库与库物理隔离，检索互不可见
- Agent 挂接（多选）决定它检索哪些 collection；挂接外的一律查不到
- 删除/更新文件：增量重分块重向量化，不影响其他文件

### 5.4 引用溯源防"表面功夫"

- Agent 产出的每条事实/案例/产品说法，后台记录引用来源（哪个库哪个块）
- **质检 Agent 可一键核对**：选中一句 → 看它的引用 → 与知识库原文对证（防编造、防"报告≠事实"）
- 检索测试页：你输入一句 query，看命中的原文块质量，随时检验库建得好不好

### 5.5 预置种子库（6 个，可增）

| 库 | 素材来源 | 分块要点 |
|---|---|---|
| 风格档案库 | 数字雅文档案/范稿/day1定稿基准/文本层铁律 | 规则型文档按章节分块 |
| 训练营框架库 | 七天导图/28天重排版/历史任务单 | 按天/按节点分块 |
| 直播原文库 | 73 场 SRT（573 万字） | 按场次→段落分块 |
| 备稿库 | 99 篇 docx（150 万字） | 按稿→标题分块 |
| 产品知识库 | 观品 chunks.jsonl | 按产品分块（content 去空格） |
| 质检规则库 | 五类审查清单/词清单/铁律 | 按检查项分块 |

### 5.6 技术选型（RAG 部分）

| 组件 | 选型 | 理由 |
|---|---|---|
| 向量库 | ChromaDB（嵌入式） | 零运维、Python 原生、collection 隔离、metadata 过滤、Windows 免编译 |
| Embedding | 本地 BGE-M3（sentence-transformers） | 中文语义强、离线可用（素材涉敏不外发）、768 维 |
| 备选 Embedding | 硅基流动/智谱 embedding API | 若嫌本地模型占内存（约 1-2GB） |
| 分块 | 自研解析器（python-docx/正则）+ 标题感知切分 | SRT/docx 格式各有专门处理 |
| 重排（可选） | cross-encoder 或 LLM rerank | 命中质量不足时开启 |
| 模型管理 | OpenAI 兼容多 Provider 注册 + 每 Agent 选模型 | DeepSeek/硅基/智谱/Kimi/Ollama 并存，按 Agent 切换 |
| 规模预估 | 700 万字 ≈ 1.4 万块 × 768 维 | ChromaDB 无压力 |

## 6. 失败处理与人工介入（生成不出来 → 必提醒人工）🆕

### 6.1 失败分类与自动重试策略

| 失败类型 | 例子 | 策略 |
|---|---|---|
| 瞬时错误 | API 超时 / 429 限流 / 连接中断 | 自动重试 2 次（指数退避），可配置 |
| 内容拒绝 | 模型拒审："抱歉，我无法生成…"（检测拒绝特征词） | 自动换措辞重试 1 次；仍拒绝 → **转人工**（不无限自动折腾） |
| 空输出/截断 | 输出为空 / 中途截断 / 结构解析失败 | 重试 1 次；仍失败 → 转人工 |
| 模型/Key 错误 | key 失效 / 模型不存在 / 余额不足 | **直接转人工**（重试无意义） |
| RAG 失败 | 检索接口报错 | 重试 1 次 → 转人工；无命中不算失败，但标"低置信"提示 |

**原则：重试只覆盖瞬时问题；凡是"重试解决不了"的失败，一律转人工，绝不静默跳过、绝不假装成功。**

### 6.2 失败提醒与人工介入台

- 节点状态变 **🔴 失败**，任务看板红标 + 通知中心提醒（待处理失败数）
- 点击进入【失败处理面板】，能看到：
  - 哪个 Agent / 哪个节点 / 用的哪个模型 / 失败类型与错误原文
  - 重试次数与调用日志（时间/模型/token/耗时）
  - 失败时的输入上下文（任务切片 + 上游锚点卡 + 规则摘要）
- 人工修复动作（按钮式）：
  - 🔁 重试
  - 🔄 换模型重跑（该 Agent 换另一个已注册模型）
  - 📝 改规则重跑（打开 rules.md 编辑 → 保存即重跑）
  - ✂️ 调整任务切片重跑（如导图段描述触发拒审，改写描述）
  - ⏭️ 跳过该段（组合时注明"本场缺段"）
  - ⏸️ 停用该节点
- **修复后记录原因**：人工在面板填一句"为什么失败/怎么修好的" → 生成记忆建议 → 进待确认池 → 确认后沉淀进该 Agent 记忆（如"该模型对 XX 内容拒审，换 YY 模型可过"）
- 失败不阻塞其他段：一段失败时其他段照常跑，但任务整体保持"⚠️ 有待处理失败"状态，直到人工处理完

## 7. 状态可视化（每个 Agent 工作状态清晰可见）🆕

### 7.1 节点状态机（画布/看板统一）

```
待派发(灰) → 生成中(蓝，显示模型+已耗时) → 质检中(黄，显示第几道)
   → 待人工审查(紫) → 已通过(绿)
   → 打回重做(橙，显示第几轮)
   → ⚠️ 失败(红，点击看原因)
   → 停用(暗) / 跳过(灰斜线，上游停用导致)
```

### 7.2 三处可见

| 位置 | 显示什么 |
|---|---|
| 画布节点 | 实时状态色 + 模型标识 + 当前轮次；点开=详情抽屉 |
| 任务看板 | 每段一行：状态徽章/模型/耗时/轮次/成本；失败红标置顶 |
| 详情抽屉 | 调用日志流（每次 LLM 调用：时间/模型/token/耗时/错误）、质检报告、锚点卡、产物全文、当前输入上下文 |

### 7.3 配套

- **运行日志流**：任务执行时实时滚动（谁在跑/谁在等/谁失败了），可暂停过滤
- **通知中心**：失败提醒 / 待确认清单 / 记忆待确认 / 待分类标签，统一小红点
- **成本面板**：按 Agent × 模型统计 token 与费用
- 状态全部落库（llm_calls 调用日志表 + segments 状态字段），历史可回看

## 8. 系统架构总览（v4）

```
┌─────────────── 你（浏览器） ───────────────────────────────┐
│ 任务看板 · Agent注册中心 · 关系画布 · 知识库管理(RAG) · 审查台 · 记忆 │
└──────┬─────────────────────────────────────────────────────┘
       ▼
┌───────────────────────────────────────────────────────────┐
│ Agent 注册中心：{类型|内容标签(26选多)|知识库挂接(多选)|     │
│               模型选择 | rules.md(版本) | 独立记忆库}        │
└──────────────┬────────────────────────────────────────────┘
               ▼
┌───────────────────────────────────────────────────────────┐
│ Agent 关系画布：节点=Agent(启停) 边=锚点卡流向 模板/快照      │
└──────────────┬────────────────────────────────────────────┘
               ▼ 按拓扑分波次
┌──────────────┴────────────────────────────────────────────┐
│ [生产Agent] ⇄ RAG检索(只查挂接库,带引用溯源)                 │
│   产出：段内容+锚点卡                                       │
│ → 4道质检(报告对证正文+锚点卡+引用) → 人工审查(硬关卡)        │
│ → 组合Agent(拼装+一致性总检+缝合标记) → 六色docx            │
└───────────────────────────────────────────────────────────┘
```

## 9. 里程碑（v4 更新）

| 阶段 | 内容 | 验收 |
|---|---|---|
| **M1（1-3天）** 骨架+知识库管道 | 后端骨架+数据表、Agent 注册中心、**标签管理页**（新建/停用/分组，随时自加）、**模型管理（多 Provider 注册+每 Agent 选模型）**、**状态与失败机制**（节点状态机+调用日志表+失败转人工+通知中心）、**RAG 管道（导入→解析→分块→BGE-M3 向量化→ChromaDB 入库→检索测试页）**、种子库导入（产品库 chunks.jsonl + 风格档案先行）、主控拆解→顺序派发、3 个种子 Agent、结构质检、审查台基础、组合（拼接+docx） | 导图跑通全链路；检索测试页验证产品库/风格库命中质量；两个生产 Agent 用不同模型各跑一段对比文风；你亲手加一个新标签并立刻能用；**故意填错 key 制造一次失败 → 看板红标+通知提醒 → 修复重跑成功** |
| **M2（4-7天）** 画布 | React Flow 画布（拖节点/连线/启停/模板/快照）、波次调度、锚点卡机制、全部种子 Agent、4 道质检 | 画布改序/停用生效；锚点卡对齐；SRT 原文库导入完成 |
| **M3（8-11天）** 记忆+引用 | 待确认池、L1-L4 记忆、组合一致性总检+组合报告、**引用溯源核对（质检一键对证）**、备稿库导入、同类多段并行 | 打回意见确认后注入；组合器抓真实矛盾；引用核对 1 次实操 |
| **M4（12-14天）** 打磨 | 导图 OCR、多天连续、跨稿对账自动化、rerank 开关、画布体验、模板库 | 连续 3 天稿、跨稿 0 漏项 |

## 10. 风险与红线（v4 增量）

1. **Embedding 隐私**：素材涉敏（成人内容），默认本地 BGE-M3 离线向量化，数据不出本机；用 API embedding 是显式可选
2. **分块质量**：SRT 字幕断句合并是关键（按时间戳间隙+语义完整句切），分块错误会在检索测试页暴露，可手动调整块大小参数
3. **引用防编造**：Agent 引用必须带来源块，质检核对；查无来源的"事实"= FAIL
4. **失败不静默**：任何"重试解决不了"的失败必须转人工提醒，绝不自动跳过/假装成功；人工修复原因沉淀进记忆（防同类失败反复）
5. 其余红线不变：导图待确认清单、口径不沉淀、质检报告对证正文、组合器不擅改内容、画布快照、停用连锁

---

**待确认（1 个问题）**：
- 26 个预置标签里，★核心 13 个之外的可选标签（转场/预告/见证/冷知识/共鸣/安全提示/产品回指/情绪/氛围/答疑/双主播/毛边/仪式）需要保留哪些？还是全部预置（可以停用不显示）？