opencode与skill实战：AI编程代理的开源终端方案与技能扩展机制

1. 认识opencode与skill：一次搞懂这两个AI编程圈的热词

最近AI编程圈子里，"opencode"和"skill"这两个词出现频率高得吓人。我自己的几个技术群，几乎每天都有人问"opencode怎么装""skill到底是什么，和插件有什么区别"。今天就把这两个东西掰开了讲清楚，先说我用下来的直观感受：如果说Claude Code是给会用终端的人准备的AI编程助手，那opencode就是把这套玩法开源化、自由化之后，让每个人都能在终端里拥有一个高度定制化的AI编程代理。

那skill又是什么？一句话解释：skill是给AI助手准备的"可复用能力包"。打个比方，你请了一个全能助理（AI），他什么都会一点，但你对他说"帮我把这份合同审一遍"，他可能只会泛泛地看。而你给他一份"合同审查清单"（skill），上面写着要看哪些条款、重点标什么、格式怎么统一，他再干活的时候，质量和效率立刻不一样。skill就是这份"审查清单"，只是它有规范的书写格式，AI能读得懂、用得上。

这篇文章适合谁看？三类人：一是刚接触opencode、不知道从哪下手的初学者；二是已经在用Claude Code或Codex CLI、想对比一下哪个更好用、怎么把skill机制玩明白的中级玩家；三是想给自己的AI代理工作流定制专属能力的高级用户。下面的内容会覆盖opencode的安装、模型配置、skill的创建与使用、与MCP的区别，以及一堆我实际踩过的坑，保证你能照着操作。

先放一张整体的技术分层图，让你心里有个底：

• 应用层：opencode CLI终端工具、VS Code插件、IDEA插件、桌面客户端
• 能力层：skill技能包（本地目录结构）、MCP服务（外部工具链接）、模型接入（OpenAI兼容协议、免费模型）
• 调度层：opencode核心引擎（自动规划、多文件编辑、命令执行、上下文管理）
• 模型层：GPT、Claude、Gemini、DeepSeek、Qwen，以及各类本地模型服务

我用的环境是Windows 11 + WSL2 Ubuntu，Node.js 20 LTS。这个组合是目前社区里兼容性最好、文档最全的搭配，如果你是Linux或macOS，差异也不大，命令基本通用。

2. 为什么是opencode：架构设计与方案选型背后的逻辑

2.1 opencode到底是什么

先说结论：opencode是一个开源的AI编程代理（AI coding agent），本质上是一个跑在终端里的命令行工具。你给它一个任务，比如"给我写一个Python脚本，批量重命名文件夹里的图片文件"，它会自动拆解任务、调用模型、读取上下文、编辑文件、执行命令，甚至自己给自己装依赖、跑测试，全程不需要你动手敲代码。

听起来很像Claude Code或Codex CLI对不对？确实，opencode的交互模式和服务对象与它们高度重合，但它有一项核心差异：完全开源、可离线部署、模型自由接入。这意味着你可以不用OpenAI的API，也不用Anthropic的API，而是接入DeepSeek、Qwen、Ollama本地模型，甚至公司内网部署的私有模型。对于有数据安全要求的团队来说，这一条就是生死线。

我最早是从Twitter上看到一个外国开发者用opencode在终端里写了一个完整的Rust项目，全程只用语音输入，当时就震惊了。后来我去翻它的GitHub仓库，才发现它的架构设计相当讲究：核心引擎负责规划和执行，模型接入层用统一的SDK支持各家模型，插件和skill机制则让生态可扩展。

2.2 opencode的核心架构与工作流

opencode的工作流可以概括为"Plan → Act → Observe → Repeat"的循环，也就是"规划-执行-观察-迭代"。具体来说：

