用 Python 把学习目标变成有时间边界的离线行动看板

昨天在制作学习任务看板时，我发现一个更早的问题：能够添加任务，并不代表计划可以执行。如果一周每天只有 45 分钟，却列出十几项没有估时的目标，进度条再漂亮也无法回答“今天做不做得完”。这次将关注点放到计划生成阶段，使用 AI 辅助实现“云上学习计划助手”：先确定时间预算和验收标准，再生成 Markdown 清单与离线 HTML 看板。本文记录实际实现与验证，不把示例计划当作已经完成的学习成果。

先让输入可以被检查

输入采用 JSON，保留目标、起始日期、计划天数、每日分钟数和任务数组。每项任务包含 day、title、minutes 与 done_when。其中 done_when 是可观察的完成条件，例如“新增并勾选一个任务，刷新后确认记录保留”，比“掌握浏览器存储”更容易验收。

本次示例从 2026 年 10 月 22 日开始，持续 7 天，每天预算 45 分钟。前五天各安排 35 分钟，后两天各 30 分钟，合计 235 分钟，在总计 315 分钟中保留 80 分钟余量。余量可以用于复盘或尚未完成的练习，不能用修改估时来掩盖已经超出的任务范围。

预算检查应当在生成之前

Python 生成器只使用标准库。日期交给 date.fromisoformat，每天的任务总时长通过 defaultdict(int) 累加。如果任务落在计划天数之外、时长不是正整数、缺少验收标准，或者某一天累计超出预算，命令会直接失败。

核心检查可以概括为下面这一段：

# 按实际天数累计任务时长，超过当天预算时停止生成。
totals = defaultdict(int)
for task in plan["tasks"]:
    day, minutes = task["day"], task["minutes"]
    totals[day] += minutes
    if totals[day] > plan["daily_minutes"]:
        raise ValueError("任务安排超过当天时间预算")

这里故意展示预算部分，完整脚本还包含前述字段检查。校验失败后的正确处理是缩小目标或重新排期，然后再次生成。生成器不负责判断某个知识点真实需要多少分钟，这仍需要使用者根据基础与学习反馈调整。

同时生成计划快照与执行界面

运行脚本后输出 study-plan.md 和 study-board.html。Markdown 按日期列出任务、时长、余量与验收标准，适合保存到笔记或版本库。HTML 用于执行过程，展示每天的任务，并通过勾选更新总体进度。

这两份文件的含义需要明确：Markdown 是生成时的计划快照，不会随着浏览器中的勾选自动变化。需要分享当前进度时，应点击“下载复盘 Markdown”，取得包含当前完成标记和验收标准的新快照。这样可以区分“最初准备做什么”和“现在记录完成了什么”。

浏览器中的数据只承担本地记录

HTML 中嵌入计划 JSON，任务标题和验收说明通过 textContent 写入页面。嵌入 JSON 前会把 < 转义为 Unicode 形式，避免任务文字提前结束数据脚本。每份计划的 JSON 计算摘要，作为 localStorage 存储键的一部分，让不同计划分别记录完成项。

localStorage 并不提供跨设备同步。清理站点数据、切换来源或更换浏览器后，原来的完成项可能无法读取。MDN 也说明，直接通过 file: URL 打开的文档，其 localStorage 行为没有统一保证。因此虽然 HTML 不依赖在线服务，演示和长期使用仍建议通过固定的本机 HTTP 地址打开，并定期导出复盘。依据：MDN《Window: localStorage property》。

用实际操作验证，而不是只看页面

本次核对了正常示例的 7 项任务与 235/315 分钟预算。浏览器中勾选第一项并刷新后，进度仍为 1/7；触发导出时，生成的 Markdown 内容包含该项的 [x] 标记和对应验收说明。核对完成后恢复为 0/7，确保公开演示展示的是待执行计划。

此前也检查了同一天超出预算的输入会失败。这里的验证针对脚本生成、当前浏览器本地保存以及复盘文本内容，没有证明所有浏览器都能以相同方式处理本地文件，也没有实现服务端账号或跨设备同步。

运行方式与后续改进

在项目根目录执行下列命令即可生成示例并在本机预览：

# 用项目自带的示例生成计划文件。
python3 scripts/render_plan.py --input assets/example-plan.json --out demo

# 仅监听回环地址，使用固定来源预览本地页面。
python3 -m http.server 8080 --bind 127.0.0.1

随后打开 http://127.0.0.1:8080/demo/study-board.html。Skill 本身用于收集目标与预算、拆解任务和生成文件；不会调用云资源 API、自动购买资源或代替本人考试。

这个小项目的价值在于把目标、预算、执行和证据连接起来。后续若增加计划调整，应先明确旧进度如何对应新任务，再决定数据结构；当前版本保持固定计划和可导出复盘，让实际使用者先验证这种工作方式是否有效。

本文及项目由 AI 辅助实现和整理，操作结果来自实际脚本与浏览器核对。示例中的学习任务仍待执行。