DevLooper：基于LLM与沙箱环境的自我纠错程序合成智能体实践

1. 项目概述：一个能自我纠错的程序合成智能体

最近在探索AI编程辅助工具的边界时，我接触到了一个名为devlooper的开源项目。它本质上是一个程序合成智能体，但它的工作方式让我觉得非常有意思：它不只是根据你的描述生成代码，而是会像一个有经验的开发者一样，运行测试，并根据测试结果自动修复代码，直到所有测试通过为止。这听起来是不是有点像拥有了一个不知疲倦、能自己调试代码的初级程序员搭档？

这个项目由Modal Labs团队发布，核心思想是赋予大型语言模型（LLM）一个“执行环境”和“反馈循环”。传统的代码生成工具，比如基于GPT的代码补全，生成一段代码后，对错与否、能否运行，完全依赖开发者自己来判断和调试。而devlooper构建了一个闭环：生成代码 -> 在隔离的沙箱中运行测试 -> 分析失败结果 -> 制定修复计划 -> 执行修复 -> 再次测试，如此循环，直到成功。它解决的核心痛点是将一次性的、静态的代码生成，变成了一个动态的、自我迭代的“开发-测试-调试”自动化流程。

想象一下这个场景：你对它说“帮我写一个生成Voronoi图的Python库”。它不会只给你一堆可能跑不通的代码文件。相反，它会开始一个迭代过程，先搭建基础环境，生成初始代码，运行测试（项目内置了简单的测试框架），发现缺少numpy包，于是自动安装；然后测试可能发现某个函数边界条件处理错误，它再分析报错信息，定位到具体文件进行修改。官方演示中，完成这个任务用了11次迭代。这非常适合需要快速原型验证、或者构建具备基础功能的脚手架项目的场景，尤其适合全栈开发者、独立开发者或者希望自动化部分重复性编码工作的团队。

2. 核心架构与工作原理深度解析

devlooper的巧妙之处在于它没有重新发明轮子，而是像一个优秀的系统集成者，将几个成熟的技术点串联起来，形成了一个智能闭环。要理解它，我们需要拆解它的几个核心组件。

2.1 基石：扩展的Smol-Developer与模态计算

项目的起点是 smol-developer ，一个轻量级的、由提示词驱动的代码生成工具。devlooper在它的基础上，增加了两个关键能力：执行环境和迭代逻辑。它不再满足于“说出”代码，而是要“跑通”代码。

执行环境的核心是 Modal 平台提供的沙箱（Sandbox）功能。你可以把Modal沙箱理解为一个高度可控、按需启动、用完即弃的云端容器环境。devlooper利用这个沙箱，为每一次代码生成和测试运行提供了一个干净的、隔离的“工作间”。这样做的好处显而易见：第一，完全隔离，不会污染本地或服务器环境；第二，环境可复现，确保了每次测试的基准一致；第三，Modal的沙箱支持增量构建镜像层并缓存，这意味着如果只是修改代码而不改变依赖，后续迭代可以复用之前的镜像层，极大加快了调试循环的速度。

注意：Modal虽然功能强大，但其商业模式和网络访问特性需要使用者自行了解和评估。devlooper选择它，主要是看中了其沙箱功能的便捷性和与Python生态的良好集成。理论上，任何能提供类似隔离容器执行能力的平台（如基于Docker的定制方案）都可以作为替代后端，但需要投入相当的开发工作量。

2.2 环境模板：定义项目的“基因”

为了让智能体知道如何在目标环境中工作，devlooper引入了环境模板（EnvTemplate）的概念。一个模板定义了某个技术栈项目的基本结构和测试方法。目前官方提供了三个模板：

• Python: 通常使用pytest或内置的unittest作为测试运行器。
• React + Jest: 用于前端JavaScript/TypeScript项目，配置了Jest测试框架。
• Rust: 使用cargo test来运行测试。

每个模板主要包含几个关键信息：

