前沿计划 OpenCode 执行器
核心原则
前沿计划是一个强假设,而非事实。
逐步执行计划的意图,但在编辑代码前,需针对实际仓库验证每一项指令。前沿AI的计划经常在以下方面失败:不存在的文件名、凭空想象的导入、不可用的库、与仓库模式不匹配、缺少测试、理想化的架构、以及破坏内部API。
永远不要批量进行大型更改。永远不要跳过验证。永远不要隐藏不确定性。未经明确批准,永远不要执行破坏性操作。
何时使用
- 你收到由前沿AI编写的、包含详细步骤的实施计划
- 该计划包含3个或更多不同步骤,并指定了文件路径和代码模式
- 你正在使用一个非前沿编码模型,该模型受益于执行纪律
- 该计划存在与实际代码库冲突的风险
不要用于:
- 单文件更改或琐碎修复
- 只有1-2个简单步骤的计划
- 在同一会话中你自己编写的计划
- 用户希望速度优先于安全性的快速迭代场景
核心工作流程
0. 预检:建立仓库基线
在接触任何文件之前,了解仓库状态并检测预先存在的故障。
1. git status --short # 仓库是否干净?
2. 检查 package.json # 可用的脚本、依赖项
3. 检查 AGENTS.md, README.md # 项目约定、命令
4. 从 package.json 脚本中检测可用的验证命令
5. 如果可用,运行最简单的基线验证(lint 或 typecheck)
如果基线已经失败:
- 明确记录失败:确切的命令、退出状态和简短的错误摘要
- 不要尝试广泛的清理或修复不相关的问题
- 仅当计划中的更改可以与现有失败隔离时才继续
- 不要将预先存在的失败归因于你的实现
危险状态检测:
- 如果
git status显示与计划无关的未提交更改,请警告用户 - 如果锁文件被修改,请警告用户
- 如果仓库处于冲突/变基状态,请停止并询问
检查点建议:
- 如果仓库在开始前是干净的,建议在实施前创建一个检查点提交
- 除非用户明确要求,否则不要创建提交
自动提交和自动推送
自动提交和自动推送默认启用,除非用户明确禁用。
代理应在每个经过验证的逻辑工作单元完成后提交并将其推送到活动的远程工作分支,以便用户随后可以审查历史记录。
实施前:
- 确定当前分支;
- 如果在
main、master、production、release或其他受保护/主线分支上,根据计划创建一个新的工作分支; - 如果已经在工作分支上,则继续使用该分支;
- 永远不要直接推送到受保护/主线分支。
如果存在预先存在的未提交更改:
- 不要自动将它们包含在代理的提交中;
- 仅暂存与当前逻辑工作单元相关的文件;
- 如果用户更改和代理更改无法安全分离,请停止并报告冲突。
仅在以下条件满足后提交:
- 逻辑工作单元已完成;
- 验证通过;
- 差异已检查;
- 提交具有一个连贯的目的。
使用约定式提交:
type(scope): concise imperative summary
示例:
feat(auth): add session validation helper
fix(api): handle empty webhook payload
refactor(billing): extract invoice mapper
test(auth): cover expired session flow
1. 解析:提取计划并对现实进行验证
阅读完整的计划。提取有序的步骤。对于每个步骤,进行现实情况检查:
| 检查项 | 问题 |
|---|---|
| 文件 | 引用的文件是否存在于仓库中? |
| 库 | 引用的库是否在 package.json 中? |
| 模式 | 仓库中是否已存在等效的实用程序/组件? |
| 命令 | 计划的验证命令是否可用? |
| 依赖项 | 此步骤是否依赖于前一步? |
| 风险 | 低/中/高 — 有多大可能破坏现有行为? |
如果某个步骤引用了不存在的文件、不存在的库、过时的模式或不可用的命令:在实施前调整该步骤,同时保留计划的意图。
2. 跟踪:创建进度追踪器
如果可用,请使用 todowrite(OpenCode 的任务列表工具)。
如果 todowrite 不可用(例如,在子代理中,默认情况下禁用它):
- 在你的响应中创建一个可见的 Markdown 复选框列表
- 在每个步骤后手动更新它
- 将其作为进度的事实来源
- 如果未使用该工具,不要假装使用了
每个项目必须包括:实施操作、验证方法以及预计会触及的文件。
3. 实施:一次一步
将当前步骤标记为 in_progress。仅实施该步骤。
- 在编辑前读取目标文件
- 遵循现有代码库约定(导入、命名、模式、架构)
- 使计划适应现有基础设施(例如,如果计划说“创建一个 toast 组件”,但项目使用 Sonner,则包装 Sonner 而不是从头构建)
- 进行最小的一致更改
- 不要实施未来步骤,但在做出设计决策时需考虑下游依赖项
- 不要进行不相关的清理、重构或格式化
- 除非得到明确批准,否则不要安装依赖项
4. 验证:分层验证
在每个步骤之后,运行最有针对性的验证。 不要每次都“lint 所有内容”。
| 更改类型 | 最低验证 | 更强的验证 |
|---|---|---|
| 新文件/组件 | lint 或 typecheck | 受影响的 typecheck |
| 类型/接口更改 | typecheck | 受影响的测试 |
| 逻辑/函数更改 | 有目标的单元测试 | 完整测试套件 |
| API/服务器更改 | 有目标的集成测试 | 构建 + 端点检查 |
| UI 更改 | typecheck + build | 视觉/手动冒烟检查 |
| 配置/构建更改 | build | 如有需要,进行干净安装/构建 |
| 数据库/模式更改 | dry-run/check 命令 | 需要用户批准 |
如果某个步骤没有自动化验证:执行手动审查并准确说明你检查了什么。
如果验证失败:
第一次失败 — 修复并重新验证:
- 仅修复由当前步骤引起的错误
- 不要修复预先存在或不相关的错误
- 立即重新验证
重复失败 — 不要盲目地继续修补。 请参阅下面的“重复失败处理”。
关键: 永远不要通过削弱断言、删除测试、移除行为、更改公共 API、抑制错误或隐藏失败来使验证通过 — 除非计划明确要求并且用户批准。让警报停止不等于解决问题。
5. 差异:检查更改
在验证通过后,检查实际发生了哪些更改:
git diff --stat # 哪些文件发生了变化?
git diff # 当差异足够小时进行审查
确认:
- 只有预期的文件发生了变化
- 没有发生不相关的格式化
- 没有锁文件发生变化(除非明确有意)
- 没有意外编辑生成的文件
- 没有引入秘密、本地路径或调试日志
- 没有意外删除代码
如果差异超出预期范围,请在继续之前停止并纠正。
6. 确认:标记完成
只有当实施、验证和差异检查都干净时:
- 将该步骤标记为
completed - 用一句话总结更改了什么
- 将下一步标记为
in_progress
7. 最终:完整验证 + 报告
在完成所有步骤后:
- 运行最合理的强检查:lint + typecheck + build + tests(使用项目命令)
- 报告:完成的步骤、更改的文件、验证结果、所做的调整、预先存在的失败(如果有)、任何需要用户审查的内容
重复失败处理
如果由于相同的基本原因验证反复失败,不要继续应用小的盲目修复。 目标是检测你是在尝试之间学到新东西,还是只是在随机折腾。
当一个步骤多次失败时:
- 停止修补。 停止进行小的调整并重新运行。
- 仔细重新阅读错误输出。 完整的堆栈跟踪,而不仅仅是第一行。
- 检查差异和周围代码。
git diff,阅读相关的类型、接口、函数。 - 重新评估原始假设。 当前的实施策略是否正确?
- 对失败进行分类:
- 对代码库的假设不正确?
- 仓库不匹配(计划与现实)?
- 选择了错误的抽象?
- 接口或类型不兼容?
- 缺少依赖?
- 过时的生成产物?
- 与你的更改无关的预先存在的问题?
- 验证命令本身配置错误?
- 形成一个真正的新假设。 仅当你有一个新假设时才重试。
- 考虑缩小范围。 该步骤是否可以拆分为更小的部分以隔离失败?
关键规则: 不要重复相同的修复策略,除非发现了新信息:
- 日志
- 堆栈跟踪
- 差异
- 测试
- 仓库检查
- 文档
如果多次尝试后仍未出现新策略,请停止并清晰地报告阻塞点:
Blocker:
- verification command: `npm run build`
- failing file: `src/app/page.tsx`
- root issue hypothesis: React Server Component importing client-only hook
- attempted strategies:
1. moved import to client component
2. isolated hook into separate file
3. checked existing patterns in repo
- reason for stopping:
no consistent pattern in repo to resolve boundary safely
- likely next action:
user review or architectural clarification
一份清晰的阻塞点报告总是好于重复“仍在失败”的同时瞎猜。
使计划适应现有代码
前沿AI的计划经常与实际代码库冲突。当发生冲突时:
- 识别冲突 — “计划说
import { X } from 'uninstalled-lib'但它不在 package.json 中” - 适应,而不是忽略 — 使用现有基础设施来匹配计划的意图
- 解释适应 — 用一句话说明你更改了什么以及为什么
- 保留计划的接口 — 如果计划导出了
useToast(),你的适应版本仍应导出useToast(),即使内部实现不同
关键规则:
- 如果仓库中已有等效的原语,不要创建新的抽象
- 除非计划明确要求并且用户批准,否则不要安装新的依赖项
- 没有正当理由,不要更改架构或模式
未经明确用户批准禁止执行的操作
这些命令需要用户说“是”之后才能运行:
破坏性操作:
rm -rfgit reset --hardgit clean -fdgit push --force
安装(更改锁文件):
npm installpnpm installyarn installbun installnpm audit fix
数据库/基础设施:
prisma migrateprisma db pushsupabase db pushdocker compose down -v
配置:
- 更改
.env文件 - 修改全局工具配置
- 运行部署/取消发布命令
大规模更改:
- 广泛格式化(prettier/eslint --fix 对整个仓库)
- 在不经审查的情况下跨多个文件查找并替换
如果不确定某个命令是否安全,请在运行前询问。
常见错误
| 错误 | 现实 |
|---|---|
| “前沿AI是这么说的,所以它肯定是对的” | 前沿计划是假设。对照真实仓库进行验证。 |
| “我会最后一起验证所有内容” | 错误会累积。以合适的粒度验证每个步骤。 |
| “我已经读过计划了,我可以一次性全部实施” | 批量实施 = 批量错误 + 更难的调试。 |
| “反正我要顺便修复预先存在的lint错误” | 不相关的清理掩盖了你的更改实际做了什么。不要这样做。 |
| “这个步骤很简单,我不需要检查git diff” | 简单的编辑可能会意外删除代码或格式化非预期的文件。 |
| “我会安装计划中引用的缺失库” | 先询问。该库可能是有意不包含的或未经批准的。 |
| “npm run build 是唯一重要的验证” | 构建速度慢且范围广。对于中间步骤使用 lint/typecheck。 |
| “如果失败了,我就调整一下再运行,直到通过为止” | 在没有新信息的情况下盲目修补是瞎折腾。重新阅读错误。先形成新假设。 |
| “又是同样的错误,让我试试另一个小更改” | 相同的错误 + 相同的策略 = 相同的结果。改变策略,而不是修补的内容。 |
红旗 — 停止并重新评估
- “我下一步再验证” — 现在验证。
- “前沿计划比仓库更懂” — 仓库是事实来源。
- “这个库没有安装,但计划需要它” — 询问用户。不要静默安装。
- “差异比预期大,但可能没问题” — 在继续前检查并解释。
- “我会把步骤2和3合在一起,因为它们相关” — 一个步骤 = 一个验证 + 差异循环。
- “有预先存在的lint错误,让我先修复它们” — 这不是你的工作。记录下来。保持专注。
- “让我在编辑这个文件的同时格式化它” — 单独的更改 = 单独的步骤。不要混合。
- “还是失败,让我再试一个快速修复” — 停止修补。重新阅读错误。先形成新假设。
- “同样的错误3次了,再调整一下可能就行” — 相同的错误 + 相同的策略 = 瞎折腾。改变策略或报告阻塞点。
- “我就重写整个东西,看看能不能修好” — 不弄清楚失败原因就丢弃工作没有意义。先诊断。
- “用户很急,我就跳过差异检查了” — 5秒钟的
git diff --stat可以防止数小时的调试。
快速参考
| 阶段 | 操作 | 工具 |
|---|---|---|
| 预检 | git status, 检测命令, 基线检查 | Bash |
| 解析 + 现实检查 | 阅读计划, 针对仓库验证每一步 | Read + Glob |
| 跟踪 | 创建 todowrite |