企业官网建设流程全解析

1. 终端里的结对程序员：OpenCode 的定位与它真正解决的事

1.1 先搞清楚它和 IDE 插件、网页版编辑器的区别

很多人第一次接触 AI 编程工具，都是从网页版编辑器或者 IDE 插件开始的：左边一个对话框，右边一个代码区，把需求敲进去，等它把代码改出来。OpenCode 走的是另一条路——它把整个交互搬回了终端，界面长得很像 Vim 或 Lazygit 那种 TUI（文本用户界面），你依然是在“命令行”里工作，但这个命令行里的智能体能自己读仓库、执行命令、改文件、跑测试。

从产品形态上说，OpenCode 和 Claude Code、OpenAI Codex 是同一类东西，业内叫 AI 编码智能体（Agent），不是简单的“代码补全工具”。它和你写提示词让 ChatGPT 给一段代码最大的区别是：它能拿到你项目的完整上下文，能运行 shell 命令，能真实地落盘修改文件，能把一次修改跑通验证后再交付给你。

那为什么不干脆用 IDE 插件？几个原因。第一是速度，终端启动快、占用小，服务器上也能用，SSH 到一台开发机就能干活；第二是可控性，所有改动、命令、日志都留在终端会话里，可回放、可存档；第三是自由度，它不绑定任何一家模型厂商，你自己有 API key 或者本地模型，接上就能用。从我的实际体验来说，OpenCode 适合那种“已经在命令行里工作了一整天”的开发者，你不需要从一个图形界面切换到另一个图形界面。

1.2 什么项目适合用 OpenCode 把活干完

它不是万能药，我试过在几种典型场景下用得很顺手，也有场景确实不合适。

先说合适的方向：接手一个陌生仓库时，让它先梳理架构比人肉看代码快得多；做跨文件重构时，它能在多个文件里同步修改；前端 bug 排查时，它能自己启动浏览器复现问题；写测试这种体力活，它能稳定地产出可运行的用例。对于 Go、TypeScript、Python 这类生态成熟的语言，配合 LSP 能力，它的表现会超出预期。

不太合适的场景也有：完全不懂命令行的新手，我还是会劝你先从 IDE 插件上手；公司有严格的数据合规要求、不允许把代码发到外部模型服务时，你就得接本地模型或者私有化部署的模型服务，这个后面会展开；还有一些特别冷门、文档稀少的框架，模型训练数据里没见过，它和你一样会两眼一抹黑。

1.3 核心能力速览

这张表我后面每一行都会展开讲，尤其是 LSP 和 Playwright 这两个能力，属于“用了就回不去”的类型。

2. 把安装踩坑一次说透：环境准备、报错排查和第一句指令

2.1 基础环境：Node、终端和 Windows 用户的特殊问题

OpenCode 的安装方式一直在迭代，我建议直接看官方 README，因为命令更新频率挺高。我本地最常用的还是官方 curl 脚本：

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

装完之后，opencode会装到用户目录下，通常是在~/.opencode/bin或者~/.local/bin。如果 shell 提示找不到命令，先别急着重装，大概率是 PATH 没加载：

export PATH="$HOME/.local/bin:$PATH"

Windows 用户在 PowerShell 里遇到的报错，应该就是热搜里那条：“opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这个报错的根因基本就三类：

1. Node.js 没有正确安装，或者安装时没勾选“Add to PATH”；
2. npm 全局安装目录不在 PATH 里；
3. 安装完成后终端没重启，新的 PATH 没生效。

排查顺序我建议这样：先运行node -v和npm -v确认 Node 环境，再看npm config get prefix拿到的目录，最后把这个目录加到 PATH 环境变量里。如果之前是旧版本升级上来的，顺手清理一下%APPDATA%\npm里残留的旧文件，有些诡异问题就是新旧版本文件冲突。

