- 文集信息
- 目录大纲
- 最新文档
- 知识宇宙
文集详情
文集导读
OpenCode · 技术教程
开源 AI 编码 Agent 的引擎原理——从分层架构到 Context Epoch,讲透一个工业级 Coding Agent 的内核设计
这本教程讲什么
本教程是开源项目「OpenCode」的体系化中文教程。OpenCode 是一个开源的 AI 编码 Agent(AI coding agent),与 Claude Code、Cursor、Windsurf 同属一类工具——它能理解你的代码库、读写文件、执行命令、搜索资料、管理任务。与那些闭源产品不同的是,它把整套内核设计摊开在阳光下:你怎么用它,就怎么理解它,甚至怎么改造它。
它有八种运行形态(终端 TUI、桌面应用、浏览器 Web、无头 HTTP 服务器、嵌入式 SDK、MCP 服务器、ACP 服务、GitHub CI),底层用一套基于效应式编程(Effect)构建的分层内核统一支撑。它的硬核之处不在「能用」,而在「为什么这样设计」——为什么把 Schema、协议、服务端、领域核心、LLM 抽象分成五层?为什么一个会话的工具调用循环要从单体演进到事件溯源?为什么给模型的初始指令要做成一套可演化的「上下文纪元(Epoch)」?这些才是本教程要讲的东西。
本教程不教你怎么点按钮,而是带你读它的引擎图纸。每章都回答「它解决什么问题、背后的原理是什么、为什么这样设计」,讲到「读完能向别人讲清楚」的程度。
三章学习路径一览
本教程按「跑起来 → 看懂架构 → 逐子系统拆解 → 拔高」的递进逻辑组织,共十三章加一个附录:
第 1 章 环境准备与首次跑通 ── 5 分钟拿到第一次响应 安装 · 多形态启动 · 最小示例 · 首次会话 │ 第 2 章 整体架构与分层设计 ── 建立全局地图(承前启后) 六层分层 · 依赖铁律 · 一次请求的跨层旅程 │ 第 3 ~ 6 章 外围与抽象层 ── 入口、Agent、工具、LLM 多形态入口 · Agent权限 · 工具系统三层抽象 · LLM多Provider │ 第 7 ~ 9 章 会话核心与上下文 ── 全书最硬核 Session执行引擎 · System Context/Epoch · 上下文压缩 │ 第 10 ~ 11 章 扩展生态 ── 如何接入与扩展 MCP外部能力 · 插件/技能/斜杠命令 │ 第 12 ~ 13 章 工程化与二次开发 ── 从会用到能改 配置与分发 · 客户端契约 · 嵌入式SDK · 贡献流程 │ 附录 A 术语表 · 速查 · 排错
如果你想快速试用,看第 1 章就够;想理解整体设计,第 2 章是地图;想知道一次对话在内核里怎么流转,重点读第 7 章;对「怎么管理给模型的上下文」感兴趣,第 8、9 章是全书最深的部分。
章节目录
第 1 章 环境准备与首次跑通
技术栈与环境要求、安装方式、多形态启动入口、最小可运行示例(非交互跑一次)、首次会话与产物观察。读完你能把 OpenCode 跑起来并得到第一次 Agent 响应。
第 2 章 整体架构与分层设计(全书地图)
一句话定位与能力边界、六层分层总览(Schema→协议→服务端→领域核心→LLM→应用层)、依赖方向与「禁止反向依赖」铁律、一次完整请求的跨层旅程。读完你能画出整张架构图并解释每层的存在理由。
第 3 章 多形态入口与进程模型
八种入口矩阵与各自适用场景、平台二进制分发(按操作系统×架构×libc×CPU 指令集选包)、serve 模式与无头 HTTP 服务器、嵌入式 SDK 的进程内路由器。读完你能解释同一套内核如何支撑八种形态。
第 4 章 Agent 体系与权限模型
内置 Agent(build/plan/general/explore 等)职责图谱、Agent 定义结构与动态生成、权限规则矩阵(allow/ask/deny)、多层规则合并与求解算法。读完你能定制 Agent 并读懂权限判定逻辑。
第 5 章 工具系统:从定义到注册运行时
工具定义抽象与参数 Schema 编译、注册表与按模型过滤(如某模型系列用补丁式工具而非读写工具)、工具上下文与权限询问、LLM 侧工具运行时的输出边界控制。读完你能新增一个工具并理解它如何被模型调用。
第 6 章 LLM 抽象层与多 Provider 集成
Provider 门面模式与路由(Route)抽象、协议/分帧/传输分离、统一事件流、提示缓存(Prompt Caching)三断点策略与成本数学、三档可移植性逃生口。读完你能新增一个 Provider 并理解跨厂商差异如何被抹平。
第 7 章 Session 核心:执行引擎的演进(硬核)
单体循环(V1)的系统提示组装与流式处理、事件溯源式执行(V2)的「持久化录入 vs 模型执行」分离、回合协调器与并发合并、Location 作用域与 Session 移动。读完你能讲清一次对话在内核里的完整编排。
第 8 章 System Context 与 Context Epoch(全书最深)
上下文源(Context Source)代数与统一组合、基准/快照/纪元三件套、对话中途系统消息与安全回合边界、协调(reconcile)状态机。读完你能解释给模型的初始指令如何安全演化。
第 9 章 上下文压缩与记忆管理
触发条件与额度估算、隐藏检查点(hidden checkpoint)滚动摘要、跨压缩边界的约束、压缩与新纪元的衔接。读完你能解释超过模型窗口时内核如何自救而不破坏厂商签名。
第 10 章 MCP 集成与外部能力扩展
三种传输方式(stdio/SSE/流式 HTTP)、OAuth 流程与浏览器认证、MCP 工具如何进入注册表并受权限约束、把 OpenCode 自身暴露为 MCP 服务器。读完你能让 Agent 安全、标准化地访问任意外部资源。
第 11 章 插件、技能与斜杠命令
插件对外 API 契约(用模式校验定义工具、事件钩子)、技能(Skill)作为上下文源的渐进式披露、斜杠命令模板、自定义工具与项目级配置目录。读完你能区分四类扩展点各自的边界并协同使用。
第 12 章 配置体系与多平台分发
配置层级与合并优先级、工作区编排、单文件构建脚本与平台分包、可观测性(OpenTelemetry 贯穿)。读完你能解释配置如何分层合并以及单文件可执行如何跨平台产出。
第 13 章 客户端契约、嵌入式 SDK 与二次开发
SDK 契约中间表示与双发射器、Promise 零效应客户端 vs 效应富投影客户端、嵌入式 SDK 的进程内客户端、贡献流程与风格规范。读完你能理解服务端 API 如何自动生成客户端并参与贡献。
附录 A 术语表 · 命令速查 · 常见报错排查
全书术语词典(中英对照)、高频命令与接口速查、报错→原因→排查三列表。
适合读者
本教程适合想读懂一个工业级 AI 编码 Agent 内核的工程师与研究者:
- 用过 Claude Code / Cursor,想知道底层怎么实现的开发者
- 想二次开发或贡献代码的开源爱好者
- 在做 AI Agent 产品、想借鉴工程设计的架构师
- 对效应式编程(Effect)在大型项目里如何落地感兴趣的人
- 研究大模型上下文管理、工具调用、会话持久化的研究者
前置知识:
- 熟悉 TypeScript 或任一静态类型语言
- 了解「大语言模型(LLM)」「API 调用」「流式响应」的基本概念
- 对命令行、HTTP、JSON 有基本经验
- 不要求读过效应式编程——本教程会在用到时点拨,但建议边读边查
目录大纲
最新文档
知识宇宙
正在加载知识图谱...