长任务断点续跑（Resumable Task Runner）
目标：让"断网中断"变得廉价。断网期间任务无法继续推理（模型在云端），但可以让中断后 不重跑、不丢进度、只补未完成部分。
核心原则：进度必须以磁盘文件形式存在，而不是只存在于对话上下文里。
一、何时启用
任务满足以下任一条即启用（无需用户显式点名）：
- 预计需要 5 步以上工具调用，或单步耗时较长（长文档、批量处理、联网调研、开发任务）
- 涉及批量文件/批量数据（可能几十上百条）
- 用户明确提到：网络不稳定、怕中断、要从上次继续、断点续跑
- 会话已经出现过中断/失败
二、断点文件约定（固定路径，不可随意改）
<工作空间>/.workbuddy/checkpoint/<任务短名>.md # 主断点文件（进度）
<工作空间>/.workbuddy/checkpoint/<任务短名>-done.txt # 批量任务幂等清单（每行一条已处理项）
<工作空间>/.workbuddy/checkpoint/<任务短名>-files.txt # 已产出产物清单（路径 + 状态）
- 任务短名用英文或拼音，不含空格，例如
bridge-boq、claim-letter-batch。 .workbuddy/checkpoint/不存在则创建；只新增文件，不移动、不删除用户任何文件。- 断点文件随任务走，属于工作空间，不散落桌面。
- 主断点文件的结构见
references/checkpoint-template.md（首次执行任务时按该模板写入）。 - 如需脚本化维护（初始化、标记完成、查看进度），使用
scripts/checkpoint.py。
三、执行流程
阶段 0：开工（必须先做，且先于任何重活）
- 提炼任务目标与交付物，生成步骤清单；步骤粒度以"能在 5-15 分钟内跑完并验收"为宜。
- 按
references/checkpoint-template.md写入主断点文件（可用scripts/checkpoint.py init）；同时用任务清单工具建同一套步骤（双保险）。 - 向用户复述"步骤清单 + 断点文件路径"，一句确认即可开工，不要索取无关信息。
阶段 1..N：分阶段执行
- 每个阶段只推进 1-3 个步骤；每完成一步立刻更新断点文件的状态列。
- 该阶段产生的产物立即写文件（报告、表格、脚本、代码、数据），不要只在回答里描述。
- 批量任务：每处理完一条就追加到
-done.txt（先记录再继续下一条，避免中途丢批次）。 - 联网步骤（联网检索、下载依赖、连接器调用）尽量前置并集中；依赖预先下载到本地缓存，避免本地处理阶段再依赖网络。
- 每阶段结束给用户一句进度播报：
已完成 3/8（断点文件已更新）。 - 长文档：分章生成、每章落盘、最后合并，不要一次性生成超长文本。
收尾
- 断点文件状态更新为「已完成」，保留文件作为任务档案（便于追溯与复用）。
- 汇总交付物路径清单给用户。
四、恢复流程（会话中断后接续）
在原任务/原会话中执行（不要新建任务重来）；完整判定与核对细则见 references/recovery-playbook.md。
- 读取主断点文件。
- 核对磁盘：用 Glob/Read 抽查状态为
done的产物是否真实存在、是否完整（大小/行数/结尾关键内容）。 - 重建进度：产物完整 → 跳过不重做；产物不完整 → 标为
doing，只补缺失部分；产物不存在 → 标回todo。 - 向用户播报「已完成 A/B/C，缺失 D/E，从第 N 步继续」，然后直接执行剩余步骤。
- 无断点文件的抢救场景：先按修改时间扫描工作空间内本次任务的产出文件，重建进度表，明确标注哪些是推测，确认后再继续。
五、口令模板（可直接给用户复制）
开工：
> 用断点续跑模式做这件事：<目标>。先出步骤清单并写入 .workbuddy/checkpoint/<短名>.md，然后分阶段执行，每阶段结束落盘并更新断点文件。
中断后接续（推荐）：
> 读取 .workbuddy/checkpoint/<短名>.md，核对已产出文件，跳过已完成步骤，只做未完成的部分，完成后更新断点文件。
轻量接续（上下文完整时）：
> 继续上一步没做完的部分，不要重做已完成的步骤。
无断点文件抢救：
> 上次任务中断了，没有断点文件。请先扫描工作空间里这次任务已产出的文件，列出清单并推断进度，标出哪些能复用、哪些缺失，我确认后再继续。
六、硬规则
- 不得在未读断点文件的情况下重头执行任务。
- 不得把进度只写在回复里而不落盘。
- 不得因为"看起来简单"而跳过断点文件（中断恰恰发生在长任务里）。
- 不得删除或移动用户已有文件来"清理"；断点文件只新增。
- 每步完成后落盘，胜过收尾时一次性写。
- 恢复时优先复用磁盘产物，而不是重新生成（这是省 token 的关键）。
- 涉及联网的批量抓取，采用"小批次 + 即时落盘 + 幂等清单"，中断后自动跳过已抓取项。
七、附带资源
| 资源 | 用途 |
|---|---|
references/checkpoint-template.md |
主断点文件标准模板（开工时按此写入） |
references/recovery-playbook.md |
中断恢复判定流程、产物完整性核对、无断点文件抢救 |
references/network-hardening.md |
降低断网概率的环境加固清单（网卡节能、DNS、双线路、代理白名单） |
scripts/checkpoint.py |
断点文件命令行工具：init / add / done / doing / status / next / mark-item / list-items |
examples/example-checkpoint.md |
断点文件填写实例（对照参考） |
