openNovel

openNovel 是一个用于搭建多智能体小说 / 剧本创作系统的命令行工具。

当前版本优先实现基础能力：

• 初始化工作空间。
• 管理 .env 中的模型配置。
• 检查模型连通性。
• 初始化小说状态文件。
• 提供多智能体正文生成、草稿审查、归档、游戏进度和结算确认流程。

安装

npm install -g open-novel

安装后会提供三个等价命令：openNovel、opennovel 和 open-novel。如果不想全局安装，也可以使用：

npx open-novel --help

查看帮助

openNovel --help

在其他项目中调用命令接口

所有 CLI 命令都可以从 npm 包导入调用。命令函数默认使用当前进程目录查找工作空间，也可以通过 cwd 指定工作空间目录。

import {
  runInitCommand,
  runCreateNovelCommand,
  runReviseNovelSettingCommand,
  runNewNextCommand,
  runReviewDraftCommand,
  runEntityCommand
} from "open-novel";

await runInitCommand({ cwd: "/path/to/novel-workspace" });
await runCreateNovelCommand(["主角进入午夜出现的门"], { cwd: "/path/to/novel-workspace" });
await runReviseNovelSettingCommand(["增加梦境污染机制"], { cwd: "/path/to/novel-workspace" });
await runEntityCommand("item", "create", "item_blood_key", {
  cwd: "/path/to/novel-workspace",
  json: "{\"name\":\"血色钥匙\",\"rank\":\"D\"}"
});
await runNewNextCommand({ cwd: "/path/to/novel-workspace", words: "1000" });
await runReviewDraftCommand({ cwd: "/path/to/novel-workspace", yes: true });

也可以从命令子路径导入：

import { runShowCharactersCommand } from "open-novel/commands";

初始化工作空间

openNovel init

创建小说设定

openNovel create 主角林望进入午夜出现的门，题材是成人向无限流恐怖生存小说

create 会调用已配置模型整理小说设定，写入 state/ 下的结构化初始状态，并生成 docs/novel-setting.md。后续 next 生成的所有正文内容都会优先遵循该设定文档。

create 不会把输入描述原封不动保存为设定文档；输入内容会先交给模型扩写、优化，生成围绕故事背景、世界观、基本规则、核心机制、大体方向、风格特色和禁忌等内容的创作圣经。用户没有提到的专项内容，例如游戏副本、任务、积分或物品体系，不会被强制写入设定文档。

如果当前工作空间已经存在小说内容、草稿、归档正文、游戏副本或待确认状态，create 会拒绝覆盖；如需重新创建小说，请先执行 clear novel。

修改小说设定

根据提示词修改 docs/novel-setting.md：

openNovel setting revise 增加梦境污染机制，并强化主角与旧同学的关系线

指定模型、超时和失败重试：

openNovel setting revise 增加主空间交易区规则 --model gpt --timeout 600 --retries 3

该命令会调用模型重写完整设定文档，不会把修改提示词原文直接追加进文件；如果模型返回需要同步的 worldState 字段，也会同步更新 state/world_state.json。

设置模型

openNovel set model gpt openai gpt-4.1 https://api.openai.com/v1 sk-xxxx
openNovel set model local custom qwen2.5 http://localhost:11434/v1 empty

删除模型

openNovel delete model gpt

设置真实 embedding 检索

openNovel set embedding openai text-embedding-3-small https://api.openai.com/v1 sk-xxxx
openNovel show embedding
openNovel delete embedding

配置后不会改变默认生成行为。next 默认仍使用本地稀疏向量检索；只有本次生成显式传入 --embedding 时，才会优先使用 OpenAI-compatible /embeddings 语义向量召回，服务不可用时自动回退到本地稀疏向量检索。

查看智能体

openNovel show agents

为智能体指定模型

先通过 show model 查看可选模型，再绑定到智能体：

openNovel show model
openNovel set agent MainAgent gpt
openNovel set agent CharacterAgent local

也可以省略模型别名，在交互式终端中从模型列表输入序号选择：

openNovel set agent MainAgent

