Wolverine:让 GPT-4 自动诊断并修复 Python 脚本崩溃的“再生”工具
Wolverine:让 GPT-4 自动诊断并修复 Python 脚本崩溃的“再生”工具
Wolverine 是一个基于 OpenAI GPT 模型的自愈式脚本运行器:你只需像平时一样运行脚本,一旦脚本崩溃,它会自动把源码、运行参数与错误堆栈交给 GPT,让模型以结构化 JSON 形式给出修改建议,随后自动应用修改并反复重跑,直到脚本修复成功。本文将以仓库 README.md 为主线,结合 wolverine/wolverine.py、prompt.txt 与 tests/test_wolverine.py 的源码细节,带你完整掌握它的安装、配置、命令行用法、修复协议与底层实现原理。
项目定位:给脚本“再生式愈合能力”
README 的开篇只有一句话:“Give your python scripts regenerative healing abilities!”(给你的 Python 脚本再生式愈合能力)。这正是 Wolverine 的核心定位——它不是一个代码分析器,而是一个“边跑边修”的自动化循环工具:
Run your scripts with Wolverine and when they crash, GPT-4 edits them and explains what went wrong. Even if you have many bugs it will repeatedly rerun until it's fixed.
翻译过来即是:用 Wolverine 运行脚本,脚本崩溃时由 GPT-4 编辑代码并解释出错原因;即使有多个 bug,它也会反复重跑直到修复完成。README 同时强调,这是一个作者“花几个小时拼出来的快速原型”(quick prototype),定位是演示与实验,而不是生产级工具。
环境搭建:五分钟跑起来
README 给出了完整的 Setup 步骤,共四步:
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.sample .env
- 前三步是标准的 Python 虚拟环境创建与依赖安装,依赖清单见 requirements.txt,其中核心依赖包括
openai==0.27.4(OpenAI API 客户端)、fire==0.5.0(命令行参数解析)、python-dotenv==1.0.0(加载.env)、termcolor==2.3.0(彩色输出)以及测试用的pytest、pytest-mock。 - 第四步复制 .env.sample 为
.env,然后在.env中填入你的 OpenAI API Key:
OPENAI_API_KEY=your_api_key
#DEFAULT_MODEL=gpt-3.5-turbo
注意 wolverine/wolverine.py 中的加载逻辑:load_dotenv() 负责读取 .env,随后 openai.api_key = os.getenv("OPENAI_API_KEY") 把 Key 注入 OpenAI 客户端。
README 在此给出了一条明确的 warning:默认情况下 Wolverine 使用 GPT-4,并且可能对 API 发起多次重复调用。这意味着每次崩溃都会触发一次(或多次)模型请求,多 bug 场景下会产生持续累积的 API 费用,实验时建议留意调用量。
环境变量一览
README 用一张表格列出了三个环境变量,下面结合源码补充其实际行为:
| 环境变量 | 说明 | 默认值 |
|---|---|---|
OPENAI_API_KEY |
OpenAI API Key | None |
DEFAULT_MODEL |
使用的 GPT 模型 | "gpt-4" |
VALIDATE_JSON_RETRY |
请求 OpenAI API 时 JSON 校验失败的重试次数(-1 表示无限重试) | -1 |
在源码中三者的解析方式分别是:
OPENAI_API_KEY:见 wolverine/wolverine.py,若未设置,后续所有 API 调用都会失败;DEFAULT_MODEL:见 wolverine/wolverine.py,os.environ.get("DEFAULT_MODEL", "gpt-4"),即默认值硬编码为gpt-4;VALIDATE_JSON_RETRY:见 wolverine/wolverine.py,int(os.getenv("VALIDATE_JSON_RETRY", -1)),默认-1表示无限重试,一旦模型返回无法解析的 JSON 就会递归重发请求,直到拿到合法 JSON 为止(详见后文“JSON 响应校验”一节)。
README 还提到:如果希望把 GPT-3.5 设为默认模型,取消 .env 中 DEFAULT_MODEL=gpt-3.5-turbo 一行的注释即可,这与 .env.sample 的注释写法完全对应。
命令行用法:从一条命令看懂全流程
README 给出了三种核心调用方式,全部通过 python -m wolverine 触发:
# 使用默认的 gpt-4(README 明确为“默认且经过测试的选项”)
python -m wolverine examples/buggy_script.py "subtract" 20 3
# 显式切换其他模型(但 README 警告:其他模型可能无法很好地遵守编辑格式)
python -m wolverine --model=gpt-3.5-turbo examples/buggy_script.py "subtract" 20 3
# 应用修改前征求确认
python -m wolverine examples/buggy_script.py "subtract" 20 3 --confirm=True
命令的构成可以拆解为四部分:脚本路径 + 脚本参数列表 + 可选 --model + 可选 --confirm。
入口实现在 wolverine/main.py:它用 fire.Fire(main) 把 wolverine/wolverine.py 中的 main(script_name, *script_args, revert=False, model=DEFAULT_MODEL, confirm=False) 暴露成命令行接口,因此 --model、--confirm、--revert 这些 flag 都是由 fire 自动解析并注入函数参数的。
--confirm=True:应用修改前的人工确认
README 明确解释了该 flag 的语义:
You can also use flag
--confirm=Truewhich will ask youyes or nobefore making changes to the file. If flag is not used then it will apply the changes to the file
即:加上 --confirm=True 时,Wolverine 在写回文件前会询问 Do you want to apply these changes? (y/n):,只有输入 y 才会真正落盘,否则打印 Changes not applied 并退出;不传该 flag 则默认直接应用修改。对应实现见 wolverine/wolverine.py 的 apply_changes 函数。
运行时的自动备份与 --revert
源码中还有 README 未展开、但对实战很关键的细节:每次进入修复循环前,main 会把原始脚本复制为 脚本名.bak(例如 buggy_script.py.bak),用于留底。
而 main 函数的 revert 参数则对应 --revert flag:当传入 --revert 时,若发现同名 .bak 备份文件,就用它覆盖当前脚本并打印 Reverted changes to ...,实现一键回滚;若找不到备份则报错退出。也就是说,你可以在 Wolverine 改坏了文件之后,用下面的命令恢复原样:
python -m wolverine examples/buggy_script.py --revert
运行示例:理解“崩溃 → 修复 → 重跑”的闭环
仓库自带两个示例脚本。第一个是 examples/buggy_script.py,README 中的演示命令正是针对它:
python -m wolverine examples/buggy_script.py "subtract" 20 3
这个脚本故意包含多个 bug:calculate 中调用了从未定义的 subtract_numbers(触发 NameError),并且最后一行返回的是未定义的变量 res 而不是 result。首次运行必然崩溃,随后 Wolverine 会进入自动修复循环。
第二个示例 examples/buggy_script_2.py 演示的是修复一个“单例模式失效”的逻辑 bug:由于每次 __new__ 都重新创建实例,singleton.a + new_singleton.a 的结果不等于预期的 4,从而触发 AssertionError。注意这个脚本内部 docstring 里的运行方式写法(python wolverine.py examples/buggy_script_2.py)是旧式写法,实际应统一使用 python -m wolverine ...。
值得留意的是,wolverine/wolverine.py 的 run_script 并不局限于 Python:它以文件扩展名 .py 决定解释器——以 .py 结尾的脚本用 sys.executable(当前 Python 解释器)运行,否则交给 node 运行。仓库中的 examples/buggy_script.js 正是对应的 JavaScript 示例(同样存在 addNumbers 未定义与 res 未定义的 bug),说明 Wolverine 的修复链路天然支持 Node.js 脚本。README 的 “Future Plans” 也把“扩展到其他语言”列为未来方向。
完整的自修复循环
把 main 的 while True 循环展开,其工作流如下:
- 运行脚本:
run_script(script_name, script_args)通过subprocess.check_output捕获脚本的标准输出与错误,同时拿到返回码; - 成功即止:若返回码为 0,打印
Script ran successfully.与输出,结束循环; - 崩溃则修复:若返回码非 0,打印
Script crashed. Trying to fix...,调用send_error_to_gpt把文件内容、运行参数与错误输出打包发给模型; - 应用修改:
apply_changes(script_name, json_response, confirm=confirm)按模型的 JSON 指令改写文件(可选人工确认); - 重跑:打印
Changes applied. Rerunning...后回到第 1 步,直到脚本成功运行或模型始终无法修复为止。
正是因为存在这个循环,README 才会警告“可能产生多次 API 调用”——每次崩溃对应一轮模型请求,且每轮请求还可能因为 JSON 解析失败而重试多次。
修复协议:GPT 必须遵守的严格 JSON 格式
Wolverine 之所以能自动化地应用修改,关键在于 prompt.txt 中定义了一套严格的“机器可读”修复协议。系统提示词要求模型输出一个 JSON 数组,其中每个元素要么是说明(explanation),要么是操作(operation),支持三种操作:
| 操作 | 含义 | 字段 |
|---|---|---|
Replace |
用 content 替换指定行的现有内容 |
operation、line、content |
Delete |
删除指定行 | operation、line、content(可为空字符串) |
InsertAfter |
在指定行之后插入 content |
operation、line、content |
提示词对格式的要求非常严格,包括:
- 行号从 1 开始计数,第一行是
line 1; - 多行插入/替换时,
content必须是一个用\n转义字符拼接的单个字符串; - 所有编辑会按行号逆序应用(reverse line order),这样前面的编辑不会影响后面编辑的行号;
- 替换内容时必须带上正确的缩进(CORRECT INDENTATION);
- 必须为修改提供简短的解释(至少一条),复杂修改可以给出多条;
- 最终响应必须“只输出 JSON 对象,不能有额外文字或注释”。
提示词中给出的示例响应为:
[
{"explanation": "this is just an example, this would usually be a brief explanation of what went wrong"},
{"operation": "InsertAfter", "line": 10, "content": "x = 1\ny = 2\nz = x * y"},
{"operation": "Delete", "line": 15, "content": ""},
{"operation": "Replace", "line": 18, "content": " x += 1"},
{"operation": "Delete", "line": 20, "content": ""}
]
测试目录中的 tests/test_files/cc_resp.txt 保存了一份针对 buggy_script.py 的真实模型响应,可以看到修复分三步:在 12 行后插入 subtract_numbers 函数定义、把整个 calculate 函数替换为含该函数调用的版本、并把第 30 行替换为 return result。这条样本与 tests/test_wolverine.py 中的单测一起,印证了修复协议与 apply_changes 的完整对应关系。
源码深挖一:apply_changes 如何把 JSON 变成代码
apply_changes 的实现在逻辑上分为五步:
- 读取原文件:
original_file_lines = f.readlines()拿到逐行内容; - 分离说明与操作:把包含
operation键的条目与包含explanation键的条目分开,说明只用于打印,不参与写文件; - 按行号逆序排序:
operation_changes.sort(key=lambda x: x["line"], reverse=True),确保先处理大行号; - 依次执行:
Replace直接替换file_lines[line - 1](行号从 1 开始,列表索引从 0 开始,因此减 1);Delete删除该行;InsertAfter在第line个元素处插入(Python 的list.insert恰好把新内容插到原第line行之后); - 展示与应用:用
difflib.unified_diff生成统一格式的 diff,新增行标绿、删除行标红,随后在confirm=True时等待用户输入y/n,最终f.writelines(file_lines)写回文件并打印Changes applied.。
测试用例 用临时文件分别验证了三种操作的结果,例如对三行文件执行 Replace 第 2 行后内容变为 first line\nnew second line\nthird line,InsertAfter 第 2 行后变为 first line\nsecond line\ninserted line\nthird line,Delete 第 3 行后变为 first line\nsecond line\n。这些断言直接对应了三种操作的行号语义,是理解修复协议最直观的参照。
源码深挖二:json_validated_response 的重试与容错
模型偶尔会不遵守“只输出 JSON”的约束,例如返回带解释文字或 Markdown 代码块的内容。为此 json_validated_response 实现了递归式的 JSON 校验重试:
- 调用
openai.ChatCompletion.create(model=model, messages=messages, temperature=0.5); - 把响应追加进
messages(保留完整对话上下文),然后从content中寻找第一个[的位置,截取从该位置到结尾的子串交给json.loads解析; - 解析成功则直接返回解析结果;
- 解析失败(
JSONDecodeError或ValueError)时,用红色打印错误与黄色打印原始响应,向messages追加一条用户消息 “Your response could not be parsed by json.loads. Please restate your last message as pure JSON.”,然后nb_retry -= 1并递归重跑; - 若
VALIDATE_JSON_RETRY为-1(默认),nb_retry永远不为 0,会无限重试直到成功;若设置了有限次数,耗尽后抛出 “No valid json response found after N tries. Exiting.” 异常。
test_json_validated_response 用 pytest-mock 把 openai.ChatCompletion.create 替换为固定响应,验证了三条路径:合法 JSON 能正常解析、非法 JSON 在重试 3 次后抛异常、非法 JSON 在重试 10 次后同样抛异常。这里也解释了 README 中 VALIDATE_JSON_RETRY 表格行的实际意义——它控制的是“模型吐出不合法 JSON”时的修复耐心,而不是崩溃修复轮数。
源码深挖三:模型可用性检查与上下文构造
main 在进入循环前会调用 check_model_availability:通过 openai.Model.list() 拉取当前账号可用模型列表,若指定的 model 不在其中,会提示改用 --model=gpt-3.5-turbo 或在 .env 中配置默认模型后直接退出。README 警告“其他模型可能无法很好地遵守编辑格式”,与此逻辑相互呼应。
每次崩溃后发送给模型的上下文由 send_error_to_gpt 构造,包含三部分:
- 带行号的脚本全文:逐行读取文件后拼成
1: <第一行>\n2: <第二行>\n...的形式,这正是修复协议要求“行号从 1 开始”的原因; - 运行参数:即命令行传给脚本的参数列表(如
['subtract', '20', '3']); - 错误输出:脚本崩溃时的 stdout/stderr 合并输出。
这三者加上 prompt.txt 系统提示词,组成 messages 交给 json_validated_response。README 的 Future Plans 中提到的“从堆栈跟踪中提取相关类/函数、只发送相关代码片段”,正是针对这个上下文构造方式的优化设想。
已知局限与演进方向
README 的 “Future Plans” 明确列出了作者自己承认的局限与改进方向,这些既是项目现状,也是后续实验的入口:
- 自定义 flag 扩展:例如“在运行修改后的代码前征求用户确认”等使用习惯定制;
- 编辑格式的进一步迭代:README 指出当前模型在缩进(indentation)处理上“还有点吃力”,提示词中的“务必保留正确缩进”正是在缓解该问题;
- 示例 bug 文件套件:用于在固定 prompt 上测试可靠性、度量改进效果——这正是 examples 目录与 tests 所承载的雏形;
- 多文件/代码库支持:把堆栈跟踪中出现的所有文件都发给模型;
- 大文件的优雅处理:是否只发送相关的类/函数给模型;
- 扩展到 Python 以外的语言(如上文所述,当前实现已通过
.py/node分流支持 JS 脚本)。
此外,wolverine/wolverine.py 在模块加载时就会读取 prompt.txt 作为 SYSTEM_PROMPT,如果你想实验自定义提示词,直接修改该文件即可(注意保持 JSON 协议不变,否则 apply_changes 无法解析)。
小结
从使用视角看,Wolverine 的完整操作闭环是:venv + pip install 完成安装 → 在 .env 中配置 OPENAI_API_KEY 与 DEFAULT_MODEL → 用 python -m wolverine <脚本> <参数...> 启动 → 崩溃后由 GPT 按 Replace / Delete / InsertAfter 三种操作给出 JSON 修复方案 → 自动应用(可选 --confirm=True 人工把关)→ 循环重跑直至成功,必要时用 --revert 从 .bak 备份回滚。
从源码视角看,它的核心资产是“提示词定义的严格机器协议 + 递归 JSON 校验 + 逆序行号编辑”这套容错机制,仓库中的 prompt.txt、wolverine/wolverine.py、tests/test_wolverine.py 与 tests/test_files 下的真实响应样本,构成了理解这套机制的最小闭环,非常适合作为“LLM 驱动的自动化代码修复”方向的入门研究对象。