从 Harness 到自研内核:智谱 ZCode 的架构迭代路线图
从 Harness 到自研内核:智谱 ZCode 的架构迭代路线图
2026 年 9 月,智谱开源 AI 编程智能体 ZCode 更新至 v3.14.3,社区流传最广的一条标签是"ZCode 3.0 全面切换自研 ZCode Agent 内核"。如果把这条新闻放回更长的坐标轴里看,它其实是智谱在 AI 编程赛道上三次架构选择的终点站:第一代是"套在 GLM 模型外面的 Harness",第二代是"开源 CLI 的工程化与 Skill 体系",第三代才是"从模型适配到编排运行时全部自持的 Agent 内核"。本文不打算复述发布会口径,而是钻进 zai-org/ZCode 仓库,沿 apps/zcode-cli 的源码逐层验证:所谓"自研内核"到底自研了什么,三代迭代在代码里留下了哪些可对证的痕迹。
一代目:Harness 平台与智能体的早期形态
"Harness"这个词在 AI Agent 圈子里有特定的含义——它指那层把大模型"接"到真实世界的壳:工具调用协议、权限控制、上下文组装、回合循环。Anthropic 在 2025 年开源 Claude Code 时,把这套壳完整摊开,从此"harness"成为终端编程智能体的标准范式:模型只是大脑,harness 决定大脑能摸到什么、能改什么、一次能干多远的活。
智谱的第一代 ZCode,本质上就是为 GLM 系列模型打造的这样一个 Harness 平台。社区早期的使用文章对此描述得很直白:"ZCode 作为专为 GLM 模型设计的智能体平台(Harness)",以及"任务规划-执行-纠错闭环工作流"。那个阶段的 ZCode 并不生产自己的 Agent 内核——它更像一个"模型承载架",把当时业界成熟的开源 harness 思路(terminal agent 的交互形态、Markdown 输出、工具即函数)与 GLM 的 API 绑定在一起。
这一代的技术遗产至今仍刻在代码里,最典型的是 identity.ts 中那段 # Harness 系统提示块:
# Harness
- Text you output outside of tool use is displayed to the user as Github-flavored markdown in a terminal.
- Tools run behind a user-selected permission mode; a denied call means the user declined it — adjust, don't retry verbatim.
- Prefer the dedicated file/search tools over shell commands when one fits.
这段文本几乎是 Claude Code 时代终端 Agent 系统提示词的"标准配置":Github-flavored markdown、用户选定权限模式、独立工具调用并行执行、file_path:line_number 可点击引用。它是跨时代最稳定的"化石"——即便内核已经换成自研实现,这段运行时约束仍被逐字保留,并明确注释为"不属于 output style 可替换的 coding instructions",连工作流子代理身份(workflow-actor.ts)都要逐字复用同一份。
协议层面同样留有第一代的印记。在 model-execution.ts 的模型装配层,ZCode 的协议栈是 anthropic-messages 与 openai-chat-completions 双轨并存的——前者让大量现成的 Anthropic 协议客户端可以无缝接入,后者则覆盖 OpenAI 生态。这解释了社区评测中反复出现的"协议兼容"评价:ZCode 从一开始就不是绑定 GLM 私有协议的封闭工具,而是选择了一条"站在成熟协议肩膀上"的兼容路线,这也是它后来能被 DeepSeek、Ollama 本地模型等第三方模型快速接入的根本原因。
一代目的结论很清晰:ZCode 的早期形态是"GLM 的 harness",价值在"接上模型",但技术栈高度依赖外部的 Agent 壳层设计与协议生态。
二代目:开源 CLI 的工程化与 Skill 体系
当 ZCode 从闭源工具走向开源时,第一个要解决的是工程形态问题。仓库根目录 README.md 把产品定位于"AI 编程工作台,提供桌面应用、浏览器界面和终端 Agent",而 Agent CLI 与运行时源码则整体收敛在 apps/zcode-cli/ 下,以普通目录随仓库克隆、无需 submodule。这是一个典型的多包 monorepo:core(Agent 运行时)、adapters(模型与工具适配)、contracts(契约类型)、tui(终端界面)、bootstrap(启动编排)等十几个 workspace 包由 pnpm + turbo 统一构建,Node 版本锁定在 24.14.0,产物可进一步用 SEA(Single Executable Application)打包成单文件。
工程化之外,二代目真正的产品级创新是 Skill 体系。与"提示词模板"不同,ZCode 的 Skill 是可执行的、带门控的代码契约。以官方捆绑的 dynamic-workflows Skill 为例,它定义了完整的编写契约:什么请求该走 CreateWorkflow、什么该用 Agent 工具、子代理拓扑怎么选、命名即身份(同名子代理会让整个 run 失败)、结果如何定型与确认。Skill 甚至能反过来约束运行时——文档明确写道,CreateWorkflow、AmendWorkflow、SaveWorkflow、EvalWorkflowSnippet 四个工具"refuse to run until this skill has been loaded in the session"。这不是一个"可选的增强文档",而是硬性的能力门禁。
插件化是这套体系的落地骨架。apps/zcode-cli/README.md 定义了 plugin.json 清单的能力面:skills、commands、mcpServers、userConfig,支持 ${ZCODE_PLUGIN_ROOT}、${ZCODE_PLUGIN_DATA}、${ZCODE_PROJECT_DIR} 等变量展开,只认 ZCODE_ 前缀的环境变量。官方插件通过市场分发,运行时重的插件(如 ios-simulator、android-emulator)默认禁用、按需启用。这意味着第三方可以把自己的工具链包装成"即插即用"的 Agent 能力,而不必改一行内核代码。
二代目还有一个容易被忽视的工程化亮点:prompt-trajectory 轨迹录制工具。它以 OpenAI 协议代理的方式拦截 zcode-cli 的模型请求,把流式增量拼装成完整 assistant 消息,落盘为 trajectory.jsonl,再派生 OpenAI / Anthropic 两种协议形态的完整请求体快照,甚至可以读取真实会话的 model-io-*.jsonl 反推 prompt 组装轨迹。社区文章把这一功能称为"录制与反推 zcode-cli 的 Prompt 组装轨迹",其价值在于:当 Agent 的上下文组装从"一段拼好的字符串"退化成"需要被审计和调试的产物"时,轨迹录制就是 Agent 可解释性的基础工程。同一时期,仓库还配套了架构治理脚本(scripts/architecture/)与 AGENTS.md 中的模块边界规范,把"Agent 运行时不得反向依赖 UI 实现"这类约束写成了可执行的架构检查。
二代目的结论:开源后的 ZCode 完成了从"模型 harness"到"可扩展工程平台"的转身,Skill/插件/MCP 三件套构成了它的生态面,而轨迹录制与架构治理则标志着它开始按"严肃基础设施"的标准来要求自己。
三代目:自研 Agent 内核意味着什么技术路线转向
社区情报中最有分量的信息来自 OSCHINA 的报道:ZCode 3.0 正式发布,全面切换自研 ZCode Agent 内核。这次切换不是品牌话术,它在仓库源码里留下了可以逐层验证的印记。
最外层是模型适配的"去单一依赖"。虽然 model-execution.ts 仍基于 Vercel AI SDK 做 provider factory 装配(@ai-sdk/anthropic、@ai-sdk/openai、@ai-sdk/openai-compatible),但上层已经长出了完整的自研 Provider 配置体系:config/provider/zcode-builtin.json 内置了 Z.ai 的 Coding Plan 与标准 API 两套模板,覆盖 anthropic-messages 与 openai-chat-completions 两种协议,内置 GLM-5.3、GLM-5.3-Flash、GLM-5V-Turbo 直至 GLM-4.5-Air 的完整模型梯度。模型不再是"接进来的外挂",而是被纳入了可配置、可审计的注册表。
往内一层是 Agent 执行内核。三代目之前,终端 Agent 的回合循环高度依赖外部 harness 的既定实现;而现在的 core 包内部是一套完整的自研状态机体系:TurnMachine 管理回合生命周期的每一跳——模型请求、流式响应、工具调度、权限请求与裁决、结果聚合、终止或失败;ContextBuilder 把上下文拆成 20 类可独立缓存、可独立注入的分节(identity、env_info、skills、tools、memory、output_style、context_management……),每节带 token 估算与缓存提示,解决的是长会话下"哪些 prompt 该常驻、哪些该按需加载"的系统性问题。权限不再是简单的"同意/拒绝",而是独立成 permission 服务,配合 hooks 工作区钩子体系与 memory 长期记忆,构成了一个"模型只负责生成意图、内核负责裁决执行"的分层结构。
最核心的证据在动态工作流(Dynamic Workflow)上。这是三代目"自研"含金量最高的部分:ZCode 没有停留在"提示模型去编排子代理"的软性方案,而是为多代理协作设计了一门专用脚本语言和一个配套的编译-分析-沙箱执行管线。
- 语言与编译器在 dynamic-workflow 包中:
compileWorkflowScript做编译,analyzeWorkflowScript做静态分析,产出站点图(site graph)、因果图(causality graph)、actor 图、交接图(handoff graph)、控制流图(flow graph)等可序列化的投影——这些分析不是装饰,而是用来在脚本运行前就发现重复命名、fan-out 死锁、数据流污染这类编排缺陷。 - 运行在 dynamic-workflow-runtime 包中:父进程 harness 把 lowered 后的脚本体写进
.zcode/workflow-runs/<runId>.mjs,spawn 一个受控子进程,通过 NDJSON 桥接子进程的__host.*调用与引擎的ask,最终由引擎裁决 run 的结算(completed / failed / stopped)。子进程有墙钟超时、堆上限,甚至适配 SEA 单文件二进制的特殊 spawn 路径。
这个设计的技术含义是:多代理编排从"模型的自由发挥"变成了"可编译、可分析、可沙箱隔离的程序"。fan-out(items.map((i) => agent(...).ask(...)))有了明确的并行语义,共享上下文导致的隐式串行化有了可诊断的因果图,恶意或错误的脚本在触碰真实文件系统之前就被世界读取能力(world-read caps)等能力边界拦下。
三代目的定位从社区视角也能得到印证:智谱官方披露 ZCode 用户突破 100 万;开源后围绕"代码上传"的争议促使官方公开了补偿方案,而开源社区反而借审计网络请求回应了"偷代码"质疑——一个 Agent 内核是否可信,最终要落到"代码是否可读、请求是否可审计"上,这正是自研内核在工程透明性上的直接回报。
技术路线转向的实质
把三代并置看,转向的实质有三层。第一层是从"接模型"到"管执行":一代目把模型接上工具就完成了使命,三代目则要求内核拥有回合状态机、分节化上下文、权限裁决和运行沙箱,模型只是内核里一个可替换的"生成器"。第二层是从"借生态"到"造标准":协议上仍兼容 Anthropic/OpenAI 双轨(这保住了生态迁移成本),但编排语言、插件清单、内置 Provider 注册表都是自己的——兼容是手段,自主是目的。第三层是从"黑盒"到"可审计":prompt-trajectory 录的是模型输入,架构治理查的是模块边界,工作流静态分析审的是并发与数据流,一套自研内核最终把"Agent 在干什么"从不可知变成了可回放、可检查的工程对象。
ZCode 的路线图给 AI 编程赛道提供的样本是:终端智能体的护城河不在模型,而在"模型和世界之间那层壳"的自主程度。当 GLM 已经站在模型侧持续迭代时,ZCode 选择了把壳也变成自己的——这才是 3.0 切换内核这句话背后真正值得读的架构语义。