企业官网建设流程全解析

上篇把 opencode 装起来、跑起来之后，我收到不少私信，问题几乎都集中在三个词上：工具、服务面、外壳。有人问“它到底怎么自己动手改文件”，有人问“免费额度怎么老报错”，还有人问“这玩意儿能不能当我 VSCode 外挂”。这篇我就顺着这三条线往下拆，最后用两个真实工作流收尾——怎么把 opencode 真正嵌进日常开发，而不是把它当个高级玩具。

1. 工具层：模型要动手，得先备好“手”

1.1 内置工具是一套接口：模型怎么决定“下一步动作”

先说结论：opencode 本质上不是一个聊天框，而是一个能执行代码的 agent。聊天的表象下面，模型每走一步都在决定要不要调用某个工具。对我来说，理解这层机制比记住任何快捷键都重要——因为所有能用 opencode 自动化掉的工作，本质都是“让模型在正确的时机调用正确的工具”。

opencode 默认会注入一批工具给模型，我用到最多的整理成了一张表：

关键点在于：模型不是靠“猜”来选工具的，它看的是工具描述和参数定义。这就像你给函数写 docstring——描述写得越清楚，模型选对的概率越高。我一开始不懂这个，经常抱怨“它怎么老用 grep 不直接 read”，后来发现是我在项目提示词里没告诉它“入口文件在哪”，它只能靠搜。

所以一个很实用的习惯是：在项目根目录放一个简短说明，让模型先读入口文件，再去翻其他代码。这个动作能把工具调用的准确率提升一大截，比我事后纠正它省心得多。

顺带一提，不是工具越多越好。工具列表越长，模型做选择时的“注意力”越分散。我见过有人把十几个 MCP 工具全挂上，结果模型频繁在简单任务上调错工具。我的原则是：能用默认工具解决的，不额外挂；只有默认工具明显做不到时，才考虑接外挂。

1.2 自定义 Skill/Agent：把私房流程写成提示词

第二个高频需求是“怎么让 opencode 记住我的做事方式”。比如我经常让它做“生成 git 提交信息”“审查某个文件的改动”“按团队规范写测试”。每次都现场敲一大段指令很累，更别提不同项目还有不同规范。

我的做法是在 opencode 的 agent 目录里放一个 Markdown 文件。思路很简单：前置元数据描述这个 agent 什么时候该被用，正文写清执行步骤和约束。下面是我一个提交信息 agent 的骨架：

--- description: 生成规范的 git commit message mode: read --- 分析 git diff --staged 的输出，按以下规则输出提交信息： - 第一行是 50 字以内的总结 - 正文按“动机/改动/影响”三段展开 - 不要包含任何 AI 语气词

具体字段名会随版本微调，但这个结构基本是稳定的。本质就是三件事：定义触发场景、写清步骤、把常用命令固化进去。你不需要会写代码，纯粹靠提示词就能搭一个很顺手的技能。

另一个更轻量的做法是直接写进项目级的 AGENTS.md 文件。opencode 在工作时会自动读这个文件，把它当成对当前仓库的“项目须知”。我在里面写过“禁止使用 any”“核心模块改动必须补测试”“命令一律非交互执行”这些规则。效果非常明显，模型在几个小时内就很少再犯同样的低级错误。

1.3 接 MCP：给模型装上看数据库、操作浏览器的“外挂”

如果默认工具不够用，下一个进阶动作就是接 MCP（Model Context Protocol）。MCP 统一了外部工具的接入方式，opencode 原生支持，理论上你可以在配置里挂任何 MCP server：数据库、浏览器、内部 API、设计稿导出工具，都能变成一个可被模型调用的工具。

配置文件里大概长这样：

