HZL：面向智能体的持久化任务台账

HZL (https://hzl-tasks.com) 是一个本地优先的任务台账系统，智能体通过它实现以下功能：

• 将多步骤工作规划为项目与任务
• 设置进度检查点，确保工作跨越会话边界持续进行
• 通过项目池将工作路由至合适的智能体
• 通过租约机制和依赖关系实现多智能体协同

本技能旨在指导智能体掌握hzl命令行工具的使用。

HZL适用场景

OpenClaw本身不具备任务跟踪功能。与拥有TodoWrite的Claude Code或具备update_plan功能的Codex不同，OpenClaw依赖内存和Markdown文件进行工作跟踪。HZL正为此填补空白。

HZL适用于：

• 需要实际顺序执行或交接的多步骤项目
• 可能超出当前会话周期或涉及多智能体的工作
• 任何需要"精确断点续作"的场景
• 将工作委托给其他代理，并在其失败时需要进行恢复

以下情况请跳过 HZL：

• 真正琐碎、可立即完成的一步任务
• 基于时间的提醒（请改用 OpenClaw Cron）
• 长篇笔记或知识记录（请使用记忆文件）

经验法则：如果你觉得需要制定多步骤计划，或者有可能无法在当前会话中完成，请使用 HZL。

⚠️ 破坏性命令 — 请先阅读

除非用户明确要求删除数据，否则切勿运行这些命令。这些操作无法撤销。

核心概念

• 项目：任务的容器。在单智能体设置中，使用一个共享项目。在多智能体设置中，为每个智能体角色使用一个项目（池路由）。
• 任务：顶层工作项。对于多步骤的倡议，使用父任务。
• 子任务：任务的分解项（--parent <id>）。最多允许一层嵌套。父任务永远不会被hzl task claim --next命令返回。
• 检查点：用于会话恢复的简短进度快照。
• 租约：有时限的认领，可在多智能体流程中实现卡顿检测。

项目设置

单智能体设置

使用一个共享项目。请求和倡议应作为父任务，而非新项目。

hzl project list                    # Check first — only create if missing
hzl project create openclaw

所有内容都放入openclaw项目中。hzl task claim --next -P openclaw总是有效。

多智能体设置（池路由）

为每个智能体角色使用单独的项目。分配给项目（而非特定智能体）的任务可由监控该池的任何智能体认领。当某个角色可能扩展到多个智能体时，这是正确的模式。

hzl project create research
hzl project create writing
hzl project create coding
hzl project create marketing
hzl project create coordination    # for cross-agent work

池路由规则：将任务分配给项目，无需--agent参数。任何符合条件的智能体均可通过--next命令认领。

# Assigning work to the research pool (no --agent)
hzl task add "Research competitor pricing" -P research -s ready

# Kenji (or any researcher) claims it
hzl task claim --next -P research --agent kenji

智能体路由：当--agent在任务创建时被设置，只有该智能体（或未分配任务的智能体）可以通过--next命令认领它。未指定智能体的任务对所有人可用。

# Pre-route a task to a specific agent
hzl task add "Review Clara's PR" -P coding -s ready --agent kenji

# Kenji claims it (matches agent)
hzl task claim --next -P coding --agent kenji   # ✓ returns it

# Ada tries — skipped because it's assigned to kenji
hzl task claim --next -P coding --agent ada     # ✗ skips it

当您特别希望由某个人处理时，请在任务创建时使用--agent参数。当池中任何符合条件的智能体都应接手时，请省略该参数。

会话启动（主要工作流）

使用工作流命令（HZL v2+）

hzl workflow run start --agent <agent-id> --project <project> --json

--project是必需的 —— 代理必须限定在其分配的资源池范围内。使用--any-project以有意扫描所有项目（例如协调代理）。

此命令同时处理过期租约恢复和新任务认领。如果返回任务，则处理它。如果未返回任何内容，则队列为空。代理路由适用：分配给其他代理的任务会被跳过。

无工作流命令（备用方案）

hzl agent status                           # Who's active? What's running?
hzl task list -P <project> --available     # What's ready?
hzl task stuck                             # Any expired leases?
hzl task stuck --stale                     # Also check for stale tasks (no checkpoints)

# If stuck tasks exist, read their state before claiming
hzl task show <stuck-id> --view standard --json
hzl task steal <stuck-id> --if-expired --agent <agent-id> --lease 30
hzl task show <stuck-id> --view standard --json | jq '.checkpoints[-1]'

# Otherwise claim next available
hzl task claim --next -P <project> --agent <agent-id>

核心工作流

添加工作

hzl task add "Feature X" -P openclaw -s ready              # Single-agent
hzl task add "Research topic Y" -P research -s ready        # Pool-routed (multi-agent)
hzl task add "Subtask A" --parent <id>                      # Subtask
hzl task add "Subtask B" --parent <id> --depends-on <a-id>  # With dependency

处理任务

hzl task claim <id>                          # Claim specific task
hzl task claim --next -P <project>           # Claim next available
hzl task checkpoint <id> "milestone X"       # Checkpoint progress
hzl task complete <id>                       # Finish

状态转换

hzl task set-status <id> ready               # Make claimable
hzl task set-status <id> backlog             # Move back to planning
hzl task block <id> --comment "reason"       # Block with reason
hzl task unblock <id>                        # Unblock

状态：待办→就绪→进行中→已完成（或已阻塞）

完成子任务

hzl task complete <subtask-id>
hzl task show <parent-id> --view summary --json   # Any subtasks remaining?
hzl task complete <parent-id>               # Complete parent if all done

委派与交接工作

工作流命令（HZL v2+）

# Hand off to another agent or pool — complete current, create follow-on atomically
hzl workflow run handoff \
  --from <task-id> \
  --title "<new task title>" \
  --project <pool>              # --agent if specific person; --project for pool

# Delegate a subtask — creates dependency edge by default
hzl workflow run delegate \
  --from <task-id> \
  --title "<delegated task>" \
  --project <pool> \
  --pause-parent                # Block parent until delegated task is done

--agent和--project护栏规则：交接时必须至少指定一项。若省略--agent将创建池路由任务；--project此时必须指定以定义具体工作池。

手动委派（备用方案）

hzl task add "<delegated title>" -P <pool> -s ready --depends-on <parent-id>
hzl task checkpoint <parent-id> "Delegated X to <pool> pool. Waiting on <task-id>."
hzl task block <parent-id> --comment "Waiting for <delegated-task-id>"

依赖关系

# Add dependency at creation
hzl task add "<title>" -P <project> --depends-on <other-id>

# Add dependency after creation
hzl task add-dep <task-id> <depends-on-id>

# Query dependencies
hzl dep list --agent <id> --blocking-only          # What's blocking me?
hzl dep list --from-agent <id> --blocking-only     # What's blocking work I created?
hzl dep list --project <p> --blocking-only         # What's blocking in a pool?
hzl dep list --cross-project-only                  # Cross-agent blockers

# Validate no cycles
hzl validate

默认支持跨项目依赖。使用hzl dep list --cross-project-only命令可查看跨项目关联。

检查点设置

在重要里程碑节点或暂停操作前设置检查点。有效的检查点应能回答："如果当前会话立即中断，其他智能体能否从此处恢复？"

检查点设置时机：

• 在执行可能失败的工具调用前
• 在创建子智能体前
• 在完成有意义的工作单元后
• 在交接或暂停前

hzl task checkpoint <id> "Implemented login flow. Next: add token refresh." --progress 50
hzl task checkpoint <id> "Token refresh done. Testing complete." --progress 100
hzl task progress <id> 75          # Set progress without a checkpoint

生命周期钩子

HZL 针对高价值状态转换发送定向通知——目前仅支持on_done。其他生命周期事件（卡顿检测、阻塞、进度）需要轮询获取。这是有意为之：钩子用于通知有意义的事件发生，而代理和编排器则通过轮询处理其他所有情况。

钩子功能在安装时配置（具体设置请参阅文档网站）。作为代理，您需要了解以下操作要点：

• 仅on_done会触发通知。当您完成任务时，HZL 会将 webhook 加入队列。对于卡顿检测、陈旧检测、阻塞变更或进度查询——请通过hzl task stuck --stale或hzl task list命令进行轮询。
• 通知传递并非实时。 hzl hook drain基于cron计划运行（通常每2-5分钟执行一次）。您的任务完成状态会被立即记录，但通知需等到下一个抽取周期才会抵达网关。
• 有效载荷包含上下文信息。每条通知都携带代理标识、项目信息以及完整的事件详情。网关会按代理进行路由处理——无论哪个代理完成任务，HZL都会将相同的有效载荷发送至单一URL。
• 若钩子功能疑似失效，请检查hzl hook drain --json以获取投递失败记录及last_error的详细错误信息。

基于租约机制的多代理协调

# Claim with lease (prevents orphaned work)
hzl task claim <id> --agent <agent-id> --lease 30       # 30-minute lease

# Fleet status: who's active, what they're working on, how long
hzl agent status                                        # All agents
hzl agent status --agent <name>                         # Single agent
hzl agent status --stats                                # Include task count breakdowns

# Agent activity history
hzl agent log <agent>                                   # Recent events for an agent

# Monitor for stuck tasks
hzl task stuck

# Monitor for stuck AND stale tasks (no checkpoints for 10+ min)
hzl task stuck --stale
hzl task stuck --stale --stale-threshold 15               # Custom threshold

# Recover an abandoned task (steal + set new lease atomically)
hzl task show <stuck-id> --view standard --json         # Read last checkpoint first
hzl task steal <stuck-id> --if-expired --agent <agent-id> --lease 30

请为每个代理使用不同的--agent标识符（例如：henry、clara、kenji) 因此作者身份是可追溯的。

