ZCode 源码解读
逐层拆读智谱开源的 AI 编程工作台“ZCode”的 TypeScript 源码——同一个 Agent 运行时驱动终端 TUI、Electron 桌面端与 Web 三种宿主，自研回合循环、权限与钩子、动态工作流与 ZCode Protocol，一边讲怎么用，一边讲怎么实现。
ZCode 是智谱开源的 AI 编程工作台：同一个产品有三种用法——Electron 桌面应用、浏览器里的 Web 界面，以及终端里的 zcode 命令。三者背后是同一个 Agent 运行时：在终端里它和界面跑在同一个进程；桌面端和 Web 服务端则把它作为子进程拉起，经标准输入输出上的 ZCode Protocol 驱动它。模型默认接智谱的 GLM Coding Plan，也可以接 Kimi、DeepSeek、OpenAI、Anthropic 等各家的 API。
这份源码没有借用任何开源 Agent 的循环：回合循环、工具执行器、权限、压缩、子 Agent 都是自己写的；最有特色的是动态工作流——让模型用 TypeScript 写一段编排脚本，经编译器做类型检查和静态分析后，在沙箱子进程里调度一群子 Agent 并行干活。整个项目用 TypeScript 写成，非测试代码约 84 万行，其中 Agent CLI 与运行时约 29 万行，桌面、Web 与共享界面约 54 万行。
这个专栏把它逐层拆开读。
源码基准
本专栏所有引用以下述快照为准：
| 项 | 值 |
|---|---|
| 仓库 | github.com/zai-org/ZCode |
| commit | 872ad960de7ec172591f7e1952f7849229f94521（main 分支，提交说明为 “feat: open source”；此前只有一个空的初始提交，没有任何 tag） |
| 版本 | 产品 3.14.0（根 package.json）；Agent CLI 0.16.9（apps/zcode-cli/package.json） |
| 快照日期 | 2026-09-21 |
| 许可 | 第一方代码 Apache-2.0；第三方组件保留各自许可，清单见 THIRD-PARTY-NOTICES.md |
| 运行要求 | Node.js 24.14.0、pnpm 10.33.2（mise.toml） |
所有路径都相对仓库根，例如 apps/zcode-cli/packages/core/src/runtime/methods/turn-loop.ts。源码是 2026-09-21 以一个提交整体公开的，此前的开发历史不在仓库里。
规模口径：git 跟踪的 .ts、.tsx、.mts、.cts 文件，排除测试目录与 *.test.*、*.spec.*，用 wc -l 数物理行。全仓 3894 个文件、842723 行；Agent 一侧的 apps/zcode-cli 1354 个文件、291458 行，桌面与 Web 一侧的 packages/ 2457 个文件、543996 行，其中共享界面 packages/ui 一个包就有 322555 行。各包的分工见仓库全景。
读者预设：默认你会读 TypeScript（async、泛型、联合类型、interface），不熟的语言点会在关键处就地补一句。读过《从 LLM 到 Coding Agent》会更顺，但不是硬前提。
这个专栏怎么读
每一章尽量走两条线：
- 怎么用——这个功能在
zcode或桌面端里长什么样、怎么配置； - 怎么实现——翻到对应包的源码，看它在底层到底怎么做。
侧重结构与数据流：讲清“一件事经过哪些包、数据怎么流、边界契约是什么”，而不是逐行贴代码——关键处才引一小段源码点睛。本书以 Agent 运行时为主线，桌面端与 Web 讲到它们怎样驱动这个运行时为止。README、仓库文档、代码注释与代码不一致时，一律写代码的实际行为，并在正文注明。
和站内其他专栏的关系
| 专栏 | 视角 |
|---|---|
| 《从 LLM 到 Coding Agent》 | 教学最小实现：一个 Coding Agent 在裸 LLM API 之上该做哪些事 |
| 《Claude Code 中文手册》 | ZCode 的生命周期钩子沿用 Claude Code 的事件名，桌面端还能导入 Claude Code 的本地会话 |
| 《OpenCode 源码解读》、《MiMo Code 源码解读》 | 另一种 TypeScript 生产实现，以及在它之上的二次开发 |
| 《MiniMax Code 源码解读》、《Kimi Code 源码解读》 | 同为国内大模型厂商的终端 Agent，都借用了 pi 的部分代码；ZCode 的 Agent 循环与终端界面都没有沿用这些上游 |
| 《Grok Build 源码解读》 | Rust 生产实现：xAI 的终端 Agent 怎么做 |
| 本专栏 | 一个运行时、三种宿主：终端、桌面、Web 共用同一个自研 Agent 运行时，靠一套线协议解耦 |
它有什么特别的
读之前先知道这份源码值得看的地方：
- 一个运行时、三种宿主。Agent 运行时住在
apps/zcode-cli，桌面端与 Web 服务端的包一个都不依赖它，两边只共用packages/下几个基础包（协议类型、Provider 配置等）：TUI 在进程内直接创建运行时，桌面与 Web 把它当子进程，经 ZCode Protocol V4 通信（一条消息的旅程、ZCode Protocol V4）。 - 端口与适配器。核心包
core的文件、网络、子进程与存储访问大多经由contracts声明的端口，由adapters实现、bootstrap组装；一个会话的AgentRuntime把几十个模块里的 187 个方法“安装”到同一个类上（AgentRuntime、bootstrap）。 - 为长程任务设计的回合循环。不以工具调用次数硬停，靠上下文压缩、输出截断续写、流中断恢复、重复调用检测与“压缩后迅速又满”的保护来收住失控（回合循环、一次模型请求、上下文压缩）。
- 动态工作流。模型写的 TypeScript 编排脚本先过类型检查、taint 分析与 JSON Schema 合成，再放进 vm 沙箱子进程执行，靠日志回放做到可恢复；另有一套固定八阶段的专家工作流（动态工作流、专家工作流）。
- 把副作用摊开讲。四种权限模式、七个生命周期钩子、按声明摘要信任的工作区钩子；根目录的
NOTICE.md逐项写明了哪些操作会发出网络请求、数据落在哪里，也直说共享的 Agent 执行适配器不提供操作系统级沙箱（权限、钩子、执行边界）。 - 桌面与远程。Electron 的 Main、Host、Renderer 三层分工，SSH 与 WSL 远程工作区，手机远控复用桌面已有的会话宿主（桌面应用、远程工作区与手机远控）。
路线图
- 第 0 部分 · 导论与全景——它是什么、仓库全景、怎么读这份源码、一条消息的旅程。
- 第 1 部分 · Agent 运行时内核——AgentRuntime 与端口、bootstrap 组装、输入受理、回合循环、一次模型请求、会话事件。
- 第 2 部分 · 上下文、压缩与记忆——系统提示词与提醒、上下文压缩、项目记忆。
- 第 3 部分 · 工具系统——工具契约、执行器、文件工具、Web 工具、Bash、执行边界、交互类工具。
- 第 4 部分 · 权限与钩子——权限模式与规则、生命周期钩子与工作区信任。
- 第 5 部分 · 模型与账号——Provider 规则与模型目录、模型适配层、账号与 Coding Plan。
- 第 6 部分 · 多 Agent 与长程任务——子 Agent、目标模式、后台任务、定时与闲时任务。
- 第 7 部分 · 工作流——专家工作流，以及动态工作流的编译器、引擎与工具链。
- 第 8 部分 · 扩展机制——技能与自定义命令、插件与官方市场、MCP、node_repl 与浏览器控制。
- 第 9 部分 · 会话、存储与可观测性——SQLite 会话库、检查点与分叉、遥测与调试。
- 第 10 部分 · 终端与协议——命令行入口与打包、终端界面、ZCode Protocol V4。
- 第 11 部分 · 桌面、Web 与远程——Electron 桌面端、Web 与服务端、远程工作区与手机远控，以及全书回顾。
准备好了，就从 ZCode 是什么 开始。