ZCode 项目分析：GLM 官方 Agent Harness 的架构与执行机制

官方文档：ZCode Agent · 源码仓库：zai-org/ZCode

AI 参与说明（Agent：Codex）：本文由 Codex 阅读官方文档与固定版本源码后协助整理，并使用 Context7 核对产品文档、humanizer-zh 编辑中文正文。资料整理于 2026-10-10；除隔离执行 Goal 解析纯函数与检查工作流示例类型外，源码分析采用静态核对，未运行完整 ZCode、调用 GLM API 或测量任务成功率。运行记录：模型 gpt-6.1-sol，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai；运行记录中的 CLI 版本 0.162.0-alpha.17.2，不代表桌面 App 版本。

ZCode 的研究价值在于，它公开了模型之外怎样把编码任务持续推进的工程实现：选择上下文、调用工具、等待授权、组织子任务、压缩历史、恢复状态，再判断目标是否完成。官网明确将它称为“GLM-5.3 官方 Harness”，这一定位有官方依据。官方首页

本文重点看分层 Context 管理、带完成检查的 Goal Mode，以及有编译分析和执行日志的 Dynamic Workflows。源码中的权限边界与完成判定有明确取舍，需要沿着执行路径理解。

先固定版本：在线产品与公开源码是两份证据

本次核对的 main 是 commit 29628c9，提交者时间为 2026-09-24，根 package.json 版本为 3.14.3。官网在 2026-10-10 的下载入口已显示 3.14.5，发布记录标注该版发布于 2026-10-09。源码版本 官方发布记录

因此，下面的实现结论均对应这个固定 commit；在线文档用于说明当前产品约定。两者不一致时，应分别记录，不能把更新后的文档当作旧版本源码的执行保证。这个快照的模型配置已经包含 GLM-5.3，不能仅凭版本日期推断它没有相关适配。

整体架构：工作台、Agent Runtime 与外部环境

仓库采用 TypeScript workspace，包含 Electron Desktop、Web、TUI，以及共享业务服务与 Agent Runtime。README 给出的开发基线是 Node.js 24.14.0 和 pnpm 10.33.2，许可证为 Apache-2.0。apps/zcode-cli 是随仓库一起提供的普通源码目录。README

桌面宿主的进程管理器按工作区管理 Agent 子进程，使用 ZCodeStdioTransport 和 ZCodeProtocolClient 通信；协议传输接口还定义了 WebSocket 与 memory 形态。进程重建后，订阅方需要重新订阅会话与配置事件，不能继续使用上一代进程的内存订阅。进程管理 传输接口

下面是职责关系图，不表示每个入口都使用相同传输：

flowchart TB
    entry["Desktop / Web / TUI"] --> host["宿主服务与会话协议"]
    host --> runtime["Agent Runtime<br/>Goal Mode / Subagents<br/>Dynamic Workflows"]
    runtime --> context["Context<br/>模型请求"]
    context --> model["GLM / 其他 Provider"]
    model --> loop["Agent Loop"]
    loop --> permission["权限判断与 Hooks"]
    permission --> environment["文件 / 进程<br/>MCP / Browser"]
    environment -->|"结果与错误"| context
    runtime --> state["会话存储<br/>Journal"]
    state --> host

这套结构使 UI 可以展示和控制执行，却不必承担全部模型循环逻辑。研究 Harness 时，应优先进入 CLI 的 core、adapters 和 dynamic-workflow，再看工作台如何呈现这些状态。

Agent Loop：在模型请求前后安排控制逻辑

源码中的循环会在模型请求前处理本地 microcompact、自动 Compaction、MCP 初始化、工具筛选和运行时提醒。模型请求经过历史投影、媒体能力与缓存策略处理，返回后再由状态机决定执行工具、继续请求或结束回合。循环入口

模型能看见的工具集合也会随执行场景变化。Plan 状态、Subagent 身份、工作流角色、已连接的 MCP 与工具白名单，不只是写进提示词的说明，还影响请求中的工具目录和后续执行路径。

The model proposes actions; the runtime decides how those actions enter execution and how their results return to the conversation.

这一区分很实用：模型调用成功，却没有正确续轮、等待授权或回传工具错误，仍然会使任务失败。ZCode 把这些行为放进运行时，而不是要求模型用自然语言自行维护全部状态。

Prompt 也按生命周期组装：稳定身份与行为规则、动态系统信息、Skills 目录、附件、Workspace 指令、Memory 和日期分别进入 Context；工具说明从请求的工具集合提供，不在系统提示中复制一遍。稳定与动态内容还分别处理缓存标记。这让变化较少的内容与每轮变化的环境信息可以分别管理。Context Builder