任务与项目的规模界定

可完成性测试：“我完成了[任务]”应当描述一个真实的成果。

• ✓ “完成了车库运动传感器的安装”
• ✗ “完成了家庭自动化”（开放式领域，永无止境）

在以下情况应拆分为多个任务：各组成部分能独立交付价值或解决不同问题。

添加上下文：

hzl task add "Install sensors" -P openclaw \
  -d "Mount at 7ft height per spec." \
  -l docs/sensor-spec.md,https://example.com/wiring-guide

不要将规范复制到描述中——应引用文档以避免信息漂移。

扩展参考

# Setup
hzl init                                      # Initialize (safe, won't overwrite)
hzl status                                    # Database mode, paths, sync state
hzl doctor                                    # Health check

# List and find
hzl task list -P <project> --available        # Ready tasks with met dependencies
hzl task list --parent <id>                   # Subtasks of a parent
hzl task list --root                          # Top-level tasks only
hzl task list -P <project> --tags <csv>       # Filter by tags

# Create with options
hzl task add "<title>" -P <project> --priority 2 --tags backend,auth
hzl task add "<title>" -P <project> -s in_progress --agent <name>
hzl task add "<title>" -P <project> --stale-after 2h
hzl task update <id> --stale-after 30m
hzl task update <id> --clear-stale-after

