基于 HelloAgents 的上下文感知章节生成 Agent以 NovelGenerator《代码之森》生成实录为例【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents导读本文以开源仓库 hello-agents 共创项目 NovelGenerator 的实际生成产物——小说《测试Agent功能小说》第一章《代码之森》为线索深入拆解一个面向长篇小说创作的上下文感知章节生成 Agent 的实现原理。读者将掌握章节产物在本地文件系统中的存储规范、ChapterGenerateAgent的生成-审核双 Agent 闭环架构、基于大纲与记忆的上下文拼接策略以及如何通过main.py与 FastAPI 服务端到端复现一次真实的章节生成。一、从一份生成产物说起章节文件的存储规范在 outputs/测试Agent功能小说-test_novel_1769540842/chapters/note_20260128_030815_0.md 中保存着一次真实运行的章节生成结果。该文件由两部分构成1. YAML Frontmatter 元数据--- id: note_20260128_030815_0 title: 第一章-代码之森 type: chapter tags: [主角林澈在一片由流动代码构成的诡异森林中醒来……被迫面对未知世界的规则与危险。] created_at: 2026-01-28T03:08:15.761075 updated_at: 2026-01-28T03:08:15.761075 ---其中值得注意的字段id章节唯一标识由时间戳生成也是章节 Agent 与 API 层定位文件的索引键type: chapter与大纲文件的type: outline区分见 outline 目录下的同名结构这是后续get_memories按类型筛选章节笔记的依据tags存放的不是普通标签而是本章摘要。从源码看ChapterGenerateAgent.run在保存笔记时执行tags: [response_data.get(summary, )]chapter_generate_agent.py即把模型输出的摘要写入 tags 字段后续通过note[tags][0]直接读取摘要作为长期记忆。2. Markdown 正文正文即《代码之森》的完整第一章程序员林澈在一座由流动代码构成的森林中醒来触碰数据树触发系统警报遭遇清除协议与无脸黑影被迫在重写规则与被删除之间抉择。这是模型在CHAPTER_START_PROMPT开篇章节模板约束下产出的开篇章节其叙事任务快速建立世界观、引出主角、设置激励事件在正文中一一兑现。3. 配套索引文件同目录下的 notes_index.json 由 NoteTool 维护记录total_notes与每条笔记的元数据摘要。ChapterGenerateAgent.get_memories正是先读取该索引再按note_type chapter筛选最近 N 章num_chapter_memories默认 5逐条读取.md文件并剥离 frontmatter 与标题后构造成MemoryItem见 chapter_generate_agent.py。get_content_from_note中通过re.match(r^---\s*\n(.*?)\n---\s*\n, content, re.DOTALL)剥离 YAML 头、再剔除首行#标题保证了进入模型上下文的都是纯净正文。二、核心架构生成 审核的双 Agent 闭环ChapterGenerateAgentagents/chapter_generate_agent.py内部组合了两个SimpleAgentself.generate_agent SimpleAgent(name章节生成助手, llmllm, system_prompt你是一位擅长长篇小说结构与文本细化的专业作者助理。) self.review_agent SimpleAgent(name章节审核助手, llmllm, system_prompt你是一位专业的小说审核助手负责检查章节是否符合小说的结构和风格。)其运行主循环run方法是典型的生成→解析→审核→重生成闭环构建上下文读取大纲、上一章正文、前几章摘要调用get_prompt组装提示词生成并解析generate_agent.run(context)产出文本extract_json_from_response清理 Markdown 代码块标记后json.loads解析若直接解析失败会退化到截取首个{到末尾}的容错策略chapter_generate_agent.py字段校验必须同时包含title、content、next_chapter_prediction、summary四个字段缺一即视为失败并进入下一轮审核用CHAPTER_REVIEW_PROMPT从大纲契合度、原创性与故事性、人物塑造、节奏与张力四个维度评判若输出包含【通过】则跳出循环否则把上一轮生成内容与审核意见一并回填到新的提示词中重新生成保存并写入记忆通过NoteTool的create动作落盘extract_note_id用正则ID:\s*(note_[0-9_])从工具输出中提取笔记 ID随后把MemoryItem追加进内存中的self.memories[novel_id]供下一章使用。max_steps默认 5限定了最多重试轮数chapter_length默认 3000 字控制目标篇幅。在 main.py 的测试配置中两者被刻意调小为max_steps3、chapter_length1000以缩短测试耗时——这也解释了为何产出的第一章正文约千字左右而非完整三千字。三、提示词工程结构化 JSON 输出与开篇模板章节生成的质量高度依赖 agents/prompt.py 中三套提示词模板的分工1.CHAPTER_START_PROMPT开篇章节专用当get_prompt检测到无前一章且无前几章摘要is_first_chapter条件时启用。它要求模型快速建立世界观与氛围但避免枯燥的设定堆砌鲜明地引出主角展现性格特征与当前处境设置激励事件Inciting Incident打破平静生活结尾设置悬念或冲突呼应黄金三章原则。对照《代码之森》正文可验证第一段即用灰蓝色天空像被反复擦写的旧屏幕建立世界观随后用昨晚还在加班调试神经接口项目交代主角背景【警告未授权实体接触核心数据结构。】则是典型的激励事件末段要么学会重写规则要么被彻底删除留下清晰悬念。2.CHAPTER_PROMPT后续章节通用输入信息包含五个部分outline大纲、prev_chapter前一章正文、prev_summaries前几章摘要、chapter_history本章历史生成内容、evaluation上轮审核意见、user_input用户输入或下一章预测摘要。特别地当没有用户输入时user_input会回退为self.memories[novel_id][-1].next_chapter_prediction上一章对本章的预测形成上一章预测→本章兑现/惊喜的衔接机制。模板还要求预测摘要与大纲冲突时以大纲与人物逻辑为最高优先级并规定大结局章节需在title中标注大结局且next_chapter_prediction置空。3. 统一 JSON 输出契约两套生成模板都强制要求仅输出一个标准 JSON 对象{ title: 第几章-标题, summary: 本章摘要200字以内, content: 本章正文内容..., next_chapter_prediction: 下一章摘要预测包含核心冲突或悬念焦点 }这一契约同时服务于三处保存笔记时的摘要写入 tags、MemoryItem的next_chapter_prediction记忆、以及 API 层的ChapterGenerateRequest响应字段。结构化输出使生成结果可被稳定解析、持久化与二次消费。4.CHAPTER_REVIEW_PROMPT四维审核审核模板要求输出固定格式【通过】或【不通过】**具体修改建议如下**加编号建议列表。run中通过if 【通过】 in review_response: break判断是否放行审核不通过时把response_data本章已生成内容与review_response一并传入get_prompt让生成 Agent 在既有稿基础上针对性修改而不是从零重写。四、上下文构建大纲、上一章与摘要记忆的拼接run方法中通过三次调用组装上下文chapter_generate_agent.pyoutline self.get_outline(novel_id) prev_chapter self.get_prev_chapter(novel_id) prev_summaries self.get_prev_summaries(novel_id) context self.get_prompt(outline, prev_chapter, prev_summaries, user_input, novel_id, chapter_lengthchapter_length)get_outline直接扫描outline目录取第一个文件经get_content_from_note剥离 frontmatter 后作为全局约束。大纲是章节生成的第一优先级依据任何剧情决策不得与大纲冲突get_prev_chapter取记忆中最后一章的正文末尾 800 字格式化为【标题】\n...末尾正文用于保证与上一章的叙事无缝衔接get_prev_summaries汇总最近num_chapter_memories默认 5章的标题 摘要构成长期记忆避免生成中间章节时遗忘早期设定。以本次产物的上游大纲 outline/note_20260128_030758_0.md 为例大纲卷一编译错误规划的章要点 1 是穿越触发键盘蓝光吞噬章要点 2 是首遇死循环风暴而第一章正文实现了穿越后场景代码森林 系统警报 未知敌人主角名字也从大纲中的林骁变更为林澈。这一细节提示模型在生成时会基于大纲做局部演绎与再创作因此大纲与章节之间存在约束而非逐字对齐的关系。五、端到端复现从命令行到 Web API1. 环境准备按 README.md 与 requirements.txt需要 Python 3.10核心依赖包括hello-agents[all]0.2.8Agent 编排框架、fastapi、uvicorn、pydantic2.0.0与python-dotenv。在项目根目录创建.envLLM_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 PORT8000HelloAgentsLLM()默认从环境变量读取这些配置各 Agent 的构造函数均为llm: HelloAgentsLLM HelloAgentsLLM()兼容任何 OpenAI 兼容接口的模型。2. 命令行测试main.pymain.py 是完整的功能验证脚本按序执行五步生成novel_id ftest_novel_{int(time.time())}与标题测试Agent功能小说输入创意一个关于AI程序员意外穿越到自己编写的代码世界中的故事初始化OutlineAgent并生成大纲target_length1000大纲以note_id形式经 NoteTool 落盘初始化ChapterGenerateAgentmax_steps3、chapter_length1000传入第一章主角醒来发现自己在代码构成的森林里生成第一章即《代码之森》的输入来源验证outputs/{title}-{novel_id}/outline与chapters两目录存在且非空。大纲与章节的目录命名遵循outputs/{title}-{novel_id}/outline|chapters规范与本次分析产物测试Agent功能小说-test_novel_1769540842的目录结构完全一致可直接对照。3. Web APIsrc/app.pysrc/app.py 基于 FastAPI 提供 REST 接口POST /outline/generate、POST /chapter/generate、GET/PUT/DELETE系列大纲与章节操作。其中POST /chapter/generate支持num_chapters参数批量生成多章首章使用用户输入后续章节自动置空user_input交由上一章预测摘要驱动剧情推进current_input 。ProjectManager通过project_data.json维护outline_id与chapters列表的映射关系实现 API 层对本地 Markdown 存储的增删改查。启动方式python src/app.py # 或 uvicorn src.app:app --reload随后可访问http://127.0.0.1:8000/docs在线调试接口前端 frontend/index.html 可直接在浏览器打开使用。六、对生成产物的技术回读一次质量复盘将《代码之森》放回生成管线审视可以总结该架构对最终质量的四个直接影响开篇模板保障叙事任务激励事件系统警报、主角处境记忆被格式化、悬念钩子清除协议均由CHAPTER_START_PROMPT显式要求正文一一落实frontmatter 承载记忆摘要写入tags、时间戳写入created_at使get_memories无需调用模型即可完成章节索引与筛选结构化输出降低管线脆弱性JSON 契约配合双重解析容错即使模型输出带代码块标记也能稳定提取四字段审核循环存在取舍max_steps是成本与质量的平衡点——重试次数越多质量上限越高但 LLM 调用成本线性增长。本次产物在一次生成后即通过审核说明在千字篇幅与明确模板约束下单轮质量通常已达标。值得注意的边界get_outline目前简单取第一个文件get_prev_chapter仅回读末尾 800 字两者在超长篇章或目录含多个文件时的鲁棒性有限这是阅读源码时可以继续观察的演进方向。结语从《代码之森》这份真实生成产物出发本文还原了 NovelGenerator 上下文感知章节生成 Agent 的完整链路本地文件存储规范frontmatter notes_index→ 双 Agent 生成-审核闭环 → 结构化提示词契约 → 大纲/上一章/摘要三层上下文拼接 → 命令行与 API 双入口复现。这套以产物为线索、以源码为依据的拆解方法同样适用于评估 hello-agents 框架下任何 Agent 应用的输出质量与工程化程度。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 HelloAgents 的上下文感知章节生成 Agent：以 NovelGenerator《代码之森》生成实录为例
基于 HelloAgents 的上下文感知章节生成 Agent以 NovelGenerator《代码之森》生成实录为例【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents导读本文以开源仓库 hello-agents 共创项目 NovelGenerator 的实际生成产物——小说《测试Agent功能小说》第一章《代码之森》为线索深入拆解一个面向长篇小说创作的上下文感知章节生成 Agent 的实现原理。读者将掌握章节产物在本地文件系统中的存储规范、ChapterGenerateAgent的生成-审核双 Agent 闭环架构、基于大纲与记忆的上下文拼接策略以及如何通过main.py与 FastAPI 服务端到端复现一次真实的章节生成。一、从一份生成产物说起章节文件的存储规范在 outputs/测试Agent功能小说-test_novel_1769540842/chapters/note_20260128_030815_0.md 中保存着一次真实运行的章节生成结果。该文件由两部分构成1. YAML Frontmatter 元数据--- id: note_20260128_030815_0 title: 第一章-代码之森 type: chapter tags: [主角林澈在一片由流动代码构成的诡异森林中醒来……被迫面对未知世界的规则与危险。] created_at: 2026-01-28T03:08:15.761075 updated_at: 2026-01-28T03:08:15.761075 ---其中值得注意的字段id章节唯一标识由时间戳生成也是章节 Agent 与 API 层定位文件的索引键type: chapter与大纲文件的type: outline区分见 outline 目录下的同名结构这是后续get_memories按类型筛选章节笔记的依据tags存放的不是普通标签而是本章摘要。从源码看ChapterGenerateAgent.run在保存笔记时执行tags: [response_data.get(summary, )]chapter_generate_agent.py即把模型输出的摘要写入 tags 字段后续通过note[tags][0]直接读取摘要作为长期记忆。2. Markdown 正文正文即《代码之森》的完整第一章程序员林澈在一座由流动代码构成的森林中醒来触碰数据树触发系统警报遭遇清除协议与无脸黑影被迫在重写规则与被删除之间抉择。这是模型在CHAPTER_START_PROMPT开篇章节模板约束下产出的开篇章节其叙事任务快速建立世界观、引出主角、设置激励事件在正文中一一兑现。3. 配套索引文件同目录下的 notes_index.json 由 NoteTool 维护记录total_notes与每条笔记的元数据摘要。ChapterGenerateAgent.get_memories正是先读取该索引再按note_type chapter筛选最近 N 章num_chapter_memories默认 5逐条读取.md文件并剥离 frontmatter 与标题后构造成MemoryItem见 chapter_generate_agent.py。get_content_from_note中通过re.match(r^---\s*\n(.*?)\n---\s*\n, content, re.DOTALL)剥离 YAML 头、再剔除首行#标题保证了进入模型上下文的都是纯净正文。二、核心架构生成 审核的双 Agent 闭环ChapterGenerateAgentagents/chapter_generate_agent.py内部组合了两个SimpleAgentself.generate_agent SimpleAgent(name章节生成助手, llmllm, system_prompt你是一位擅长长篇小说结构与文本细化的专业作者助理。) self.review_agent SimpleAgent(name章节审核助手, llmllm, system_prompt你是一位专业的小说审核助手负责检查章节是否符合小说的结构和风格。)其运行主循环run方法是典型的生成→解析→审核→重生成闭环构建上下文读取大纲、上一章正文、前几章摘要调用get_prompt组装提示词生成并解析generate_agent.run(context)产出文本extract_json_from_response清理 Markdown 代码块标记后json.loads解析若直接解析失败会退化到截取首个{到末尾}的容错策略chapter_generate_agent.py字段校验必须同时包含title、content、next_chapter_prediction、summary四个字段缺一即视为失败并进入下一轮审核用CHAPTER_REVIEW_PROMPT从大纲契合度、原创性与故事性、人物塑造、节奏与张力四个维度评判若输出包含【通过】则跳出循环否则把上一轮生成内容与审核意见一并回填到新的提示词中重新生成保存并写入记忆通过NoteTool的create动作落盘extract_note_id用正则ID:\s*(note_[0-9_])从工具输出中提取笔记 ID随后把MemoryItem追加进内存中的self.memories[novel_id]供下一章使用。max_steps默认 5限定了最多重试轮数chapter_length默认 3000 字控制目标篇幅。在 main.py 的测试配置中两者被刻意调小为max_steps3、chapter_length1000以缩短测试耗时——这也解释了为何产出的第一章正文约千字左右而非完整三千字。三、提示词工程结构化 JSON 输出与开篇模板章节生成的质量高度依赖 agents/prompt.py 中三套提示词模板的分工1.CHAPTER_START_PROMPT开篇章节专用当get_prompt检测到无前一章且无前几章摘要is_first_chapter条件时启用。它要求模型快速建立世界观与氛围但避免枯燥的设定堆砌鲜明地引出主角展现性格特征与当前处境设置激励事件Inciting Incident打破平静生活结尾设置悬念或冲突呼应黄金三章原则。对照《代码之森》正文可验证第一段即用灰蓝色天空像被反复擦写的旧屏幕建立世界观随后用昨晚还在加班调试神经接口项目交代主角背景【警告未授权实体接触核心数据结构。】则是典型的激励事件末段要么学会重写规则要么被彻底删除留下清晰悬念。2.CHAPTER_PROMPT后续章节通用输入信息包含五个部分outline大纲、prev_chapter前一章正文、prev_summaries前几章摘要、chapter_history本章历史生成内容、evaluation上轮审核意见、user_input用户输入或下一章预测摘要。特别地当没有用户输入时user_input会回退为self.memories[novel_id][-1].next_chapter_prediction上一章对本章的预测形成上一章预测→本章兑现/惊喜的衔接机制。模板还要求预测摘要与大纲冲突时以大纲与人物逻辑为最高优先级并规定大结局章节需在title中标注大结局且next_chapter_prediction置空。3. 统一 JSON 输出契约两套生成模板都强制要求仅输出一个标准 JSON 对象{ title: 第几章-标题, summary: 本章摘要200字以内, content: 本章正文内容..., next_chapter_prediction: 下一章摘要预测包含核心冲突或悬念焦点 }这一契约同时服务于三处保存笔记时的摘要写入 tags、MemoryItem的next_chapter_prediction记忆、以及 API 层的ChapterGenerateRequest响应字段。结构化输出使生成结果可被稳定解析、持久化与二次消费。4.CHAPTER_REVIEW_PROMPT四维审核审核模板要求输出固定格式【通过】或【不通过】**具体修改建议如下**加编号建议列表。run中通过if 【通过】 in review_response: break判断是否放行审核不通过时把response_data本章已生成内容与review_response一并传入get_prompt让生成 Agent 在既有稿基础上针对性修改而不是从零重写。四、上下文构建大纲、上一章与摘要记忆的拼接run方法中通过三次调用组装上下文chapter_generate_agent.pyoutline self.get_outline(novel_id) prev_chapter self.get_prev_chapter(novel_id) prev_summaries self.get_prev_summaries(novel_id) context self.get_prompt(outline, prev_chapter, prev_summaries, user_input, novel_id, chapter_lengthchapter_length)get_outline直接扫描outline目录取第一个文件经get_content_from_note剥离 frontmatter 后作为全局约束。大纲是章节生成的第一优先级依据任何剧情决策不得与大纲冲突get_prev_chapter取记忆中最后一章的正文末尾 800 字格式化为【标题】\n...末尾正文用于保证与上一章的叙事无缝衔接get_prev_summaries汇总最近num_chapter_memories默认 5章的标题 摘要构成长期记忆避免生成中间章节时遗忘早期设定。以本次产物的上游大纲 outline/note_20260128_030758_0.md 为例大纲卷一编译错误规划的章要点 1 是穿越触发键盘蓝光吞噬章要点 2 是首遇死循环风暴而第一章正文实现了穿越后场景代码森林 系统警报 未知敌人主角名字也从大纲中的林骁变更为林澈。这一细节提示模型在生成时会基于大纲做局部演绎与再创作因此大纲与章节之间存在约束而非逐字对齐的关系。五、端到端复现从命令行到 Web API1. 环境准备按 README.md 与 requirements.txt需要 Python 3.10核心依赖包括hello-agents[all]0.2.8Agent 编排框架、fastapi、uvicorn、pydantic2.0.0与python-dotenv。在项目根目录创建.envLLM_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 PORT8000HelloAgentsLLM()默认从环境变量读取这些配置各 Agent 的构造函数均为llm: HelloAgentsLLM HelloAgentsLLM()兼容任何 OpenAI 兼容接口的模型。2. 命令行测试main.pymain.py 是完整的功能验证脚本按序执行五步生成novel_id ftest_novel_{int(time.time())}与标题测试Agent功能小说输入创意一个关于AI程序员意外穿越到自己编写的代码世界中的故事初始化OutlineAgent并生成大纲target_length1000大纲以note_id形式经 NoteTool 落盘初始化ChapterGenerateAgentmax_steps3、chapter_length1000传入第一章主角醒来发现自己在代码构成的森林里生成第一章即《代码之森》的输入来源验证outputs/{title}-{novel_id}/outline与chapters两目录存在且非空。大纲与章节的目录命名遵循outputs/{title}-{novel_id}/outline|chapters规范与本次分析产物测试Agent功能小说-test_novel_1769540842的目录结构完全一致可直接对照。3. Web APIsrc/app.pysrc/app.py 基于 FastAPI 提供 REST 接口POST /outline/generate、POST /chapter/generate、GET/PUT/DELETE系列大纲与章节操作。其中POST /chapter/generate支持num_chapters参数批量生成多章首章使用用户输入后续章节自动置空user_input交由上一章预测摘要驱动剧情推进current_input 。ProjectManager通过project_data.json维护outline_id与chapters列表的映射关系实现 API 层对本地 Markdown 存储的增删改查。启动方式python src/app.py # 或 uvicorn src.app:app --reload随后可访问http://127.0.0.1:8000/docs在线调试接口前端 frontend/index.html 可直接在浏览器打开使用。六、对生成产物的技术回读一次质量复盘将《代码之森》放回生成管线审视可以总结该架构对最终质量的四个直接影响开篇模板保障叙事任务激励事件系统警报、主角处境记忆被格式化、悬念钩子清除协议均由CHAPTER_START_PROMPT显式要求正文一一落实frontmatter 承载记忆摘要写入tags、时间戳写入created_at使get_memories无需调用模型即可完成章节索引与筛选结构化输出降低管线脆弱性JSON 契约配合双重解析容错即使模型输出带代码块标记也能稳定提取四字段审核循环存在取舍max_steps是成本与质量的平衡点——重试次数越多质量上限越高但 LLM 调用成本线性增长。本次产物在一次生成后即通过审核说明在千字篇幅与明确模板约束下单轮质量通常已达标。值得注意的边界get_outline目前简单取第一个文件get_prev_chapter仅回读末尾 800 字两者在超长篇章或目录含多个文件时的鲁棒性有限这是阅读源码时可以继续观察的演进方向。结语从《代码之森》这份真实生成产物出发本文还原了 NovelGenerator 上下文感知章节生成 Agent 的完整链路本地文件存储规范frontmatter notes_index→ 双 Agent 生成-审核闭环 → 结构化提示词契约 → 大纲/上一章/摘要三层上下文拼接 → 命令行与 API 双入口复现。这套以产物为线索、以源码为依据的拆解方法同样适用于评估 hello-agents 框架下任何 Agent 应用的输出质量与工程化程度。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考