{ "$schema": "https://opencode.ai/config.json", "mcp": { "readonly-db": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"], "env": { "DATABASE_URI": "postgres://user:pass@localhost:5432/app" } } } }

我实际用得最多的是一个只读数据库 MCP。模型可以直接看表的 schema、跑只读 SQL，不用我再手动导出结构喂给它。写代码的时候它能自己搞清楚字段类型、索引、外键关系，生成的查询明显靠谱很多。

但这里必须强调安全：MCP 工具一旦挂上，等于把对应权限交给了模型。生产库写操作、能改系统的命令、能花钱的云操作，尽量不要挂，或者至少在配置层限制成只读。我的经验是，宁可每次手动执行高权限动作，也不要图省事把炸弹递给模型。

1.4 工具调用最容易翻车的两个瞬间

工具层虽然强大，但我在实际使用里至少有两次被坑到记忆犹新，提出来给你避雷。

第一个坑是并行编辑冲突。opencode 接到一个跨文件的改动任务时，可能会同时开多个 edit 去改不同文件，看起来效率高，但一旦两个编辑命中了同一函数的相邻区域，合并结果就可能出一个逻辑坏的版本。更稳妥的做法是在提示词里明确写“小步、单文件优先，需要跨文件改动时先列计划让我确认”。多花半分钟，省下 debug 一小时。

第二个坑是 bash 命令卡死。模型有时候会执行一个交互式命令，比如裸跑npm init或者某些会等待输入的脚本，然后整个任务就挂在那里不动。我这边的止损方案是，在 AGENTS.md 里统一写上“所有命令必须非交互执行，必要时用echo y |兜底”，同时把默认超时时间设短一点，一旦卡住就快速杀掉重来。

2. 服务面：模型路由、额度限制和烧钱反思

2.1 模型别只挂一个：我的多模型选型表

opencode 的价值之一是它把各家模型聚到了一层统一接口下，你可以按任务类型随时换模型。很多人只挂一个默认模型，我觉得浪费了这层灵活性。

我现在常用的选型逻辑是这样的：

配置上，我会在 opencode 配置里把默认模型设为中端模型，这样日常对话快且省钱；遇到真正“烧脑”的问题，再手动切到高端模型。有人问“opencode 和某个特定模型比哪个好”，我的回答通常很直接：别问哪个好，问你的任务类型。比如 DeepSeek 系列是出了名的性价比高、量大管饱，适合结构清晰、重复度高的编码任务；但涉及复杂工具链、多步骤自主调试时，Claude 系列在 opencode 里的工具调用稳定性确实更好。我现在就是小活走 DeepSeek，重活切 Claude，两者互相补位。

2.2 那个 free tier 报错的真相与应对

不少人在 opencode 里遇到过这个报错：

error from provider (console): opencode's free tier can only be used from within opencode

我第一次看到时也在想：我不就是在 opencode 里用的吗？怎么还拦我？后来才明白，这是 opencode 内置“Console”免费额度的来源校验机制。简单说，这个免费额度只面向在官方客户端里通过官方登录方式使用的用户；如果你的客户端版本、调用方式、或者把它当成通用接口从外部走，服务端就会拒绝。本质是防白嫖机制：免费额度不是给你的 API key 当通用额度用的。

我的建议很简单：薅免费额度时就老老实实在 opencode 客户端里用官方登录；真想稳定、可控地跑任务，就配自己的 API key，按量付费。别花时间想什么绕过办法，既费劲又没必要。免费额度适合体验和轻量试用，正式工作是另一回事。

2.3 套餐额度到底怎么算：一次真实对账

顺着上面的话题，很多人关心套餐额度怎么计算，尤其是“每种模型是不是分开算额度”。我见过不止一个套餐，结论是：大概率按提供方或模型桶分开算，而不是放在同一个池子里共享。也就是说，你在 A 家的额度烧完了，不会自动挪 B 家的来补。

有一次我开着两个 provider 跑一个长任务，结束之后去后台看用量报表，发现 A 家几乎没动，B 家烧掉一大截。原因就是路由配置默认全走了 B 家模型。所以我的习惯是：开通任何订阅或套餐之后，第一件事不是写代码，而是去后台把用量报表搞清楚，看看默认路由到底走了哪个桶、哪些模型计费标准不同。

另外，跑“重活”之前先估一下量级：一个大仓库全量重构可能吃掉几十万 token，拆成几个小任务反而更容易控制成本和排查问题。

2.4 兜底预算的三个习惯

服务面绕不开一个字：钱。我的观点是，AI 编程工具烧钱不可怕，可怕的是烧得莫名其妙。所以我给自己定了三个省钱习惯，你可以直接抄：

第一，默认模型保持“够用就好”。把最便宜但能完成任务的模型设为默认，遇到瓶颈再手动切高级模型，而不是一上来就给所有任务用最贵的。

第二，长任务先让模型出计划，不要直接进入执行。先只读分析、列出改动点，确认后再放它动手。这一步能拦截大量无意义输出。

第三，给危险或大额操作设人工确认点。涉及删除、批量写入、大规模重构时，我在提示词里要求模型先把命令打出来，由我回车确认。这样既保留了 agent 的效率，也不会让它一脚油门到底。

3. 外壳：TUI、Zen 模式和编辑器协同

3.1 TUI 不是噱头：界面操作要像编辑器一样熟练

opencode 的终端界面不是花架子，它面向的是“键盘流”用户：你要能在一个终端里完成看 diff、改文件、跑命令、切会话的全过程，而不是中间跳出去开鼠标。刚开始用的时候，我的姿势很蠢——来回切窗口，让模型改了文件又回 VSCode 里看，折腾了两天我才习惯在 TUI 里确认改动。

现在我最常用的几个交互是：Tab 切会话、在 diff 面板里小范围修改然后接受、用/快速发指令切模式。不同版本快捷键略有差异，我的建议是进去先按?看一眼快捷键列表，花十分钟把常用操作练成肌肉记忆，之后效率会明显不一样。

另外别忘了主题和字体。终端里文字一多，清晰度就很重要。把界面主题调成顺眼的配色，代码区字体用等宽字体，长任务跑起来时扫一眼就能定位到关键输出，这种体验改善是真实的。

3.2 Zen 模式：把干扰信息全部关掉

Zen 模式是我后来才高频使用的功能。它本质上是一个极简界面，把工具调用日志、状态面板、乱七八糟的信息全部收起来，只保留对话主流程。听上去只是“界面变干净了”，但实际体验差别很大。

什么时候用？我主要在两种场景切 Zen：一种是快速问答，比如问个 API 用法、让模型解释一段报错；另一种是我已经看过 diff，只想盯着模型输出做最后微调。普通模式适合干活，Zen 模式适合专注阅读和决策。来回切换不需要重启会话，熟练之后也就是一个快捷键的事。

3.3 和 VSCode 共存的三种姿势

“VSCode 怎么和 opencode 一起工作”这个问题我被问过很多次。我的答案取决于你到底想让它扮演什么角色。

最简单的姿势：在 VSCode 的集成终端里直接跑 opencode，并在同一个工作区目录下干活。模型生成的文件改动会实时刷新到编辑器，你既能用 VSCode 的补全和跳转，又能让 agent 做跨文件的批量修改。这是我最常用的方式，零额外配置，稳定到几乎不需要维护。

更“深度绑定”的姿势是装官方或社区的 VSCode 扩展，在编辑器面板里直接开对话、复用会话上下文。优点是视觉上更统一，缺点也很实际：扩展版本的更新往往落后于 CLI，我遇到过几次配置不兼容，后来就回到集成终端方案了。

还有一种“副驾”姿势：不主动让模型碰文件，而是把它当成顾问，让它帮你查问题、写测试、生成提交信息，你则在 VSCode 里负责最终修改和提交。这个姿势适合还不放心让 agent 改代码的阶段，也适合多人协作时保持代码改动可审查。

不管哪种姿势，共同点是工作区目录必须一致。别在 VSCode 打开 A 目录，又让 opencode 在 B 目录跑任务，模型改的文件你在编辑器里根本看不到，等于自找麻烦。

3.4 无头模式：把 opencode 塞进脚本和 CI

除了 TUI 交互，opencode 也支持非交互模式。我最常用的是opencode run，它可以直接执行一段任务命令并输出结果，非常适合脚本化调用：

opencode run "分析这个仓库的模块划分，输出到 docs/architecture.md" --model claude-sonnet

这背后的价值是：opencode 不只是终端里的对话工具，它可以变成流水线上的一环。比如我用它批量生成提交信息、按项目模板生成文件、甚至在 CI 里跑一次初步代码审查。你可以把它理解为一个“每次都会自己看代码、自己动手写东西的实习生”，只要给清楚任务和边界就行。

还有一个opencode serve模式，可以把它作为本地服务暴露给其他应用调用。用的时候务必注意鉴权：别把服务端口直接暴露到公网，最好绑定回环地址，并加上请求令牌。我见过有人为了方便不加鉴权，结果某天本地局域网里其他机器也能调，差点出事，这个坑必须说在前面。

4. 实战集成：两个真实工作流与配套工具链

4.1 接盘新仓库：让 opencode 当我的“入职导师”

我最近接手一个三年没人维护的旧项目，文档几乎没有，唯一能确认的是它还能编译。以前我会花一下午自己翻代码、理清模块关系；这次我把这个过程完全交给了 opencode。

我把项目打开后的第一个提示词是这样的：

先不要改任何代码。 1. 读取 AGENTS.md 和 README（如果有）； 2. 找到入口文件并解释启动流程； 3. 画出顶层模块的依赖关系，用文字描述； 4. 列出最重要的命令（构建、测试、启动）。

它跑完之后，又自己执行了几次 grep 和 read，最后给我一份内容扎实的架构说明，包括入口、核心模块、测试命令，甚至指出了两处疑似死代码的位置。整个过程大约半小时，其中大部分时间是我在看它的输出、追问细节。这个工作流把我从“考古队员”解放成了“审核员”，价值很高。

这里有个容易被忽略的细节：给它的第一个任务必须是“只读分析”，而不是“帮我优化一下这个项目”。如果不加这个边界，模型大概率会直接开改，改到一半你才发现它对项目的理解还是错的。先让它证明自己理解了代码库，再放它动手，是接盘老项目的黄金法则。

4.2 远程开发与数据库操作怎么配合

日常开发里，我和很多人一样有远程开发的需求——代码在开发机上，本地用 SSH 连过去。opencode 在这块的落地方式很简单：在远程终端里跑 opencode，本地 VSCode 通过 Remote-SSH 连到同一目录。这样模型执行的命令就发生在真实环境里，路径、依赖、网络条件全部对得上，不会出现“本地能跑远程不能跑”的落差。

数据库操作又是另一套逻辑。我踩过一次坑：图省事给 opencode 挂了开发库的可写权限，它一上来就尝试跑批量 UPDATE，幸好事务和备份兜住了。从那以后，我的原则很明确：图形化数据库工具负责“看”，opencode 负责“写代码”，高风险写操作一律人工执行。

具体分工是：用 SQLServer 这类图形化工具查表结构、跑只读查询、确认数据特征，然后把这些结构信息作为上下文交给 opencode，让它生成代码。如果你确实想让 opencode 自己摸 schema，也建议用只读 MCP，并明确告诉它“禁止写操作、禁止无条件 UPDATE/DELETE”。

4.3 提交信息、Code Review 与日常自动化

日常提交里，我现在习惯直接用 opencode 生成提交信息：

opencode run "根据 git diff --staged 的改动生成规范的提交信息"

它比大部分模板插件灵活，因为它真的会读 diff 内容而不是只拼写文件列表。生成完之后我自己改一版再提交，省去了每次憋消息的时间。

还有一个我目前正在实验的用法：在 pre-commit 阶段对 staged 改动跑一次 opencode 审查，输出潜在问题清单。注意，这个清单我不会盲信——模型做审查时偶尔会误报，甚至会漏掉真正的风险项。所以我的姿势是把它当成“第一道扫描仪”，输出一份带理由的评论列表，最终的判断和取舍仍然在我手里。

从这些日常动作来看，opencode 最适合接管的不是“高难度的架构设计”，而是那些流程固定、重复度高、需要读大量代码才有可能做好的杂活。真正重要的决策，人类依然要在场。

4.4 项目配置进 Git：团队协作时的同步方案

如果你的团队不止你一个人用 opencode，我强烈建议把项目级配置放进 Git 仓库。这样全队共用一套 agent 规则、工具配置和项目规范，不会出现张三的 opencode 很乖、李四的很乱的情况。

我会把这几样东西提交进去：opencode.json（项目级配置）、AGENTS.md（项目规范）、以及必要的 agent 定义文档。提交的时候注意不要把 API key、token 这类敏感信息写进配置文件，改用环境变量引用。这个道理跟写代码一样：密钥不落库。

还有一点经验：opencode 本身的版本迭代非常快，项目级配置尽量只写保守、稳定的字段，别把刚出的新功能立刻固化进团队配置。先在自己环境里验证稳定了，再推广给其他人，不然时不时就出现“配置文件不兼容”的提示，反而增加维护成本。

我个人的习惯是，每接一个新项目，第一件事就是写下 AGENTS.md 的基本内容，哪怕只有三五行：技术栈是什么、启动命令是什么、代码风格有什么红线。之后 opencode 每次开始干活都会先读它，相当于给我所有的 AI 助手统一做了一次“入职培训”。

最后再分享一个小技巧：如果你发现自己经常和 opencode 在工具调用上较劲，先把默认模型调成“快模型”，遇到真正难啃的问题再手动切换到重模型。这个切换习惯能让日常交互明显更跟手，模型也不容易在一个简单问题上过度思考。这也是我目前每天工作里最依赖的配置之一。