ainovel-cli

全自动 AI 长篇小说创作引擎。确定性引擎跑完整本书，模型在每个需要判断的位置被精确使用：Engine 按事实路由驱动 Architect / Writer / Editor 三个自主创作代理，语义裁定按需唤醒 Arbiter。从一句话需求到完整小说，全程无需人工干预。

特性

• 确定性引擎 + 多智能体协作 — Engine 按事实决策表调度 Architect / Writer / Editor 三个自主创作代理，主循环零 LLM 开销、行为可穷举测试
• 语义裁定可审计 — 选规划师、干预分诊、失败出路等判断由 Arbiter 单次调用完成，每次裁定落盘可回放。越简单越稳定，拒绝复杂编排
• Step 级断点恢复 — 每个工具执行成功后写入 checkpoint，崩溃后精确到 plan/draft/check/commit 步骤级恢复
• 卷弧双层滚动规划 — 长篇不再一次性规划全部章节。初始只规划前 2 卷弧骨架 + 第 1 弧详细章节，后续弧/卷在写作推进到时再由 Architect 展开，每次展开都参考前文摘要和角色状态，远期规划不空洞
• 相关章节智能推荐 — 每章写作时从伏笔、角色出场、状态变化、关系四个维度自动推荐相关历史章节，配合下一章预告，确保 500+ 章长篇的连续性
• 自适应上下文策略 — 根据总章节数自动切换全量 / 滑窗 / 分层摘要，支持 500+ 章长篇
• 七维质量评审 — Editor 从设定一致性、角色行为、节奏、叙事连贯、伏笔、钩子、审美品质七个维度评审，审美维度细分描写质感/叙事手法/对话区分度/用词质量/情感打动力五项，每项必须引用原文举证
• 用户实时干预 — 写作过程中随时在输入框注入修改意见（无需暂停），系统自动评估影响范围并重写受影响章节
• 可选逐章验收 — 默认仍全自动；需要精细控制时用 /review on，每次 /next 只放行一个新章节，返工和崩溃恢复不会误消耗许可
• TUI + Headless 双入口 — 既可在交互界面实时观察和干预，也可在服务器、NAS 或 CI 中无界面持续运行
• 多 LLM 支持 — OpenRouter / Anthropic / Gemini / OpenAI 等等随意切换

架构

核心设计：事实层确定，语义层自主。可枚举的状态迁移由确定性代码执行（Engine + Route）；边界清晰的判断按需咨询 LLM 函数（Arbiter）；开放式创作交给自主的 LLM 循环（Workers）。一句话概括：一个串行确定性 Engine、三个自主 Worker、少数几个按需 Arbiter 函数、一个文件系统事实层。

┌─────────────────────────────────────────────────┐
│              Host / Engine（确定性）              │
│  读 Store → Route → 直接运行 Worker → 循环        │
│  启动裁定 / 干预分诊 / 失败僵局 → 按需咨询 Arbiter  │
└────┬──────────┬──────────┬─────────────┬────────┘
     │          │          │             │
 ┌───▼────┐ ┌───▼───┐ ┌────▼────┐   ┌────▼────┐
 │Architect│ │Writer │ │ Editor  │   │ Arbiter │
 │(LLM循环)│ │(LLM循环)│ │(LLM循环)│   │(LLM函数)│
 └───┬────┘ └───┬───┘ └────┬────┘   └─────────┘
     └──────────┼──────────┘
                │ 工具调用（IO + checkpoint）
┌───────────────▼─────────────────────────────────┐
│                   Store                         │
│  Progress / Checkpoint / Outline / Drafts / ... │
└─────────────────────────────────────────────────┘

• Engine — 每轮从 Store 读事实、按 Route 决策表派发 Worker，执行决定、不参与文学判断；崩溃恢复=读 store 续跑,无会话可恢复
• Arbiter — 按需唤醒的语义裁定（选规划师、用户干预分诊、失败/僵局出路），事实进、结构化决策出，每次裁定落盘可审计可回放
• Workers — Architect / Writer / Editor 各自独立 context 的自主创作循环，通过 Store 中的工件协作
• Tools — 单文件原子 IO + 幂等重放；章节提交使用持久化 Saga + checkpoint，只返事实 JSON，不夹带指令

智能体职责