1. 你输入一个自然语言任务（比如"修复这个项目的类型错误"）。
2. opencode把任务交给大模型，模型先生成一个执行计划（Plan）。
3. opencode按计划执行操作：读取文件、修改文件、运行命令（Act）。
4. 执行后，opencode收集输出、错误信息、测试结果（Observe）。
5. 如果任务没完成或出了错，它会带着新的上下文再次进入规划，直到解决或向你求助（Repeat）。

这个循环的设计理念，说白了就是让AI不仅"会聊天"，更"会干活"。我把它理解为"终端版的自动驾驶"——你只设定目的地，中间怎么转弯、怎么避障、怎么停车，它自己搞定。

要实现这个循环，opencode的架构里几个模块缺一不可：

• 会话管理模块：负责维护当前对话的上下文，包括历史记录、文件状态、用户偏好。这就像人的短期记忆，AI不记得前几步干了什么，后面就全乱了。
• 工具调用模块：封装了文件读写、命令执行、网络请求等基础能力。opencode默认内置了十几种工具，比如read_file、edit_file、run_command等，skill里的指令最终也是通过这套工具去执行的。
• 模型接入模块：通过OpenAI兼容协议，把各家的模型统一成一个接口。这就好比你家的排插，不管你买的是公牛还是小米的插头，只要符合国标，插上去都能用。
• Skill加载模块：扫描指定目录下的skill包，把其中有用的指令注入到系统提示词或上下文里，让模型在行动时能调用这些"经验"。

2.3 为什么选择"终端+skill"这套组合，而不是IDE插件

这个我多说两句，因为很多人问我："既然有VS Code插件、有IDEA插件，为什么还要用终端？"我的体会是：终端是AI代理的主场，IDE是AI辅助的战场。两者定位完全不同。

• 终端：无头环境、无界面干扰，AI可以自由地执行命令、跑脚本、看日志，自主性最强。但它给用户的控制感弱，如果你习惯看着代码变绿变红，终端里没那么直观。
• IDE插件：你可以看到AI改动的每一行代码，更可控，但它本质上还是"助手"，干一个重要任务还得你一步步确认，效率上不去。
• skill机制：补充的是"专业能力"维度。IDE插件往往是通用聊天补全，而skill是一份结构化的领域知识+工作流模板。给AI装上"合同审查skill"它就能处理合同，装上"数学建模skill"它就能帮你分析竞赛题目。这比每次对话都重新描述一遍要求，不知道高到哪里去了。

所以我的建议是：日常小改动用IDE插件，跑整体任务、批量重构、搭建项目骨架，用终端+opencode+skill。两者不冲突，你可以并行使用。

2.4 opencode与其他工具的关系与差异

这里我结合自己用过的几款工具，做个直观对比：

可以看到opencode主要的卖点是"模型自由度+插件扩展能力"。我特别强调一句：如果你手上的主力模型是Claude或GPT，那其实用官方工具更省心；如果你经常要切换模型、或者公司有私有化部署需求，opencode才是最优解。

3. skill机制深度拆解：它和MCP、插件到底有什么区别

3.1 skill到底是什么，规则是什么

先说skill的定义。在opencode的语境里，skill就是一个文件夹，里面包含一个SKILL.md主文件，以及若干辅助资源文件。它的目录结构长这样：

my-skill/ ├── SKILL.md # 核心指令文件，必须存在 ├── reference/ # 参考资料，可选 │ ├── style-guide.md │ └── examples.md └── scripts/ # 可执行脚本，可选 └── check.py

SKILL.md用Markdown编写，里面写清楚这个skill是干什么的、在什么场景下使用、应该按什么步骤执行、重点关注什么。当opencode加载这个skill时，SKILL.md的内容会被注入到模型的上下文中，相当于给模型发了一份"工作手册"。

从实现原理上说，skill本质上是"系统提示词的模块化封装"。在没用skill之前，你要在每次对话里写"请你扮演一个资深律师，审查合同的时候重点看违约金条款、争议解决条款……"，用了skill之后，你只需要跟opencode说"用合同审查skill处理这份文件"，它会自动从skill目录里找到对应指令，然后按标准流程走。

