企业官网建设流程全解析

上篇我们把 opencode 跑通了，能对话、能改文件、能跑命令，看起来是个很不错的终端AI助手。但不少朋友用了一两周就停在“玩具阶段”——让它做点小任务还行，一碰真实项目就露怯：该调的接口调不到、模型换起来手忙脚乱、团队根本没法统一玩法。问题不在 opencode 本身，而是你还没碰到它真正值钱的部分：工具（Tools）、服务面（Providers/Servers）和外壳（Shell/Hooks）。这三块才是把“能跑的 demo”变成“每天靠它干活”的分水岭。本篇就把这三层拆开揉碎，最后用一个真实场景带你把它们串起来，看完你就能直接照搬到自己项目里。

1. 工具面：Agent的手脚，决定它是助手还是玩具

1.1 内置工具的“分工逻辑”

opencode 内置工具并不算多，但每类都指向一个明确意图。大致可以分四组：读（Read、Glob、Grep）、写（Write、Edit）、执行（Bash）、探索/协作（WebSearch、Task 等）。理解这个分组的逻辑，比背工具列表重要得多。

定位搜索交给 Glob 和 Grep，而不是 Read。很多新手让模型“打开文件看看”，结果一个几千行的文件全塞进上下文，钱花了、效果还差。正确的做法是先 Grep 定位关键符号，再 Read 局部读取，需要确认结构时用 Glob 匹配文件名。这符合 Agent 的运行逻辑：每一次工具调用都会消耗上下文空间，检索效率直接决定了任务的完成质量和成本。

Bash 工具是双刃剑。它给了 Agent 真正的动手能力，也给了它破坏能力。我的习惯是：先让它用只读命令（ls、git status、grep）收集信息，再让它执行写操作。这个顺序不是纪律问题，而是上下文管理问题——只有掌握了足够的项目信息，后续的写入动作才不至于反复回滚。

1.2 别急着写自定义工具，先把内置工具用透

很多同学一上来就琢磨怎么接入内部系统、怎么写插件，结果被一堆自定义逻辑绊住。我见过太多项目，问题根本不是“工具不够”，而是内置工具没有被正确组合。我最常用的一套组合拳：

1. 开局用 Glob 摸清项目目录结构
2. 用 Grep 定位核心模块和入口文件
3. 用 Read 读取关键实现片段
4. 用 Bash 跑测试或构建验证判断
5. 最后才用 Write/Edit 做修改

这套流程解决了我早期 80% 的需求。还有一个容易忽略的点：Task 子任务工具。面对跨模块的大型改动（比如“这个接口要改，调用方有七八处”），与其让 Agent 在一个超长上下文里线性推进，不如拆成几个子任务并行探索。opencode 的 Task 工具可以把子任务的结论汇总回主对话。实测下来，这比一根筋处理全流程稳定得多。

1.3 自定义工具：把“人肉操作”交给 Agent

内置工具用透之后，下一步才是自定义工具。什么时候必须上自定义工具？三个典型信号：一是有固定的 CLI 流程，比如新模块脚手架生成；二是每次都要访问内部接口，比如查询某个配置中心的开关状态；三是多步骤操作想封装成一句话，比如“打完包丢到测试环境”。这些事让 Agent 仿着做容易出错，封装成工具后可以被稳定调用。

自定义工具的本质很简单：你用任意语言写一个脚本，能读 stdin 拿参数、往 stdout 输出结果，再在配置文件里注册一下就行。关键点在描述上。你给工具写的 description 就是 Agent 判断“什么时候该用”的依据，写得越具体，调用越准确。工具名要短，描述要含使用时机和参数含义，参数用 JSON Schema 声明，别让模型去猜。

举个例子，项目里通常有初始化模块的命令npm run generate:module -- --name=xxx。你可以写个包装脚本：

#!/usr/bin/env bash name=$(jq -r '.name' <<< "$BASH_ARGV") # 调用项目内部脚手架 npm run generate:module -- --name="$name" --template="$template_dir" echo "module $name generated"

然后注册成工具，描述里写清楚“当用户需要新建模块时，用此工具，参数 name 必填”。这一步做完，Agent 就能像调用内置工具一样执行你团队内部的流程。

1.4 工具调用的权限与容错

工具越多，权限设计越要提前想。opencode 对每个工具和每条 Bash 命令都可以进行“允许/拒绝/询问”的约束。我的经验是：读类命令默认放行，写类命令保持询问，删除、重定向这类的干脆拒绝。别图省事把所有命令都 allow，否则一次误操作的成本远超那点确认时间。