GLM 适配：能看到哪些“深度集成”

官方文档把长上下文、长轨迹训练和 Flexible Effort 作为 GLM-5.3 的模型能力，并将工作区 Context、执行模式与 Goal Mode 作为 Harness 中承接这些能力的机制。这是官方对产品与模型关系的解释；它没有在该页给出 Harness 的消融实验或联训配方。ZCode Agent

固定源码里可以核对到更具体的适配：

模型目录 · 推理参数映射

官方套餐路由只匹配指定端点，第三方自建地址不按同一规则改写；Thinking 历史兼容也限定身份组，没有扩展到全部 GLM 请求。这些是接入与协议上的具体边界。Coding Plan 网关 Thinking 历史处理

这些机制足以支持“存在 GLM 的具体工程适配”。但运行时也支持其他模型，Context、工具权限、Goal 和工作流引擎的大部分结构具有通用性。公开代码不能证明它是 GLM 唯一可用的 Harness，也不能证明整套机制都是 GLM 独有。

评价“官方 Harness 对 GLM 有多大增益”，还需要固定同一个模型版本、任务集、工具和预算，比较不同 Harness 的成功率、用量与人工介入次数。本次没有进行这种实验。

Context：大窗口之外还有清理、摘要与按需加载

microcompact 与 Compaction 分工

本地 microcompact 先清理可压缩的旧工具结果，默认保留最近五个候选工具调用组，保护错误结果和媒体，并设置最少节省 256 tokens 的门槛。它不需要为了每次清理再请求模型；需要总结历史时，才进入模型参与的 Compaction。microcompact

当前配置文档说明自动 Compaction 会为输出和缓冲预留约 34K tokens，并由模型窗口决定触发位置；套餐模型的窗口配置可以由服务端同步。这是在线产品约定，不能用“1M Context”推导所有历史都无损保留。配置文档

这两种操作解决不同问题：一段冗长终端输出可以清理；目标、决策与待办则需要总结后继续携带。它们都会改变模型下一轮能看到的材料，因此压缩后的任务应重新核对关键文件与检查结果，尤其是文件后来又发生变化时。

自动摘要通常把近期完整消息组留在尾部，再用摘要替代较早历史；压缩结果和边界会持久化。超出窗口时还可能进一步减少旧消息组。运行时另有 rapid-refill breaker，防止“刚压缩，又很快填满”的重复循环。因此，它管理的是有损 Context，而非无限保真的会话记录。历史选择 压缩提交

指令、Skills 与 Memory 的生命周期不同

项目指令用于稳定规则，Skills 用于按任务装载操作知识，Memory 用于跨会话保留事实。把三者混成一个不断增长的系统提示词，会扩大 Context，也使规则来源难以区分。

ZCode 文档规定用户全局 AGENTS.md 与当前 Workspace 的 AGENTS.md 顺序拼接，不递归合并子目录规则，也不展开 @import / @include。Skills 的名称与短说明先进入目录，正文按调用加载；文档给出的短说明注入上限为每条 250 字符，目录另有共享预算，超预算时退为只列名称。这会影响模型自动选择 Skill 时能看到的信息。项目指令 Skill

Memory 当前文档描述的是默认关闭、按项目隔离的本地 Markdown 文件与索引，成功回合后用额外请求提炼可复用事实；当前项目 Memory 的公开说明限于本地主会话，不支持远程 Workspace，也不应据此推断所有 Subagents 共享它。它不适合替代可以重新读取的源码或 Git 历史。专页给出了对话管理与手工编辑方式，而 Agent 总页仍保留不能查看或清除的旧描述；使用时应核对安装版本。Memory

本地保存 Memory 描述的是存储位置。当内容被选进远端模型请求时，它仍会成为请求 Context；这两件事需要分别理解。

Goal Mode：把回合停止与任务完成分开

Goal Mode 是 ZCode 在长任务方向最值得研究的一层。源码将目标状态持久化为 active、paused、budget_limited、complete，并保存目标文本、Token 预算、已用 Token 和用时。自动续轮由运行时命令队列驱动；有待执行命令时，循环会让出控制权。Goal 数据契约 自动续轮

默认存储实现使用 SQLite。目标达到 Token 预算时转为 budget_limited，中断的活跃运行在恢复时转为 paused；持久化进度不代表应用重启后自动恢复所有执行。Goal 存储与预算结算