未指定模型的智能体会使用 next --model 指定的本次默认模型；如果 next 未指定 --model，则使用当前模型列表中的第一个模型。next --model 不是只给 ProseWriterAgent 使用；如需只替换正文写作模型，请使用 set agent ProseWriterAgent <模型别名>。

检查模型

openNovel doctor

生成下一段小说正文

openNovel next

指定模型和目标字数：

openNovel next --model local --words 1000

指定超时和失败重试次数：

openNovel next --model local --words 1000 --timeout 600 --retries 3

本次生成启用真实 embedding 检索：

openNovel next --embedding

为本次生成提供参考信息：

openNovel next --reference "本段重点写主角发现门牌号变成自己的名字"
openNovel next --reference-file ./notes/next.md

说明：

• --timeout 的单位是秒，默认 600 秒。
• --retries 表示超时或服务调用失败后的重试次数，默认 3 次。
• --embedding 表示仅本次生成启用真实 embedding 语义检索；默认不启用，使用本地稀疏向量检索。
• --reference 和 --reference-file 可以同时使用，会合并作为本次内容大纲的参考信息。
• next 只生成草稿并写入 state/draft.json，同时把草稿正文写入 logs/<runId>/draft.md，不会直接归档。
• 当前存在草稿时不能继续执行 next，需要先审查归档或修改草稿。
• 当前存在待确认游戏结算时也不能继续执行 next，需要先执行 review settlement 确认或保留结算草稿。
• 正文生成前会由 MainAgent 基于 docs/novel-setting.md、generation packet、当前状态和本次参考信息生成内容大纲。
• 大纲会列出本次出场人物、出场物品、新人物、新物品和是否需要创建游戏副本；新人物和新物品会自动写入 characters.json / items.json。
• 如果大纲判断本段需要创建新游戏副本，next 会先调用 GameWorldAgent 生成完整副本并输出到控制台；用户确认后副本写入 state/game_instances.json 并标记为 active，用户拒绝时可输入引导信息重新生成，直接回车则按原逻辑重新生成。
• 新版 next 会依次生成大纲、初稿、正文、审查意见和美化后的最终正文；中间产物写入 logs/<runId>/。
• 第一次执行 next 时没有前文，会按小说开头处理，自然交代主角、背景、初始处境和核心悬念。
• next 是连续写作流，不要求每次生成的内容形成完整章节或剧情收尾。
• 正文生成会读取 agent_memory.narrativeContinuity.lastTail 中上一段正文尾部，要求模型从尾部最后一句之后自然续写，避免重新开头或重复前文。
• 正文生成会要求模型在目标字数附近返回内部技术结束标识；如果没有检测到结束标识，CLI 会输出每次生成 / 补全进度并继续补全，避免长文本被截断。若正文已达到目标字数附近但模型漏掉结束标识，系统会接受当前正文并停止补全。
• 正文生成前会让存活角色通过 CharacterAgent 做出行动决策，角色动作、反应和语言要有人味，不能像机器执行指令。
• 正文风格默认采用正常中文网文叙事：白话顺读、节奏快，优先用人物行动、对话、反应和信息推进；主角要有疑惑、追问、判断和当下麻烦，设定尽量通过问答、插话、打断、玩笑、吐槽、争执、补充说明或现场反应交付；严肃剧情里允许轻微生活感和熟人互动，危险感不靠抽象氛围词硬撑，避免故作深沉、说明书式设定和 AI 式辞藻堆叠。
• 生成规则支持成人向黑暗题材：可以包含服务剧情的暴力威胁、伤害后果、性张力、亲密关系、心理压迫和权力支配，但不会以色情、猎奇或越过底线的方式处理。
• 执行 review draft 后，ContinuityReviewAgent、ForeshadowingAgent 和 ContentReviewAgent 会分别给出审查结果和修改建议；ContentReviewAgent 只做语言、节奏和中文网文可读性审查，并会对送审文本做轻量脱敏，降低模型服务误拦截。用户选择不修改时，ArchiveAgent 会生成归档摘要并正式归档，同时把角色近期行动保守同步到 characters.json，保存本次正文尾部供下次 next 衔接。

审查草稿与归档

openNovel review draft

