2026/9/11 7:40:36
FEATURED · 精选文章 
先说一个很实在的观察OpenCode 这类命令行 AI 编程工具绝大多数人装完以后只干了一件事——把它当成一个加强版聊天框遇到问题复制报错进去拿到答案再复制出来。这当然有用但它真正值钱的能力其实是把“开发检查清单”这种偏流程化、偏规范的事情交给一个不会累、不会忘、还愿意按你的要求逐项执行的 agent 去跑。我这一年的用法发生了很大变化从“哪里不会问哪里”变成了先把优化和文档这两个最容易被跳过的环节固化成一套明确的检查项。然后让 OpenCode 做我的检查执行器——先照着清单扫代码、再给优化建议、最后把文档同步补齐整个过程可复现、可交给 CI、也可丢给团队里任何一个同事去跑。这篇文章就围绕这套思路展开适合正在用或打算用 OpenCode 做日常开发的人也包括那些想给团队沉淀一套工程规范但不想靠人肉 Reviewer 硬扛的开发者。我不会通篇讲概念尽量把安装、配置、清单设计、实际命令和踩坑经历都揉在一起你能直接照着抄。1. 为什么把优化和文档作为检查清单的核心1.1 OpenCode 这类工具真正的价值不在“写代码”聊 OpenCode 之前先说清楚我理解的这类工具的本质。它不是一个简单的代码补全插件而是一个具备“规划、执行、观察结果”能力的 agent 框架。你可以给它一个目标它会自己拆解任务、读文件、调用命令行工具、运行测试、根据输出调整策略。这跟传统 IDE 的自动补全完全不是一个物种——补全是在你写的时候帮忙续写agent 是能自己闭环地做一件相对复杂的工程任务。那这和“优化”“文档”有什么关系关系非常大。因为写代码这件事AI 做得已经不错了但写完代码之后那些“收尾工作”——检查性能隐患、清理冗余逻辑、补注释、更新文档、维护 CHANGELOG——才是最消耗人的。这些事有三个特点一是重复性高二是多数情况下不紧急三是遗漏了也不会立刻爆炸。正因如此它们恰恰是最容易被人在忙碌中跳过的环节。OpenCode 这类工具的到来改变了这个局面。因为这些事情非常结构化非常适合转成清单让 agent 去逐项执行。比如代码里有没有未捕获的异常有没有重复的三方依赖有没有已经不被引用的导出函数这些都可以通过静态扫描或让 agent 读代码来检查。重点不在于它 100% 准确而在于它能稳定地、低成本地、一遍又一遍地执行同样的检查动作。人做不到这种稳定性人会累、会烦、会在赶进度的时候偷偷把检查这步省略。所以我的结论是OpenCode 的真正价值不是帮你把代码写得更快而是帮你把代码“交付之前的那一公里”走得更稳。而这个“一公里”就是检查清单最值得覆盖的领域——优化和文档。1.2 开发检查清单在交付流程里的定位我见过很多团队做代码审查Reviewer 往往把精力全放在“逻辑对不对”上至于性能隐患、文档同步、是否有无用的调试代码很少人会在意。这不能怪 Reviewers人脑的注意力带宽是有限的一次 review 能关注 3 个维度就已经很好了。检查清单这件事航空业做得最好。飞行员起飞前不会靠记忆去逐项确认而是拿着一张卡片从左到右、从上到下一项项核。开发也应该一样把你过去踩过的坑、团队约定过的规范、开源社区总结出的最佳实践都写进清单里。写清单不是为了“管住人”是为了把“记得检查”这件事从大脑里挪出去让大脑专注在处理真正需要判断的事情上。我给自己用的清单有三个来源过去半年里真实出现过的线上事故和严重 bug每一项都是一个检查项。团队里在 PR 评论中反复提到的意见比如“这个字段要加索引”“这里日志级别用错了”“这个接口缺鉴权”。开源文档规范里常见的硬性要求比如“README 必须包含安装和最小示例”“公开 API 必须有注释”“破坏性变更必须写进 CHANGELOG”。这些来源都非常务实没有任何一条是“为了规范而规范”。而在 OpenCode 出现以前这套清单的执行成本其实不低每一条都需要人手动去翻代码、去验证。现在有了 agent清单的执行方式变成了——你把清单写成 skill 或 prompt让 OpenCode 去跑跑完它给你一份报告你只需要审核报告即可。这也是我把优化和文档作为核心的原因。性能问题具有隐蔽性和滞后性文档问题具有累积性。它们都是“不做检查也能正常跑一段日子”的软性问题如果不通过清单强制检查几乎必然被推迟到“以后再说”然后就没有然后了。2. 环境准备与工具选择先把手里的家伙备齐2.1 安装 OpenCode两种版本、一条 PATH 的坑我用 OpenCode 的时间不算短从最早的原生 CLI 到现在的版本整体感受是TypeScript 版本功能最全插件生态和 VSCode 扩展配合得最好后来社区里出现的 Go 版本主打启动速度和内存占用如果你习惯让 agent 常驻终端、频繁切换任务Go 版会更舒服一点。功能上两个版本基本对齐但一些新功能和实验性特性通常先在 TypeScript 版上线所以我实际主力用的还是前者。安装方式最简单的就是走 npm 全局安装npm install -g opencode-ai/opencode装完以后运行opencode --version验一下。如果你用的是 Go 版go install github.com/opencode-ai/opencodelatest这个方式有个坑我踩过Go 默认装到$GOPATH/bin如果这个目录不在你的 PATH 里运行opencode就会直接报“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这个报错特别典型不只是 OpenCode几乎所有 Go 工具在 Windows 上第一次安装都会遇到。解决方法也很简单把 Go bin 目录加进 PATH$env:Path ;$env:USERPROFILE\go\bin或者永久加到环境变量里。如果你不太确定自己的 GOPATH 在哪可以用go env GOPATH查一下把 bin 目录找出来加上。千万别急着重装软件90% 的“命令找不到”都是 PATH 而不是安装本身的问题。2.2 模型接入与配置不要只绑一个模型OpenCode 本身只是一个壳真正干活的是你接入的大模型。我见过很多人只在配置里填了一个模型然后用它干所有的活结果体验很差。为什么因为不同类型任务的“最佳模型”根本不是同一个。做一个复杂的重构规划需要推理能力强的模型跑一个机械的文档补全用轻量模型就够了便宜又省时间。我目前的配置是双模型方案主模型用代码能力最强的那个负责 agent 的规划和最终结果生成辅模型用响应更快的轻量模型用于一些简单任务和 agent 过程中的快速判断。OpenCode 支持在配置里同时声明多个模型还可以在运行时用快捷键或命令临时切换我后面实操部分会讲具体场景。如果你不想付费也有链路能跑通。把本地推理工具接进来让 OpenCode 调用本地模型虽然速度会慢一些但胜在免费、数据不出本机。本地模型做不了太复杂的推理但用来生成注释、补 README 结构这类文档类任务还是够用的。注意它不是开箱即用你需要先在本地把模型服务跑起来然后在 OpenCode 配置里把它加成一个 provider之后在模型选择列表里就能看到它了。配置文件的默认位置在~/.config/opencode/下我贴一个最小可用的配置示例{ provider: { main: anthropic, fallback: openai }, model: { default: claude-sonnet-4-5, light: gpt-4.1-mini }, skills: { enabled: true, directory: ~/.config/opencode/skills } }注意具体 provider 名和模型名会随版本变化别直接照抄先跑opencode models看看当前支持哪些。配置文件的作用是让你在进入交互界面之后少做反复切换提前把“主力/轻量”设定好。2.3 用 VSCode 扩展配合 OpenCode核心是能看到 diff纯终端里用 OpenCode 完全可以但我个人强烈建议在 VSCode 里用官方扩展配合起来原因很简单终端里一个 agent 噼里啪啦改完几个文件你其实很难快速判断它到底动了什么。而在 VSCode 的源代码管理面板里你能看到每一个文件的 diff逐行审查不满意就直接丢弃。这个 workflow 节奏是这样的先在扩展面板里打开 OpenCode 会话告诉它“按开发清单检查 src 目录”它会自己启动 agent 开始读文件、跑扫描。同时你打开源码管理视图能看到它创建了哪些新文件、修改了哪些旧文件。等 agent 写完你逐个文件看 diff保留合理的修改不需要的地方直接 revert。这个体验比纯终端舒服太多了。还一个小技巧VSCode 扩展支持把当前文件或当前选区直接传给 OpenCode。我在代码 review 阶段习惯选中一段可能有性能问题的代码右键选择“发送到 OpenCode”然后让它按清单里的性能项检查这一段。不用给上下文不用描述问题选中即检查。3. 开发检查清单的设计与核心条目3.1 清单设计三原则可执行、有产出、能闭环很多团队把检查清单做成了一篇又长又虚的规范文档列了四五十条但每条都长这样“确保代码性能良好”。这种条目没有任何意义因为拿到它的人不知道具体要做什么拿给 agent 更是无从下手。我设计清单时遵循三个原则第一可执行。每一条清单项必须能翻译成一个具体的检查动作。比如“确保代码性能良好”是不可执行的但“检查是否存在循环内执行 SQL 查询或同步 IO 的代码”就可执行。agent 拿到这句话它知道该去看什么代码模式。第二有产出。清单每一项跑完都应该有明确产出物要么是通过要么是一个修改建议要么是一条已发现的问题记录。不能是“已了解”这种敷衍状态。第三能闭环。发现的问题必须能对应到处理动作。要么代码改了要么文档补了要么被明确标记为“已知限制暂不处理”。否则检查就只是走流程不会对质量产生真实影响。基于这三条原则我把常用清单对应到两个核心维度优化和文档。接下来分别展开。3.2 优化维度清单从业务代码到慢 SQL优化不是玄学也不是靠感觉。大部分性能问题其实都集中在几个固定的模式里。我在检查清单里会把优化这一维度拆成若干条目每一条都对应一种典型问题。下面是我最常用的一组检查项也对应我平时让它执行时的 prompt 模板检查项典型问题让 OpenCode 执行的示例指令循环内 IO在 for 循环里查库、调 HTTP、写文件“扫描 src 下所有 for/forEach/map找出循环体内有 await 数据库查询或外部请求的代码列出行号和原因”N1 查询先查列表再在循环里逐条查详情“检查数据访问层是否存在典型的 N1 查询模式给出合并为批量查询的重构建议”慢 SQL缺索引、全表扫描、SELECT 了多余列“阅读 schema 文件和 DAO 层代码找出没有走索引的大表查询按 explain 输出分析 join 和 where 条件”重复计算同一结果在循环内重复计算未提取到循环外“检查核心计算函数中是否有不依赖循环变量的表达式被放到了循环内部”无界增长列表一直追加、缓存只写不淘汰、日志全量打“检查内存缓存和日志相关代码找出没有容量上限或清理策略的集合变量”大对象传递把整个大对象传入循环或持久化到 session“找出函数参数中有没有跨层传递的大对象评估是否可以改为只传必要字段”每次执行优化清单时我都会在 prompt 里加一条约束先给问题清单和影响评估先不要改代码。原因很简单agent 一上来就改很容易改错方向。先让它把发现的问题列出来我再决定哪些要改、哪些保持现状。这比让它“自己想办法优化”可控得多。这里特别说一下慢 SQL。单纯让 agent 看代码它很难发现 SQL 性能问题因为它看不到数据库的执行计划。我的做法是把 explain 的输出贴给它让它分析是 type 是 ALL、key 是 NULL、rows 扫描了多少行有没有走索引然后再让它结合查询条件给出索引建议。这比让它纯靠代码推理靠谱得多。OpenCode 本身也支持读取文件你可以把 explain 结果保存成一个文本文件直接让它读那个文件再分析。3.3 文档维度清单从注释到 README 再到 CHANGELOG文档这一维度我过去一直很头疼。因为代码是否“正确”有编译器把关但文档是否“完整”没有任何硬性检查。直到我让 OpenCode 来执行文档检查才真正变成一个闭环动作。我的文档清单分三层第一层是代码级文档也就是注释和 API 说明。检查项包括对外导出的函数、组件、类型是否都有 JSDoc/TSDoc 注释注释是否还能反映当前实现有没有功能改了但注释没改的“僵尸注释”有没有重要业务逻辑缺少“为什么这样做”的说明。这块执行起来最容易出效果因为 agent 读代码速度快还能顺着注释和实现的差异给出修改建议。第二层是项目级文档主要是 README。我把 README 的检查点固定为有没有一句话说清项目是做什么的有没有环境依赖和版本要求有没有最小可运行示例有没有配置项说明有没有常见问题板块。凡是缺项直接生成一份对应内容的建议稿。我写这些检查项的时候参考过不少优秀中文开源项目的文档结构比如 Vue 3 官方文档里对基础安装、核心概念、API 参考的层级划分Vant 那种组件库文档对每个组件“属性/事件/方法/插槽”的统一结构。有一个能参考的文档骨架agent 生成出来的东西会规整很多不会瞎写。第三层是版本级文档也就是 CHANGELOG。这一项很多个人项目是不做的但只要你做开源或者团队产品就必须有。检查项是最近的 git log 中标记为 breaking change 的提交是否记录到了 CHANGELOG 的顶部新增功能、修复的 bug、依赖升级是否都有对应条目。我通常会让 OpenCode 读取git log --oneline -30的输出然后对比 CHANGELOG 文件找出遗漏的条目并生成补充文案。这三层文档我的一句话建议是文档的首要目标是让一个从没看过你代码的人能独立地跑通、用会、看懂关键设计而不是追求辞藻和篇幅。4. 把 OpenCode 变成检查清单的执行器实操过程4.1 把清单封装成 SKILL不用反复粘贴 prompt如果你只是临时用一次检查清单直接在 OpenCode 对话框里粘贴 prompt 就够了。但如果你像我一样三天两头就要跑一次完整检查就必须把清单固化成 skill省去重复劳动。OpenCode 的 skill 概念可以通俗理解成给 agent 装一个“专用工具包”。一个 skill 是一个目录里面有说明文件也可以有可执行脚本。调用方式很简单直接在对话里跟上 skill 名字agent 就会加载对应的说明和配置去执行。你可以理解成不用 skills 就像每次叫外卖都要把所有菜名、忌口、配送地址重新说一遍用了 skills 就是把默认偏好都提前存好点击下单就可以。我建了一个叫development-checklist的 skill目录结构大概是这样~/.config/opencode/skills/ └── development-checklist/ ├── SKILL.md └── scripts/ └── check-docs.sh核心文件是SKILL.md里面写清楚这个 skill 的用途、触发场景、执行步骤和输出格式。我摘一段简化版的模板供大家直接用--- name: development-checklist description: 按照优化与文档检查清单对当前项目执行一次完整检查。 --- ## 执行步骤 1. 扫描项目的 src 或核心目录理解整体结构和模块划分。 2. 按优化检查项逐条执行 - 循环内 IO / N1 查询 / 重复计算 / 无界增长 / 大对象传递 - 每条问题输出文件路径 行号 影响评估 优化建议 3. 按文档检查项逐条执行 - README一句话介绍 / 安装步骤 / 最小示例 / 配置说明 - 公开 API 注释缺失项补齐 - CHANGELOG对比最近 30 条 git log列出遗漏条目 4. 输出 Markdown 格式报告结果保存到 checklist-report.md。 5. 过程中不要修改任何代码文件只输出报告。注意最后一步很关键默认只输出报告不改代码。我倾向于先看问题清单再决定是否让 agent 优化避免它在没经我确认的情况下乱改代码。写好这个 SKILL.md 之后在 OpenCode 交互界面里直接说一句话就能触发整套检查按 development-checklist 检查当前项目实测下来一个小型项目几百个文件整体跑一遍通常只需要两三分钟。对规模更大的 monorepo建议按包或按模块拆分执行一次检查一个子项目这样报告更聚焦agent 也不容易被大量文件干扰。4.2 实操案例用 Agent 做一次性能问题定位与优化光说清单有点虚我拿一个实际场景演示完整流程。假设我有一段代码疑似存在循环内查询的问题async function generateOrderReport(orderIds) { const results []; for (const id of orderIds) { const order await db.query(SELECT * FROM orders WHERE id ${id}); const items await db.query(SELECT * FROM order_items WHERE order_id ${id}); results.push({ order, items }); } return results; }以前我可能自己改或者把这段代码贴给 AI 问“怎么优化”。但我现在的做法是把场景交给 OpenCode并给出明确的约束。第一步让 agent 分析问题先不要改代码。我的 prompt 是分析 generateOrderReport 函数的性能特征。重点关注 1. 是否有 N1 查询问题 2. 循环内是否存在不必要的重复 IO 3. 查询语句是否有 SQL 注入风险 输出一份问题清单不要修改代码。agent 的输出会准确指出循环内两次查询的问题并建议改成批量查询或者 join。同时它还会注意到模板字符串拼接 SQL 的注入风险。这一步价值在于我并没有明确提示注入问题但它按优化清单检查时把安全性也捎带看了。第二步让它按约束给出修改方案但只输出 diff 不动文件基于这个问题清单生成重构后的代码。要求 1. 保持原函数的功能不变 2. 使用批量查询替代循环内查询 3. 不要改函数签名的对外形式 4. 只输出 diff不要直接修改文件第三步我确认 diff 没有问题再手动应用或让它执行apply_patch。三步走下来每一处改动都是可解释、可回退的。这套流程里有个细节我要特别强调每次生成代码的任务里一定要加“不要更改函数签名”“保持对外行为不变”这类硬约束。agent 有时候会“顺手”做很多额外的重构把不相关的地方也改一遍。这不是它故意的而是因为它缺少对你项目结构的完整理解。明确约束文件范围和职责边界能省掉大量 review 成本。4.3 用 Agent 批量生成与同步文档维护只花十分钟文档同步这件事最理想的状态是“每次代码变更后顺手做掉”。以前靠人推进基本不可能因为写完代码的人已经不想再面对同一段代码了。用 OpenCode 做这个工作可以从十分钟的拖延变成一个三十秒的触发动作。我常用的一个命令路径是走opencode run直接以非交互方式执行opencode run 读取最近的 git log对比 CHANGELOG.md 的更新记录。如果存在未记录的 breaking change、新增功能或 bugfix按 Conventional Commits 风格补充到 CHANGELOG 顶部。不要修改其他任何文件。这条命令执行完agent 会自己读 git log、读 CHANGELOG、比对、补齐并且只动 CHANGELOG 一个文件。由于加了“不要修改其他文件”的约束它不会跑到别的地方“顺手优化”。README 的同步也一样甚至可以做成一个更完整的脚本流程。比如项目主要结构变了、配置项改了之后我会执行opencode run 扫描项目的 package.json、README.md 和 src 目录。检查 README 中列出的安装方式和配置项是否与当前代码一致。如果发现不一致或有遗漏直接更新 README 并输出 diff 摘要。这里有个容易被忽视的技巧生成的文档质量高度依赖于“项目背景”。如果你只让它扫代码生成文档它生成的 README 会很干缺少业务背景和设计取舍的说明。所以我在让 agent 写文档类内容时会把项目背景和已知设计决策一并写进 prompt。我平时维护了一个项目背景文档放在 docs/background.md 里生成 README 时让 agent 先读它再动笔。文档这块的完整闭环其实还包括自检生成完以后我会让 agent 以“第一次接触项目的读者”视角复读一遍指出哪里说明不清、哪里缺示例。这个“文档自动 review”的步骤很容易被忽略但对提升文档质量帮助极大。5. 实际使用中的常见问题与排查实录5.1 安装和权限相关的典型报错我梳理一下这半年遇到的高频问题方便你排查时对照报错或现象可能的原因解决方法无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称安装路径不在 PATH 中找到全局安装目录npm prefix 或 GOPATH/bin加入 PATH 后重启终端agent 报“模型未配置”或类似错误config 里 provider 名称或模型名不存在先运行 opencode models 查看可用列表修正配置执行优化任务时改动范围超出预期prompt 里没有限制文件范围重跑时明确写“只检查 src 目录”“不要修改文件”等约束条件非交互模式下长时间无响应模型响应慢或 agent 循环内步骤过多切换到轻量模型处理简单步骤或给任务增加更明确的子目标拆解在 VSCode 扩展里启动 agent 后源码管理面板一片红agent 改动了大量文件包括格式化类修改先在 prompt 里要求“只输出 diff 不直接改文件”确认后统一应用第一个问题我前面已经详细讲过了这里再说一个我忽略过的细节如果你用nvm或者fnm这类 Node 版本管理器全局安装的包路径通常和系统终端默认 PATH 不一致容易出现“刚才还能用换个窗口就找不到”的情况。这种问题不是 OpenCode 的锅是你 Node 环境多版本切换导致的路径差异把当前 Node 全局 bin 目录加进用户级 PATH 即可。5.2 让 Agent 做优化时最容易翻车的三个操作虽然我把优化清单写得很细但 agent 执行优化任务时还是有几个高概率翻车点。你提前知道这些,能少走非常多弯路。第一个翻车点agent 只看了被修改的局部代码没看调用方结果改坏了接口约定。比如把某个函数的入参从一个对象改成多个基础类型参数表面看着更“干净”了但所有调用方全部报错。我吃过一次亏之后凡是涉及修改已有代码的优化任务都会在 prompt 里强制加一句“找出所有调用该函数的位置确认修改不会破坏调用方”。第二个翻车点agent 过度抽象把简单功能重构成一整套继承体系或策略模式。这类问题在“大模型自作聪明”式的优化里尤其常见。它的判断标准是“代码模式更优雅”但我的判断标准是“以后的人看到这段代码能立刻看懂”。所以我给优化清单立了一条规矩除非当前代码存在真实的、可感知的问题bug、性能、安全、可维护性硬伤否则不做结构性重构。小步优化优先于大型重构。第三个翻车点agent 优化算法时“假设”了一个输入边界但这个边界可能并不成立。比如说它把某个数组去重优化成基于 Set 的一次性转换但如果原逻辑允许重复项且后续依赖这个重复计数这就直接改变了语义。处理方式很简单任何算法层面的优化要求 agent 先解释它理解的函数输入输出和边界条件确认无误之后再让它给出修改方案。这一步非常值钱。5.3 文档生成内容偏移的问题文档生成也有自己的坑。最大的问题是风格不一致。让 agent 生成 README直接交给它跑十次可能有八次生成出来的是那种“万能模板味”的文档大量使用“本项目是一个…”这类空泛描述说了一堆概念但没有任何一个真实代码示例。原因很简单它没有可参考的“风格锚点”。我自己的解法是给文档类任务附一个风格参考。第一次生成项目文档时先让 agent 阅读项目中已有的文档片段或我指定的几个“标杆文档”明确告诉它“输出风格与这些参考保持一致”。如果项目里实在没有参考文档我会先写一小段开头让它顺着这个基调续写。基于“开头风格”的续写通常比让它从零生成要自然得多。第二个偏移是内容的“断层”。agent 生成的 API 文档常常是基于代码注释直接罗列的没有把功能之间的关联和使用场景讲清楚。这类问题没法靠 prompt 完全解决但可以让 agent 站在新用户角度重新阅读一遍文档专门挑“读完了还不知道怎么用”的地方补充说明。相当于对文档做一次“用户测试”虽然不如真人测试准确但成本低了很多。最后再分享一点我自己的使用体会把优化和文档做成检查清单再让 OpenCode 去执行最大的收益不是省了多少时间而是我在交付前的心态变了。以前提交代码前我会潜意识里担心“是不是漏了哪里”现在不太会了——我知道我有一份清单而且有一个不会偷懒的 agent 会帮我把清单跑完。还有个额外的好处这个 skill 是可以积累的。每踩一个坑、每发现一类新问题就往清单里补一条。三个月之后你的检查清单就不是网上复制来的通用版了而是完全长在你项目历史和你个人复盘上的“私人清单”。这比任何通用模板都值钱。如果你也想搭一套类似的流程我建议从最小的闭环开始先只写 README 检查和 CHANGELOG 检查这两条跑通 OpenCode 的 skill 机制再逐步加入性能相关条目。一上来全量上反而容易被冗长的检查报告劝退。工具这东西归根到底还是得适合你的使用习惯才能长期用下去。
用OpenCode将代码优化与文档检查清单自动化，打造团队开发规范
先说一个很实在的观察OpenCode 这类命令行 AI 编程工具绝大多数人装完以后只干了一件事——把它当成一个加强版聊天框遇到问题复制报错进去拿到答案再复制出来。这当然有用但它真正值钱的能力其实是把“开发检查清单”这种偏流程化、偏规范的事情交给一个不会累、不会忘、还愿意按你的要求逐项执行的 agent 去跑。我这一年的用法发生了很大变化从“哪里不会问哪里”变成了先把优化和文档这两个最容易被跳过的环节固化成一套明确的检查项。然后让 OpenCode 做我的检查执行器——先照着清单扫代码、再给优化建议、最后把文档同步补齐整个过程可复现、可交给 CI、也可丢给团队里任何一个同事去跑。这篇文章就围绕这套思路展开适合正在用或打算用 OpenCode 做日常开发的人也包括那些想给团队沉淀一套工程规范但不想靠人肉 Reviewer 硬扛的开发者。我不会通篇讲概念尽量把安装、配置、清单设计、实际命令和踩坑经历都揉在一起你能直接照着抄。1. 为什么把优化和文档作为检查清单的核心1.1 OpenCode 这类工具真正的价值不在“写代码”聊 OpenCode 之前先说清楚我理解的这类工具的本质。它不是一个简单的代码补全插件而是一个具备“规划、执行、观察结果”能力的 agent 框架。你可以给它一个目标它会自己拆解任务、读文件、调用命令行工具、运行测试、根据输出调整策略。这跟传统 IDE 的自动补全完全不是一个物种——补全是在你写的时候帮忙续写agent 是能自己闭环地做一件相对复杂的工程任务。那这和“优化”“文档”有什么关系关系非常大。因为写代码这件事AI 做得已经不错了但写完代码之后那些“收尾工作”——检查性能隐患、清理冗余逻辑、补注释、更新文档、维护 CHANGELOG——才是最消耗人的。这些事有三个特点一是重复性高二是多数情况下不紧急三是遗漏了也不会立刻爆炸。正因如此它们恰恰是最容易被人在忙碌中跳过的环节。OpenCode 这类工具的到来改变了这个局面。因为这些事情非常结构化非常适合转成清单让 agent 去逐项执行。比如代码里有没有未捕获的异常有没有重复的三方依赖有没有已经不被引用的导出函数这些都可以通过静态扫描或让 agent 读代码来检查。重点不在于它 100% 准确而在于它能稳定地、低成本地、一遍又一遍地执行同样的检查动作。人做不到这种稳定性人会累、会烦、会在赶进度的时候偷偷把检查这步省略。所以我的结论是OpenCode 的真正价值不是帮你把代码写得更快而是帮你把代码“交付之前的那一公里”走得更稳。而这个“一公里”就是检查清单最值得覆盖的领域——优化和文档。1.2 开发检查清单在交付流程里的定位我见过很多团队做代码审查Reviewer 往往把精力全放在“逻辑对不对”上至于性能隐患、文档同步、是否有无用的调试代码很少人会在意。这不能怪 Reviewers人脑的注意力带宽是有限的一次 review 能关注 3 个维度就已经很好了。检查清单这件事航空业做得最好。飞行员起飞前不会靠记忆去逐项确认而是拿着一张卡片从左到右、从上到下一项项核。开发也应该一样把你过去踩过的坑、团队约定过的规范、开源社区总结出的最佳实践都写进清单里。写清单不是为了“管住人”是为了把“记得检查”这件事从大脑里挪出去让大脑专注在处理真正需要判断的事情上。我给自己用的清单有三个来源过去半年里真实出现过的线上事故和严重 bug每一项都是一个检查项。团队里在 PR 评论中反复提到的意见比如“这个字段要加索引”“这里日志级别用错了”“这个接口缺鉴权”。开源文档规范里常见的硬性要求比如“README 必须包含安装和最小示例”“公开 API 必须有注释”“破坏性变更必须写进 CHANGELOG”。这些来源都非常务实没有任何一条是“为了规范而规范”。而在 OpenCode 出现以前这套清单的执行成本其实不低每一条都需要人手动去翻代码、去验证。现在有了 agent清单的执行方式变成了——你把清单写成 skill 或 prompt让 OpenCode 去跑跑完它给你一份报告你只需要审核报告即可。这也是我把优化和文档作为核心的原因。性能问题具有隐蔽性和滞后性文档问题具有累积性。它们都是“不做检查也能正常跑一段日子”的软性问题如果不通过清单强制检查几乎必然被推迟到“以后再说”然后就没有然后了。2. 环境准备与工具选择先把手里的家伙备齐2.1 安装 OpenCode两种版本、一条 PATH 的坑我用 OpenCode 的时间不算短从最早的原生 CLI 到现在的版本整体感受是TypeScript 版本功能最全插件生态和 VSCode 扩展配合得最好后来社区里出现的 Go 版本主打启动速度和内存占用如果你习惯让 agent 常驻终端、频繁切换任务Go 版会更舒服一点。功能上两个版本基本对齐但一些新功能和实验性特性通常先在 TypeScript 版上线所以我实际主力用的还是前者。安装方式最简单的就是走 npm 全局安装npm install -g opencode-ai/opencode装完以后运行opencode --version验一下。如果你用的是 Go 版go install github.com/opencode-ai/opencodelatest这个方式有个坑我踩过Go 默认装到$GOPATH/bin如果这个目录不在你的 PATH 里运行opencode就会直接报“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这个报错特别典型不只是 OpenCode几乎所有 Go 工具在 Windows 上第一次安装都会遇到。解决方法也很简单把 Go bin 目录加进 PATH$env:Path ;$env:USERPROFILE\go\bin或者永久加到环境变量里。如果你不太确定自己的 GOPATH 在哪可以用go env GOPATH查一下把 bin 目录找出来加上。千万别急着重装软件90% 的“命令找不到”都是 PATH 而不是安装本身的问题。2.2 模型接入与配置不要只绑一个模型OpenCode 本身只是一个壳真正干活的是你接入的大模型。我见过很多人只在配置里填了一个模型然后用它干所有的活结果体验很差。为什么因为不同类型任务的“最佳模型”根本不是同一个。做一个复杂的重构规划需要推理能力强的模型跑一个机械的文档补全用轻量模型就够了便宜又省时间。我目前的配置是双模型方案主模型用代码能力最强的那个负责 agent 的规划和最终结果生成辅模型用响应更快的轻量模型用于一些简单任务和 agent 过程中的快速判断。OpenCode 支持在配置里同时声明多个模型还可以在运行时用快捷键或命令临时切换我后面实操部分会讲具体场景。如果你不想付费也有链路能跑通。把本地推理工具接进来让 OpenCode 调用本地模型虽然速度会慢一些但胜在免费、数据不出本机。本地模型做不了太复杂的推理但用来生成注释、补 README 结构这类文档类任务还是够用的。注意它不是开箱即用你需要先在本地把模型服务跑起来然后在 OpenCode 配置里把它加成一个 provider之后在模型选择列表里就能看到它了。配置文件的默认位置在~/.config/opencode/下我贴一个最小可用的配置示例{ provider: { main: anthropic, fallback: openai }, model: { default: claude-sonnet-4-5, light: gpt-4.1-mini }, skills: { enabled: true, directory: ~/.config/opencode/skills } }注意具体 provider 名和模型名会随版本变化别直接照抄先跑opencode models看看当前支持哪些。配置文件的作用是让你在进入交互界面之后少做反复切换提前把“主力/轻量”设定好。2.3 用 VSCode 扩展配合 OpenCode核心是能看到 diff纯终端里用 OpenCode 完全可以但我个人强烈建议在 VSCode 里用官方扩展配合起来原因很简单终端里一个 agent 噼里啪啦改完几个文件你其实很难快速判断它到底动了什么。而在 VSCode 的源代码管理面板里你能看到每一个文件的 diff逐行审查不满意就直接丢弃。这个 workflow 节奏是这样的先在扩展面板里打开 OpenCode 会话告诉它“按开发清单检查 src 目录”它会自己启动 agent 开始读文件、跑扫描。同时你打开源码管理视图能看到它创建了哪些新文件、修改了哪些旧文件。等 agent 写完你逐个文件看 diff保留合理的修改不需要的地方直接 revert。这个体验比纯终端舒服太多了。还一个小技巧VSCode 扩展支持把当前文件或当前选区直接传给 OpenCode。我在代码 review 阶段习惯选中一段可能有性能问题的代码右键选择“发送到 OpenCode”然后让它按清单里的性能项检查这一段。不用给上下文不用描述问题选中即检查。3. 开发检查清单的设计与核心条目3.1 清单设计三原则可执行、有产出、能闭环很多团队把检查清单做成了一篇又长又虚的规范文档列了四五十条但每条都长这样“确保代码性能良好”。这种条目没有任何意义因为拿到它的人不知道具体要做什么拿给 agent 更是无从下手。我设计清单时遵循三个原则第一可执行。每一条清单项必须能翻译成一个具体的检查动作。比如“确保代码性能良好”是不可执行的但“检查是否存在循环内执行 SQL 查询或同步 IO 的代码”就可执行。agent 拿到这句话它知道该去看什么代码模式。第二有产出。清单每一项跑完都应该有明确产出物要么是通过要么是一个修改建议要么是一条已发现的问题记录。不能是“已了解”这种敷衍状态。第三能闭环。发现的问题必须能对应到处理动作。要么代码改了要么文档补了要么被明确标记为“已知限制暂不处理”。否则检查就只是走流程不会对质量产生真实影响。基于这三条原则我把常用清单对应到两个核心维度优化和文档。接下来分别展开。3.2 优化维度清单从业务代码到慢 SQL优化不是玄学也不是靠感觉。大部分性能问题其实都集中在几个固定的模式里。我在检查清单里会把优化这一维度拆成若干条目每一条都对应一种典型问题。下面是我最常用的一组检查项也对应我平时让它执行时的 prompt 模板检查项典型问题让 OpenCode 执行的示例指令循环内 IO在 for 循环里查库、调 HTTP、写文件“扫描 src 下所有 for/forEach/map找出循环体内有 await 数据库查询或外部请求的代码列出行号和原因”N1 查询先查列表再在循环里逐条查详情“检查数据访问层是否存在典型的 N1 查询模式给出合并为批量查询的重构建议”慢 SQL缺索引、全表扫描、SELECT 了多余列“阅读 schema 文件和 DAO 层代码找出没有走索引的大表查询按 explain 输出分析 join 和 where 条件”重复计算同一结果在循环内重复计算未提取到循环外“检查核心计算函数中是否有不依赖循环变量的表达式被放到了循环内部”无界增长列表一直追加、缓存只写不淘汰、日志全量打“检查内存缓存和日志相关代码找出没有容量上限或清理策略的集合变量”大对象传递把整个大对象传入循环或持久化到 session“找出函数参数中有没有跨层传递的大对象评估是否可以改为只传必要字段”每次执行优化清单时我都会在 prompt 里加一条约束先给问题清单和影响评估先不要改代码。原因很简单agent 一上来就改很容易改错方向。先让它把发现的问题列出来我再决定哪些要改、哪些保持现状。这比让它“自己想办法优化”可控得多。这里特别说一下慢 SQL。单纯让 agent 看代码它很难发现 SQL 性能问题因为它看不到数据库的执行计划。我的做法是把 explain 的输出贴给它让它分析是 type 是 ALL、key 是 NULL、rows 扫描了多少行有没有走索引然后再让它结合查询条件给出索引建议。这比让它纯靠代码推理靠谱得多。OpenCode 本身也支持读取文件你可以把 explain 结果保存成一个文本文件直接让它读那个文件再分析。3.3 文档维度清单从注释到 README 再到 CHANGELOG文档这一维度我过去一直很头疼。因为代码是否“正确”有编译器把关但文档是否“完整”没有任何硬性检查。直到我让 OpenCode 来执行文档检查才真正变成一个闭环动作。我的文档清单分三层第一层是代码级文档也就是注释和 API 说明。检查项包括对外导出的函数、组件、类型是否都有 JSDoc/TSDoc 注释注释是否还能反映当前实现有没有功能改了但注释没改的“僵尸注释”有没有重要业务逻辑缺少“为什么这样做”的说明。这块执行起来最容易出效果因为 agent 读代码速度快还能顺着注释和实现的差异给出修改建议。第二层是项目级文档主要是 README。我把 README 的检查点固定为有没有一句话说清项目是做什么的有没有环境依赖和版本要求有没有最小可运行示例有没有配置项说明有没有常见问题板块。凡是缺项直接生成一份对应内容的建议稿。我写这些检查项的时候参考过不少优秀中文开源项目的文档结构比如 Vue 3 官方文档里对基础安装、核心概念、API 参考的层级划分Vant 那种组件库文档对每个组件“属性/事件/方法/插槽”的统一结构。有一个能参考的文档骨架agent 生成出来的东西会规整很多不会瞎写。第三层是版本级文档也就是 CHANGELOG。这一项很多个人项目是不做的但只要你做开源或者团队产品就必须有。检查项是最近的 git log 中标记为 breaking change 的提交是否记录到了 CHANGELOG 的顶部新增功能、修复的 bug、依赖升级是否都有对应条目。我通常会让 OpenCode 读取git log --oneline -30的输出然后对比 CHANGELOG 文件找出遗漏的条目并生成补充文案。这三层文档我的一句话建议是文档的首要目标是让一个从没看过你代码的人能独立地跑通、用会、看懂关键设计而不是追求辞藻和篇幅。4. 把 OpenCode 变成检查清单的执行器实操过程4.1 把清单封装成 SKILL不用反复粘贴 prompt如果你只是临时用一次检查清单直接在 OpenCode 对话框里粘贴 prompt 就够了。但如果你像我一样三天两头就要跑一次完整检查就必须把清单固化成 skill省去重复劳动。OpenCode 的 skill 概念可以通俗理解成给 agent 装一个“专用工具包”。一个 skill 是一个目录里面有说明文件也可以有可执行脚本。调用方式很简单直接在对话里跟上 skill 名字agent 就会加载对应的说明和配置去执行。你可以理解成不用 skills 就像每次叫外卖都要把所有菜名、忌口、配送地址重新说一遍用了 skills 就是把默认偏好都提前存好点击下单就可以。我建了一个叫development-checklist的 skill目录结构大概是这样~/.config/opencode/skills/ └── development-checklist/ ├── SKILL.md └── scripts/ └── check-docs.sh核心文件是SKILL.md里面写清楚这个 skill 的用途、触发场景、执行步骤和输出格式。我摘一段简化版的模板供大家直接用--- name: development-checklist description: 按照优化与文档检查清单对当前项目执行一次完整检查。 --- ## 执行步骤 1. 扫描项目的 src 或核心目录理解整体结构和模块划分。 2. 按优化检查项逐条执行 - 循环内 IO / N1 查询 / 重复计算 / 无界增长 / 大对象传递 - 每条问题输出文件路径 行号 影响评估 优化建议 3. 按文档检查项逐条执行 - README一句话介绍 / 安装步骤 / 最小示例 / 配置说明 - 公开 API 注释缺失项补齐 - CHANGELOG对比最近 30 条 git log列出遗漏条目 4. 输出 Markdown 格式报告结果保存到 checklist-report.md。 5. 过程中不要修改任何代码文件只输出报告。注意最后一步很关键默认只输出报告不改代码。我倾向于先看问题清单再决定是否让 agent 优化避免它在没经我确认的情况下乱改代码。写好这个 SKILL.md 之后在 OpenCode 交互界面里直接说一句话就能触发整套检查按 development-checklist 检查当前项目实测下来一个小型项目几百个文件整体跑一遍通常只需要两三分钟。对规模更大的 monorepo建议按包或按模块拆分执行一次检查一个子项目这样报告更聚焦agent 也不容易被大量文件干扰。4.2 实操案例用 Agent 做一次性能问题定位与优化光说清单有点虚我拿一个实际场景演示完整流程。假设我有一段代码疑似存在循环内查询的问题async function generateOrderReport(orderIds) { const results []; for (const id of orderIds) { const order await db.query(SELECT * FROM orders WHERE id ${id}); const items await db.query(SELECT * FROM order_items WHERE order_id ${id}); results.push({ order, items }); } return results; }以前我可能自己改或者把这段代码贴给 AI 问“怎么优化”。但我现在的做法是把场景交给 OpenCode并给出明确的约束。第一步让 agent 分析问题先不要改代码。我的 prompt 是分析 generateOrderReport 函数的性能特征。重点关注 1. 是否有 N1 查询问题 2. 循环内是否存在不必要的重复 IO 3. 查询语句是否有 SQL 注入风险 输出一份问题清单不要修改代码。agent 的输出会准确指出循环内两次查询的问题并建议改成批量查询或者 join。同时它还会注意到模板字符串拼接 SQL 的注入风险。这一步价值在于我并没有明确提示注入问题但它按优化清单检查时把安全性也捎带看了。第二步让它按约束给出修改方案但只输出 diff 不动文件基于这个问题清单生成重构后的代码。要求 1. 保持原函数的功能不变 2. 使用批量查询替代循环内查询 3. 不要改函数签名的对外形式 4. 只输出 diff不要直接修改文件第三步我确认 diff 没有问题再手动应用或让它执行apply_patch。三步走下来每一处改动都是可解释、可回退的。这套流程里有个细节我要特别强调每次生成代码的任务里一定要加“不要更改函数签名”“保持对外行为不变”这类硬约束。agent 有时候会“顺手”做很多额外的重构把不相关的地方也改一遍。这不是它故意的而是因为它缺少对你项目结构的完整理解。明确约束文件范围和职责边界能省掉大量 review 成本。4.3 用 Agent 批量生成与同步文档维护只花十分钟文档同步这件事最理想的状态是“每次代码变更后顺手做掉”。以前靠人推进基本不可能因为写完代码的人已经不想再面对同一段代码了。用 OpenCode 做这个工作可以从十分钟的拖延变成一个三十秒的触发动作。我常用的一个命令路径是走opencode run直接以非交互方式执行opencode run 读取最近的 git log对比 CHANGELOG.md 的更新记录。如果存在未记录的 breaking change、新增功能或 bugfix按 Conventional Commits 风格补充到 CHANGELOG 顶部。不要修改其他任何文件。这条命令执行完agent 会自己读 git log、读 CHANGELOG、比对、补齐并且只动 CHANGELOG 一个文件。由于加了“不要修改其他文件”的约束它不会跑到别的地方“顺手优化”。README 的同步也一样甚至可以做成一个更完整的脚本流程。比如项目主要结构变了、配置项改了之后我会执行opencode run 扫描项目的 package.json、README.md 和 src 目录。检查 README 中列出的安装方式和配置项是否与当前代码一致。如果发现不一致或有遗漏直接更新 README 并输出 diff 摘要。这里有个容易被忽视的技巧生成的文档质量高度依赖于“项目背景”。如果你只让它扫代码生成文档它生成的 README 会很干缺少业务背景和设计取舍的说明。所以我在让 agent 写文档类内容时会把项目背景和已知设计决策一并写进 prompt。我平时维护了一个项目背景文档放在 docs/background.md 里生成 README 时让 agent 先读它再动笔。文档这块的完整闭环其实还包括自检生成完以后我会让 agent 以“第一次接触项目的读者”视角复读一遍指出哪里说明不清、哪里缺示例。这个“文档自动 review”的步骤很容易被忽略但对提升文档质量帮助极大。5. 实际使用中的常见问题与排查实录5.1 安装和权限相关的典型报错我梳理一下这半年遇到的高频问题方便你排查时对照报错或现象可能的原因解决方法无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称安装路径不在 PATH 中找到全局安装目录npm prefix 或 GOPATH/bin加入 PATH 后重启终端agent 报“模型未配置”或类似错误config 里 provider 名称或模型名不存在先运行 opencode models 查看可用列表修正配置执行优化任务时改动范围超出预期prompt 里没有限制文件范围重跑时明确写“只检查 src 目录”“不要修改文件”等约束条件非交互模式下长时间无响应模型响应慢或 agent 循环内步骤过多切换到轻量模型处理简单步骤或给任务增加更明确的子目标拆解在 VSCode 扩展里启动 agent 后源码管理面板一片红agent 改动了大量文件包括格式化类修改先在 prompt 里要求“只输出 diff 不直接改文件”确认后统一应用第一个问题我前面已经详细讲过了这里再说一个我忽略过的细节如果你用nvm或者fnm这类 Node 版本管理器全局安装的包路径通常和系统终端默认 PATH 不一致容易出现“刚才还能用换个窗口就找不到”的情况。这种问题不是 OpenCode 的锅是你 Node 环境多版本切换导致的路径差异把当前 Node 全局 bin 目录加进用户级 PATH 即可。5.2 让 Agent 做优化时最容易翻车的三个操作虽然我把优化清单写得很细但 agent 执行优化任务时还是有几个高概率翻车点。你提前知道这些,能少走非常多弯路。第一个翻车点agent 只看了被修改的局部代码没看调用方结果改坏了接口约定。比如把某个函数的入参从一个对象改成多个基础类型参数表面看着更“干净”了但所有调用方全部报错。我吃过一次亏之后凡是涉及修改已有代码的优化任务都会在 prompt 里强制加一句“找出所有调用该函数的位置确认修改不会破坏调用方”。第二个翻车点agent 过度抽象把简单功能重构成一整套继承体系或策略模式。这类问题在“大模型自作聪明”式的优化里尤其常见。它的判断标准是“代码模式更优雅”但我的判断标准是“以后的人看到这段代码能立刻看懂”。所以我给优化清单立了一条规矩除非当前代码存在真实的、可感知的问题bug、性能、安全、可维护性硬伤否则不做结构性重构。小步优化优先于大型重构。第三个翻车点agent 优化算法时“假设”了一个输入边界但这个边界可能并不成立。比如说它把某个数组去重优化成基于 Set 的一次性转换但如果原逻辑允许重复项且后续依赖这个重复计数这就直接改变了语义。处理方式很简单任何算法层面的优化要求 agent 先解释它理解的函数输入输出和边界条件确认无误之后再让它给出修改方案。这一步非常值钱。5.3 文档生成内容偏移的问题文档生成也有自己的坑。最大的问题是风格不一致。让 agent 生成 README直接交给它跑十次可能有八次生成出来的是那种“万能模板味”的文档大量使用“本项目是一个…”这类空泛描述说了一堆概念但没有任何一个真实代码示例。原因很简单它没有可参考的“风格锚点”。我自己的解法是给文档类任务附一个风格参考。第一次生成项目文档时先让 agent 阅读项目中已有的文档片段或我指定的几个“标杆文档”明确告诉它“输出风格与这些参考保持一致”。如果项目里实在没有参考文档我会先写一小段开头让它顺着这个基调续写。基于“开头风格”的续写通常比让它从零生成要自然得多。第二个偏移是内容的“断层”。agent 生成的 API 文档常常是基于代码注释直接罗列的没有把功能之间的关联和使用场景讲清楚。这类问题没法靠 prompt 完全解决但可以让 agent 站在新用户角度重新阅读一遍文档专门挑“读完了还不知道怎么用”的地方补充说明。相当于对文档做一次“用户测试”虽然不如真人测试准确但成本低了很多。最后再分享一点我自己的使用体会把优化和文档做成检查清单再让 OpenCode 去执行最大的收益不是省了多少时间而是我在交付前的心态变了。以前提交代码前我会潜意识里担心“是不是漏了哪里”现在不太会了——我知道我有一份清单而且有一个不会偷懒的 agent 会帮我把清单跑完。还有个额外的好处这个 skill 是可以积累的。每踩一个坑、每发现一类新问题就往清单里补一条。三个月之后你的检查清单就不是网上复制来的通用版了而是完全长在你项目历史和你个人复盘上的“私人清单”。这比任何通用模板都值钱。如果你也想搭一套类似的流程我建议从最小的闭环开始先只写 README 检查和 CHANGELOG 检查这两条跑通 OpenCode 的 skill 机制再逐步加入性能相关条目。一上来全量上反而容易被冗长的检查报告劝退。工具这东西归根到底还是得适合你的使用习惯才能长期用下去。 
