SuperAPI AI 工具集

oil-plan

编程与开发

查看项目

更新于 11-13 15:33

技能介绍

oil-plan 是一个开发方案制定与派发流程技能,核心是按任务复杂度分级,拒绝小事大做,并在动手前完成事实核对与关键分歧确认。

一、用途与分级 它用于在写代码前制定人类看得懂的开发方案,按复杂度分为三级:L1 轻量直达,适用于单模块明确修补、改文案、调样式、定位清楚的小缺陷,用 2–3 句话说明改法后直接修改或派发,跑一次关联局部快测;L2 对话方案,适用于常规单功能开发、中等重构或存在 1–2 个产品取舍,核实代码事实后在对话里给出精炼四要素方案与待拍板项,用户点头后实现;L3 里程碑规格,适用于跨多子系统改造、新数据格式/打包链路或高风险架构变更,核实事实后按项目既有风格写入 docs/ 规格文档,独立挑刺内审,用户确认后分批或按 Worktree 派发。

二、主要能力

  1. 方案审查闭环:审方案属于 oil-plan 内置动作,不混入 oil-code-review(后者只审已写出的代码)。
  2. 平实语言方案:围绕“要解决什么与外部可见变化、改动范围与现成基建复用、关键取舍与异常安全兼容打包边界、分层验证标准”四个核心问题写清楚,读者无需关心底层框架内部写法。
  3. 事实核实与分歧清零:动手前只卡两条真红线——提到的现有文件路径、可复用组件与测试命令已在仓库真实核对存在;影响用户体验或范围边界的关键分歧已向用户问清。不搞填表式虚假百分比打分。
  4. 修缺陷先复现:无论哪个级别,修缺陷都先复现问题(能写失败测试就先写并确认它真的失败),修完以同一个用例转绿作为验收。
  5. 严格契约派发:交给外部执行 Agent(如经 oil-delegate)或当前会话自己实现时,把方向、必复用组件、允许修改的文件和测试快规则一次写死,防止执行方自行发散或每改两行就反复空跑重测试。
  6. 中途升级:执行中发现要动高风险模块(并发与后台任务、数据存储格式与迁移、文件删除等不可逆操作、鉴权/权限/支付等安全敏感逻辑、对外 API 与数据契约、打包发布与升级,以及开发约定里标为高风险的目录)、改动超出原定文件,或冒出新的产品取舍时,停下来升级到 L2/L3 重新对齐。L1 改动只要碰到高风险模块,仍交给 oil-code-review 把关。
  7. 并行隔离:同时推进多条互不依赖的任务时,先确认热点文件不重叠,分别放入同级父目录下的独立 Git Worktree,记下分支名与 Worktree 路径供收尾合并;编译缓存较重的原生工程可先用写时复制(如 macOS APFS cp -cR)克隆主仓库构建目录。
  8. 验收不只听自报:先用 REVIEW_HELPER --allow <契约里允许的路径> 检查越界改动,再看测试有没有被删除、跳过或弱化,然后亲自跑一次契约里的局部快测;慢测试不在这一步重复跑。执行器说“基线本来就失败”时,在主干上跑同一条命令核实。
  9. 收尾合并:审查通过后按收尾合并清单在待合并分支上跑一次合并门禁,门禁失败先判断是不是本次改动引入的,按仓库约定提交合并(执行器不自行提交),多个 Worktree 按依赖顺序逐个合入,全部合入后再跑一次门禁,最后清理已合入的 Worktree 并处理 L3 规格文档的去留。

三、使用方式 先按 oil-explore 只读查实目标模块真实路径、可复用公共组件与局部快测命令,严禁凭猜测编造路径;若仓库有 AGENTS.md 或 DESIGN.md,先核对架构分层、设计令牌、测试隔离与打包分发硬约束。L2/L3 用平实语言写方案,L3 落盘到 docs/ 并沿用目标仓库标题风格。方案自检时逐一核实引用路径真实存在;L3 跨模块高风险方案且环境已安装 oil-delegate 时,可让独立模型以 --role critique 挑刺,返回 USE_HOST 时改用当前 Agent 的全新只读子 Agent,返回 NEEDS_ROLE_CHOICE 时问用户一次并按 oil-delegate 说明保存,回来后确认 git status 没有变化。派发前确认工作区干净或改在独立 Worktree 中执行;用户自己有未提交改动时先问清是提交、暂存还是另开 Worktree。经 oil-delegate 派发时用 --role implement。

四、适用场景与限制 适用于有明确仓库与开发约定的项目中进行功能开发、重构、缺陷修复与多任务并行推进。资源文件 references/plan-rubric.md 提供好差方案对照、动手前核对清单、快规则派发模板与收尾合并清单。REVIEW_HELPER 指 oil-code-review Skill 自带的改动采集脚本 review_helper.py,未安装时用 git status 与 git diff --stat 对照契约代替。该技能依赖 oil-explore、oil-code-review、oil-delegate、oil-govern 等配套技能,具体安装与配置方式暂未提供。