writer-work-flow/PRODUCT_SPEC.md

# 网文创作工作流 · 产品规格说明书（Product Specification）

> 面向中文网文作者的 AI 辅助创作工作流。**以 Web 应用形态交付**（让非技术作者零门槛使用），后端经 **LLM 网关多提供商适配** 做多 Agent 编排（Claude / DeepSeek / Kimi / GPT / Gemini 等可路由）。
> 本文档为产品规格（含问题定义、功能范围、系统架构、数据模型、接口与实施路线），评审通过后进入实现。配套 UX/UI 规格见 [UX_SPEC.md](./UX_SPEC.md)。

---

## 0. 文档状态

| 项 | 内容 |
|---|---|
| 阶段 | 方案设计（未编码） |
| 目标场景 | 中文网文（连载长篇） |
| 交付形态 | Web 应用（前端 Next.js/TS + 后端 Python/FastAPI + LangGraph 编排 + Postgres）；模型经 **LLM 网关多提供商适配**（Claude / DeepSeek / Kimi / GPT / Gemini / 通义 / GLM 等可路由可回退） |
| 优先痛点 | ① 长篇一致性 ② 伏笔追踪 ③ 文风模仿 ④ 节奏与爽点（四者并列） |
| 设计原则 | 不可变数据（记忆记录追加/保留历史，不就地覆盖）、单一职责高内聚、AI 在系统边界校验输入 |

---

## 1. 问题陈述

中文网文作者的核心痛点（调研结论，按优先级）：

1. **长篇一致性** — 写到几十万字，人物性格突变、设定遗忘、时间线矛盾。
2. **伏笔追踪** — 埋的线收不回来，缺乏"埋设→回收"的显式账本与逾期提醒。
3. **文风模仿** — AI 续写不像作者本人，机翻腔、风格漂移。
4. **节奏与爽点** — 不懂网文节奏（黄金三章、章末钩子、爽点密度），中期注水拖沓。

现有工具（NovelCrafter / Sudowrite / novel-writer / ai-novel-workspace）已解决"设定库 + 基础一致性校验 + 文风分析"，但**伏笔到期提醒**和**中文网文节奏引擎**是空白点，**长篇记忆衰减**仍是命门。本工作流聚焦这四点做深。

---

## 1.5 设计哲学：把写小说当软件工程

本工作流的内核是**把长篇创作当成软件工程来做**——先立架构、再对着规格生成、每章写完即测、全程维护单一真相源。这不是硬套：作者圈本就有一批工程化方法论（雪花写作法=自顶向下逐步求精、三幕/起承转合=架构模式、故事圈=状态机、Save the Cat 节拍表=规格清单、Story Bible=单一数据源），AI 只是把它自动化、可校验化。

### 软件工程 ↔ 写小说 映射

| 软件工程 | 写小说 | 对应模块 |
|---|---|---|
| 需求 / PRD | 立意、核心卖点、目标读者、"一句话故事" | 立项 |
| 架构设计 | 世界观、力量体系、故事结构选型 | 设定库 |
| 数据模型 / Schema | 人物卡、设定集（实体定义） | 角色生成器 + 设定库 |
| 接口契约 | 人物的动机/目标——约束行为，像 interface | 人物卡 |
| 模块分解 | 卷 → 章 → 场景（场景 ≈ 函数） | 大纲 |
| 全局状态 | 世界观 + 时间线 + 人物当前状态 | 记忆库（真相源） |
| 不变量 / 断言 | 人物不崩、设定不违例、时间线自洽 | 一致性校验 |
| 单元测试 | 每章写完即审：一致性/伏笔/文风/节奏 | 四审 |
| 依赖图 | 伏笔（埋设 → 回收），逾期 = 未满足依赖 | 伏笔账本 |
| CI / 回归测试 | 阶段性全书一致性扫描 | 一致性校验 |
| 重构 | 改稿——剧情(行为)不变，改善文笔/结构 | 改稿 |
| Lint / 风格指南 | 文风指纹 + 四级规则 | 文风模仿 + 规则积累 |
| 技术债 | 没填的坑、注水段落 | 伏笔账本 + 节奏引擎 |

### 三个命门级工程思想

1. **Spec-first，不让 AI 一口气瞎写 10 万字** — 先立架构（世界观+人物+大纲），再对着规格逐章生成。这是防"一致性崩坏"的根本（参考 novel-writer 的 Spec-Kit 范式）。
2. **单一真相源 + 纯函数** — 记忆库是全局状态，每章是 `章 = f(大纲, 选中的状态, 文风指纹)`（"选中"=确定性按需选择，非向量检索，§3.4），写完更新状态。即本文档"记忆即真相源"（§3.2）的由来。
3. **测试左移到每一章** — 一致性/伏笔/文风/节奏校验就是 CI，每章跑一遍，而非写完整本才发现崩盘。即"写完即审"四审（§4）。

### 工程化流水线（对应 §6 工作流）

```
需求 → 立项（一句话故事 + 卖点）
架构 → 世界观圣经 + 故事结构选型
建模 → 人物卡 + 群像（角色生成器批量产出）
接口 → 分卷分章大纲 + 场景清单（雪花式细化）
实现 → 逐章生成（纯函数）
测试 → 写完即审（四审 = 测试套件）
集成 → 验收 → 更新全局状态 + 伏笔账本
回归 → 阶段性全书一致性扫描
重构 → 改稿（保持剧情，改善表达）
```