1. 基础镜像：例如，Python模板可能基于python:3.11-slim。
2. 安装命令：如何安装依赖（如pip install -r requirements.txt）。
3. 测试命令：运行测试的具体指令（如python -m pytest）。
4. 初始文件结构：可能会预先创建一个简单的test_*.py文件框架，引导LLM按照正确格式编写测试。

模板的作用是给LLM划定一个明确的“工作上下文”。当用户指定--template="python"时，智能体就知道它应该生成Python代码，用pip管理依赖，并用pytest风格的测试。这大大降低了LLM的认知负担，使其输出更加规范。社区贡献新的模板（如Go、Java）是项目演进的重要方向，这体现在env_templates.py文件中，结构清晰，易于扩展。

2.3 调试循环：智能体的核心“思考”过程

这是devlooper最精髓的部分，我把它称为“感知-思考-行动”循环。每一次迭代，都是一次完整的OODA循环（观察、判断、决策、行动）。

1. 执行与观察（Run Tests）：智能体在沙箱中执行当前模板定义的测试命令。它并不关心测试内容是什么，只关注结果：退出代码（Exit Code）。0代表成功，非0代表失败。同时，它会捕获所有的标准输出（stdout）和标准错误（stderr），这些是宝贵的“症状”信息。

2. 诊断与判断（Diagnose Error）：如果测试失败，原始的失败日志（stdout/stderr）会连同当前的代码上下文一起，提交给LLM（默认是GPT-4）。这里有一个关键设计：LLM的任务首先是“诊断”，而不是直接“开药方”。它会分析日志，判断错误类型：是语法错误（SyntaxError）？是导入错误（ModuleNotFoundError）？还是逻辑错误（AssertionError）？并给出一个文本描述的诊断报告，比如“在voronoi.py第32行，calculate_edges函数在处理空输入时未返回预期值，导致断言失败”。

3. 规划与决策（Generate DebugPlan）：基于上一步的“诊断报告”，另一个LLM调用被触发，用于生成一个结构化的DebugPlan。这个计划是一个具体的行动清单，目前支持三种操作类型：

   • Inspect and fix a file: 检查并修复某个文件。计划中会包含文件路径和具体的修改指令或代码块。
   • Install a package: 在容器镜像中安装某个包。例如，诊断发现缺少numpy，计划就会包含pip install numpy。
   • Run commands in the image: 在镜像中运行任意命令。这可能用于执行数据准备、环境变量设置等辅助操作。

   将“诊断”和“计划”分两步走，是一个被实践证明有效的策略。这类似于人类的调试过程：我们先看懂报错信息（诊断），再决定是改代码、加依赖还是改配置（计划）。这种“思维链（Chain-of-Thought）”式的设计，显著提高了LLM行动计划的准确性和可靠性。

4. 行动与验证（Execute Plan）：智能体忠实地执行DebugPlan中的每一条指令。该改代码的改代码，该装包的装包。所有操作都在同一个沙箱会话中进行，状态得以保留。执行完毕后，循环回到第1步，再次运行测试。

这个循环会一直持续，直到测试全部通过，或者达到预设的最大迭代次数。当循环成功退出时，最终通过的代码会被保存到本地的output/目录中。

3. 从零开始实操：搭建与运行你的第一个DevLooper项目

理解了原理，手痒想试试看？我们来一步步搭建环境并运行一个实例。整个过程主要围绕Modal和OpenAI API的配置展开。

3.1 前期准备与账户配置

首先，你需要准备好两个核心服务的访问权限：

1. Modal账户：访问Modal官网进行注册。目前Modal可能处于邀请制或有限公测阶段，如果遇到等待列表，可以尝试联系其团队（如官方README中提到的邮箱）。注册成功后，记下你的账户信息。
2. OpenAI API密钥：你需要一个有效的OpenAI账户，并在其平台生成一个API Key。确保该Key有足够的余额，并且你了解其计费方式（GPT-4的调用成本不低，尤其是在多次迭代的调试循环中）。

3.2 本地环境搭建与初始化

假设你的本地开发环境是macOS/Linux系统，并已安装Python 3.8+和Git。