这套机制的第一个好处是知识复用。你积累的审查清单、编码规范、故障排查手册，都可以沉淀成skill文件，下次遇到同类任务，AI直接就按你的标准做。第二个好处是团队共享。整个技能包做成一个git仓库，团队成员clone下来就能用，统一工作流，减少沟通成本。

3.2 skill和MCP的区别，别再搞混了

热词里有一句"agent skill和MCP有什么区别"，这确实是最容易被混淆的一对概念。我尝试用最简单的方式说清楚：

• skill：一份给AI的"说明书"，教它"怎么做"。它不连接外部系统，只是把知识和流程告诉AI。它回答的是"怎么做"的问题。
• MCP（Model Context Protocol）：一个给AI的"连接器"，让它能用外部工具。它连接文件系统、数据库、浏览器、API服务等真实环境。它回答的是"能调用什么"的问题。

我打个比方：skill是"岗位培训手册"，MCP是"工具箱"。培训手册告诉你怎么用扳手、怎么用螺丝刀（知识），工具箱给你提供了扳手和螺丝刀（工具）。AI要先知道该用什么，再能实际拿起来用，两者是互补的关系。

实际操作中，两者也确实配合使用：你写一个"数据库巡检skill"，里面会写清楚巡检的步骤、关注哪些指标；而真正连接数据库执行SQL查询的，是MCP服务提供的工具。AI通过skill知道"要查什么"，通过MCP知道"怎么连上去查"。

3.3 官方skill与自定义skill

opencode的官方仓库里提供了一些SKILL示例，社区里也有大量开发者分享自己的skill包。我整理几个典型的场景：

有意思的是，热词里还有"倪海厦skill""仓颉skill"这种看起来很垂直的skill。"倪海厦skill"我扫了一眼，大概率是封装了倪海厦的中医知识库，让AI能基于他的理论进行健康咨询；"仓颉skill"应该是华为仓颉编程语言相关的辅助技能包。这说明skill的应用范围已经不止于编程，知识付费、专业问答、垂直领域服务都在往这边靠。

不过我要泼一盆冷水：别为了用skill而用skill。我见过有人装了几十个skill，结果AI每次收到任务都在几十个手册里翻找，上下文爆掉，反而变笨了。skill贵精不贵多，你的核心场景，配三五个高质量的skill就足够。

3.4 skill vs 插件，别再傻傻分不清

热词里也出现了"skill插件"这种混搭说法。严格来说，在opencode生态里，skill和插件是两个不同的扩展机制：

• skill：面向"AI能力"的扩展，改变的是AI处理任务的方式和知识水平。
• 插件（plugin）：面向"工具链"的扩展，给opencode增加新的命令、新的界面元素或者第三方服务集成。

说得直白一点，插件是给opencode这个软件"加功能"，比如加一个"打开浏览器预览"按钮；skill是给AI"加知识"，比如教它"处理合同的时候要先看违约条款"。两者维度不同，但可以叠加使用。

4. 实操手册：从零装好opencode并配置模型

4.1 环境准备与依赖安装

在装opencode之前，先确认你的机器上有这几样东西：

• Node.js：opencode的官方CLI工具主要通过npm分发，要求Node.js 18以上，推荐20 LTS。命令行输入node -v看版本，如果没装，去官网下载LTS版本，装完记得重启终端。

• Git：拉取skill仓库和项目代码要用，git --version验证。

• 终端环境：Windows用户强烈建议用WSL2，或者至少是PowerShell 7+。老版Windows PowerShell 5.1兼容性很差，很多命令和字体显示都是坑，我刚开始就在这上面浪费了半天。

我把我的安装流程直接贴出来，照着抄就行：

