企业官网建设流程全解析

基于 HelloAgents 框架的智能小说创作系统：NovelGenerator 架构解析与实战指南

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

本文以开源仓库 Co-creation-projects/lgs-only-NovelGenerator 项目为主体，完整拆解一个「创意 → 大纲 → 章节 → 本地持久化」的 LLM 小说辅助创作系统：从.env环境配置、FastAPI 服务启动，到OutlineAgent大纲生成、ChapterGenerateAgent上下文感知章节生成与记忆机制、双 Agent 审核循环的底层实现，并结合仓库源码逐行印证每个设计决策。读完本文，你将掌握如何基于 HelloAgents 框架的SimpleAgent、HelloAgentsLLM与NoteTool，独立搭建一个具备长文本一致性、可批量续写、内容可编辑的小说创作 Agent 应用。

一、项目定位：解决长篇小说创作的三类核心痛点

NovelGenerator 不是一个简单"输入提示词、输出一段文字"的文本生成器，而是一个理解故事结构、保持剧情连贯、具备上下文记忆能力的创作伙伴。其 README 明确指出了它瞄准的三大痛点：

1. 大纲构建困难：从一句模糊灵感（如"一个关于AI程序员穿越到代码世界的故事"）到结构化大纲，由 LLM 梳理世界观、人物与分卷规划；
2. 剧情连贯性差：生成后续章节时自动回顾前文情节与摘要，保证人物行为、剧情发展前后自洽，缓解长篇小说常见的"逻辑崩坏"问题；
3. 创作效率低：支持一次批量生成多个章节，快速推进故事进度。

从仓库目录结构看，整个系统由四个层次构成（详见 目录结构）：

Co-creation-projects/lgs-only-NovelGenerator/ ├── agents/ # Agent 核心逻辑 │ ├── outline_agent.py # 大纲生成 Agent │ ├── chapter_generate_agent.py # 章节生成 Agent（含记忆与审核） │ └── prompt.py # 全部 Prompt 模板 ├── src/ │ └── app.py # FastAPI 应用入口（RESTful API） ├── frontend/ │ └── index.html # Vue3 + Tailwind 单页前端 ├── outputs/ # 生成结果存储目录（Markdown + JSON） ├── main.py # 命令行端到端测试脚本 ├── data/image.png # 前端演示截图 └── requirements.txt # 项目依赖

技术选型上，它踩在 HelloAgents 框架之上：核心编排使用SimpleAgent与HelloAgentsLLM，持久化使用框架自带的NoteTool，对外服务用 FastAPI + Pydantic，文件存储直接落盘为 Markdown + JSON，方便创作者在任意编辑器里直接查看和二次编辑。

二、快速开始：环境配置与两种运行方式

2.1 环境要求与依赖安装

• Python 3.10+；
• 任一兼容 OpenAI 接口的大模型（如 DeepSeek、Qwen，或本地 Ollama 服务）。

在项目目录执行依赖安装（依赖清单见 requirements.txt，核心包括hello-agents[all]>=0.2.8、fastapi>=0.109.0、uvicorn>=0.27.0、pydantic>=2.0.0、python-dotenv>=1.0.0）：

pip install -r requirements.txt

2.2 配置.env环境变量

在项目根目录创建.env文件，参考仓库 README 提供的完整示例：

# .env 示例 LLM_PROVIDER=ollama # 或 openai, qwen 等 LLM_MODEL_ID=qwen2.5-72b-instruct API_KEY=your_api_key BASE_URL=http://localhost:11434/v1 # 如果使用本地 Ollama LLM_TIMEOUT=60 HOST=127.0.0.1 PORT=8000

各变量作用如下：

两个 Agent 模块（outline_agent.py、chapter_generate_agent.py）都在模块顶部通过load_dotenv()加载该文件；src/app.py 中则直接用os.getenv("LLM_MODEL_ID")读取模型 ID 来初始化HelloAgentsLLM，并在__main__里以os.getenv("HOST")、os.getenv("PORT")启动 uvicorn。

2.3 方式一：启动 API 服务（推荐）

python src/app.py # 或者 uvicorn src.app:app --reload