审查后会询问是否根据审查意见修改草稿。选择 y 会自动修改草稿并重新审查；选择 n 会将草稿转为正稿并归档。

选择 y 自动修改草稿时，会覆盖写入 logs/<runId>/draft.md。

非交互环境可直接归档当前草稿：

openNovel review draft --yes

正文归档后，如果系统检测到当前 active 游戏副本在本段正文中结束，会更新 state/game_instances.json 的副本运行态，并生成 state/settlement_draft.json。交互式终端会询问是否确认并应用本次游戏结算。

如果选择不确认，结算草稿会保留，副本保持 settlement_pending，后续不能继续 next，需要先审查结算草稿。

审查游戏结算

openNovel review settlement

该命令用于重新审查并确认 state/settlement_draft.json 中的待结算草稿。命令会展示副本、结束证据和结算摘要，并询问是否应用结算。

确认后会：

• 调用 SettlementAgent 生成结构化结算补丁。
• 更新人物积分、状态、物品、环境、世界状态和副本结算记录。
• 同步时间线、实体、伏笔、物品 / 能力 / 强化索引。
• 清空 state/settlement_draft.json。

也可以直接确认：

openNovel review settlement --yes

审查状态补丁

openNovel review state-patch

该命令用于审查并确认 state/state_patch_draft.json 中的待确认状态补丁草稿。命令会展示来源正文、摘要和补丁操作，并询问是否应用、拒绝或保留。

确认后会应用补丁并清空草稿；拒绝会直接清空草稿；保留则不修改任何状态。

也可以直接确认或拒绝：

openNovel review state-patch --yes
openNovel review state-patch --reject

兑换商店

生成或刷新兑换商店：

openNovel exchange shop generate --count 5

查看当前商品：

openNovel exchange shop show

为角色购买商品：

openNovel exchange shop buy char_001 shop_d_salt_lamp

说明：

• 新工作空间初始化时会自动创建一批基础物品库和初始兑换货架，覆盖前期过渡、帮助类、武器类、信息类、治疗类、逃脱类、进化路线基础物和高价目标物。
• next 生成正文草稿时，ItemAgent 会根据导演方向、角色状态、副本类型和上下文生成本轮物品供给计划；计划会写入草稿和日志，供场景蓝图与正文使用。
• 物品供给计划只有在 review draft 确认归档后才会落入 items.json，避免未确认草稿污染正式状态。
• exchange shop generate 会优先使用 ItemAgent 绑定模型；没有模型时使用保守兜底商品。
• 商店商品只能是 D、B、A、S、SR，XR 不能直接兑换。
• 购买会扣除角色积分、更新人物物品列表、更新物品持有者、移出当前货架，并写入 items.exchangeTransactions。
• 购买记录会同步到 memory/item_reinforcement_index.json，供后续长期记忆和上下文检索使用。

显式管理人物、物品和游戏副本

这些命令用于在其他客户端接入核心逻辑时，直接创建、更新或删除状态实体。实体变更会复用内部 StatePatch 校验和应用流程，写入 lastStatePatchRunId / recentStatePatches 等追踪信息。

如果物品、人物或游戏副本已经被剧情日志、草稿、待确认结算、未完成运行、长期记忆或关联状态引用，或正处于使用中状态，显式 update / delete 会拒绝执行。需要改变这类实体时，应通过正文生成、草稿审查或状态补丁流程推进，避免破坏已发生的剧情状态。

创建人物：

openNovel entity character create char_002 --json '{"name":"林望","status":"alive","points":0}'

更新人物：

openNovel entity character update char_002 --json '{"points":120,"currentGoal":"调查午夜门"}'

删除人物：

openNovel entity character delete char_002

创建物品：

openNovel entity item create item_blood_key --json '{"name":"血色钥匙","rank":"D","effects":["打开一扇被标记的门"]}'

更新物品：

openNovel entity item update item_blood_key --json '{"holderId":"char_001","tradable":false}'

删除物品：

openNovel entity item delete item_blood_key

创建游戏副本：

openNovel entity game create game_midnight_hospital --json '{"name":"午夜病栋","status":"not_started","participants":["char_001"]}'

