Orchestrate long-form fiction with canon governance, chapter continuity, and agent-driven writing workflows.
用设定治理、章节连续性控制与 Agent 驱动工作流，编排整本长篇小说的持续创作。
Novel Orchestrator is a structured writing engine for long-form fiction. It combines story canon governance, chapter-level continuity control, portable agent skills, and resumable workflow orchestration to support high-quality novel production.
Novel Orchestrator 是一个面向长篇小说创作的结构化写作引擎，聚焦故事设定治理、章节连续性控制、可移植 Agent Skill 与可恢复工作流编排，用于支撑更稳定、更高质量的整书创作。
- 用
story/*.md、Markdown frontmatter 与 Canon 层组织可持续演进的小说资产 - 用 portable skill runtime 连接不同 AI Agent 工具的写作技能与规则约束
- 用章节级工作流串联
plan -> draft -> audit -> revise -> canon-sync的闭环 - 用 SQLite 记录运行状态、检查点、artifact 与审校结果，支持恢复与追踪
- 用模型扫描与路由配置能力接入本机已配置的大模型环境
- 用 inspect、audit、export 等命令形成可验证、可迭代的创作流程
Novel Orchestrator 采用分层式写作引擎架构，把创作输入、Canon 记忆、技能规则、工作流编排与产出层清晰拆分。
flowchart TD
A["Story Assets<br/>story/*.md<br/>profiles/*.md<br/>stylepacks/*.md"] --> B["Canon Layer<br/>canon/*.json<br/>objective memory"]
B --> C["Skill & Rule Layer<br/>.agent/skills<br/>portable contracts"]
C --> D["Workflow Engine<br/>planner / writer / auditor / reviser<br/>context compiler / orchestrator"]
A --> D
B <--> E["SQLite State<br/>state/novel_orchestrator.db"]
D <--> E
D --> F["Outputs<br/>chapters / reports / exports / runtime logs"]
各层职责可以简单理解为：
Story Assets：承载用户真正关心的创作输入，包括题材意图、人物设定、世界观、风格约束与续写素材。Canon Layer：把长篇创作中的关键事实沉淀为可检索、可校验、可持续引用的客观设定层。Skill & Rule Layer：用可移植的 Agent Skill、写作约束与输出契约组织不同 AI 工具的协同方式。Workflow Engine：负责章节规划、正文生成、审校修订、上下文编译、任务编排与恢复执行。SQLite State：记录运行状态、任务事件、artifact 索引、检查点与审校结果，支撑可恢复闭环。Outputs：沉淀最终章节、审校报告、导出稿件与运行日志，形成可继续迭代的成果面。
- 中文用户命令手册
- 中文技术方案
- 英文技术方案
- 通用写作引擎重构方案
- Portable Skill Runtime 说明
- JSON Canon 设计
- 项目配置体系设计
- SQLite 设计
- YAML Frontmatter 设计
- Markdown 资产设计
详细命令参数、全部子命令说明、更多示例，已经统一迁移到 docs/user_cli_manual.zh-CN.md。
要求：
- Python
>=3.12
建议先确认当前 Python 版本，再安装：
python --version推荐使用虚拟环境：
python -m venv .venv
source .venv/bin/activate
pip install -e .查看 CLI 帮助：
novel --help如果当前环境还没有生成 novel 可执行入口，也可以临时这样运行：
PYTHONPATH=src python -m novel_creator.cli.app --help上面这两种方式都默认你当前激活的 Python 环境已经满足 >=3.12。
如果你只想先照着教程跑，请继续看本页。
如果你想查每个命令的完整参数、边界和更多示例，请直接看 中文用户命令手册。
建议把完整使用流程理解成下面这条主线：
novel init <project_name>- 编辑
story/*.md novel models scannovel models apply <project_name>novel run <project_name> --provider ...novel inspect <project_name>- 继续多章试跑或人工修订
novel export <project_name>
如果你是第一次使用，最稳妥的方式是先跑通“mock 一章闭环”，再切换到真实模型。
novel init book_001初始化后建议先看一眼项目状态：
novel inspect book_001最少优先编辑这些文件：
projects/book_001/story/author_intent.mdprojects/book_001/story/story_bible.mdprojects/book_001/story/style_bible.mdprojects/book_001/story/current_focus.md
最低建议：
- 在
author_intent.md写清楚你要的题材、气质、禁区和质量要求 - 在
story_bible.md写清楚主角、关键人物、主线冲突、世界边界 - 在
style_bible.md写清楚语言风格、节奏要求、禁止表达
如果这一步写得太空，后面虽然能生成，但质量通常会漂。
novel run book_001 --provider mock这一步的目标不是看文学质量，而是确认：
- 项目结构是否正常
- 工作流是否能从
plan -> draft -> audit -> revise -> canon-sync跑通 runtime/、reports/、chapters/final/是否有产物
novel inspect book_001重点看：
- 当前章节号是否推进
- 是否已有
chapters/final/chapter_001.md - 审校结果和字数检查是否正常
- Canon 是否已生成并回写
novel export book_001如果这一条能走通，说明最小闭环已经成立。
真实使用时，建议这样跑，而不是一上来就长批次连续生成：
novel models scan
novel models list
novel models apply book_001这一步会扫描本机常见配置位置，并把推荐路由写回项目。
当前重点支持的本机配置发现路径包括：
~/.codex/config.toml~/.codex/auth.json~/.claude/settings.json
novel run book_001 --provider configured然后立刻检查：
novel inspect book_001确认这几件事：
- 终稿章节是否生成
- 审校分是否正常
- 字数是否接近目标
- 设定、角色、时间线是否有明显跑偏
novel run book_001 --to chapter:3 --provider configured
novel inspect book_001这是当前最推荐的真实验证区间。
如果 3 章都能稳定承接，再继续扩到 5 章。
novel export book_001 --profile clean_manuscript_v1novel init imported_project
novel import imported_project --source ./legacy_book.md --mode continue
novel inspect imported_project
novel run imported_project --provider configurednovel init style_project
novel import style_project --source ./style_samples --mode style-only
novel inspect style_project这类导入更适合作为“补充上下文”和“风格治理输入”，不是保证一导入就等于高质量仿写。
如果你想把当前项目的 skill 直接复用到 Claude Code、Codex 等 Agent，会有两条常见路径。
novel skill compile-prompt book_001 1 writer.scene_draft这会把上下文和 prompt 产物落到：
runtime/context/runtime/prompts/
适合把编译结果直接投递到外部 Agent 会话中。
novel skill run "use skill writer.scene_draft book=book_001 chapter=1" --provider configured这条路径更适合测试 canonical skill runtime 是否正常。
新用户最需要关心的目录只有这几类：
story/：你的创作意图与设定输入outlines/：总纲、卷纲、章节 briefchapters/draft/：中间草稿chapters/final/：终稿正文reports/：审校结果canon/：系统维护的结构化事实层runtime/：上下文、prompt、response 调试产物state/novel_orchestrator.db：运行状态数据库
如果你只想把流程跑通，优先盯住：
story/chapters/final/reports/canon/
仓库里已经提供了一个真实试跑脚本：
bash scripts/run_xianxia_trial.sh它适合做：
- 受控多章连续试跑
- 检查修仙题材的 workflow 承接
- 验证字数、审校、repair 和 canon 回写链路
默认参数等价于：
bash scripts/run_xianxia_trial.sh real_trial_xianxia_five 5 configured如果你想指定项目名、章节数和 provider，可以直接传参：
bash scripts/run_xianxia_trial.sh my_xianxia_trial 3 configured使用前请先确认本机 provider 配置可被 novel models scan 正常发现。
- 先执行
pip install -e . - 或临时使用
PYTHONPATH=src python -m novel_creator.cli.app
- 先执行
novel models scan - 检查
~/.codex/config.toml - 检查
~/.codex/auth.json - 检查
~/.claude/settings.json
这通常是质量闸门生效，不一定是崩溃。
建议顺序：
novel inspect <project_name>- 查看最近章节终稿和审校报告
- 调整
story/*.md、project.yaml或模型路由 - 再决定
novel resume还是继续单章重跑
先确认：
- 至少已有一个终稿章节
chapters/final/中已有文件- 导出 profile 合法
更详细的排查与命令说明，请看 中文用户命令手册。
当前最稳定的主链路是：
- 项目初始化
- 模型扫描与应用
- 单章或 3 到 5 章的受控连续创作
inspect- Markdown 导出
当前不建议直接把它当作“整本书无人干预自动生产器”来使用。
更合适的方式，是“短批次、多复核、持续迭代”。
This repository is licensed under PolyForm Noncommercial 1.0.0.
- Noncommercial use is allowed under the license terms.
- Commercial use is not permitted without separate written permission from the licensor.
- This is a source-available noncommercial license, not an OSI-approved open source license.
本仓库采用 PolyForm Noncommercial 1.0.0 许可。
- 允许在许可证约束下进行非商用使用。
- 未经许可人单独书面授权，不得将本项目用于商用。
- 该许可证属于源码可见的非商用许可证，不属于 OSI 定义下的开源许可证。