Files

T

yi 72fc5b47c7 docs: add architecture, workflow and delivery documents

2026-09-16 19:06:19 +08:00

19 KiB

Raw Blame History

雅文内容创造工作台 · 设计文档 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 增量）

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

待确认（1 个问题）：

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

19 KiB Raw Blame History Unescape Escape