---

## 2. 设计目标与非目标

### 目标
- 作者从"一句灵感"走到稳定连载，全程有记忆、有校验、有提醒。
- 每章写完即审：一致性 / 伏笔 / 文风 / 节奏四审。
- 记忆随写作渐进积累，对抗长篇上下文衰减。
- 作者始终掌控创意，AI 是"灵感增幅器 + 质检员"，不是全自动黑箱。

### 非目标（第一版不做）
- 不做多人实时协作 / 多人共编一本（先单作者多作品）。
- 不做模型微调（用提示工程 + 文风指纹注入实现文风模仿）。
- 不做内容分发 / 发布平台对接。
- 不做移动原生 App（先响应式 Web）。

---

## 2.5 功能总览（含优先级）

优先级：**P0** = MVP 必备（先跑通一章闭环）；**P1** = 核心差异化（产品价值所在）；**P2** = 体验增强。⭐ = 市面空白的差异化王牌。

> 注：优先级是**开发排序**，非痛点重要性。§0 四大痛点同等重要；一致性是 MVP 地基故列 P0，其余三者作为差异化王牌列 P1。

### 立项与设定
| 功能 | 优先级 | 说明 |
|---|---|---|
| 引导式立项 | P0 | 一句灵感 → 世界观/主角/金手指/总纲，自动建库 |
| 设定库 (Codex) | P0 | 人物卡 + 世界观结构化管理 |
| 世界观设计器 | P1 | worldbuilder 独立生成/扩展世界观、力量体系、势力、地理（立项已含基础版） |
| ⭐角色生成器 | P1 | 一句话 → 完整角色卡（背景/性格/弧光/关系），群像批量生成防雷同（§4.5） |
| 文风学习 | P1 | 上传样本 → 生成文风指纹（9 通用维 + 中文 7 维，带原文证据） |

### 写作
| 功能 | 优先级 | 说明 |
|---|---|---|
| 分卷分章大纲 | P0 | AI 排骨架；⭐提示伏笔回收窗口 |
| 整章生成 | P0 | 注入设定+文风，产出本章草稿 |
| AI 续写 / 扩写 | P2 | 卡文时贴合语气续写 |
| 章节管理 | P0 | 卷/章组织、草稿/已验收状态 |

### 四大质检（写完即审）
| 功能 | 优先级 | 说明 |
|---|---|---|
| 长篇一致性校验 | P0 | 比对历史摘要，报性格/设定/时间线冲突，标 `[CONFLICT]` |
| ⭐伏笔账本 + 到期提醒 | P1 | 追踪埋设→状态→回收窗口，逾期自动 `OVERDUE` |
| 文风漂移检测 | P1 | 每段对指纹打分，漂移段回炉 |
| ⭐中文网文节奏引擎 | P1 | 注水检测、章末钩子、爽点密度、情绪曲线 |

### 记忆与积累
| 功能 | 优先级 | 说明 |
|---|---|---|
| 章节事实摘要 | P0 | 每章沉淀客观事实，抗上下文衰减 |
| 时间线管理 | P2 | 事件→章节→时间点 |
| 设定决议记录 | P2 | 讨论过的设定决定留痕 |
| ⭐渐进式规则积累 | P2 | 审稿发现随手存为四级规则，越用越懂你 |

### 管理与底层
| 功能 | 优先级 | 说明 |
|---|---|---|
| 伏笔看板 | P1 | 一眼看开着/快到期的线 |
| 审稿报告页 | P1 | 四审结果汇总一页，作者裁决 |
| 多提供商/多模型路由 | P0 | LLM 网关：能力档位映射到 Claude/DeepSeek/Kimi/GPT 等，可换可回退（§3.3） |
| 长记忆 Prompt Caching | P0 | 稳定前缀缓存，省约 90% 重复 token |
| 确定性按需注入 | P0 | 写章只调相关设定（显式点名+主角+近况；向量检索为 P2） |
| 技能系统 (Skill 扩展) | P2 | 内置能力即 skill；支持题材模板/用户自定义/克隆改（§5.5） |

**MVP（P0）闭环**：立项 → 设定库 → 大纲 → 写章 → 一致性校验 → 验收（更新摘要+记忆），底层带多模型路由 + 缓存 + 检索。
**第二期（P1）**：上齐伏笔账本、文风指纹/漂移、节奏引擎、伏笔看板、审稿报告——即四张差异化王牌。
**第三期（P2）**：续写/扩写、规则积累、时间线、决议记录等增强项。

---

## 3. 系统架构

### 3.1 技术栈与分层

| 层 | 选型 | 职责 |
|---|---|---|
| 前端 | Next.js (React/TS) | 设定库(Codex)、章节管理、伏笔账本看板、四审报告、AI 续写交互 |
| 后端 | Python / FastAPI + LangGraph | 多 Agent 编排（写章→四审→验收 HITL）、记忆检索注入、模型路由 |
| LLM 网关 | 多提供商适配层（Anthropic / OpenAI 兼容: DeepSeek·Kimi·Qwen·GLM / Gemini） | 统一接口 + 能力档位路由 + 能力降级 + 故障回退（见 §3.3 / §3.4） |
| 存储 | **Postgres**（无向量） | 记忆真相源 + 确定性按需注入（显式+近况，抗上下文衰减）；向量检索为 P2 |

