核心功能
Task-ledger 是 OpenClaw 生态中的持久化任务管理工具包，专为超长运行、多阶段、具备外部副作用的复杂工作流设计。其核心能力包括：
1. 任务骨架与生命周期管理
通过 new-task.sh 创建结构化任务对象，以 JSON 文件形式持久化存储于 tasks/ 目录，配合 logs/ 和 outputs/ 实现执行轨迹与产出物分离。每个任务记录阶段推进、优先级、负责人及执行模式，形成可追溯的审计链。
2. 检查点与恢复机制
关键设计哲学："任务文件非真相，真相优先"（Task files are not truth. Reality wins.）。恢复时先执行 task-verify.py 核对实际状态，若检查点与现实冲突，修正后再续行，避免状态漂移导致的级联错误。task-resume-summary.py 生成断点摘要，支持对话重入后的快速上下文重建。
3. 关系感知与依赖调度
内置 parent/child 任务关系、执行依赖（ readiness-aware scheduling）及 task-start-if-ready.py 条件启动，防止下游任务在上游未就绪时盲目执行。task-graph-export.py 支持将任务拓扑导出为 Markdown、DOT 或 JSON，便于可视化与 handoff。
4. 执行绑定与外部引用
可绑定 process.sessionId、subtask.sessionKey、cron.jobId 三类外部执行实体，实现跨会话、跨代理、定时任务的统一追踪。
5. 回滚元数据与风险工作流模板
针对重启网关、服务部署、飞书文档同步等高风险操作，提供预置模板（restart-openclaw-gateway.example.json 等），强制要求记录回滚步骤与验证检查点。
6. 短优先报告机制
用户交互层遵循 "short-first reporting"：常规更新以 1-2 行摘要呈现，详细报告写入 outputs/ 文件，平衡信息密度与可读性。
显著优点
- 断线续命：会话断开、上下文丢失、OpenClaw 重启后仍可恢复任务
- 副作用安全：外部 API 调用、部署操作等具备回滚元数据与验证闭环
- 复杂依赖：原生支持任务树、条件调度，避免人工状态同步
- 审计友好：全生命周期 JSON 记录 + 人类可读导出
潜在局限
- 基础设施依赖：需
python3与bash环境，Windows 原生支持需 WSL - 学习曲线：理解 "reality wins" 验证模式及阶段粒度划分需实践磨合
- 非分布式锁：同一工作区的并发修改仍依赖文件锁或外部协调
适用人群
- 运维工程师：执行滚动重启、蓝绿部署等需分阶段验证的操作
- 自动化开发者：构建跨会话、跨 cron 周期的长周期工作流
- 多代理协作者：需要子任务（subagent）结果汇总与父任务状态同步的场景
常规风险
- 检查点污染：若忽视
task-verify.py直接续行，可能基于过期状态继续执行 - 权限扩散：
tasks/、logs/、outputs/目录需限制写入权限，防止敏感命令历史泄露 - 模板误用：风险工作流模板未经验证直接投产，可能遗漏环境特定的前置检查
安全评估说明
本简介基于技能文档自动生成，未执行动态安全扫描。建议实际部署前对 scripts/*.py 进行静态分析（如 Bandit），并对任务 JSON Schema 实施输入校验。