yawan-workbench/设计文档v2.md

# 雅文内容创造工作台 · 设计文档 v2（B 方案·独立 Web 工作台）

> 日期：2026-08-25 ｜ 状态：方案确认稿 ｜ 技术路线：独立 Web 应用（FastAPI + SQLite + React）
> v1 → v2 变更：① Agent 注册中心（可自建 Agent，数量不限）② 记忆沉淀需人工确认（待确认池）③ 锚点卡上下文契约（解决段间互不知情的连贯性问题）④ 组合 Agent 升级为"拼装+一致性总检+打回路由"

---

## 1. 项目概述

一个**独立运行的 Web 工作台**（浏览器访问，本地部署），核心是"多 Agent 内容工厂"：

- 你只需要：输入主题/导图/框架 → 主控 Agent 自动拆解派单 → 各环节 Agent 生产 → 4 道质检 → 人工审查 → 组合交付
- **Agent 可以自己随便添加**：预置 7 个环节 Agent + 4 个质检 Agent + 2 个服务 Agent，任何时刻你都可以新建/复制/停用 Agent，把它编进流水线
- **记忆沉淀必须你点头**：所有"AI 想记住的东西"先进待确认池，你确认了才写进对应 Agent 的记忆库
- **连贯性有双保险**：生成时传锚点卡对齐 + 组合时一致性总检，发现问题打回原段，不糊弄

## 2. 需求 → 设计对策映射（v2 完整版）

| # | 你的要求 | 设计对策 | 状态 |
|---|---|---|---|
| 1 | 很多个 Agent 组成 | 预置 13 个 Agent，可自由添加 | v2 升级：注册中心 |
| 2 | 每个 Agent 可设置规则 | 每个 Agent 一个 `rules.md`，工作台内可视化编辑，版本历史可回滚 | ✅ |
| 3 | 上下文隔离 | Agent 间不共享对话，只传结构化契约：任务切片 + 上游锚点卡 | v2 升级：锚点卡 |
| 4 | 知识库共用 | 只读共享知识库（6 库），所有 Agent 可检索、不可写 | ✅ |
| 5 | 哪里不对改哪里 | 打回粒度=段产物；三种修改路径（打回/改规则/直接改） | ✅ |
| 6 | 给主 Agent 主题/导图即可 | 主控解析→任务单→自动派发（按依赖分波次）→跟踪→汇总 | v2 升级：波次调度 |
| 7 | 每件产物都有质检 Agent | 4 道质检闸（结构/内容/风格尺度/跨稿），产物生成即检 | ✅ |
| 8 | 质检过还要人工审查 | 人工审查台=硬关卡，质检全过≠交付 | ✅ |
| 9 | 组合成一篇直播文稿 | 组合 Agent：拼装+一致性总检+六色 docx | v2 升级：总检职责 |
| 10 | Agent 自主学习、越用越懂 | 每 Agent 独立记忆库（L1-L4），**写入需人工确认** | v2 升级：待确认池 |
| 11 | 记忆库隔离 | 记忆按 Agent 命名空间物理隔离 | ✅ |
| 12 | **Agent 可自添加、数量不限** | Agent 注册中心：新建向导/复制/停用/版本管理；流水线自由编排 | 🆕 |
| 13 | **沉淀先人工确认** | 所有沉淀建议→待确认池→人工确认→写入；拒绝可屏蔽 | 🆕 |
| 14 | **段间连贯性** | 锚点卡（生成时对齐）+ 组合器一致性总检（兜底） | 🆕 |

## 3. 系统架构总览（v2）