服务启动后，Swagger 交互式 API 文档可通过http://127.0.0.1:8000/docs访问。前端页面 frontend/index.html 可直接在浏览器打开（前端代码中将 API 地址硬编码为http://localhost:8000），也可以通过简单 HTTP 服务器托管。

2.4 方式二：命令行端到端测试

main.py 是一个完整的命令行测试脚本，跑通"初始化 LLM → 生成大纲 → 生成第一章 → 校验输出文件"全流程：

python main.py

该脚本的核心流程值得留意：它用int(time.time())生成唯一novel_id，以target_length=1000、chapter_length=1000缩短生成耗时用于测试；在生成完成后，还会检查outputs/{标题}-{novel_id}/outline与chapters两个目录是否存在且非空，输出PASS/FAIL校验结果。仓库 outputs 目录下保留了完整的实测产物（如"测试Agent功能小说"项目的 大纲 与 第一章），可作格式参考。

三、大纲生成 Agent：从一句创意到十二节结构化大纲

3.1 源码结构与调用方式

agents/outline_agent.py 中的OutlineAgent继承自 HelloAgents 框架的SimpleAgent，构造参数支持自定义工作目录（workspace，默认./outputs）与大纲目标字数（outline_length，默认 3000）。其核心run方法执行三步：

1. 校验入参：novel_id与title为必填（assert强制）；
2. 构建上下文：将用户创意、标题、标签、目标字数格式化进OUTLINE_PROMPT；
3. 调用 LLM 并持久化：self.llm.invoke(messages)获取大纲文本，再通过NoteTool以create动作保存，并从输出中解析出note_id。

值得注意的是标签处理方式：OutlineAgent.run中tags='，'.join([str(tag) for tag in kwargs.values() if tag])，会把剩余的任意关键字参数（如风格标签、情感基调、channel、style）拼接为标签串注入 Prompt，这正是前端"男频/女频 + 风格选择"得以生效的通道——在 src/app.py 的/outline/generate接口中，run_kwargs.update(req.style_tags)将style_tags字典透传给 Agent。

OutlineAgent还提供了三个文档操作方法，均以novel_id+note_id定位笔记：

• get_outline(novel_id, note_id, title)：read动作读取大纲；
• update_outline(novel_id, note_id, title, **kwargs)：update动作覆盖内容（注意：更新是整体覆盖，需要先读取再追加，main()中的示例即演示了"读取 → 拼接新设定 → 更新 → 再读取验证"的完整闭环）；
• del_outline(novel_id, note_id, title)：delete动作删除大纲。

3.2 NoteTool 持久化与 note_id 解析

_ensure_tool方法按novel_id缓存NoteTool实例，其工作目录为{workspace}/{title}-{novel_id}/outline，从而将不同小说的大纲物理隔离到独立文件夹：

self.note_tools[novel_id] = NoteTool( workspace=os.path.join(self.workspace, f"{title}-{novel_id}", 'outline') )

extract_note_id函数用正则ID:\s*(note_[0-9_]+)从 NoteTool 的输出文本中提取笔记 ID（如note_20260128_030758_0），并在此后所有读写操作中复用，作为小说与大纲、章节之间的关联主键。从 outputs 下的实际产物可见，每个笔记文件头部都带有 YAML frontmatter（id、title、type、tags、created_at、updated_at），正文是标准 Markdown，并由notes_index.json维护索引。

3.3 OUTLINE_PROMPT：十二节专业大纲模板

agents/prompt.py 中的OUTLINE_PROMPT是整套系统专业性的基石。它将 LLM 定位为"资深故事架构师与编辑"，要求输出约{target_length}字（允许 ±10%）的中文长篇小说大纲，且明确要求"分卷/分段形式，细化到章节级要点"。模板规定了大纲必须覆盖的十二个一级标题：