flowchart TB
    goal["持久化 Goal"] --> turn["执行一个回合"]
    turn --> verify["单独发起完成检查"]
    verify --> decision{"检查结果"}
    decision -->|"未通过"| pending{"有 nextAction？"}
    pending -->|"有"| feedback["reason<br/>nextAction"]
    feedback --> turn
    pending -->|"无"| hold["暂不自动续轮"]
    decision -->|"通过 / 部分故障放行"| complete["标记 complete"]

文档要求以改动、命令输出、测试结果等证据判断完成，未完成 todo 应优先处理；没有完成时给出下一步并自动继续。Goal Mode

完成检查会读取检查开始时的当前会话模型选择，使用会话历史加完成检查 Prompt，发送 tools: [] 的单独请求，返回 passed、reason 和可选 nextAction。它没有单独配置异构裁判模型，也不会在这次请求里重新执行测试；用户切换模型后，检查器可能与上一回合使用的模型不同。检查器请求

正常续轮还要求未通过结果带有 nextAction；只有未通过却没有下一步时，循环不会自动再起一轮。后台任务尚未结束时也会延后检查。续轮条件

更重要的边界是 fail-open：输出无法解析成有效 JSON、检查请求遇到部分非取消错误，或检查器尝试调用工具时，代码存在返回 passed: true 的路径；上层会据此把目标标记为 complete。源码注释解释其目的，是避免检查器基础设施或格式故障使已交付目标不断迭代。解析与 fail-open 请求错误处理

本次从固定源码中提取解析纯函数，隔离执行两项检查：输入 not JSON 得到 passed: true；输入明确的 passed: false JSON 则保持失败与 nextAction。这验证了格式故障与模型明确判定未完成的区别，未覆盖真实模型请求或完整 Goal 生命周期。

Goal completion is a runtime decision, not a proof that every requirement has passed an executable check.

这项设计有明确收益：任务不会只因模型写了一段收尾就失去继续推进的机制。但它把可用性放在部分检查故障前面。依赖 Goal Mode 交付工程成果时，应把可执行的通过标准写进目标，例如具体测试、输出文件和人工 Review 条件；结束后仍查看证据，不能只读状态标签。

失败恢复：重试要知道已经执行到了哪里

长任务需要处理的不只是 HTTP 请求失败，还包括流式文本已显示、工具参数尚未完成、工具已经执行、输出被截断等不同阶段。

ZCode 的模型 Adapter 把 SDK 自带重试设为零，由自己的策略控制重试与退避。流式工具参数先用于展示，真正执行需要完整调用与输入结束边界；执行层再校验名称、参数和重复 ID。网络重试边界则区分尚未提交的输入与已经输出的正文，不能把任何断流都当成无副作用的重新开始。请求选项 工具调用组装 流式重试边界

运行时还有截断后续写、超窗后的 Reactive Compaction、取消时保存部分输出等路径。这些机制减少整轮重做，但仍有次数上限和失败出口；恢复机制的存在不能直接说明所有长任务都能恢复成功。输出续写

Dynamic Workflows：编译脚本、调度节点并恢复结果

常规 Subagents 让主 Agent 临时派发任务。Dynamic Workflows 又增加一层：模型生成受约束的 TypeScript 脚本，用代码表达顺序、并行、分支、检查与产物，再由引擎执行。这个版本的更新记录也集中在并发调整、重启复用、实时状态及 Context 消耗上。commit 说明

编译与分析先于执行

脚本被包在异步函数里，以 ES2022 与专用 Facade 做类型检查，没有 Node 或浏览器的 ambient types；随后分析器收集调用位置、命令集合、阶段、产物和角色名称，再生成因果、控制流及交接图。分析不通过，就不能把脚本当成可提交工作流。编译器 分析器

agent().ask<T>() 的结果类型可以参与运行时 Schema 合成，便于后续代码按字段分支。world.run 的命令名必须是编译期字符串字面量，让确认界面能够提前展示命令集合。外部观察经 Facade 进入执行；这能帮助控制和重放工作流，不等于为它创建了操作系统安全沙箱。

编译选项里还有一处针对模型生成代码的取舍：保留 strict，关闭 noUncheckedIndexedAccess。源码注释说明，目的是减少数组索引产生的修复负担，同时继续检查可空结果。注释中的本地统计是上游解释，本文没有复测，不把它作为通用效果数据。

Journal 保存结果，恢复不必全部重做

