从零搭建自我编程Agent：架构设计、代码生成与自动修复实战-北京尧图网络

开头直接从技术视角切入讲清楚这个系统的价值然后顺着架构、选型、实现、实战、避坑的顺序展开。1. 整体设计思路为什么“自我编程Agent”值得自己搭一套近两年大语言模型的应用落点越来越多地集中到 Agent 上而“自我编程 Agent”又是 Agent 里最特别的一类它不满足于聊天、总结、翻译而是直接拿代码当输出自己写函数、自己改 bug、自己跑测试甚至能根据报错信息反推修复方案。我花了大概三周时间把这样一套系统从零搭起来过程中踩了不少坑也把一些“看起来可行但实际跑不通”的思路彻底推翻重来。这篇文章把最终版本的设计思路、关键代码、踩坑记录都整理出来属于收藏级教程级别的内容。先说清楚这系统到底能干什么给它一个自然语言任务描述比如“写一个函数输入是 CSV 文件路径输出是各列缺失值统计表”它会自动拆解需求、生成代码、写入文件、尝试运行如果运行报错它还能读取错误信息自己改代码直到跑通或者达到预设的迭代上限。整个过程不需要人工干预开发者只需要最后检查它产出的代码和结果。什么人适合自己搭一套如果你已经在用代码补全类工具但你想要的不是“补全”而是“让模型独立完成一个小型开发任务”那这套系统的设计思路就会对你有用。它需要的基础技能包括熟悉大模型 API 调用方式、了解函数调用机制、有一点 Python 工程经验。难度不算高难点全在细节设计上。这里借用我实际调试时的一个体会把 Agent 想成一个刚入职的实习生它态度很好但经验不足容易犯错。你要做的不是替它写代码而是给一套明确的“工作流程反馈机制”——告诉它目标是什么让它自己动手错了就让编译器告诉它哪里错了再让它自己改。这套系统的本质就是把“带实习生”这件事标准化、自动化。整套系统由四个核心模块组成任务拆解与规划模块、代码生成模块、工具执行环境、反馈与自我修正模块。四个模块形成一个闭环任务从进入到产出每一步都有日志记录方便事后回溯。2. 核心技术选型模型、接口、环境都要配套2.1 模型选择的关键考量模型是整套系统的“大脑”选型是否合理直接决定后面工程化的工作量。我试过多款主流模型最终固定使用具备结构化输出能力的模型而不是纯粹靠提示词“希望它输出 JSON”。原因是自我编程 Agent 的运行链路中要频繁解析模型输出一旦格式不稳定解析层就得写大量容错代码越到后期越痛苦。选模型时重点看三个维度一是上下文窗口大小因为代码生成、运行日志、错误信息都要塞进对话上下文窗口太大会导致多轮迭代后信息丢失二是工具调用能力也就是模型能否理解并触发“执行代码”这样的外部动作三是输出格式遵循能力即能否稳定输出符合 JSON Schema 的结果。另外要关注的是模型在“中文任务描述”和“英文代码”之间的转换能力。实际测试中有些模型中文理解很好但生成的代码风格混乱、注释缺失有些模型代码能力很强但遇到模糊的中文需求会自行脑补不存在的功能。多测几种prompt风格后我的经验是任务描述中包含明确的输入输出示例比单纯的文字说明效果好得多。2.2 工具接口设计代码执行环境怎么封装自我编程 Agent 和普通聊天机器人最大的区别在于“工具”。聊天只需要返回文本而编程 Agent 必须操作真实环境写文件、跑代码、安装依赖、查看输出。这意味着你要把系统能力封装成一组工具暴露给模型调用。我最终设计了四个基础工具写文件工具、执行 Python 代码工具、安装依赖工具、读取文件工具。写文件工具负责把模型生成的代码落盘执行代码工具运行某个 Python 文件并返回 stdout、stderr 和退出码安装依赖工具对接 pip让模型能自行解决第三方库缺失问题读取文件工具让模型在修改代码前先看一眼已有文件内容避免盲目覆写。工具接口设计的最重要原则是返回值必须结构化、可预测。执行工具返回固定格式比如{exit_code: 0, stdout: ..., stderr: }这样模型才能准确理解执行结果。如果只是返回一段拼接文本模型经常搞不清到底哪部分是错误信息导致自我修正时答非所问。2.3 为什么不直接用现成的开源框架市面上有不少开源 Agent 框架拿来即用似乎省事。但实际体验下来框架把太多细节封装好了出问题时你很难判断是模型的问题、提示词的问题还是框架调度的问题。自己搭一套核心不是为了“重复造轮子”而是为了把链路中的每一个环节都掌握在手里后面做调试和扩展都有主动权。自建系统的另一个好处是灵活。比如我想在特定步骤插入额外校验逻辑或者对执行代码做超时控制框架里改起来很难自己写的代码里改动就是几行的事。如果你有稳定的时间和精力我建议至少自己从零搭一个最小原型跑通后再决定要不要引入现成框架。3. 核心实现细节提示词结构、状态管理和自我修正机制3.1 消息结构设计让模型始终知道“现在进行到哪一步”大模型本质上是无状态的所有“状态感知”都靠消息历史来提供。自我编程 Agent 的多轮迭代场景里消息结构尤其关键。我采用了一种类似 ChatML 的结构系统消息固定设置 Agent 的行为模式和工作原则用户消息用来描述任务工具消息用来承载代码执行结果。系统提示词里面写清楚三件事Agent 的角色是“专业的 Python 开发工程师”工作原则是“必须先理解需求再生成代码最后通过工具执行验证”每次修改代码前要先说明修改理由不允许编造执行结果。这里要特别强调系统提示词的一个细节一定要写“如果工具返回错误请根据错误信息修正代码并重试而不是解释错误原因”。我最初没有这一句模型在遇到报错时经常长篇大论分析错误原因但完全不给修改后的代码。加了这个约束后修正效率明显提升。3.2 状态管理迭代轮次、文件路径、任务目标都要跟踪为了确保多轮交互不跑偏我用一个简单的状态对象维护整场任务的元信息包含任务原始描述、当前轮次、最大迭代上限、所有生成过的文件路径列表、最近一次执行结果摘要。每一轮迭代开始前把这些元信息作为只读参考注入到用户消息中提醒模型当前进展。状态对象最简单的实现是一个 Python dataclass核心字段如下from dataclasses import dataclass, field from typing import List dataclass class TaskState: task_description: str max_rounds: int 5 current_round: int 0 generated_files: List[str] field(default_factorylist) last_execution_summary: str 每轮迭代结束时更新current_round和last_execution_summary。这个状态对象虽然简单但它解决了 Agent 最容易出现的“迷失方向”问题——模型不会忘记自己已经改过几个文件、当前卡在哪一步。3.3 代码生成与执行循环反馈回路是灵魂核心运行流程可以压缩成一句话生成代码执行把执行结果返回模型让模型判断是否完成。如果没完成就继续循环。这里面的关键在于“让模型自己判断任务是否完成”而不是由外部硬编码条件来决定。因为任务类型千变万化只有模型才理解“计算出缺失值统计表”意味着什么。我的实现方式是在每轮工具执行后把执行结果和一段询问文本一起塞回对话“以上是代码执行结果。请判断任务是否已完成。如果已完成回复 DONE如果未完成请直接输出修改后的完整代码。”这样避免了额外的一次模型调用也节省了 token。代码执行循环配合超时控制很重要。某些任务会让代码进入死循环或长时间运行我设置了单次执行超时时间为 30 秒超时直接杀进程并返回超时提示。如果没有这个机制一次测试可能卡住整个 Agent 流程好几分钟。3.4 安全沙箱千万别让 Agent 在裸环境里跑代码让模型生成的代码直接在你的开发机执行这是最危险的环节。大模型生成的代码可能意外删除文件、修改系统配置甚至故意插入恶意操作。虽然大部分场景下模型不会作恶但“意外”总是存在。我在部署时把所有代码执行都放进容器环境宿主机和容器间只挂载一个临时工作目录。容器化解决的不只是安全问题还有环境一致性问题。宿主机的 Python 环境可能缺少某个包或版本冲突而容器里是干净的镜像每次运行完直接销毁重建。我用的镜像基于精简版 Python 官方镜像包含 pip不预装任何第三方库模型需要什么库就用安装依赖工具自行安装。容器环境下代码执行工具实现时需要特别注意路径映射。宿主机的工作目录和容器内的工作目录不同日志和文件路径要标准化否则模型执行后以为自己写入了output.csv但实际上文件在容器里的另一个位置外部很难找到。4. 完整实战从任务描述到代码自动生成与修复4.1 实战任务设定一个典型的数据处理脚本为了直观展示系统的能力边界我用一个真实任务来跑完整流程“编写一个 Python 脚本读取当前目录下的 sales_data.csv该文件包含三列日期、销售额、地区。要求按地区统计销售总额输出为 summary.csv按销售额降序排列。”这个任务足够有代表性需要读文件、分组聚合、排序、写出新文件覆盖了常见的数据处理模式。我把这个任务作为初始用户消息传入同时把max_rounds设置为 5也就是允許最多循环五次生成-执行-修正的过程。执行环境是容器工作目录挂载了包含sales_data.csv的文件夹。4.2 第一轮迭代模型首先生成代码第一轮生成的代码通常是“最理所当然”的写法。模型看到需求后直接生成代码调用写文件工具写入summary.py然后调用执行工具运行。这个阶段的代码基本能完成“读文件并用 groupby 分组求和”的任务但由于任务要求“按销售额降序”第一版代码有两个常见问题一是分组后忘记排序二是输出列名和原文件列名不一致。这正是这个系统最有意思的地方模型生成的代码不是一次到位的而是需要在执行结果的驱动下自我修正。第一轮执行后返回的 stdout 为空exit_code 为 0但模型判断任务未完成原因就是缺少排序。这是模型从执行反馈中自己意识到的而不是外部规则告诉它的。4.3 第二轮迭代自我修正开始发挥作用第二轮迭代中模型阅读了上一轮的执行摘要和文件内容生成修改后的代码将sort_values加进去同时统一了列名。执行后退出码仍然是 0模型查看输出文件内容后确认数据已正确排序最终回复 DONE。整个任务从开始到结束耗时约两分半钟花费一次模型调用和一次修正调用。这是比较顺利的情况。我在测试中还遇到过完全不顺利的情况模型生成的代码包含语法错误执行工具返回了 traceback模型第二轮的修复方案居然是给整个文件包上一层 try-except 并直接打印“成功”——这属于典型的“掩盖问题”反而不是修复问题。4.4 对代码质量的隐性检查模型自己看得懂自己的输出迭代结束后我会额外要求模型做一次“自审”描述它生成代码的逻辑结构、依赖的第三方库、运行注意事项。这一步不是为了给模型自己看而是为了给开发者省去通读代码的时间。模型描述出来的内容如果和实际代码不符说明生成过程有幻觉成分需要重点检查。从实际测试来看自审描述和代码逻辑的一致性大约在九成左右剩下的一成要么是模型对某些 Python 内置函数的行为理解有误要么是它高估了自己代码的健壮性比如没考虑空文件、列名含空格等边界情况。这也是为什么最后的人工代码审查环节不能省。5. 常见问题与排查技巧实录5.1 模型“假装成功”没有报错但结果明显不对这是我遇到频率最高的问题。具体表现为代码执行 exit_code 为 0没有报错模型满意地输出 DONE但检查产出文件发现内容是空的或者列数不对。原因是模型在生成代码时使用了不存在的列名Pandas 在按列名读取时会抛 KeyError但某些写法下错误被吞掉了或者模型把错误 try-except 掉了。排查思路是先看生成文件的字节大小。如果目标输出文件大小为零基本可以断定数据处理没有正确执行。修复方法是追加一条约束到系统提示词“任务完成后必须验证输出文件非空且结构符合预期不得只依赖 exit_code 判断成功。”这一条加上后类似问题少了很多。5.2 上下文膨胀导致执行效率下降多轮迭代后对话历史里塞满了完整代码、运行输出、错误堆栈token 消耗越来越大模型调用延迟也越来越高。极端情况下上一轮的代码内容在新一轮回复里被反复引用token 浪费严重。我的处理方案是引入“压缩机制”每轮执行结束后把完整的 stdout 和 stderr 做截断只保留最后 1000 个字符作为摘要写回对话。代码文件本身不需要完整保留在消息里因为模型可以通过读取文件工具随时查看。这个改动让平均 token 消耗降低了约三成而且没有影响任务完成质量。5.3 依赖安装失败导致反复尝试模型在容器环境里安装第三方库常见的问题是网络不稳定导致 pip 下载失败。模型第一轮安装失败后会把报错信息当作代码错误来修生成一个没有任何意义的“修复版”代码。这个坑很隐蔽因为它不是代码逻辑问题而是环境问题。解决办法是在工具返回错误时加入错误类型识别标签比如[NETWORK_ERROR]或[SYNTAX_ERROR]模型看到网络错误标签后就不会试图改代码而是直接重新尝试安装或者换源。这个小改动让依赖问题的处理准确率提高了很多。5.4 识别“循环修复但永远修不好”的死局有些任务会让 Agent 陷入循环改一个 bug引入一个新 bug再改新 bug再引出另一个新 bug直到达到迭代上限还停不下来。这类死局通常发生在需求本身和代码实现方向不匹配的情况下。我设置了一个简单的“方向漂移检测”如果模型连续两轮修改后的代码结构发生了大幅变化比如从 pandas 写法突然变成了纯 Python 循环实现就判定方向不稳定主动将对话回退到上一轮的稳定版本切换策略为“先生成最小实现再逐步加功能”。绕开死局比硬碰硬修 bug 高效得多。5.5 小技巧用日志记录每一轮的关键决策开发调试过程中我养成了一个习惯把每一轮迭代中模型的“理由叙述”单独提取出来存成日志。理由叙述虽然不影响代码执行但它是判断模型思考质量的最直观材料。模型如果说“我改用另一种方法更稳妥”这是正常的策略调整模型如果说“我认为原代码可能有问题所以加了防御性分支”要警惕它是否在无中生有。6. 扩展思路这套系统未来还能怎么用自我编程 Agent 搭好基础版本后后面能扩展的方向很多。我最先尝试的是给它接入“测试生成”能力任务完成后让模型自动生成对应的单元测试并运行验证。这一步对代码质量的保障作用很大相当于把“自我编程”升级成了“自我测试”。另一个方向是把文件读写工具替换成 Git 操作工具让 Agent 直接完成 commit 和 push 操作。这样它就能完整地“写代码—验证—提交”更接近真实开发流程。但这一步要格外谨慎建议先在私有仓库的独立分支上试用避免污染主分支。再有就是任务拆解的深化。目前系统处理的是单体脚本类任务如果任务复杂度再上一个台阶比如“实现一个包含多个模块的小型服务”单轮规划就不够用了需要引入任务拆分成子任务的能力让 Agent 像一个真正的工程师一样分模块开发、独立测试、最后集成。我在实际使用中的体会是这套系统的上限并不完全取决于模型的能力更取决于工程细节的设计。提示词的结构、工具的返回值格式、循环的控制策略每一点都直接影响最终效果。第一次跑通时你可能会觉得“就这”但当你真正拿它去处理一批任务观察它在失败时如何自我修正就会意识到这已经是开发模式开始转变的信号。后续如果你也在搭类似的系统建议从最小闭环开始先把“生成—执行—反馈—再生成”这条路走顺再去加更多花哨的功能。基础循环稳定了一切才有的谈。

从零搭建自我编程Agent：架构设计、代码生成与自动修复实战

相关推荐

无线安全实战：802.11帧结构、WPA2握手与离线破解原理

C++函数重载底层原理：名字修饰、重载决议与二义性一次讲透

TensorFlow环境配置完全指南：版本选型、GPU验证与排错实战

更多资讯

HF 热度榜从第 6 滑到第 24：全网围观后，N2.5-mini 的“冷静期”到了

claude-watch 核心原理揭秘：ffmpeg 场景切换帧提取如何让 Token 成本保持平坦

U-Net图像分割实战指南：原理详解与PyTorch实现

OpenClaw智能体框架实战：五分钟接入QQ机器人全流程

开源轻量AI工具：嵌入Office/浏览器的生产力副驾

基于YOLO的跌倒检测实战：从数据处理到模型部署全流程解析

今日更新

智能硬件视频会议集成：从芯片选型到场景落地的全栈实践

FFmpeg音视频处理与5路RTMP推流实战：从原理到118克盒子部署

RK3528+1GB内存如何变身直播节点？硬编解码与六协议实战复盘

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？