### 3.2 数据模型（记忆即真相源）

记忆从「Markdown 文件」升级为「数据库表」，但**真相源**地位不变：每次写章前按本章涉及实体检索并注入，每次验收后增量更新。

```
users(id, email, display_name, created_at)   -- 多租户主体(后续); 原型单用户 stub; projects.owner_id 指向此
projects(id, owner_id, title, genre, logline, premise, theme, selling_points, structure, created_at)  -- logline=一句话故事; premise=总纲; theme=立意; selling_points=卖点; structure=故事结构选型(三幕/故事圈)
characters(id, project_id, name, role, traits, appearance, motive, backstory, arc, speech_tics, tags, relations, first_chapter, latest_state)  -- role=定位(主角/CP/对手/导师/工具人); backstory=背景故事; arc=人物弧光; tags=人设标签/萌点
world_entities(id, project_id, type, name, rules, first_chapter, latest_state)
outline(id, project_id, volume, chapter_no, beats, foreshadow_windows)  -- foreshadow_windows=json数组(一章可关联多条伏笔回收窗口)
chapter_digests(id, project_id, chapter_no, facts, created_at)   -- 每章事实摘要，防矛盾的关键
foreshadow(id, project_id, code, title, status, planted_at, expected_close_from, expected_close_to, importance, links, progress)  -- 伏笔账本(§4.2)
style_fingerprint(id, project_id, dimensions_json, evidence_json) -- 文风指纹(§4.3)
rules(id, project_id, level, content)   -- 四级规则: global/genre/style/project
chapters(id, project_id, volume, chapter_no, content, status, version, created_at)  -- version 支持改稿回溯
chapter_reviews(id, project_id, chapter_no, chapter_version, conflicts, foreshadow_sug, style, pace, health_score, decisions, created_at)  -- 四审留痕 + 裁决, 支撑审稿历史(§4)
timeline(id, project_id, event, chapter_no, story_time, created_at)  -- 时间线: 事件→章节→故事内时间(P2; MVP 先由 chapter_digests 推导)
decisions(id, project_id, topic, decision, created_at)  -- 设定讨论决议留痕(P2)
```

**不可变原则**：摘要/伏笔状态变更**追加新行**保留历史（带 `created_at`），便于回溯"第 X 章为什么这样写"；不就地覆盖旧设定，冲突显式标 `[CONFLICT]` 待作者裁决。

> 注：上表为**创作数据**表。原型用**确定性按需注入**（显式点名+主角+近况，无向量列）；向量检索为 P2，届时再加 `embedding` 列 + 嵌入服务。`users/owner_id` 为多租户接缝，原型单用户 stub。运营/系统表（凭据/用量/技能/档位路由/jobs）见 ARCHITECTURE §3.1。

### 3.3 LLM 网关与模型路由（多提供商，不绑定单一厂商）

系统**不绑定单一 LLM 提供商**。后端经一层 **LLM 网关（Provider Adapter）** 统一调用；Agent/Skill 只声明**能力档位（tier）**，由网关按配置映射到具体「提供商 + 模型」。

**统一内部接口**（网关对上层暴露）：`input（易变内容）/ system（稳定块，可标缓存）/ streaming / 结构化输出 / 思考`（字段契约见 ARCHITECTURE §4.1）。各提供商以适配器实现：
- **OpenAI 兼容适配器**：一套覆盖 OpenAI、DeepSeek、Kimi(Moonshot)、通义千问(Qwen)、智谱(GLM) 等（多数提供 OpenAI 兼容端点）。
- **Anthropic 适配器**：Claude Messages API（独立请求形态）。
- **Gemini 适配器**：Google。

**能力档位 → 候选模型**（可在 *全局 / 项目 / 单 Agent* 三级覆盖；列首为推荐默认）：

| 档位 | 用于 | 候选模型（跨提供商，作者可选） |
|---|---|---|
| **写手档**（创意/文笔） | worldbuilder / character-gen / writer | Claude Opus · DeepSeek-V3 · GPT 高配 · Kimi · 通义 · GLM |
| **分析档**（长上下文/推理） | outliner / continuity / foreshadow / 文风指纹提取 | Claude Sonnet · DeepSeek-R1(推理) · GPT mini · Kimi(长文) |
| **轻量档**（高频廉价） | 文风漂移打分 / 节奏检测 | Claude Haiku · DeepSeek · Qwen-turbo · GLM-flash |

- **能力协商 + 降级**：并非所有提供商都支持 prompt caching / 结构化输出 / 工具调用 / 思考；网关探测能力并优雅降级（如不支持原生结构化输出 → 改 JSON 提示 + schema 校验重试）。
- **故障回退（fallback）**：某提供商限流/故障时，按档位回退到备用提供商。
- **凭据隔离**：各提供商 API Key 由后端密钥管理，按用户/项目隔离。
- **中文网文优势**：DeepSeek / Kimi / 通义 / GLM 在中文语感与成本上有优势，作者可自由路由（如写手用 Claude 求文笔、校对用 DeepSeek 降本）。

