# novel-agent

**Repository Path**: crazyslide/novel-agent

## Basic Information

- **Project Name**: novel-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# novel 重写项目 · 文档索引

对标公众号「月夜烛峰」的闭源作品 **novel-agent**(长篇小说写作工作台)的开源重写项目。

## 文档地图

| 文档 | 性质 | 内容 |
|---|---|---|
| [novel-agent-调研报告.md](novel-agent-调研报告.md) | 调研 | 原项目未开源的验证过程、6 个替代开源项目对比与选型建议、外部项目评估(§六 deepwrite Apache-2.0;§七 chevoink **平台级调研**:市场定位/创作 Agent 架构/写作失败模式分类学/运行期护栏 + 可借鉴与候选清单) |
| [novel-agent-系统设计.md](novel-agent-系统设计.md) | 原文整理 | 公众号文章全文 1:1 整理(含 assets/ 23 张截图),**需求的事实来源** |
| [01-需求文档-PRD.md](01-需求文档-PRD.md) | 需求 | 定位、设计原则、范围内外、用户故事、M1–M13 功能清单与优先级、非功能需求、里程碑 |
| [02-功能设计文档.md](02-功能设计文档.md) | 设计 | 各模块功能规格:状态机(章节/伏笔)、废案语义、AI 写回协议、快照协议、导出规则 |
| [03-边界条件与异常处理.md](03-边界条件与异常处理.md) | 设计 | **逐条编号的边界条件清单(E-xx,~90 条)**,每条含期望行为与必须/建议级别,验收直接依据 |
| [04-数据存储与锚定算法设计.md](04-数据存储与锚定算法设计.md) | 设计(v0.2 SQLite 口径) | 数据库表清单、API 载荷 Schema、伏笔文本指纹锚定算法、字数统计规则、REST 端点清单;原桌面文件夹方案存档于其附录 A |
| [05-EPUB导出设计.md](05-EPUB导出设计.md) | 设计(v0.1,**已实现**) | EPUB 3.3 导出:范围、选型(避开 AGPL 依赖)、输出规格、接口、边界条目 E-M11-85~93、测试与里程碑 |
| [06-对抗性审查报告-2026-09-16.md](06-对抗性审查报告-2026-09-16.md) | 审查记录 | 2026-09-16 对抗性审查:2 严重 / 5 中等 / 8 轻微 + 测试缺口与修复顺序(含可复现脚本);条目状态跟踪于其 §9 |
| [CHANGELOG.md](CHANGELOG.md) | 发布 | 版本历史(当前 0.9.0) |

## 阅读顺序

新成员:调研报告(可选)→ 系统设计(事实来源)→ 01 PRD → 02 功能设计 → 03 边界条件 → 04 数据设计。
改动评审:03 中曾标 `[决策]` 的条目均已拍板落地(结论写在条目内),直接看对应 02 章节。

## 关键设计决策速览(原 `[决策]` 待拍板项均已落地,结论见 03 对应条目)

1. 文件按内部 UUID 命名,标题存元数据(规避重名/非法字符,E-G-06);
2. 伏笔仅支持段内锚定 + 4 步模糊重定位,失败转 orphan 不静默丢(E-M5-43);
3. AI 结果绑定章节 ID,跨章禁写(E-M9-67),生成期间切章不中断;
4. 快照恢复前自动备份,备份计入 50 上限(E-M10-76);
5. 存储单一 SQLite 文件(WAL,原子事务);正文即 Markdown 文本列,无专有格式。

## 当前状态