另外提醒一句：如果你平时用 Windows Terminal + Git Bash，会比纯 PowerShell 省心一些；要是开发环境跑在 WSL 里，直接在 WSL 内安装使用是最顺滑的，别在 Windows 侧硬较劲。

2.2 首次启动和第一轮对话的正确姿势

装好之后，进到你的项目根目录，直接运行opencode。首次启动会进入 TUI 界面，它会引导你配置模型服务商。我没有账号相关配置时，是先接的本地模型体验的，后面第三节会讲具体配置方法；如果你手里有 Anthropic 或 OpenAI 的 API key，也可以直接用opencode auth login登录。

第一句指令，我强烈建议不要上来就让它改功能，先让它“认路”。我会这么说：

先不要修改任何代码。请阅读 README 和项目主要目录，给我一份模块结构说明，标注出核心模块和它们之间的依赖关系。

这一步的作用是让智能体建立项目地图，同时你也能从它的回答判断它对这个技术栈熟不熟。此时你要观察它列出的文件是否准确，如果它连项目入口都找错了，后面的大改动就别指望了。

热搜里有一条“opencode 如何导入一段程序代码并进行修改完善”，这个我实测最顺手的做法不是复制粘贴大段代码到对话框——那样容易丢缩进、也容易让它丢失对项目环境的感知。正确姿势是：把代码片段保存到项目里的一个临时文件（比如/tmp/example.ts），然后这样下指令：

请阅读 @/tmp/example.ts，这段代码目前的问题是 X，我需要你把它改造成 Y。改完先不要写回原文件，把完整的新版本输出给我。

用@引用文件路径，它就能精确地读取内容，同时不会污染项目目录。等确认方案没问题，再让它直接修改目标文件。

2.3 项目级配置文件的骨架

OpenCode 的项目级配置文件是opencode.json（部分版本也支持opencode.toml，以你安装版本的文档为准）。我的最小可用配置长这样：