```
┌────────────────────────── 你（浏览器访问工作台） ──────────────────────────┐
│  输入：主题/导图/框架  ·  管理：Agent注册中心/流水线编辑  ·  审查：质检+记忆确认 │
└───────┬──────────────────────────────────────────────────────────────────┘
        ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        Agent 注册中心（可自建）                          │
│  ├─ 预置生产Agent：开场/心法/技法/场景/产品/收尾/互动标记                  │
│  ├─ 预置质检Agent：结构/内容/风格尺度/跨稿                               │
│  ├─ 预置服务Agent：产品顾问/风格顾问                                    │
│  └─ 你新建的任意 Agent（向导：名称/职责类型/规则/输入来源/记忆库自动开）   │
└──────────────────────────┬─────────────────────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────────────────────┐
│                流水线编排器（Pipeline，DAG 依赖图）                      │
│  主控Agent：解析导图→任务单→按依赖分波次派发→跟踪→汇总                    │
│  波次1：开场段、服务Agent预热     波次2：心法段、技法段（读开场锚点卡）     │
│  波次3：场景段、产品段（读心法/技法锚点卡）  波次4：收尾段（读全部锚点卡）  │
└──────┬─────────────────────────────────────────────────────────────────┘
       ▼ 每波次完成后
┌────────────────────────────────────────────────────────────────────────┐
│  [段Agent]（每段独立会话/独立记忆库）──产出──▶ 段产物 + 锚点卡AnchorCard │
│       ▲   │                                    │                       │
│       │   ▼                                    ▼                       │
│  打回重跑 ◀── 4道质检闸（结构/内容/风格尺度/跨稿）──▶ 质检报告            │
│       ▲                                                     │          │
│       │                                                     ▼ 全过     │
│  ┌────┴──────┐                                        ┌──────────────┐ │
│  │ 人工审查台 │◀── 逐段：产物+质检报告+锚点卡 ──────────│ 记忆待确认池   │ │
│  │ ✅通过/🔁打回│（打回意见→记忆建议，等你确认）           │ 沉淀建议→你确认│ │
│  └────┬──────┘                                        └──────────────┘ │
│       ▼ 全部通过                                                       │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 组合Agent：时间轴拼装 → 一致性总检（矛盾/回指/时间线/情绪曲线/钩子） │   │
│  │ → 不一致打回原段（带位置） → 微衔接缝合（必须标记） → 六色docx      │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────┘
        ▼
📄 直播文稿.docx（六色标记）+ 组合报告（衔接处理清单）+ 待确认清单
```

## 4. Agent 注册中心（🆕 核心变更 1）

### 4.1 三种 Agent 类型

| 类型 | 干什么 | 例子 | 是否参与流水线 |
|---|---|---|---|
| 生产 Agent | 生成一段内容 | 开场段、心法段、你自己建的"弹幕互动段" | ✅ 是流水线节点 |
| 质检 Agent | 检查某类质量 | 结构质检、合规质检 | ✅ 挂在每个段产物上 |
| 服务 Agent | 只读供给素材/标准 | 产品顾问、风格顾问 | 后台被调用 |

### 4.2 新建 Agent（向导式，5 步，几分钟完成）

```
1. 基本信息：名称 / 描述 / 图标 / 类型
2. 职责定义：这个 Agent 负责生成/检查什么（一句话职责）
3. 规则编辑：自动生成 rules.md 模板 → 你直接写规则（支持 Markdown）
   （预置常用规则片段库：开场降档/技法快准狠/一产品一概念/色情小说档…一键插入）
4. 输入来源：从哪个上游读锚点卡（可多选）/ 需要哪些知识库（勾选）
5. 确认创建：自动创建独立记忆库 + 工作目录 + 测试按钮（拿一段样稿试跑）
```

- **复制**：右键现有 Agent → 复制 → 改名改规则（想做个"青蛇白蛇段Agent"就复制"场景段Agent"改规则）
- **停用/启用**：停用的 Agent 不进派单池，历史产物保留
- **版本管理**：规则每次保存记版本，可回滚，可对比 diff
- **数量无上限**：Agent 表就是普通数据库表，加多少都行

### 4.3 Agent 的能力标签

每个 Agent 挂标签（心法/技法/产品/场景/收尾/质检-结构/…），主控派单时按"任务单段类型 → 匹配标签的 Agent"选择执行者。同一类型有多个 Agent 时可选（或轮流）。

## 5. 流水线编排（🆕 核心变更 2）

- **默认流水线**（预置）：开场 →(依赖) 心法/技法 →(依赖) 场景/产品 →(依赖) 收尾 → 组合
- **你可以编辑**：流水线编辑器（拖拽/列表）里加节点、删节点、改依赖关系、改执行顺序
- **调度逻辑**：主控把任务单段映射到流水线节点，按**依赖图分波次（wave）执行**——无依赖的段并行跑，有依赖的段等上游完成后跑
- 每个节点配置：执行 Agent、输入来源（读哪些上游的锚点卡）、质检要求（挂哪几道质检）

