1. 先认识-ZCode

来源：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 工作区，并进行一次只读验证。