角色	职责	工具
Arbiter	语义裁定：启动选规划师、用户干预分诊、失败/僵局出路	无（单次 LLM 调用，输出结构化决策）
Architect	生成书名、小说简介、前提、大纲、角色档案、世界规则	novel_context save_book save_foundation
Writer	自主完成一章的构思、写作、自审和提交	novel_context read_chapter plan_chapter draft_chapter check_consistency commit_chapter
Editor	阅读原文，从结构和审美两个层面审阅	novel_context read_chapter save_review save_arc_summary save_volume_summary

写作流程

用户需求 → Arbiter 选规划师 → Architect 规划骨架+首弧 → Writer 逐章写作 → Editor 弧级评审
              (裁定落盘)                                     ↑                   │
                                                            ├── 重写/打磨 ◄──────┘
                                                            │
                                                     Architect 展开下一弧/卷
                                                    （参考前文摘要+角色快照）

每一步"下一个派谁"由 Engine 的 Route 决策表按 Store 事实推导（万级组合穷举测试钉死），不消耗任何 LLM 调用。

Writer 按固定顺序完成每章（写作内容完全自主，工具调用顺序严格）：

1. novel_context — 加载上下文（前情摘要、伏笔、角色状态、风格规则、相关章节推荐）
2. read_chapter — 回读前文找回语气和节奏
3. plan_chapter — 构思本章目标、冲突、情绪弧线
4. draft_chapter — 写入整章正文
5. check_consistency — 对照状态数据检查一致性（必须在 draft 之后）
6. commit_chapter — 提交终稿，落盘事实字段（arc_end / next_chapter / 反馈池等），下一步由 Engine 按 Route 决策表推导

状态迁移规则

系统内部把运行状态拆成两层：

• Phase — 大阶段，表示作品目前处于设定期、写作期还是已完成
• Flow — 当前活跃流程，表示系统此刻是在正常写作、审阅、重写、打磨还是处理用户干预

Phase

Phase 采用“只前进不回退”的规则：

init -> premise -> outline -> writing -> complete
  \-------> outline ------^
  \--------------> writing

含义：

• init — 任务已创建，尚未形成稳定设定
• premise — 已保存故事前提
• outline — 已保存大纲，可以进入正式写作
• writing — 已进入章节创作期
• complete — 全书流程结束

规则说明：

• 允许同态更新，例如 writing -> writing
• 允许前进，例如 outline -> writing
• 不允许回退，例如 writing -> premise、complete -> writing

Flow

Flow 只描述写作期内的活跃流程，允许在几个工作流之间切换：

writing   -> reviewing / rewriting / polishing / steering / writing
reviewing -> writing / rewriting / polishing / steering / reviewing
rewriting -> writing / steering / rewriting
polishing -> writing / steering / polishing
steering  -> writing / reviewing / rewriting / polishing / steering

含义：

• writing — 正常推进下一章
• reviewing — Editor 正在评审
• rewriting — 处理必须重写的章节
• polishing — 处理只需打磨的章节
• steering — 正在评估并处理用户干预

规则说明：

• 允许 writing -> reviewing，例如章节提交后触发评审
• 允许 reviewing -> rewriting/polishing/writing，由评审结果决定
• 允许 steering -> writing/reviewing/rewriting/polishing，由干预影响范围决定
• 不允许明显反常的跳转，例如 rewriting -> reviewing

这些规则现在由代码中的轻量校验统一约束，避免状态回退或跳到不合理的流程分支。

长篇滚动规划

传统方案一次规划所有章节，300+ 章时大纲空洞、节奏像赶进度。本系统采用指南针 + 视野滚动规划，模拟网文作者的真实创作流程：

初始规划                     弧结束时                      卷结束时
┌────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│ 终局方向（指南针）   │    │ Editor 弧级评审      │    │ Editor 卷级评审      │
│ 起步 2 卷，后续按需  │    │ 弧摘要 + 角色快照    │    │ 卷摘要               │
│ 第1弧详细章节       │ →  │ Architect 展开下一弧 │ → │ Architect 自主创建   │
│ 角色 + 世界观       │    │ Writer 继续写作      │    │ 下一卷 + 更新指南针   │
└────────────────────┘    └─────────────────────┘    └─────────────────────┘

