通用小说写作引擎

这是一套本地优先的逐章小说写作流程。章节计划、人物、世界观、风格和状态保存在小说项目目录中；初稿与审稿保存在运行目录中；正文经过人工确认后才进入正式稿并更新故事状态。

当前版本提供离线 Mock Provider，也支持 OpenAI-compatible 与 Anthropic API。Codex、Claude Code 和 WorkBuddy 可以通过同一个 MCP 服务参与写作。

环境要求

• Python 3.11 或更高版本
• macOS、Windows 或 Linux

安装

从 GitHub 直接安装

python -m pip install "git+https://github.com/YinFY90/novel-engine.git"

也可以从 Releases 下载 .whl 文件：

python -m pip install novel_engine-0.1.0-py3-none-any.whl

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'

Windows PowerShell

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[test]"

创建小说项目

novel init "我的小说" --id my-novel --title "我的小说"
novel validate "我的小说"

初始化后，在 plans/ch-0001.yaml 编写章节计划，在 canon/ 中维护人物、世界观和风格。

完成一章

所有命令均可增加 --json，便于 Codex、Claude Code、WorkBuddy 或其他工具读取结果。

# 1. 组装上下文，输出中会返回 run_id
novel --json context "我的小说" ch-0001

# 2. 使用离线 Mock Provider 生成初稿
novel --json draft "我的小说" --run-id <run_id> --provider mock

# 3. 执行基础审稿
novel --json review "我的小说" --run-id <run_id>

# 4. 查看本次运行及正典差异
novel --json run-inspect "我的小说" <run_id>

# 5. 人工确认后提交正文、状态并创建快照
novel --json approve "我的小说" --run-id <run_id>

确认前，manuscript/ 和 state/ 保持不变。确认后，本次初稿写入 manuscript/<chapter-id>.md，状态提案一次写入 state/，同时在 snapshots/ 保存恢复点。同一运行重复确认会返回已有结果。

API 模式

API 模式由引擎调用已配置的模型生成初稿。密钥放在环境变量中，项目文件和运行记录不会保存密钥。

OpenAI-compatible：

export NOVEL_PROVIDER=openai-compatible
export NOVEL_API_KEY="<API key>"
export NOVEL_MODEL="<模型名称>"
export NOVEL_BASE_URL="<API 地址>"

Anthropic：

export NOVEL_PROVIDER=anthropic
export ANTHROPIC_API_KEY="<API key>"
export NOVEL_MODEL="<模型名称>"

Windows PowerShell 使用 $env:NOVEL_PROVIDER、$env:NOVEL_API_KEY、$env:NOVEL_MODEL 和 $env:NOVEL_BASE_URL 设置相同变量。

完整章节流程仍使用统一命令：

novel --json validate "我的小说"
novel --json context "我的小说" ch-0001
novel --json draft "我的小说" --run-id <run_id>
novel --json review "我的小说" --run-id <run_id>
novel --json run-inspect "我的小说" <run_id>
novel --json approve "我的小说" --run-id <run_id>

writer、reviewer、settler 的模型配置可以分别保存；当前版本的 API 自动调用用于正文写作，审稿和状态整理继续使用可检查的本地规则与章节计划。人工确认是写入正式正文和故事状态的唯一入口。

命令参数可以覆盖项目与环境配置：

novel --json draft "我的小说" --run-id <run_id> \
  --provider openai-compatible \
  --model "<模型名称>" \
  --base-url "<API 地址>"

AI 工具模式

Codex、Claude Code、WorkBuddy 使用 novel-mcp 连接同一小说项目：

1. validate_project 检查项目。
2. build_context 创建章节运行并取得 run_id。
3. AI 工具自己写正文时调用 submit_draft；使用已配置 API 时调用 generate_draft。
4. review_run 生成审稿结果和状态提案。
5. inspect_run 检查本次运行，project_status 查看当前阶段。
6. 用户明确接受正文后调用 approve_run。

三种工具的配置与项目调用规则位于：

• adapters/codex
• adapters/claude-code
• adapters/workbuddy

所有入口共用 runs/、manuscript/、state/ 和 snapshots/。适配层只提供调用规则，不保存独立状态。

查看进度

novel status "我的小说"
novel status "我的小说" --run-id <run_id>
novel run-inspect "我的小说" <run_id>

示例

examples/example-story 是一个完全虚构的最小示例，包含第一章章节计划、人物资料、世界规则、行文风格和初始状态。

可以复制整个目录，在副本中运行完整流程：

cp -R examples/example-story "示例故事"
novel validate "示例故事"
novel --json context "示例故事" ch-0001

Windows PowerShell：

Copy-Item -Recurse examples\example-story "示例故事"
novel validate "示例故事"
novel --json context "示例故事" ch-0001

项目结构

novel-project/
├── novel.yaml              # 项目信息
├── canon/                  # 已确认的大纲、人物、世界观和风格
├── plans/                  # 章节计划
├── manuscript/             # 已确认正文
├── state/                  # 已确认故事状态
├── packs/                  # 作品或类型规则包
├── runs/                   # 每次运行的上下文、初稿、审稿和提案
└── snapshots/              # 确认时生成的恢复点

项目目录可以整体复制到另一台电脑。项目内文件引用统一使用相对路径。

设计参考

本项目参考了多个开源小说写作项目的工作流设计，包括可检查上下文、文件化记忆、连续性检查、审稿与回退机制。具体项目和借鉴内容见 ACKNOWLEDGMENTS.md。本仓库的代码、示例和文档独立维护，不包含这些项目的源码或作品内容。

测试

测试只使用本地临时目录和 Mock Provider，不访问网络，也不读取密钥。

pytest

跨平台 GitHub Actions 模板位于 ci/github-actions-tests.yml。仓库管理员获得 GitHub CLI 的 workflow 权限后，可将它放入 .github/workflows/tests.yml 启用。