**跨提供商通用约定**：
- 思考/推理：有则启用（Claude 自适应思考、DeepSeek-R1 推理链）。
- 结构化输出：优先各家原生 JSON Schema；不支持则 JSON 提示 + 校验重试（网关统一封装）。
- 写章/续写一律 streaming（避免长输出 HTTP 超时）。
- 定价随提供商而异，由网关按 provider+model 记账。

### 3.4 为什么直连各家 API（经适配层），而非厂商 Agent 运行时/CLI

| 方案 | 是否采用 | 原因 |
|---|---|---|
| **直连各提供商 API + 自建适配/编排层** | ✅ | 多提供商可换可回退、确定性编排循环、自己路由模型与注入记忆——正是本场景 |
| 厂商无头 CLI（如 `claude -p` 等） | ❌ | Web 后端 shell-out 进程是反模式，并发/上下文/错误难管，且锁定单厂商 |
| 厂商托管 Agent 运行时（如 Anthropic Managed Agents 等） | ❌ | 托管 agent loop + 沙箱容器，本工作流不需要，且锁定单厂商 |

### 3.5 Prompt Caching —— 长记忆注入的成本命门

网文几十万字，每章注入世界观+人物卡+章节摘要+文风指纹，不缓存就每章重复烧数万 token。

> **缓存机制各家不同**（Claude 显式 `cache_control`、OpenAI/DeepSeek 自动前缀缓存、部分提供商暂无），由 LLM 网关按提供商封装；但下述「稳定前缀」原则**跨提供商通用**，不支持缓存的提供商自动跳过、不影响正确性。

- **经济性**（以支持缓存的提供商为例）：缓存读取 ≈ 0.1× 输入价（省约 90%）。
- **前缀匹配规则**（`tools → system → messages`，前缀任何一字节变化即全部失效）：
  1. **只缓存稳定内核**：世界观硬规则 + 已定型角色 + 文风指纹放 `system` 并打 `cache_control` 断点；**易变部分**（本章实体的 `latest_state`、新增角色、本章大纲）放 `messages` 末尾、断点之后注入——否则角色一新增/状态一更新就整块缓存失效。
  2. **绝不把章号/时间戳/UUID 拼进 system 前缀**——会让缓存每次失效。
  3. 记忆 JSON **排序序列化**（`sort_keys`），保证字节稳定，否则静默不命中。
  4. 作者连写一卷可用 **1h TTL** 让世界观缓存跨章存活。
  5. 用网关返回的缓存命中指标（如 `cache_read` token 数）验证；恒为 0 即存在静默失效源或该提供商不支持缓存。
  6. 记忆别全塞——确定性选择本章相关实体（显式点名+主角+近况）后再注入（兼顾成本与上下文衰减）。

### 3.6 多 Agent 编排（后端 LangGraph 示意）

```python
from llm_gateway import gateway   # 统一网关: 多提供商 + 档位路由 + 缓存/降级/回退

# 写手：写手档(默认 Claude Opus，可按配置换 DeepSeek/Kimi…) + 稳定前缀缓存 + 文风指纹
async def write_node(s):
    return await gateway.run(LlmRequest(
        tier="writer", stream=True,
        system=[Block(text=style_fingerprint + world_core, cache=True)],  # 稳定内核→缓存
        input=volatile_state + chapter_outline,                           # 易变，断点之后
    ))

# LangGraph: write ─並行→ 四审(只读, 结构化输出) ─→ collect ─interrupt→ 作者验收
# 连续性/伏笔(分析档) + 文风漂移/节奏(轻量档)
# 验收(HITL 恢复) → 单事务: 章节版本 + 伏笔账本 + 章节摘要 + 人物 latest_state
```

---

## 4. 四大核心模块设计

### 4.1 长篇一致性（实体记忆 + 校验）

**机制**
- **章节事实摘要**：每章验收时，continuity 角色提炼该章"发生的客观事实"（谁做了什么、状态变化、新增设定），追加进 `chapter_digests` 表。这是对抗上下文衰减的核心——不靠塞全文，靠塞结构化摘要。
- **实体关系（轻量知识图谱）**：人物/势力/物品以结构化条目维护（`characters` / `world_entities` 表），关键字段含 `first_chapter`、`latest_state`。
- **写前检索 + 写后校验**：
  - 写本章前：确定性选择本章涉及实体（显式点名+主角+近况），注入其最新状态。
  - 审稿时：continuity 角色比对新章与 `chapter_digests` + `characters`，输出结构化冲突清单（性格突变 / 设定矛盾 / 时间线冲突），标 `[CONFLICT]`。

**一致性 Bug 校验清单**（参考 *Lost in Stories 2026* 分类）
- 人物：性格漂移、能力前后不符、外貌/称呼不一致
- 设定：力量体系违例、地理矛盾、势力关系错位
- 时间：事件顺序倒错、跨度不合理、季节/年龄漂移

### 4.2 伏笔追踪（伏笔账本 — 差异化创新点）

现有工具最多做到 `threads.md` 列表，**没有到期提醒**。本模块做显式账本。