还要给工具调用留出容错余地。脚本工具要设计好退出码和错误输出。Agent 判断工具是否成功，主要靠退出状态和 stderr。如果脚本因为缺参数返回 0 但实际没干活，模型会被误导。我的习惯是：脚本开头做参数校验，失败时输出 JSON 格式错误并返回非 0 退出码。这样 Agent 读到错误能自己修正再试，而不是一头雾水地继续下一步。

2. 服务面：模型接入与真正的成本控制

2.1 服务面到底“面”在哪

标题里说的“服务面”，指的就是模型服务接入层。opencode 的核心抽象是 Provider：任何服务，只要能按统一协议暴露出来，就能无缝替换。对使用方来说，这意味着模型选择权在你手里，而不是被某个编辑器绑定。这对接国内用户尤其重要——你可以随意切换不同服务商，也可以随时切回本地模型，全部只改配置，不动业务逻辑。

典型的 Provider 配置包含三样：接口地址、密钥、模型名。opencode 走的是 OpenAI 兼容协议，所以市面上绝大多数模型服务都能直接填进去。配置文件长这样：

{ "provider": { "default": "custom", "custom": { "apiKey": "your-key-here", "baseUrl": "https://your-provider.example.com/v1", "models": { "code-model": { "name": "your-code-model-name" } } } } }

2.2 模型参数：别照抄默认值

接入模型后，很多人默认参数一直用到底。实际上代码生成场景下，有几个参数非常值得调。

Temperature 建议调低。程序员的幽默感在代码里越少越好，低温度（0.2 左右）能明显减少“看起来对但跑不起来”的幻觉输出。上下文长度要心里有数。长对话场景下，上下文耗尽是个硬边界。opencode 里针对超长会话有压缩和裁剪机制，但比依赖自动压缩更重要的是主动控制输入：开局让 Agent 先看项目结构而不是贴几千行代码，能省掉大量无效上下文。

还有一个很实用的参数：最大输出长度。有些模型默认输出很短，Agent 生成一半就停，导致文件被截断。配置时把 maxTokens 设置到模型允许的合理上限，能减少这类半截代码问题。我在实际项目中把输出上限翻了一倍之后，“代码写到一半就断”的情况几乎绝迹。

2.3 本地模型与云端模型协同

本地模型没有试用门槛，也不怕限流，但推理能力和上下文窗口往往不如云端。我的做法是分级使用：简单任务（变量改名、格式化、补注释）交给本地模型，复杂重构、跨文件改动、依赖升级这类任务切到云端强模型。

即便只在本地和云端之间切换，你的工程效率差距也会拉开。日常小改动走本地，延迟低、零成本，不会因为网络波动打断思路；大任务再切云端。opencode 里切换模型很快，所以别怕来回切。针对固定任务，甚至可以把不同难度自动路由到不同模型，省心不少。

2.4 限流、超时、计费：写代码前先算账

用云端模型必须面对三个现实问题：限流、超时、计费。我吃过亏：让 Agent 批量处理几万个文件，结果中途被限流卡死，整个任务卡在半路。后来学乖了，把大任务拆小，并且设置合理的并发上限。

成本控制上，最关键的是上下文管理。一次长会话的费用大头往往不是 token 总数，而是对话越聊越长之后每轮都在重新处理累积的上下文。我建议每完成一个阶段性任务，就主动开一个新会话，把上下文精简后带过去继续。别把会话当成草稿纸一直往上堆，堆到后面每轮对话都在为前面所有废话买单。

再说说超时。长任务运行中，工具调用或模型请求偶尔会卡住。与其干等，不如在操作层面养成“分步走”的习惯：让 Agent 一次只做一个可验证的步骤，而不是一口气列出二十步计划。单步超时后，重试和恢复的成本都低得多。

3. 外壳：会话、TUI与可编程工作流

3.1 TUI 里的效率细节

TUI（终端用户界面）是 opencode 这层外壳的第一印象。很多人觉得终端界面不如图形界面直观，但真正高频使用之后，我发现键盘流在 TUI 里的效率反而更高。状态栏会显示当前模型、会话 ID、目录位置，建议花十分钟把帮助面板过一遍，把所有快捷键记下来再开始用。

