ZCode

01 学习交流群

知识库之外，我们还建了「主流 Agent 入门交流群」。

进群和大家一起交流主流 Agent 的使用方法、适用场景和入门实践，分享不同工具的上手经验、工作流与真实案例，也会同步专题最新更新和实战资料。

扫码加入，一起找到适合自己的 Agent，真正用起来。

02 学前须知

本教程配套代码素材：https://gitee.com/geektime-geekbang_admin/ai-tutorial-material/tree/master/zcode-materials

03 先认识-ZCode

这一课不安装软件，也不写代码。先弄清 ZCode 会做什么、你要控制什么。等下一课真正让 Agent 读取本地文件时，你会知道哪些操作只是分析，哪些操作会改变电脑上的状态。

完成本课后，你应该能解释一次 ZCode 任务如何从要求变成实际文件，并能为课程项目划出一个安全工作区。

ZCode 不是只给答案的聊天框

ZCode 官方把产品称为 Agentic Development Environment，中文可以理解为“以智能体为中心的开发环境”。普通聊天工具通常给出建议或代码片段；ZCode Agent 还可以结合当前工作区，读取文件、修改文件、执行命令、打开网页，并继续根据实际结果调整下一步。官方产品介绍

这意味着你和 Agent 的关系不是“提问—收到答案”，而是一个控制循环：

1. 你说明目标、范围和验收标准。
2. Agent 读取当前工作区，判断需要哪些操作。
3. 它提出或执行文件修改、命令和工具调用。
4. ZCode 把结果重新交给 Agent，Agent 决定是否继续。
5. 你检查实际文件和运行结果，决定任务是否真的完成。

最后一步不能省略。模型可能误解需求，也可能在正确文件里写入错误逻辑。以后每一课都会保留一个独立检查，不把“Agent 说已经完成”当作证据。

四个需要分清的对象

工作区决定它从哪里开始看

工作区通常是一个项目文件夹。Agent 会围绕这里的文件和命令结果开展工作，所以打开了哪个文件夹，比提示词写得多漂亮更重要。

这套课程使用一个单独的空文件夹：

focus-board/

不要把“桌面”“文档”或整个用户目录直接作为练习工作区。里面可能有私人文件，也会让 Agent 面对大量无关内容。

任务保存一次工作的上下文

任务包含你的消息、Agent 的回复、工具结果和修改记录。同一个项目可以有多个任务，例如“制作初版”“修复筛选问题”“审查发布前改动”。后面的课程会逐步使用这种拆分方式；现在只需记住：任务不是项目本身，关闭对话也不会自动删除已经生成的文件。

工具把文字变成真实操作

Agent 的回复只是文字；文件编辑、终端命令、浏览器和 Review 面板才会改变或验证项目。ZCode 把这些工具放在同一个工作台中。例如，HTML 文件可以从文件树用内置浏览器打开，终端可以运行构建或测试命令，Review 用来检查实际改动。智能体开发环境工具

执行模式决定何时停下来问你

ZCode Agent 当前提供四种执行模式：变更前确认、自动编辑、计划模式和完全访问。课程开始时使用默认的“变更前确认”：文件修改和命令执行前先让你看清准备做什么。安全操作确认

不要把“允许”理解成“这一步肯定正确”。它只表示你允许操作发生。看到确认请求时，至少检查三件事：

• 路径是否位于本课工作区；
• 操作是否与当前任务有关；
• 是否包含删除文件、安装软件、联网提交数据等额外影响。

不确定时选择仅允许当前一次，不要急着使用“始终允许”。

课程项目要做到什么

我们要制作一个纯本地网页“今日专注清单”。第一版只做四件事：

• 输入一件准备完成的事情；
• 将它加入列表；
• 标记完成；
• 删除不再需要的事项。

第一版不用账号、数据库、云服务或第三方框架。这样设计不是为了做一个功能很少的展示页，而是把注意力放在 Agent 协作本身：它改了哪些文件、页面能否工作、你如何证明结果正确。

项目最终会逐步增加持久化、筛选、移动端检查、缺陷修复、周统计和数据导出。每项能力都在出现真实需要时再学。

先写下验收边界

在安装前，先保留下面这张任务卡。你可以复制到自己的笔记中；第 3 课会把它变成给 Agent 的正式要求。

项目：今日专注清单

工作区：只使用 focus-board 文件夹
技术范围：原生 HTML、CSS、JavaScript
第一版必须做到：添加、完成、删除事项
第一版暂时不做：登录、云同步、数据库、框架、部署
验收方式：自己在浏览器中逐项操作，并检查生成的文件
安全规则：不粘贴密钥；不允许修改工作区外的文件；不盲目选择“始终允许”

检查你是否掌握了边界

先判断下面三种情况该怎么处理，再对照后面的参考判断。

1. Agent 准备在 focus-board/index.html 中写入页面结构。
2. Agent 准备删除你“文档”目录下一个同名文件夹。
3. Agent 说页面已经完成，但没有打开页面，也没有给出测试结果。

参考判断：

1. 路径和任务一致，可以查看具体改动后允许一次。
2. 路径超出工作区，应拒绝并要求它只处理 focus-board。
3. 不能算完成；需要打开页面，亲自执行添加、完成和删除，并查看实际文件。

如果你的判断与上面一致，本课目标已经达到。你的电脑目前还没有因为课程发生任何项目改动；下一课会安装 ZCode、建立 focus-board 工作区，并进行一次只读验证。

04 安装与首次验证

这一课把 ZCode 安装好，连接一个可用模型，再让 Agent 读取一个空工作区。结束时，focus-board 文件夹仍然应该是空的；我们只验证连接和工作区是否正确，不提前生成项目。

开始前准备

你需要：

• 一台 macOS、Windows 或 Linux 电脑；
• 能下载 ZCode 安装包的网络；
• 一个 BigModel 账号，或你已经拥有的其他受支持模型凭据；
• 在容易找到的位置新建一个空文件夹，名称为 focus-board。

中国大陆个人用户建议走本课的 BigModel 账号登录主路径。它不要求你手动填写接口地址，也能避免把 Coding Plan 端点和通用 API 端点混在一起。是否需要付费、当前可用模型和额度，以登录后页面的实时显示为准，本教程不固定这些易变化的信息。

从官方页面下载安装

打开 ZCode 官方安装页，确认地址栏域名是 zcode.z.ai，再选择自己的系统和处理器架构。官方当前支持 macOS 的 Apple Silicon / Intel、Windows 的 x64 / ARM64，以及 Linux 的多种安装格式。

macOS

1. 下载与你芯片对应的 .dmg。
2. 打开安装镜像，把 ZCode.app 拖入“应用程序”。
3. 从启动台或“应用程序”目录启动 ZCode。

如果不知道 Mac 使用哪种芯片，打开左上角苹果菜单，选择“关于本机”。看到 Apple M 系列就选 Apple Silicon；看到 Intel 就选 Intel。

Windows

1. 下载与设备架构匹配的安装程序；多数普通电脑使用 x64。
2. 双击运行并完成安装向导。
3. 从开始菜单或桌面快捷方式启动 ZCode。

