OpenCode · 第 13 章客户端契约、嵌入式 SDK 与二次开发

文档摘要

OpenCode · 第 13 章客户端契约、嵌入式 SDK 与二次开发章节摘要:OpenCode 的服务端 API 不是手写客户端的——它用一套契约驱动的代码生成(codegen):服务端的具体 HTTP API 是权威来源,被编译成一份中间表示(SDK Contract IR),再由两个独立的发射器生成两种客户端——一种是返回 Promise、零效应依赖的轻量客户端(给不想用效应式编程的用户),另一种是返回效应流、保留全部类型信息的富投影客户端(给深度集成的用户)。最妙的是嵌入式 SDK:它不起 HTTP 端口,而是在进程内用内存级客户端跑同一套路由、中间件、编解码——保留了完整的 HTTP 编码边界,只是没有网络 I/O。

OpenCode · 第 13 章客户端契约、嵌入式 SDK 与二次开发

章节摘要:OpenCode 的服务端 API 不是手写客户端的——它用一套契约驱动的代码生成(codegen):服务端的具体 HTTP API 是权威来源,被编译成一份中间表示(SDK Contract IR),再由两个独立的发射器生成两种客户端——一种是返回 Promise、零效应依赖的轻量客户端(给不想用效应式编程的用户),另一种是返回效应流、保留全部类型信息的富投影客户端(给深度集成的用户)。最妙的是嵌入式 SDK:它不起 HTTP 端口,而是在进程内用内存级客户端跑同一套路由、中间件、编解码——保留了完整的 HTTP 编码边界,只是没有网络 I/O。本章要把这三件事讲透:契约如何从服务端流向客户端、两种客户端各自的取舍、嵌入式 SDK 如何让 OpenCode 嵌进任意应用,最后落到贡献流程——当你想改它时,该遵循哪些风格规范。这是全书最后一章,它把「读懂」推向「能改」。

学习目标

阅读完本章,你应当能够:

描述契约驱动的代码生成:服务端 HTTP API 如何被编译成 SDK 契约中间表示(IR)。
区分两种客户端:Promise 零效应客户端(轻量、同步构造、返回异步迭代)与效应富投影客户端(深度集成、保留全部类型)各自的取舍与适用场景。
解释嵌入式 SDK 的妙处:进程内内存级客户端跑同一套路由,保留 HTTP 编码边界却跳过网络。
讲清贡献流程:加 Provider、加工具、改内核时该遵循哪些风格规范、依赖方向、测试要求。
把 OpenCode 嵌进自己的应用,或为它贡献一个新特性。

核心概念速览

一句话总结:服务端 API 是单一事实来源——codegen 把它编译成两种客户端覆盖不同集成深度,嵌入式 SDK 则用「跳过网络但保留编码边界」的妙笔让内核能进程内复用;读懂这套契约,你就能把 OpenCode 嵌进任何地方。

子章节导航

01 SDK 契约中间表示与双发射器

讲契约驱动 codegen 的全流程:服务端的具体 HTTP API 如何被编译成中间表示(IR,保留编码/解码投影与传输元数据),再由两个独立发射器生成两种客户端。重点说明为什么用单一事实来源(避免客户端与服务端漂移)。

02 Promise 客户端 vs 效应客户端

讲两种客户端的取舍:Promise 客户端同步构造、返回异步迭代、用统一错误类型区分领域/基础设施错误,适合不想引入效应式编程的用户;效应客户端保留全部类型信息、与效应生态深度集成,适合重度用户。给出选型建议。

03 嵌入式 SDK 的进程内客户端

本章妙笔。讲嵌入式 SDK 如何在进程内用内存级客户端跑同一套路由、中间件、编解码——保留完整的 HTTP 编码边界(所以行为与起服务器一致),只是没有网络 I/O(所以更快、更省)。讲它的适用场景:把 OpenCode 嵌进桌面应用、CI 脚本、其他 Agent。

04 贡献流程与风格规范

讲当你想改 OpenCode 时该遵循什么:加 Provider 该走哪几步、加工具该符合什么契约、改内核该守哪些依赖方向铁律、测试要求(单元 + 录像带 + 端到端)。这一节把全书从「读懂」推向「能改」。

子章节之间的逻辑关系

本章遵循「契约 → 客户端 → 嵌入 → 贡献」的从读到改路径:


契约 IR (01)   ──客户端如何从服务端生成
   │
   ▼
两种客户端 (02) ──不同集成深度的选择
   │
   ▼
嵌入式 SDK (03) ──进程内复用的妙笔
   │
   ▼
贡献流程 (04)  ──如何参与改进它
   │
   ▼
附录 A:全书检索入口

前三节是「如何集成与使用」,最后一节是「如何反哺与改进」。理解了全部四节,你就完成了从读者到参与者的转变——这正是体系化教程的终点。

前置知识与后续延伸

前置知识:

第 3 章多形态入口(理解 serve 模式与嵌入式 SDK 的关系)
第 2 章分层架构(理解契约所在的层与依赖方向)
第 11 章扩展点(理解贡献工具/插件的基础)
对「代码生成」「契约」的基本概念

本章为后续学习奠定的基础:

契约驱动 codegen 是理解 OpenCode 长期可维护性的关键
嵌入式 SDK 为把 OpenCode 集成进任意应用提供了入口
贡献流程让读者能真正参与开源协作

本章是全书正文最后一章。读完后建议翻阅附录 A 的术语表与速查,把它们作为日常工作的检索入口。若你想了解 OpenCode 在更大的产品形态里如何被使用,可关注其姐妹项目——一个基于该引擎构建的桌面应用与能力分享平台,但那是另一本书的主题。

OpenCode · 第 13 章 客户端契约、嵌入式 SDK 与二次开发

文档摘要