更新游戏副本：

openNovel entity game update game_midnight_hospital --json '{"status":"active","currentStage":"一楼护士站"}'

删除游戏副本：

openNovel entity game delete game_midnight_hospital

也可以从 JSON 文件读取实体数据：

openNovel entity character create char_003 --file ./data/character.json

作为 npm 包在其他项目中调用核心接口：

import { OpenNovelEntityManager } from "open-novel";

const manager = new OpenNovelEntityManager({ workspaceRoot: "/path/to/novel-workspace" });

await manager.createCharacter({
  id: "char_002",
  data: { name: "林望", status: "alive" }
});

await manager.updateItem({
  id: "item_blood_key",
  data: { holderId: "char_002" }
});

await manager.deleteGame({ id: "game_midnight_hospital" });

修改草稿

openNovel draft revise 强化开头和上一段结尾的动作衔接，减少解释性文字

每次执行后都会覆盖写入 logs/<runId>/draft.md。

恢复最近正文为草稿

openNovel draft restore-last

该命令仅在当前没有草稿时可执行，会把最近一次正式正文移回草稿状态，并同步撤销该 runId 对角色归档状态、游戏进度、待确认结算草稿、待确认状态补丁草稿、章节文件和长期记忆索引的影响。

生成结果会写入：

state/draft.json
docs/chapters/<chapter>.md
logs/<runId>/result.md
logs/<runId>/draft.md
logs/<runId>/direction.json
logs/<runId>/contributions.json
logs/<runId>/validation.json
logs/<runId>/revision-rounds.json
logs/<runId>/character-decisions.json
logs/<runId>/character-decisions.md
logs/<runId>/scene-plan.json
logs/<runId>/item-supply-plan.json

清空小说

openNovel clear novel

该命令会重置 state/ 下所有小说状态文件，并清空 docs/chapters/ 正式章节归档，但保留 .env 中的模型配置。执行时需要二次确认。

回滚正文

openNovel rollback
openNovel rollback run_20260518T075328Z

该命令默认回滚最近一次已归档正文；传入 runId 时会回滚指定正文。它会移除对应的 plot_log 章节、docs/chapters/ 章节文件、事件和归档摘要记忆，但保留 logs/<runId>/ 运行日志。

状态巡检

openNovel status

该命令会检查当前草稿、待确认结算、待确认状态补丁、长流程中断、副本运行态、长期记忆文件、长期索引残留、章节归档文件和物品归属一致性，只输出巡检结果，不修改任何状态。

长流程运行状态

openNovel run status
openNovel run resume
openNovel run repair
openNovel run discard

• run status 查看当前是否存在未完成的 next / review draft 长流程。
• run resume 从安全阶段恢复未完成运行：已生成草稿的 next 会清理中断标记并提示进入草稿审查；如果 next 已在 logs/<runId>/result.md 生成正文但尚未写入草稿状态，会从运行日志恢复草稿；如果 review draft 已在 logs/<runId>/reviews.json、archive-summary.md 或 active run checkpoint 写入审查结果、归档摘要和章节文件路径，会复用这些产物继续流程；如果正文已进入 plot_log，会补齐长期索引、状态补丁草稿、游戏进度和结算草稿。
• run repair 根据已落地的 plot_log、章节正文、状态文件和 logs/<runId>/ 运行日志补齐缺失的长期记忆索引、状态补丁草稿、游戏进度和结算草稿；如果中断运行已经形成草稿或已完成归档，会清理遗留的 state/active_run.json 标记。
• run discard 丢弃尚未形成草稿或正式归档的中断运行，并清理本次运行创建的副本。

查看小说状态

openNovel history
openNovel history --limit 5
openNovel show characters
openNovel show games
openNovel show items
openNovel show world
openNovel show memory

这些命令用于快速查看最近剧情、人物状态、副本状态、物品体系、世界状态和长期记忆概览，不修改任何状态。

导出正文

openNovel export
openNovel export --output docs/my-novel.md

该命令会按 plot_log 中的章节顺序读取已归档正文，并导出为一份可阅读 Markdown。默认输出到 docs/openNovel-export.md。