仓库:gpt-engineer-org/gpt-engineer(原 AntonOsika/gpt-engineer,55k+ Stars)
定位:CLI 代码生成实验平台,”用自然语言描述软件,AI 自动编写并执行代码”
语言:Python | 框架:LangChain + Typer CLI
1. 整体架构分层
gpt-engineer 采用经典的三层架构,职责清晰:
┌─────────────────────────────────────────────┐
│ applications/cli/ — CLI 入口 + 用户交互 │
│ main.py (Typer) → CliAgent │
│ file_selector.py → 文件选择器 │
│ collect.py → 遥测/反馈收集 │
├─────────────────────────────────────────────┤
│ core/ — 核心抽象层 │
│ BaseAgent → 抽象 Agent 接口 │
│ AI → LLM 调用封装 │
│ FilesDict → 代码文件容器 │
│ chat_to_files → 聊天→代码解析器 │
│ diff → Diff 处理引擎 │
│ preprompts_holder→ 提示词管理 │
│ Prompt → 多模态提示封装 │
├─────────────────────────────────────────────┤
│ core/default/ — 默认实现层 │
│ SimpleAgent → 简单 Agent 实现 │
│ CliAgent → CLI 专用 Agent │
│ DiskMemory → 文件系统 KV 存储 │
│ DiskExecutionEnv → 本地执行环境 │
│ steps.py → 代码生成/改进流水线 │
├─────────────────────────────────────────────┤
│ preprompts/ — 系统提示词模板 │
│ tools/ — 自定义步骤工具 │
└─────────────────────────────────────────────┘
设计哲学:面向接口编程(ABC 抽象基类),核心层定义抽象,default 层提供默认实现,applications 层组装完整应用。这种分层使得替换 LLM 后端、存储方式、执行环境都非常容易。
2. Agent 设计模式
2.1 BaseAgent 抽象接口
class BaseAgent(ABC):
@abstractmethod
def init(self, prompt: Prompt) -> FilesDict:
"""从自然语言提示生成完整代码"""
pass
@abstractmethod
def improve(self, files_dict: FilesDict, prompt: Prompt) -> FilesDict:
"""根据提示改进已有代码"""
pass
接口极其精简——只有 init 和 improve 两个方法。这是 gpt-engineer 的核心抽象:所有 Agent 变体都只需实现”从零生成”和”增量改进”两个能力。
2.2 三层 Agent 实现
| 实现类 | 职责 | 特点 |
|---|
|——–|——|——|
SimpleAgent |
最简实现 | 硬编码 gen_code → gen_entrypoint 流程 |
|---|---|---|
CliAgent |
CLI 增强版 | 可注入 code_gen_fn、improve_fn、process_code_fn |
LeanAgent(曾存在) |
轻量版 | 后续版本移除 |
CliAgent 的关键设计是策略注入——通过构造函数参数注入不同步骤函数,实现了 Agent 行为的运行时可配置:
class CliAgent(BaseAgent):
def __init__(self, memory, execution_env, ai=None,
code_gen_fn=gen_code, # 可替换的代码生成策略
improve_fn=improve_fn, # 可替换的代码改进策略
process_code_fn=execute_entrypoint, # 可替换的执行策略
preprompts_holder=None):
3. AI 调用层(LLM 抽象)
AI 类是与 LLM 交互的唯一入口,基于 LangChain 的 BaseChatModel:
class AI:
def __init__(self, model_name="gpt-4o", temperature=0.1, ...):
self.llm = ChatOpenAI(...) # 或 ChatAnthropic、AzureChatOpenAI
def start(self, system, user, step_name) -> List[Message]:
"""开启对话:system + user 消息"""
def next(self, messages, prompt, step_name) -> List[Message]:
"""继续对话:追加用户消息,获取 AI 回复"""
关键设计决策:
- LangChain 统一接口:通过 LangChain 抽象,支持 OpenAI、Anthropic Claude、Azure OpenAI、本地模型等多种后端
- 指数退避重试:使用
backoff库处理 API 速率限制 - Token 用量追踪:
TokenUsageLog记录每步的 token 消耗,支持成本分析 - 流式输出:通过
StreamingStdOutCallbackHandler实现实时输出
4. 代码生成流水线(Steps)
这是 gpt-engineer 的核心流程,定义在 steps.py 中:
4.1 Init 模式(从零生成)
用户 prompt
↓
gen_code() → AI 生成完整代码 → FilesDict
↓
gen_entrypoint() → AI 生成 run.sh 启动脚本
↓
execute_entrypoint() → 用户确认后执行 run.sh
gen_code 细节:
- 从
preprompts/加载系统提示(roadmap + generate + philosophy + file_format) - 调用
ai.start(system_prompt, user_prompt)获取 AI 回复 - 用正则
r"(S+)ns*`[^n]*n(.+?)`"从回复中提取文件路径和代码 - 返回
FilesDict(文件名→内容的字典)
gen_entrypoint 细节:
- 将已生成的代码通过
files_dict.to_chat()序列化为带行号的文本 - 要求 AI 生成
run.sh(安装依赖 + 运行代码) - 从回复中提取 bash 代码块
4.2 Improve 模式(增量改进)
已有代码 + 改进 prompt
↓
improve_fn()
├─ 构造消息序列:system_prompt + 现有代码 + 用户请求
├─ AI 生成 unified diff 格式的修改
├─ parse_diffs() 解析 diff
├─ validate_and_correct() 校验/修正 hunk
└─ apply_diffs() 应用到 FilesDict
↓
如果有解析错误 → 追加错误信息要求 AI 重试(最多 MAX_EDIT_REFINEMENT_STEPS 次)
这是最精妙的部分——gpt-engineer 不是让 AI 重新生成全部代码,而是使用 unified git diff 格式进行增量修改,并内置了 diff 校验和自动修正机制。
5. Diff 引擎
diff.py 实现了完整的 unified diff 解析和应用引擎:
5.1 数据模型
class Hunk:
"""单个修改块"""
lines: List[Tuple[str, str]] # (RETAIN|ADD|REMOVE, line_content)
start_line_pre_edit: int # 原文件起始行
start_line_post_edit: int # 修改后起始行
class Diff:
"""单个文件的完整修改"""
hunks: List[Hunk]
filename_pre: str # 修改前文件名
filename_post: str # 修改后文件名
5.2 校验与修正
Diff.validate_and_correct() 是 gpt-engineer 的关键容错机制:
- 将 AI 生成的 diff hunk 与原始文件内容逐行对比
- 如果 RETAIN 行与原文不匹配,尝试模糊匹配(
is_similar(),阈值 0.6) - 如果匹配失败,尝试在附近搜索(forward_block_len=10 行范围内)
- 修正行号偏移,确保 diff 能正确应用
这使得 gpt-engineer 能够容忍 LLM 输出的不精确 diff,大幅提高了代码改进的成功率。
6. 存储架构
6.1 DiskMemory(KV 文件存储)
class DiskMemory(BaseMemory):
"""文件系统 KV 存储:key=文件名,value=文件内容"""
def __init__(self, path):
self.path = Path(path).absolute()
self.path.mkdir(parents=True, exist_ok=True)
- 以目录为存储单元,文件名为 key,文件内容为 value
- 支持
.gpteng/memory/子目录存储元数据 - 自动创建目录结构,零配置
6.2 DiskExecutionEnv(执行环境)
class DiskExecutionEnv(BaseExecutionEnv):
def upload(self, files: FilesDict) -> self: # 写入磁盘
def download(self) -> FilesDict: # 从磁盘读取
def run(self, command, timeout) -> (stdout, stderr, exitcode): # subprocess 执行
def popen(self, command) -> Popen: # 后台进程
执行环境通过 subprocess.Popen 运行代码,支持超时控制和 stdout/stderr 实时捕获。
7. Preprompts 系统(提示词工程)
gpt-engineer 的提示词策略是其核心竞争力之一,存储在 preprompts/ 目录下:
| 文件 | 作用 |
|---|
|——|——|
roadmap |
总体指令:”你会收到代码编写指令,写出非常长的回答” |
|---|---|
generate |
代码生成提示:先列出核心类/函数,然后逐文件实现 |
improve |
代码改进提示:使用 unified diff 格式修改 |
philosophy |
编码哲学:不同类放不同文件、遵循最佳实践 |
file_format |
文件输出格式:FILENAME + `CODE` |
file_format_diff |
Diff 输出格式:unified git diff |
entrypoint |
生成 run.sh 的提示 |
提示词组装逻辑:
# 代码生成
system_prompt = roadmap + generate(FILE_FORMAT=file_format) + "Useful to know:" + philosophy
# 代码改进
system_prompt = roadmap + improve(FILE_FORMAT=file_format_diff) + "Useful to know:" + philosophy
可定制性:用户可通过 --use-custom-preprompts 参数覆盖默认提示词,实现个性化 Agent 行为。这是 gpt-engineer 的”记忆”机制——通过修改 preprompts 让 Agent 在不同项目间保持一致的行为模式。
8. FilesDict——代码容器
class FilesDict(dict):
"""类型安全的代码文件容器"""
def __setitem__(self, key, value):
# 强制 key 为 str/Path,value 为 str
def to_chat(self):
"""转为带行号的聊天格式(供 AI 阅读)"""
def to_log(self):
"""转为日志格式"""
FilesDict 是贯穿整个系统的数据载体。它:
- 强制类型检查,防止非字符串值混入
to_chat()方法将文件转为File: pathn行号 内容格式,带行号是为了让 AI 在改进模式下能精确定位代码行- 实现了
to_log()用于调试日志
9. CLI 入口与交互设计
main.py 使用 Typer 构建 CLI,核心流程:
gpte [-i] [--use-custom-preprompts] [--image_directory ...]
↓
load_env_if_needed() # 加载 API Key
↓
FileSelector.ask_for_files() # 改进模式下选择要修改的文件
↓
load_prompt() # 从 prompt 文件加载用户指令
↓
SimpleAgent / CliAgent # 创建 Agent
↓
agent.init(prompt) # 生成模式
agent.improve(files, prompt) # 改进模式(-i 标志)
↓
stage_uncommitted_to_git() # 自动 git stage
collect_and_send_human_review() # 收集用户反馈(可选遥测)
FileSelector 交互设计:
- 生成
file_selection.toml文件,用户通过编辑 TOML 选择要包含的文件 - 支持
.gitignore过滤 - 自动排除
node_modules、venv、__pycache__等目录
10. 自愈机制(Self-Healing)
tools/custom_steps.py 中的 self_heal() 是 gpt-engineer 最具前瞻性的特性:
def self_heal(ai, execution_env, files_dict, ...):
"""执行代码 → 如果失败 → 将错误反馈给 AI → 修复 → 重试"""
MAX_SELF_HEAL_ATTEMPTS = 10
while attempts < MAX_SELF_HEAL_ATTEMPTS:
execution_env.upload(files_dict)
stdout, stderr, returncode = execution_env.run(f"bash {ENTRYPOINT_FILE}")
if returncode == 0:
break # 成功
# 将错误输出反馈给 AI 要求修复
files_dict = improve_fn(ai, error_prompt, files_dict, memory, preprompts_holder)
这是一个闭环反馈循环:执行 → 检测错误 → AI 修复 → 重新执行,最多重试 10 次。这体现了 gpt-engineer 的设计哲学——不仅生成代码,还要确保代码能运行。
架构总结与启示
设计亮点
- 极简接口:BaseAgent 仅 2 个方法(init/improve),降低了扩展门槛
- 策略模式:CliAgent 通过依赖注入支持运行时替换代码生成/改进/执行策略
- Diff 容错引擎:内置校验+修正机制,容忍 LLM 输出的不精确 diff
- 提示词即配置:preprompts 文件系统化,支持用户自定义 Agent 行为
- 自愈闭环:执行→报错→修复的自动循环,提高了代码可用率
局限性
- 单轮对话:init 模式是一次性生成,缺乏多轮交互式迭代
- 无工具调用:纯文本生成,不支持函数调用/工具使用
- 无并行:代码文件串行生成,无法利用并行加速
- Diff 解析脆弱:虽然有容错,但 AI 生成的 diff 仍可能无法解析
- 缺乏状态管理:没有真正的 Agent 记忆系统,每次会话独立
对 OpenMate 的启发
- 策略注入模式值得借鉴:Agent 的核心步骤应该是可替换的
- Diff 引擎的容错设计可以复用:AI 生成的代码修改需要校验机制
- preprompts 文件化是好的实践:提示词应该版本化管理
- 自愈机制是 Agent 必备能力:代码生成后必须验证可执行性
- FilesDict 模式(带行号的代码序列化)对 AI 理解代码结构非常有效