Hello-Agents 共创实战：用 Reflection 反思机制构建 CodePlanAgent 智能代码规划工具

Hello-Agents 共创实战用 Reflection 反思机制构建 CodePlanAgent 智能代码规划工具【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents本文基于 Hello-Agents 仓库中Co-creation-projects/yangyousan123-CodePlanAgent共创项目展开讲解一个基于 hello-agents 框架、内置生成—反思—优化迭代闭环的 CodePlanAgent 的完整实现原理与使用方法。读完本文你将掌握如何用 Agent 基类、LLM 封装、消息与流式事件等框架能力实现一个智能代码计划生成器理解 Reflection 机制中计划记忆PlanMemory 七维度评审 早停策略的源码级设计并能按照文档给出的配置步骤在本机跑通demo.py演示。一、项目定位从自然语言需求到结构化代码计划CodePlanAgent 是 Hello-Agents 社区仓库 Co-creation-projects 共创区贡献的一个共创项目定位为基于 HelloAgents 框架的智能代码计划工具。它解决的核心问题是把一句自然语言的需求描述例如用 Flask 写一个待办事项应用转化为一份结构化的、可直接指导编码的代码实现计划包含项目概述、技术栈、目录结构、实现步骤、关键设计与注意事项等固定章节。与普通一次性让 LLM 输出计划的做法不同该项目的最大特点是内置了Reflection 反思机制初始计划生成后由一个技术评审专家角色从七个维度进行评估若评估结果不是无需改进则由计划优化器根据反馈重写计划如此迭代直到计划收敛或达到最大迭代次数默认 2 轮。整个项目文件极简核心只有三个文件code_plan_agent.py核心实现包含PlanMemory、CodePlanAgent与工厂函数demo.py使用示例演示待办事项应用计划生成requirements.txt依赖声明仅一项hello-agents1.0.0注意该文件实际为 UTF-16LE 编码用普通文本工具打开可能乱码。运行产物则落在项目内的outputs/与memory/traces/目录仓库中已附带一份真实运行结果 outputs/todo_app_plan.md可对照本文理解输出格式。二、系统架构五个核心组件与两条反馈回路项目 README 用一张 Mermaid 流程图描述了整体架构其要点可以概括为一个核心智能体 四个内部角色 一个记忆模块图示源自 README 系统架构图已精简样式。2.1 核心组件与代码落地位置组件职责源码落点CodePlanAgent核心智能体编排生成、反思、优化全流程code_plan_agent.py#L59代码计划生成器根据需求生成结构化计划_generate_code_plan()见 code_plan_agent.py#L226-L247反思评估器七维度评审当前计划_reflect_on_plan()见 code_plan_agent.py#L249-L288计划优化器按反馈重写计划_refine_plan()见 code_plan_agent.py#L290-L327计划记忆模块存储计划/反思/优化的全轨迹PlanMemory见 code_plan_agent.py#L16-L56从源码结构看所谓生成器/评估器/优化器并不是三个独立的 Agent 实例而是CodePlanAgent内部三个职责单一的私有方法分别构造不同的 system/user prompt 后调用同一个 LLM。这种单 Agent 多角色的写法比多 Agent 互相对话更省 token、链路更可控是 Reflection 范式的典型简化实现。2.2 PlanMemory轻量级轨迹记忆PlanMemory是一个纯内存的列表容器每条记录带typeplan/reflection/revision、content、metadata与时间戳见 code_plan_agent.py#L23-L30。它提供三个关键查询接口get_trajectory()把全部记录按类型拼接成带分隔符--- 代码计划 ---、--- 反思反馈 ---、--- 优化后计划 ---的连贯文本用于事后追溯整个规划过程CodePlanAgent.get_plan_trajectory()直接暴露该能力见 code_plan_agent.py#L618-L620get_last_plan()倒序遍历返回最近一条plan或revision记录——这意味着优化后的计划会自然顶掉旧计划成为下一轮反思的输入这正是迭代闭环能成立的关键get_last_reflection()返回最近一次反思反馈。值得注意的是run()入口处会先执行self.memory PlanMemory()重置记忆code_plan_agent.py#L184保证每次任务从零开始历史轨迹不跨任务污染。README 项目结构中还列出了memory/traces/下按时间戳命名的 HTML/JSONL trace 文件从该目录命名推断框架侧可能另有一套轨迹持久化机制但当前仓库的项目目录中仅存在outputs/未包含这些 trace 文件此处不做展开。三、核心执行流程run() 方法逐段解析CodePlanAgent继承自 hello-agents 框架的Agent基类构造时引入框架的HelloAgentsLLM、Config、Message、ToolRegistry等模块文件头部导入见 code_plan_agent.py#L7-L13。其构造函数参数与默认值如下参数默认值说明name必填Agent 名称工厂函数固定为CodePlanAgentllm必填HelloAgentsLLM实例system_prompt内置规划专家提示词定义角色与输出格式见下文configNone框架配置对象max_reflection_iterations2最大反思—优化轮数tool_registryNone可选工具注册表enable_tool_callingTrue是否启用 Function Callingmax_tool_iterations3工具调用循环的最大迭代次数参数清单来自 code_plan_agent.py#L81-L104。3.1 默认系统提示词把输出格式写死在 prompt 里构造函数内置了一份资深软件架构师/代码规划专家系统提示词code_plan_agent.py#L106-L155核心是要求模型按如下固定章节输出计划## 项目概述 [简要描述项目目标和核心功能] ## 技术栈 - 语言[编程语言] - 框架[主要框架] - 数据库[数据库类型] - 其他[关键依赖] ## 目录结构 [项目目录结构] ## 实现步骤 1. [步骤1描述] - 实现要点[关键实现细节] - 文件路径[涉及文件] - 预期输出[预期结果] 2. ... ## 关键设计 - [设计决策1][说明原因] ## 注意事项 - [注意事项1]这种格式即契约的做法让下游人工审阅或后续代码生成 Agent可以按章节稳定解析计划内容。3.2 run()生成 → 反思 → 早停 → 优化同步入口run(input_text, **kwargs)的主循环code_plan_agent.py#L170-L224可拆为四步重置记忆并生成初始计划_generate_code_plan()将需求描述包进请根据以下需求描述生成一份详细的代码实现计划的 user prompt调用 LLM 得到初始计划记为plan反思每轮调用_reflect_on_plan()评估当前计划记为reflection早停判断若反思文本包含无需改进或英文no need for improvement立即break结束循环——这是防止过度迭代、越改越差的廉价而有效的收敛策略优化否则调用_refine_plan()结合原始需求 当前计划 评审反馈重写完整计划记为revision。循环结束后get_last_plan()取出最终计划并把用户需求 最终计划作为 user/assistant 两条Message追加进 Agent 消息历史code_plan_agent.py#L221-L222使同一 Agent 实例可支持多轮规划对话。整个循环默认最多执行 2 轮反思工厂函数create_code_plan_agent()显式传入了max_reflection_iterations2见 code_plan_agent.py#L623-L637。对应的 README 工作流程描述为用户输入需求 → PlanGenerator 生成初始计划 → Reflector 反思评估 → 需要改进则 Refiner 优化 → 重复直到无需改进 → 输出最终计划。3.3 反思评估器七个评审维度_reflect_on_plan()的评审 prompt 是本项目的质量核心code_plan_agent.py#L261-L281system 角色设定为严格的技术评审专家user 侧要求从七个维度评估并给出具体改进建议完整性是否覆盖所有核心需求、有无功能遗漏可行性技术方案是否可行、有无技术风险架构合理性模块划分是否合理、接口设计是否清晰可维护性代码结构是否清晰、是否遵循最佳实践性能考虑有无性能优化空间或潜在瓶颈安全性有无安全风险、是否需要安全措施测试覆盖是否考虑测试策略、关键路径有无测试覆盖。输出要求很关键如果计划已经很好请回答无需改进——这句指令正是 3.2 节早停判断能命中的语言契约。3.4 可选能力Function Calling 与流式执行_get_llm_response()code_plan_agent.py#L329-L419实现了带工具调用的 LLM 调用封装当enable_tool_calling开启且存在tool_registry时循环调用invoke_with_tools()tool_choiceauto把助手tool_calls追加进消息历史、逐个解析 JSON 参数并复用基类_execute_tool_call()执行工具结果以role: tool消息回注参数解析失败会回注错误说明而非中断。若达到max_tool_iterations默认 3仍未收敛则退回普通invoke()取最终文本回答。若未配置工具注册表则直接走无工具的invoke()路径。arun_stream()code_plan_agent.py#L421-L616则是同一流程的异步流式版本通过StreamEvent/StreamEventType对外发布结构化事件AGENT_START→ 计划生成STEP_START 逐LLM_CHUNKSTEP_FINISH→ 每轮反思THINKINGchunk 实时透出评审思考→ 优化LLM_CHUNK→AGENT_FINISH携带total_iterations异常时发出ERROR事件并向上抛出。这对构建实时展示生成—反思—优化过程的前端界面非常有用。四、配置与运行4.1 环境准备按照 README 配置步骤完整流程为四步# 1. 安装依赖依赖仅一项hello-agents1.0.0 pip install -r requirements.txt # 2. 复制 .env.example 为 .env cp .env.example .env # 3. 在 .env 中配置 LLM 环境变量 # 4. 运行 demo 查看效果 python demo.py.env需要包含三个变量demo.py的load_env()会强制校验缺失即退出见 demo.py#L9-L22LLM_MODEL_ID模型名称LLM_API_KEYAPI 密钥LLM_BASE_URLOpenAI 兼容接口的 base URL。README 提到.env.example模板覆盖 OpenAI、DeepSeek、Qwen、Kimi、Zhipu、Ollama 等常用 LLM 服务需要说明的是当前仓库的项目目录中仅保留了requirements.txt、code_plan_agent.py、demo.py、README.md与outputs/未见.env.example文件实体实际配置时可参照上述三个变量名自行创建.env。4.2 最小使用代码README 给出的最小用法如下只需初始化 LLM、创建 Agent、调用run()from hello_agents.core.llm import HelloAgentsLLM from code_plan_agent import create_code_plan_agent # 初始化LLM llm HelloAgentsLLM( modelyour-model, api_keyyour-api-key, base_urlhttps://api.example.com/v1 ) # 创建CodePlanAgent agent create_code_plan_agent(llm) # 生成代码计划 requirements 创建一个待办事项应用... plan agent.run(requirements) print(plan)demo.py在此基础上示范了两个工程化细节一是用较低温度与较大的max_tokens换取更确定性的计划输出temperature0.2, max_tokens4096见 demo.py#L36-L42二是把run()结果落盘为 Markdown 便于审阅requirements1 创建一个简单的待办事项(Todo)应用使用Python和Flask框架实现 功能需求 1. 添加待办事项标题、描述、截止日期 2. 删除待办事项 3. 标记待办事项为已完成/未完成 4. 按状态筛选待办事项全部/已完成/未完成 5. 数据持久化存储使用SQLite 技术要求 - 使用Flask框架 - 使用SQLAlchemy ORM - 提供RESTful API接口 - 支持JSON格式数据 - 包含基本的错误处理 plan1 agent.run(requirements1) with open(./outputs/todo_app_plan.md, w, encodingutf-8) as f: f.write(plan1)demo 中还以注释形式保留了一个用户认证系统FastAPI PostgreSQL JWT bcrypt的第二个示例需求取消注释即可运行见 demo.py#L80-L107。4.3 真实输出示例反思效果从何而来仓库自带的运行结果 outputs/todo_app_plan.md 是观察 Reflection 机制价值的最佳样本。该计划最终呈现了项目概述 / 技术栈 / 目录结构 / 实现步骤 / 关键设计 / 注意事项六节结构其中多处文本能直接看出经过了评审—修正项目概述中写道基于评审反馈我们修正了架构描述与实际目录的一致性移除了未实现的Repository术语明确采用 Controller-Service-Model 分层架构关键设计一节明确记录了修正过程修正了原计划中提及Repository但无对应目录的问题并解释了测试环境用db.create_all()替代 Alembic 迁移的取舍注意事项中出现了自我权衡本计划采用了企业级实践Pydantic, Alembic, 分层对于简单 Todo需求属于适度超前——这种对自身方案复杂度的诚实评估正对应评审维度中的可行性与可维护性检查。可见反思轮次并非仅仅润色文字而是能发现计划内部自相矛盾术语与目录不一致、环境兼容性问题SQLite 内存库跑不了 Alembic这类实质缺陷这正是相比单次生成的增量价值。五、设计要点小结与延伸阅读把 CodePlanAgent 的设计拆开来有三个值得复用到自己项目中的模式格式即契约把期望输出的章节结构写进 system prompt让计划变成可解析、可评审、可追溯的结构化产物而非一段散文记忆驱动闭环PlanMemory用get_last_plan()让最新计划自动成为下轮反思输入配合无需改进早停词用最小机制实现收敛轨迹文本get_trajectory()则天然支持过程审计角色切换而非多 Agent 编排生成、评审、优化共用一个 LLM 实例仅切换 system prompt 与输入拼装方式降低了多 Agent 系统的延迟与成本从源码结构看这也让整条链路更容易调试和单步验证。局限方面README未来改进一节列出了作者的规划方向增强反思深度、支持多格式输出、集成代码生成、优化性能、增加团队协作能力。就现状而言反思是否收敛完全依赖模型对无需改进字面指令的遵循且PlanMemory不落盘每次run()重置如需跨会话复用规划经验或接入持久化 trace需要自行扩展。如果你想进一步了解本项目所处的框架上下文可以参阅本书教程中的经典范式章节 第四章 智能体经典范式构建Reflection 范式即在其中以及共创项目区的贡献规范 Co-creation-projects/README.md——该项目遵循了用户名-项目名的目录命名与 README/requirements 必备结构要求是社区共创项目的一份典型样本。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考