首页 / 阶段一 / ZCode
ZCode：图形界面里第一次看 diff
智谱做的 Agentic Development Environment——名字很拗口，其实就是一个「给 AI 用的代码工作台」。它把终端里那些抽象的「agent 正在改文件」变成可视化：哪个文件被动了、加了哪几行、你要不要接受。这是从「点鼠标」走向「用命令行」之间最好的一块跳板。
一句话定位
带界面的编码 agent。适合「不想学命令行，但想用 AI 改代码/改文件」的人；也适合已经在用 Codex 的人，用来更直观地审 diff。
01它和 VS Code 的区别
不是同一类东西。VS Code = 你写代码，插件辅助你。ZCode = 你说需求，agent 动手写，你审。所以它的界面重心不在编辑器，而在对话、任务步骤、改动预览这三块。
| 界面区域 | 作用 |
|---|---|
| 左侧项目 / 文件 | 打开你要操作的文件夹。它只会在这个范围内读写。 |
| 中间对话区 | 你提需求，它边干边说：读了哪个文件、准备改哪里、执行了什么命令。 |
| 改动预览（diff） | 每处修改以「旧行删除 / 新行增加」的形式列出，你逐条接受或拒绝。这个是核心。 |
| 子智能体 | 内置 general-purpose（通用执行）和 Explore（只读探索）两类。复杂任务会派子 agent 去搜索、去试。 |
| 模型 / 提供商 | 设置里选 Z.AI、BigModel，或填自己的 API Key。 |
02安装
- 打开 zcode.z.ai，按你的系统下载（支持 macOS、Windows、Linux）。
- 双击安装，Windows 遇到 SmartScreen 点「更多信息 → 仍要运行」。
- 首次启动会进入配置向导，让你选模型提供方。这一步别乱点「跳过」，否则后面发消息会提示没有可用模型。
它的源码在 GitHub 上公开（zai-org/ZCode）。想确认它到底会碰你电脑上什么，可以去看源码——这也是开源工具相对闭源工具的一个实际好处。
03接模型：三条路，选一条
ZCode 本身只是一个壳，真正干活的是背后的模型。三条路门的门槛和花钱方式都不同：
路径 A：Z.ai 账号（最省事）
- 在配置向导里选 Z.AI。
- 按提示登录 Z.ai 账号。有订阅的话额度直接可用。
- 没有订阅会提示你去充值或购买 GLM Coding Plan。
路径 B：BigModel（国内站）
- 配置里选 BigModel（智谱的国内开放平台）。
- 去开放平台注册、实名、创建 API Key。
- 把 Key 填进 ZCode 对应的输入框。务必打开该提供商的「启用」开关，只填 Key 不开开关是不会生效的。
路径 C：自己的 API Key（接任何兼容模型）
GLM 的 Coding Plan 同时兼容 OpenAI 与 Anthropic 两套协议，也就是说：把 Base URL 换成智谱的地址、填上你的 key，就能让原本只支持 OpenAI/Anthropic 的工具走 GLM。反过来，ZCode 里也可以填别的兼容服务。
提供方：自定义 / OpenAI 兼容 Base URL：https://…（控制台里复制的那个，通常带 /v1） API Key：sk-… 模型名：控制台里列出的模型 ID
三种最常见的「配好了但不能用」
- 开关没打开：填了 key 但提供商那一行是灰色的。回去把启用打开。
- Base URL 少了 /v1：不同服务要求不同，报 404 基本就是路径不对。
- 账户没余额：报 401/403 不一定是 key 错，也可能是欠费。
04第一次用它改点东西
别拿重要项目练手。按下面这个流程走一遍，你会同时学会「怎么下指令」和「怎么审 diff」。
- 新建一个空文件夹，比如
D:\ai-test\zcode-01，在 ZCode 里打开它。 - 让它建点东西：「新建一个 index.html，做一个只有标题和一段介绍文字的页面，中文内容，风格简洁，不要用外部资源。」
- 看它的执行过程：它说要创建文件时，注意它有没有真的创建、创建在哪。
- 第二轮：「把标题字号改大一点，加一个按钮，点击后弹出提示。」
- 这时会出现 diff（改动预览）。逐行看：它有没有顺手删掉你认为该保留的东西？有没有加你没要求的样式？
- 接受或拒绝。拒绝时给它理由，它会重新改。
- 用浏览器打开那个 html 文件，看结果对不对。
这一遍走完，你就掌握了这类工具的通用工作流：开目录 → 提需求 → 看过程 → 审 diff → 验收。Codex 和 Claude Code 只是把这套流程搬到了命令行里。
05基本用法与技巧
| 场景 | 怎么做 |
|---|---|
| 只想知道「这段代码干嘛的」 | 用 Explore 类子智能体或直接问，明确说「只读，不要修改任何文件」。 |
| 改一个具体 bug | 给出三样东西：报错原文、复现步骤、相关文件路径。只给「有个 bug」它只能猜。 |
| 改动范围太大不敢信 | 要求「先给方案，不要动文件」。方案确认后再说「按方案执行」。 |
| 它改错了想回退 | 项目里有 git 就 git checkout .；没有 git 就在 diff 阶段逐条拒绝。 |
| 同类任务反复做 | 建自定义子智能体：把角色、约束、常用路径写进去，下次直接调用。 |
| 想知道它花了多少钱 | 看会话用量统计。agent 一轮任务可能调用模型几十次，成本意识和命令行工具一样要有。 |
06三个实战
实战一：给直播工具写个辅助脚本
需求说清：「写一个 Python 脚本，扫描 D:\直播素材 目录，把每个子文件夹里的视频按修改时间排序列出来，输出成一个 csv。不要动原文件。」 这类「只读 + 汇总」的任务最安全，也最容易一次成功。
实战二：把一段 Excel 数据变成网页图表
把 CSV 放进项目目录，说：「用这个 csv 的数据做一个单页 HTML，画一张柱状图，横轴是月份，纵轴是销量，中文标签，不要联网加载任何库。」 它需要自己写图表代码——正好检验它改文件的准确性。
实战三：批量重命名与整理
这是最能体现「agent 比聊天框强」的地方。「D:\直播素材 下有 200 个文件，命名是乱的。按 日期_主题_序号 的规则重命名（日期从文件的创建时间取），重命名前先把清单打出来给我确认。」 加最后一句，避免它一上来就动手。
07踩坑与排错
| 现象 | 原因与处理 |
|---|---|
| 发消息后一直没反应 / 提示无模型 | 提供商没启用，或 key 无效。回设置里确认「启用」开关和余额。 |
| 报 404 / 模型不存在 | Base URL 或模型 ID 填错。从控制台原样复制，别手打。 |
| 它说改了，但文件没变 | 改动可能停在「待接受」状态。去 diff 面板点接受。 |
| 中文路径报错 | 把项目放到纯英文路径下（如 D:\projects\demo）再试。这类兼容问题在国产工具里也偶发。 |
| 它一次改太多文件 | 下指令时限定范围：「只改 src 目录下，不要碰配置和依赖文件」。 |
| 装了但打不开（Windows） | 确认系统版本、是否有安全软件拦截；必要时用管理员权限安装一次。 |
08学完这一课你应该会
- 看懂 diff：红色是删的、绿色是加的，自己判断这次改动是不是你要的。
- 限定范围：在指令里写清「只动哪些文件/目录」，而不是让它自由发挥。
- 先方案后执行：大改动前要求它出方案，这是控制风险最有效的一句话。
这三件事，在 Codex、Claude Code、OpenClaw 里一模一样适用，只是没有图形界面帮你画出来。
官方入口：zcode.z.ai · 中文文档 zcode.z.ai/cn/docs
开源仓库：zai-org/ZCode。模型地址、价格、套餐内容以智谱官方控制台为准，本文不写具体价格。