## 6. 上下文契约机制（🆕 核心变更 3）—— 回答"段间互不知情"的问题

### 6.1 锚点卡 AnchorCard（每段产物自动附带）

```json
{
  "segment_id": "seg-02",
  "agent": "segment_xinfa",
  "title": "心法·女人如水",
  "core_concepts": ["女人是水，男人是火", "先把自己叫湿了"],
  "techniques": [],
  "products_ref": [],
  "golden_lines": ["所有的性感都不是天生的"],
  "emotion_tone": "温柔引导型（低声区）",
  "ending_hook": "水要养，亲水先热",
  "key_facts": []
}
```

- 每段产物生成后，由产出 Agent 自动提炼锚点卡（或主控提炼）
- **下游 Agent 只读上游锚点卡**（一页摘要），不读全文、不共享对话——隔离不破，连贯性有保障
- 锚点卡同时是质检的"对照物"：质检核对产物与锚点卡是否一致（防锚点卡撒谎）

### 6.2 依赖规则（默认，可改）

| 下游段 | 必读锚点卡 | 为什么 |
|---|---|---|
| 心法段 | 开场段 | 心法要接住开场的情绪落差 |
| 技法段 | 心法段 | 技法兑现心法埋的钩子 |
| 场景段 | 心法段+技法段 | 场景要用已教的技法做戏 |
| 产品段 | 技法段 | 产品挂靠已展示的痛点技法（卖点前必有痛点技法展示） |
| 收尾段 | 全部 | 收尾钩子=次日真实框架+本场回指 |

## 7. 组合 Agent（升级：拼装 + 一致性总检 + 打回路由）

### 7.1 拼装
按任务单时间轴把各段拼接（每段标题带时间标注、大块灰字分隔），复用六色标记 docx 引擎（宋体 10.5pt、段落自然合并 85-110 段）。

### 7.2 一致性总检（组合器新增核心职责，5 项）

| 检查项 | 查什么 | 不过怎么办 |
|---|---|---|
| 跨段矛盾 | 概念/数据/说法前后打架（阈值高 vs 低） | 打回对应段 |
| 回指断裂 | 前面提到的技法/产品/金句，后面引用对得上 | 打回引用段或定义段 |
| 时间线打架 | 段标题时间标注与任务单、与段内叙述一致 | 打回该段 |
| 情绪曲线断裂 | 全稿情绪走势（低谷→峰值→信念收尾）连贯 | 打回问题段 |
| 钩子兑现 | 段 N 结尾钩子 = 段 N+1 实际内容；收尾钩子=次日预告 | 打回 |

### 7.3 处理原则：打回 > 缝合

- 结构性不一致 → **打回原段重跑**（组合器永不擅自改内容）
- 微小衔接（两段交界缺个过渡句）→ 组合器做"缝合编辑"，但**缝合处必须标记**（蓝色【B】+ 组合报告里列"衔接处理清单"给你看）

### 7.4 组合报告
交付时附带：`衔接处理清单`（哪些原样拼接/哪些缝合/哪些打回过）、时间压缩决策、跨稿对账结果、待确认项。

## 8. 质检体系（4 道闸，不变，细节见 v1 第 4.4）

| 闸 | 检查 | 产物 |
|---|---|---|
| ① 结构质检 | 硬伤/笔误/结构残留/时间轴 | 质检报告（逐条对证正文） |
| ② 内容质检 | 痛点技法展示/一产品一概念/技法密度/为什么铺垫 | 同上 |
| ③ 风格尺度质检 | 色情小说档词清单/禁词清零/反问句归零/表演标记 | 同上 |
| ④ 跨稿质检 | day N-1 预告兑现/价格术语/产品台账 | 同上 |

质检报告格式、打回路由与 v1 相同；新增：质检报告核对锚点卡一致性。

## 9. 人工审查台（硬关卡 + 记忆确认面板）

