# novel-maker

**Repository Path**: osheyx/novel-maker

## Basic Information

- **Project Name**: novel-maker
- **Description**: AI小说- 制作家
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-30
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 小说生成家 · NovelMaker

> 高速并行的长篇小说自动生产引擎 —— 从一句话设定，到百万字成稿。
>
> A high-throughput, DAG-parallel engine that turns a one-line premise into a full-length novel.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)

NovelMaker 把「写长篇」拆解成一条工业化流水线：**立项 → 世界观 → 全书结构 → 人物 → 卷纲 → 单元纲 → 单元门审纲 → 章纲 → 正文 → AI 审稿 / 按批改修订 → 润色定稿 → 摘要 / 连贯性检查与 P0 修补**。
所有任务在一张 DAG 上**无阶段屏障地并行**——某一章的章纲一落地，正文立刻开写，不必等其它章。

## 代码与发行，两条通道

同一个 Gitee 仓库里，**代码**和**小说产物**分开走，互不触发对方的构建：

| 通道 | 载体 | 消费方 |
|------|------|--------|
| 代码 | `main` 分支 / `vX.Y.Z` tag | 开发机、CI |
| 作品发行 | 发行版 tag `novel-<书名>-vX.Y.Z` + `.tar.gz` 附件 | 服务器 |

于是：改代码只是 `git push`，服务器无感；出一本书就发一个发行版，
服务器 `curl` 下载 → 校验 → 解压 → 重启容器，**不需要 clone 仓库、不需要 Node、
不需要 `uv sync`**。

```bash
# 开发机：把当前进度发成发行版
novel release publish 太初剑主 --version 1.0.0

# 服务器：一条命令切到这一版
./scripts/deploy-release.sh --tag novel-太初剑主-v1.0.0
```

发行包是**可搬迁的只读快照**：解压到任意路径后 C 端 API 仍能读到正文
（正文路径在打包时已统一成相对形态）。完整说明见 [docs/RELEASE.md](docs/RELEASE.md)。

## 文档

完整文档在 [docs/](docs/)：

| 文档 | 内容 |
|------|------|
| [文档中心](docs/README.md) | 全部文档的分组索引与阅读路径 |
| [需求文档](docs/REQUIREMENTS.md) | 背景、产品定位、需求清单与验收标准（PRD） |
| [功能说明](docs/FEATURES.md) | CLI / 配置 / Web / API 的用户手册 |
| [技术架构](docs/ARCHITECTURE.md) | 分层、模块职责、数据模型、并发模型、部署形态 |
| [发行说明](docs/RELEASE.md) | 代码与作品分离的发行机制与服务器部署 |
| [战略](docs/STRATEGY.md) | 定位的形成逻辑、护城河、主动放弃项、AGI 小说路径 |
| [路线图](docs/ROADMAP.md) | 三阶段里程碑与每阶段出口判据 |
| [调查报告](docs/MARKET-AND-POLICY-RESEARCH.md) | AI 小说产业与政策风险，46 条一手来源 |
| [商业计划](docs/BUSINESS-PLAN.md) | 商业模式、单位经济模型、财务规划 |
| [合规手册](docs/COMPLIANCE.md) | 权属、标识、资质、平台规则的工程与制度落点 |
| [运营手册](docs/OPERATIONS.md) | 内容 SOP、IP 授权运营、数据运营、止损规则 |
| [路演材料](docs/PITCH-DECK.md) | 逐页讲稿与投资人追问应答库 |

## 特性

- ⚡ **DAG 并行流水线**：不做「分阶段等待」。关键路径从 `阶段数 × 阶段耗时` 压到 `单章耗时`，默认 32 路并发（实测可上探 48）；滑动窗口（`write_lookahead`）允许正文领先 16 章，兼顾吞吐与前后微连贯。
- 🩺 **AI 全自动质量门**：critic 审稿打分并列必改项 → writer 定向修订 → editor 润色定稿（不改情节）；story doctor 在每个剧情单元开写前审纲并 AI 调纲；continuity 检查跨章矛盾，P0 问题由写手定向修补。追求极限速度时 `--fast` 一键全关。
- 🎓 **创作技能库**：`skills/` 下 9 张工艺卡（开头钩子、冲突升级、伏笔台账、白描文字、爽点节奏、人物声口、场景、事实台账、节奏），按角色自动匹配、按预算注入提示词；沉淀新工艺只需要加一张 Markdown 卡，所有 Agent 通用。
- 🧠 **分层故事记忆**：故事圣经 → 卷纲 → 单元纲 → 本章指令 → 前章尾部 + 滚动摘要 → 伏笔台账，每章上下文都被裁剪成「刚好够用」的形状，长篇不崩。
- 📚 **一本书一份配置**：`new` 时把有效配置快照写入作品目录，设定随作品走、互不串台。
- 🔌 **Provider 抽象**：内置 `mmx` / 任意 OpenAI 兼容服务 / Anthropic / 外部 Agent CLI / `mock` 五类适配器。接入新模型只需在 YAML 里加一段。
- 🔁 **自适应并发调度**：指数退避重试、429 限流处理；推理模型思考预算烧光时自动加预算重试；连续失败自动降并发，恢复后缓慢升回。
- 💾 **SQLite 持久化 + 断点续跑**：每个阶段产物都落库，随时 `Ctrl-C`，重跑同一条命令即接着写。
- 📦 **多格式导出**：`txt` / `md` / `json`。