引擎用“调用位置 ID × 该位置执行序号”标识节点，记录输入哈希、状态与结果。同一角色按 FIFO 排队，不同角色受并发上限调度。恢复时，已完成或失败的节点可以从 Journal 结算；仍处于运行状态的节点会重新派发，输入哈希不一致则报告错误。引擎 恢复调度

修改工作流后再运行，另有按命名角色和未变化请求导入结果的机制。一旦新的执行开始改写工作区，或执行 live world.run，旧工作区观察与带工具调用结果的导入缓存会关闭；纯文本请求结果另行处理。原因很具体：相同 Prompt 哈希不能证明文件仍是原来那份。缓存关闭条件

Replay reuses recorded observations; it does not automatically re-verify the current workspace.

同样，恢复日志不能单独保证任意外部副作用恰好执行一次。某个节点在副作用发生后、结果落库前中断，如何处理仍取决于具体工具与外部系统。这是采用 Journal 时必须评估的条件。

一个最小脚本：并行审查，再运行确定性检查

下面是 ZCode Dynamic Workflows 的脚本正文，不能直接交给普通 Node.js 执行。前提是工作区有两个示例文件，且 package.json 定义了 check。在支持该功能的 ZCode 中通过 /workflow 发起任务，明确文件、检查与产物要求，让 Agent 使用 CreateWorkflow 提交脚本。

interface Review {
  /** File reviewed by this actor. */
  path: string;
  /** Candidate issues that still need independent confirmation. */
  candidates: string[];
}

phase("审查关键文件");
const reviews = await Promise.all(
  ["src/auth.ts", "src/storage.ts"].map((path) =>
    agent(`审查 ${path}`, "Review code without editing files.").ask<Review>(
      `Read ${path}. Report candidate issues with path:line evidence.`,
    ),
  ),
);

phase("运行项目检查");
const check = await world.run("npm", ["run", "check"]);
const body = reviews
  .map((review) => `## ${review.path}\n${review.candidates.join("\n")}`)
  .join("\n\n");
await artifact.markdown("review", `${body}\n\nCheck exit code: ${check.exitCode}`, {
  title: "候选问题与检查结果",
  primary: true,
});
return { filesReviewed: reviews.length, checkPassed: check.exitCode === 0 };

这里新建两个角色才能并行；把同一个角色变量用于两次 ask，会进入同一角色的 FIFO 队列。“不编辑文件”由角色 Prompt 要求，示例没有设置操作系统只读限制。检查是否通过直接读取进程退出码；候选问题保留为候选，不因检查成功就自动成立。产物与最后返回的简短状态也分别处理。公开 Facade 内置工作流编写规范

本次将该 commit 的 Facade 声明与示例包装成异步函数，使用本地 TypeScript 6.0.3 做类型检查：正确示例产生 0 条诊断；把 reviews.length 改成不存在的 reviews.missingProperty，得到 TS2339。未执行完整 ZCode 分析器、工作流、模型请求或上述项目检查，因此这项结果只证明示例与公开类型接口相符。

工具、权限与扩展：哪些是程序约束，哪些依赖约定

工具执行经过权限流程

工具执行路径会验证输入、处理调用前 Hook、判断权限、等待必要的确认，再执行工具并回传成功或失败。Hook 改写输入后还需要重新校验，不能把最初通过检查的参数直接当作改写后参数的授权。权限流程

产品提供变更前确认、自动编辑、Plan 和完全访问等执行模式。审批与计划批准不使用普通反问的无人响应自动继续规则。安全操作确认

但这个源码版本的命令执行器直接使用 node:child_process.spawn；注释明确提到此前的 protected-resource sandbox 已撤除。审批控制的是操作是否进入执行，命令本身仍在宿主进程权限下运行。执行器 sandbox 历史注释

Plan 也有具体边界：代码对 MCP 读取 readOnlyHint 和 destructiveHint，但 Plan 权限分支放行非 destructive 的 MCP，并不要求 readOnlyHint 为真。未经准确声明的远端工具不能仅凭进入 Plan 就认定没有副作用。Plan 权限判断

Subagents 隔离的是 Context

常规 Subagents 有独立历史与工具目录，支持前台等待、后台完成后回注，以及用户定义的角色。源码关闭子运行时继续派发 Subagents，并移除其 EnterPlanMode / ExitPlanMode，避免进入没有对应交互界面的计划审批等待。

需要留意 Explore：文档将它称为只读角色，但源码白名单包含 Bash，文件写入工具被移除；未显式配置权限模式时，内置 Explore 选择 yolo。只读语义还依赖 Prompt，不能据此推导强制隔离。不同类型 Subagents 的权限服务处理也不同，不宜笼统说全部继承同一限制。Explore 工具约定 子运行时装配 默认权限模式