### 9.1 逐段审查视图
- 左：段产物全文（表演标记灰色显示）
- 右：该段质检报告（红绿灯）+ 锚点卡 + 时间轴位置
- 操作：✅ 通过 / 🔁 打回（写意见，意见自动生成"记忆建议"进待确认池）/ ✏️ 直接改（改动标记）

### 9.2 记忆确认面板（🆕 核心变更 4）
```
┌─ 待确认池（记忆建议）─────────────────────────────┐
│ #3 建议沉淀：技法段Agent ← 打回意见               │
│   "技法讲解前必须先给'为什么'铺垫1-2句再进干货"    │
│   来源：2026-08-day4 打回#2 ｜ 类型：L3偏好        │
│   [✅ 确认沉淀] [❌ 拒绝] [🚫 拒绝且屏蔽同类]       │
│ #4 建议沉淀：质检Agent ← 质检FAIL                 │
│   "本场高频错误：'养护'字样残留"                   │
│   [✅ 确认沉淀] [❌ 拒绝]                          │
└──────────────────────────────────────────────────┘
```
- 任何沉淀（打回意见/质检模式/你的规则改动）**都先进池子**
- 确认 → 写入对应 Agent 记忆库（独立命名空间）；拒绝 → 丢弃；"屏蔽同类" → 该来源类型不再建议
- 池子可批量操作（连过 5 条）

### 9.3 组合终审
组合完成后你还要过一遍全文（组合 Agent 的报告+全文），确认后才是最终交付。质检→人工→组合→人工终审，四道关卡。

## 10. 记忆系统（v2：人工确认版）

| 层 | 内容 | 来源 | 写入方式 |
|---|---|---|---|
| L1 规则 | 你显式改的规则 | 你编辑 rules.md | 直接写入（你改的就是规则） |
| L2 纠错 | 质检错误模式 | 质检 FAIL 自动生成建议 | **待确认池→你确认** |
| L3 偏好 | 打回意见/审查意见 | 打回时自动生成建议 | **待确认池→你确认** |
| L4 成功 | 通过稿复盘 | 你主动触发 | 你触发才生成建议，再确认 |

红线不变：只沉淀"怎么讲"（打法/结构/风格/质检标准），不沉淀"讲什么"（价格/头衔/技法名/场次性口径）；记忆条目带来源标签可追溯。

## 11. 数据模型（v2 核心表）

```sql
agents            -- Agent 注册中心
  id, name, type(production|qc|service), status(active|disabled),
  tags, rules_version, memory_namespace, created_at, version_history(json)

pipelines         -- 流水线定义
  id, name, nodes(json: [{agent_id, depends_on[], qc_gates[], kb_tags[]}])

campaigns         -- 每次生产任务
  id, date_id, pipeline_id, mindmap_ref, task_spec(json), status, wave_state

segments          -- 段产物
  id, campaign_id, agent_id, node_id, anchor_card(json),
  artifact_path, status(pending|qc|human_review|approved|rework), version

qc_reports        -- 质检报告
  id, segment_id, gate(structure|content|style|cross), checks(json), verdict

pending_memories  -- 记忆待确认池
  id, target_agent_id, type(L2|L3|L4), content, source_ref,
  status(pending|approved|rejected|blocked)

memories          -- 已确认记忆（per-agent 命名空间）
  id, agent_id, layer(L1-L4), content, source_ref, created_at, status(active|expired)

artifacts         -- 组合产物
  id, campaign_id, docx_path, compose_report(json), final_status
```

## 12. 工作台页面规划（UI）

| 页面 | 功能 |
|---|---|
| 任务看板（首页） | 新建任务（传导图/主题）、任务列表、每任务进度（波次状态/各段红绿灯/当前卡在哪） |
| Agent 管理 | Agent 列表/新建向导/规则编辑器（含版本历史）/复制/停用/试跑按钮 |
| 流水线编辑 | 节点编排（加/删/依赖连线）、节点 Agent 指派、质检挂载 |
| 导图解析 | 上传导图 → 主控解析预览 → 读不准的词列表 → 你确认/修正 → 生成任务单 |
| 审查台 | 逐段审查（产物+质检报告+锚点卡）+ 打回/通过 + 直接改 |
| 记忆确认 | 待确认池：确认/拒绝/屏蔽 + 各 Agent 记忆浏览（只读） |
| 交付中心 | 组合报告 + docx 下载 + 历史版本 |