# 1. 安装opencode（全局安装） npm install -g opencode-ai # 2. 检查是否安装成功 opencode --version # 3. 如果是Windows且提示“无法识别”，按4.2节处理

注意：这里安装的是opencode-ai包，不是opencode包。有些教程写的是npm install -g opencode，那个包是完全不同的东西，装错了后面会出各种诡异问题。我在网上看到很多人就是这一步错了，然后纠结半天为什么命令识别不了。

安装完成后，初次运行opencode会引导你配置API Key，这一步先不急，我们先去准备模型配置。

4.2 彻底解决“opencode无法识别”的问题

热词里有一句特别扎眼："opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。"这是Windows用户最常见的报错，原因只有一个：npm全局安装目录没有加入系统PATH环境变量。

解决步骤如下：

1. 在PowerShell里运行npm config get prefix，拿到全局安装路径。通常长这样：C:\Users\你的用户名\AppData\Roaming\npm。
2. 打开"系统属性" → "环境变量"，在"用户变量"里找到Path这一项，双击编辑，点击"新建"，把上面的路径粘贴进去。
3. 点击确定保存，然后彻底关闭并重新打开PowerShell，不是开新标签，是完全退出重开。
4. 再运行opencode --version验证。

如果你用的是WSL2 Ubuntu，安装方式略有不同：

curl -fsSL https://opencode.ai/install | bash

或者用npm也一样：

npm install -g opencode-ai

Linux下如果遇到权限不足，用sudo npm install -g opencode-ai，或者按npm官网建议用nvm管理Node再装，那样不用sudo更好。

macOS用户和Linux基本一样，只是可能要用brew install node先装Node。如果遇到"权限不够"的报错，检查一下是不是用了公司的受限账号，或者macOS的SIP对终端工具的签名限制。

4.3 模型接入：免费模型与CCSwitch配置

opencode最大的优势是模型自由，它支持所有兼容OpenAI协议的服务。实际项目里，我主力用的三个模型：

• 日常开发：Claude Sonnet 4，写代码质量高，上下文理解强。
• 轻量任务：GPT-4o mini / DeepSeek-V3，速度快，成本低。
• 本地隐私场景：Ollama跑的Qwen2.5 32B，完全离线，数据不出机器。

配置方式很简单，opencode启动时会读取环境变量里的API Key，比如：

export ANTHROPIC_API_KEY=你的key export OPENAI_API_KEY=你的key

或者用opencode自带的模型管理功能，在交互界面里输入/models就能切换。

热词里的"ccswitch配置opencode"指的是一类模型切换工具（比如CCSwitch、AI Gateway），它们的核心作用是在不同的模型服务之间做流量的动态路由。简单说，你可以在一个配置文件里定义多个供应商的Key和模型，然后通过工具自动选择调用哪个。这样做的价值是：不怕某个供应商挂了，也不怕单个Key额度用完。

我个人建议的开发机配置是：OpenAI兼容协议选DeepSeek或Qwen的API做默认，因为价格便宜且质量够用；要处理超复杂任务时手动切到Claude。不用刻意追最新最强的模型，重点是让AI帮你把流程跑通。

4.4 集成到VS Code和IDEA，以及桌面版

热词里有人搜"opencode vscode"、"opencode idea插件"、还有"opencode桌面版"，说明大家其实更习惯在IDE里干活。opencode官方提供了VS Code扩展，IDEA也有社区插件，它们的基本功能类似：在IDE内嵌一个终端面板，让你不用切窗口就能和opencode交互。

但我要说实话：目前IDE插件的体验，还没有达到终端原生的水平。主要问题是渲染层和交互层不一样，IDE里的代码块显示、命令高亮、文件diff查看，都还在持续迭代中。如果你只是想"在IDE里用opencode"，最简单的方案就是在IDE内置终端里直接运行opencode，效果一模一样。

