文章目录
- 第一章：项目概述与架构分析
- 1.1 项目简介
- 1.2 核心功能
- 1.3 技术栈总览
- 1.4 系统架构图
- 1.5 完整目录结构
- 第二章：环境准备
- 2.1 Python 环境安装
- 2.2 虚拟环境创建（强烈推荐）
- 2.3 LLM 服务准备
- 方案 A：使用 DeepSeek（推荐新手）
- 方案 B：使用通义千问 Qwen
- 方案 C：使用本地 Ollama（免费，但需要足够显存）
- 2.4 项目依赖安装
- 第三章：项目搭建 —— 从空目录到完整项目
- 3.1 创建项目根目录与子目录
- 3.2 创建配置文件 `.env`
- 3.3 创建依赖声明 `requirements.txt`
- 3.4 创建 Git 忽略文件 `.gitignore`
- 第四章：核心代码实现 —— Prompt 模板层
- 4.1 文件位置与作用
- 4.2 完整代码：`agents/prompt.py`
- 4.3 逐段深度解析
- 4.3.1 OUTLINE_PROMPT（大纲生成模板）
- 4.3.2 CHAPTER_PROMPT vs CHAPTER_START_PROMPT（两个章节模板的区别）
- 4.3.3 CHAPTER_REVIEW_PROMPT（审核模板）
- 第五章：核心代码实现 —— 大纲生成 Agent
- 5.1 设计思路
- 5.2 完整代码：`agents/outline_agent.py`
- 5.3 逐段深度解析
- 5.3.1 `extract_note_id()` 工具函数
- 5.3.2 `_ensure_tool()` —— 懒加载模式
- 5.3.3 `run()` 方法 —— 核心流程
- 第六章：核心代码实现 —— 章节生成 Agent
- 6.1 设计思路
- 6.2 完整代码：`agents/chapter_generate_agent.py`
- 6.3 逐段深度解析
- 6.3.1 MemoryItem 数据模型
- 6.3.2 生成-审核循环（核心算法）
- 6.3.3 首章判断逻辑
- 第七章：API 服务层 —— FastAPI 后端
- 7.1 设计思路
- 7.2 完整代码：`src/app.py`
- 7.3 逐段深度解析
- 7.3.1 导入路径配置
- 7.3.2 ProjectManager —— 数据持久化的桥梁
- 7.3.3 批量章节生成的状态管理
- 7.4 API 接口清单
- 第八章：前端界面 —— Vue3 单页应用
- 8.1 技术选型
- 8.2 完整代码：`frontend/index.html`
- 8.3 前端功能模块解析
- 8.3.1 三大功能区
- 8.3.2 状态管理设计
- 8.3.3 懒加载策略
- 第九章：命令行测试脚本
- 9.1 完整代码：`main.py`
- 9.2 使用说明
- 第十章：测试验证全流程
- 10.1 启动 API 服务
- 10.2 使用前端界面测试
- 10.3 使用命令行脚本测试
- 10.4 验证输出文件
- 第十一章：常见问题与排错指南
- Q1：`ModuleNotFoundError: No module named 'hello_agents'`
- Q2：`KeyError: 'LLM_MODEL_ID'` 或 LLM 连接失败
- Q3：`AssertionError: 请提供小说ID`
- Q4：前端页面无法连接后端（CORS 错误）
- Q5：生成的内容出现乱码或编码错误
- Q6：`ValueError: 无法从输出解析 note_id`
- Q7：章节生成很慢
- Q8：`hello_agents` 版本兼容性问题
- 附录
- A. 完整文件创建清单
- B. 快速创建脚本
- C. 关键设计模式总结
- D. 扩展开发方向
第一章：项目概述与架构分析
1.1 项目简介
NovelGenerator是一个基于HelloAgents 框架的智能小说辅助创作系统。它利用大语言模型（LLM）的强大能力，为小说创作者提供智能化的辅助工具。
该项目解决的核心痛点：
| 痛点 | 解决方案 |
|---|---|
| 大纲构建困难 | 从模糊灵感到结构化大纲，AI 帮你梳理逻辑 |
| 剧情连贯性差 | 自动回顾前文情节和摘要，确保人物行为和剧情发展合理 |
| 创作效率低 | 支持批量生成章节，快速推进故事进度 |
| 内容管理混乱 | 自动保存为 Markdown 格式，提供 Web 界面管理 |
1.2 核心功能
- ✅智能大纲生成：根据用户输入的一句话创意、标题及标签，自动生成包含世界观、人物设定、分卷规划的详细大纲
- ✅上下文感知章节生成：基于大纲和前序章节内容，生成连贯的新章节，支持自动回顾前
