给代码智能体的需求怎么写：以研究生学习计划网页为例

用代码智能体生成网页时，只有“帮我做一个学习计划工具”往往不够。页面可能已经漂亮了，却没有说明计划怎样保存、时间不足时怎样提示，或数据损坏时怎样恢复。把需求写成可检查的行为，能减少生成后的反复修改。下面给出一个不依赖后端的学习计划工具设计示例，可用于码道等代码智能体的练习。

先限定一个可完成的范围

第一版只做四件事：添加学习主题、填写预计分钟数、标记完成、显示计划进度。数据保存在当前浏览器，并提供 JSON 导出。暂时不加入账号、支付或外部模型接口，这样可以把注意力放在数据流和基本交互上。

主题记录可以采用这样的结构：

{"id":"topic-001","title":"阅读一篇论文","minutes":45,"completed":false}

标题和分钟数都是用户输入。标题必须去除首尾空白，分钟数必须是有限的正整数。记录标识要独立于标题，否则两个同名主题可能在删除时被一起删掉。

把提示词写成验收清单

请生成一个中文学习计划网页，仅使用 HTML、CSS 和 JavaScript。
目标用户：需要安排论文阅读和实验学习的学生。
核心行为：
1. 添加主题，填写标题和预计分钟数。
2. 标题为空或分钟数不是正整数时，显示具体错误，不保存记录。
3. 可以标记完成、恢复未完成状态、删除单条记录。
4. 显示主题完成比例，以及已完成和总计划分钟数。
5. 刷新页面后记录保留；提供 JSON 导出和带结构校验的导入。
6. 导入格式错误时，提示问题并保留原有记录。
7. 用户输入按文本显示，不拼接到 HTML 中。
8. 页面可用键盘操作，窄屏不出现横向滚动。
完成后说明启动方法，并给出核心交互的验证步骤。

这份提示词指定了输入、状态变化、失败条件和交付方式。它没有把“好用”留给模型猜测，而是把几个容易遗漏的边界写了出来。

进度计算要先定义含义

“主题完成比例”和“时间完成比例”是不同的指标：完成一个 10 分钟主题与完成一个 90 分钟主题，按主题计数时贡献相同，按计划时长计数时贡献不同。界面应给指标加上准确名称。按计划时长计算可写成：

function minuteProgress(topics) {
  let total = 0;
  let done = 0;
  for (const topic of topics) {
    if (!Number.isSafeInteger(topic.minutes) || topic.minutes <= 0) {
      throw new TypeError("预计分钟数必须是正整数");
    }
    if (typeof topic.completed !== "boolean") {
      throw new TypeError("完成状态必须是布尔值");
    }
    total += topic.minutes;
    if (!Number.isSafeInteger(total)) {
      throw new RangeError("计划总时长过大");
    }
    if (topic.completed) done += topic.minutes;
  }
  return { total, done, percent: total === 0 ? null : Math.round(done / total * 100) };
}

没有主题时返回 null，界面可以显示“尚未创建计划”，避免把空计划展示为已完成。完成 10 分钟主题、未完成 90 分钟主题时，时间进度应为 10%，主题进度则为 50%。这一对例子可以直接检验界面的指标是否混用。

验收时覆盖失败路径

生成后至少手动检查这些操作：只输入空格、输入 0 或负数、添加两个同名主题、完成后再取消、刷新页面、导入损坏的 JSON。还应输入 <img src=x onerror=alert(1)> 这样的文本，确认它作为普通字符串显示。导入和渲染之间必须有校验，不应把导入文件当成可信数据。

如果浏览器阻止本地存储，应用应明确提示本次数据无法持久保存，并继续提供导出功能。导出文件也值得打开检查：它应包含实际记录，不能只下载一个空数组。

让修改也有可检查的目标

第一轮完成后，每次只提出一个具体问题，例如“取消完成后，预计分钟数没有恢复，请检查完成状态到统计值的数据流”。附上最短的复现步骤和期望结果，比笼统要求“继续优化”更容易得到可验证的修复。

写作说明：本文由 AI 辅助编写，示例用于说明需求设计与验收方法。