SuperAPI AI 工具集

refactor-pipeline

编程与开发

查看项目

更新于 10-29 06:29

技能介绍

Refactor pipeline 面向“重要但没人愿意做”的机械式大规模重构:把一个膨胀到数十万行的 crate 拆分、抽取模块、迁移某个 API 的全部调用方等。这类工作重复而漫长,既不适合作为一个巨型 PR 审阅,也不值得人工盯上一周。

用途与适用判断

该技能适合以下情形:

  • 目标可度量且机械,例如“把 core 的非测试 LoC 削减 50%”“src/legacy 中不再有文件 import old_client”“v1::fetch 的调用方归零”。
  • 变更能自然拆成许多小而独立正确的单元。
  • 结果需要以可审阅的 PR 形式落地,而不是一个巨大 diff。

不适用:每一步都需要设计决策的重构(改用 brief 与 autonomous-delivery);以“更快、更少 flaky”等可度量改进为目标的工作(改用 find-the-loop 与 experiment-arms);只需照看单个 PR 的场景(直接使用 pr-shepherd)。

三条独立通道

每条通道在独立会话中运行(如独立 Copilot CLI 进程、app 会话或云会话),以保持上下文精简,并让某条通道崩溃时不影响其他通道。

1. Producer(生产者):执行实际工作

它以带心跳的长期目标运行,启动说明可写在一段话内,需要明确:目标、工作单元、基线(现在测量)、心跳(如每 30 分钟按绝对 LoC 和百分比汇报)、验证(每次提交前运行受影响 crate 的测试)、约束(如不要让其他 crate 显著变大)。

必须遵守的规则:

  • 每次提交后推送,便于打包者同步消费。
  • 基线永不移动,每日 rebase 后仍按原始基线汇报。
  • 不得制造虚假进展:不删除、弱化或重分类测试,不改变统计口径,不为让调用方编译通过而留下兼容包装。
  • 测试随代码一起迁移,连同测试模块与 fixture 迁到新归属。
  • 每日 rebase 到最新已落地状态,丢弃已合并提交并重新测量。

2. Packager(打包者):让结果可审阅

按计划把原始提交转成可审阅的 PR 栈。它采用“检查点”而非记忆:保存最后处理的源提交,以及每个已打包提交的稳定标识(git patch-id --stable 或 Change-Id trailer)。每次运行先输出差异说明,无新提交时保持静默。

生产者 rebase 后需要重新对齐:若源分支非快进移动,旧检查点可能不再是祖先,已打包提交的 SHA 也会变化;此时应按 patch-id 或 Change-Id 匹配,跳过已打包部分,只打包剩余提交;补丁在 rebase 中变化的提交会被标记而非重复打包。新提交 rebase 到栈顶、运行测试,并把 fixup 折叠进尚未进入 PR 的提交;它只在栈顶追加 PR,不改写已在栈中的 PR。每个 PR 按人工可读规模控制(例如改动行数少于 2,000,纯移动除外),并用仓库的堆叠工具(如 gh stack)加入栈。节奏随批量大小调整,起初可每几小时一次;若每次只发现一两个提交则放慢。

3. Shepherd(守护者):保持栈可合并

频繁对栈中每个 PR 运行 pr-shepherd。每次运行都重新发现栈成员;它是唯一改写栈的通道,重排、冲突 rebase 和已入栈 PR 的 fixup 都经它处理,打包者只给它发通知而不直接推送。合并性要针对真实目标分支检查:堆叠 PR 相对其堆叠基线可能“无冲突”,但下层合并后可能与 main 冲突,需用 git merge-tree 对实际落地分支验证。遇冲突先立即推送 rebase 再验证,因为等待本地验证的陈旧 PR 会阻塞其上所有 PR。栈全绿只是检查点而非终点,持续运行直到栈合并、人工叫停、预算耗尽或连续 6 次 tick 无动作,然后说明原因并停止计划。仅在证明栈未导致失败后重跑红色检查。

共享规则

  • 统一 API 预算:三条通道共用同一 GitHub 配额;每个 PR 约每 10 分钟最多一次状态轮询,合并查询(每栈一次 GraphQL 调用而非每检查一次),遇 403 或 429 退避到 resetAt。
  • 默认由人决定合并:守护者保持 PR 绿色,人随时合并;可调高自治档位让守护者自行落地绿色 PR。
  • 纠正写入常驻指令:当你纠正某通道(如“先推送再验证”),该通道会改写自己的周期性提示以纳入规则,从而只需说一次。
  • 人负责路由上下文:只有人能看到三条通道,可告知某通道“rebase 到 extract-projections,它已把大部分工作适配到较新 main”或“另一个任务正在向此栈添加 PR”。

运行方式

  • Copilot CLI:每条通道一个终端;用 /goal 设置生产者目标,用 /every 设置各通道节奏,例如生产者汇报 /every 30m、打包者 /every 3h、守护者 /every 20m;终端应放在不休眠的机器(开发机或 VM)上。
  • Copilot app:每条通道一个会话;/goal 用法相同,但没有 /every,需为各通道配置相同节奏与会话自动化,唤醒同一会话以保留上下文与检查点。
  • 云端:打包者与守护者适合自动化,因其有调度、有边界、可重复;生产者保持为长期会话并定期查看。

可调档位

  • target:必填,指标 + 方向 + 数量,对照固定基线。
  • pr_size:默认少于 2,000 改动行(纯移动除外)。
  • cadence:生产者汇报 30 分钟、打包者 3 小时、守护者 20 分钟、生产者 rebase 24 小时。
  • autonomy:守护者默认 L2(保持绿色、由人合并)。
  • api_budget:每个 PR 每 10 分钟最多一次轮询,所有通道共享。
  • spend:取决于你的档位与预算;多日运行会产生数千次模型调用,提示缓存很重要。

效果示例

资料称,在一次真实五天运行中,针对约 564k 行的 Rust crate,三条通道完成 135 次拆分,非测试 LoC 减少约三分之一;20 个堆叠 PR 中 19 个合并,最慢的 CI 作业顺带提速约 28%。人共输入 38 条消息,计划运行触发 373 次;其中多数是一行纠正(被通道写入常驻指令)以及“为什么停止计划”。

反馈闭环

生产者的心跳即循环:若指标连续三次汇报未动,应停下并询问人目标或工作单元是否有误。需要重复输入两次的纠正即缺失规则,应加入该通道常驻指令,通用规则则写入技能文档。

限制

该技能依赖 Git 分支、PR 栈与相关工具(如 gh stack、pr-shepherd),并受 GitHub API 配额与模型调用预算约束;不适用于每一步都需设计决策的重构,也不负责自动合并(默认由人合并)。具体平台支持范围、安装方式与价格信息暂未提供。