{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4", "provider": { "ollama": { "npm": "@ai-sdk/ollama", "name": "Ollama (Local)", "options": { "baseURL": "http://localhost:11434/api" }, "models": { "qwen2.5-coder:7b": { "name": "Qwen 2.5 Coder 7B" } } } } }

这里model字段写默认模型，provider下面可以注册你自己的模型服务商。一个很重要的经验：永远不要在配置文件里明文写 API key，而是用env:YOUR_KEY_NAME这种形式去读环境变量。我见过不止一次有人把 key 直接提交到 Git 仓库里，然后被自动化扫描工具抓出来告警，这个坑能躲就躲。

3. 模型接入和 token 花费怎么平衡：Provider 配置与本地模型实测

3.1 从 API Key 到 Provider：连接不同模型服务商

OpenCode 的模型接入思路是“Provider 抽象层”，它底层基于 AI SDK，你可以把任意一个兼容 OpenAI 接口的服务商配置进来。常见的大模型服务商，官方基本都内置好了，只要设置好对应的环境变量就能用：

export ANTHROPIC_API_KEY="sk-ant-..." export OPENAI_API_KEY="sk-..." export GOOGLE_API_KEY="AI..."

如果你的模型服务商不在内置列表里，就手动在opencode.json里配置一个自定义 Provider，比如用 OpenAI 兼容格式：

{ "provider": { "mycompany": { "npm": "@ai-sdk/openai-compatible", "name": "My Company Models", "options": { "baseURL": "https://api.example.com/v1", "apiKey": "env:MY_COMPANY_API_KEY" }, "models": { "my-fast-model": { "name": "Fast Model" } } } } }

配置好之后，在 TUI 里按快捷键或者输入模型切换命令，就能在多个模型之间切换。我的习惯是：做架构分析、大范围重构时用最强模型，批量做一些简单机械的修改时切到便宜快速的模型，这样整体费用能下降一大截。

3.2 本地模型是被低估的一条路

热搜里有“opencode免费模型”，大部分人的第一反应是找网上的免费接口，但我更推荐你试试本地模型。原因很简单：数据不出机器、没有按量计费、请求无限。用 Ollama 跑一个 Qwen 系列的 Coder 模型，配置就和 2.3 节那个示例一样，在 Provider 里加一个 Ollama 入口就行。

实测下来，7B 到 14B 量级的本地模型能做这些事：解释代码逻辑、写单元测试、做 diff review、按照明确的规范修改样式。但你要是让它做跨十几个文件的复杂重构，它大概率会丢上下文，甚至会自信地给出错误的 API 调用。所以本地模型更适合当“廉价劳动力”，不适合当“架构师”。

硬件条件上，MacBook Pro 的 M 系列芯片跑 7B 模型基本流畅，16G 内存是底线；如果只有 CPU 没有 GPU，速度会慢到我没什么耐心。另外，启动 Ollama 后要记得先把模型拉下来：

ollama pull qwen2.5-coder:7b

然后再启动 OpenCode，让它连接http://localhost:11434/api。

3.3 省 token 的几个实操细节

用云端模型最怕的就是 token 哗哗流走，我总结了四个亲测有效的控制手段。

第一，善用 ignore 规则。OpenCode 默认会忽略node_modules、.git、dist这类目录，但如果你的项目里有体积巨大的生成文件、日志文件、二进制资源，一定要把它们加进忽略列表，否则它扫描文件时会浪费大量上下文。

第二，用@精确指定上下文范围。不要让它“看一下整个项目”然后自己去翻，你自己心里清楚问题出在哪个目录，就明确告诉它。比如@src/utils/format.ts，它读取的文件越少，留给推理的上下文就越多，答案质量越高。

第三，阶段性压缩会话。聊了二三十轮之后，历史记录会占用大量上下文，此时用/compact命令把之前的对话压缩成摘要，能立刻释放空间。这个操作看起来简单，但对长任务的连续性帮助很大。

第四，大文件不要反复读。如果你已经让它把某个文件读到上下文里了，后续提醒它“刚才那个文件里有个函数叫 X”，它会直接从已有上下文里找，而不是重新读一遍。养成这个习惯之后，token 消耗能明显下降。

4. “看懂”仓库这件事：LSP 接入、AGENTS.md 与接手旧项目

4.1 接手旧项目前，先让它写一份“项目地图”

如果你被丢到一个陌生的仓库，别急着让智能体改需求，先花二十分钟让它生成项目地图。我会用 headless 模式跑一条指令：

opencode run "阅读项目入口文件和关键配置，输出一份 ARCHITECTURE.md，内容包括模块划分、启动方式、核心数据流、现有测试策略。不要修改任何源码。"

它会自己扫描目录、读配置、梳理模块关系，然后生成一份文档。我拿这份文档当基础，再补上我看到但智能体没捕捉到的业务背景，最后把修正版提交进仓库。这个文件对新加入项目的人非常有价值，相当于把“项目里最资深的开发者的脑内地图”落在了纸面上。

还有一个我觉得比 README 更重要的文件：AGENTS.md。这是给 AI 看的项目说明书，写在仓库根目录，里面约定“这个项目的命令习惯是什么”“哪些目录绝对不能动”“测试怎么跑”。有了它，以后每次启动 OpenCode，智能体都会先读到这份约定，行为会规矩很多。如果当前版本支持/init命令，可以直接让它基于仓库现状生成一个初始版，你再手动补充团队规范。

4.2 接入 LSP 之后，AI 像长了眼睛

LSP（Language Server Protocol）本来是为了给编辑器提供“跳转定义、查找引用、诊断错误”等能力，OpenCode 把它接给了智能体。这意味着 AI 不再靠“字符串匹配”理解代码，而是能真正拿到编译层面的符号信息。

举个例子，我让它把某个工具函数从一个文件移到另一个文件，同时更新所有调用方。没有 LSP 的时候，它偶尔会漏掉某个动态导入的调用路径，我得自己再查一遍；接入 LSP 后，它移动完文件会主动查“引用”，然后发现遗漏的 import 并修正。对它来说，这就像多了一双能看到“代码真实依赖关系”的眼睛，而不是靠猜。

如果你的某个语言 LSP 没生效，先别赖 OpenCode，大概率是本地缺少对应的 language server。Go 项目需要gopls，Python 项目需要pyright，TypeScript 项目需要typescript-language-server，先用各语言的包管理器装好。比如 Go：

go install golang.org/x/tools/gopls@latest

然后再重新启动 OpenCode，它通常能自动探测到新装的 LSP。

4.3 高频命令和会话工作流

我日常在 TUI 里用到的命令不算多，但都很关键。/help查看当前版本支持的所有命令，/compact压缩上下文，/new开启新会话但保留当前项目上下文。接手旧项目时，我习惯为每个大任务开独立会话：读代码一个会话，改代码一个会话，跑测试验证再一个会话。这样每个会话的上下文都很干净，不会互相干扰。

headless 模式更是脚本党的福音：

opencode run "review 当前 git diff，指出潜在 bug 和风格问题"

这条命令可以直接接在 CI 流程里，也可以配合git diff | opencode run -做管道输入。比如每次提交代码前，我先在终端跑一遍这个 diff review，它能用很低的成本帮我挡掉不少低级错误。注意 headless 模式默认没有 TUI 那种交互确认，所以它执行命令时会更激进，建议在配置里把危险命令（比如git push、rm -rf）放进禁止列表。

5. Skills：给智能体装上“职业素养”和团队规范

5.1 SKILL.md 的基本结构与加载路径

Skills 是 OpenCode 里我非常喜欢的一个机制，简单说就是给智能体定义“遇到某类任务时按这个流程来”。每个 Skill 是一个目录，里面有一个SKILL.md文件，描述这个技能的触发条件、执行步骤、注意事项，还可以附带脚本和模板。加载路径一般是用户级的~/.config/opencode/skills，或者项目级的.opencode/skills，后者跟着仓库走，天然适合团队共享。

一个最小的SKILL.md长这样：

--- name: code-review description: 当用户要求审查代码时执行此技能 --- - 先运行 `git diff` 获取改动内容 - 关注：安全性、错误处理、可读性、性能 - 对每个问题给出文件和行号 - 最后按严重程度分级输出

关键在于 frontmatter 里的description，OpenCode 会把它作为“何时调用这个技能”的依据。所以描述要写清楚适用场景，不要用“处理代码”这种废话，要写“当用户要求审查代码、做 code review、检查 pull request 时”。

5.2 一个前端设计开发一体 Skill 的完整模板

热搜里有一条“opencode 前端设计开发一体的skill”，我正好沉淀了一个团队内部在用的版本。它的目的是让智能体在开发前端组件时遵循同一套设计规范和验证流程，避免每次交出来的 UI 风格五花八门。

我建议的SKILL.md结构如下，你可以直接抄去改：

--- name: frontend-component-dev description: 开发或修改前端组件时使用。要求遵循设计令牌、响应式规范，并用 Playwright 截图验证。 --- ## 设计规范 - 颜色使用项目设计令牌（见 styles/tokens.css） - 组件需适配 375px、768px、1280px 三档宽度 - 所有交互元素必须支持键盘操作 ## 执行流程 1. 阅读组件相关源码和现有样式 2. 按设计规范实现组件 3. 启动开发服务器 4. 用 Playwright 打开组件所在页面，分别在三档宽度截图 5. 检查截图是否符合规范，不符合则继续修改直到通过 6. 输出改动摘要和截图路径

这个 Skill 的精髓不是给 AI 讲大道理，而是把检查项变成可执行的动作——截图、分档位验证、对比规范。有了这套流程，AI 每次开发完组件都会真的启动浏览器看效果，而不是“我觉得应该没问题”。

5.3 从 oh-my-claudecode 等项目借技能

社区里有很多现成的 Skills 可以借鉴，比如 oh-my-claudecode 这类项目，原本是为 Claude Code 做命令管理和技能集成的。我的建议是：可以大胆借鉴里面的SKILL.md写法和流程设计，但不要直接整个搬进 OpenCode，因为两个项目的插件机制、配置加载路径、工具权限模型不一样，直接套用大概率会出一些莫名其妙的问题。

我看到 OpenCode 用户经常在社区里讨论怎么把 Claude Code 生态里的 skills 迁移过来。实际做法通常是：把 SKILL.md 拷贝到.opencode/skills目录，然后删掉所有依赖 Claude Code 特定命令的步骤，改成通用的 shell 命令。迁移完一定要实测一遍，看智能体能不能在 OpenCode 里顺利走完整个流程，不要迷信“能加载就是能用”。

6. Playwright 实测：让 AI 自己把前端 Bug 修完

6.1 为什么要用浏览器自动化，而不是只让 AI 读代码

修前端 bug 最大的痛苦在于：代码和人看到的页面之间存在一层“运行时复杂性”。组件 A 报错，原因可能在父组件 B 的某个状态没传对，而这种跨文件的运行时问题，静态读代码很难发现。OpenCode 接入 Playwright 后，智能体可以自己打开浏览器、点击按钮、收集控制台报错、截图，然后根据真实运行结果去定位代码问题。

这个模式的关键是“反馈闭环”。AI 改完代码后，它不需要等你去验证，而是自己重新打开页面再跑一遍流程，如果问题还在就继续修，直到控制台干净了才交付给你。我在实际项目里用这个方式处理过不少“点击按钮没反应”“弹窗位置不对”“某个功能在移动端样式错乱”的问题，效率比我自己手动复现高很多。

6.2 一次完整排查链路：从描述到修完

下面是一条我常用的 prompt 模板，可以直接套用：

用 Playwright 复现并修复这个前端 bug： 1. 启动开发服务器（npm run dev） 2. 打开 http://localhost:5173/page 3. 点击“提交”按钮 4. 收集控制台报错并截图 5. 根据报错分析原因，修复 @src/components/SubmitButton.tsx 6. 修完后再跑一次同样的流程，确认控制台无报错并再次截图

智能体会按照这个流程拆解动作。我观察到的执行顺序大致是：

这个闭环跑完之后，我一般还会补一句：“把修改的 diff 给我，并说明为什么这样改”。这样既能审计它的改动，也能从中学到一些自己没想到的思路。

6.3 权限、超时和登录态的几个坑

Playwright 集成虽然强大，但不是零成本，我踩过几个坑值得说一下。

第一是浏览器内核下载。首次使用 Playwright 前，大概率需要手动装一次 Chromium：

npx playwright install chromium

不装的话，智能体运行测试脚本时会报找不到浏览器。这个问题在 CI 环境里尤其常见，我通常会在项目的AGENTS.md里写一句“首次运行请先执行 npx playwright install chromium”。

第二是权限确认。OpenCode 在 TUI 模式下执行命令前会征求确认，对危险命令很谨慎。如果你确认某个命令绝对安全，可以在配置里加入白名单，省得每次弹窗打断节奏；但也就意味着智能体以后可以无确认执行这条命令，所以白名单一定要收紧。我的原则是：允许npm run dev、npm test这类只读或本地只写命令，禁止一切可能影响远端状态的操作。

第三是登录态问题。很多页面的 bug 需要登录之后才能复现，而 Playwright 默认的浏览器上下文是干净的。如果你碰到“页面一直跳转登录页”的情况，可以让 Playwright 加载一个已保存的浏览器 profile，或者先手动登录一次并把 cookie 持久化到本地文件，然后在 prompt 里告诉智能体“使用 /tmp/profile 作为用户数据目录启动浏览器”。这属于偏高级的用法，但一旦用上，能排查的问题范围会大很多。

7. 桌面版、VSCode/IDEA 插件和团队落地经验

7.1 桌面版和 IDE 插件的正确使用姿势

关于“opencode桌面版”，我的看法是：如果你已经习惯 TUI，桌面版不是必需品；如果你是团队里被“命令行恐惧”支配的成员，桌面版能降低上手门槛。底层核心还是同一个，只是外壳不同。

VSCode 插件和 JetBrains IDEA 插件的价值，我认为在于两点：更方便地看 diff，以及把 AI 的输出直接嵌入编辑器。终端里改完代码后，我会习惯性地用 IDE 打开差异视图，逐处检查；检查没问题再提交。插件里的“选中代码右键发送给 Agent”功能，在处理局部问题时很顺手，不用为了一个小问题单独跑一遍完整会话。

但我也要泼一盆冷水：插件不是魔法，它只是 OpenCode 的一个前端入口。如果你在终端里用不顺，装了插件大概率也不顺。关键还是先把模型、LSP、Skills 这些基础配置搞对。

7.2 把 AGENTS.md 和 Skills 放进 Git 仓库

团队落地 OpenCode，我最推荐的做法是把项目相关的资产直接提交进仓库：

• AGENTS.md：项目规范、常用命令、禁止操作；
• .opencode/skills/：团队沉淀的各类技能包；
• opencode.json：统一的项目级配置（去掉 API key）。

新成员 clone 项目之后，装好 OpenCode 就能直接用，不需要手动调一堆配置。我们团队内部已经把这个流程跑了小半年，效果很稳定。无论是谁用 OpenCode 改代码，出来的风格都符合项目约定，因为他一进项目就自动读到了这些约束。

在 CI 里的落地方式也一样，跑一个 headless 的 diff review 任务，每天自动检查 PR；输出的 review 结果直接贴在 PR 评论里。不要让它自动合并代码，它只负责发现问题，决策权还是在人手里。

7.3 我踩过的几个真实坑

最后分享几个不写在官方文档里的坑。

第一个是 API key 泄露。我前面提过，再强调一次：所有 key 一律用环境变量引用，配置文件里只写env:XXX。最好给 CI 和本地用不同的 key，方便单独吊销。

第二个是“AI 自信删代码”。有一次它认为某个工具函数没有被引用，就直接删了，结果那个函数是被动态导入的，运行到对应功能时才炸。现在我的opencode.json里会把src/generated、scripts/archive这类目录加进禁止修改列表，并且明确规定“处理引用关系前先做全局搜索确认”。

第三个是长会话的“慢性污染”。一个会话里如果连续换了好几个任务，后面的回答质量会肉眼可见地下降，因为它上下文中积累了太多无关内容。遇到这种情况别硬扛，/compact一次，或者干脆/new开新会话，成本很低，收益却很大。

第四个是免费模型接口不稳定。我理解大家想找免费资源，但如果你跑的是真实项目，我建议优先用本地模型或者正规的模型服务商，哪怕花点钱。把时间浪费在调试不稳定的接口上，远比 token 费用更贵。信息差这个东西，终究是要还的。

用了一年多 OpenCode，我最深的体会是：真正能提升效率的，不是某个特别强的模型，而是你沉淀下来的“项目资产”——AGENTS.md 里写的规范、Skills 里定义的流程、LSP 和 Playwright 搭好的验证闭环。这些东西不随模型升级而失效，才是团队最值得投入的部分。你换一个模型它照样工作，你换一个人它照样能快速上手。把它当成一个可以持续进化的“团队成员”，而不是一个临时凑合的代码生成器，你很快就会感受到它的价值。

如果你刚开始接触 OpenCode，建议从一个小项目开始：先让它读代码、写测试、修一个简单的 bug，跑通一次完整闭环。等你熟悉了它的工作方式和脾气，再逐步放权。工具是死的，但你和它配合的节奏，是可以慢慢养出来的。