- [x] 调研与原文沉淀
- [x] PRD / 功能设计 / 边界条件 / 数据设计 v0.1(`[决策]` 项均已拍板落地,见 03 §0.6)
- [x] **Web 版实现**(FastAPI + SQLite / React + Vite + TipTap,端口 8765 / 5185)
- [x] 核心流程黑盒验证通过(编辑保存 / 伏笔锚定与回收 / 提醒 / 快照 / 看板 / 完稿检查 / 设定集 / 导出 / AI 错误路径)
- [x] 查找替换、EPUB 3.3 导出、卷排序、专注模式、人物检索(2026-09-08 补齐)
- [x] **AI 找伏笔**(结构化产物,2026-09-10):通读本章产出伏笔候选 → 本地 `locate()` 锚定预校验(对不上正文的置灰禁采纳) → 逐条采纳为「待定」伏笔。服务端只把标记块抽成候选项,位置推断全在前端,算法只有一份实现(见 03 号文档 E-M9-77~79)
- [x] 自动化回归:后端 pytest 65 例 + ruff · 前端 `npm run check`(logic-check + store-check)· **Playwright UI 回归 `npm run test:ui`(10 条关键路径)** · `scripts/check_all.sh`(CI:.github/workflows/ci.yml;推送门禁 pre-push)
- [x] 03 号文档 §0.2 未实现清单**已清空**(12 项全部落地,见 03 §0.6)
- [x] 部署与数据安全(2026-09-12):FastAPI 托管前端单进程、一键启动脚本、整库每日备份、双实例锁(E-G-04)、CI + epubcheck
- [x] 写作增强(2026-09-12,v0.3.0):全书搜索(顶栏 / Ctrl+Cmd+P)、decoration 点击编辑伏笔、推送门禁(pre-push 跑全量回归)
- [x] UI 回归(2026-09-12,v0.4.0):Playwright 8 条关键路径上线,顺带修复「装饰延迟渲染」「搜索跳转无选区」两个交互缺陷
- [x] v0.5.0(2026-09-12):AI 分任务模型 + 提示词模板可编辑;作品归档导出/导入;卷拖拽排序;密度分页;分词搜索;超大章提示;DOCX 提要选项;pyproject(`novel-web` 命令)+ ruff 门禁;UI 回归扩到 9 条(AI 找伏笔全流程)
- [x] v0.6.0(2026-09-15):整库备份剔除 AI Key(数据安全(2),防备份拷贝拖走明文 Key);调研报告归档 deepwrite 评估
- [x] v0.6.1(2026-09-15):E-M11-82 补齐 EPUB/DOCX 标题 # 转全角(三种导出格式统一);清 03 遗留 `[决策]` 标记;修 package-lock 版本漂移
- [x] v0.7.0(2026-09-16):**06 号对抗性审查全量修复**——S1 删卷幽灵章 / S2 设置类型校验(死库防线)/ M1 改 Base URL 自动清 Key / M2 对话框失败不关 / M3 大纲吞字 / M4 锚定跨段判 orphan / M5 空输入回落默认 / L1–L8;测试扩到 pytest 65 + store-check 状态机回归 + e2e 10 条
- [x] v0.7.1(2026-09-16):§5 观察项闭环——`locate()` 模糊窗口对齐(空白差异 1–2 字错位校正)+ boot 规模实测(2000 章 1.15MB/632ms,5000 章 3.46MB/1678ms,万章以上再分页化)
- [x] v0.8.0(2026-09-16):chevoink 评估后的借鉴落地——AI 结果**内容寻址缓存**(概括/找伏笔:正文或模型配置未变则复用,不重复调用模型,可「重新生成」跳过)+ **失败止损**(同类连续失败 3 次升级为聚合诊断,不阻断重试);顺带修复错误分类被通用"连接中断"文案覆盖、部分内容中断静默当成功;测试扩到 pytest 72 + logic-check/store-check 各加一组 + e2e 11 条
- [x] v0.9.0(2026-09-17):**多模型档位 + 多模态输入**——任意多档配置(端点/Key/模型/输入输出上限/温度/超时/声明的输入模态),可增删改与切换当前档、每档单独测试连接、按任务选档;写作页可挂图片/PDF/音频/视频附件随请求发送(未声明模态一律拒发);`ai.profiles` 成为真源、扁平字段退化为镜像(历史库零迁移),Key 逐档隔离;测试扩到 pytest 95 + e2e 13 条
- [ ] 路线图(01 §4.2 范围外,非缺陷):DOCX 已补做;拼写检查、TTS、云同步/账号/多人协作、移动端 App、git 集成、插件系统、内置大模型

## 许可证

[MIT](LICENSE)

## 运行方式

**一键启动(推荐,单进程单端口)**:

```bash
# Windows 双击 start.bat;macOS / Linux:
./start.sh
# 首次运行自动构建前端,之后直接打开 http://127.0.0.1:8765
```

**开发态(改前端热更新,双进程)**:

```bash
cd backend && pip install -r requirements.txt
python -m uvicorn app.main:app --port 8765   # 会托管 frontend/dist(若有,02 §M13)
# 或安装为命令:pip install ./backend 后直接运行 `novel-web`

cd frontend && npm install && npm run dev    # 浏览器打开 http://localhost:5185,/api 代理到 8765
```

- 数据库文件:`backend/data/novel.db`;API Key 存于该库 settings 表,不随导出外泄;
- **整库备份**:每次启动自动快照到 `backend/data/backups/`(每日一份,保留 14 份;`NOVEL_BACKUP_DAYS` 可调,0=关闭)。备份副本已剔除 API Key,但**运行库(`backend/data/novel.db` 与 WAL)仍是明文**——直接拷贝整个 `data/` 目录会带走 Key,共享/上传时请只给 `backups/` 下的副本;
- **局域网部署须知**:默认只绑定 `127.0.0.1`;用 `NOVEL_ALLOWED_HOSTS` / `NOVEL_ALLOWED_ORIGINS` 放开后**API 无鉴权**——局域网内任何人可读写全部数据、改写设置。v0.7.0 起「改 Base URL 必须随请求重交 API Key」(存量 Key 自动清除),已阻断「改地址把库内 Key 外送」的链路,但数据面暴露不变,请仅在可信网络使用;
- **单实例**:同一数据库同时只允许一个实例(E-G-04 数据目录锁,崩溃自动过期);并行开发/测试用 `NOVEL_DB` 指向其他库;
- AI 助手需在「⚙ 设置」配置 OpenAI 兼容端点与 Key(默认 DeepSeek),**支持多档位**:一档 = 一套端点 + Key + 模型 + 输入/输出上限 + 声明的输入模态,可增删改并切换「当前档」,每个任务也可单独指定档位;每档有「测试连接」自检。**输入模态按档位声明**:未勾选的模态(如图片/PDF)会被拒绝发送,不会静默丢弃(E-M9-82);
- 实现与文档的差异:作品存储由"文件夹+Markdown"改为 SQLite(用户指定 Web 版),锚点/字数/快照等算法规格仍遵循 04 号文档;
- 无 API Key 时可用 `python backend/scripts/mock_openai.py`(本地假 OpenAI 端点)端到端验证 AI 路径;
- 全量回归:`bash scripts/check_all.sh`(Windows `scripts\check_all.bat`)= pytest + npm check + build;UI 回归:`cd frontend && npm run test:ui`(需先 `npx playwright install chromium`);CI 见 `.github/workflows/ci.yml`(推 GitHub 可直接用,Gitee 可配 webhook/Gitee Go 调用同一脚本);
- **推送门禁**:`git config core.hooksPath scripts/hooks` 启用后,每次 push 自动跑全量回归,失败即中止(紧急跳过:`git push --no-verify`)。