task-wrap-guard · 长任务收尾护栏
> 埋点：执行第一步前，向 ~/.workbuddy/skill-calls.jsonl 追加一行 {"skill":"task-wrap-guard","ts":<unix秒>,"cwd":"<当前目录>","session_id":"<会话ID>"}。
1. 这个技能解决什么
WorkBuddy 用户 10 月吐槽里最伤的一类，不是"做不出来"，而是做了一半没了：
- 「当项目前置条件搞得七七八八跑上 10 来分钟的时候，提醒你『免费额度已经使用完了』……更让人崩溃的是，项目直接停下来，而人不在电脑前。」
- 「体面的限流是提前打招呼：这模型你还能跑五分钟，抓紧收尾。不体面的限流是跑到一半掐电。」
- 「给它一个模糊的两小时目标，它会晃神。边界清晰、范围小的任务才是它的主场。」
社区里已有大量"断点续跑"类技能，解决的是断掉之后怎么接着跑（多是工程视角：状态机、心跳、幂等重放）。本技能补的是它们不管的那一半：
> 在还没断的时候，决定"现在收在哪最划算"；真断了，用最小代价把已做的部分落袋，并用 30 秒复述卡重开。
一句话区分：它们是"续跑工程"，本技能是"收尾止损"。
2. 适用场景 / 不适用场景
适用（满足任一即进入）
- 预计超过 10 分钟，或需要 3 步以上，或产出 2 个以上文件的任务。
- 已经出现中断信号：额度告警、上下文压缩后开始"流口水"、同一处反复返工。
- 用户明确说"这个要跑一会儿""先做着，我等会儿回来看"。
不适用，直接说清归谁
| 用户真正的问题 | 归谁 |
|---|---|
| 进程还在不在、要不要判活、心跳监控 | long-tasks-monitor、long-running-task-healthcheck |
| 跨会话的交接文档体系、会话接力规范 | session-continuity |
| 批处理作业的重试、补偿、幂等状态机（开发视角） | durable-job-recovery-cn、resume-runner、reconnectforworkbuddy |
| 该用哪个模型、这次大概烧多少分 | model-credit-advisor（本技能的上游） |
| 任务到底跑成功了没、AI 有没有谎报 | 自动化验收巡检类技能 |
3. 输入参数
| 参数 | 必填 | 说明 | 缺省时的处理 |
|---|---|---|---|
任务名 |
✅ | 一句话说清在干什么 | 无缺省，必填 |
目标 |
✅ | 做完之后世界有什么不同 | 无缺省，必填 |
分块 |
✅ | 用 | 分隔的块名，建议 2–6 块 |
无缺省；用户给不出时，由 AI 按「每块可独立交付」原则代拟，并请用户确认 |
风险等级 |
⬜ | 每块 low/mid/high，英文逗号分隔 | 全部按 mid 处理，并在输出里标注为假设 |
验收标准 |
⬜ | 一句话「做到什么算完」 | 落袋为「数据缺口」，收尾包里会明写"派活时未填写" |
截止时间 |
⬜ | 自然语言 | 不填则不做时间相关建议 |
收尾原因 |
⬜（wrap 时） | 为什么现在收 | 记为"（未说明）" |
4. 执行步骤（五步，按序执行）
步骤 1 · 判定是否值得立合同
三问：预计超过 10 分钟？超过 3 步？产出 2 个以上文件？三问全否 → 直接干活，不要上流程（小任务上护栏是净负担）。任一为是 → 进步骤 2。
步骤 2 · 立任务合同（init）
python scripts/wrap_guard.py init --title "任务名" --goal "目标" \
--blocks "块1|块2|块3" --risk "low,mid,high" --done-when "一句话验收"
分块铁律：每块必须能独立交付——做完这块，即使后面全断，这块的东西也能用。风险等级按"错了代价多大"标，不按"难不难"标；高风险块不许排在最后赶。
步骤 3 · 做一块，登记一块（done）
python scripts/wrap_guard.py done --index 1 --artifact "产物路径" --note "一句话"
多个产物用 ; 分隔。产物路径不存在时脚本会警告——这是故意的，防止"以为落盘了其实没有"。禁止跳过登记攒到最后一次性补，那等于没落盘。
步骤 4 · 风险点做收尾决策（status → wrap）
出现以下任一信号，立刻跑一次 status：
- 界面提示额度不足 / 排队 / 限速；
- 同一处返工两轮以上，或 AI 开始复述你已经说过的要求；
- 剩余量按平均速度超过 20 分钟。
收尾三选一，由用户拍板，AI 只给依据：
| 选项 | 何时选 | 代价 |
|---|---|---|
| 现在收尾 | 已完成部分已能交差，或余额撑不到下一块 | 剩余部分留到下次 |
| 降级续跑 | 剩余块质量底线不高（草稿、初筛） | 质量下降，可能返工 |
| 硬跑 | 已完成的块离交付还差得远，且余额明显够 | 可能被中途掐断，白等 |
选完执行：
python scripts/wrap_guard.py wrap --reason "额度告警，先落袋" --next "下一步做第 2 块"
步骤 5 · 重开（resume）
新会话里直接：
python scripts/wrap_guard.py resume
把输出的「30 秒复述卡」粘给 AI，它就能接着做，你不需要重新讲一遍需求。这一步是本技能的兑现点——前面所有落盘都是为了这一刻不用重讲。
5. 输出格式（四种产物，固定结构）
| 产物 | 文件 | 内容 |
|---|---|---|
| 任务合同 | .taskguard/contract.md |
目标、截止时间、分块表（块名/风险/状态）、验收标准 |
| 状态文件 | .taskguard/state.json |
机器可读的块状态与产物清单（脚本用，人不用看） |
| 收尾包 | .taskguard/handoff.md |
四段：已经落袋的部分 / 还没做的部分 / 30 秒复述卡 / 恢复命令 |
| 恢复简报 | 终端输出 | resume 时打印收尾包全文 + 一句使用提示 |
对话里给用户看的东西控制在一屏：进度表 + 收尾建议，不要把文件内容整段复读。
6. 边界约束（红线）
- 不联网、不读账户、不读余额。本技能不知道你还有多少分，也不会猜。
- 不自动续跑任务。
resume只出简报，要不要继续由用户决定。 - 只写
.taskguard/一个目录，且只写四个文件；不删、不改、不覆盖用户的任何业务文件。 - 不编造耗时、积分数、完成度。没有已完成的块就不预估剩余时间，直接写"数据缺口"。
- 不替用户决定收不收尾，只给依据与代价对比。
- 不做文件清理、批量删除类操作——这是社区事故率最高的话术，本技能一律回避。
7. 脚本用法
纯标准库、零依赖，Windows / macOS / Linux 通吃。所有子命令都支持 --root <目录>（默认当前目录）与 --json（机器可读）。
| 子命令 | 作用 | 关键参数 | 退出码 |
|---|---|---|---|
init |
建任务合同与状态文件 | --title --goal --blocks --risk --deadline --done-when |
0 |
done |
登记某块完成 | --index --artifact --note |
0 |
status |
进度 + 剩余预估 + 收尾建议 | — | 0 |
wrap |
生成收尾包 | --reason --next --done-when |
0 |
resume |
打印恢复简报 | — | 0 |
verify |
校验状态与产物完整性 | — | 0 通过 / 1 有问题 |
无状态文件时执行 status 会提示先 init 并返回退出码 2，不会静默失败。
8. 交付前自检（八项）
- 是否先用三问判定了"值不值得立合同"？（小任务不上流程）
- 分块是否每块都能独立交付？
- 风险等级是否按"错了的代价"而非"难度"标的？
- 高风险块有没有被排在最后？
- 每完成一块是否立即登记，而不是攒到最后？
- 收尾决策是否给了三个选项的代价对比，而不是替用户拍板？
- 收尾包里是否写清了"验收标准未填写"这类数据缺口？
- 有没有忍住没去读余额、没联网、没动用户的业务文件？