Windows 可能弹出防火墙或安全软件提示。先确认安装包来自官方域名，再决定是否放行；不要为了省事永久关闭安全防护。

Linux

根据发行版选择 AppImage、DEB 或 RPM。AppImage 第一次运行前需要可执行权限。先在终端进入安装文件所在目录，再执行：

chmod +x ZCode-*.AppImage

这里的 * 代表文件名中的版本和架构部分。如果目录里有多个 ZCode AppImage，最好改用完整文件名，避免同时修改无关文件。DEB 和 RPM 则使用发行版原有的软件包管理方式安装。

第一次启动是否成功

成功启动后应该看到首次启动设置或 ZCode 工作台，而不是系统安装器。如果应用立即退出或操作系统阻止启动，先回到官方安装页的“故障排查”部分，不要从非官方站点重新下载安装包。

进入工作台并打开空文件夹

首次启动时：

1. 选择“开始使用 ZCode”。
2. 如果出现数据迁移选项，本课程选择跳过。我们不需要导入其他工具的历史对话。
3. 在工作区选择页面打开刚才创建的 focus-board 文件夹。

进入后，看左侧工作区或文件树中的名称。它应该是 focus-board，里面没有 index.html、package.json 或其他项目文件。如果看到个人文档或另一个项目，先关闭当前工作区，再重新打开正确文件夹。

连接 BigModel 账号

如果欢迎页直接显示连接选项：

1. 选择“连接 BigModel 继续使用”。
2. 在弹出的授权窗口登录 BigModel。
3. 完成授权并返回 ZCode。

如果已经进入工作台：

1. 点击聊天输入框内显示的模型名称。
2. 在模型列表底部选择“管理模型”。
3. 进入“设置 → 模型设置”，在左侧选择 BigModel。
4. 完成账号连接，并确认供应商处于启用状态。
5. 回到聊天输入框，选择一个当前账号实际可用的 GLM 模型。

官方连接文档把 BigModel 账号连接列为国内用户的推荐路径；可用模型由账号权限和供应商返回结果决定。连接模型与套餐

如果你只能使用 API Key

API Key 不要粘贴到聊天输入框，也不要写进课程项目文件。只在“设置 → 模型设置”的供应商配置界面填写。

BigModel 有两个容易混淆的 OpenAI 兼容地址：

二者不是可以随意替换的镜像地址。使用哪个取决于你的账号产品。若不确定，优先返回账号授权登录，或根据官方连接文档核对凭据来源。

选择保守的执行方式

找到聊天输入框附近的执行模式选择器，确认当前为“变更前确认”。这是默认档位：Agent 准备修改文件或执行命令时，会先显示请求。

本课只做只读验证。即便如此，保留这个模式仍有价值：如果 Agent 意外提出创建文件或安装工具，你会在操作发生前看到。

进行第一次只读验证

新建一个任务，把下面的内容完整发给 Agent：

请检查当前工作区，只进行只读操作，不要创建、修改、移动或删除任何文件，也不要安装软件。

请告诉我：
1. 当前工作区根目录的名称；
2. 根目录中有哪些文件和子目录；
3. 如果目录为空，请明确写“目录为空”；
4. 你为了得到这些信息实际使用了哪些只读操作。

Agent 可能直接使用工作区信息，也可能申请执行一个列目录的命令。若出现确认请求，先看命令是否只是读取当前 focus-board，路径是否正确。确认是只读操作后，可以仅允许这一次。

预期结果

回复的具体措辞会随模型变化，但应该明确包含：

工作区：focus-board
目录为空

它不应该声称创建了文件，也不应该把其他目录中的内容当作当前项目。

不依赖 Agent 的独立检查

回到左侧文件树，或者在系统的 Finder / 文件资源管理器中重新打开 focus-board：

• 文件夹仍然为空；
• 没有刚生成的 Markdown、配置或代码文件；
• ZCode 当前工作区名称仍是 focus-board。

这一步证明两件事：模型连接可用，Agent 看到的工作区与你检查的是同一个目录。

两个最常见的阻塞

授权完成后仍然没有可用模型

回到“设置 → 模型设置 → BigModel”，依次检查：

1. 账号连接状态是否成功；
2. BigModel 供应商是否启用；
3. 模型选择器中是否出现账号实际有权使用的模型。

不要凭记忆手输一个模型名。可用列表应以供应商返回结果为准。

浏览器能上网，ZCode 却无法连接

如果你的网络必须使用代理，打开“设置 → 常规”，填写 HTTP 代理并保存，然后重启 ZCode。官方说明中特别提醒：代理字段留空表示 ZCode 直连，不会自动读取 HTTP_PROXY 等系统环境变量。因此“终端可以联网”不能证明 ZCode 已经使用同一代理。安装页的网络代理说明

如果你的网络不需要代理，不要照抄别人的本地代理地址；错误的地址反而会让连接失败。

本课结束状态

现在你应该拥有：

• 已安装并能启动的 ZCode；
• 一个已连接、可回复的模型；
• 以“变更前确认”运行的任务；
• 一个仍然为空的 focus-board 工作区。

下一课会第一次授权 Agent 写入文件。我们将只创建三个静态网页文件，并用浏览器亲自检查它们。

05 第一次完整交付

上一课结束时，ZCode 已连接模型，当前工作区是空的 focus-board。这一课会让 Agent 在里面创建三个文件，交付可以直接打开的“今日专注清单”第一版。

本课只实现添加、完成和删除。刷新后数据会消失，这是有意保留的边界；持久化会在第 5 课加入。

先确认起始状态

开始前检查：

• 左侧显示的工作区是 focus-board；
• 文件树为空；
• 聊天输入框附近的执行模式是“变更前确认”；
• 当前选择的模型能够正常回复。

如果你跳过了第 2 课，至少先创建并打开一个独立的空 focus-board 文件夹。不要在已有项目或个人文档目录中完成本课。

把需求写成可验收的任务

一个好请求不需要很长，但应该让 Agent 知道目标、技术边界、允许修改的范围和完成标准。复制下面的请求发送给 ZCode Agent：

在当前空的 focus-board 工作区创建“今日专注清单”第一版。

只创建以下三个文件：
- index.html
- styles.css
- app.js

要求：
1. 只使用原生 HTML、CSS 和 JavaScript，不使用框架、第三方库、CDN、后端或构建工具。
2. 页面包含标题、一句简短说明、一个文本输入框、“添加”按钮和事项列表。
3. 用户可以添加事项、将事项标记为完成、删除事项。
4. 空输入不能创建事项，需要给出清楚的页面内提示。
5. 完成的事项要有明显但仍可阅读的视觉状态。
6. 页面在普通桌面宽度和窄屏下都能正常使用。
7. 本课不使用 localStorage，刷新后数据可以清空。

请先用几句话说明准备创建什么，再执行文件修改。完成后列出实际创建的文件，并说明每个文件的职责。不要安装依赖，不要修改工作区以外的内容。

这里特意写明“不使用 localStorage”。它防止 Agent 提前完成后续课程内容，也让这一课的验收更明确。教学项目中，清楚写出“暂时不做什么”和写出功能列表同样重要。

审核第一次文件修改

在“变更前确认”模式下，Agent 准备写文件时会暂停并显示操作。不要直接连续点击允许，先逐项看：

