Xiaoyangy/novel-studio · 上手攻略

  • 仓库：Xiaoyangy/novel-studio
  • 链接：https://github.com/Xiaoyangy/novel-studio
  • 分类：agent / AI 创作工具 / RAG / 长文本生成
  • 作者：spark
  • 更新：2026-09-09

⚠️ 读前必看：本文所有命令、版本号、文件名均直接来自仓库 README（main 分支，2026-09-08 commit 可见）与仓库卡片元数据。⚠️ 个别点已在文末「坑与注意」逐条标出：Go 版本号（README 声称 go.mod 要求 1.25.5，与已知 Go 发行版序列不一致，待核）、适配器清单中出现的 MiniMax、Mimo（未在公开生态中检索到对应一致命名，存疑）、README 截图命名时间戳 20260710/20260720（早于仓库卡片登记的"首次采集 2026-09-07"，可能为占位或文档图复用，存疑）。其它按 README 原样复述。

1. 它是什么

Xiaoyangy/novel-studio 是一个开源、本地优先的长篇小说 AI 创作引擎。它把"大纲、人物、世界状态、RAG、正文审核与返工"从容易丢失的聊天上下文，搬进可保存、可校验、可恢复的生产流水线。语言以 Go 为主（仓库卡片登记），许可 Apache-2.0，最新 release 来自仓库 main 分支（卡片"最近提交"2026-09-08）。

它不是：

  • ❌ 续写上一段的聊天壳
  • ❌ 所见即所得的桌面小说编辑器
  • ❌ 单进程自动续写器

它是：先冻结全书导航并完成整弧条件预演，让重要角色在接下来至多 3 章的窗口内独立决策、由 World Arbiter 裁决后果、Planner 出 POV 计划、seal 当前窗口，再逐章渲染、逐章审核——只有通过审核的正文和实际结果进入正史。

2. 解决什么问题

长篇创作痛点 novel-studio 的处理
角色为剧情突然降智或提前知道秘密 当前弧重要角色有稳定 Agent 身份 + 私有观察 + 结构化记忆；World Arbiter 只能裁决结果，不能改意图
大纲与正文逐渐脱节 全书章位先冻结；当前细推窗口完成跨章因果、POV 边界、承载力校验后才生成不可变章节合同
RAG 命中多但正文没用上 命中必须绑来源 + 内容摘要，先转成"事实锚点"或"写法方法"再进 sealed render packet
连载越长口吻/事实/资源越漂移 已验收正文、人物连续性、关系、资源、伏笔、世界变化都进结构化台账，下一章按权威状态恢复
返工后审了错误版本 计划、候选正文、审核、实际变化、发布全部绑定 digest 与正文 SHA-256
长任务中断只能重跑 pipeline、弧规划、候选正文、审核、发布都有 checkpoint、租约与幂等恢复
上下文与 token 失控 阶段化最小上下文 + canonical 去重 + 事件驱动角色激活 + 短期前缀缓存 + 可配置预算
生产过程黑箱 Dashboard 展示弧规划、角色 Agent、正文、RAG、调用量、成本、错误、恢复状态；不展示原始思维链

3. 快速安装

3.1 运行要求

  • macOS / Linux；Windows 用 WSL2
  • Release 安装不需要 Go；从源码运行需 go.mod 声明的 Go 版本（README 标注 1.25.5，⚠️ 存疑：当前 Go 公开稳定版未到 1.25，安装前请自行 cat go.mod 核实）
  • 至少一个可用的文本模型 provider
  • Dashboard 需要 Python 3.9+（页面资源已嵌入 CLI）
  • Embedding 与 Qdrant 为可选增强

3.2 稳定 Release 安装（推荐）

curl -fsSL https://raw.githubusercontent.com/Xiaoyangy/novel-studio/main/scripts/install.sh | sh

脚本会自动选可写目录、校验 SHA-256，必要时打印 PATH 修复命令。

3.3 源码运行（拿到 main 最新能力）

git clone https://github.com/Xiaoyangy/novel-studio.git
cd novel-studio
./scripts/run-local.sh doctor

源码模式不需预构建；scripts/run-local.sh 始终跑当前 checkout。文中 novel-studio 可等价替换为 ./scripts/run-local.sh。

3.4 Docker 入口

mkdir -p config workspace
docker compose run --rm novel-studio
docker compose run --rm novel-studio doctor --dir /workspace
docker compose run --rm novel-studio --check

Dashboard 从容器启动：

docker compose run --rm --service-ports novel-studio service start --host 0.0.0.0
# 浏览器打开 http://127.0.0.1:8765/

4. 核心用法

novel-studio 的工作流可压缩为一条主线：

Idea → Brainstorm → Architect（世界+章纲）→ Zero-init
  → Preplan（全书骨架）→ Rehearse-arc（整弧条件预演）
  → 接下来至多 3 章（角色独立决策）→ World Arbiter 裁决
  → Planner 出 POV 章计划 → Seal 当前窗口 → Promote 下一章
  → Drafter 逐章渲染 → Exact-body Review → 通过则 Accepted Canon

