用 ZCode 创造 AI Passport 玩法

ZCode 是智谱推出的桌面 AI 编程工具，深度适配 GLM 编程模型，可以打开本地工作区，由 Agent 规划任务、修改代码、运行命令，并在侧边栏查看改动和进度。

• 开发方：北京智谱华章科技股份有限公司（Z.ai）
• 支持系统：macOS（Apple 芯片与 Intel），Windows（x64 / ARM64），Linux（测试版）
• 使用前提：智谱账号；使用 GLM 编程模型需要 GLM Coding Plan 或可用额度
• 本教程使用的版本：3.16.3

从官方网站下载安装包：zcode.z.ai↗。请只使用官方渠道，不要安装来源不明的打包版本。

• 在官网点击「立即下载 ZCode」；需要其他系统或芯片版本时点击「查看全部下载」
• macOS：打开 .dmg，把 ZCode 拖进「应用程序」文件夹
• Windows：运行 .exe 安装程序；Linux 可选择 .deb、.rpm 或 .AppImage

首次打开时登录智谱账号，然后在输入框下方确认模型和权限。本教程使用 GLM-5.3-Flash（思考强度「最高」），权限为「变更前确认」：Agent 每次修改文件或运行新命令前都会先弹出确认。

点击「新建任务」（⌘N），在输入框上方点击「选择项目」→「创建项目」，填写项目名称，点击「选择文件夹」打开 AI Passport 项目文件夹，最后点击「信任文件夹并创建」。

新建一个会话，把下面的提示词复制到输入框，把【填写应用需求】换成你想做的玩法，再发送。本教程的示例需求如下：

请基于完整项目 https://gitee.com/FoloToy/ai-passport 开发；本地已有项目则复用。
先读 AGENTS.md 和 docs/README.md，按需查阅相关文档、硬件接口及示例，自行准备环境并安装项目要求的 Skill。
保留已有修改，新建分支开发。复用 BSP，重新设计应用界面，不照搬 demo；中文界面检查字体覆盖。关键需求不明确时询问，其余自主完成。
运行项目验证，交付可从 0x0 刷写的合并固件，说明测试结果与未验证项。完成后主动询问是否刷机测试，未经确认不烧录。

• 一个番茄钟：开机进入 25 分钟专注倒计时；确定键开始 / 暂停，上下键在未开始时把时长调整为 5–60 分钟（每次 5 分钟）；倒计时结束时屏幕醒目提示并播放提示音，按确定键回到初始状态

ZCode 会新建 feature/pomodoro-timer 分支，安装项目要求的 passport Skill，阅读文档后编写倒计时逻辑、中文界面和提示音，并生成界面用到的中文字体。在「变更前确认」模式下，每条新命令都会弹出「需要权限」卡片：只读命令和项目内的构建、测试命令可以选「始终允许此命令」，修改文件时逐次选「允许」；写入项目以外位置的命令请选「拒绝」。

本次示例用时约 1 小时 50 分钟（包括多次确认权限和模型服务重连的等待）。ZCode 报告项目的完整验证脚本 ./tools/validate.sh 全部通过（包括仓库检查、电脑端测试和固件构建），新增了倒计时状态机测试和中文字体覆盖测试，交付合并固件 build/FoloToy-AI-Passport-full.bin（853,712 字节，从 0x0 写入），并附上 SHA-256 校验值。

• 点击「15 个文件已更改」可以展开查看每个文件的改动；需要放弃全部改动时可以点「撤销」
• 界面里的中文使用 ZCode 自动生成的字体（约 117 个字），改动文案后要让它重新生成字体并运行覆盖测试
• 报告的「Unverified」列出了需要安装到设备后确认的内容：中文显示效果、提示音音量、按键手感、电量显示和倒计时精度
• 报告里的「假设与取舍」说明了第一版的简化，例如重启后回到默认 25 分钟、暂停时不能调时长；不符合预期时直接在同一个任务里提出修改
• Agent 询问是否刷机时，设备没准备好就回复「暂不刷机」

打开本地玩法安装工具↗，选择 Agent 交付的合并固件（从 0x0 写入的 .bin 文件），用支持数据传输的 USB-C 线连接 AI Passport 并开始安装。完成后设备自动重启，逐项检查屏幕、按键和声音。

• 安装新玩法会覆盖设备当前的全部内容；之后可以随时恢复默认固件
• 安装过程中不要拔线或关闭页面
• 把与预期不一致的画面和按键表现描述给 Agent，让它继续修改并重新构建

使用 ZCode 开发 AI Passport 玩法时，可能遇到以下情况：

• 提示「服务繁忙」或额度不足：换用 GLM-5.3-Flash 等负载较低的模型，或确认 GLM Coding Plan / 账户额度可用
• 提示「Cannot connect to API: Connect Timeout」：当前任务选中了无法访问的自定义模型服务。登录智谱账号后新建任务，并在模型菜单里选择 GLM 模型
• 确认弹窗太多：对只读和项目内的构建、测试命令选「始终允许此命令」；不建议选「完全访问」，它会让 Agent 不经确认执行任何命令
• 模型服务中途断开、反复重连：停止当前这一轮，在同一个任务里发送「继续」，Agent 会接着已有的修改往下做
• 构建环境缺失：让 Agent 按项目文档准备 ESP-IDF 5.5.3；已经安装过时，可以提示它通过 IDF_PYTHON_ENV_PATH 使用现有的 Python 环境
• Agent 想把文件写到项目外（如 /tmp 或用户目录下的 Skill 文件夹）：选「拒绝」，并告诉它「所有依赖、缓存和临时文件都放在项目的 build/ 目录内」