• 目标路径是否都在 focus-board 下；
• 是否只有 index.html、styles.css、app.js；
• 是否出现删除、安装依赖或访问外部服务；
• HTML 是否引用本地的 styles.css 和 app.js，而不是远程 CDN。

符合要求时，对当前文件操作选择“允许”。如果它准备创建 package.json、下载依赖或改工作区外的文件，选择拒绝，并补充：

请遵守原任务边界：只在当前工作区创建 index.html、styles.css 和 app.js，不安装任何依赖。

为什么这次不用“完全访问”

任务虽然简单，但这是你第一次让 Agent 写本地文件。保留逐次确认，可以把“自然语言要求”与“真实文件操作”对应起来。等后面熟悉项目结构并且任务风险较低时，再判断是否减少确认。

先检查交付物，不急着相信总结

Agent 回复完成后，在文件树中应该看到：

focus-board/
├── index.html
├── styles.css
└── app.js

分别单击三个文件，做一次快速检查：

• index.html 中有输入框、添加按钮、事项列表容器，并引用另外两个本地文件；
• styles.css 中有页面布局和完成状态的样式；
• app.js 中有添加、切换完成状态和删除事项的逻辑；
• 三个文件中没有真实 API Key、账号信息或与你无关的绝对路径。

代码写法可能与别人的结果不同。这里检查的是职责和边界，不要求每一行完全一致。

在内置浏览器打开页面

在左侧文件树中右键 index.html，选择“用内置浏览器打开”。ZCode 会在右侧浏览器面板新建标签并渲染本地 HTML。官方文档说明，这个菜单只在本地工作区提供，内置浏览器支持直接打开 file、http 和 https 地址。智能体开发环境工具

预期看到：

• 页面标题“今日专注清单”或意思一致的标题；
• 一个可输入文字的文本框；
• 一个清楚标注的添加按钮；
• 列表为空时的合理空状态，而不是报错或一片空白。

如果浏览器显示的是源代码而不是网页，确认你使用的是“用内置浏览器打开”，而不是普通文件预览。

完成四项人工验收

不要只看页面外观。按下面的顺序实际操作，每项都观察页面变化。

1. 添加事项

输入：

整理本周计划

点击“添加”。列表中应该出现这条事项，输入框通常会被清空。

2. 阻止空事项

保持输入框为空，再点击“添加”。列表不应增加空白行，页面中应出现清楚的提示。浏览器原生校验或页面自定义提示都可以，但用户必须知道为什么没有添加成功。

3. 标记完成

点击事项旁的复选框或完成控件。该事项应进入明显的完成状态，例如文字增加删除线、颜色减弱或卡片状态改变。文字仍应能够阅读。

4. 删除事项

点击这条事项的删除按钮。事项应该从列表消失，页面回到空状态。

四项都通过，才说明第一版功能闭环成立。

再做两个独立检查

刷新页面

先添加一条事项，然后刷新浏览器。数据应该消失。当前阶段这是正确结果，因为请求明确禁止使用 localStorage。如果刷新后数据仍在，说明 Agent 超出了本课范围；可以让它移除持久化逻辑，保持第一版简单。

检查实际文件数量

查看左侧文件树，确认工作区仍然只有本课约定的三个文件。Agent 的文字总结不能代替这一步。

页面不工作时检查什么

页面有内容，但样式完全没有生效

打开 index.html，检查样式引用的文件名是否与 styles.css 完全一致。大小写在部分系统上也有区别。引用通常应是相对路径，而不是指向另一个电脑位置的绝对路径。

点击“添加”没有反应

先检查 index.html 是否引用了 app.js，再打开内置浏览器的开发者工具查看控制台第一条红色错误。把错误文字和相关文件一起交给 Agent，比只说“按钮坏了”更容易定位：

点击“添加”没有反应。浏览器控制台第一条错误是：
（在这里粘贴错误文字，不要粘贴账号或密钥）

请只检查 index.html 和 app.js，先解释原因，再做最小修复。

Agent 生成了额外文件

先不要手动乱删。让 Agent 说明每个额外文件的用途。如果它们不属于需求，要求它只删除自己刚创建的额外文件，并在确认请求中核对精确路径。删除比创建更难恢复，因此不要使用含糊的“清理一下项目”。

本课结束状态

你已经完成了第一个完整的 ZCode 交付循环：

写出边界明确的需求
→ 审核文件操作
→ 查看真实文件
→ 打开页面
→ 人工执行功能验收
→ 检查范围是否超出

工作区现在应包含三个文件，页面支持添加、完成和删除，但刷新后不保存数据。下一课会在这个准确状态上创建 AGENTS.md，学习怎样把技术范围和验证要求变成项目的长期约定，而不是每次都重新输入。

06 上下文计划与项目约定

第 3 课结束时，focus-board 已经有 index.html、styles.css 和 app.js，能够添加、完成和删除事项。现在要做一次小升级：显示事项统计，并把窄屏布局整理得更稳。

这次不直接把所有要求塞进一条消息。我们先把长期有效的规则写进 AGENTS.md，再用文件引用和计划模式完成修改。

临时要求和项目规则不是一回事

“这次给按钮换个颜色”只影响当前任务，适合写在消息里；“项目只用原生 JavaScript，不安装依赖”会影响以后每次修改，适合写进项目根目录的 AGENTS.md。

ZCode 会在任务开始时读取两个来源：用户级的 ~/.zcode/AGENTS.md，以及当前工作区根目录的 AGENTS.md。本教程只创建工作区文件，不修改全局规则。官方文档也提醒，ZCode 不会继续扫描子目录中的多层 AGENTS.md，所以重要的项目约定应放在工作区根目录。ZCode Agent：项目指令文件

创建工作区 AGENTS.md

在当前任务中发送：

请只在当前工作区根目录创建 AGENTS.md，不修改其他文件。内容需要准确表达以下项目规则：

- 项目是纯本地的“今日专注清单”。
- 只使用原生 HTML、CSS 和 JavaScript；不添加框架、第三方库、CDN、后端、构建工具或包管理器。
- 现有应用文件是 index.html、styles.css 和 app.js。
- 修改前先说明计划，只改实现当前需求必需的文件，避免无关重构。
- 不读取或修改工作区外的文件，不在代码中写入密钥。
- 修改后列出实际变更文件，并验证添加、完成、删除和空输入提示没有退化。
- 如果需求或验收标准不清楚，先说明疑点，不自行扩展功能。

请写成简短、明确的 Markdown 规则。

在确认请求中检查目标必须是 focus-board/AGENTS.md。允许后打开文件，对照上面的规则逐条检查。Agent 可以调整措辞，但不应增加部署、框架或团队流程等本课程没有要求的内容。

此时文件树应为：

focus-board/
├── AGENTS.md
├── index.html
├── styles.css
└── app.js

新建任务，让规则真正成为起点

AGENTS.md 是在旧任务开始后才创建的。为了避免误判它是否已经进入上下文，新建一个项目任务，再完成后续升级。

在新任务中，先不要输入需求。找到输入框附近的执行模式，切换到“计划模式”。计划模式会先检查项目并给出方案，不直接修改文件，适合第一次跨三个文件调整功能。执行模式说明