1. 故事概念与独特性：核心母题、3 个左右卖点、叙事视角；
2. 世界观与设定：时空背景、关键规则/禁忌/代价、重要地点与象征物；
3. 人物谱系与关系网：主角群的目标/缺陷/成长弧线、反派动机、关键配角功能；
4. 叙事结构总览：三幕/四幕/环形等结构方案、主题推进与情感曲线；
5. 分卷/分段规划（核心）：每卷 300–500 字概述 + 6–10 章章节要点（每章 2–3 行，标注冲突/悬念/反转）+ 伏笔回收；
6. 高潮与关键转折设计：至少 3 个大型高潮、反转的误导点与真实点；
7. 节奏控制与悬念布置：短/中/长三类悬念链、每卷结尾"钩子"；
8. 原创性与防重策略：规避市场套路、原创钩子与相似风险评估；
9. 主题深化与象征系统：贯穿意象/隐喻绑定关键场景、结尾主题回应；
10. 延展与改编可能：2–3 条可扩展支线、影视化改编要点；
11. 标签融入策略：把标签映射到人物、场景、冲突与意象；
12. 写作风格与审美基调：文体、语言节奏、叙述者语气与距离。

仓库实测产物完整呈现了该模板的效果：以"AI 程序员穿越到自己编写的代码世界"为创意生成的 大纲文档 中，"逻辑域"世界观、协议阶级、"主控塔/递归深渊/变量花园"三处关键地点、三幕剧结构、分三卷的章节要点，乃至"Bug 具象化为物理灾难"的原创钩子与意象系统全部齐备，且每卷结尾都埋设了清晰钩子。

四、章节生成 Agent：上下文感知 + 记忆机制 + 双 Agent 审核

4.1 核心数据结构与构造函数

agents/chapter_generate_agent.py 定义了ChapterGenerateAgent（注意：它没有继承SimpleAgent，而是内部组合两个 SimpleAgent 实例）与MemoryItem记忆项：

• MemoryItem（Pydantic 模型）承载node_id、novel_id、title、content、summary、timestamp、metadata、next_chapter_prediction八个字段，是"创作记忆"的最小单元；
• 构造函数关键参数：max_steps（生成-审核最大重试轮次，默认 5）、chapter_length（单章字数，默认 3000）、num_chapter_memories（回忆最近章节数，默认 5）、workspace（默认./outputs）；
• 内部组合两个SimpleAgent：generate_agent（"章节生成助手"）与review_agent（"章节审核助手"，system prompt 定位为"检查章节是否符合小说的结构和风格"）——这正是系统中"生成-审核"双 Agent 架构的载体；
• self.memories: Dict[str, List[MemoryItem]]以novel_id为键维护进程内记忆缓存。

4.2 run 主流程：生成 → 审核 → 修正 → 保存

run方法的完整链路如下（chapter_generate_agent.py）：

1. 校验novel_id、novel_title必填，_ensure_tool按{workspace}/{novel_title}-{novel_id}/chapters初始化NoteTool；
2. 首次运行时通过get_memories从notes_index.json与 Markdown 文件加载历史章节为MemoryItem；
3. 构建三路上下文：get_outline（从同级outline目录读取大纲文件）、get_prev_chapter（最近一章正文的末尾 800 字）、get_prev_summaries（最近num_chapter_memories章的摘要列表）；
4. 进入while steps < self.max_steps循环：先让generate_agent产出章节 JSON，再用CHAPTER_REVIEW_PROMPT驱动review_agent审核，若审核意见含【通过】则跳出循环，否则把上一轮生成内容与审核意见作为chapter_history/evaluation重新注入 Prompt 修正重试；
5. 通过后以create动作保存章节笔记（note_type="chapter"，tags存摘要），提取note_id，追加MemoryItem到记忆列表，返回(response_data, note_id)。