4.1 诊断与配置模型

novel-studio doctor        # 不调模型，只检查环境、目录、配置、Dashboard、RAG
novel-studio               # 首次直接跑会进配置向导
novel-studio --check       # 发起最小真实模型请求，验证 provider/model/fallback
  • 全局配置：~/.novel-studio/config.json
  • 项目级覆盖：./.novel-studio/config.json
  • 完整字段见 config.example.jsonc
  • 生产建议：把 roles.reviewer 路由到 DeepSeek；--draft-ai-judge 会严格校验 Reviewer 确实用 DeepSeek

4.2 创建一本书（只初始化）

novel-studio --pipeline --new-novel --init-only \
  --prompt "写一部 12 章完结的双女主都市悬疑短篇；每章 2000—2500 字"

--init-only 完成世界/人物/全书导航/初始状态后即退出，不进整弧推演、不写正文。

4.3 创建并继续（初始化后立刻进入规划与写作）

novel-studio --pipeline --new-novel \
  --prompt "写一部 12 章完结的双女主都市悬疑短篇；每章 2000—2500 字；人物边界和结局回收先在章纲中冻结"

或把完整创作合同放进文件：

novel-studio --pipeline --new-novel --init-only --prompt-file prompt.md

新项目默认写入 data/runs/<书名>。初始化后默认走：

preplan → rehearse-arc → project-all → seal → promote → render

一次 pipeline 调用最多完成下一章的渲染与验收；重复同一命令继续。

4.4 继续、查看、交付

# 从落盘证据继续下一步
novel-studio --pipeline --dir data/runs/<书名>

# 只读进度看板
novel-studio service open

# 诊断报告（不推进状态）
novel-studio --diag --dir data/runs/<书名>

短篇末章与终弧回执齐全后显式交付：

novel-studio --pipeline --dir data/runs/<书名> --stages finalize,deliver

成功后生成 output/novel/正文.md、全文终审与出版包。长篇以完整章级验收链为终态，不会冒充 exact-book 全文终审。

路径规则：--pipeline/--diag 的 --dir 指向 data/runs/<书名>；--build-rag 与 --rag-ready 指向该目录下 output/novel；Dashboard 默认扫描当前工作区 data/runs/。

4.5 阶段化控制（细推 + 封存窗口，不写正文）

novel-studio --pipeline --dir <RUN> \
  --stages preplan,rehearse-arc,project-all,seal

4.6 渲染 + 审核下一份 sealed bundle

novel-studio --pipeline --dir <RUN> --stages promote,render

4.7 RAG 索引与一致性

# 构建/刷新单本书索引
novel-studio --build-rag --dir <RUN>/output/novel

# 验证并恢复 embedding、本地向量、Qdrant 一致性
novel-studio --rag-ready --dir <RUN>/output/novel

# 只读审计全部正式/投影/候选/归档快照
novel-studio rag audit --root data/runs

# 先备份再修复正式索引并物理去重相同历史快照
novel-studio rag maintain --root data/runs --apply

4.8 角色 Agent 默认配置

{
  "character_agents": {
    "protocol": "v1",
    "scope": "active_core",
    "activation": "event_driven",
    "max_concurrency": 4,
    "max_revision_rounds": 1
  }
}

角色数没有 8 人硬上限；超出时自动分批。主角拥有贯穿全书的稳定 Agent 身份（改名/别名不创建新身份）。投影记忆只存在于当前 generation；只有正文正式验收后，实际发生且被角色感知的内容才进入长期记忆。

4.9 切窗口与"五条硬边界"

  1. 全书导航先冻结：卷/弧/章位提供方向，但不冒充各章正式计划
  2. 整弧预演 + 窗口细推：rehearse-arc 是 Architect/World Arbiter 产出的条件预演，不是角色决定或已发生事实；之后才允许 seal
  3. 正文仍逐章生产：每次只提升下一份 sealed bundle，候选正文始终在隔离目录
  4. 审核通过才进入正史：失败稿保留诊断但不污染 live canon
  5. 窗口接受 ≠ 整弧完成：窗口验收后要重算剩余弧的预演；只有原逻辑弧的全部窗口形成完整验收汇总，才能进下一弧

5. 典型适用场景

  • 多角色长篇网文/连载：需要稳定人设、跨章伏笔回收、长程记忆
  • 多 POV 群像悬疑/奇幻：World Arbiter + 角色 Agent 决策流避免"作者强行降智"
  • 带完整出版流程的短篇集：短篇范围可用 --stages finalize,deliver 一次性出 正文.md + 全文终审 + 出版包
  • 作家工作室协作：pipeline 状态、RAG 命中、成本、错误、恢复状态全在 Dashboard 上可读
  • AI 写作流程研究 / Benchmark 复现：完整 digest + SHA-256 + 验收回执便于审计

