基于 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 明确指出了它瞄准的三大痛点大纲构建困难从一句模糊灵感如一个关于AI程序员穿越到代码世界的故事到结构化大纲由 LLM 梳理世界观、人物与分卷规划剧情连贯性差生成后续章节时自动回顾前文情节与摘要保证人物行为、剧情发展前后自洽缓解长篇小说常见的逻辑崩坏问题创作效率低支持一次批量生成多个章节快速推进故事进度。从仓库目录结构看整个系统由四个层次构成详见 目录结构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、fastapi0.109.0、uvicorn0.27.0、pydantic2.0.0、python-dotenv1.0.0pip install -r requirements.txt2.2 配置.env环境变量在项目根目录创建.env文件参考仓库 README 提供的完整示例# .env 示例 LLM_PROVIDERollama # 或 openai, qwen 等 LLM_MODEL_IDqwen2.5-72b-instruct API_KEYyour_api_key BASE_URLhttp://localhost:11434/v1 # 如果使用本地 Ollama LLM_TIMEOUT60 HOST127.0.0.1 PORT8000各变量作用如下变量含义说明LLM_PROVIDER模型供应商ollama/openai/qwen等决定底层调用方式LLM_MODEL_ID模型标识例如qwen2.5-72b-instructAPI_KEYAPI 密钥使用云端服务时必填BASE_URL接口地址本地 Ollama 通常为http://localhost:11434/v1LLM_TIMEOUT请求超时秒默认 60长文本生成可适当调大HOST/PORT服务监听地址与端口默认127.0.0.1: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_length1000、chapter_length1000缩短生成耗时用于测试在生成完成后还会检查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方法执行三步校验入参novel_id与title为必填assert强制构建上下文将用户创意、标题、标签、目标字数格式化进OUTLINE_PROMPT调用 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_idnote_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( workspaceos.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 frontmatterid、title、type、tags、created_at、updated_at正文是标准 Markdown并由notes_index.json维护索引。3.3 OUTLINE_PROMPT十二节专业大纲模板agents/prompt.py 中的OUTLINE_PROMPT是整套系统专业性的基石。它将 LLM 定位为资深故事架构师与编辑要求输出约{target_length}字允许 ±10%的中文长篇小说大纲且明确要求分卷/分段形式细化到章节级要点。模板规定了大纲必须覆盖的十二个一级标题故事概念与独特性核心母题、3 个左右卖点、叙事视角世界观与设定时空背景、关键规则/禁忌/代价、重要地点与象征物人物谱系与关系网主角群的目标/缺陷/成长弧线、反派动机、关键配角功能叙事结构总览三幕/四幕/环形等结构方案、主题推进与情感曲线分卷/分段规划核心每卷 300–500 字概述 6–10 章章节要点每章 2–3 行标注冲突/悬念/反转 伏笔回收高潮与关键转折设计至少 3 个大型高潮、反转的误导点与真实点节奏控制与悬念布置短/中/长三类悬念链、每卷结尾钩子原创性与防重策略规避市场套路、原创钩子与相似风险评估主题深化与象征系统贯穿意象/隐喻绑定关键场景、结尾主题回应延展与改编可能2–3 条可扩展支线、影视化改编要点标签融入策略把标签映射到人物、场景、冲突与意象写作风格与审美基调文体、语言节奏、叙述者语气与距离。仓库实测产物完整呈现了该模板的效果以AI 程序员穿越到自己编写的代码世界为创意生成的 大纲文档 中逻辑域世界观、协议阶级、主控塔/递归深渊/变量花园三处关键地点、三幕剧结构、分三卷的章节要点乃至Bug 具象化为物理灾难的原创钩子与意象系统全部齐备且每卷结尾都埋设了清晰钩子。四、章节生成 Agent上下文感知 记忆机制 双 Agent 审核4.1 核心数据结构与构造函数agents/chapter_generate_agent.py 定义了ChapterGenerateAgent注意它没有继承SimpleAgent而是内部组合两个 SimpleAgent 实例与MemoryItem记忆项MemoryItemPydantic 模型承载node_id、novel_id、title、content、summary、timestamp、metadata、next_chapter_prediction八个字段是创作记忆的最小单元构造函数关键参数max_steps生成-审核最大重试轮次默认 5、chapter_length单章字数默认 3000、num_chapter_memories回忆最近章节数默认 5、workspace默认./outputs内部组合两个SimpleAgentgenerate_agent章节生成助手与review_agent章节审核助手system prompt 定位为检查章节是否符合小说的结构和风格——这正是系统中生成-审核双 Agent 架构的载体self.memories: Dict[str, List[MemoryItem]]以novel_id为键维护进程内记忆缓存。4.2 run 主流程生成 → 审核 → 修正 → 保存run方法的完整链路如下chapter_generate_agent.py校验novel_id、novel_title必填_ensure_tool按{workspace}/{novel_title}-{novel_id}/chapters初始化NoteTool首次运行时通过get_memories从notes_index.json与 Markdown 文件加载历史章节为MemoryItem构建三路上下文get_outline从同级outline目录读取大纲文件、get_prev_chapter最近一章正文的末尾 800 字、get_prev_summaries最近num_chapter_memories章的摘要列表进入while steps self.max_steps循环先让generate_agent产出章节 JSON再用CHAPTER_REVIEW_PROMPT驱动review_agent审核若审核意见含【通过】则跳出循环否则把上一轮生成内容与审核意见作为chapter_history/evaluation重新注入 Prompt 修正重试通过后以create动作保存章节笔记note_typechaptertags存摘要提取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 服务初始化与 CORSsrc/app.py 通过两行sys.path.append把项目根目录与agents目录加入模块搜索路径随后创建 FastAPI 应用并配置了全开放 CORSallow_origins[*]以支持前端跨域直连。全局单例初始化了ProjectManager、OutlineAgent与ChapterGenerateAgentchapter_length3000默认值可在请求中覆盖。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接口如下方法路径功能GET/projects/{title}/{novel_id}加载项目映射数据POST/outline/generate生成大纲透传style_tagsGET/outline/{title}/{novel_id}/{note_id}读取大纲剥离 frontmatterPUT/outline/update更新大纲DELETE/outline/delete删除大纲并清空映射POST/chapter/generate批量生成章节多章自动续写GET/chapter/{title}/{novel_id}/{note_id}读取章节正文剥离 frontmatterPUT/chapter/update更新章节与映射DELETE/chapter/delete删除章节与映射其中/chapter/generate的批量逻辑src/app.py值得强调循环调用chapter_agent.run第一轮使用用户输入后续current_input置空交给预测续写每成功一章即写入chapters映射并追加到返回列表任一章失败则break返回已生成部分。六、前端界面所见即所得的创作工作台frontend/index.html 是一个基于 Vue 3CDN 引入vue.global.js与 Tailwind CSS 的单页应用无需构建工具即可运行通过 fetch 直连http://localhost:8000。界面按创作流程分为三个模块大纲生成与管理左侧输入核心思路/故事梗概、预计字数默认 3000、小说频段男频/女频、作品风格右侧展示大纲并支持保存修改 / 删除大纲。风格数据在STYLE_CATEGORIES中预置——男频玄幻/历史/都市/衍生/悬疑女频年代/纯爱/现代言情/古代言情/衍生/悬疑章节生成支持本章思路可留空自动续写、生成数量滑杆 1–5 章、单章字数生成后自动加载最新一章内容预览章节列表倒序展示全部章节点击折叠展开正文可直接编辑标题与内容并保存修改 / 删除本章。前端还会在输入标题后自动生成随机novel_idnovel_ 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会回灌到下一轮 Promptmax_steps默认 5限制兜底避免无限循环结构化输出 容错解析强制 JSON 输出、剥离代码块标记、{到}截取回退、字段缺失校验四层保障使 LLM 输出能稳定落盘为结构化笔记先大纲、后章节的结构化工作流还原作家真实创作路径创意 → 大纲 → 章节而非从零开始盲目生成从源头降低剧情失控概率。README 的未来计划还列出了回退功能、人物与事件知识图谱、短篇小说生成、更多小说风格、前端体验优化等方向均为待定规划仓库中尚无对应实现。总体而言NovelGenerator 的价值在于它把 HelloAgents 框架的SimpleAgent、HelloAgentsLLM、NoteTool三件套与一套严谨的 Prompt 工程、记忆机制和双 Agent 审核循环组合成一个开箱即用的完整产品——既有 CLI 测试入口main.py又有 RESTful APIsrc/app.py和可视化前端frontend/index.html是学习如何用 Agent 框架构建上下文感知 长文本一致性创作应用的优秀范本。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考