"opencode桌面版"则是指社区开发者打包的图形界面应用，本质上是给opencode包了一个Electron壳，把终端交互转成了图形对话框。适合完全不想碰命令行的朋友，但它目前还比较早期，功能不全，我不做主力推荐。

4.5 离线安装与部署场景

热词里有一条"opencode离线安装windows"，这个需求一般来自两类场景：一是内网开发环境，没法直接访问npm registry；二是公司有严格的安全审计，所有软件必须走离线包审批。

离线安装的正确姿势是：

1. 在一台能上外网的机器上，先执行npm pack opencode-ai，这会打出一个tgz包。
2. 把tgz包拷贝到内网机器上，执行npm install -g ./opencode-ai-xxx.tgz。
3. 如果opencode依赖的原生二进制（比如某些平台相关的模块）也需要离线，可以用npm ci配合全局依赖缓存，或者用node_modules整体拷贝的方式。

这一步很多人会卡在"依赖装不上"，我的建议是提前把npm缓存也打包带走：npm cache clean --force后，npm install的缓存目录通常在你的用户目录下，把整个.npm目录打包，内网机器上解压到相同位置，再离线安装，成功率会高很多。

至于部署层面，opencode可以跑在服务器上做批量任务，比如定时代码审查、自动生成项目文档。你只需要用ssh连上服务器，装好opencode，配好模型Key，然后用cron或systemd定时任务触发命令即可。

5. skill的实战：创建、安装与使用完整流程

5.1 加载官方skill仓库

opencode默认会加载当前工作目录下.opencode/skills文件夹里的所有skill，也会读全局路径下的skill目录。具体加载规则可以在启动日志里看到。我第一次运行的时候，默认就带了一个官方的code-review skill，那种"即插即用"的感觉确实爽。

如果你想加载社区里的skill，最简单的办法是把仓库clone到本地，然后告诉opencode从哪个目录加载：

git clone https://github.com/someone/awesome-skills.git opencode --skill-dir ./awesome-skills

加载之后，你在交互界面里输入/skills，就能看到当前会话可用的所有skill列表。

这里我做一个很重要的提醒：skill的加载是"注入上下文"，不是"按需读取"。也就是说，只要skill被加载了，它们的内容就会占用你模型上下文的一部分。如果你在同一个目录下放了100个skill，每次对话可能要先"读完"这100份手册才能干活，token成本急剧上升。所以，保持skill目录干净，只放当前项目真正用得上的。

5.2 编写一个自定义skill：从零开始30分钟搞定

我以一个实战案例来演示怎么写skill。假设我要做一个前端代码审查skill，用于帮团队在提交PR前统一检查代码规范。

第一步，创建目录结构：

mkdir frontend-review cd frontend-review touch SKILL.md mkdir reference

第二步，编写SKILL.md，这是核心文件：

--- name: frontend-review description: 审查前端代码，检查React组件规范、TypeScript类型安全、CSS样式规范。 when_to_use: 当用户要求审查React或TypeScript代码时使用。 --- # 前端代码审查指南 ## 审查目标 - 代码是否符合团队React编码规范 - TypeScript类型是否严格，有无any滥用 - 样式命名是否符合BEM约定 - 有无明显的性能问题（如不必要的re-render） ## 审查步骤 1. 先扫描项目结构，确认React版本、TypeScript配置、CSS方案 2. 逐文件阅读核心组件代码 3. 按下方检查清单逐项打分 4. 输出审查报告，标注严重程度和建议 ## 检查清单 - [ ] 组件是否用function组件，避免不必要的class组件 - [ ] Props是否定义interface，且使用`type`或`interface`关键字 - [ ] 是否存在`any`类型，有则标注需改进 - [ ] useState初始值是否正确 - [ ] useEffect依赖数组是否完整 - [ ] 事件处理函数是否用useCallback包裹（必要时） ## 报告输出格式 ### 文件路径 - 严重程度(高/中/低): 问题描述

第三步，把这个文件夹放到项目的.opencode/skills/frontend-review目录下，重启opencode会话。

