夜雨聆风如果你用过 OpenCode、Claude Code 这类 AI 编程工具，多半有过这种体验：你说一句"帮我加个登录功能"，它就开始自己翻代码、建文件、改逻辑、跑测试，像一个不用手把手教的同事坐在旁边。
这近乎魔法的体验背后，藏着一个值得拆开看的问题：大模型本质上只会"说话"，它是怎么学会读写文件、执行命令、修改代码的？
答案藏在这些工具的源代码里。这个系列打开 OpenCode 的源代码，把"你按下回车，到模型开始作答"的全过程一步步拆给你看。
读懂这些原理，至少有三层价值。
把工具用得更好。 当你明白模型看到的提示词是怎么拼出来的、工具是怎么被调用的、对话太长时它怎么悄悄"丢掉"前面的内容，你就知道怎么给它更有效的指令，也知道它会在什么地方、因为什么而犯错。
看懂 AI Agent 的设计骨架。 先解释一个词：Agent（智能体）指的是"能自己调用工具、分多步完成任务的 AI 系统"。OpenCode 自己不实现任何大模型，它做的是把大模型包装成一个能动手干活的 Agent。这套包装方式——工具调用循环、上下文压缩、权限确认、流式响应——是当下 AI Agent 产品的共同骨架。OpenCode 是一个高完成度的开源实现，读懂它，等于读懂了这一类产品的底层逻辑。
纯粹的好奇心。 一个能自己改代码的系统，内部到底怎么运转？这种"打开黑盒"的快乐，本身就值得。
所有分析基于 OpenCode 1.18.16 的源代码（仓库 dev 分支），只反映这个版本的真实实现，不做新旧版本对比。
读这个系列之前，先建立一个认识：OpenCode 自己不会写代码，真正写代码的是背后的大模型。OpenCode 做的事，是当一个极其称职的调度员——把你的一句话，翻译成大模型能理解的一系列指令，再把大模型的回答转化成实际的文件读写和命令执行。
这个调度过程可以概括成一个循环，它是整个系统的心脏：
这个循环有个名字，叫 agent loop（智能体循环）。循环之外的所有东西——提示词怎么拼、工具怎么定义、用哪个 Agent 配置、权限怎么确认、对话太长怎么压缩——都是为这个循环服务的。记住这张图，读后面的内容就不会迷路。
1.18.16 正处在一个内部重构的过渡期，代码里同时存在两套会话（session）实现：
packages/opencode/src/session/，叫 V1 栈。packages/core/src/session/runner/，叫 V2 栈。这个系列以 V1 栈为主线，因为它才是你运行 OpenCode 时实际执行的代码。原因很简单：文档要对应真实运行的行为，不能把一个还没上线的实现描述成现状。
这个系列一共 13 篇（不含导读），按"先建立全局、再拆解零件、最后回到整体、再讲专项"的顺序编排。建议按顺序读，因为后面会引用前面建立的认知。
第一阶段（01） 先建立全局地图。第二阶段（02—05） 逐个拆开循环依赖的核心组件。第三阶段（06） 把零件重新组装成主循环，这是整个系列的高潮。第四阶段（07—10） 讲怎么扩展系统：先讲 4 种组件的运行时机制，再分别讲 Skills/Commands、MCP、Plugins 怎么编写。第五阶段（11—13） 讲三个专项：长对话压缩、操作权限确认、代码理解，可按兴趣选读。
代码引用：涉及源代码的地方都标注 文件路径:行号，路径相对于 OpenCode 仓库根目录。比如 packages/opencode/src/session/prompt.ts:1081 表示 prompt.ts 的第 1081 行。可以对照源码一起读。
术语：每个术语第一次出现时会解释，不假设你已经知道。
事实与解释：代码里能直接看到的行为作为事实陈述；涉及"为什么这么设计"的推断会明确标注，不把推断包装成定论。
例子：讲抽象机制时，会用一个具体的、能追踪的例子走一遍。
下一篇，我们从全局开始：先画出一次对话的完整旅程，再拆开代码的分层。