智谱 ZCode 上手:GLM-5.3 开源编码 Agent 实战

一、背景与问题

过去一年,编码工具的形态发生了一次明显的迁移:从 IDE 里的“自动补全”,到聊天面板里的“帮我改这段代码”,再到现在的 Agent 中心化——不再是你写代码、AI 补全,而是你描述目标,Agent 自己规划、执行、验证。ZCode 就是这类 ADE 的典型代表。

它要解决的核心问题,是 Long Horizon Task(长程任务)的稳定性:普通对话式编码助手改到一半就丢上下文、长任务执行到后面偏离最初目标。ZCode 的思路是,把 GLM-5.3 的 1M 稳定上下文、长程规划和 Agentic Coding 强化训练能力,通过工作区状态、文件引用、执行模式、Git 分支信息完整地释放出来,让一个任务从“需求理解”一路推进到“落地改动”。

选择它的理由很直接:国产开源、中文文档齐全、多入口(桌面 / Web / 终端),而且 9 月 22 日刚冲上 GitHub 热度榜第一——现在正是上手尝鲜的最佳窗口。

二、环境与前提

动手前先确认四件事:

操作系统:支持 macOS(Apple Silicon / Intel)、Windows(x64 / ARM64)、Linux(x64 / ARM64)。Linux 提供 AppImage、DEB、RPM 三种格式。
模型:ZCode 深度适配 GLM-5.3 系列,需要智谱 BigModel 平台的 API Key(首次启动时在左下角“连接使用”登录绑定)。其他主流模型也能接,但长任务体验以 GLM-5.3 为最佳。
Node.js:直接使用发行版不需要;只有从源码构建仓库时才要求 Node.js 24.14.0 + pnpm 10.33.2(版本以仓库根目录 mise.toml 为准)。
下载渠道:官方站 zcode.z.ai/cn,当前最新桌面版为 v3.14.3。

三、实操步骤

3.1 下载并安装

到 zcode.z.ai/cn 下载对应平台的安装包,安装方式与常规桌面软件一致:

macOS:打开 .dmg,把 ZCode.app 拖入“应用程序”。
Windows:运行 .exe 安装向导。
Linux:下载 .AppImage(或 deb/rpm),先加可执行权限再运行:

chmod +x ZCode-*.AppImage
./ZCode-*.AppImage

3.2 首次启动:连接模型

首次启动会进入设置向导,完成后点击左下角「连接使用」登录 BigModel 账号,绑定 GLM-5.3 模型。注意两个关键默认值:

执行模式默认是「变更前确认」:Agent 每次修改文件或执行命令前都会先征求你同意,这是最稳妥的档位,新手不要动它。
输入框里可以直接切换模型和「推理强度」——复杂任务开最高档,日常小改动用低档省钱省时间。

3.3 跑第一个任务:理解工作台的输入语法

ZCode Agent 的输入框不是普通聊天框,它支持四种上下文符号,记住它们,效率直接翻倍:

入口	触发符号	作用
添加附件	—	上传截图、文档、需求材料作为任务上下文
插入 @ 提及	`@`	引用工作区中的文件或整个文件夹,让 Agent 精准定位代码
插入 # 会话	`#`	关联历史对话,把已有任务的上下文带进来
插入 / 命令	`/`	调用已保存的命令,复用固定提示词或流程

另外 $ 可以调用技能。一个标准的任务开场可以是这样:

@src/utils/format.ts 这个文件里日期格式化函数有 bug,
当月份小于 10 时输出少一位,请修复并补上单测。
改完先跑 pnpm test 确认通过再提交。

Agent 会先给出改动计划,进入「变更前确认」流程,逐项执行后把结果和测试输出带回对话。把“目标 + 上下文 + 验收标准”一次性说清楚,是长任务成功的关键。

【配图:ZCode输入框与四档执行模式切换示意】

3.4 用 AGENTS.md 给 Agent 立规矩

想让 Agent 长期遵守项目约定,在仓库里放一个 AGENTS.md。ZCode 启动任务时会读取它,并把其中的约定注入给 Agent。它读取两个来源:

用户全局指令:~/.zcode/AGENTS.md——跨项目通用的个人偏好;
Workspace 指令:当前工作区根目录的 AGENTS.md——本项目专属约定,优先级更高。

一个可用的示例:

# 项目约定

协作方式:先给方案再动手,不做与需求无关的重构

更进一步的,可以打开项目记忆(设置 → 常规 → Memory):开启后,每轮任务顺利结束,Agent 会把可复用的事实(比如“这个项目用 pnpm”“测试要跑哪个命令”)自动记下来,后续会话自动带上。注意这个开关默认是关闭的。

3.5 进阶:终端 CLI 与远程机器人

不装桌面版也能用。发行版自带 zcode 命令,终端里直接开 TUI,或启动本地 Web 工作台:

# 默认进入终端交互界面(TUI)
zcode

启动 Web 界面
zcode --web
指定项目目录和端口,不自动打开浏览器
zcode --web --workspace /path/to/project --port 3030 --no-open
查看帮助

zcode --help

Web 模式默认监听 127.0.0.1 并自动打开浏览器;需要局域网访问时加 --host 0.0.0.0,此时会自动生成访问令牌。

另外,ZCode 支持把任务挂到飞书、微信、Telegram 的机器人上——在群里 @ 机器人就能触发并执行任务,适合“人在外面,活先干着”的场景。

四、坑点与注意事项

上手过程里这几个坑最值得提前知道:

CLAUDE.md 只会迁移一次:老 Claude Code 项目的 CLAUDE.md,ZCode 只在 onboarding 阶段一次性复制到 AGENTS.md,之后以 AGENTS.md 为准,不会再持续读取 CLAUDE.md。
AGENTS.md 只读两个来源:不会扫描子目录,也不支持 @import / @include。最重要的规则放工作区根目录那一份。
项目记忆默认关闭:想要“越用越懂你”的效果,记得手动在设置里打开。
非项目对话不会自动清理:在“不在项目中工作”模式下创建的临时文件会留在磁盘上,关掉对话也不删,记得自己清理。
安全模式别急着调低:“变更前确认”是默认档,用 Shift + Tab 可以循环切换四档模式。处理关键代码、生产配置时,建议保持确认档。
源码构建版本锁死:仓库要求 Node.js 24.14.0 与 pnpm 10.33.2,版本不符会直接失败;普通用户直接下发行版即可,没必要走源码。
Star 数与版本是快照:本文数据截至 2026 年 9 月 23 日,具体用法以官方文档(zcode.z.ai)为准。

五、总结

ZCode 把“Agent 中心化”的开发体验落成了一个可以日常使用的产品:GLM-5.3 的长程能力、四档安全确认、AGENTS.md 规则注入、项目记忆,再加上终端 / Web / 机器人多入口。如果你想体验国产开源编码 Agent 的第一梯队,现在从官网下载、连上模型跑一个真实任务,是最直接的判断方式。