Dynamic Workflows 中的角色又有另一套约定：角色复用变量就复用 Context，重新调用 agent() 就创建新 Context；每个角色的行为要求写在任务中。它与设置里的用户级 Subagent 配置不能混为一套接口。

后台回复也有运行时处理：主会话分叉或重置后，旧分支的子任务响应会被过滤；有效回复进入命令队列，转成模型能读到的通知并持久化。否则，界面收到一条完成通知，模型却可能始终不知道分工已经结束。后台回信处理

Hooks 把反馈插在循环边界

当前官方文档列出七个事件：SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Stop。调用前可检查或改写输入，执行后可追加反馈，Stop 可要求继续，但连续续轮有上限。这与 Goal Mode 的跨回合目标循环是两种机制。Hooks

源码另有 Workspace Hook 的信任记录，以工作区身份和声明摘要核对是否已获信任；未信任的 Hook 可以跳过并报告待审状态。当前在线文档却写项目级 Hook 配置不执行。这里能确认的是“源码存在信任与准入实现”，不能直接宣称当前发行版默认启用它。信任判断 运行准入

Plugin 与 MCP 形成扩展入口

Plugin 把 Skills、Commands、Agents、MCP 与 Hooks 放在同一分发单元，减少用户逐项配置的负担；清单保留了部分 Claude Code 兼容路径，但一些字段只登记而不执行，所以应按字段核对兼容性。MCP 则把外部工具接进统一目录、调用与授权流程。Plugin MCP

这类扩展会带来本地进程与网络能力。权限判断、扩展来源信任、工具自身的身份校验，分别位于不同边界；一个环节具备确认机制，不表示其余边界自动成立。

观察与恢复：让模型看到结果，也让人能够介入

官方 Browser Use 插件给 Agent 提供打开网页、点击、填表、截图等能力；工具得到页面观察后，可以继续检查前端结果。终端、文件引用、Git 与 Review 面板则把工程状态接回同一任务。Browser Use ADE 工具

这是 Harness 对任务成功很直接的一种贡献：给模型可读取的真实环境反馈。浏览器截图或测试输出可以帮助发现错误，但只有实际检查了相关路径，才构成该项验证的证据；“拥有浏览器工具”不能代替“完成了页面验收”。

恢复也有范围。会话分叉保留对话历史，却共享工作区且不回滚磁盘。文件撤销和历史重发的恢复不能覆盖所有终端副作用，用户中途修改文件也会影响安全恢复；这时仍需要 Git 或外部系统自己的恢复方式。会话分叉 编辑历史对话

源码的 Checkpoint 来自成功文件工具结果中的路径、原内容与补丁等结构化数据，保存单文件修改前内容；它没有为每次 Bash 自动创建整个环境快照。文件摘要撤销流程会比较当前内容与记录哈希，发现外部修改后拒绝应用，并有失败补偿；旧恢复路径仍存在直接覆盖或删除文件的逻辑。因此，不能把某一条安全撤销路径泛化为全部 rewind 的保证。Checkpoint 创建 文件冲突判断 旧恢复路径

从 ZCode 可以借鉴什么

如果要设计自己的 Coding Agent，本文更建议借鉴控制边界，而不是先复制工具数量。

这些做法值得作为设计样本，但独创性与相对性能需要另外证明。ZCode 用 Context 和 Provider 适配承接模型能力，用运行时状态推进任务，用脚本与日志组织复杂分工，再通过工作台呈现过程与产物。完成检查和权限边界的具体实现，决定了这些能力在什么条件下可以依赖。

源码阅读与关联文章

建议按“循环 → Context → Goal → 工具权限 → 工作流”的顺序读。先建立一次请求如何完成的认识，再追踪长任务与并行任务怎样跨越请求边界。

• 运行时方法目录：模型循环、停止、Goal 与 Subagents。
• Context 目录：指令与动态内容组织。
• 工具执行目录：验证、权限、Hook 与结果回传。
• Dynamic Workflows 目录：编译、分析、调度与 Journal 契约。
• Pi Agent 框架架构：包边界、Agent Loop 与接入选择：对照另一种分层方式，理解模型接口、Core 与 Coding Agent SDK 的边界。
• Agent 开发中的测试方法：Specification、Test Oracle 与验证证据：进一步区分模型判断、可执行检查和任务完成证据。
• Agents Overview：回到栏目导航。