HZL

核心功能

HZL 是一款专为 AI Agent 设计的本地优先任务账本系统，通过 hzl CLI 提供多步骤工作规划、进度检查点和跨会话持久化能力。其核心定位是填补 OpenClaw 缺乏原生任务追踪的空白，支持单 Agent 项目管理和多 Agent 池路由两种模式。

主要特性

任务层级与状态管理：支持项目→父任务→子任务三级结构，内置 backlog → ready → in_progress → done → blocked 完整状态流转，支持依赖关系和最大一层嵌套。

多 Agent 协调机制：通过项目池（pool routing）实现角色级任务分配——省略 --agent 参数时任务进入公共池，任何监控该池的 Agent 均可认领；指定 --agent 则实现专属路由。结合 --lease 租约机制防止任务孤儿，支持 task steal 回收过期任务。

会话恢复与检查点：checkpoint 命令记录关键进度快照，配合 workflow run start 实现跨会话无缝恢复。推荐在工具调用前、子 Agent 派生前、暂停前等关键节点打点。

工作流命令（v2+）：handoff 实现原子化任务交接，delegate 支持带依赖关系的子任务委派并可暂停父任务，简化多 Agent 协作流程。

显著优点

• 本地优先架构：数据自主可控，支持可选的 Turso/LibSQL 云同步
• 明确的协作契约：租约、依赖、状态机提供清晰的 Agent 间协作语义
• 灵活的路由策略：单共享项目或多项目池模式适配不同团队规模
• 丰富的可观测性：agent status、task stuck、events NDJSON 流、内置 Web Dashboard

潜在局限

• 无自动编排：不自动派生 Agent 或分解任务，需外部编排层驱动
• 简单调度策略：仅支持优先级+FIFO，无智能负载均衡
• 钩子延迟：on_done 通知通过 cron 轮询（2-5分钟），非实时推送
• 嵌套限制：子任务仅支持单层，复杂层级需扁平化处理

适用场景

适合需要「精确断点续作」的多步骤项目、跨 Agent 工作交接、长期运行可能中断的任务编排。不适合即时单步任务、时间提醒或长文知识库管理。

风险提示

hzl init --force 和 --yes 组合会无确认删除全部数据；task prune --yes 永久清除历史记录，无回滚机制。建议生产环境配合定期备份。

核心用法

HZL 是一个本地优先的 CLI 任务账本工具，专为 OpenClaw 等无原生任务追踪的代理环境设计。核心工作流分为三步：

1. 项目初始化：单代理场景使用统一项目（如 openclaw），多代理场景按角色分池（如 research、coding、writing）
2. 任务生命周期：task add 创建 → claim 认领 → checkpoint 检查点 → complete 完成
3. 协调机制：通过 --lease 租赁防止任务孤儿，--agent 路由实现精确分配，依赖管理支持跨项目阻塞检测

关键命令：hzl workflow run start 统一处理会话启动（含过期租赁恢复和新任务认领）；hzl task steal 支持孤儿任务回收；hzl serve 启动 Web 仪表盘。

显著优点

• 会话持久化：解决 OpenClaw 无原生 TodoWrite 的核心痛点，工作进度可跨会话精确恢复
• 多代理原生设计：项目池路由、租赁机制、代理身份追踪均为多代理场景优化
• 零外部依赖：纯本地 SQLite 优先，可选 Turso 同步，无网络亦可运行
• 破坏性操作防护：--force 删除强制确认，文档明确标注危险命令
• 灵活协调模式：支持精确代理路由（--agent）或池化竞争认领（省略 --agent）

潜在缺点与局限性

• 无自动编排：不自动分解任务、不智能调度、不代理生成，需外部编排层配合
• 钩子能力有限：仅 on_done 事件推送，其他状态变更需轮询检测
• 子任务限制：仅支持一级嵌套，复杂工作分解受限
• CLI 学习成本：20+ 子命令，多代理场景需理解池路由与租赁概念
• 生态锁定：专为 OpenClaw 设计，与其他平台（Claude Code、Codex）的 update_plan 机制不互通

适合人群

• 需要跨会话持久化复杂多步骤工作的 OpenClaw 用户
• 多代理协作场景（研究团队+写作团队+开发团队分池协作）
• 对任务可追溯性有高要求的企业场景（检查点、代理身份、历史日志）
• 需要本地优先、数据可控的隐私敏感环境

常规风险

1. 数据丢失风险：hzl init --force --yes 和 task prune --yes 永久删除无恢复，需用户显式确认
2. 租赁冲突：代理 ID 重复或租赁过期配置不当可能导致任务被误抢或孤儿
3. 依赖循环：hzl validate 需手动运行，跨项目依赖可能形成隐性阻塞
4. 网关配置：--gateway-url 模式若令牌泄露，Web 仪表盘可能暴露任务数据
5. 版本兼容性：workflow run 命令需 HZL v2+，旧版本需回退手动模式

使用建议

建议配合 TOOLS.md 中的代理身份配置，严格区分 --agent ID，定期运行 hzl doctor 健康检查，多代理生产环境启用 --lease 租赁保护。