核心用法
task-ledger 是一套面向 OpenClaw 代理系统的轻量级持久化任务管理工具包，旨在解决长时间运行任务因上下文丢失而中断的痛点。其核心机制是将任务状态外化为可序列化的 JSON 检查点文件，而非依赖脆弱的对话上下文。
典型使用流程：
1. 触发条件识别：当任务预计运行超 5 分钟、包含 3 个以上阶段、涉及后台执行/子代理/cron 调度，或存在外部副作用时启用
2. 初始化工具包：首次使用需将 toolkit/ 下的脚本、模板复制到工作区根目录，创建 tasks/、logs/、outputs/ 目录
3. 创建任务骨架：通过 ./scripts/new-task.sh 生成任务定义，明确 slug、标题、目标、执行模式及阶段划分
4. 执行与记录：每个阶段完成后更新任务文件，记录关键执行引用（sessionId、subtaskKey、cron.jobId）
5. 状态管理：利用 task-advance.py、update-task.py、close-task.py 等工具推进流程
6. 故障恢复：通过 task-doctor.py 诊断状态，结合 resume-task.md 剧本验证现实状态后恢复
显著优点
- 韧性设计：任务可跨会话、重启、上下文窗口限制而存活
- 可审计性：完整的执行日志与阶段历史，便于事后追溯
- 协作友好：支持子代理分工，通过 task-bind-process 关联外部进程
- 轻量无依赖：仅依赖 bash/python3，无需外部数据库
- 显式状态机：强制阶段划分，避免隐式逻辑堆积
潜在缺点与局限性
- 最终一致性风险：检查点文件与现实状态可能漂移（文档明确警示"任务文件不是真相"）
- 手动协调成本：需开发者主动调用更新脚本，缺乏自动事务机制
- 文件系统依赖：基于本地文件 IO，分布式部署需额外同步方案
- 恢复复杂度：中断后需人工执行诊断流程，无法完全自动自愈
- 模板僵化：预定义阶段 CSV 格式对动态分支任务支持有限
适合人群
- 构建复杂自动化工作流的 OpenClaw 开发者
- 需要可靠后台任务管理的运维工程师
- 多步骤数据处理、长时间编译/训练、跨服务编排等场景的用户
- 重视可观测性与故障可恢复性的团队
常规风险
- 状态不一致：若脚本崩溃于更新调用之间，检查点将滞后于实际执行
- 并发冲突：多进程同时修改同一任务文件可能引发竞态（无内置锁机制）
- 敏感信息泄露：日志与任务文件可能捕获 sessionId、进程 ID 等执行引用，需配合工作区权限管理
- 误恢复风险：盲目信任陈旧检查点可能导致重复执行副作用操作，必须遵循"先验现实"原则