# 1. 克隆项目仓库到本地 git clone https://github.com/modal-labs/devlooper.git cd devlooper # 2. 创建并激活一个虚拟环境（强烈推荐，避免包冲突） python -m venv venv source venv/bin/activate # Linux/macOS # 对于Windows: venv\Scripts\activate # 3. 安装项目依赖，核心就是modal客户端 pip install modal # 也可以选择从项目的requirements.txt安装（如果有的话） # pip install -r requirements.txt

3.3 关键步骤：Modal身份验证与密钥配置

这是将本地环境与云端Modal服务连接起来的关键一步。

# 在终端执行以下命令，这会打开浏览器引导你完成登录和授权 modal token new

执行后，终端会打印一个链接，点击它或在浏览器中打开，按照指引登录你的Modal账户并授权。成功后，Modal的访问令牌（Token）会自动保存到你的本地配置中（通常是~/.modal.toml）。

接下来，需要将你的OpenAI API Key安全地配置到Modal中，供云端函数访问。我们不能将API Key硬编码在代码里。

# 创建一个名为`openai-secret`的Modal密钥，将你的API Key存入其中 modal secret create openai-secret openai_api_key=你的OpenAI-API-Key

例如：modal secret create openai-secret openai_api_key=sk-...。这条命令会在Modal云端创建一个加密存储的密钥，在devlooper运行时，程序可以安全地读取它，而不会暴露在代码或日志中。

实操心得：modal token new是认证本地客户端，modal secret create是在云端存储敏感信息。两者缺一不可。务必确保你创建的秘密名称与代码中引用的名称一致（默认是openai-secret）。

3.4 运行你的第一个程序合成任务

配置完毕，现在可以体验devlooper的魔力了。项目使用modal run命令来在云端触发执行。基本语法是：

modal run src.main --prompt="你的项目描述" --template="模板名称"

让我们尝试生成一个简单的Python爬虫工具：

modal run src.main --prompt="a Python script that fetches the title from a given URL and prints it" --template="python"

执行这条命令后，会发生以下事情：

1. 本地CLI会将任务提交到Modal云端。
2. Modal会根据src.main中的定义，启动一个包含devlooper代码的容器。
3. 容器内的智能体开始工作：初始化Python模板环境，理解你的提示词，生成初始的Python脚本和对应的测试文件。
4. 进入调试循环：运行测试 -> 分析失败 -> 修改代码/安装依赖（比如发现需要requests和beautifulsoup4库）-> 再测试。
5. 最终，当测试通过，或者达到迭代上限（默认可能是20次），容器会停止，并将生成的代码文件打包下载到你本地的output/目录（默认路径，可通过--output-path覆盖）。

你可以打开output/目录，查看生成的main.py（或类似文件）和test_main.py，观察智能体是如何构建代码和测试用例的。

更多运行示例：

• 生成一个Rust版本的命令行计算器：modal run src.main --prompt="a simple command-line calculator that supports add, subtract, multiply, divide" --template="rust"
• 生成一个React待办事项应用组件：modal run src.main --prompt="a TodoList React component with add, delete, and toggle completion features" --template="react"

4. 核心机制与技术细节探讨

要真正用好devlooper，或者想在其基础上进行二次开发，我们需要深入它的几个核心机制。

4.1 沙箱交互与状态管理

devlooper与Modal沙箱的交互是其稳定运行的基石。它并非每次迭代都创建一个全新的容器，而是利用沙箱会话（Session）的持久性。大致流程如下：

# 伪代码，示意流程 with modal.Sandbox() as sandbox: # 1. 初始设置：基于模板，可能执行基础镜像拉取、初始包安装 sandbox.run("pip install pytest") # 示例 # 2. 写入初始生成的代码文件 sandbox.write_file("/root/main.py", generated_code) sandbox.write_file("/root/test_main.py", generated_test) iteration = 0 while not tests_passed and iteration < max_iterations: # 3. 运行测试命令，捕获输出 result = sandbox.run("cd /root && python -m pytest test_main.py -v") if result.exit_code == 0: tests_passed = True else: # 4. 将result.stdout, result.stderr发送给LLM诊断 diagnosis = llm_diagnose(result.stdout, result.stderr, current_files) # 5. 根据诊断生成DebugPlan plan = llm_plan(diagnosis) # 6. 执行Plan中的每一条Action for action in plan.actions: if action.type == "install": sandbox.run(f"pip install {action.package}") elif action.type == "write_file": sandbox.write_file(action.path, action.content) # ... 其他action类型 iteration += 1 # 7. 测试通过，从沙箱中读取最终文件 final_code = sandbox.read_file("/root/main.py")