## 13. 技术选型（B 方案落地）

| 层 | 选型 | 理由 |
|---|---|---|
| 后端 | FastAPI (Python) | 你环境 Python 3.14 可用；FastAPI 开发快、异步适合并行调 Agent |
| 数据库 | SQLite + SQLModel | 单机部署零运维；一张库文件可备份迁移 |
| Agent 引擎 | DeepSeek API（可配置多 provider） | 你已有 DeepSeek 密钥；后续可换 |
| 知识库 | 文件系统 + SQLite FTS5 全文检索 | 素材是本地文件（SRT/docx/md/chunks.jsonl），先做索引+BM25；后续可加向量 |
| 前端 | React + Vite + 看板组件 | 交互密集（拖拽/红绿灯/编辑）；本地起 dev server |
| 产物 | 文件系统 + 元数据入库 | docx 引擎复用 make_color_docs.py 逻辑（改为工作台内生成） |
| 部署 | 本机 `uvicorn` 服务，浏览器访问 localhost | 单用户；后续可加登录 |

## 14. 里程碑（2 周，4 阶段，每阶段可验收）

| 阶段 | 内容 | 验收标准 |
|---|---|---|
| **M1（第1-2天）** 骨架+核心链路 | 后端骨架、SQLite 表、Agent 注册中心（新建/规则编辑）、任务创建（传导图/文字）、主控解析→任务单→顺序派发（先不做波次）、3 个预置段 Agent、结构质检 1 道、审查台（打回/通过）、组合（简单拼接+docx） | 用一天真实导图跑通：导图→任务单→3段→质检→审查→docx 全链路 |
| **M2（第3-6天）** 隔离与连贯 | 锚点卡机制、依赖图波次调度、流水线编辑器（简单版）、全部 7 个预置段 Agent、4 道质检全开 | 段间互读锚点卡生效；打回段3 不影响段1/2/4；质检报告逐条可对证 |
| **M3（第7-10天）** 记忆+组合升级 | 待确认池（记忆面板）、L1-L4 记忆库落库、组合器一致性总检（5项）+缝合标记+组合报告、知识库接入（原文库/备稿库/产品库 FTS5 检索+风格顾问/产品顾问） | 打回意见进池→确认→下次注入；组合器抓到一次真实矛盾并打回；六色 docx 规格达标（宋体10.5/段落合并/词清单验证） |
| **M4（第11-14天）** 打磨+批量 | 导图图片 OCR 接入（Windows OCR 替代路径）、多天连续任务、跨稿对账自动化（day N-1 预告→day N 兑现）、UI 打磨 | 连续跑 3 天稿子，跨稿质检 0 漏项；全程不依赖对话式操作 |

## 15. 风险与红线（继承 v1 + 新增）

1. 导图读取：读不准的词必须列待确认清单问你（不变）
2. 口径不沉淀：记忆系统只沉淀"怎么讲"（不变，且加人工确认双保险）
3. 质检报告≠事实：报告逐条对证正文（不变）+ 新增核对锚点卡
4. **锚点卡防撒谎**：锚点卡由质检核对与产物一致性，防"摘要和正文不符"导致下游被误导
5. **组合器权限边界**：只拼装+总检+缝合标记，永不擅自改内容；结构性不一致一律打回
6. 记忆噪音：待确认池挡住噪音；"屏蔽同类"防反复打扰
7. 合规底线：质检保留合规闸；防拒审信封只进后台不进正文
8. 并行与成本：波次调度天然限流（同波次并发数可配置），DeepSeek API 调用量在任务页可见

---

**待你确认（v2 只剩 2 个关键问题）：**
1. 默认流水线依赖关系（第 6.2 表：心法读开场、技法读心法、产品读技法…）符合你的生产逻辑吗？要不要调整？
2. M1 验收用哪一天的导图试跑？（建议最近一天的真实导图，边跑边把任务单/锚点卡 schema 敲实）