**`foreshadow` 表记录（示例，前端以卡片呈现）**

```yaml
code: F-012
title: 神秘玉佩
status: OPEN              # OPEN / PARTIAL / CLOSED / OVERDUE
planted_at: 8            # 埋设章号
content: 主角母亲遗物，背面有未知符文
expected_close_from: 40  # 预期回收窗口
expected_close_to: 60
importance: 主线
links: [人物:母亲, 势力:符文宗]
progress:
  - { chapter: 23, note: 符文短暂发光, status: PARTIAL }
```

**自动提醒逻辑**
- **验收后**（`POST /projects/:id/chapters/:no/accept`）扫描：当前章号 > 某伏笔 `expected_close_to` 且状态非 CLOSED → 置 `OVERDUE`，在审稿报告与伏笔看板提醒。
- **排大纲时**（`POST /projects/:id/outline`）主动提示"以下伏笔接近回收窗口，可考虑安排"。
- **审稿时**（`POST /projects/:id/chapters/:no/review`）检测本章是否意外引入新伏笔（自动建议登记）或回收了某伏笔（自动建议改状态）。

### 4.3 文风模仿（文风指纹 + 双轨打分）

**学习阶段（`POST /projects/:id/style`）**
- 上传作者 3-5 篇样本（建议 ≥5 万字）。
- 后端 **style-auditor 角色**提取**文风指纹**（提取是一次性重分析任务，走 **分析档**；后续每段漂移打分是高频轻任务，走 **轻量档**——经 LLM 网关路由，见 §3.3），维度参考 ai-novel-workspace：
  - 通用 9 维：句长分布、段落节奏、对话/叙述比、修辞密度、视角人称、情绪基调、词汇丰富度、标点习惯、节奏感。
  - 中文 7 维：文白比、四字结构频率、量词习惯、语气词、成语/俗语密度、网络用语、方言/口癖。
- **每个维度结论必须附原文引用作为证据**，存入 `style_fingerprint` 表。
- 支持增量更新（同端点传 `mode=update` 补样本合并）。

**生成阶段**
- 写本章（`POST /projects/:id/chapters/:no/draft`）时注入文风指纹作为约束。
- **双轨打分**：每段生成后 style-auditor 对照指纹打相似度分，低于阈值 → 标注漂移段落，前端可一键回炉重写。

### 4.4 节奏与爽点（中文网文节奏引擎 — 差异化创新点）

内置中文网文模板（存入 `rules` 表的 `genre` 级），这是对英文工具的降维差异。

**模板库**
- **黄金三章**：前三章必须完成的钩子（金手指亮相、冲突立起、目标明确）。
- **章末钩子**：每章结尾留悬念/反转/期待点。
- **爽点密度**：按字数设定爽点节拍（如每 2-3 千字一个小爽点，每卷一个大高潮）。
- **情绪曲线**：抑扬节奏，避免长段平铺。

**pace-checker 角色校验（审稿 `POST /projects/:id/chapters/:no/review` 内）**
- 检测注水段落（信息密度过低、重复铺陈）。
- 检测章末是否有钩子。
- 输出本章"爽点节拍图"与情绪曲线，对照模板给出节奏建议。

---

### 4.5 角色生成器（Character Generator — 直击群像痛点）

立项只生成主角；配角/群像靠这个专门工具一键生成，解决"群像刻画力不从心、配角一多就乱、人设重复"。

**输入**：一句话需求 + 世界观约束（自动从设定库读取）。
> 例："给我一个亦正亦邪的女二，和主角有宿命纠葛，出身敌对势力"

**产出：一张完整结构化角色卡**
| 维度 | 内容 |
|---|---|
| 基础 | 姓名（取名风格契合世界观）、性别、年龄、身份/职业 |
| 外貌 | 外形 + 标志性细节（疤/配饰/习惯动作） |
| 性格 | 框架落地（核心-表层-阴影三层 / 大五人格）+ 核心动机、欲望、恐惧、价值观 |
| 背景故事 | 出身、关键经历、创伤/转折点 |
| 口癖/语言风格 | 用词偏好、口头禅 → 喂给文风一致性，让对话有辨识度 |
| 人物弧光 | 起点 → 转变 → 终点（与剧情挂钩） |
| 关系网 | 自动与已有角色建边（宿敌/师徒/CP…），写入 `relations` |
| ⭐网文专属 | 角色定位（主角/CP/对手/导师/工具人）、能力契合力量体系、人设标签/萌点 |

**三个关键能力**（区别于"随便生成一段人设"）
1. **世界观一致性校验**：入库前由**编排器**追加一道 continuity 检查（非 character-gen 直接互调，符合 §5.4 "agent 经记忆库交换"），确认角色背景/能力不与既有设定、力量体系冲突。
2. ⭐**群像批量生成 + 防雷同**：一次配一组配角，自动分配差异化定位与性格，避免"一群人一个模子"。
3. **直接入库**：输出结构化卡 → 写入 `characters` 表（角色行即注入单元），立即进入写章时的确定性选择注入。关系网为行内 `relations` 冗余存储，群像批量建边时由**编排器统一维护双向边**（A↔B 同事务写两侧）。

