3. 第一次完整交付

来源：ZCode

上一课结束时，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，学习怎样把技术范围和验证要求变成项目的长期约定，而不是每次都重新输入。