• 指南针（Compass） — 终局方向 + 活跃长线 + 规模估计，每次卷边界由 Architect 更新，故事方向可随创作演化
• 按需生成 — 当前卷写完后，Architect 根据已写内容自主创建下一卷。初始规划生成 2 卷作为起步，后续卷按需生成
• 骨架弧 — 只有 goal + 预估章数，到达时再展开详细章节
• 渐进细化 — 每次展开都参考前文摘要、角色快照、风格规则，越往后写越精确
• 通用节奏模板 — 成长突破弧 / 竞技对抗弧 / 探索发现弧 / 恩怨冲突弧 / 日常过渡弧，每种弧型有参考密度和适用题材映射

长篇上下文管理

500+ 章小说采用三级摘要 + 四级压缩管线 + 智能推荐：

卷（Volume）→ 卷摘要
└── 弧（Arc）→ 弧摘要 + 角色快照 + 风格规则
    └── 章（Chapter）→ 章摘要（滑窗最近3章）

• 分层摘要 — 近处用章摘要，中距离用弧摘要，远处用卷摘要，层层压缩不丢信息
• 相关章节推荐 — 每章写作时从伏笔、角色出场、状态变化、关系四个维度反查历史章节，推荐 Writer 按需回读
• 下一章预告 — 加载下一章大纲，帮 Writer 设计章末钩子和伏笔衔接
• 弧边界检测 — 自动识别弧/卷结束，触发评审、摘要生成和下一弧/卷展开

上下文压缩管线

当对话超出模型上下文窗口时，按代价从低到高逐级压缩：

ToolResultMicrocompact → LightTrim → StoreSummaryCompact → FullSummary
     清理旧工具结果        截断长文本      store 零 LLM 压缩      LLM 摘要兜底

• StoreSummaryCompact — Writer 专用，用 store 中已有的章节摘要、角色快照、伏笔台账直接替换旧消息，零 LLM 开销
• FullSummary 小说定制 — Writer 使用面向叙事连续性的摘要提示词，明确要求保留角色状态、伏笔线索、审稿待修项、风格锚点
• 压缩后恢复包 — FullSummary 后自动注入当前章节计划、大纲和角色快照，防止 Writer 压缩后"失忆"
• 熔断器 — 压缩连续失败时自动跳过并显式告警，采用半开模式，下轮自动重试
• CJK Token 估算 — 中文 runes × 1.5，不会因为 bytes/4 低估而导致压缩触发滞后
• TUI 健康度渐变 — 上下文占用绿(<70%)→黄(70-85%)→红(>85%)实时展示

快速开始

# 一键安装（macOS / Linux，无需 Go）
curl -fsSL https://raw.githubusercontent.com/voocel/ainovel-cli/main/scripts/install.sh | sh

# 安装指定版本
curl -fsSL https://raw.githubusercontent.com/voocel/ainovel-cli/v1.2.3/scripts/install.sh | sh -s -- v1.2.3

# 或通过 Go 安装
go install github.com/voocel/ainovel-cli/cmd/ainovel-cli@latest

# 查看版本 / 更新到最新版本
ainovel-cli --version
ainovel-cli update

# 首次运行，自动进入引导流程（选择 Provider → 输入 API Key → Base URL → 模型名）
ainovel-cli

Windows 或手动安装：前往 Releases 下载对应平台的包。 安装脚本会从同一 GitHub Release 下载 SHA256 清单，校验通过后才提取并安装二进制。

Headless 模式

--headless 无需 TUI，适合在服务器、NAS、CI 或后台任务中持续运行。它不提供首次配置引导，请先运行一次 ainovel-cli 完成配置，或手动创建 ~/.ainovel/config.json。

# 使用一句话需求启动新任务
ainovel-cli --headless --prompt "写一本东方玄幻长篇，主角从边陲小城起步"

# 从文件读取需求
ainovel-cli --headless --prompt-file prompt.txt

# 在同一目录恢复未完成的任务
ainovel-cli --headless

--prompt 与 --prompt-file 只能在 Headless 模式下使用，且不能同时指定。模型流式输出写入 stdout，运行事件写入 stderr，完整运行日志保存在作品目录的 logs/headless.log。

Docker

Docker 镜像适合在服务器/NAS 上运行 headless 长任务，也可以用 -it 进入 TUI。配置和作品目录建议挂载到宿主机：

mkdir -p config workspace

# TUI
docker run --rm -it \
  -v "$PWD/config:/root/.ainovel" \
  -v "$PWD/workspace:/workspace" \
  ghcr.io/voocel/ainovel-cli:latest

# Headless
docker run --rm \
  -v "$PWD/config:/root/.ainovel" \
  -v "$PWD/workspace:/workspace" \
  ghcr.io/voocel/ainovel-cli:latest \
  --headless --prompt "写一本东方玄幻长篇，主角从边陲小城起步"