第四步，测试。在opencode里输入：

用frontend-review skill审查一下src/components/Button.tsx

AI就会按照SKILL.md里写的步骤走，从扫描项目结构开始，到逐项检查，最后输出一份标准化的审查报告。

第一次写SKILL.md的时候，很容易犯一个错误：把它当成普通的Markdown文档，描述太宽泛。我的经验是，skill要写得像流程SOP（标准作业程序）那样具体。你写出来的内容，AI是要"照着执行"的，不是"参考一下"就完事。所以每个步骤要有明确动作，每个检查项要有可判断的标准。

5.3 用drawio skill生成图表、用写作skill控制文风

社区里比较好用的skill，我还推荐两个实际场景举例：

• drawio skill：先画系统架构图、流程图的时候，让AI直接生成.drawio.xml文件，然后在draw.io里打开就是完整图表。我最常用的场景是接口文档升级——让AI根据代码自动画出一张模块依赖图，以前我要花半小时画，现在一分钟搞定。

• 写作/文风skill：类似热词里的"taste skill"，核心是控制AI的输出风格。比如你要求AI输出的文档必须是"技术方案风格"，你就可以写一个SKILL.md，里面注明：文章结构必须是背景→目标→方案→影响→风险；段落必须短，每段不超过5行；必须用表格做对比；禁止使用"总之"作为开头。这样AI输出的内容才能稳定复用。

这两个例子有个共同点：skill把"不稳定的AI随机行为"变成了"稳定的流程化输出"。这也是我为什么反复强调，skill是opencode最有价值的能力，而不是模型本身。

5.4 多场景skill推荐：数学建模、报告生成、学习辅助

前面表格里列了几个热门skill，我再具体补充几个实操细节：

数学建模skill，适合参加数模竞赛的学生。一般的用法是：准备一个SKILL.md，里面内置各种模型算法的适用场景和代码模板，比如"预测类问题→用回归/时间序列/神经网络，优先简单到复杂""优化类问题→用线性规划/整数规划/启发式算法"，再附带每类算法的Python实现模板。这样AI拿到建模题，能快速从模板里套用合适的算法，先把思路跑通。

报告生成skill，适合做数据分析的同学。SKILL.md里规定报告必须包含：数据来源说明、统计方法、结论摘要、可视化图表建议。AI会自动用pandas读数据、生成图表、输出一份半成品报告，你只需要补细节。

语言学习skill，针对有学外语需求的人。SKILL.md里规定：每次对话先用目标语言回答，然后在括号里给出中文翻译，再补充一个同义替换和语法讲解。AI从一个"聊天机器人"变成了"语言陪练"，效果完全不一样。

这些例子说明一个道理：skill的粒度其实由你自己决定。它可以大到"整个项目的架构规范"，也可以小到"每次回答都要先复述问题"。重点是它把"隐性知识"变成了"显性流程"，让AI真的能按你的标准做事。

6. 进阶技巧：skill和MCP协同、上下文管理、项目实战

6.1 用skill控制AI行为与角色，减少"话痨"和离题

很多人的opencode用起来不顺手，一个核心原因是：AI太爱自由发挥了。问一个简单问题，它洋洋洒洒写几百字，或者答非所问。这个问题，用skill能有效纠正。

我在一个项目里专门写了一个"short-answer skill"，SKILL.md里规定：只回答问题的直接答案，能用一句话就不用两句话；如果问题不明确，先反问澄清；禁止在答案里加入"作为AI"之类的废话。加载这个skill之后，AI的回复简洁多了。

类似的，你还可以控制它的"角色"，提高专业性。比如写代码的时候加载"senior-architect skill"，里面规定："在给出代码之前，先说明你选择该架构方案的理由；如果有更好的方案，列出对比；代码必须包含错误处理，不能只有happy path。"这样AI输出的代码质量，明显比裸用模型高一个档次。