不太适合：

  • 一两百字以内的快速续写
  • 纯单线主角独白散文
  • 完全没有 API key、也不打算跑本地模型的用户（即便走 Ollama，也得先有可用模型）

6. 坑与注意

⚠️ 本节所有不确定条目都已逐条标注。

  1. Go 版本号存疑。README badge 与文中要求 Go 1.25.5，但截至 README 抓取时点（2026-09-08），Go 公开稳定版未到 1.25。从源码跑前先 cat go.mod 自行确认。
  2. 适配器清单含两个不常见名字："OpenAI、Anthropic、Gemini、OpenRouter、DeepSeek、Qwen、GLM、Grok、MiniMax、Mimo、Ollama、Bedrock、OpenAI-compatible 代理、本机 Codex CLI"。MiniMax、Mimo 在公开生态中未检索到与该 README 上下文一致的产品命名，存疑——可能是 README 自身笔误、未发布代号、占位符，或上游 PR 注入。生产选型前请直接查 provider 列表与文档。
  3. README 截图命名时间戳早于仓库卡片"首次采集"日期。截图文件含 20260710、20260720 命名，而仓库卡片登记首次采集 2026-09-07。两种可能：占位文件名复用 / README 在卡片登记前已存在；本攻略以"占位复用"为默认假设，不据此宣称功能上线时间。
  4. README 描述的是 main，不是最新 Release。新能力可能未随 release 发布；想要新能力就 git clone 跑源码。
  5. 不要并发跑同一条 pipeline，也不要手改 progress.json、候选目录、事务目录、运行时回执——这会破坏 digest/SHA 校验链。
  6. --init-only 只初始化不写正文；finalize,deliver 不会自动追加，需显式执行。
  7. Local-first ≠ 默认完全离线。即便文本模型、embedding、Qdrant 都在本地，web_research 等工具仍可能联网。不要把真实 API key 提交到仓库，优先用 api_key_env。
  8. OpenAI-compatible 代理默认不接收专有缓存参数；确认兼容后，才在 provider 的 extra 中设 "prompt_cache_params": true。
  9. 中文恢复包按 CJK token 估算裁剪，并保持合法 UTF-8 / JSON。
  10. Drafter 看不到 raw hits，render 阶段不连 live Qdrant——这是设计而非 bug；如发现"为什么 Drafter 没用上 RAG 命中"，先去审计 rag 流水。

7. 与同类对比

维度 novel-studio SillyTavern / Agnai AI 小说续写类 Web App（OpenRouter 系） 通用 agent 编排（LangGraph 等）
强项 多角色 Agent 决策 + 整弧预演 + sealed 章节合同 + RAG receipt + 完整验收链 角色卡 + 聊天 上手快、零配置 通用工作流
数据真相 落盘工件 + SHA-256 + digest 聊天记录 浏览器/云端 看实现
长程一致性 强（canonical 状态 + 长期记忆仅过审入） 中（依赖人维护 lorebook） 弱 看 prompt
离线/本地 本地优先 + 自选 provider 看前端 多数远程 看实现
透明性 Dashboard 但不展示原始思维链 聊天可见 多数可见 看实现
适配成本 中（需装 Go / Python / 可选 Docker + 配 provider） 低 低 高（要自己拼）
短篇交付 --stages finalize,deliver 直接出 正文.md + 终审 + 出版包 无 无 无

novel-studio 的差异化在于"先把大纲冻结，再做整弧条件预演，再让角色在密封窗口内决策 + 裁决，再封包 + 渲染 + 审核"——这一整套合同/收据/可恢复流水线是常见聊天壳或通用 agent 框架默认不提供的。

8. 一句话推荐

如果你要写多角色、有完整大纲、需要长程一致性与可审计生产链的 AI 长篇/网文/工作室连载，并且愿意配 Go + Python + 至少一个 LLM provider，Xiaoyangy/novel-studio 值得装来跑一次 doctor + 一个 12 章双女主短篇——跑完 --stages finalize,deliver 后那份 正文.md + 终审 + 出版包就是它的最小可行演示。

主要来源： - 仓库 README（main 分支，2026-09-08 抓取）：https://raw.githubusercontent.com/Xiaoyangy/novel-studio/main/README.md - 仓库卡片 /shared/research-kb/organized/repo_cards/3589-xiaoyangy-novel-studio.md - 仓库元信息：https://github.com/Xiaoyangy/novel-studio（Apache-2.0 · Go · 102★ · +10/周）

不确定处（已写入正文 §6）： 1. Go 版本号 1.25.5 与公开 Go 发行版序列不一致，待核。 2. 适配器清单中 MiniMax、Mimo 在公开生态未见一致命名，存疑。 3. README 截图命名时间戳 20260710/20260720 早于仓库卡片首次采集日期 2026-09-07，不据此宣称功能上线时间。 4. 其它命令、阶段名、配置键、目录布局、Dashboard 端口、文件路径均按 README 原样复述。