用 @ 精确提供上下文

在输入框键入 @，依次选择 index.html、styles.css 和 app.js。选中的文件会作为标签出现在输入框中。然后发送：

请基于我引用的三个文件，为“今日专注清单”规划一次小升级：

1. 在页面上显示总事项数和已完成数，初始为 0 和 0。
2. 添加、切换完成状态、删除事项后，统计立即更新。
3. 在 375px 左右的窄屏下，输入框、添加按钮、统计区和事项操作不能互相遮挡。
4. 保留现有添加、完成、删除和空输入提示行为。
5. 不加入持久化、筛选、导出或新依赖。

请说明准备修改哪些文件、每个文件为什么需要修改，以及完成后如何验收。当前只做计划。

检查计划，而不是只看它是否详细

合格计划应该把改动限制在三个现有应用文件中，并包含统计更新和窄屏检查。出现下面任一情况时，先纠正计划：

• 准备引入 React、Vue、npm 或 CSS 框架；
• 把统计做成后端接口；
• 顺手加入持久化、筛选或导出；
• 没有说明如何确认原有功能未退化。

计划越长不代表越好。只要路径、职责和验收闭环清楚，就可以实施。

按确认后的计划实施

把执行模式切回“变更前确认”，发送：

按刚才确认的计划实施。只修改计划中列出的文件。完成后列出实际修改文件，并给出人工验收顺序。

每次出现文件修改请求时，对照已确认计划检查路径。计划中没有出现的文件，不要因为 Agent 说“顺便整理”就直接允许。

独立验收统计和窄屏布局

用内置浏览器打开或刷新 index.html，依次操作：

1. 空列表应显示总数 0、已完成 0。
2. 添加“整理本周计划”和“阅读 20 分钟”，总数应变成 2。
3. 完成其中一项，已完成数应变成 1，总数保持 2。
4. 删除已完成项，总数应变成 1，已完成数变回 0。
5. 将浏览器面板宽度缩小到约 375px，确认输入区和事项操作仍可见、可点击，没有横向溢出遮挡。

最后查看文件树，工作区仍应只有四个文件。统计正确但多出了依赖或配置文件，也不算通过。

常见偏差

新任务没有遵守 AGENTS.md

先确认文件名是大写的 AGENTS.md，位置在工作区根目录，不是 docs/AGENTS.md。再确认当前任务是在文件创建后新建的。必要时用 @AGENTS.md 引用它，让 Agent 复述本次应遵守的三条关键规则；复述与文件不一致时，先停止编辑。

计划模式已经开始改文件

检查执行模式是否真的显示“计划模式”。聊天输入框聚焦时按 Shift + Tab 会循环切换模式，误触可能改变当前档位。发现路径或模式不对时拒绝操作，重新说明“当前只做计划”。

本课结束状态

工作区现在有四个文件；应用仍不保存刷新前的数据，但增加了总数和已完成数，窄屏布局经过人工检查。更重要的是，技术边界和验证要求已经进入 AGENTS.md，后续新任务不必每次从头交代。

下一课会在这些规则内加入 localStorage 和状态筛选，并第一次让 Agent 驱动浏览器完成一套明确的验收流程。

07 持久化筛选与浏览器验证

当前应用能添加、完成和删除事项，也能显示统计，但刷新页面后数据会清空。这个缺口正适合引入两个能力：用 localStorage 保存本地数据，以及让 ZCode Agent 在内置浏览器里执行真实操作。

完成本课后，事项会在刷新后保留，并可按“全部、进行中、已完成”筛选。Agent 会先跑一遍浏览器验收，你再独立复查。

固定存储来源

从本课起使用固定 HTTP 地址。先确认 Python 可用，在项目目录运行 python3 -m http.server 8000 --bind 127.0.0.1（Windows 用 py 替代 python3），在 ZCode 浏览器打开 http://127.0.0.1:8000。保持终端运行，结束时 Ctrl+C；后续使用同一浏览器、协议、主机名和端口。

file:// 的 localStorage 行为没有跨浏览器保证。此前只有少量练习数据，可记录后重新录入；不要把移动文件后看不到数据直接判为业务删除。

开始前确认浏览器控制

打开“设置 → 浏览器”，确认“开启内置浏览器控制”处于开启状态。Browser Use 官方插件通常默认开启；如果你刚刚打开它，需要新建任务，因为开关只对新会话生效。浏览器自动化

创建一个新的项目任务。这样既能载入第 4 课的 AGENTS.md，也能确保浏览器控制使用最新设置。

本课的文件范围明确，且只有三个应用文件可能修改，可以将执行模式切换为“自动编辑”：文件编辑自动进行，命令等风险更高的操作仍会请求确认。如果你希望逐个检查文件，也可以继续使用“变更前确认”。

规定数据结构和存储边界

在输入框中用 @ 引用 index.html、styles.css、app.js 和 AGENTS.md，发送：

为当前“今日专注清单”加入本地持久化和状态筛选，并遵守 AGENTS.md。

功能要求：
1. 使用 localStorage，固定键名为 focus-board.tasks。
2. 每条事项至少保存 id、text、completed、createdAt；createdAt 使用可重新解析的时间字符串。
3. 页面首次加载时读取已有数据；添加、完成状态变化和删除后立即保存。JSON 损坏时保留原值并提示用户备份后恢复，不静默清空；写入失败显示“未保存”，不能假装刷新仍会保留。
   所有事项文本用 textContent 等按文本渲染，不拼入 innerHTML。
4. 增加“全部、进行中、已完成”三个筛选控件，当前筛选状态要清楚可见。
5. 筛选只改变显示结果，不删除或重写被隐藏的数据。
6. 保留现有统计、空输入提示和窄屏可用性。
7. 不添加框架、依赖、后端、导入导出或其他功能。

修改完成后，请打开自己的内置浏览器标签验证：
A. 添加“整理本周计划”和“阅读 20 分钟”；
B. 将“阅读 20 分钟”标记完成；
C. 检查进行中只显示第一项，已完成只显示第二项，全部显示两项；
D. 刷新页面，再确认两项内容、完成状态、统计和筛选仍然正确；
E. 将视口设为 375×812，确认控件没有重叠或超出页面。

最后按 A～E 报告实际观察结果；不要只说“测试通过”。

固定存储键和字段不是为了增加技术感，而是为下一课制造并定位刷新问题提供稳定基础。createdAt 会在第 7 课计算近七天统计，当前只需正确保存。

看着 Agent 执行浏览器步骤

Agent 新建标签时，右侧浏览器面板会自动展开。它默认只操作自己打开的标签；你在上一课手动打开的页面不会自动被接管。因此，看到它新开一个本地页面是正常现象。

观察时注意三个信号：

• 输入和点击顺序是否与 A～E 一致；
• 刷新前后页面状态是否真的相同；
• 失败时它是否停下来说明实际现象，而不是继续编造后续结果。

如果 Agent 只检查源代码，没有打开页面，补充：

代码检查不能替代本课验收。请在你自己的内置浏览器标签中打开工作区的 index.html，按 A～E 实际操作，并逐步报告可见结果。

人工重复关键路径

