AInovel · AI 自动小说创作平台

给出灵感 → 生成大纲 → 逐章创作；维护“世界线 / 人物线 / 感情线”等全局线，支持用户编辑并驱动创作调整。

本仓库采用 UTF-8 编码。当前实现已包含 FastAPI 后端与 React 前端；LangGraph 属于后续可选集成（当前未集成，不影响现有实现与测试）。

---

功能特性

• 灵感驱动：输入灵感后自动生成小说大纲与章节草稿。
• 全局线数据库：世界线 / 人物线 / 感情线等可读写，影响后续创作。
• 可编辑与反馈循环：用户修改会被纳入上下文，驱动生成调整。
• 轻量持久化：默认 SQLite；可选对接 Gemini 2.5 Flash（需 GEMINI_API_KEY）。
• 可测试与可观测：合约 / 集成 / 单元测试；结构化日志与错误上下文。

技术栈与结构

• 后端：Python 3.11 · FastAPI · SQLite
• 前端：React 18 · Vite · TypeScript 5+
• 测试：pytest；Jest + React Testing Library

推荐目录（Option 2：Web 应用）

backend/
  src/{models,services,api,...}
  tests/{contract,integration,unit,performance}
frontend/
  src/{components,pages,services,store,...}
  tests/

更多设计请见 specs/001-ai-novel-creation-platform。

快速开始

以下命令默认在仓库根目录执行；如无特殊说明，请使用 UTF-8 终端。

1) 后端（FastAPI）

Windows PowerShell：

python -m venv venv
./venv/Scripts/Activate.ps1
pip install -r backend/requirements.txt
# 配置环境变量（可选：.env）
#   GEMINI_API_KEY=你的密钥（可选，仅当启用 Gemini 生成）
cd backend
uvicorn src.main:app --reload --port 8000

macOS/Linux：

python3 -m venv venv
source venv/bin/activate
pip install -r backend/requirements.txt
# 可在 backend/.env 写入 GEMINI_API_KEY
cd backend
uvicorn src.main:app --reload --port 8000

启动后访问 Swagger 文档：http://localhost:8000/docs。

2) 前端（React + Vite）

cd frontend
npm install
npm run dev

访问：http://localhost:3000。

3) 基础 API 验证（示例）

# 1) 创建灵感
curl -X POST http://localhost:8000/api/inspiration \
  -H "Content-Type: application/json" \
  -d '{"prompt":"一支远航舰队在未知星域遭遇时空裂缝"}'

# 2) 生成大纲
curl -X POST http://localhost:8000/api/outline \
  -H "Content-Type: application/json" \
  -d '{"inspiration_id":"<替换为上一步返回的id>", "chapter_count":12}'

# 3) 生成章节
curl -X POST http://localhost:8000/api/novel/<novel_id>/chapter \
  -H "Content-Type: application/json" \
  -d '{"chapter_index":1, "feedback":"节奏稍快，补充分支线"}'

# 4) 全局线读写
curl http://localhost:8000/api/novel/<novel_id>/global-lines
curl -X PUT http://localhost:8000/api/novel/<novel_id>/global-lines \
  -H "Content-Type: application/json" \
  -d '{"worldline":[{"event":"裂缝扩大","impact":"影响航道"}]}'

端点与字段以 specs/.../contracts/api-spec.yaml 为准；如有差异，以最新合约为准。

API 一览

• POST /api/inspiration 创建灵感
• POST /api/outline 生成大纲
• POST /api/novel/{novel_id}/chapter 生成章节
• GET/PUT /api/novel/{novel_id}/global-lines 全局线读写

配置说明

• GEMINI_API_KEY（可选）：启用 Gemini 2.5 Flash 生成能力。
• SQLite 默认内置；如需自定义路径，可在后端配置中调整。
• 日志：使用结构化日志，包含错误上下文与请求关键信息。

测试与质量

• 准则：Contract → Integration → Unit；严格 RED → GREEN → REFACTOR。
• 后端测试（pytest）：

  cd backend
  pytest -q

• 前端测试（Jest）：

  cd frontend
  npm test

• 合约测试覆盖四个端点；集成测试覆盖“灵感→大纲→章节→全局线→用户修改影响创作”。

数据模型（摘要）

• 核心实体：Inspiration、Outline(+ChapterOutline[])、WorldEvent、Character(+Relationship,+Development)、Relationship、Chapter(+ChapterReference[])。
• 状态 NovelCreationState：current_chapter、total_chapters、status、worldline/characterline/relationshipline、outline/chapters、user_feedback、cached_context、api_call_count 等。

详情见 specs/001-ai-novel-creation-platform/data-model.md。

性能目标

• 大纲生成 < 60s；章节生成 < 30s；全局线更新 < 5s；支持 100+ 章节长篇。

开发约定

• 简单优先：仅前后端两个项目；直连 SQLite；统一数据模型（DTO 仅作序列化）。
• 版本策略：语义化版本自 1.0.0 起，每次变更递增 build。
• 节流与缓存：优先减少 Gemini API 调用（缓存 / 批处理 / 条件执行 / Token 统计）。
• 文档与代码一一对应：新文档放在 specs/001-ai-novel-creation-platform/。

路线图（摘录）

• Phase 3.1 初始化：依赖与质量工具（pre-commit/ESLint/Prettier）。
• Phase 3.2 测试先行：合约 T006–T009；集成 T010–T013。
• Phase 3.3 核心实现：数据模型 T014–T019；状态与 reducer T020–T021；服务 T022–T026；API T027–T030。
• Phase 3.4 前端：组件 T031–T035；状态管理与 API 客户端 T036–T038。
• Phase 3.5 集成与优化：DB/检查点/监控；批处理/缓存/条件执行/Token 统计；前端路由/主题/错误边界/加载态。
• Phase 3.6 完善与发布：单元与性能测试；文档与部署（docker-compose/Dockerfile）；Quickstart 验证。

故障排查

• 端口占用：修改后端 --port 或前端 VITE_PORT。
• 未设置 GEMINI_API_KEY：仅禁用 Gemini 相关能力，核心流程仍可运行。
• SQLite 锁冲突：确保单进程写入或开启 WAL；重试后继续。

贡献与许可

• 欢迎提交 Issue / PR（保持小步提交与一致风格）。
• 代码格式：统一使用 Prettier/ESLint（前端）与 Black/ruff（后端，如已配置）。
• 许可：当前未设置 License；在明确之前，默认保留所有权利。

---

如果这个项目对你有帮助，欢迎点亮 ⭐ 支持！