# 小说写作

**Repository Path**: xpcode123/crafting-novels

## Basic Information

- **Project Name**: 小说写作
- **Description**: 用来写小说的项目
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# crafting-novels · 中长篇小说写作工作流

基于 CrewAI 的中文小说写作项目：**5 阶段 + 3 个人工检查点**，本地 Ollama 或远程 OpenAI 兼容 API 驱动，文件式断点续跑，逐章复审保一致性。

## 工作流

```
[1]世界观设定 ⏸ → [2]主线叙事 ⏸ → [3]分章大纲 → [4]逐章写作+复审 → [5]全书复审 ⏸
```

⏸ = 检查点，跑到这里停下，产物落盘，等你人工审阅（可直接编辑文件），满意后再 `crewai run` 继续。

## 前置条件

- **Python 3.12**（`uv sync` 会自动准备）
- **LLM 后端**：本地 Ollama，或任意 OpenAI 兼容 API
- **crewai CLI**：`conda activate crewai`，或 `uv tool install crewai`

## 安装

```bash
conda activate crewai
cd crafting-novels
uv sync                 # 装依赖（首次较慢，含 chromadb/onnxruntime）
```

## 配置模型（`.env`）

```
OPENAI_API_BASE=http://localhost:11434/v1   # 本地 Ollama
OPENAI_API_KEY=ollama
OPENAI_MODEL_NAME=qwen2.5:7b                # 改这行切模型
```

**换模型只改 `.env`，代码不动。** 远程后端同理，例如：

```
OPENAI_API_BASE=https://your-api-host/v1
OPENAI_API_KEY=sk-xxxxxxxx
OPENAI_MODEL_NAME=deepseek-xxx
```

## 运行

```bash
crewai run
```

- 首次：交互式问书名/主题/目标/章数/每章字数，生成 `output/<书名>/config.yaml`，然后从世界观阶段开始。
- 之后每次 `crewai run` 推进到**下一个检查点**就停：

| 次数 | 跑什么 | 产物 |
|---|---|---|
| 第 1 次 | 世界观设定 | `worldview.md` ⏸ |
| 第 2 次 | 跳过世界观 → 主线叙事 | `main_plot.md` ⏸ |
| 第 3 次 | 跳过世界观+主线 → 大纲+逐章写作+全书复审 | `outline.json` / `chapters/*.md` / `review.md` ⏸ |

反复 `crewai run` 即从断点续；产物文件存在就跳过，可直接编辑干预结果。

## 常用操作

```bash
# 切换模型：改 .env 的 OPENAI_MODEL_NAME（无需改代码）

# 阶段重跑（清该阶段及之后产物，强制重来）
BOOK_START_STAGE=main_plot crewai run   # 从主线重生成
BOOK_START_STAGE=write    crewai run     # 重写全部章节
BOOK_START_STAGE=review   crewai run     # 只重新出复审报告

# 单章重写（只重写第 N 章到末章，前 N-1 章保留，保一致性）
BOOK_START_CHAPTER=2 crewai run

# 频率限制（每次 crew 触发前等待，防 API 限流；默认 3 秒，设 0 关）
BOOK_CALL_DELAY=3 crewai run

# 指定某本书（多本并存时）
BOOK_ID=书名 crewai run
```

## 产物结构

```
output/<书名>/
├── config.yaml          规模配置（可手改章数/字数）
├── worldview.md         [1] 世界观设定      ⏸ 可编辑
├── main_plot.md         [2] 主线叙事        ⏸ 可编辑
├── outline.json         [3] 分章大纲
├── chapters/NN_*.md     [4] 各章正文
├── audits/NN_audit.json [4] 各章复审结论
├── facts.json           [4] 累积事实（人物/设定/进展，保前后一致）
└── review.md            [5] 全书复审报告    ⏸
```

**关键设计**：文件存在即视为该阶段已完成，可手动编辑 `worldview.md`/`main_plot.md`/`outline.json` 干预结果，下一次运行沿用你的修改。

## 项目结构

```
src/crafting_novels/
├── main.py              Flow 调度（5 阶段 + 断点续跑 + 节流 + 重跑控制）
├── config.py            配置加载 / 后端探测 / 交互建书
├── storage.py           产物读写 + purge_from + purge_chapters_from
├── llm.py               统一 LLM 工厂（改 .env 切模型）
├── types.py             数据结构（BookState/BookConfig/ChapterAudit...）
└── crews/
    ├── worldbuilding_crew/      [1] 世界观设定
    ├── main_plot_crew/         [2] 主线叙事
    ├── outline_book_crew/      [3] 分章大纲
    ├── write_book_chapter_crew/[4] 写单章正文
    ├── chapter_audit_crew/     [4] 逐章复审 + 事实提取
    └── final_review_crew/      [5] 全书复审
```

## 详细文档

- **`docs/验证指南.md`** —— 完整运行/验证手册（含实测记录、切换模型、重跑、故障排查）
- **`docs/superpowers/specs/`** —— 设计 spec

## 一致性如何保证

第 4 阶段每章流水线：写（注入世界观+主线+本章大纲+前文事实）→ 复审（判是否偏离主线/前文，同时提取本章人物/设定/进展）→ 偏离则带反馈重写，最多 3 次。每章事实累积进 `facts.json`，供后续章节引用——长篇不靠塞全文，靠累积事实摘要防失忆。串行执行，顺序天然保一致。