# Agent fleet status
hzl agent status                              # Active/idle agents, current tasks, lease state
hzl agent status --agent <name>               # Single agent
hzl agent status --stats                      # With task count breakdowns
hzl agent log <agent>                         # Activity history for an agent

# Web dashboard
hzl serve                                     # Start on port 3456
hzl serve --host 127.0.0.1                    # Restrict to localhost
hzl serve --background                        # Fork to background
hzl serve --status / --stop
hzl serve --gateway-url ws://host:18789       # Connect to OpenClaw gateway
hzl serve --gateway-token <token>             # Gateway auth token
# Or set gateway once in config.json: { "gateway": { "url": "...", "token": "..." } }

# Raw reporting surfaces
hzl events                                    # NDJSON event feed
hzl events --follow
hzl events --from 0 > events.jsonl
hzl stats --window 1h

# Authorship
hzl task claim <id> --agent alice
hzl task checkpoint <id> "note" --author bob  # Records who did the action
hzl task claim <id> --agent "Claude" --agent-id "session-abc123"

# Cloud sync (optional)
hzl init --sync-url libsql://<db>.turso.io --auth-token <token>
hzl sync

网页仪表板（常驻运行，Linux系统）

hzl serve --print-systemd > ~/.config/systemd/user/hzl-web.service
systemctl --user daemon-reload
systemctl --user enable --now hzl-web
loginctl enable-linger $USER

访问地址：http://<your-box>:3456（可通过Tailscale访问）。macOS系统请使用：hzl serve --background命令替代。

HZL不具备的功能

• 无编排功能——不会自动启动代理或分配工作
• 无任务分解——不自动拆解任务
• 无智能调度——采用简单优先级 + 先进先出排序

这些功能应归属于编排层，而非任务账本

注意事项

• 运行hzl通过exec工具
• 查阅TOOLS.md以获取您的身份标识字符串、需监控的项目，以及与您角色相关的命令
• 请为每个智能体使用不同的--agent身份标识，并依赖租约机制避免共享数据库中的冲突
• hzl workflow run命令要求 HZL v2+ 版本。若不可用，请采用上文记载的手动备用方案