# ZCode 源码解读

> 逐层拆读智谱开源的 AI 编程工作台“ZCode”的 TypeScript 源码——同一个 Agent 运行时驱动终端 TUI、Electron 桌面端与 Web 三种宿主，自研回合循环、权限与钩子、动态工作流与 ZCode Protocol，一边讲怎么用，一边讲怎么实现。

- 作者：David（道雾轩）
- 最后更新：2026-09-21
- 原文：https://daiw.org/manual/zcode
- 转载与引用：请注明出处并附原文链接（https://daiw.org/about/copyright）

[ZCode](https://github.com/zai-org/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](https://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 行。各包的分工见[仓库全景](https://daiw.org/manual/zcode/monorepo-map)。

<Callout type="info">
  **读者预设**：默认你会读 TypeScript（`async`、泛型、联合类型、`interface`），不熟的语言点会在关键处就地补一句。读过[《从 LLM 到 Coding Agent》](https://daiw.org/manual/llm-to-agent)会更顺，但不是硬前提。
</Callout>

## 这个专栏怎么读

每一章尽量走**两条线**：

- **怎么用**——这个功能在 `zcode` 或桌面端里长什么样、怎么配置；
- **怎么实现**——翻到对应包的源码，看它在底层到底怎么做。

侧重**结构与数据流**：讲清“一件事经过哪些包、数据怎么流、边界契约是什么”，而不是逐行贴代码——关键处才引一小段源码点睛。本书以 Agent 运行时为主线，桌面端与 Web 讲到它们怎样驱动这个运行时为止。README、仓库文档、代码注释与代码不一致时，一律写代码的实际行为，并在正文注明。

## 和站内其他专栏的关系

| 专栏 | 视角 |
| --- | --- |
| [《从 LLM 到 Coding Agent》](https://daiw.org/manual/llm-to-agent) | **教学最小实现**：一个 Coding Agent 在裸 LLM API 之上该做哪些事 |
| [《Claude Code 中文手册》](https://daiw.org/manual/claude-code) | ZCode 的生命周期钩子沿用 Claude Code 的事件名，桌面端还能导入 Claude Code 的本地会话 |
| [《OpenCode 源码解读》](https://daiw.org/manual/opencode)、[《MiMo Code 源码解读》](https://daiw.org/manual/mimo-code) | 另一种 TypeScript 生产实现，以及在它之上的二次开发 |
| [《MiniMax Code 源码解读》](https://daiw.org/manual/minimax-code)、[《Kimi Code 源码解读》](https://daiw.org/manual/kimi-code) | 同为国内大模型厂商的终端 Agent，都借用了 pi 的部分代码；ZCode 的 Agent 循环与终端界面都没有沿用这些上游 |
| [《Grok Build 源码解读》](https://daiw.org/manual/grok-build) | **Rust 生产实现**：xAI 的终端 Agent 怎么做 |
| 本专栏 | **一个运行时、三种宿主**：终端、桌面、Web 共用同一个自研 Agent 运行时，靠一套线协议解耦 |

## 它有什么特别的

读之前先知道这份源码值得看的地方：

- **一个运行时、三种宿主**。Agent 运行时住在 `apps/zcode-cli`，桌面端与 Web 服务端的包一个都不依赖它，两边只共用 `packages/` 下几个基础包（协议类型、Provider 配置等）：TUI 在进程内直接创建运行时，桌面与 Web 把它当子进程，经 ZCode Protocol V4 通信（[一条消息的旅程](https://daiw.org/manual/zcode/message-lifecycle)、[ZCode Protocol V4](https://daiw.org/manual/zcode/zcode-protocol)）。
- **端口与适配器**。核心包 `core` 的文件、网络、子进程与存储访问大多经由 `contracts` 声明的端口，由 `adapters` 实现、`bootstrap` 组装；一个会话的 `AgentRuntime` 把几十个模块里的 187 个方法“安装”到同一个类上（[AgentRuntime](https://daiw.org/manual/zcode/agent-runtime)、[bootstrap](https://daiw.org/manual/zcode/bootstrap-assembly)）。
- **为长程任务设计的回合循环**。不以工具调用次数硬停，靠上下文压缩、输出截断续写、流中断恢复、重复调用检测与“压缩后迅速又满”的保护来收住失控（[回合循环](https://daiw.org/manual/zcode/turn-loop)、[一次模型请求](https://daiw.org/manual/zcode/model-step)、[上下文压缩](https://daiw.org/manual/zcode/compaction)）。
- **动态工作流**。模型写的 TypeScript 编排脚本先过类型检查、taint 分析与 JSON Schema 合成，再放进 vm 沙箱子进程执行，靠日志回放做到可恢复；另有一套固定八阶段的专家工作流（[动态工作流](https://daiw.org/manual/zcode/dwf-compiler)、[专家工作流](https://daiw.org/manual/zcode/expert-workflow)）。
- **把副作用摊开讲**。四种权限模式、七个生命周期钩子、按声明摘要信任的工作区钩子；根目录的 `NOTICE.md` 逐项写明了哪些操作会发出网络请求、数据落在哪里，也直说共享的 Agent 执行适配器不提供操作系统级沙箱（[权限](https://daiw.org/manual/zcode/permission)、[钩子](https://daiw.org/manual/zcode/hooks)、[执行边界](https://daiw.org/manual/zcode/exec-boundary)）。
- **桌面与远程**。Electron 的 Main、Host、Renderer 三层分工，SSH 与 WSL 远程工作区，手机远控复用桌面已有的会话宿主（[桌面应用](https://daiw.org/manual/zcode/desktop)、[远程工作区与手机远控](https://daiw.org/manual/zcode/remote)）。

## 路线图

- **第 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 是什么](https://daiw.org/manual/zcode/what-is-zcode) 开始。

## 本专栏篇目

- [ZCode 源码解读](https://daiw.org/manual/zcode.md): 逐层拆读智谱开源的 AI 编程工作台“ZCode”的 TypeScript 源码——同一个 Agent 运行时驱动终端 TUI、Electron 桌面端与 Web 三种宿主，自研回合循环、权限与钩子、动态工作流与 ZCode Protocol，一边讲怎么用，一边讲怎么实现。

### 第 0 部分 · 导论与全景

- [ZCode 是什么](https://daiw.org/manual/zcode/what-is-zcode.md): 智谱的 AI 编程工作台：桌面应用、Web 与终端三种形态，Coding Plan 登录与自带模型，命令行子命令、权限模式、斜杠命令与快捷键，数据放在哪里，以及它和 Claude Code、Codex、OpenCode 的兼容之处。
- [仓库全景：两层 workspace 与依赖方向](https://daiw.org/manual/zcode/monorepo-map.md): ZCode 仓库由产品一侧的 packages 与 Agent 一侧的 apps/zcode-cli 两层 workspace 组成：三十多个包各管什么、规模多大、依赖怎样单向流动，两层之间为何只靠一条进程边界相连，以及把边界写成规则的架构治理工具。
- [怎么读这份源码](https://daiw.org/manual/zcode/reading-the-source.md): 怎样把 ZCode 的桌面端、Web 与 Agent CLI 分别跑起来，各层有哪些检查命令，开源仓库为何几乎不带测试、formal-proof 又是什么，两份 AGENTS.md 立了哪些规矩，以及一条沿 Agent 主线的阅读路线。
- [一条消息的旅程](https://daiw.org/manual/zcode/message-lifecycle.md): 从回车到屏幕：一条输入在终端与桌面两条路上各经过哪些层——命令中心与 ZCodeApp、受理与命令队列、回合准备与循环、模型流式与工具执行、事件与持久化，最后怎样回到界面；两条路在哪里汇合、又在哪里分开。

### 第 1 部分 · Agent 运行时内核

- [AgentRuntime：端口、依赖与方法装配](https://daiw.org/manual/zcode/agent-runtime.md): 一个会话对应一个 AgentRuntime：它身上的八十多个状态字段、构造时注入的四十九项依赖，近百个方法文件怎样用声明合并加原型安装装到同一个类上，AgentRuntimeInternal 的作用，trace 上下文如何从根一路传到模型请求，以及 core 包对外导出了什么。
- [bootstrap：把运行时拼起来](https://daiw.org/manual/zcode/bootstrap-assembly.md): bootstrap 是 Agent CLI 的装配层：配置分几层、怎样合并，主配置文件有哪些键，数据目录各放什么，一次 createZCodeApp 怎样造出 AgentRuntime、注入哪些端口，模型怎样选，会话怎样新建与恢复，各扩展机制在哪里接入，以及启动日志、日志保留与资源采样的数字。
- [输入受理、命令队列与引导](https://daiw.org/manual/zcode/prompt-admission.md): 一条新输入在会话空闲与忙碌时分别怎样被 AgentRuntime 受理：PromptAdmissionReceipt 的三种结果，运行时命令队列的结构与消费时机，引导（guide）与排队（queue）在回合的哪个边界被消费，控制类回合，提问的自动继续，以及输入意图怎样一次性落进账本与消息。
- [回合循环与 TurnMachine](https://daiw.org/manual/zcode/turn-loop.md): 一个回合从入队、准备到收尾的全过程：runRegularTurnLoop 每轮做什么，何时 continue、何时 break，TurnMachine 记下哪些阶段；重复工具调用检测与“长程优先”原则在代码里的样子，自动化与闲时回合为何在请求边界藏起写工具。
- [一次模型请求：流式、工具并发与恢复](https://daiw.org/manual/zcode/model-step.md): runModelBackedTurnStep 的内部：请求怎样发出、输出预算怎么算，流式事件怎样被消费与投影，只读工具怎样边流边执行、账本记什么；输出截断后如何续写，断流与取消怎样恢复或落盘，错误如何分类、各层重试几次，用量与缓存命中怎样统计。
- [会话事件流与持久化投影](https://daiw.org/manual/zcode/session-events.md): AgentRuntime 怎样对外交代它做了什么：七十九种会话事件的谱系，只在内存里、按回合窗口淘汰的事件存储，appendEvent 的四步管线，EventReducer 投影出的会话状态，消息与 part 怎样与事件并行落库，合成通知的语义标注，标题生成的旁路请求，以及会话驻留。

### 第 2 部分 · 上下文、压缩与记忆

- [系统提示词、上下文与提醒](https://daiw.org/manual/zcode/context-builder.md): 每次模型请求前的那段“前缀”怎样拼出：十几个段落按静态、动态分进三条 system 消息，AGENTS.md 与记忆索引走 meta user 块；二十多种 system reminder 何时产生、落在请求哪里、是否落库；中途 system 消息投影，以及上下文用量拆解给谁看。
- [上下文压缩](https://daiw.org/manual/zcode/compaction.md): microcompact 与自动压缩的阈值公式和具体数字，rapid refill 保护的规则，压缩时保留什么、丢掉什么，摘要请求怎样构造与重试，图片与文档怎样降级，手动 /compact 的入口，压缩后补回哪些提醒，以及摘要怎样落库、冷恢复时怎样重建。
- [项目记忆](https://daiw.org/manual/zcode/memory.md): 记忆存在哪、按项目根怎样定位目录；MEMORY.md 索引怎样进上下文；每个成功回合之后后台记忆 Agent 如何抽取，输入、工具白名单、调度与游标；为什么没有独立的召回器；记忆文件的写权限规则；ReadSessionContext 怎样跨会话读取历史；以及用户怎样开关与查看。

### 第 3 部分 · 工具系统

- [工具契约、注册表与可见性](https://daiw.org/manual/zcode/tool-contract.md): 一个 ZCode 工具要声明哪些字段、其中哪些真正被读取；内置工具与 MCP 工具怎样进同一张注册表；每回合发给模型的工具清单怎样按端口、开关与模型能力层层筛选、排序并投影成 JSON Schema；参数不合格时模型收到什么。附内置工具全表。
- [执行器：调度、审批、超时与结果](https://daiw.org/manual/zcode/tool-executor.md): 一批工具调用怎样按并发安全分组、哪些并行哪些串行；单个调用怎样走完校验、PreToolUse、权限审批、执行、PostToolUse 与结果投影；超时的默认值与取消语义；错误和大结果怎样变成给模型的内容，又怎样投影给界面；执行事件与遥测。
- [读、写、改、搜](https://daiw.org/manual/zcode/file-tools.md): 五个文件工具的实现：Read 怎样分流文本、图片、PDF 与视频并计入预算，read-file-state 怎样落实“先读后改”，Edit 的八级匹配与唯一性要求，文件系统 adapter 的原子写与编码，以及默认搜索为何改走 Bash 里的 bfs 与 ugrep、这些原生工具怎样分发到各平台。
- [WebFetch 与 WebSearch](https://daiw.org/manual/zcode/web-tools.md): 两个联网工具的实现：WebFetch 的 URL 规范化、出站护栏、重定向与各项上限、手写的 HTML 转 Markdown、交给当前模型提炼与 15 分钟缓存；预批准域名与审批；WebSearch 怎样借模型提供方的原生 web_search，哪些端点支持，结果与引用怎样整理。
- [Bash：解析、只读判定与后台任务](https://daiw.org/manual/zcode/bash.md): Bash 工具的输入与提示词、unbash 解析与只读判定规则体系、判定结果在权限层的含义、命令注册表生成、工作目录与 git 护栏、超时与自动转后台、输出截断与图片、TaskOutput 与 TaskStop，以及 Bash 读文件怎样回填读取状态。
- [执行边界：子进程、环境与网络](https://daiw.org/manual/zcode/exec-boundary.md): 所有子进程与网络请求都收敛到 adapters 的两个入口：执行端口怎样选 shell、取登录 Shell 快照、在 Windows 上起 .cmd 与 Git Bash；环境变量怎样在入口清洗、把代理与证书封存再只还给子进程；输出直写、进程树终止与退出码归一；以及为什么没有操作系统沙箱。
- [Todo、提问与 Plan 模式](https://daiw.org/manual/zcode/interaction-tools.md): TodoWrite 的输入结构、存储与待办提醒；AskUserQuestion 的问卷上限，及其在 TUI、桌面与无头模式下怎样收场；Plan 模式的进入与退出、ExitPlanMode 的审批与计划文件、规划期间的工具面；ListModels 与模型引用解析。

### 第 4 部分 · 权限与钩子

- [权限模式与规则](https://daiw.org/manual/zcode/permission.md): 四种权限模式在各入口的默认值与真实语义，PermissionService 的判定顺序，规则的结构与匹配算法，审批请求怎样经 broker 交给终端或桌面并与钩子竞速，“始终允许”与 Full access 各存在哪一层，以及 Plan 与 yolo 的例外。
- [生命周期 Hooks 与工作区信任](https://daiw.org/manual/zcode/hooks.md): 七个钩子事件的触发时机、matcher 与能力，配置格式与默认值，进程钩子的 stdin 与 stdout 协议、退出码 2 与失败语义，Stop 续跑上限，钩子输出怎样进模型上下文，与 Claude Code 的兼容程度，以及项目目录里的钩子为什么要按声明摘要逐条信任。

### 第 5 部分 · 模型与账号

- [Provider 规则、模型目录与选项映射](https://daiw.org/manual/zcode/provider-config.md): ZCode 用一份随包分发、可远程更新的规则集描述账号型 Provider、第三方模板和每个模型的能力，再叠上个人 BYOK 配置与账号权益两层；“推理强度”“输出上限”两个统一选项则由一门受限的 CEL 小语言翻译成各家请求体字段。
- [模型适配层](https://daiw.org/manual/zcode/model-adapters.md): adapters 包的 model 目录怎样用 Vercel AI SDK 的三个 provider 包对接 anthropic-messages、openai-chat-completions、openai-responses 三种协议，把流式输出归一成运行时事件；推理签名、缓存断点、请求头、超时重试、两个 SDK 补丁和官方套餐网关都落在这一层。
- [账号、Coding Plan 与闲时计划](https://daiw.org/manual/zcode/accounts-plans.md): zcode login 怎样经 ZCode 平台中转完成浏览器授权，z.ai 与 bigmodel 两个账号区域怎样区分，令牌与 API Key 存在哪、怎样加密；个人、团队 Coding Plan、Start Plan 与隐藏的闲时计划各自用什么凭据、配哪些模型，额度又从哪里查。

### 第 6 部分 · 多 Agent 与长程任务

- [子 Agent](https://daiw.org/manual/zcode/subagents.md): Agent 工具怎样派生子 Agent：内置 general-purpose 与 Explore、自定义 Markdown 画像与模型选择、独立的子 AgentRuntime 与借用的 MCP 连接、父子双向消息、审批回到父会话、后台完成通知、持久记忆与 TUI 观察。
- [目标模式：让 Agent 做到完成为止](https://daiw.org/manual/zcode/goal-target.md): /goal 与 --target 怎样立目标，session_target 里的四种状态怎样流转，回合结束后续跑循环何时再起一轮、续跑提示怎样构造，完成验证怎样另起一次无工具请求、故障时为何放行，以及上限、计时与遥测。
- [后台任务与通知](https://daiw.org/manual/zcode/background-tasks.md): 后台 Bash、后台子 Agent 与工作流 run 怎样登记进同一张内存任务表，结束后怎样变成一条只给模型看的 task-notification 消息，在回合中途注入或在空闲时自动开一轮；单个任务的停止分派，以及桌面端后台面板怎样与运行时对齐。
- [定时任务与闲时任务](https://daiw.org/manual/zcode/cron-offpeak.md): 模型能用的 Cron 与 OffPeak 工具及其参数，任务定义存进桌面端的 tasks-index.sqlite，由 Electron 常驻调度进程每 20 秒认领派发；执行轮为何隐藏写工具，独立 CLI 为何没有调度，闲时任务怎样取号、轮询与续跑，错过与失败怎样处理。

### 第 7 部分 · 工作流

- [专家工作流与图调度器](https://daiw.org/manual/zcode/expert-workflow.md): core/src/workflow 里的一条固定八阶段长任务流水线：每个阶段交给一次性子会话，执行阶段由依赖图调度器按并发上限推进、可让 planner 扩图，终审可以重开节点，状态写成可恢复的文件快照。它在当前版本只有 CLI 与 TUI 的 /expert 一个入口，与动态工作流是两条独立的线。
- [动态工作流（一）：门面与编译器](https://daiw.org/manual/zcode/dwf-compiler.md): 主 Agent 用 TypeScript 写工作流脚本：门面 API 长什么样，编译器怎样在纯内存的虚拟宿主里做类型检查、报出 9001～9009 诊断，用 taint 不动点和时序遍历算出四种图，再把结果类型合成 JSON Schema、把脚本降级成沙箱能跑的 JavaScript。
- [动态工作流（二）：引擎、沙箱与日志回放](https://daiw.org/manual/zcode/dwf-engine.md): 引擎怎样在不做 I/O、不读时钟的前提下调度多个 actor：序号、日志回放与 hold 规则、repair 与 nudge、用量记账；沙箱怎样用子进程加 vm 上下文隔离脚本、禁用 Date.now 与 Math.random；NDJSON 线协议，以及各类故障落到哪种终态。
- [动态工作流（三）：从工具调用到落库](https://daiw.org/manual/zcode/dwf-tools.md): 动态工作流的产品层：功能开关与入口，模型可用的十个工作流工具，一次“创建并运行”从草稿文件、编译诊断、确认窗到后台 run 的全过程，每个 actor 怎样成为一个子会话，进度怎样回到主会话，日志存进 SQLite 的哪四张表，以及升级问答、保存、修订、恢复与无头模式。

### 第 8 部分 · 扩展机制

- [技能与自定义命令](https://daiw.org/manual/zcode/skills-commands.md): SKILL.md 从哪些目录被发现、同名时谁先被加载，技能清单怎样以系统提醒进入上下文、Skill 工具怎样读取全文；Markdown 自定义命令的参数替换与 shell 展开及其安全边界，以及内置斜杠命令在 TUI、无头模式与 App 协议里的不同面貌。
- [插件与官方市场](https://daiw.org/manual/zcode/plugins.md): 插件能带来哪些组件、清单放在哪里、变量怎样展开；插件状态目录的布局，官方市场的内置分区与 CDN 分区、个人来源与 sha256 校验的 zip，启用状态怎样存与解析，plugin-host 子进程为何要在导入运行时之前分流，以及对话里的插件引用提醒。
- [MCP](https://daiw.org/manual/zcode/mcp.md): ZCode 的 MCP 客户端：配置从用户、项目、插件与内置宿主四处合并，支持 stdio、http、sse 三种传输；会话一创建就开始连接，首次模型请求前注册工具；工具命名与图片归一、OAuth 两段式授权、官方 MCP 的身份头注入，以及工作区级 MCP 自动连接的安全含义。
- [node_repl、Browser Use 与 Computer Use](https://daiw.org/manual/zcode/node-repl-browser.md): 浏览器控制只给模型一个 js 工具：node_repl 是随官方插件注册的 stdio MCP 服务器，每次调用都在一次性 Worker 里起新内核，再经私有 socket 回到 Agent 的浏览器端口；桌面端驱动内嵌浏览器，CLI 用 Playwright 起无头 Chromium；Computer Use 在开源版是一律失败的占位实现。

### 第 9 部分 · 会话、存储与可观测性

- [SQLite 会话库](https://daiw.org/manual/zcode/session-store.md): Agent CLI 的持久状态都在一个 SQLite 文件里：为什么用 Node 内置的 node:sqlite，库在哪、有哪些表，22 条只追加的迁移怎样按校验和记账，多进程并发与事务，故障注入，-c 与 --resume 的查询，以及恢复时怎样把消息和 part 重建成模型历史与读文件状态。
- [检查点、回退与分叉](https://daiw.org/manual/zcode/rewind-fork.md): Write 与 Edit 每次成功都留一份文件快照；回退对话只移动会话上的分支游标，不删消息；回退文件分“按检查点直接恢复”和“先预览、按哈希校验再应用”两条路；分叉把前缀复制进子会话，稳定分叉在回合结束时就钉好边界；旁支会话则是一个只继承上下文的隐藏分叉。
- [遥测、调试与提示词轨迹](https://daiw.org/manual/zcode/telemetry-debug.md): traceId 从会话一路传到回合、工具调用和模型请求头；OpenTelemetry 默认关闭，配了 OTLP 端点才加载；错误与端点怎样脱敏；日志的格式、位置与 7 天保留；模型输入输出的本地录制与 prompt-trajectory；debug 包的抓包代理与时间线界面。

### 第 10 部分 · 终端与协议

- [命令行入口、无头模式与打包](https://daiw.org/manual/zcode/cli-surface.md): Agent CLI 的外壳：main.ts 怎样守住 stdout 与 stderr、兜住进程错误与退出，全部子命令与全局选项及其限制，-p 无头模式的流程与三种输出格式，Node bundle 与 SEA 两条打包路径，发行包的 --web 分流与安装脚本，以及界面语言检测。
- [终端界面](https://daiw.org/manual/zcode/tui.md): 不带参数运行 zcode 打开的全屏 TUI：OpenTUI 之上的 React 渲染与同进程直调，界面分区、输入框与全部快捷键，斜杠命令与切换面板，Markdown 与 diff 渲染，审批与问卷，侧边栏的 MCP 与子 Agent 观察，以及为什么要拦截 stderr。
- [ZCode Protocol V4：Agent 对外的线协议](https://daiw.org/manual/zcode/zcode-protocol.md): 桌面端与 Web 服务端怎样经 stdio 驱动 Agent 子进程：NDJSON 帧与 stdout 保护，版本与握手，V4 方法与 34 种命令，CommandInbox 的串行受理与幂等，快照续传，两种投递档位，交互应答竞速，stale 防护与会话驻留。

### 第 11 部分 · 桌面、Web 与远程

- [桌面应用：Electron 的三层](https://daiw.org/manual/zcode/desktop.md): ZCode 桌面端怎样把 Electron 拆成 Main、窗口级 Local Host 与 Renderer：Host 用 Electron 自带的 Node 拉起 app-server 模式的 Agent 子进程并管理其生命周期，任务列表怎样与 Agent 会话库同步；另有 V8 字节码试验、内嵌浏览器、自动更新、终端、Claude Code 历史导入与打包签名。
- [Web 与服务端：同一套 UI 的另一种宿主](https://daiw.org/manual/zcode/server-web.md): zcode --web 与 pnpm dev:web 各起了什么、令牌怎样生效；Hono 服务怎样经仿 VS Code 的 RPC 把业务服务交给浏览器、拉起 Agent 并推回事件；同一套 React UI 如何靠依赖注入同时跑在 Electron 与浏览器里，架构规则又管到了哪里。
- [远程工作区与手机远控](https://daiw.org/manual/zcode/remote.md): ZCode 怎样把 SSH 主机、WSL 发行版与 Docker 容器变成远程工作区：远端部署哪些资源包、两种安装方式与 SHA-256 校验，经 SSH exec 通道的 stdio 跑起远端服务与 Agent；workspaceIdentity、workspacePath 与 remoteSessionId 各管什么，缺席的主机密钥校验；手机远控怎样挂到桌面已有的 Host，以及独立远端服务 zcode-server-cli 的 Supervisor 与控制 IPC。
- [回顾](https://daiw.org/manual/zcode/recap.md): 全书要点串联：一条消息穿过的各层，值得记住的设计，与站内其他终端 Agent 的对照，读代码时发现的文档出入与值得留意的行为，以及可迁移的经验和这份源码的短板。