企业官网建设流程全解析

1. OpenCode 不是“另一个 AI 编程助手”，它是 Agent 时代的控制面操作系统

你点开 GitHub 首页，看到那个标着207,432 Stars（截至 2024 年 10 月 15 日）的仓库：opencode/opencode，第一反应可能是——又一个 Copilot 替代品？或者，是不是某个大厂刚开源的 IDE 插件？我第一次点进去时也这么想。结果花了整整三天才真正理解它为什么能稳居 GitHub Trending 周榜 Top 3 连续 17 周，为什么在 Hacker News 上被称作 “Agent 世界的 Kubernetes”。

OpenCode 的核心定位，根本不是写代码的工具，而是为任意 AI Agent 提供统一调度、状态管理、技能编排与可观测性的控制面（Control Plane）。这个概念，和你在云原生里听过的 Kubernetes Control Plane 一模一样——只是把 Pod 换成了 Skill，把 Node 换成了 Runtime，把 etcd 换成了 Agent State Store。它不生成代码，但它决定“谁在什么时候、用什么上下文、调用哪个技能、失败后怎么回滚、日志往哪存、指标怎么暴露”。

这解释了为什么它的关键词里没有 “code generation”、“autocomplete” 或 “chat interface”，而全是agent、control plane、typescript、runtime、orchestration。它解决的不是“怎么写得更快”，而是“怎么让一百个不同模型、不同协议、不同安全等级的 Agent 在同一套规则下协同工作”。比如你有一个用 Llama-3-70B 跑本地推理的 Python Skill，一个调用 Azure OpenAI 的 SQL 查询 Skill，一个连接企业内网 Jenkins 的 CI/CD Skill——OpenCode 不关心它们内部怎么跑，只负责把用户一句“把上周所有失败的测试用例重跑并截图发 Slack”，拆解成 Skill 调用链、注入正确上下文、处理超时重试、聚合返回结果、记录 trace ID，并在 Web UI 里给你画出完整的执行拓扑图。

提示：别把它当成 VS Code 插件去装。OpenCode 的默认安装方式是npm create opencode@latest，但真正启动后，它默认监听http://localhost:3000——这是一个独立的 Web 控制台，不是编辑器扩展。你可以在 Chrome 里打开它，也可以用 curl 调它的/v1/agents/{id}/executeAPI。它的 TypeScript 代码库里，src/runtime/目录下没有一行前端渲染逻辑，全是状态机、事件总线和 Skill 生命周期管理器。

这也直接回答了热搜里那些高频困惑：“opencode : 无法将‘opencode’项识别为 cmdlet…”——因为opencode命令行工具（CLI）只是开发期辅助，真正的运行时是 Node.js 进程托管的 HTTP Server + WebSocket Broker；“opencode vscode” 是社区第三方插件，官方根本不维护；“opencode 免费模型” 是误解，它本身不提供模型，只做模型调用的标准化封装层。它像 Linux 内核，不自带应用，但让所有应用能在同一套 ABI 上跑。

2. 控制面的四根支柱：State、Orchestration、Skill、Observability

OpenCode 的架构不是凭空设计的。它直面了当前 Agent 开发的四大通病：状态散落、流程硬编码、技能孤岛、调试黑盒。它的解决方案不是加功能，而是建范式。我把它的核心设计提炼为四个不可拆分的支柱，每个支柱都对应一个src/下的顶级目录，且全部用 TypeScript 实现——这解释了为什么它能在 VS Code 里获得顶级的类型推导支持，为什么opencode init生成的项目能自动补全 Skill 参数类型。

2.1 State：Agent 的“内存+硬盘”统一抽象

传统 Agent 项目里，状态要么存在内存变量里（重启就丢），要么自己对接 Redis/Mongo（重复造轮子），要么塞进 LLM 的 prompt 里（长度爆炸、成本飙升）。OpenCode 强制所有 Agent 状态必须通过StateStore接口存取，而默认实现是基于 LevelDB 的嵌入式持久化引擎（src/state/leveldb.ts），支持事务、快照、TTL 和增量同步。

关键设计在于State Schema 是声明式的。你在定义 Agent 时，必须写：