这种“长生命周期的沙箱会话”模式，使得依赖安装、文件修改等操作产生的副作用可以累积，模拟了真实的开发过程，也充分利用了Modal的缓存机制提升速度。

4.2 提示词工程：引导LLM有效协作

devlooper的成功很大程度上依赖于精心设计的提示词（Prompt），这些提示词引导GPT-4扮演不同的角色。主要涉及两个核心提示：

1. 诊断提示词（Diagnosis Prompt）：当测试失败时，系统会将错误日志、相关源代码片段和当前文件列表喂给LLM。提示词会要求LLM扮演一个“资深调试工程师”，分析错误根源，用清晰的自然语言描述问题所在，并指出可能涉及的文件。它不直接给出修改方案，这确保了思考的专注性。提示词中可能包含这样的指令：“你是一个专家软件工程师。以下是测试运行失败后的输出。请分析根本原因，用一句话描述问题，并指出哪个源代码文件最可能需要修改。”

2. 规划提示词（Planning Prompt）：基于上一步的诊断报告，系统会再次调用LLM，但这次是要求它生成结构化的DebugPlan。提示词会定义好DebugPlan的JSON格式，包括actions列表，每个动作有type、description、target（如文件名）、content（如新代码）等字段。这相当于给LLM一个严格的输出模板，确保返回的结果能被程序准确解析和执行。例如：“根据以上诊断，请生成一个具体的修复计划。计划必须是一个JSON对象，包含一个‘actions’数组。每个动作可以是‘write_file’、‘install_package’或‘run_command’类型...”

这种“分而治之”的提示策略，比让LLM一次性完成“看错误->改代码”要可靠得多，也更容易针对每一步进行优化和调整。

4.3 DebugPlan行动系统的扩展性

目前DebugPlan支持三种基础操作，这已经能覆盖大部分初级调试场景。但它的设计是易于扩展的。例如，我们可以设想添加更多操作类型：

• create_file: 创建一个全新的文件。
• delete_file: 删除一个文件。
• execute_script: 运行一个复杂的多步骤脚本。
• modify_test: 直接修改测试用例本身（当智能体认为测试本身有误时，需谨慎）。

扩展的方法通常是在src/目录下的相关文件（如debug_plan.py）中定义新的动作类型枚举（Enum），并在执行器（executor.py或类似文件）中实现该类型动作对应的沙箱交互逻辑。这种插件式的架构，让devlooper的调试能力具备了很大的成长空间。

5. 实战经验、常见问题与优化策略

在实际使用和研读devlooper代码的过程中，我积累了一些经验，也发现了一些潜在的挑战和优化点。

5.1 提高成功率的关键：编写清晰的提示词

智能体的表现很大程度上取决于你给的“任务说明书”（即--prompt参数）。模糊的提示会导致模糊甚至错误的结果。

• 反面例子：--prompt="make a website"（过于宽泛，智能体不知道用什么技术栈、具体什么功能）。
• 正面例子：--prompt="a Python Flask web server with one endpoint /health that returns JSON {'status': 'ok'}. Include a unit test using pytest."（明确的技术栈、具体的功能、甚至指定了测试框架）。

技巧：在提示词中“植入”一些约束或最佳实践，比如“请使用Pydantic进行数据验证”、“请为每个函数添加docstring”、“请遵循PEP 8代码风格”。虽然LLM不一定百分百遵守，但能显著提高输出代码的质量。

5.2 控制成本与迭代次数