## 流水线总览

```
concept → world → architect → characters
                         │
                         ├─ vol(v) ─ arcs(v) ─ gate(v,a)  ← story doctor 审纲/调纲
                         │                        │
                         │                  plan(n) ── write(n) ── review(n)
                         │                     ↑ 滑动窗口  │  审稿+按必改项修订
                         │                     └ write(n-16)        │
                         │                                   finalize(n) 润色定稿
                         │                                          │
                         │                                 summarize(n) → continuity(n)
                         │                                              └ P0 定向修补
```

任何一章的规划一完成，正文立刻开写；审稿、润色、摘要与连贯性检查全部在 DAG 上随章流动，无阶段屏障。

### 质量门开关

| 控制方式 | 行为 |
|----------|------|
| 默认 | 审稿 + 修订 + 润色 + 单元门 + P0 修补全开 |
| `--fast` | 质量门全关，drafted 直接定稿，极限速度 |
| `--no-critic` / `--no-editor` | 单独关审稿 / 润色 |
| `config.yaml → quality` | 细粒度配置（修订轮数、连贯修补、单元门） |

## 安装

需要 Python 3.11+，推荐使用 [uv](https://docs.astral.sh/uv/)：

```bash
git clone git@gitee.com:osheyx/novel-maker.git
cd novel-maker

uv sync                      # 安装运行时依赖
uv run novel --help          # 或激活虚拟环境后直接用 novel
```

不用 uv 也可以：

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e .
```

## 配置模型

配置文件位于 [`config/default.yaml`](config/default.yaml)，优先级：**CLI 参数 > 环境变量 > YAML**。

### 方式一：MiniMax（默认配置）

默认走本机 [`mmx`](https://www.npmjs.com/package/mmx-cli) CLI：

```bash
npm install -g mmx-cli
mmx auth login
```

### 方式二：任意 OpenAI 兼容服务（DeepSeek / Qwen / Kimi / GLM / vLLM / OpenRouter …）

在 `config/default.yaml` 的 `providers` 中加入，并在 `routes` 里把角色路由过去：

```yaml
providers:
  deepseek:
    type: openai_compat
    model: "deepseek-chat"
    base_url: "https://api.deepseek.com/v1"
    api_key_env: "DEEPSEEK_API_KEY"   # 从该环境变量读取密钥
    enabled: true

routes:
  concept: deepseek
  architect: deepseek
  world: deepseek
  character: deepseek
  planner: deepseek
  writer: deepseek
  continuity: deepseek
  summarizer: deepseek
```

```bash
export DEEPSEEK_API_KEY="sk-..."
```

> 密钥只从环境变量读取，不要把它写进配置或提交到仓库。

## 快速开始

```bash
# 1. 环境体检：配置、Provider 连通性
novel doctor

# 2. 新建一本书（先用小体量跑通）
novel new "残剑照边城" --genre 东方玄幻 \
      --premise "边陲少年偶得残破剑胎，被卷入仙门清算" \
      --words 9000 --volumes 1

# 3. 小批量试写：只生成前 3 章
novel generate 残剑照边城 --chapters 3

# 4. 正式生产：跑到目标字数（支持断点续跑）
novel generate 残剑照边城

# 5. 看进度 / 列作品 / 导出
novel status 残剑照边城
novel list
novel export 残剑照边城 --format txt
```

发布（详见 [docs/RELEASE.md](docs/RELEASE.md)）：

```bash
novel release build   太初剑主 --version 1.0.0          # 只构建，不联网
novel release verify  dist/novel-xxx-v1.0.0.tar.gz      # sha256 + 格式校验
novel release info    dist/novel-xxx-v1.0.0.tar.gz      # 看包里有什么
novel release publish 太初剑主 --version 1.0.0          # 发布为 Gitee 发行版
```

发行版 tag 与代码 tag 严格不撞：`--scheme novel`（默认）用 `novel-<书名>-v1.0.0`，
`--scheme data` 用 `data-YYYYMMDD.N`。

`generate` 常用参数：

| 参数 | 说明 |
|------|------|
| `--chapters, -n N` | 只跑前 N 章 |
| `--concurrency, -j N` | 覆盖并发上限 |
| `--lookahead N` | 正文领先窗口章数（默认 16，0=不限） |
| `--fast` | 质量门全关的极速模式 |
| `--no-critic` / `--no-editor` / `--no-gate` | 单独关审稿 / 润色 / 单元门 |
| `--no-post` | 跳过摘要与连贯性检查（更快） |
| `--fresh` | 忽略已有进度重跑 |

## 项目结构

```
novel-maker/
├── config/default.yaml        # 主配置：作品设定 / 运行时 / 质量门 / Provider / 路由
├── skills/                    # 创作技能卡（Markdown，按角色自动注入，Agent 通用）
├── src/novelmaker/
│   ├── cli.py                 # novel CLI 入口
│   ├── skills.py              # 技能卡加载 / 匹配 / 预算裁剪
│   ├── core/                  # config（配置）/ store（SQLite 持久化）/ textutil（文本工具）
│   ├── agents/prompts.py      # 各创作 Agent 的角色定义与提示词模板
│   ├── llm/                   # Provider 抽象 + 五类适配器 + 自适应调度器
│   ├── memory/context.py      # 分层故事记忆：圣经 / 卷 / 单元 / 前情 / 伏笔
│   └── pipeline/
│       ├── dag.py             # 无阶段屏障 DAG 执行器
│       ├── engine.py          # 把 DAG + Provider + 记忆层 + 技能库组装成生产流水线
│       └── release.py         # 发行包：构建 / 打包 / 校验 / 发布 Gitee 发行版
├── scripts/deploy-release.sh  # 服务器端：拉发行版 → 校验 → 解压 → 起容器
├── Dockerfile                 # 从源码构建（含 Node 阶段编译前端）
├── Dockerfile.release         # 运行时镜像（不含前端，产物由发行包带进来）
└── novels/<slug>/             # 每本书独立目录：config.yaml 快照 / 正文 / novel.db / 导出
```

> `novels/` 与 `dist/` 都不进 git：前者是过程产物、后者是发行版附件。

## 设计要点

1. **无阶段屏障 DAG**：节点依赖一满足就派发，不等待阶段边界——这是吞吐的主要来源。
2. **质量门随章流动而非整书批处理**：审稿/修订/润色/连贯性都是每章的 DAG 节点，质量保证不制造吞吐瓶颈。
3. **长篇不崩靠裁剪而非记忆**：`StoryMemory` 为每章动态拼装可控长度的上下文，并由摘要 Agent 持续把旧章节压成结构化记忆。
4. **技能与代码解耦**：工艺知识沉淀在 Markdown 卡片里，改写法不用改代码、不用重新发版。
5. **失败不致命的节点设计**：卷 / 单元 / 章 / 后处理任务标记为 `critical=False`，单点失败会被记录并跳过下游，而不拖垮整本书。
6. **一切皆 Provider**：新增模型 = 继承 `LLMProvider` 并通过 `register_adapter` 注册，或直接复用 `command_agent` 把任意 CLI 当模型。

## Web 预览 / Docker 部署

C 端小说预览站：**书架 → 书籍详情 → 阅读器**，成品与制作中的作品都能看。
后端 FastAPI 只读扫描 `novels/` 下的作品库，同时托管 Vue 构建产物，单进程、单镜像即可对外服务。

**手机与电脑同一套页面**：320px 到 2560px 自适应（平板不白吃一屏、手机有底部拇指工具条、
刘海屏走安全区）；滚动揭示等动效尊重系统「减弱动态效果」设置。
**阅读交互**：段落赞踩段评之外，支持按章书签、正文划线与笔记、阅读时长与连续天数统计——
都存在服务端 `interactions.db`，换设备打开同一本书仍在。详见 [docs/FEATURES.md](docs/FEATURES.md)。

### 1. Docker 一键部署（推荐）

```bash
# 构建镜像（多阶段：node 构建前端 → python 运行 API + 静态托管）
docker build -t novelmaker .

# 运行，挂载小说目录（卷保存 novels/，容器不存数据）
docker run -d --name novelmaker -p 8000:8000 \
  -v $PWD/novels:/app/novels \
  novelmaker
```

打开 <http://localhost:8000> 即可。更新小说内容后无需重启，刷新页面即可看到最新进度。

反向代理到域名时，SPA history fallback 已由 FastAPI 处理，nginx 只需转发：

```nginx
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
```

### 2. 本地开发

```bash
# 终端 A：后端（只读 API，默认 8000）
uv sync --extra server
uv run novel serve                 # 打开 http://127.0.0.1:8000

# 终端 B：前端（热更新，/api 已代理到 8000）
cd web && npm install && npm run dev    # 打开 http://127.0.0.1:5173
```

改后端加 `--reload`：`uv run novel serve --reload`；容器内需 `--host 0.0.0.0`。

### 3. 只构建前端（部署到 Nginx / OSS 等纯静态托管）

```bash
cd web && npm run build      # 产物在 web/dist
```

此时前端仍会请求同源 `/api`，需由 Nginx 反代到后端；若后端也托管 `web/dist`，
`novel serve` 会自动挂载并处理 history fallback，无需额外配置。

### API

只读、不鉴权（C 端公开预览）。以 `file:...?mode=ro` 打开 SQLite，
流水线生成中（WAL 模式）也不会产生写锁竞争；单本损坏不影响整页书架。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/health` | 健康检查，返回 workdir / web/dist 路径 |
| GET | `/api/books` | 书架：全部作品 + 定稿字数/章数/草稿章数 |
| GET | `/api/books/{slug}` | 详情：元信息 + 按卷分组的章节目录 |
| GET | `/api/books/{slug}/chapters/{no}` | 章节正文 + `draft` 标记 + 上下章号 |
| GET | `/api/books/{slug}/search?q=` | 书内全文搜索，按段定位（触顶会标 `truncated`） |
| GET | `/api/books/{slug}/reading` | 阅读态总览：书签 + 划线 + 阅读统计 |
| POST / DELETE | `/api/books/{slug}/bookmarks[/{chapterNo}]` | 加 / 取消书签（按章幂等） |
| POST | `/api/books/{slug}/highlights` | 新建划线（`text` 为真源，草稿重生成后自动重新定位） |
| PATCH / DELETE | `/api/books/{slug}/highlights/{id}` | 改划线笔记 / 删除划线 |
| POST | `/api/books/{slug}/reading/stats` | 阅读时长心跳上报 |

**抢先看**：定稿（`final`/`done`）之外的草稿章同样可读，目录打「抢先看·未校对」角标，
阅读器顶部显示未校对提示条——生成中的章节因此也能先睹为快。

### 环境变量

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `NOVEL_WORKDIR` | 配置里的 `workdir` | 小说根目录（容器里指向挂载卷） |
| `NOVEL_WEB_DIST` | `<repo>/web/dist` | 前端构建产物目录；不存在时只提供 API |

## 路线图

- [x] DAG 并行生产引擎 + 断点续跑
- [x] AI 质量门：审稿 / 修订 / 润色 / 单元门 / P0 修补
- [x] 创作技能库（9 张卡，自动注入）
- [x] 32 项测试（mock provider 离线跑通全链路）
- [x] CI：ruff + pytest
- [x] 发行：作品打包成可搬迁快照 → Gitee 发行版 → 服务器一键部署（代码/发行分离）
- [x] C 端 Web 预览站：书架 / 详情 / 阅读器（`web/` + `novel serve` + Dockerfile）
- [ ] 更多 Provider 适配器
- [ ] 并发 32 跑完百万字《太初剑主》

## 开源协议

基于 [MIT License](LICENSE) 开源，可自由使用与二次开发。生成的小说内容版权归使用者所有。

## 免责声明

本工具仅用于合法的创作与学习用途。请遵守所用模型服务商的使用条款，以及你所在地区的法律法规。

**生成合成内容标识义务**：《人工智能生成合成内容标识办法》（国信办通字〔2025〕2 号）已于
2025 年 9 月 1 日起施行。该办法要求对人工智能生成的文本在适当位置添加显式标识，
并在文件元数据中添加包含内容属性、服务提供者名称或编码、内容编号的隐式标识；
提供下载、复制、导出功能时须确保导出文件含有符合要求的显式标识；
任何组织和个人不得恶意删除、篡改、伪造、隐匿该标识，也不得为他人实施上述行为提供工具或服务。

`novel export` 的 txt 输出已由 `novelmaker.compliance.marking` 自动写入显式标识
（正文首尾）、隐式标识（文件内不可见块 + 旁置 `.meta.json`）与服务提供者编码；
`Store.export_marked` 提供 txt/md/json 三格式的统一带标识出口。
**`novel export --format md|json` 目前仍走命令行内的旧路径、尚未接入该模块**，
在该接线完成前，用这两种格式对外提供内容前需自行完成标识。

标识中的「生成工具」与「过程记录状态」按作品实际留痕生成，**没有机器可读记录时
如实写「无」，不填推断值**——标识文件是权属证据，不实陈述会反过来削弱举证能力。
本仓库在产作品中已存在零过程记录的作品，可导出后直接核验这一状态。

相关工程方案与代码落点见 [合规手册](docs/COMPLIANCE.md) 第 4 节。此外，纯 AI 自动生成
的内容在现行司法口径下不构成作品，权属与平台准入的判定标准见
[调查报告](docs/MARKET-AND-POLICY-RESEARCH.md) 第二、三章。