6.2 上下文管理：token足够用，但别浪费

opencode上下文管理的基本规则是这样的：AI能记住当前会话里的所有内容，但模型有一个上下文窗口上限。很长对话或读了很多大文件之后，容易"忘记"前面的内容。

实操中有几个技巧：

• 用/compact命令压缩会话，让AI把关键信息总结成更短的摘要，然后再继续。但压缩会丢失细节，所以重要信息建议直接写在项目文档里。
• 尽量避免把大文件全局读进来，改成用skill里的检查项逐步查找、按需读取。这比一次性把1000行代码全塞进上下文高效得多。
• 明确"任务边界"。opencode支持多会话并行，不同模块的任务用不同的会话来做，避免上下文互相干扰。我在重构项目时，会按"数据库层""业务逻辑层""接口层"分别开会话，效率更高。

6.3 skill与MCP协同的一个完整案例

我用一个实际案例来说明两者配合：自动日报生成任务。

需求描述：每天下午6点，自动从Git提交记录里拉取当天的代码变更，生成一份日报，发到企业微信群里。

拆解一下这个任务的两部分：

• MCP部分：需要连接Git仓库、企业微信群机器人。这里可以用MCP插件注册需要的外部工具，比如git_commit_log、wecom_send_message。
• skill部分：需要一份"日报生成skill"，SKILL.md里写清楚日报的格式：标题、今日完成、遇到的问题、明日计划、需要协调项。另外规定：统计提交记录时，只看master分支，忽略merge commit；遇到提交信息不规范的情况，要用代码上下文猜测意图。

执行流程就变成：opencode通过MCP工具读git提交记录，把原始提交摘要交给AI，AI按照日报skill的格式整理成结构化报告，再通过MCP工具发到群机器人。整个过程自动完成。

这个案例最大的价值是：skill决定了"产出长什么样"，MCP决定了"能触达哪些系统"。两者配合，AI不光是能聊天能改代码，而是真正嵌入了你的业务流。

6.4 用opencode做项目级重构的实战记录

最后分享一个我最近做的实战项目，用的是opencode+两个skill完成了一个小型Spring Boot项目的接口重构。

项目背景：一个老的Spring Boot 2项目，大约30个Controller，接口命名混乱，返回结构不统一，没有统一异常处理。我的目标是：给所有接口加上统一返回体、统一异常处理、规范命名。

操作步骤：

1. 我先创建了两个skill：spring-refactor skill和api-standard skill。

   前者规定重构的步骤顺序：先扫描项目结构、再逐个Controller识别接口、分析返回类型、标记不规范的写法；后者规定新的接口标准和示例代码。

2. 启动opencode，加载项目目录，输入指令："使用spring-refactor skill，先扫描所有Controller，列出需要改造的接口清单。"

   它几分钟后返回了一份清单，分好了优先级。

3. 我继续输入："按api-standard标准，先改造UserController，改完跑一下Maven编译，成功后继续下一个。"

   它每次改造完，都会自动运行mvn compile验证，编译失败会自己检查日志修复，实在不行会回滚改动并报告我要人工处理。

4. 全部改造完成后，我让它输出一份改造报告，列出修改的文件、改动原因、影响范围，我基于报告做了code review。

整个过程花了大约3小时，比我一个人手动改节省了一倍以上的时间。最关键的是，AI遵循我定制的skill标准，改出来的代码风格统一，不是乱七八糟的"人工智能风"。这背后其实是"强大的模型能力+专业标准流程"的叠加效果。

7. 常见问题与排查技巧实录

7.1 安装与启动类问题速查表

7.2 模型调用与上下文类问题