其中 JSON 解析由静态方法extract_json_from_response完成：先剥离```json代码块标记，再json.loads；解析失败则回退为截取文本中第一个{到最后一个}再解析，并对"缺少title/content/summary/next_chapter_prediction字段"的情况抛出ValueError触发重试——这是保证生成结果结构化可落盘的关键防线。

4.3 记忆机制：回顾、摘要与下一章预测

系统对"剧情连贯性"的保障体现在三个层面：

• 上一章正文回顾：get_prev_chapter返回【标题】\n...{最近内容末尾800字}，让模型在衔接处"承上"；
• 多章摘要记忆：get_prev_summaries汇总最近 N 章（默认 5）的【标题】+ 摘要，让模型掌握更宏观的剧情脉络；
• 下一章预测传导：每章生成时模型必须输出next_chapter_prediction（下一章摘要预测），存于MemoryItem；当用户未给下一章输入时（get_prompt中user_input为空），会默认使用self.memories[novel_id][-1].next_chapter_prediction作为续写方向，从而实现"AI 自行推进剧情"的连续创作——这一点在 src/app.py 的/chapter/generate接口中体现得更为直接：批量生成多章时，只有第一轮传入用户输入，之后current_input被清空，后续章节完全依赖记忆与预测自动续写。

get_content_from_note方法负责清洗笔记内容（剥离 YAML frontmatter 与首行# 标题），确保喂给模型的只有正文。此外，del_chapter与update_chapter在删除/更新磁盘笔记的同时，会同步维护内存中的MemoryItem列表，保证记忆与文件一致。

4.4 三个 Prompt 的分工：开篇、续写与审核

prompt.py 为章节生成准备了三个模板：

• CHAPTER_START_PROMPT（开篇章节）：当prev_chapter == '无' and prev_summaries == '无'时启用。强调"黄金三章原则"——快速建立世界观避免设定堆砌、鲜明引出主角、设置激励事件（Inciting Incident）打破平静生活，并在章末埋设悬念；
• CHAPTER_PROMPT（后续章节）：输入包含大纲、前一章正文、前几章摘要、本章历史生成内容、评判结果、用户输入/预测摘要六路信息；要求严格遵循大纲与前文、设置局部高潮与悬念、为下一章制造钩子；并内置"大结局"特殊规则——若判断本章为大结局，title必须含"大结局"字样，next_chapter_prediction置为空字符串；
• CHAPTER_REVIEW_PROMPT（审核模板）：从大纲契合度、原创性与故事性（"AI 味"检测、套路化风险）、人物塑造、节奏与张力四个维度评审，输出格式严格限定为【通过】或以【不通过】开头并附带分条修改建议——run主循环正是以"是否包含【通过】"作为循环终止条件。

三者的 JSON 输出格式统一为：

{ "title": "第X章-标题", "summary": "本章摘要（200字以内）", "content": "本章正文内容...", "next_chapter_prediction": "下一章摘要预测（包含核心冲突或悬念焦点）" }

仓库 第一章实测产物 展示了这一流程的最终效果：章节带有"第一章-代码之森"标题与写入 frontmattertags的中文摘要，正文以"林澈睁开眼时，天空是灰蓝色的，像一块被反复擦写的旧屏幕"开局，完整呈现了"代码之森"世界观建立、主角处境交代与"启动清除协议"这一激励事件，文末以"他要么学会重写规则，要么被彻底删除"收束悬念。

五、FastAPI 服务层：内容管理系统与项目映射

5.1 服务初始化与 CORS

src/app.py 通过两行sys.path.append把项目根目录与agents目录加入模块搜索路径，随后创建 FastAPI 应用，并配置了全开放 CORS（allow_origins=["*"]）以支持前端跨域直连。全局单例初始化了ProjectManager、OutlineAgent与ChapterGenerateAgent（chapter_length=3000默认值，可在请求中覆盖）。

5.2 ProjectManager：以 project_data.json 维护项目映射

ProjectManager是内容管理系统的"账本"：每个项目目录下维护一份project_data.json，记录novel_id、title、outline_id与chapters列表，提供load_mapping/save_mapping/update_outline_mapping/add_chapter_mapping/update_chapter_mapping/remove_chapter_mapping六个方法。它解决了一个关键问题：NovelGenerator 的novel_id可重复（README 注释"命名可能会重复"），因此以{title}-{novel_id}目录 + 映射文件双重定位，让前端刷新页面后能恢复大纲与章节列表。

5.3 API 接口清单

Pydantic 模型定义了五个请求体（OutlineRequest、OutlineUpdateRequest、ChapterGenerateRequest、ChapterUpdateRequest），接口如下：

其中/chapter/generate的批量逻辑（src/app.py）值得强调：循环调用chapter_agent.run，第一轮使用用户输入，后续current_input置空交给预测续写；每成功一章即写入chapters映射并追加到返回列表，任一章失败则break返回已生成部分。

六、前端界面：所见即所得的创作工作台

frontend/index.html 是一个基于 Vue 3（CDN 引入vue.global.js）与 Tailwind CSS 的单页应用，无需构建工具即可运行，通过 fetch 直连http://localhost:8000。界面按创作流程分为三个模块：

1. 大纲生成与管理：左侧输入"核心思路/故事梗概、预计字数（默认 3000）、小说频段（男频/女频）、作品风格"；右侧展示大纲并支持"保存修改 / 删除大纲"。风格数据在STYLE_CATEGORIES中预置——男频：玄幻/历史/都市/衍生/悬疑，女频：年代/纯爱/现代言情/古代言情/衍生/悬疑；
2. 章节生成：支持"本章思路（可留空自动续写）、生成数量（滑杆 1–5 章）、单章字数"，生成后自动加载最新一章内容预览；
3. 章节列表：倒序展示全部章节，点击折叠展开正文，可直接编辑标题与内容并"保存修改 / 删除本章"。

前端还会在输入标题后自动生成随机novel_id（'novel_' + Date.now().toString(36) + 随机串），并在刷新时调用/projects/{title}/{novel_id}恢复项目状态。下图为该创作工作台的实际界面（截图对应"华夏上下五千年"示例项目，可见大纲生成模块的完整交互布局）：

七、目录结构与产出文件格式

系统所有创作内容以本地文件形式落盘，目录组织为{workspace}/{title}-{novel_id}/{outline|chapters}/，每个笔记文件包含 YAML frontmatter 元数据与 Markdown 正文，配套notes_index.json索引。以仓库实测产物为例：

• 大纲文件 note_20260128_030758_0.md 的 frontmatter 为id / title / type: outline / tags / created_at / updated_at；
• 章节文件 note_20260128_030815_0.md 的 frontmatter 中tags存放该章中文摘要，type: chapter。

这种"Markdown + JSON"双格式存储带来两个实际收益：一是创作者可用任意编辑器直接阅读、搜索与二次编辑，实现"数据完全掌控"；二是notes_index.json让ChapterGenerateAgent.get_memories能快速索引并按时间序截取最近 N 章，无需全量扫描文件。

八、设计亮点与演进方向

从源码层面可以提炼出四个值得借鉴的设计决策：

• 长文本一致性靠"记忆分层"而非"单次超长上下文"：正文回顾（800 字窗口）+ 多章摘要（默认 5 章）+ 下一章预测，三层信息以不同粒度同时注入 Prompt，在控制 token 成本的同时维持连贯性；
• 生成-审核双 Agent 形成闭环：generate_agent与review_agent分工，审核意见（evaluation）与失败轮次的生成内容（chapter_history）会回灌到下一轮 Prompt，max_steps（默认 5）限制兜底，避免无限循环；
• 结构化输出 + 容错解析：强制 JSON 输出、剥离代码块标记、{到}截取回退、字段缺失校验四层保障，使 LLM 输出能稳定落盘为结构化笔记；
• "先大纲、后章节"的结构化工作流：还原作家真实创作路径（创意 → 大纲 → 章节），而非从零开始盲目生成，从源头降低剧情失控概率。

README 的"未来计划"还列出了回退功能、人物与事件知识图谱、短篇小说生成、更多小说风格、前端体验优化等方向（均为待定规划，仓库中尚无对应实现）。总体而言，NovelGenerator 的价值在于它把 HelloAgents 框架的SimpleAgent、HelloAgentsLLM、NoteTool三件套，与一套严谨的 Prompt 工程、记忆机制和双 Agent 审核循环组合成一个开箱即用的完整产品——既有 CLI 测试入口（main.py），又有 RESTful API（src/app.py）和可视化前端（frontend/index.html），是学习如何用 Agent 框架构建"上下文感知 + 长文本一致性"创作应用的优秀范本。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents