zcode-task-resume — ZCode 任务续跑 / 中断恢复 Skill

Agent 可以结束，但任务不能因为 Agent 结束而丢失。

一个任务类型无关（task-type-agnostic）的 Agent 基础能力：执行复杂、耗时较长、可能被中断的任务时，自动维护任务状态与 Checkpoint；无论因为什么原因中断（会话结束、超时、上下文耗尽、工具/网络失败、用户关闭），都不默认失败、不从头重来，而是从最近可靠断点继续推进，直到任务真正完成。

English: a ZCode skill for persistent, resumable agent tasks — stage decomposition, checkpoints, reality-checked resume after interruption, anti-duplication rules, a 3-strike error ladder, and an honest external-watchdog interface. Currently ZCode-specific; the plain-file state format and resume protocol are runtime-agnostic.

适配范围：目前仅适配 ZCode。Skill 发现路径遵循 ZCode 规范（~/.agents/skills/<name>/、<project>/.agents/skills/<name>/、<project>/.zcode/skills/<name>/）；状态文件（.agent-tasks/）与续跑协议是纯文件约定，未来如需支持其他 Agent 运行时可整体迁移。

---

它解决什么问题

Agent 执行长任务时最常见的三种失败模式：

失败模式	本 Skill 的对策
中断后从头再来，重复劳动	状态落盘 + 断点恢复（RESUME MODE / Task Successor）
会话结束被当成任务完成，伪造结果	完成门禁：COMPLETED 必须有客观证据，脚本层面强制拒绝
同一失败操作无限重试	三振升级：换策略 → 替代方案 → BLOCKED（保留全部恢复信息）

核心机制

• 状态存储：<project>/.agent-tasks/<task_id>/，含机器可读的 state.json（唯一事实源）和人读的 CHECKPOINT.md（每次写状态自动重新渲染）。
• 7 种状态：PENDING → IN_PROGRESS ⇄ INTERRUPTED/RESUMING/BLOCKED → COMPLETED/FAILED。前五种都可恢复；只有客观验证达成 completion_condition 才允许 COMPLETED。
• 阶段化拆分：复杂任务先拆成可独立验证的 Stage，每个阶段完成即 Checkpoint，任何阶段中断都不丢失。
• 以实际状态为准：Checkpoint 用于定位，实际环境用于确认。记录说"已完成"但实际只有一半 → 补完剩余部分，而不是推倒重建；实际比记录更靠前 → 把多做的部分记入状态。
• 防重复执行：恢复时 Inspect → Verify → Continue，绝不 Delete → Restart → Rebuild（唯一例外：产物客观损坏且修复成本高于重建，且必须留痕）。
• 诚实的外部接口：本 Skill 是"状态保存 + 恢复执行"层，不能从死掉的会话内部重启会话，也不伪造这个能力。它对外提供 resume-scan --prompt-only 输出的续跑提示词，任何外部 Watchdog（系统 cron、CI、ZCode 定时自动化）都能据此启动下一个 Agent。详见 references/watchdog-integration.md。

安装

把整个目录放到 ZCode 能发现 Skill 的位置（目录名必须保持 zcode-task-resume）：

# 用户级（所有项目可用，推荐）
git clone https://github.com/xwu43361-sys/zcode-task-resume.git ~/.agents/skills/zcode-task-resume

# 或项目级（仅当前项目可用）
git clone https://github.com/xwu43361-sys/zcode-task-resume.git <project>/.agents/skills/zcode-task-resume

依赖：无硬依赖。 scripts/task_state.js 是可选的零依赖 Node.js（≥14）CLI，提供原子写入、完成门禁和三振保护的机械强制；没有 Node.js 时，Agent 按 references/state-schema.md 直接读写 state.json，能力完整保留。

快速上手（Agent 视角）

cd <project>

# 创建任务（复杂任务先拆阶段，再初始化状态）
node ~/.agents/skills/zcode-task-resume/scripts/task_state.js init \
  --goal "把 12 个月度 CSV 汇总成 report.xlsx 并校验" \
  --condition "report.xlsx 存在且 scripts/validate.py 退出码 0" \
  --name annual-report

# 每个重要步骤：先写意图（write-ahead），做完验证，再记账 + Checkpoint
node .../task_state.js update <task_id> --action "正在写 merge.py"
node .../task_state.js update <task_id> --done "Stage 1 — 汇总 CSV" --stage-set "1:COMPLETED:行数比对通过"
node .../task_state.js checkpoint <task_id> --summary "raw_annual.csv 生成" --verification "wc -l 校验"

# 失败记账；同一步骤连续失败 3 次自动 BLOCKED
node .../task_state.js error <task_id> --error "GBK 编码崩溃" --step "merge" --strategy "加编码检测"

# 新会话接管：先扫描未完成任务，进入 RESUME MODE
node .../task_state.js resume-scan
node .../task_state.js resume-scan --prompt-only   # 直接输出给下一个 Agent 的续跑提示词

# 完成门禁：没有证据的 COMPLETED 会被拒绝
node .../task_state.js update <task_id> --status COMPLETED \
  --evidence "validate.py exit 0；12/12 月数据齐全"

CHECKPOINT.md 摘录（恢复时的第一读物）：

Task: Annual sales report consolidation
Goal: 把 12 个月度 CSV 汇总成一个年度报表 workbook 并校验数据
Status: IN_PROGRESS (updated 2026-09-06T16:40:12+08:00)

Completed:
- Stage 1 — 汇总 12 个月度 CSV 为 raw_annual.csv

Current:
- Stage 2 — 生成 report.xlsx — 正在写 scripts/build_xlsx.py

Next:
- 运行 python scripts/build_xlsx.py，然后 python scripts/validate.py 校验行数

Checkpoint:
- ck-0003 · 2026-09-06T16:39:58+08:00 — raw_annual.csv 生成，5678 行 〔verified: wc -l == 5678〕

Issues:
- (none)

长任务核心循环

START → LOAD TASK → 有未完成任务？
                      ├─ 是 → RESUME MODE（读目标/状态/断点 → 核实实际环境 → 对账 → 继续）
                      └─ 否 → CREATE TASK（拆阶段 → init）
→ 执行下一步 → 验证结果 → 保存 CHECKPOINT → 完成？
       ├─ 是 → 最终验证（对照原始目标）→ 带证据 COMPLETED
       └─ 否 → 继续（中断则：保存状态 → 等待接管）

Watchdog / 定时续跑

层级	机制	说明
Tier 1	同会话内持续推进	无需外部组件，Checkpoint 节奏兜底
Tier 2	新会话自动接管	在项目 AGENTS.md 加一行"会话开始先 resume-scan"（见参考文档）
Tier 3	外部 Watchdog	OS cron / CI / ZCode 定时自动化，定期以 resume-scan --prompt-only 的输出启动新 Agent；模板：scripts/watchdog_example.sh

测试

node tests/test_task_state.js        # 39 项断言：状态机、门禁、三振、恢复扫描
bash tests/e2e_resume_demo.sh        # 端到端：中断 → Task Successor 接管 → 无重复劳动 → 完成门禁

目录结构

zcode-task-resume/
├── SKILL.md                          # Skill 主文件（Agent 加载的指令）
├── references/
│   ├── state-schema.md               # state.json 完整字段表 + 状态机 + CHECKPOINT.md 模板
│   ├── recovery-playbook.md          # 恢复手册：核对清单、对账三案例、分领域验证探针、反模式
│   └── watchdog-integration.md       # 外部 Watchdog / 定时器集成（ZCode 自动化、cron、CI）
├── scripts/
│   ├── task_state.js                 # 零依赖 Node CLI（原子写入 + 完成门禁 + 三振保护）
│   └── watchdog_example.sh           # Watchdog 模板（LAUNCH_CMD 由部署方提供）
├── examples/state.example.json       # 完整状态示例
└── tests/                            # 单测 + 端到端演示

License

MIT