Wolverine:让 GPT-4 自动诊断并修复 Python 脚本崩溃的“再生”工具

原创2026-10-14 13:03:10164 阅读
文章标签:AI 应用开发工具

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=True which will ask you yes or no before 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 循环展开,其工作流如下:

  1. 运行脚本:run_script(script_name, script_args) 通过 subprocess.check_output 捕获脚本的标准输出与错误,同时拿到返回码;
  2. 成功即止:若返回码为 0,打印 Script ran successfully. 与输出,结束循环;
  3. 崩溃则修复:若返回码非 0,打印 Script crashed. Trying to fix...,调用 send_error_to_gpt 把文件内容、运行参数与错误输出打包发给模型;
  4. 应用修改:apply_changes(script_name, json_response, confirm=confirm) 按模型的 JSON 指令改写文件(可选人工确认);
  5. 重跑:打印 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 的实现在逻辑上分为五步:

  1. 读取原文件:original_file_lines = f.readlines() 拿到逐行内容;
  2. 分离说明与操作:把包含 operation 键的条目与包含 explanation 键的条目分开,说明只用于打印,不参与写文件;
  3. 按行号逆序排序:operation_changes.sort(key=lambda x: x["line"], reverse=True),确保先处理大行号;
  4. 依次执行:Replace 直接替换 file_lines[line - 1](行号从 1 开始,列表索引从 0 开始,因此减 1);Delete 删除该行;InsertAfter 在第 line 个元素处插入(Python 的 list.insert 恰好把新内容插到原第 line 行之后);
  5. 展示与应用:用 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 校验重试:

  1. 调用 openai.ChatCompletion.create(model=model, messages=messages, temperature=0.5);
  2. 把响应追加进 messages(保留完整对话上下文),然后从 content 中寻找第一个 [ 的位置,截取从该位置到结尾的子串交给 json.loads 解析;
  3. 解析成功则直接返回解析结果;
  4. 解析失败(JSONDecodeError 或 ValueError)时,用红色打印错误与黄色打印原始响应,向 messages 追加一条用户消息 “Your response could not be parsed by json.loads. Please restate your last message as pure JSON.”,然后 nb_retry -= 1 并递归重跑;
  5. 若 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. 带行号的脚本全文:逐行读取文件后拼成 1: <第一行>\n2: <第二行>\n... 的形式,这正是修复协议要求“行号从 1 开始”的原因;
  2. 运行参数:即命令行传给脚本的参数列表(如 ['subtract', '20', '3']);
  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 驱动的自动化代码修复”方向的入门研究对象。

登录后查看全文
wolverine