Agent 的浏览器记录是证据之一，不是最终裁判。在它完成后，自己打开或刷新 index.html，执行下面这组更短的独立检查：

1. 删除已有事项，回到空列表。
2. 添加“测试持久化”，将它标记完成。
3. 切换到“已完成”，应只看到这条事项。
4. 刷新页面；页面可以回到默认的“全部”，也可以保留原筛选，但这条事项及其完成状态必须仍然存在。
5. 切换到“进行中”，列表应为空，但总数据不应被删除。
6. 切回“全部”，删除事项，再刷新；列表仍应为空。

步骤 5 用来区分“筛选隐藏”和“数据被删”。这是很多初版实现容易混淆的地方。

检查实际数据和代码边界

打开 app.js，搜索 focus-board.tasks。键名应在读写逻辑中保持一致。再检查事项对象是否包含 createdAt，以及添加、完成和删除三条路径是否都会保存。

不要求你能独立理解每行 JavaScript。你只需要确认需求中的固定词能在正确职责附近找到，并且没有出现远程接口地址或额外依赖。

文件树应仍为：

focus-board/
├── AGENTS.md
├── index.html
├── styles.css
└── app.js

两个常见失败

刷新后事项还在，但完成状态丢失

这通常说明保存或恢复时只处理了文字，没有完整保留 completed。把复现步骤和 @app.js 一起交给 Agent，要求先说明数据写入和读取路径，不要直接大改界面。第 6 课会系统练习这种调试流程。

浏览器控制已打开，当前任务仍不能操作

浏览器控制开关只对新会话生效。保留当前文件，重新新建一个项目任务，再发送验收步骤即可，不要重复生成代码。还要确认这是桌面端；官方说明浏览器面板仅桌面端可用。

本课结束状态

应用现在把数据保存在 focus-board.tasks，每条事项具有 id、text、completed 和 createdAt，并提供三种筛选。你已经看过一次 Agent 浏览器验收，也亲自复查了刷新和筛选。

下一课会先把这个可用版本记录为 Git 基线，再故意引入一个“刷新后完成状态丢失”的缺陷，练习复现、最小修复和变更审查。

负向验收

在独立练习数据上，将存储值改为非法 JSON 后刷新，应显示恢复提示且原始值还在；模拟 setItem 抛错，应出现未保存提示；输入 <b>阅读</b>，应显示字面文本而不是粗体元素。测试前备份当前值，结束后恢复。

08 调试与变更审查

这一课不继续堆功能。我们会把第 5 课的可用版本保存为 Git 基线，故意引入一个局部缺陷，再让一个新任务仅根据可复现现象定位并修复它。

最终目标不是“让 Agent 猜中原因”，而是建立稳定顺序：保存基线、复现、限制范围、修复、回归、查看真实差异。

先确认第 5 课基线可用

在浏览器中添加一条事项，标记完成后刷新。它应该仍然是完成状态。然后删除所有事项，让页面回到空状态。

如果这一步已经失败，先回到第 5 课修好，不要在未知基线上继续制造练习缺陷。

初始化本地 Git 基线

打开 ZCode 内置终端，确认当前目录是 focus-board。先检查 Git 是否可用：

git --version

看到 git version 和版本号即可。若提示找不到命令，从 Git 官方下载页 安装后重启 ZCode，再继续。

依次执行：

git init
git add AGENTS.md index.html styles.css app.js
git commit -m "baseline: persistent focus board"
git status --short

最后一条没有输出，表示工作区与基线一致。

如果首次提交提示缺少身份，只为这个练习仓库设置本地身份，不必修改电脑的全局配置：

git config --local user.name "ZCode Learner"
git config --local user.email "learner@example.invalid"
git commit -m "baseline: persistent focus board"

example.invalid 是保留的无效域名，不会把邮件发到真实地址。完成后再次运行 git status --short。

故意引入一个可控缺陷

新建一个任务，保持“变更前确认”，用 @app.js 引用脚本并发送：

这是一个调试练习。请只修改 app.js，故意引入下面这个局部缺陷：

事项从 localStorage 恢复到页面时，原本 completed 为 true 的事项会错误地恢复为未完成；当前页面内切换完成状态和保存仍然正常。

不要修改存储键、数据字段、HTML、CSS 或其他功能，也不要写注释直接透露缺陷位置。完成后只说明 app.js 已修改，不要修复它。

允许前确认只涉及 app.js。修改完成后不要提交 Git。

现在自己复现：

1. 添加“复现刷新问题”；
2. 标记为完成，确认已完成数为 1；
3. 刷新页面；
4. 事项仍然存在，但变回未完成，已完成数变为 0。

运行：

git status --short
git diff -- app.js

第一条应显示 app.js 被修改；第二条应展示相对已知可用基线的差异。你不必马上理解代码，但已经证明缺陷与这次局部改动相关。

用新任务按现象调试

新建另一个项目任务。新任务会读取 AGENTS.md，但不会依赖上一个任务中“我故意改了哪里”的对话说明。

用 @app.js 引用脚本，发送：

当前应用有一个可稳定复现的缺陷：

1. 添加一条事项；
2. 将它标记完成，已完成数显示 1；
3. 刷新页面；
4. 事项文字仍在，但完成状态丢失，已完成数变回 0。

请先在内置浏览器复现并报告实际现象，再检查 app.js 中 localStorage 的保存与恢复路径。找到原因后只做最小修复，不改存储键、不改数据结构、不重做界面。

修复后请再次执行上述四步，并回归检查添加、删除以及“全部/进行中/已完成”筛选。列出实际修改文件和验证结果。

如果 Agent 没有复现就准备大范围重写，拒绝并要求先完成前四步。调试任务里，复现失败本身也是信息：可能打开了错误页面、使用了旧标签，或浏览器里没有按步骤产生数据。

审查任务修改与仓库差异

修复完成后，先看当前任务的变更统计或 Review 面板。它记录的是这个任务做了什么；重点确认只修改 app.js，并且修改集中在恢复 completed 的路径。

再运行：

git diff -- app.js
git status --short

这里可能出现两种合理结果：

• **没有差异和状态输出：**Agent 恰好把脚本恢复到第 5 课的已知可用基线。
• **app.js 仍有小范围差异：**Agent 用另一种正确写法修复了问题。先阅读 Diff，确认没有顺手改数据结构或其他功能，再决定是否保留。

ZCode 的任务 Review 与 Git Diff 回答的问题不同：前者看“这个 Agent 任务改了什么”，后者看“当前工作区与最后一次提交相比有什么不同”。两者一起使用，比只看最终页面更容易发现无关改动。文件树还可以启用“仅显示变更文件”，快速聚焦带 Git 状态的文件。任务与文件管理

完成回归并留下干净状态

自己重新执行：

1. 添加两项；
2. 完成其中一项；
3. 刷新，完成状态和统计不变；
4. 三个筛选结果正确；
5. 删除两项，刷新后保持空列表。

如果 git status --short 为空，本课结束。如果保留了审查通过的新写法，提交它：

git add app.js
git commit -m "fix: preserve completed state after refresh"
git status --short

最后一条仍应没有输出。不要使用会抹掉其他工作的强制重置命令来追求“干净”。