使用GPT-4进行多轮调试，成本是必须要考虑的因素。一次复杂的任务，进行十几轮迭代，花费数美元是很可能的。

• 设置迭代上限：devlooper应该有内置的最大迭代次数参数（可能在代码常量中定义，如MAX_ITERATIONS = 20）。在运行前，可以检查src/main.py或相关配置文件，考虑将其调小（比如10次）进行尝试，避免陷入死循环消耗大量费用。
• 使用更经济的模型：项目未来方向中提到支持更多LLM。如果实现，可以尝试使用GPT-3.5-Turbo或Claude Haiku等成本更低的模型进行前期探索，虽然它们的能力可能弱于GPT-4。
• 本地模型：对于内部部署或对成本极度敏感的场景，集成开源模型（如CodeLlama、DeepSeek-Coder）是一个有吸引力的方向，但这需要解决本地模型的性能、提示词适配和API兼容性问题。

5.3 常见失败模式与排查

即使提示词很清晰，devlooper也可能失败。以下是一些常见情况：

1. 陷入死循环：智能体可能在一个错误上反复“折腾”，比如安装了错误版本的包，或者修改了一个地方又引入了另一个错误，始终无法通过测试。对策：观察迭代日志。Modal的运行日志会输出每次迭代的测试结果和执行的Action。如果发现连续几次Action都在重复类似操作，可以手动中断任务。项目未来计划通过“记忆”之前的修改来避免循环，这是一个重要的改进点。

2. 依赖地狱：在Python环境中，有时安装一个包会引发与现有包的不兼容。智能体可能只根据错误信息安装缺失的包，但不会处理版本冲突。对策：使用约束更严格的模板。例如，在Python模板的初始环境中就通过requirements.txt固定核心包的版本，减少冲突可能。

3. 测试本身过于复杂或模糊：如果初始生成的测试用例逻辑非常复杂，或者断言条件（Assertion）描述不清，LLM可能难以理解测试到底想要什么，导致修复方向错误。对策：从简单的、功能明确的提示词开始。或者，考虑修改模板中的测试框架，使其错误信息更友好、更具指向性。

4. 网络或API问题：

   • Modal认证失败：确保modal token new成功执行，并且令牌未过期。可以运行modal whoami验证。
   • OpenAI API错误：检查openai-secret是否正确创建，以及API Key是否有余额、是否超过速率限制。可以在Modal的Web控制台查看函数运行日志，里面会有更详细的错误信息。
   • 沙箱网络拉取包失败：某些包源可能访问不畅。可以考虑在环境模板中预设国内镜像源，但这需要修改模板代码。

5.4 自定义与扩展：打造你的专属智能体

devlooper是一个优秀的起点，你可以基于它进行深度定制：

• 创建自定义环境模板：如果你经常需要生成Go微服务或Vue.js组件，完全可以仿照env_templates.py里的结构，创建自己的模板。定义好基础镜像、依赖安装命令（如go mod tidy）、测试命令（如go test ./...）和初始文件结构即可。
• 集成其他云服务或本地环境：Modal并非唯一选择。如果你熟悉Docker API，可以尝试将沙箱层替换为本地Docker守护进程，这样就能在本地机器上运行调试循环，完全零云成本。当然，这需要重写一部分底层交互代码。
• 优化提示词：src/目录下肯定存在包含提示词模板的文件（可能叫prompts.py）。深入研究并调整这些提示词，可以针对特定领域（如数据科学脚本、API客户端）优化智能体的表现。例如，在诊断提示中加入“你是一个经验丰富的数据工程师，擅长处理pandas和NumPy错误”这样的角色设定。

这个项目展示了将LLM与执行环境结合的巨大潜力。它不再是一个被动的文本生成器，而是一个能主动验证、修正其输出的“行动者”。虽然目前仍是一个概念验证，在复杂项目、深层逻辑错误处理上还有局限，但它为AI编程助手的发展指明了一个激动人心的方向：让AI不仅会写代码，更会为自己的代码负责，运行它、调试它，直到它真正工作起来。