6. 调试与变更审查

来源：ZCode

这一课不继续堆功能。我们会把第 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 导出和键盘可操作性升级。