核心用法
task-ledger 是一套面向 OpenClaw 的长任务持久化工具包，解决大模型对话上下文中「任务易丢失、难恢复、难审计」的核心痛点。它将长运行任务转化为 durable task objects，通过 JSON 文件记录 checkpoint、执行日志与元数据，实现跨会话的断点续作与故障恢复。
关键操作流程：
1. 任务初始化：使用 new-task.sh 创建任务骨架，定义阶段目标与执行模式
2. 执行追踪：绑定 process/session/cron 等执行引用，每完成一阶段更新任务文件
3. 故障恢复：通过 resume-task.md 剧本，验证真实状态后从断点继续
4. 生命周期管理：task-doctor.py 诊断健康度，close-task.py 归档闭环
核心设计原则：「Task files are not truth. They are cached descriptions of truth. Reality wins.」—— 恢复时优先验证真实状态，而非盲信 JSON。
显著优点
- 会话无关性：任务状态持久化到文件系统，完全脱离脆弱的 chat context
- 生产级鲁棒性：支持后台执行、子代理、定时任务等复杂场景的状态同步
- 可审计可追踪：完整的执行日志、阶段变更历史与产物归档
- 零侵入设计：通过 shell/Python 脚本与 OpenClaw 现有工具链无缝集成
潜在局限
- 本地文件依赖：任务状态绑定工作区文件系统，跨机器迁移需手动同步
- 最终一致性：状态更新需显式调用脚本，异常崩溃可能丢失最新进度
- 学习曲线：用户需理解「plan → skeleton → execute → checkpoint」的范式转换
- 无内置分布式协调：多并发任务需自行处理锁机制
适合人群
- 运行 5 分钟以上长任务的开发者
- 需要后台/cron/子代理协同的复杂工作流用户
- 对任务可恢复性、可审计性有要求的生产环境
- 厌倦了「重新生成全部代码」式上下文丢失的 OpenClaw 重度用户
常规风险
- 状态漂移风险：未及时调用 update-task 可能导致 checkpoint 与实际执行脱节
- 敏感信息泄露：任务 JSON 可能捕获环境变量或密钥，需妥善管理 outputs/ 目录权限
- 恢复误判：resume 流程若未严格执行「验证真实状态」原则，可能基于 stale 数据错误决策
- 磁盘占用：长期运行的日志与产物需定期清理