• 总是调用同一个模型，切不过来：这通常是因为配置里只有一个模型被标记为默认。检查opencode config里的模型列表，确认你想用的模型是否已加进去，然后在交互界面用/models手动切换。
• 上下文一长就严重降智：这是所有AI代理类工具的共性问题。原因是"大海捞针"效应——模型在长上下文里容易忽略关键信息。我实测有效的做法是：给重要任务开新会话，把上一步的产出和下一步目标写清楚；必要的时候用/compact压缩历史。
• opencode读了某个文件，但你不太想让它读的项目路径被它扫到了：在项目的.gitignore或opencode的配置里加排除规则。比如在项目中创建.opencode/ignore文件，写入不需要AI扫描的目录路径，AI执行任务时就会跳过这些目录。

7.3 skill相关的典型问题与排查

7.4 热词里提到的其他高频问题快答

"opencode是哪个公司的"：opencode是一个开源项目，在GitHub上开源，社区驱动，背后没有像Google或Microsoft那样的大公司。它更像是一个开源的社区项目，团队由核心维护者和贡献者组成，用的许可证是MIT，所以你可以自由使用和二次开发。这一点对想深度定制的人来说反而是加分项。

"opencode go订阅"：这里的"go"我理解有两层含义，一是"开始使用opencode"，二是部分人用它指代一门语言或某个订阅服务。但无论如何，opencode本身没有任何付费订阅，所有源代码和核心能力都是开源的，你只需要为底层调用的模型API付费，或者用免费模型如DeepSeek、Qwen的免费额度、本地Ollama模型跑，成本可以控制到几乎为零。

"skill脚本"是怎么写的：skill的核心文件SKILL.md本身不是脚本，它是一份Markdown文档。但skill可以包含scripts/目录，里面放真实的Python、Shell、Node脚本。比如一个"自动化部署skill"，SKILL.md规定了部署流程的文字说明，scripts目录里放着真正的deploy.sh或build.py脚本，AI在按流程走的时候会调用这些脚本来执行。

"skill编码196是什么"：这个有点偏，我不确定它具体指哪个体系里的编码，可能是某个电商平台或内部的商品编码。但既然搜这个热词大概率是想了解"skill编码"的规则，我的建议是：所有自定义skill最好给每个检查项和步骤加稳定编号（比如REQ-001、CHK-002），这样AI生成的报告能精准引用规则编号，团队协作时沟通成本大幅下降。

8. 我在实操中的一些体会与建议

最后聊几句个人感受，不太像教程，更像是我这几个月折腾opencode和skill下来的心得。

先想清楚要解决什么问题，再决定装不装skill。很多新手一上来就装几十个skill，结果每个都只会一点点，反而干扰AI的判断。我自己的做法是：先裸用opencode跑一段时间，发现某个任务反复要花大量时间描述背景和要求，才把它沉淀成一个skill。比如我做了十几个项目的代码审查之后，才总结了那套前端审查skill，它一出来就特别能用。

配置能写到文件里就别写在命令行里。我之前老想着临时设环境变量，结果换个终端就忘了设，好几次卡在"API key not found"。现在我把所有Key、模型偏好、目录配置都写进opencode.json项目配置文件里，随项目走，走到哪配到哪。

skill文件要版本管理。我建议把自定义skill放在单独的Git仓库里，因为skill里的知识和标准会随着项目迭代更新。每次更新后commit，记录变更原因，这样大家都清楚"为什么标准变了"。

别迷信"最强模型"。在一个流程化任务里，用DeepSeek或Qwen这类性价比模型反而稳定，因为任务的核心质量是由skill定义的，不是模型临场发挥。只有在任务很开放、需要大量创意和分析时，才值得切到Claude或GPT旗舰。

从我的体验看，opencode+skill这套组合，把"AI编程"从"聊天工具"往前推进了一大步。它更像是在训练一个懂你团队规则的"数字员工"，而不是一个什么都会一点但什么都不精的"万能助理"。如果你也想尝试，别贪多，先装好环境、跑通一个最简单的skill，让AI帮你完成第一件小事，后面你自然就能感受到它的价值。