SuperAPI AI 工具集

bugfix

编程与开发

查看项目

更新于 10-16 05:59

技能介绍

用途

bugfix 是一个基于根因分析(root cause)的一次性缺陷修复技能。它不直接改代码,而是先完成完整的调查流水线,再把修复工作委派给 /execute。触发方式为:

/bugfix "error description"

核心原则(The Iron Law)

  • 未经根因调查,不得进行任何修复(NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST)。
  • 无证据不得宣称完成。
  • 3 次尝试失败后必须停止。

主要流程

技能始终运行完整的调查加执行流水线,没有 SIMPLE/COMPLEX 分支。整体分为五个阶段:

Phase 1:DIAGNOSE(诊断)

  • 解析输入:提取缺陷描述、错误输出(堆栈、测试失败日志)、上下文(相关文件、近期改动)。
  • 初始化调试状态:使用会话 ID 生成 slug,创建 debug-state.md,记录症状(Phase 1 后不可变)。
  • 并行调查:始终并行调度 debugger 与 verification-planner 两个代理。debugger 负责按调查协议分类缺陷类型、回溯根因、评估严重程度;verification-planner 负责给出证明修复生效的验证命令(仅 Tier 1-3 的 Auto 项,不内联 VERIFICATION.md,不含 Tier 4 沙箱项)。收到 debugger 结果后更新 debug-state.md 的诊断段。
  • Gap 分析:debugger 结果返回后始终运行 gap-analyzer,核对根因与症状的区分是否正确、拟议修复是否会破坏其他区域、是否存在同模式的类似缺陷。
  • 爆炸半径快速扫描:在得到根因位置后,提取函数/模块名进行基于 grep 的结构扫描,统计 total_files、callers、importers、tests、hot_path。使用 -F(固定字符串)避免正则注入;符号为空或格式异常则跳过该项信号,不使该阶段失败。资料同时注明盲区:grep 无法覆盖动态派发、反射以及非 JS/Python 的 import 形式,计数低不代表安全。
  • 分诊建议:根据扫描结果给出路由提示(首个匹配生效)——触及热门路径(auth/payment/migration/schema)建议 /specify;严重程度为 COMPLEX 且 callers 超过 10 且超过仓库文件数的 5% 建议 /specify;根因文本含不确定标记(?、추정、possibly、may、unclear)建议 /discuss;以上都不满足则适合 bugfix。该提示仅为建议。
  • 用户确认:通过 AskUserQuestion 展示缺陷类型、根因(file:line + 一行描述)、拟议修复、验证命令、假设、Gap 分析关键警告、爆炸半径与分诊建议,选项包括:继续 bugfix(若分诊建议非 bugfix 则显示为“覆盖分诊继续”)、切换 /specify、切换 /discuss、根因不同(补充信息后重跑 Step 1.2)、停止。选择 /specify 时会生成 requirements.md 骨架并附上 debugger 报告与爆炸扫描,随后退出 bugfix。

Phase 2:REQUIREMENTS GENERATION(需求生成)

  • 将诊断结果转换为 requirements.md 格式。该文件是 /execute 消费的标准格式,并在失败时作为 /specify 的升级上下文。
  • 使用 hoyeon-cli req init ${SPEC_DIR} --type bugfix --goal "Fix: {bug description}" 初始化,创建带存根模板的 requirements.md。
  • 使用 Write 工具覆写完整需求内容,包含 type/goal/non_goals 头部、R-B1 需求(含 R-B1.1、R-B1.2 等子需求,采用 given/when/then 形式)、R-T1 最小差异约束以及 Constraints(最小差异 <5%、修复根因而非症状、不做修复以外的重构)。
  • 映射规则:把 debugger 的复现步骤转换为 GWT;若识别到边界情况或类似问题则各加一条子需求;包含修复范围护栏的约束段。
  • 注册:通过 hoyeon-cli session set --sid $SESSION_ID --spec "$SPEC_DIR" 登记,并在 debug-state.md 中记录 spec_dir。

Phase 3:EXECUTE(执行)

将 requirements.md 交给 /execute,由 Execute2 从 spec 目录读取 requirements.md 并在内部推导 plan.json。execute 负责:通过 AskUserQuestion 提示用户选择 dispatch / work / verify;按所选 dispatch 模式派发 worker;轮级提交;按所选 verify 深度执行验证配方;输出最终报告。执行成功进入 Phase 5,中止则进入 Phase 4。

Phase 4:RESULT HANDLING(结果处理)

  • 读取失败上下文(execute 的 HALT 输出,或 context 目录的 audit.md、issues.json)。
  • 重试:attempt 计数加一,最多 3 次;达到上限进入 Step 4.5 熔断。
  • 停滞检测(attempt 大于等于 2):对比先前失败信息,识别 SPINNING(同一文件/组件连续失败)、OSCILLATION(A 失败→B 失败→A 失败)、NO_PROGRESS(每次失败不同,先前修复引发回归)三类模式,并给出对应的 retry_hint;无模式则提示需要不同方法、不要重复先前尝试。
  • 更新需求并重新执行:在 debug-state.md 记录本次尝试结果与提示,更新尝试计数,将失败上下文追加进 requirements.md(Constraints 或 Known Issues),然后重新调用 execute。直接修改 plan.json 交给 /execute 处理,如需重置失败任务可用 hoyeon-cli plan list 与 hoyeon-cli plan task --status <task-id>=pending。
  • 熔断:超过最大尝试次数后,将记录写入 .hoyeon/debug/{slug}.md(状态 ESCALATED),通过 AskUserQuestion 提供选项:切换 /specify(完整规划)、再试一次(不重置熔断)、停止。

Phase 5:CLEANUP & REPORT(清理与报告)

  • execute 成功后,将报告写入 .hoyeon/debug/{slug}.md(状态 RESOLVED),含根因、修复、验证内容,并将 debug-state 状态更新为 resolved。
  • 输出最终摘要:缺陷、根因(file:line)、尝试次数、Spec Dir、报告路径。
  • QA 建议:通过 AskUserQuestion 询问是否运行 /qa 在浏览器/应用中验证修复且无回归。

升级路径

/bugfix(诊断 + requirements.md + execute)→ 熔断(3 次失败)→ 保存 requirements.md 与 .hoyeon/debug/{slug}.md → /specify(利用已有诊断上下文丰富需求)→ /execute(执行丰富后的需求)。由于 requirements.md 是标准格式,/specify 可读取并丰富既有需求,所有诊断上下文(约束、已知问题、GWT 场景)都会保留。

代理汇总

Phase 1 始终调用三个已有代理:debugger(根因分析、Bug Type 分类)、verification-planner(生成 Auto 项验证命令列表)、gap-analyzer(检查遗漏因素、风险评估);Phase 1.5 执行 Bash(git grep + wc -l)扫描。

限制

  • 3 次尝试失败后必须停止,不会无限重试。
  • 爆炸半径扫描基于 grep,无法覆盖动态派发、反射与非 JS/Python 的 import 形式,计数低不代表安全。
  • 分诊建议仅供参考,最终路由由用户决定。
  • 关于收费、价格、支持平台等信息,资料未提供。