本课结束状态

你已经用已知基线证明并修复了一个刷新缺陷，完成了功能回归，也区分了任务 Review 与 Git Diff。项目当前应无未审查改动。

下一课会在这个稳定版本上设置一个多步骤目标，让 ZCode 连续完成近七天统计、JSON 导出和键盘可操作性升级。

09 目标模式完成复杂升级

前几课的任务都能在一两轮内完成。现在项目已有稳定基线，要同时增加近七天统计、JSON 导出和键盘可操作性，还要回归原有功能。继续靠你反复说“下一步”很容易漏项，这才是使用目标模式的时机。

目标模式解决“做到什么程度才算结束”；执行模式解决“过程中哪些操作需要确认”。二者不是同一个开关。

起始状态

开始前确认：

• 工作区仍是 focus-board；
• AGENTS.md、index.html、styles.css、app.js 都存在；
• 持久化、三种筛选和刷新后的完成状态都正常；
• git status --short 没有未审查改动。

如果 Git 状态不为空，先审查并处理当前差异。不要让一个长任务建立在来源不明的修改上。

把“大升级”改写成可校验目标

“把应用完善一下”没有明确终点。目标模式需要能从文件、页面或测试结果中核对的完成标准。本课采用以下定义：

• 显示最近 7 天创建数、完成数和完成率；
• 导出当前全部事项为 JSON 文件；
• 只用键盘也能完成主要操作；
• 原有持久化、筛选、统计和窄屏行为不退化；
• 最终给出实际浏览器验证记录和变更清单。

创建任务并选择执行模式

新建项目任务，让 AGENTS.md 从任务开始就进入上下文。把执行模式设为“自动编辑”：它可以连续修改低风险项目文件，但命令和其他高风险操作仍可能停下来确认。

不要停留在“计划模式”。官方说明 /goal 与计划模式的工作方式冲突，在计划模式或当前任务仍在运行时不能设置目标。目标模式

目标模式可能自动运行多轮并持续消耗模型额度。开始前确认当前套餐或 API 余额足够，并在目标摘要中观察迭代；达到目标用量上限时，ZCode 会停止自动推进，而不是无限运行。

设置目标

在输入框输入 /goal，从建议面板选择命令，后面接上下面的目标内容；也可以直接整段粘贴：

/goal 在遵守 AGENTS.md 且不添加依赖、后端或新存储键的前提下，完成“今日专注清单”的以下升级：

1. 基于现有 createdAt 计算浏览器本地时区的最近 7 个自然日（含今天及前 6 日，不含未来日期）内创建的事项数、其中已完成数和完成率；无数据时完成率显示 0%，不能出现 NaN。
2. 增加“导出 JSON”按钮，将当前全部事项导出为 focus-board-backup.json；导出内容保留 id、text、completed、createdAt，不能只导出当前筛选结果。
3. 保证输入框、添加按钮、三个筛选控件、事项完成控件、删除按钮和导出按钮可以用 Tab 到达，并有清楚的焦点样式；在输入框按 Enter 可以添加事项。
4. 保留 localStorage 键 focus-board.tasks、原有添加/完成/删除、总数统计、三种筛选、刷新持久化和 375×812 窄屏可用性。
5. 完成后用内置浏览器创建至少两条事项、完成一条、刷新、切换三种筛选、仅用键盘添加一条并触发导出，逐项报告实际结果；再列出所有修改文件和仍存在的限制。

只有文件改动、浏览器操作结果和下载文件检查都有证据时才算完成。

设置成功后，界面会出现目标摘要卡，显示当前目标、迭代和待办。每轮结束时 ZCode 会单独校验；没有完成会自动进入下一轮，而不是等你发送“继续”。官方文档明确说明，计划或口头总结本身不能作为完成实据。

运行中什么时候介入

目标模式不是无人监管。遇到下面情况应暂停：

• 准备安装依赖或修改 focus-board.tasks；
• 开始实现导入、账号、同步等目标外功能；
• 多轮重复同一个失败，没有新的诊断信息；
• 需要离开电脑，且后续可能出现权限或下载确认。

在输入框执行：

/goal pause

目标记录、已产生文件和迭代历史会保留。纠正范围后执行：

/goal resume

如果需求本身需要换掉，使用 /goal replace <新目标>；不要让旧验收标准和新方向混在一起。

不依赖完成总结的人工验收

目标显示完成后，先查看 Review，确认通常只修改 index.html、styles.css 和 app.js，AGENTS.md 不应被任务自行改写。然后手动完成下面的检查。

近七天统计

1. 清空列表，统计应为 0、0、0%。
2. 添加两条新事项，近七天创建数应增加 2。
3. 完成其中一条，近七天完成数应为 1，完成率应为 50%。

本课创建的事项都处于最近七天，可以验证基本计算闭环。对于七天以前的数据边界，先检查 app.js 是否基于 createdAt 比较时间，而不是直接统计全部事项；更深入的日期边界测试可以作为后续练习。

JSON 导出

保持“进行中”筛选，只让一条事项显示，然后点击“导出 JSON”。打开下载的 focus-board-backup.json，确认数组中仍包含全部事项，而不只是当前可见项；每项都有 id、text、completed、createdAt。

导出只在本机生成文件，不应上传到网络。JSON 中可能包含你的事项文字，分享前要自己检查内容。

键盘操作

先用鼠标点一下页面空白处，然后：

1. 连续按 Tab，焦点应依次到达输入、添加、筛选、事项操作和导出按钮；
2. 每个焦点位置应有可见轮廓，不能只能靠猜；
3. 在输入框键入“键盘测试”，按 Enter，事项应被添加；
4. 使用 Space 或 Enter 激活当前聚焦的完成控件和按钮。

审查并保存最终版本

运行：

git diff -- index.html styles.css app.js
git status --short

确认差异只服务于三项目标，没有更换存储键或引入外部依赖。审查通过后提交：

git add index.html styles.css app.js
git commit -m "feat: add weekly stats and JSON export"
git status --short

最后一条应没有输出。

本课结束状态

主项目已经形成一个可使用、可刷新、可筛选、可导出并支持基本键盘操作的本地应用。你也完成了一个真正需要多轮推进的目标，而不是为了展示功能而启动长任务。

下一课不再扩展这个项目，而是用三组不同材料检查技能迁移：修复陌生缺陷、阅读小型仓库、把重复发布检查保存为 Command。

七日边界的固定验收

让统计函数接受可注入的参考日期，测试中固定为本地 2026-10-02 中午，不修改系统时钟。构造四条数据：10-02 已完成、09-26 未完成、09-25 已完成、10-03 已完成。预期窗口内共 2 条，完成 1 条，完成率 50%；09-25 和未来记录不计入。再用空数组验证 0%，在本地零点附近验证按日期而非滚动 168 小时计算。

10 迁移练习

主项目已经完成。下面三组练习分别测试三种不同能力：修缺陷、理解陌生代码、沉淀重复流程。它们不是把“今日专注清单”换个名字再做一遍。

课程目录中的 exercises/ 已提供起始文件。每次练习先复制对应文件夹，在副本中操作，保留原始材料便于重来。

练习一：修复刷新后丢失的计数