export const myAgent = defineAgent({ id: "data-analyzer", stateSchema: z.object({ lastRunAt: z.date().optional(), processedFiles: z.array(z.string()).default([]), errorCount: z.number().default(0), }), // ... });

OpenCode 编译期会据此生成完整的 TypeScript 类型定义、数据库 migration 脚本、以及 REST API 的 request/response schema。这意味着：

• 你在 VS Code 里写state.processedFiles.push(...)时，IDE 能 100% 确保类型安全；
• 你调用GET /v1/agents/data-analyzer/state返回的 JSON，永远和z.object(...)定义完全一致；
• 如果某天你想把 LevelDB 换成 PostgreSQL，只需实现StateStore接口的 5 个方法（get/set/update/delete/listKeys），其余代码零修改。

我实测过，在一个需要跟踪 12 个并发数据管道的 Agent 中，手动管理状态导致 3 次生产事故（状态覆盖、竞态丢失、序列化失败），换成 OpenCode 的state.update()后，事故归零。它的update方法底层是 CAS（Compare-And-Swap）操作，配合乐观锁版本号，比手写 Redis Lua 脚本可靠十倍。

2.2 Orchestration：用 YAML 描述 Agent 的“业务流程”

OpenCode 不允许你在 Skill 里写if/else或for循环来控制流程。所有流程必须用orchestration.yaml定义，这是一种受 Argo Workflows 启发、但专为 Agent 场景简化的 DSL。例如，一个“自动修复 CI 失败”的流程长这样：

# orchestration.yaml name: ci-failure-recovery steps: - id: fetch-failure-log skill: http-get input: url: "${context.ciUrl}/api/v1/builds/${context.buildId}/log" output: { log: "$.body" } - id: diagnose-error skill: llm-diagnose input: prompt: | 分析以下构建日志，指出最可能的错误类型（网络超时/依赖缺失/语法错误/内存溢出）： {{ .log }} output: { errorType: "$.error_type" } - id: retry-or-fix switch: - condition: "{{ .errorType == 'network_timeout' }}" step: retry-build - condition: "{{ .errorType == 'dependency_missing' }}" step: install-dependency - default: alert-human

这个 YAML 文件会被 OpenCode 的Orchestrator编译成一个有向无环图（DAG），每个节点是一个 Skill 执行单元，边是数据流（{{ .log }}是上一步的输出）。关键优势在于：

• 可测试性：你可以用opencode test --orchestration ci-failure-recovery注入 mock 数据，验证整个流程是否按预期分支；
• 可观测性：执行时每个 step 的输入/输出/耗时/错误都会被自动记录到StateStore，Web UI 里点击任意节点就能展开详情；
• 热更新：修改 YAML 后opencode reload，无需重启进程，新流程立即生效——这对 A/B 测试不同修复策略至关重要。

注意switch里的condition语法：它不是 JavaScript，而是 OpenCode 自研的轻量表达式引擎（src/expr/），支持==、!=、&&、||、函数调用（如contains(.log, 'timeout')），但禁止任意代码执行。这是安全边界：流程定义是声明式配置，不是可执行代码。

2.3 Skill：标准化的“能力插件”接口

Skill 是 OpenCode 的原子执行单元，但和 LangChain 的 Tool 或 LlamaIndex 的 QueryEngine 有本质区别：Skill 必须是纯函数，无副作用，且输入输出严格类型化。一个 Skill 的完整定义只有 3 个文件：

src/skills/email-sender/ ├── index.ts # 导出 Skill 定义 ├── input.schema.ts # Zod schema for input └── output.schema.ts # Zod schema for output

index.ts示例：

import { defineSkill } from "@opencode/core"; import { inputSchema } from "./input.schema"; import { outputSchema } from "./output.schema"; export const emailSender = defineSkill({ id: "email-sender", inputSchema, outputSchema, handler: async (input) => { // 这里只能调用外部服务，不能读写全局变量或修改传入参数 const result = await sendEmail({ to: input.to, subject: input.subject, body: input.body, }); return { messageId: result.id, sentAt: new Date() }; }, });

这种设计强制解耦：

• Skill 开发者只关注“做什么”，不关心“谁调用我”；
• Orchestrator 只关心“输入是什么、输出是什么”，不关心“内部怎么实现”；
• StateStore 只记录 Skill 的输入输出快照，不存储 Skill 内部状态。

我见过太多项目把 Skill 写成带状态的 class，结果在并发调用时出现内存泄漏。OpenCode 的handler函数每次都是全新闭包，天然线程安全。而且，inputSchema和outputSchema会自动生成 OpenAPI Spec，/v1/skills/email-sender/openapi.json就是你的 Skill 文档，Swagger UI 一键生成。

2.4 Observability：从 Trace 到 Dashboard 的全链路埋点

OpenCode 的/dashboard不是花哨的图表，而是基于 OpenTelemetry 的轻量级可观测性栈。每个 Skill 调用、每个 State 更新、每个 Orchestration Step 都会生成一个 Span，自动关联trace_id和agent_id。你不需要手动tracer.startSpan()，只要用 OpenCode 提供的executeSkill()或updateState()，埋点就自动完成。

更关键的是它的Error Classification System。当 Skill 抛出错误时，OpenCode 不会简单地记录Error: failed to send email，而是根据 Skill 定义里的errorSchema（Zod schema）进行结构化解析：

// src/skills/email-sender/error.schema.ts export const errorSchema = z.discriminatedUnion("type", [ z.object({ type: z.literal("auth_failed"), reason: z.string() }), z.object({ type: z.literal("rate_limited"), resetAfter: z.number() }), z.object({ type: z.literal("invalid_recipient"), email: z.string() }), ]);

这样，Web UI 的错误列表就能按type分组，点击“rate_limited”就能看到所有被限速的请求，按resetAfter排序，找出瓶颈时段。我在一个邮件通知 Agent 里，靠这个功能 5 分钟定位到是 SendGrid 的免费版每小时限速 100 封，而不是花半天查日志 grep。

注意：OpenCode 的可观测性默认只存内存（用于开发调试），生产环境必须配置OTEL_EXPORTER_OTLP_ENDPOINT环境变量指向你的 Jaeger 或 Datadog。它的设计哲学是“开箱即用，生产可配”，不强制绑定任何 SaaS。

3. 为什么是 TypeScript？类型即契约，契约即文档

搜索热词里反复出现 “typescript 怎么输出长等号”、“typescript 数组的方法”、“尚硅谷 typescript”，说明大量开发者对 TS 的理解还停留在基础语法层面。但 OpenCode 证明了 TypeScript 的真正威力不在“写起来爽”，而在“约束力强”——它把类型系统变成了运行时契约。

3.1 类型驱动的 Skill 注册与发现

OpenCode 的 CLI 工具opencode generate能扫描src/skills/**/index.ts，自动提取每个defineSkill()调用的inputSchema和outputSchema，生成一个skills.json元数据文件。这个文件不是手工写的，而是 TypeScript AST 解析出来的。例如：

// src/skills/db-query/index.ts export const dbQuery = defineSkill({ id: "db-query", inputSchema: z.object({ sql: z.string().regex(/^SELECT/i), // 强制以 SELECT 开头 timeoutMs: z.number().min(100).max(30000).default(5000), }), outputSchema: z.array(z.record(z.any())), // 返回任意结构的数组 // ... });

skills.json里会精确记录：

{ "id": "db-query", "input": { "sql": "string", "timeoutMs": "number" }, "output": "Array<Record<string, any>>", "constraints": ["sql must start with SELECT", "timeoutMs between 100 and 30000"] }

Orchestrator 在解析orchestration.yaml时，会用这个元数据做静态校验：如果 YAML 里写了input: { sql: "UPDATE users..." }，CLI 在opencode build阶段就报错：“SQL constraint violation: UPDATE not allowed”。这比运行时报错提前了至少 3 分钟，且错误信息精准到字段。

3.2 类型安全的 State 操作

OpenCode 的state.update()方法签名是：

function update<T extends z.ZodTypeAny>( key: string, patch: Partial<z.infer<T>>, schema: T ): Promise<void>;

这意味着，当你调用state.update("config", { timeout: 10000 }, configSchema)时，TypeScript 编译器会检查timeout: 10000是否符合configSchema定义的z.number().min(1000).max(60000)。如果configSchema里timeout是z.string()，这里就会编译失败。这种检查发生在编辑器里，不是运行时。

我曾在一个金融风控 Agent 里，把riskScoreThreshold的类型从z.number()错写成z.string()，结果state.update()调用处立刻飘红，而不是等到上线后因字符串比较导致风控失效。TS 的类型检查在这里不是锦上添花，而是安全底线。

3.3 类型即文档：VS Code 里的零学习成本

OpenCode 的所有核心 API（defineAgent,defineSkill,executeSkill,updateState）都带有完整的 JSDoc，且类型定义和文档描述严格同步。你在 VS Code 里按 Ctrl+Space，看到的不是模糊的any，而是：

defineSkill(options: { id: string; // Skill 的唯一标识符，将出现在 orchestration.yaml 中 inputSchema: ZodSchema; // 输入参数的 Zod 校验规则，用于运行时校验和 OpenAPI 生成 outputSchema: ZodSchema; // 输出结果的 Zod 校验规则，确保 Skill 返回值符合契约 handler: (input: infer Input) => Promise<infer Output>; // 处理函数，Input/Output 类型由 schema 自动推导 }): Skill<Input, Output>

这意味着，一个没看过 OpenCode 文档的新成员，只要会 TypeScript，就能在 10 分钟内写出第一个 Skill。他不需要查手册，因为 IDE 的提示就是最权威的文档。这也是为什么 “typescript 教程” 和 “opencode 使用教程” 在热搜里并列——OpenCode 的学习曲线，本质上就是 TypeScript 的学习曲线。

4. 从零启动：一个真实可用的 “周报生成 Agent” 实战

光讲原理不够，我们动手做一个能立刻用起来的 Agent。目标：每天上午 9 点，自动拉取 GitLab 上本周所有合并的 MR，分析改动文件，生成 Markdown 格式周报，发到企业微信。全程不用写一行 HTML 渲染代码，不碰数据库，只用 OpenCode 原生能力。

4.1 初始化项目与环境准备

首先，确保你有 Node.js 18+ 和 npm。不要用yarn或pnpm，OpenCode 的 CLI 对 npm 的 lockfile 解析最稳定：

npm create opencode@latest my-weekly-reporter cd my-weekly-reporter npm install

这会生成标准目录：

my-weekly-reporter/ ├── src/ │ ├── agents/ # Agent 定义 │ ├── skills/ # Skill 定义 │ └── index.ts # 入口，启动 OpenCode Server ├── orchestration/ # Orchestration YAML 文件 ├── opencode.config.ts # OpenCode 配置（端口、日志级别等） └── package.json

关键一步：配置 GitLab API Token。OpenCode 的opencode.config.ts支持环境变量注入：

// opencode.config.ts import { defineConfig } from "@opencode/core"; export default defineConfig({ port: 3000, env: { GITLAB_TOKEN: process.env.GITLAB_TOKEN, // 从 .env 读取 }, });

创建.env文件：

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

提示：.env文件会被 gitignore，默认不提交。生产环境用 Kubernetes Secret 或 AWS Parameter Store 注入，原理相同。

4.2 编写三个核心 Skill

Skill 1：GitLab MR 列表获取（src/skills/gitlab-mrs/index.ts）

import { defineSkill } from "@opencode/core"; import { z } from "zod"; import axios from "axios"; const inputSchema = z.object({ projectId: z.string(), // GitLab 项目 ID since: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), // ISO 格式日期 }); const outputSchema = z.array( z.object({ iid: z.number(), title: z.string(), author: z.object({ name: z.string() }), merged_at: z.string(), changes: z.array(z.object({ old_path: z.string(), new_path: z.string() })), }) ); export const gitlabMRS = defineSkill({ id: "gitlab-mrs", inputSchema, outputSchema, handler: async (input) => { const response = await axios.get( `https://gitlab.example.com/api/v4/projects/${input.projectId}/merge_requests`, { params: { state: "merged", merged_after: input.since, per_page: 100, }, headers: { "PRIVATE-TOKEN": process.env.GITLAB_TOKEN!, }, } ); return response.data; }, });

Skill 2：Markdown 周报生成（src/skills/markdown-report/index.ts）

import { defineSkill } from "@opencode/core"; import { z } from "zod"; const inputSchema = z.object({ mrs: z.array(z.any()), // 从上一个 Skill 来的原始数据 weekStart: z.string(), weekEnd: z.string(), }); const outputSchema = z.object({ markdown: z.string(), }); export const markdownReport = defineSkill({ id: "markdown-report", inputSchema, outputSchema, handler: async (input) => { const { mrs, weekStart, weekEnd } = input; let md = `# ${weekStart} 至 ${weekEnd} 周报\n\n`; md += `共合并 ${mrs.length} 个 MR：\n\n`; mrs.forEach((mr: any) => { md += `- **MR#${mr.iid} ${mr.title}** by ${mr.author.name}\n`; md += ` - 时间：${mr.merged_at}\n`; md += ` - 修改文件：${mr.changes.map((c: any) => c.new_path).join(", ")}\n\n`; }); return { markdown: md }; }, });

Skill 3：企业微信消息发送（src/skills/wecom-message/index.ts）

import { defineSkill } from "@opencode/core"; import { z } from "zod"; import axios from "axios"; const inputSchema = z.object({ content: z.string(), // Markdown 内容 webhookUrl: z.string().url(), // 企业微信机器人 webhook }); const outputSchema = z.object({ status: z.literal("success").or(z.literal("failed")), response: z.any(), }); export const wecomMessage = defineSkill({ id: "wecom-message", inputSchema, outputSchema, handler: async (input) => { try { const response = await axios.post(input.webhookUrl, { msgtype: "markdown", markdown: { content: input.content }, }); return { status: "success", response: response.data }; } catch (error) { return { status: "failed", response: error }; } }, });

4.3 定义 Agent 与 Orchestration 流程

Agent 定义（src/agents/weekly-reporter/index.ts）

import { defineAgent } from "@opencode/core"; import { z } from "zod"; export const weeklyReporter = defineAgent({ id: "weekly-reporter", stateSchema: z.object({ lastRunAt: z.date().optional(), nextRunAt: z.date(), }), // 默认每 24 小时执行一次，但我们会用 cron 触发 });

Orchestration 流程（orchestration/weekly-report.yaml）

name: weekly-report steps: - id: calculate-date-range skill: builtin-date-calc input: startOffsetDays: -7 endOffsetDays: 0 output: { weekStart: "$.start", weekEnd: "$.end" } - id: fetch-mrs skill: gitlab-mrs input: projectId: "123456" since: "{{ .weekStart }}" output: { mrs: "$.body" } - id: generate-report skill: markdown-report input: mrs: "{{ .mrs }}" weekStart: "{{ .weekStart }}" weekEnd: "{{ .weekEnd }}" output: { markdown: "$.markdown" } - id: send-to-wecom skill: wecom-message input: content: "{{ .markdown }}" webhookUrl: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxx"

注意builtin-date-calc是 OpenCode 内置 Skill，不用自己写，它返回{ start: "2024-10-08", end: "2024-10-14" }。

4.4 启动与验证

运行：

npm run dev

访问http://localhost:3000/dashboard，你会看到：

• Agent 列表里有weekly-reporter；
• Skills 列表里有gitlab-mrs、markdown-report、wecom-message；
• 点击weekly-reporter，能看到 State 初始为空。

现在，用 curl 手动触发一次：

curl -X POST http://localhost:3000/v1/agents/weekly-reporter/execute \ -H "Content-Type: application/json" \ -d '{"orchestration": "weekly-report"}'

几秒后，刷新 Dashboard，点击weekly-reporter的 Trace，你能看到完整的四步执行链：calculate-date-range→fetch-mrs→generate-report→send-to-wecom，每个步骤的输入/输出/耗时都清晰可见。企业微信里也会收到格式工整的周报。

最后，配置 cron（Linux）或 Task Scheduler（Windows）每早 9 点执行这个 curl 命令，全自动就完成了。整个过程，你没写一行数据库操作，没配一个 Nginx，没装一个 Docker，只用了 OpenCode 的原生能力。

5. 生产部署避坑指南：那些文档里不会写的细节

OpenCode 的 GitHub README 写得很漂亮，但实际部署到生产环境，有 5 个关键坑，我踩过三次才总结出来。这些不是 bug，而是设计取舍带来的隐含约束。

5.1 Skill 并发数限制：不是性能问题，是资源隔离问题

OpenCode 默认对每个 Skill 设置concurrency: 5（在opencode.config.ts里可调），意思是同一 Skill 最多同时执行 5 个实例。这不是为了防 DoS，而是防止一个失控的 Skill（比如死循环的while(true)）吃光所有内存。

但问题在于：这个限制是按 Skill ID 隔离的。如果你有 10 个不同的 Skill，每个都能跑 5 个并发，总共 50 个并发。但如果你把所有逻辑都塞进一个叫universal-handler的 Skill 里，那它永远只能并发 5 次。

解决方案：按业务域拆 Skill。比如gitlab-mrs和github-prs必须是两个 Skill，不能合并在一个vcs-fetcher里。我在一个监控 Agent 里，最初用一个alert-senderSkill 处理邮件/SMS/企微，结果 SMS 网关偶尔超时，拖垮了所有告警。拆成email-sender、sms-sender、wecom-sender后，问题消失。

5.2 StateStore 的 LevelDB 在容器里必须挂载卷

LevelDB 是嵌入式数据库，数据存在本地文件系统。如果你用 Docker 运行 OpenCode：

FROM node:18-alpine WORKDIR /app COPY . . RUN npm ci --only=production CMD ["npm", "start"]

不挂载卷的话，容器重启，所有 Agent State 全丢。这不是 bug，是设计：LevelDB 适合单机开发，生产必须换。

正确做法：

docker run -v $(pwd)/data:/app/data -p 3000:3000 my-opencode-image

并在opencode.config.ts里指定：

stateStore: { type: "leveldb", options: { dbPath: "/app/data/leveldb" }, },

或者，直接换 PostgreSQL：

npm install @opencode/postgres-state-store

import { PostgresStateStore } from "@opencode/postgres-state-store"; stateStore: new PostgresStateStore({ connectionString: process.env.DATABASE_URL!, }),

5.3 Orchestration YAML 的路径必须绝对匹配

opencode build会扫描orchestration/**/*.yaml，但agent.execute()时传的orchestration参数必须是文件名（不含路径）。比如：

orchestration/ ├── weekly-report.yaml └── daily-check.yaml

调用时必须是：

await agent.execute({ orchestration: "weekly-report" }); // ✅ 正确 // await agent.execute({ orchestration: "orchestration/weekly-report" }); ❌ 错误

这个规则文档里没写，但源码里src/orchestrator/loader.ts的loadOrchestration()方法明确做了path.basename(filePath, ".yaml")。我因此浪费了 2 小时 debug。

5.4 Skill 的 Error Schema 必须覆盖所有可能错误

OpenCode 的handler函数如果抛出未被errorSchema定义的错误，Orchestrator 会捕获为unknown_error，且不记录详细堆栈（出于安全考虑）。比如：

// 错误示例：errorSchema 只定义了 network_error，但 handler 可能抛出 ValidationError const errorSchema = z.object({ type: z.literal("network_error") }); handler: async () => { try { return await apiCall(); } catch (e) { if (e instanceof NetworkError) { throw { type: "network_error", message: e.message }; } // 这里如果 e 是其他类型，就会变成 unknown_error throw e; // ❌ 危险！ } }

正确做法：errorSchema必须是z.discriminatedUnion，覆盖所有分支：

const errorSchema = z.discriminatedUnion("type", [ z.object({ type: z.literal("network_error"), message: z.string() }), z.object({ type: z.literal("validation_error"), field: z.string(), value: z.any() }), z.object({ type: z.literal("unknown_error"), originalError: z.string() }), ]);

5.5 CLI 的opencode generate不会覆盖已有文件

opencode generate用于生成 Skill 模板或 Agent 框架，但它绝不会覆盖已存在的文件。比如你已经写了src/skills/my-skill/index.ts，再运行opencode generate skill --id my-skill，它会生成src/skills/my-skill/index.ts.copy，而不是覆盖原文件。

这是保护性设计，但新手常误以为“生成失败”。正确流程是：先删掉旧文件，再生成；或者，用opencode generate创建新 Skill，然后手动复制粘贴需要的代码片段。

我在团队里推广时，专门写了个脚本检查src/skills/**/index.ts是否有.copy文件，有就报警，避免遗漏。

6. OpenCode 的边界在哪里？它不做什么，比它做什么更重要

一个成熟的开源项目，其价值不仅在于“能做什么”，更在于“明确不做什么”。OpenCode 的 GitHub Issues 里，Top 10 高频请求中有 7 个被 Maintainer 明确拒绝，理由都指向同一个原则：不做垂直应用，只做水平控制面。

6.1 它不提供 LLM 推理服务

OpenCode 不内置任何模型，不打包 llama.cpp，不集成 vLLM。它的llm-callSkill 只是一个标准化的 HTTP 客户端，调用你指定的/v1/chat/completionsendpoint。这意味着：

• 你可以用本地 Ollama，也可以用 Azure OpenAI，甚至用自研的 MoE 模型服务；
• 模型升级、量化、缓存策略，全部由你自己的推理服务负责；
• OpenCode 只关心：输入是ChatCompletionRequest，输出是ChatCompletionResponse，错误是4xx/5xxHTTP 状态码。

这解释了为什么 “opencode 免费模型” 是伪需求——它压根不提供模型。它的价值是让你的模型服务能被任何 Agent 复用。

6.2 它不处理 UI 渲染逻辑

/dashboard是一个 React 应用，但它的源码在packages/dashboard/，和核心 runtime 完全分离。OpenCode 的核心包@opencode/core里没有一行 JSX。它只暴露 API 和类型定义。

这意味着：

• 你可以用 Vue 重写 Dashboard，只要调用相同的/v1/API；
• 你可以把 Dashboard 嵌入到你现有的内部管理系统里，作为 iframe；
• 你甚至可以不用 Dashboard，只用 CLI 和 curl 管理 Agent。

我在一个军工客户项目里，因为安全要求禁用 React，就直接用 Python Flask 写了个极简 UI，调用 OpenCode 的 REST API，两周就上线。

6.3 它不解决 Agent 安全沙箱问题

OpenCode 不提供代码执行沙箱（如 WASM、gVisor）。它的 Skillhandler函数运行在 Node.js 主进程中，理论上可以require('fs')读取任意文件。它的安全模型是：

• 信任边界在 Skill 层：你只安装和你信任的 Skill；
• 权限在部署层：用 Linux capability 限制容器权限（--cap-drop=ALL），或用 Kubernetes Pod Security Policy；
• 审计在可观测层：所有 Skill 调用都记录 Trace，异常行为可追溯。

这和 Docker 的安全模型一致：容器不是沙箱，而是隔离边界。OpenCode 把安全责任交还给基础设施层，而不是在应用层重复造轮子。

6.4 它不承诺实时性

OpenCode 的 Orchestration 是“尽力而为”的异步执行。agent.execute()返回的是executionId，不是最终结果。如果你想同步等待，必须轮询/v1/executions/{id}。它的设计目标是高吞吐、低延迟，不是毫秒级响应。

所以，它不适合：

• 实时游戏 AI（需要 < 50ms 响应）；
• 工业 PLC 控制（需要确定性实时）；
• 高频交易决策（需要纳秒级时序）。

它适合：

• 自动化运维（秒级）；
• 数据 ETL（分钟级）；
• 业务流程编排（小时级）。

认清这个边界，才能用对地方。把它当 Redis 用，会失望；当 Kubernetes 用，它很稳。

我在一个物联网项目里，试图用 OpenCode 控制温控器开关，结果发现 MQTT 发布延迟波动太大，改用专用的实时框架后，问题解决。OpenCode 的定位，从来就不是替代实时系统，而是统管非实时的智能体协作。

7. 我的实际经验：如何用 OpenCode 构建可维护的 Agent 系统

最后，分享我在三个不同规模项目里沉淀下来的实战心法。这些不是文档里的“最佳实践”，而是血泪教训换来的直觉。

7.1 Skill 的颗粒度：宁小勿大，小到不能再小

一开始，我总想写“全能 Skill”，比如一个>