也可以用 Compose：

docker compose run --rm ainovel
docker compose run --rm ainovel --headless --prompt "写一本悬疑短篇"

进入 TUI 后，启动阶段支持两种前置交互：

• 快速开始：一句话直接进入创作
• 共创规划：与 AI 多轮对话澄清需求，右侧实时同步整理出的创作指令草稿；AI 每轮主动提供 1-3 条引导建议，可连续按数字键组合填入，编辑后发送，按 Ctrl+S 进入正式创作

两种模式最终都会收敛为同一份创作指令，再进入同一套创作引擎。

已有较长的世界设定或故事大纲时，可在欢迎页直接从文件创建新书：

/start ./outline.md

/start 会把文件全文作为初始创作要求，交给 Architect 整理为内部设定和动态大纲，不会将文件内容当成已完成章节。导入已有小说并续写仍使用 /import。

管理多本小说

每本小说绑定到启动目录，产物落在 {cwd}/output/novel/。换目录启动 = 换一本，cd 回去启动 = 自动从最近 checkpoint 恢复。配置 ~/.ainovel/config.json 全局共享，无需复制。

配置文件

首次运行时自动引导生成配置文件 ~/.ainovel/config.json。进入 TUI 后可输入 /config 新增或编辑 Provider、保存多个模型并为每个模型设置上下文窗口；保存后立即生效。/model 用于在这些已保存模型之间切换。

也可以手动创建配置文件，参考仓库根目录的 config.example.jsonc。首次引导也会复制一份到 ~/.ainovel/config.example.jsonc，方便本机离线查看。

{
  "provider": "openrouter",
  "model": "google/gemini-2.5-flash",
  "reasoning_effort": "medium",
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-xxx",
      "base_url": "https://openrouter.ai/api/v1",
      "models": [
        { "name": "google/gemini-2.5-flash", "context_window": 200000 },
        { "name": "google/gemini-2.5-pro", "context_window": 1000000 }
      ],
      "extra": {
        "user_agent": "my-client/1.0",
        "headers": { "X-Custom-Client": "my-client" }
      }
    }
  },
  "style": "default"
}

配置文件查找顺序（后者覆盖前者）

1. ~/.ainovel/config.json — 全局配置
2. ./.ainovel/config.json — 项目级覆盖（可选）

项目级 .ainovel/ 是全局 ~/.ainovel/ 的镜像：同样的结构、只是根目录从家目录换成当前项目。配置放 ./.ainovel/config.json，写作规则放 ./.ainovel/rules/*.md（详见下文「去 AI 味与自定义规则」）。该目录含密钥，已默认加入 .gitignore。

覆盖规则说明：

• 标量字段按后者覆盖前者，例如 provider、model、reasoning_effort、style
• providers 和 roles 按 key 合并，同名项内部按字段覆盖
• 未填写的字段会继承上层配置，例如项目级配置只写 base_url 时会保留全局配置中的 api_key
• 不支持用空字符串清空上层已有值；如需清空，请直接编辑更高优先级的配置文件

⚠️ provider（以及 roles.*.provider）的值是 providers 里的 key 名——一根指针，不是协议名。项目级若把 provider 切到一个全局 providers 里不存在的账号，必须在项目级同时补上该账号的凭证（api_key / base_url），否则启动会报“未配置凭证”。

providers.<name>.models 为可选模型对象列表：name 是传给 Provider 的模型名，context_window 是模型专属的上下文压缩窗口，json_schema 是原生结构化输出的三态覆盖（true 确认支持、false 确认不支持、省略则采用适配器能力）。自定义中转或能力取决于具体模型时建议明确填写。旧版字符串数组仍可读取，下一次通过 /config 保存时会规范化为对象列表。如果未配置，系统会回退为配置中已经出现过的同 Provider 模型。

上下文窗口按“模型专属值 → 旧顶层 context_window → 模型注册表 → 200K 兜底”的顺序解析。它只影响本地上下文压缩时机，不改变远端 API 的真实请求限制。

/config 只用来编辑 Provider 的定义（协议 / API Key / Base URL / 模型库），不负责“当前用哪个模型”——切换模型与推理强度请用 /model。模型列表支持 ↑↓ 选行、←→ 选字段、Enter 原位编辑模型 ID 或上下文窗口、`D