使用 SDK
基于官方 OpenCode SDK 教程，面向新手讲清 SDK 适合什么集成场景、server/client 怎么理解、结构化输出和错误处理怎么验收。
OpenCode JS/TS SDK 是 opencode server 的类型安全客户端。它适合把 OpenCode 接进你自己的工具、后台服务、自动化平台或产品界面。
新手先记住：SDK 不是用来替代 TUI 的第一入口。你已经能在 TUI / CLI 里稳定完成任务后，才应该考虑 SDK。
先理解：SDK 解决什么问题
TUI 解决“人和 OpenCode 交互”。
CLI 解决“从命令行触发任务”。
Server 解决“OpenCode 对外提供可调用 API”。
SDK 解决“你的 JS/TS 程序类型安全地调用 server”。
如果你只是想手动改代码，用 TUI。如果你只是想在脚本里跑一次任务，先看 CLI。如果你要让内部系统创建 session、发送 prompt、读取结果、做结构化输出、集成到业务流程里，才用 SDK。
怎么判断两种使用方式
第一种是 SDK 帮你启动 server，并返回 client。这适合本地工具、桌面辅助脚本和一次性集成实验。
第二种是 client-only，连接已经运行的 opencode server。这适合已有后台服务、共享 server、容器化部署或你想自己控制 server 生命周期的场景。
新手先用第一种验证 API 调用，再用第二种做真实集成。不要一开始就把 server 生命周期、认证、端口、日志、错误处理全混在一起。
配置怎么理解
SDK 可以传入 config 覆盖或补充本机 opencode.json。这适合测试不同模型、切换 provider、限制工具或为某个集成定制行为。
但不要把凭据塞进 SDK 代码。provider key 仍然应该由 /connect、环境变量或安全凭据系统管理。
如果 SDK 代码要进仓库，配置里只放可公开的模型名、provider 名和行为策略，不放 token。
结构化输出什么时候用
官方 SDK 支持通过 JSON Schema 请求结构化输出。它适合让下游程序消费结果，例如风险报告、项目元数据、发布摘要、分类标签、检查清单。
结构化输出不是为了让回答更好看，而是为了让程序能稳定解析。
新手写 schema 时要简单：字段少、描述清楚、required 明确。复杂嵌套 schema 会增加模型失败和重试成本。
错误处理要先设计
SDK 集成一定会遇到错误：server 启动失败、端口被占、模型请求失败、session id 无效、结构化输出校验失败、网络超时。
新手不要只写 happy path。至少要处理：
- server 是否启动成功。
- client 是否连到正确 base URL。
- prompt 是否返回错误对象。
- 结构化输出是否失败并需要重试。
- 操作结束后 server 是否需要关闭。
新手常见坑
- TUI 还没跑通就写 SDK：问题会被包装层掩盖。
- 把 SDK 当模型 API：它控制的是 OpenCode server，不只是调用 LLM。
- 不管理 server 生命周期：本地残留进程、端口冲突、测试互相影响。
- 把 API key 写进代码：SDK 示例里出现 config，不代表凭据可以进仓库。
- schema 太复杂：结构化输出频繁失败，最后又回到自然语言解析。
- 忽略 TypeScript 类型：SDK 的价值之一就是让 API shape 在开发时暴露出来。
一个稳妥的集成路线
第一步，在 TUI 里确认 provider、model、permissions 和项目配置都能工作。
第二步，用 SDK 做一个只读健康检查：连接 server，确认版本和当前项目。
第三步，创建一个最小 session，发送一个只读 prompt，读取结果。
第四步，加入结构化输出，让结果变成固定字段。
第五步，再接入业务系统，例如 PR 检查、内部 dashboard、任务队列或发布流程。
怎么验收
你能说明 server 是 SDK 启动的，还是外部已运行的。
你能在失败时区分 server 未启动、client base URL 错误、模型失败、权限失败和结构化输出失败。
你能证明 SDK 代码里没有 key、token 和私有配置。
你能用 TypeScript 类型约束输入输出，而不是到处写 any。
你能在任务结束后关闭本地 server，避免测试和开发环境残留。