**接口**：`POST /projects/:id/characters/generate`（前端"AI 生成角色"）；批量版传 `count` + 定位列表。走**写手档**（创意丰富度，默认 Claude Opus，可换 DeepSeek/Kimi），由后端 **character-gen 角色**执行，结构化输出经网关统一封装。

---

## 5. 多 Agent 编排

### 5.1 设计原则：单一职责 + 确定性编排

- **Agent = 一个独立的认知任务**，有自己的 system prompt、模型、约束契约（高内聚低耦合，呼应 §1.5 工程哲学）。
- **Agent = 一组带固定角色的 LLM 调用（经网关）**；由后端**编排器**确定性串联，并按档位路由到不同提供商+模型（见 §3.3 / §3.4）。
- **不是所有功能都做成 Agent**——只有需要 LLM 判断的才是 Agent：

| 类型 | 例子 | 实现 |
|---|---|---|
| **Agent（LLM 认知任务）** | 世界观设计、角色生成、写章、连续性校对、文风/节奏审查 | LLM 调用（经网关） |
| **确定性代码（非 Agent）** | 伏笔到期扫描、相关实体选择、状态写库、规则注入、缓存 | DB 查询 / 确定性选择 / 普通后端逻辑 |

### 5.2 Agent 花名册（按阶段）

**架构 / 建模阶段**
| Agent | 档位（默认模型） | 输入 | 输出 | 约束 |
|---|---|---|---|---|
| **worldbuilder**（世界观设计师） | 写手档（Claude Opus） | 立项需求 + 题材 | 世界观/力量体系/势力/地理/规则 | 内部自洽，硬规则显式标注（供后续校验引用） |
| **character-gen**（角色设计师） | 写手档（Claude Opus） | 一句话需求 + 世界观约束 | 结构化角色卡 / 群像 | 须过一致性校验，群像防雷同 |

**规划阶段**
| Agent | 档位（默认模型） | 输入 | 输出 | 约束 |
|---|---|---|---|---|
| **outliner**（大纲师） | 分析档（Claude Sonnet） | 总纲 + 伏笔回收窗口 | 分卷分章大纲 + 场景清单 | 不写正文，只定骨架与节拍 |

**写作阶段**
| Agent | 档位（默认模型） | 输入 | 输出 | 约束 |
|---|---|---|---|---|
| **writer**（写手） | 写手档（Claude Opus） | 单章大纲 + 检索到的记忆 + 文风指纹 | 章节草稿 | 不改设定，冲突需上报 |

**质检阶段（写完即审，并行）**
| Agent | 档位（默认模型） | 输入 | 输出 | 约束 |
|---|---|---|---|---|
| **continuity**（连续性校对） | 分析档（Claude Sonnet） | 草稿 + `chapter_digests` + 人物卡/世界观 | 冲突清单（结构化） | 只校验不改写 |
| **foreshadow-analyst**（伏笔分析） | 分析档（Claude Sonnet） | 草稿 + 伏笔账本 | 本章新埋/回收的伏笔建议 | 只建议，登记由作者确认（到期扫描是代码） |
| **style-auditor**（文风审查） | 轻量档（打分）/ 分析档（指纹提取） | 草稿 + 文风指纹 | 漂移段落 + 评分 | 只评不改 |
| **pace-checker**（节奏检查） | 轻量档（Claude Haiku） | 草稿 + genre 规则 | 节奏报告 | 只评不改 |

### 5.3 编排流（后端确定性串联）

```
立项 ─────────────> worldbuilder ─> character-gen      建世界观 + 群像，入库
  │
POST /outline ────> outliner                           产出分卷分章 + 场景清单
  │
POST /draft ──────> writer                             逐章生成草稿
  │
POST /review ─┬──> continuity        ┐
              ├──> foreshadow-analyst ├─ 并行四审，汇总报告
              ├──> style-auditor      │
              └──> pace-checker       ┘
  │
POST /accept ─────> 作者裁决 → 更新记忆表 + 伏笔账本 + 章节摘要 + 规则积累
                    （以上更新 = 确定性代码，非 Agent）
```

> 注：立项（`POST /projects`）只产出**基础版**世界观+主角；worldbuilder / character-gen 是**独立端点**（§6），用于后续扩展世界观与批量生成群像，并非立项时自动全跑。上图把它们画在建模阶段是逻辑归类，非单次调用链。

---

### 5.4 全局协作图与数据流

各 Agent 通过**记忆库（真相源）读写**协作，而非互相直接调用——记忆库是唯一的"集成总线"（呼应 §1.5 单一真相源）。

```
                        ┌─────────────────────────────────────────┐
                        │            记忆库（真相源 / 集成总线）        │
                        │  world_entities  characters  outline       │
                        │  chapter_digests foreshadow  style_*       │
                        │  rules           chapters                  │
                        └─────────────────────────────────────────┘
   写 ▲          读 │          读 │ 写 ▲        读 │            读 │
      │             ▼             ▼    │           ▼               ▼
 worldbuilder  character-gen   outliner   writer        四审（只读，出报告）
 (世界观)       (角色/群像)      (大纲)     (写章)    continuity/foreshadow/style/pace
                                                              │
                                          验收(确定性代码) ◀──┘ 作者裁决
                                          写回: chapter_digests / foreshadow状态
                                                / characters.latest_state / chapters.status
```

