# 智能小说工作台

从一句话创意到完整长篇的 AI 小说生成工作台。核心设计：**分层流水线 + 故事圣经**——AI 不会一次生成整本书，而是沿「人物卡 → 世界观 → 分卷大纲 → 分章细纲 → 逐章正文」推进，每一步产物都可编辑确认；正文生成时自动注入相关人物卡、前情摘要与未回收伏笔，写完后自动把摘要、新设定、人物变化、伏笔、时间线回写进"故事圣经"，保证长篇的前后一致性。

## 功能

- **项目管理**：作品名 / 题材 / 故事创意 / 文风要求与示例 / 目标规模，卡片式总览，字数与进度统计
- **人物卡 & 世界观**：AI 生成（可反复重生成），全部字段可编辑；生成正文后自动追加人物近况
- **大纲与细纲**：AI 生成分卷大纲、每卷分章细纲（事件 / 涉及人物 / 伏笔安排），均可编辑
- **逐章正文生成**：流式输出（SSE），可中断；上下文注入 = 本章细纲 + 涉及人物完整卡 + 相关设定 + 全部前章摘要 + 上一章结尾 500 字 + 未回收伏笔
- **段落级改写**：选中任意段落重写 / 扩写 / 缩写 / 自定义指令，结果确认后替换
- **故事圣经面板**：人物 / 世界观 / 伏笔（未回收·已回收）/ 时间线，右侧栏常驻可直接增删改
- **自动回写**：每章正文采纳后，AI 自动提取章节摘要、新设定、人物状态变化、埋设/回收的伏笔、时间线事件
- **导出**：TXT（含卷章结构）与 EPUB（EPUB 3，目录按卷分组）
- **生成日志**：记录每次调用的模型与 token 用量（`generation_logs` 表）

## 快速开始

```bash
npm install          # 已安装过可跳过
npm run dev          # 开发模式：API 127.0.0.1:5175 + 前端 127.0.0.1:5173（自动代理）
```

生产模式（单端口，服务同时托管前端页面）：

```bash
npm run build
npm start            # 打开 http://127.0.0.1:5175
```

数据存放在 `server/data/novel.db`（SQLite 单文件，WAL 模式），备份即复制该文件。

## 模型接入（重要）

支持任意 **OpenAI 兼容接口**。首次启动会从 `.env` 读取初始配置，之后在界面右上角「模型设置」中查看修改，可一键「测试连接」。

当前 `.env` 预置了火山方舟配置：

```
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/plan/v3
ARK_API_KEY=ark-xxxx          # 你的 API Key
ARK_MODEL=doubao-seed-2.0-lite
```

当前 `.env` 已配置火山方舟 Agent Plan 并实测连通：

```
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/plan/v3
ARK_API_KEY=ark-xxxx
ARK_MODEL=doubao-seed-2.0-lite
```

> 配置以界面「模型设置」中保存的为准（存在数据库里）。若要换模型，注意 Agent Plan 只支持套餐内模型（如 `doubao-seed-2.0-lite`），标准后付费模型名会报 UnsupportedModel。应用会自动关闭豆包 seed 系列的深度思考以提速并保证输出干净。

## 目录结构

```
├── server/                 # Node.js + Express + node:sqlite
│   └── src/
│       ├── db/             # 建表 / 种子 / 行类型
│       ├── routes/         # CRUD、生成(SSE)、导出、设置
│       ├── llm/            # OpenAI 兼容客户端 + 各阶段提示词
│       └── pipeline/       # 上下文组装 + 圣经回写
├── web/                    # React 18 + Vite + Ant Design
│   └── src/components/     # 章节树 / 编辑器 / 生成抽屉 / 故事圣经 等
├── scripts/e2e_test.py     # 端到端回归测试（python -X utf8 scripts/e2e_test.py，需服务已启动）
└── .env                    # 模型配置（已 gitignore，勿提交）
```

## 设计说明

- **为什么不是一键生成整本**：长篇的难点是一致性（人物/伏笔/设定），分层生成 + 中间产物人工确认，比"一把梭"质量高得多，也便宜得多（改大纲比重写正文便宜）。
- **上下文策略**：MVP 采用"滚动摘要 + 相关实体注入"，可稳定支撑数百章；向量检索留作二期增强。
- **模型容错**：自动兼容豆包 seed 系列的 thinking 参数（400 时降级重试）、JSON 输出解析失败自动带反馈重试（最多 3 次）。

## 常见问题

- **生成报 401 / AuthenticationError**：API Key 无效，去「模型设置」更换。
- **生成报 UnsupportedModel**：Agent Plan Key 只能用套餐内模型名（当前可用：`doubao-seed-2.0-lite`）。
- **生成报 max_tokens 相关错误**：模型输出上限小于设置值，调小「单次最大输出 tokens」。
- **端口号**：默认 API 5175、前端开发端口 5173，可在 `server/src/index.ts` / `web/vite.config.ts` 修改。