起始材料：01-counter-bug

起始问题

这是一个能加一、减一和归零的本地计数器。减一和归零会保存，但“加一”后刷新页面会回到旧值。

你的任务

1. 在 ZCode 中把练习副本作为独立工作区打开。
2. 先点击“归零”，再连续加一两次并刷新，记录实际值和期望值。
3. 新建任务，引用 app.js，要求 Agent 先复现，再做最小修复。
4. 回归减一、归零和刷新，不修改页面结构与样式。

新判断

症状发生在刷新后，不代表问题一定出在“读取”。保存路径和读取路径都要检查。让 Agent 先描述数据何时写入、何时读取，再决定修改哪一处。

验收

• 连续加一两次后刷新，数字保持不变；
• 减一和归零仍正常；
• 只修改实现问题所需的文件；
• Review 中没有框架、依赖或无关重构。

练习二：读懂仓库，但先不改代码

起始材料：02-reading-list

起始问题

你接手了一个“阅读清单”网页。它能按状态筛选书目，但没有面向新维护者的结构说明。产品希望以后加入评分功能，你现在还不应该直接实现。

准备基线

把副本作为工作区打开，在终端中建立本地 Git 基线：

git init
git add README.md index.html styles.css data.js app.js
git commit -m "baseline: reading list sample"

若提示缺少身份，沿用第 6 课的仓库本地配置。建立 Git 仓库后，如果工作区顶部出现“仓库 Wiki”入口，可以先生成架构导读；无论是否使用 Wiki，都要用 @ 引用实际源文件核对结论。

你的任务

让 Agent 只创建两个文档：

• ONBOARDING.md：说明页面入口、数据来源、渲染流程、筛选流程和各文件职责；
• CHANGE_PLAN.md：规划加入 1～5 星评分需要修改哪些数据字段、文件、页面元素和验收步骤。

提示词中明确：不修改现有 HTML、CSS 或 JavaScript，不实现评分。

新判断

区分“源码能证明的事实”和“对未来改造的建议”。例如，data.js 当前提供哪些字段是事实；评分应该使用星形按钮还是下拉框是方案选择，不能写成仓库现状。

验收

• ONBOARDING.md 的关键结论能指向具体文件和函数或变量；
• CHANGE_PLAN.md 说明数据迁移和无评分数据的兼容方式；
• git status --short 只显示两个新文档；
• 原有网页仍可打开和筛选。

练习三：把发布检查保存为 Command

起始材料：03-release-candidate

起始问题

这个示例准备发布 1.2.0。package.json、CHANGELOG.md 和源码中的版本常量需要一致，但每次人工重复检查容易漏项。

创建工作区 Command

先把 exercises 中的 03-release-candidate 复制到自己的练习目录，并在 ZCode 中将该副本作为当前工作区打开；检查 package.json、版本常量文件和变更说明都位于该副本，不能仍停在 02-reading-list。确认后打开“设置 → 命令”，点击“新建命令”，填写：

• **作用域：**工作区；
• 名称：release-check；
• **描述：**检查版本一致性、变更说明和发布清单；
• **参数提示：**留空；
• **提示词：**使用下面内容。

只读检查当前工作区的发布准备状态，不修改文件：

1. 比较 package.json 的 version 与 src/version.js 的 APP_VERSION。
2. 检查 CHANGELOG.md 是否包含该版本且有实际变更说明。
3. 按 RELEASE_CHECKLIST.md 逐项判断能否从当前文件中找到证据。
4. 如果工作区是 Git 仓库，报告未提交文件；不是 Git 仓库则明确说明未检查 Git 状态。
5. 输出“阻塞问题、警告、已通过”三组结果，每条都引用证据文件。

不要把缺少证据的项目判断为通过，也不要自动修复。

保存后，在新的任务输入框输入 /release-check 调用。ZCode 官方说明，自定义 Command 用于保存简单、重复的提示词，可选择用户级或工作区级作用域；本练习使用工作区级，避免污染其他项目。Command

新判断

第一次运行应该发现 src/version.js 与 package.json 不一致。检查命令的职责是报告，不是自动修复。确认报告准确后，再单独要求 Agent 只修正版本常量，然后第二次调用 /release-check。

验收

• 第一次运行准确报告版本不一致；
• 修正后第二次运行不再报告该阻塞；
• 两次报告结构一致，方便比较；
• Command 没有自行修改项目；
• 你能说明为什么这是一段适合 Command 的固定提示词，而不是需要脚本、模板和多份资源的 Skill。

完成练习后的自评

如果三组都能完成，你应该已经能根据任务类型改变工作方式：

• 有明确故障时，先复现再修复；
• 面对陌生仓库时，先建立证据充分的理解；
• 面对重复但简单的流程时，保存为 Command；
• 不把所有问题都处理成“让 Agent 直接改代码”。

下一课将把整套课程中最可能阻塞完成的问题整理成症状式排障表，并给出继续学习不同 ZCode 能力的选择路线。

11 排障与下一步

这一课不再添加项目功能。你会用固定顺序定位问题，并完成一次课程收口检查。遇到故障时，从可观察状态开始，不要立刻重装、换模型或授权完全访问。

通用诊断顺序

先回答六个问题：

1. 当前打开的是哪个工作区？
2. 当前任务从什么时候开始，是否读取了最新 AGENTS.md？
3. 模型是否已连接、供应商是否启用？
4. 当前是哪个执行模式，是否有等待处理的确认？
5. Agent 实际用了哪些文件、命令或浏览器标签？
6. 文件、Git Diff、页面和下载结果分别提供了什么证据？

这个顺序能把“ZCode 不工作”缩小成具体层次：项目状态、模型连接、权限、工具调用或实现结果。

安装或启动问题

症状：安装包打不开或启动后立即退出

• **可能原因：**安装包架构不匹配、系统安全策略拦截、Linux AppImage 缺少权限或依赖。
• **检查：**回到官方安装页确认系统和架构；Linux 从终端启动一次，读取首个错误；Windows 查看安全软件记录。
• **处理：**重新下载匹配的官方安装包；AppImage 先添加执行权限。涉及关闭安全防护或解除系统隔离时，先确认来源和影响，不照抄陌生命令。

官方安装与平台排障

模型连接问题

症状：连接一直 Loading，或输入后没有模型可选

• **可能原因：**网络无法访问服务、账号没有可用模型权限、供应商未启用。
• **检查：**打开“设置 → 模型设置”，确认账号连接、供应商开关和实际返回的模型列表。
• **处理：**先修复连接或账号权限，不要凭记忆手填模型名。官方 FAQ 将网络环境和账号权限列为持续 Loading 的优先检查项。常见问题解答

症状：有 Coding Plan 或余额，但请求没有走预期额度

• **可能原因：**把 Coding Plan 专用端点与开放平台通用端点混用。
• **检查：**确认凭据属于编程套餐还是资源包 / 充值余额。
• **处理：**BigModel Coding Plan 当前使用 /api/coding/paas/v4，通用余额使用 /api/paas/v4；不确定时改用 BigModel 账号授权，让 ZCode 自动选择通道。不要把 API Key 发进聊天。

症状：终端能调用模型，ZCode 仍未配置