几个容易忽略的点：Vim 模式支持让习惯了 Vim 键位的人直接在编辑区操作；diff 视图可以逐行确认 Agent 的修改，这个习惯能拦住大量垃圾改动；日志面板对排查问题至关重要，工具调用成功与否、报错信息在日志里一目了然。这些功能不是装饰，而是你判断 Agent 是否“正常发挥”的唯一依据。

3.2 Hooks：让工作流自己转起来

如果只说一个“用了就回不去”的 opencode 功能，我选 Hooks。它是连接 Agent 和外部世界的触发器：会话开始、用户提交 prompt、Agent 完成回复、会话结束，甚至异常通知，都能触发你指定的命令、脚本或通知。

最简单的落地场景是会话结束钩子。比如希望每次 Agent 干活时自动保存代码变更：

{ "hooks": { "events": { "SessionEnd": [ { "type": "command", "command": "git add -A && git commit -m \"auto: session completed\"" } ] } } }

这只是一个起步。我建议把 Hook 的触发条件从“会话结束”细化到“Agent 完成特定行为”。比如在重要任务完成后自动跑一遍测试，再根据测试结果决定是否发通知。这样 Agent 不再是孤立改代码的哑工具，而是嵌入了你团队质量闭环的一个环节。

3.3 会话管理与团队协作

会话管理在长周期项目里是刚需。opencode 的会话支持恢复、fork、归档。隔天继续前一天的活，直接恢复会话就行；想验证一个不破坏现有上下文的临时想法，就 fork 一个分支会话。这个过程和 git 分支的思维如出一辙，也建议严格执行：主干会话保持稳定，实验性操作全部放到 fork 里。

团队协作方面，最实际的做法是把配置文件、脚本和 Hook 定义都放进 Git 仓库。新同事 clone 完项目，跑一次初始化命令就能获得与团队一致的 AI 工作环境。这比让大家各自摆弄配置高效得多，也能避免“他机器上能跑，我机器上不行”的灵异问题。

3.4 配置文件的“人多口杂”问题

团队统一配置时，最怕的就是配置文件越改越乱。我的经验是把配置分成两层：一层是公共的、稳定的，放进项目仓库；另一层是本地的、私人的（比如密钥），通过本地覆盖文件处理，不进版本库。权限规则也走公共配置，但允许个人在本地放宽自己账号的某些限制。这样既保证了团队的一致性，又保留了个人灵活性。

4. 实战集成：从零给一个存量项目装上AI助手

4.1 场景设定：给一个老旧 Web 服务做“体检”

空谈理论没意思，我们用一个具体场景把前面所有内容串起来。假设有一个模拟项目 X：一个运行了几年的 Web 服务，代码结构混乱，缺文档，新人接手至少要看两周才能上手。典型痛点：新人上手慢、提交信息乱、接口无文档。我们现在目标很明确：通过配置 opencode，做成一个“项目专家”，让它能在几分钟内回答新人关于项目的任何基础问题，并且规范团队的提交流程。

4.2 第一步：初始化配置和最小验证

先在项目根目录创建 opencode.json，配置好默认模型和权限规则。这一步有个原则：最小化验证优先。我不建议一上来就写一堆自定义工具，先把模型接好、内置工具放行，跑通一轮“帮我梳理项目结构，输出关键模块清单”的对话。

这轮对话的产出很关键。让 Agent 用 Glob 扫描目录、用 Grep 搜索核心入口、用 Read 读取启动脚本和路由定义，最终生成一份项目结构说明。这份说明会留在会话上下文里，后续所有提问都可以基于它回答。实测下来，一个中大型项目，这一步大概消耗几分钟时间，换来的是新人能直接向 Agent 提问“登录模块怎么走流程”这种问题，而不是翻半天代码。

4.3 第二步：把内部脚手架变成自定义工具

项目里通常有几个“人肉执行”的固定流程，脚手架的生成是最典型的一个。比如老项目里新建一个模块要手动创建目录、登记路由、加配置，新手经常漏步骤。把整个流程写进一个 bash 脚本，再注册成自定义工具，之后 Agent 收到“帮我加一个订单模块”的指令时，就会自动调用工具，而不是靠记忆猜测流程。

写这个脚本时要注意输出信息要结构化：成功时输出“module ok, files: ...”，失败时输出具体错误原因。调试阶段有个笨但有效的方法：先在终端里手动跑一遍脚本，确认输入输出都是稳定正确的，再注册到 opencode 里。否则你会分不清是 Agent 调用姿势不对，还是脚本本身有 bug。