**读写矩阵**（R=读，W=写，·=无关）

| 表 \ Agent | worldbuilder | character-gen | outliner | writer | continuity | foreshadow-analyst | style-auditor | pace-checker | 验收(代码) |
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| world_entities | **W** | R | R | R | R | · | · | · | · |
| characters | · | **R/W** | R | R | R | · | · | · | W (latest_state) |
| outline | · | · | **W** | R | · | · | · | · | · |
| chapters | · | · | · | **W** | R | R | R | R | W (status) |
| chapter_digests | · | · | · | R | R | · | · | · | **W** |
| foreshadow | · | · | R (窗口) | · | · | R | · | · | **W** (状态/到期) |
| style_fingerprint | · | · | · | R | · | · | **R/W** | · | · |
| rules | · | · | R | R | · | · | · | R (genre) | W (加规则) |

> 注：矩阵只列核心记忆表；`projects`（根表）、`timeline`/`decisions`（P2）从略。`style_fingerprint` 的 W 发生在**学文风**阶段（非写章流水线）；character-gen 对 `characters` 的 R 用于建关系网与群像防雷同。

**三条关键规则**
1. **质检四审只读不写** — 它们出结构化报告，任何入库都经作者验收（确定性代码），守住"AI 是增幅器不是黑箱"。
2. **agent 之间不直接通信** — 全部通过记忆库交换，降耦合、可独立替换/升级单个 agent。
3. **写章是纯函数** — writer 只读不改设定，产出草稿；状态变更统一在验收阶段由代码完成。

---

### 5.5 技能系统（Skill 扩展 — Agent 的可插拔形态）

把 §5 的 agent 抽象成**声明式、可插拔的 skill**：内置能力与用户自定义跑在同一套机制上。工程类比——**skill = 插件/包，registry = 包管理器，内置 skill = 标准库**。

**Skill 定义（纯声明式，不含可执行代码）**
```yaml
name: 修仙力量体系生成器
description: 何时使用——需要为修仙题材设计境界/功法/灵根体系时
tier: writer                   # 能力档位(由 LLM 网关映射 provider+model)；亦可写 provider:model 锁定
system_prompt: "你是修仙世界观设计师……"
input_schema: { ... }          # 结构化输入
output_schema: { ... }         # 结构化输出，过 schema 校验
reads:  [world_entities]       # 声明式表权限（只能读这些）
writes: [world_entities]       # 只能写这些
genre:  修仙                    # 适用题材（可空=通用）
examples: [ ... ]              # few-shot
```

**Skill 分层**
| 层 | 例子 | 优先级 |
|---|---|---|
| 官方内置 | worldbuilder / character-gen / outliner / writer / 四审（即 §5 的 agent） | P0/P1 |
| 题材模板 | 修仙力量体系、言情 CP 张力检测、悬疑诡计设计、地图生成 | P2 |
| 用户自定义 | 克隆内置改 prompt，或从零写一个 | P2 |
| 社区市场 | 作者间分享/订阅 skill | P3（远期） |

**`skills` registry 表**
```
skills(id, scope, name, description, model, system_prompt,
       input_schema, output_schema, reads[], writes[], genre, owner, examples)
       -- scope = builtin / custom / community; model 字段实为 tier(档位)或 provider:model
```
后端编排器加载 skill 配置 → 按声明的 tier/prompt/schema 经 LLM 网关发一次调用（复用 §5 的 agent 机制）。

**三条安全约束**（用户 skill = 不可信输入，呼应 §10 风险）
1. **纯声明式，不可执行代码** — skill 只是 prompt + schema 配置，杜绝任意代码执行。
2. **表权限强制** — 运行时只允许访问 skill 声明的 `reads`/`writes`，越权拒绝。
3. **写库仍经验收 gate** — 自定义 skill 的产出同样要过作者验收/四审才入库，不开后门。

---

## 6. 接口与前端动作

每个阶段对应一个后端端点和一个前端按钮：

| 端点 | 前端动作 | 阶段 | 作用 |
|---|---|---|---|
| `POST /projects` | 新建作品 | 立项 | 引导式建立世界观/人物/总纲，初始化设定库与规则 |
| `POST /projects/:id/world/generate` | 设计世界观 | 立项/写作 | worldbuilder 生成/扩展世界观、力量体系、势力、地理 |
| `POST /projects/:id/characters/generate` | AI 生成角色 | 立项/写作 | 一句话生成完整角色卡，入库；批量传 `count` + 定位 |
| `POST /projects/:id/style` | 学文风 | 立项 | 学习作者文风，生成文风指纹（`mode=update` 增量补样本） |
| `GET /projects/:id/style` | 查看文风 | 立项/写作 | 读取最新文风指纹（完整 16 维 + 原文证据 + 版本号；无指纹 404） |
| `POST /projects/:id/outline` | 排大纲 | 规划 | 生成/更新分卷分章大纲，提示伏笔回收窗口 |
| `POST /projects/:id/chapters/:no/draft` | 写本章 | 写作 | 注入记忆+文风，产出本章草稿（streaming） |
| `POST /projects/:id/chapters/:no/review` | 审稿 | 审稿 | 四审并行，输出冲突/漂移/节奏报告 |
| `POST /projects/:id/chapters/:no/accept` | 验收 | 验收 | 作者裁决后更新记忆表、伏笔账本、章节摘要 |
| `POST /projects/:id/chapters/:no/refine` | 回炉 | 写作 | 仅重写指定段落（文风漂移/选中段），返回新旧对比 |
| `POST /projects/:id/rules` | 加规则 | 任意 | 审稿发现的问题/亮点随手沉淀为项目规则 |
| `GET /skills/toolbox` | 进创作工具箱 | 任意 | 列出生成器描述符（key/标题/输入表单/是否可入库/legacy 路由），前端声明式渲染卡片栅格 |
| `POST /projects/:id/skills/:tool_key/generate` | 用某生成器 | 任意 | 通用执行器：按工具的 context 策略组材料 → 按 `tier` 建网关 → 结构化预览（不写库，仅记账）。未知 key 404 / 无 provider 503 |
| `POST /projects/:id/skills/:tool_key/ingest` | 入库生成结果 | 任意 | 仅可入库工具（金手指/词条→world_entities、细纲→outline）：复用 continuity 预检 409 + 权限白名单后写库 |