• **原因：**终端环境变量和 ZCode 桌面端模型设置是独立入口。
• **处理：**在 ZCode 的欢迎页或“管理模型”中单独连接。终端可用不代表桌面端自动继承。

工作区和项目规则问题

症状：Agent 分析了错误项目或看到了无关文件

• **检查：**查看工作区名称和文件树根目录，不要只看任务标题。
• **处理：**停止当前操作，打开正确文件夹后新建项目任务。不要把用户主目录、整个“文档”目录作为工作区。

症状：Agent 没有遵守刚写的 AGENTS.md

• **可能原因：**文件不在工作区根目录、文件名不正确，或当前任务早于文件创建。
• **检查：**确认路径是 <工作区>/AGENTS.md。
• **处理：**新建项目任务；必要时用 @AGENTS.md 引用并要求复述关键规则。不要用项目 Memory 代替需要评审和共享的规则文件。

权限与执行问题

症状：任务一直停着不动

• **可能原因：**正在等待文件、命令、网络操作或计划审批。
• **检查：**查看当前任务输入区和侧边栏的等待状态，阅读具体路径和命令。
• **处理：**符合范围则只允许本次；路径或影响不明确则拒绝并纠正。不要为了消除提示直接切换完全访问。

症状：确认太多，任务被频繁打断

• **检查：**任务是否已明确限制在低风险练习工作区，操作是否重复且可恢复。
• **处理：**常规文件迭代可切换“自动编辑”；涉及删除、系统配置、外部提交或陌生脚本时继续使用“变更前确认”。减少确认次数不等于扩大工作区范围。

浏览器与页面问题

症状：浏览器控制已开启，Agent 仍不能操作

• **可能原因：**开关只对新任务生效，当前会话是在开启前创建的；或者你期待它直接控制手动打开的标签。
• **处理：**新建任务，让 Agent 打开自己的标签；需要它接管手动标签时显式认领。浏览器面板仅桌面端提供。

症状：Agent 说已修复，页面仍显示旧结果

• **检查：**确认浏览器打开的是当前工作区的 index.html；刷新页面；查看控制台第一条错误；比较文件时间和 Git Diff。
• **处理：**把具体 URL、复现步骤、预期与实际结果交给 Agent。不要只说“还是不行”。

症状：刷新后数据、筛选或完成状态异常

• **检查：**分别检查 focus-board.tasks 的写入和读取；确认筛选只控制显示，没有重写完整数组。
• **处理：**用最短复现步骤建立基线，再限制 Agent 只检查 app.js 的保存、恢复和筛选路径。

Git 与目标模式问题

症状：git commit 提示缺少身份

• **原因：**当前 Git 环境没有提交者名称或邮箱。
• **处理：**在练习仓库中使用第 6 课的 git config --local 设置；除非你明确希望所有项目共用，否则不必改全局配置。

症状：无法设置 /goal

• **可能原因：**当前处于计划模式，或者另一个任务仍在执行。
• **处理：**等待当前轮结束或停止它，再切换到自动编辑、变更前确认或完全访问后设置目标。目标模式和计划模式不能同时运行。

症状：目标运行很多轮仍不完成

• **检查：**目标是否有客观终点；是否有未完成待办；是否在重复同一失败；是否达到用量上限。
• **处理：**用 /goal pause 保留状态，缩小目标或补充验收证据后恢复。不要把“继续努力”当成新的验收标准。

什么时候提交官方反馈

如果问题可以稳定复现，且已经排除错误工作区、网络、账号、权限和项目代码，准备以下信息：

• 操作系统与版本；
• ZCode 版本；
• 模型通道；
• 最短复现步骤；
• 期望表现与实际表现；
• 必要的截图和脱敏日志。

macOS 可从菜单栏“ZCode → 关于 ZCode”查看版本，Windows / Linux 可从标题栏“帮助 → 关于 ZCode”查看。应用右上角反馈入口可以提交问题或导出日志；日志和截图中仍要自行检查敏感项目内容。用户反馈与支持

课程完成检查

回到自己的 focus-board，确认你能够独立完成这些动作：

• 指出工作区、任务、工具和执行模式各自控制什么；
• 打开一个项目任务，并用 @ 引用必要文件；
• 解释一次修改为何选择计划模式、变更前确认或自动编辑；
• 查看真实文件、浏览器结果、任务 Review 和 Git Diff；
• 复现缺陷后要求最小修复并完成回归；
• 设置一个带验收证据的 /goal，必要时暂停和恢复；
• 说出密钥、工作区范围、删除操作和外部副作用的安全边界。

如果其中某一项还只能照着步骤机械完成，回到对应课程再做一次不同的小改动，比继续浏览功能列表更有效。

接下来学什么

按真实需求选下一步，不需要把所有扩展都学一遍：

课程到这里结束。你得到的不是一份 ZCode 菜单说明书，而是一条可以迁移到真实项目的工作路径：限定范围、提供上下文、选择权限、观察执行、独立验证、审查差异，再决定是否继续。

12 进阶学习

用 ZCode 做出一个能用的页面 下一步该学什么

在 ZCode 知识库中，你做出了一个“今日专注清单”：可以添加、完成、删除事项，按状态筛选，刷新后保留数据，还能逐步加入周统计和导出功能。

这个小应用有一个很好的学习特点：结果看得见，也检查得了。

按钮有没有反应、数据有没有保存、手机上能不能操作，打开页面试一试就知道。它让你走完了从提出需求到检查结果的第一段路。

把这套检查方法留下来

每次增加功能，都留下一份可以重复操作的检查清单。可以从下面四类情况开始。

然后，看看 Git 中的代码差异：这次改了哪些文件，有没有顺手修改无关内容？修复后，再用清单确认已有功能仍然正常。

这样，你积累的不只是一个能用的页面，还有一套以后可以反复使用的验收方法。

当清单开始给多人使用

如果有一天，你想让同事也用这个清单，验收就要扩展到页面之外。下面四个问题，需要接口、数据和权限一起配合。

可以先做一个小升级：增加一个后端接口，约定字段和错误返回，再接上页面。最后，主动模拟一次接口失败，看看应用怎样回应。

浏览器里的检查仍然重要，但你还需要检查接口返回、失败提示和发布后的行为。学习可以沿着真实需求逐步展开。

把小应用里的经验 带到更完整的项目

如果你准备继续学习完整项目交付，可以了解《企业级 AI 编程实战营》。

课程以 Claude Code 为主要实践工具，通过规格驱动开发，把需求、实现、测试和审查放进同一条流程。ZCode 用户可以从中继续练习项目交付方法。

OryxOS 项目会涉及工具接入、权限和端到端验证；DifyPro 项目则练习在已有大型仓库中做增量修改，检查对旧功能的影响。

从本地页面走向真实系统，需要把验收范围一步步扩展。你可以先对照课程项目，看看自己的下一步是前后端协作，还是维护已有仓库，再选择合适的学习内容。

想了解下一步怎么学

如果你希望进一步了解《企业级 AI 编程实战营》的课程内容与学习要求，可以扫描下方二维码，向学习顾问发送「ZCode 项目交付」，说明自己的基础和想解决的问题，一起判断课程是否适合。