# 通用小说写作引擎

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

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

## 环境要求

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

## 安装

### 从 GitHub 直接安装

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

也可以从 [Releases](https://github.com/YinFY90/novel-engine/releases) 下载 `.whl` 文件：

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

### macOS / Linux

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

### Windows PowerShell

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

## 创建小说项目

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

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

## 完成一章

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

```bash
# 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：

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

Anthropic：

```bash
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` 设置相同变量。

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

```bash
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 自动调用用于正文写作，审稿和状态整理继续使用可检查的本地规则与章节计划。人工确认是写入正式正文和故事状态的唯一入口。

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

```bash
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/codex)
- [`adapters/claude-code`](adapters/claude-code)
- [`adapters/workbuddy`](adapters/workbuddy)

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

## 查看进度

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

## 示例

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

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

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

Windows PowerShell：

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

## 项目结构

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

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

## 设计参考

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

## 测试

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

```bash
pytest
```

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