**典型循环**：新建作品 → 学文风 → 排大纲 →（写本章 → 审稿 → 验收）× N

---

## 7. 渐进式规则积累

四级规则，越具体越优先：`global → genre → style → project`（`rules` 表 `level` 字段）。

作者在审稿页发现 AI 的系统性问题或亮点，用"加规则"（`POST /projects/:id/rules`）写入 `project` 级，后续生成自动遵守。规则随项目成长，AI 越用越"懂你"。

---

## 8. 差异化总结

| 能力 | 现有工具 | 本工作流 |
|---|---|---|
| 设定库 + 一致性校验 | ✅ 已普及 | ✅ + 章节事实摘要抗衰减 |
| 伏笔追踪 | ⚠️ 仅列表 | ✅ **账本 + 到期提醒** |
| 文风模仿 | ✅ 部分 | ✅ **指纹 + 双轨打分回炉** |
| 网文节奏 | ❌ 英文工具不懂 | ✅ **中文节奏引擎 + pace-checker** |
| 长篇记忆 | ⚠️ 衰减 | ✅ 写前检索 + 写后增量摘要 |

---

## 9. 实施路线（建议）

- **M1 骨架**：建**全部创作表**（含 rules，writer/outliner 读它）+ 立项 + 写本章端点 + **提供商凭据配置（至少一家）** + 前端最小界面。
- **M2 一致性**：continuity 角色 + 审稿端点冲突校验 + 章节摘要自动化。
- **M3 伏笔 + 节奏**：`foreshadow` 账本表 + 到期提醒 + 伏笔看板；pace-checker + genre 模板库。
- **M4 文风**：学文风端点（指纹）+ style-auditor 双轨打分。
- **M5 打磨**：验收全链路、规则积累、排大纲伏笔窗口提示、审稿报告页。

---

## 10. 风险与开放问题

- **上下文成本**：记忆注入要做相关性选择，避免无脑塞全量。需设计选择策略（按本章涉及实体过滤）。
- **一致性覆盖盲区**：确定性选择（显式+主角+近况）可能漏掉"久未出场又未点名"的远程回调实体，导致 AI 写出冲突——正是要防的失败。缓解：伏笔窗口关联实体强制纳入 + 按名匹配兜底 + 作者手动 pin；彻底解决靠向量检索（P2）。详见 ARCHITECTURE §3.4。
- **文风量化阈值**：相似度打分阈值需实测校准，过严会频繁回炉。
- **作者掌控权**：所有 AI 改动需经验收（`accept`）裁决，冲突标注而非自动覆盖——守住"AI 是增幅器"的边界。
- **多提供商/多模型一致性**：Agent 按档位路由到不同提供商+模型，各家在结构化输出/工具调用/缓存/思考的支持参差，网关需能力协商与降级；换提供商可能影响设定/文风表现，用「档位 + 提示约束」抹平；缓存按 `provider+model` 隔离；故障/限流支持回退。各提供商**数据合规与可用性**（境内外、隐私）需在配置层让用户/运营选择。
- **并发与限流**（多租户阶段）：多用户写章并发调用 API，需处理 429 限流（SDK 自带退避）与按用户/作品的速率配额。原型单用户阶段仅需按作品配额。
- **用户自定义 Skill 安全**（§5.5）：用户 prompt 属不可信输入——需强制纯声明式（杜绝代码执行）、表权限白名单、提示注入防护，且产出仍经验收 gate 才入库。

---

## 参考项目

- [novel-writer](https://github.com/wordflowlab/novel-writer) — Spec-Kit 范式的小说工作流
- [ai-novel-workspace](https://github.com/cminn10/ai-novel-workspace) — Skills+Agents、四级规则、文风分析
- [StoryCraftr](https://github.com/raestrada/storycraftr) — CLI 式创作工具
- DOME（arXiv 2412.13575）— 动态分层大纲 + 知识图谱记忆
- RecurrentGPT（arXiv 2305.13304）— 自然语言记忆滚动生成
- Lost in Stories（arXiv 2603.05890）— 长篇一致性 Bug 分类