4.4 第三步：Hook 守住代码规范底线

提交信息混乱的问题，我用一个提交前 Hook 来解决：让 Agent 每次会话结束前，自动检查当前改动是否符合团队的提交规范——不符合就拦截，符合就顺手生成提交信息。这一步不复杂，关键在于脚本要“可重入”，即跑一次和跑一百次结果一致，绝对不能每次运行都改动文件。

实现细节上，脚本要显式设置 PATH 环境变量，因为在 Hook 环境中 PATH 往往很短，直接调用 npm/npx 可能失败。另外任何一条日志都要输出到标准错误还是标准输出要想清楚，否则 Agent 会把这些输出当成任务结果的一部分，干扰判断。

4.5 第四步：多 Provider 降级与成本控制

配置好后，我给团队定了一条使用纪律：日常小问题（查 API 定义、找函数实现）用便宜模型就够；涉及跨模块重构、框架升级这类高危改动，才切到强模型。这条纪律不是拍脑袋定的，而是我观察了一个月后的结论——多数日常问题根本不需要顶级模型的推理能力，用便宜模型跑起来速度反而更快。

执行层面，我们在配置里准备了两个模型入口，并在文档里写清楚切换姿势。遇到强模型被限流或者服务不稳定的情况，就切到备用模型继续干。整套配置下来，项目 X 的 AI 助手算是真正嵌入了团队日常：新人提问有应答、提交规范有卡口、高频重复操作有工具兜底。这比当初预想的“一个会写代码的机器人”有价值得多。

5. 常见问题与排查经验

5.1 工具调用失败：先看权限再看输出

遇到“Agent 说要执行命令但没执行”或者“工具调用失败”，九成问题出在权限配置上。第一反应别去检查代码，先看日志里的权限拦截记录。常见情况是 sed -i 这类命令默认不允许，或者自定义工具忘了注册到白名单。排错顺序建议：确认权限放行，确认脚本本身可执行，确认脚本能否在纯净环境跑通。这个顺序能省下大量瞎猜时间。

5.2 长任务无响应：日志、会话恢复、子任务

长任务卡死是另一个高频问题。现象是 Agent 长时间不输出，你以为卡了，实际可能是在等待工具结果，也可能是模型请求超时。先切到日志面板看最后一条事件，再判断是等模型还是等命令。如果是模型请求超时，直接终止会话恢复到一个检查点重试；如果是命令执行时间长，建议把长命令拆成多个短步骤，让每一步都有中间反馈。维护一个“最近一次成功状态”的检查点，长任务就不会轻易全盘崩溃。

5.3 Hook 不触发：别瞎猜，先跑脚本

Hook 不触发的排查路径很直接：先手动执行 Hook 配置里的命令，确认脚本本身无问题；再确认事件名拼写正确，并设置了对应的触发条件；最后确认是否异步执行导致看不到输出。大多数“Hook 没生效”其实是脚本执行报错但被吞了，或者触发条件不匹配。切忌在没跑通脚本之前就去改配置，那是浪费生命。

5.4 配置了但不生效：逐层 check

改配置文件后发现不生效，最常见的两个原因：一是没重启会话，运行时环境不会热加载；二是路径写错了，配置里的脚本路径或工作目录是相对路径，导致找不到文件。建议所有路径写绝对路径或基于项目根目录的显式路径。排查顺序：先确认改的文件是用对了那个配置；再确认配置语义正确；最后确认运行时确实加载了新配置。逐层 check 下来，一般五分钟内能定位。

5.5 一些容易踩的“低级坑”

权限配置中，allow 列表里路径带通配符时经常出意外，建议明确到目录级别；自定义工具的脚本输出不要用彩色 ANSI 转义，模型解析会受影响；多 Provider 切换时，旧会话的模型上下文不会自动清空，切模型后最好新开一个会话。这些坑都不难解决，但它们往往比模型选型更影响日常使用体验。

我个人在实际操作中最深刻的体会是：opencode 这类工具能不能在生产环境立住，关键不在模型多强，而在于你有没有把“使用它的方式”当成项目的一部分来治理。工具可以简单、外壳可以朴素，但工具调用规则、模型切换策略、Hook 脚本质量这些“制度设计”，才是它真正产生价值的地方。你投入在配置和脚本上的每一分钟，都会在日后无数次重复任务中成倍赚回来。