OA0 = Omni AI 0

OA0 是一个探索 AI 的论坛

现在注册

已注册用户请登录

名称： hzl
描述： 用于智能体协调的持久化任务账本。规划多步骤工作，跨会话边界检查点进度，并通过项目池路由实现多智能体协调。
元数据：
{ "openclaw": { "emoji": "🧾", "homepage": "https://github.com/tmchow/hzl", "requires": { "bins": ["hzl"] }, "install": [ { "id": "brew", "kind": "brew", "package": "hzl", "bins": ["hzl"], "label": "安装 HZL (Homebrew)" }, { "id": "node", "kind": "node", "package": "hzl-cli", "bins": ["hzl"], "label": "安装 HZL (npm)" } ] } }

HZL：智能体持久化任务账本

HZL (https://hzl-tasks.com) 是一个本地优先的任务账本，智能体可用来：

将多步骤工作规划为项目 + 任务
设置进度检查点，使工作能跨越会话边界持续
通过项目池将工作路由到合适的智能体
利用租约和依赖关系协调多个智能体

本技能教授智能体如何使用 hzl 命令行工具。

何时使用 HZL

OpenClaw 没有原生的任务跟踪功能。 与 Claude Code（拥有 TodoWrite）或 Codex（拥有 update_plan）不同，OpenClaw 依赖内存和 Markdown 文件来跟踪工作。HZL 填补了这一空白。

在以下情况使用 HZL：
- 具有实际顺序或交接需求的多步骤项目
- 可能超出当前会话生命周期或涉及多个智能体的工作
- 任何需要“从上次中断处精确恢复”的场景
- 将工作委派给其他智能体，并需要在其失败时进行恢复

在以下情况跳过 HZL：
- 你打算立即完成的真正琐碎的单步任务
- 基于时间的提醒（改用 OpenClaw Cron）
- 长篇笔记或知识记录（使用内存文件）

经验法则： 如果你有制定多步骤计划的冲动，或者有任何可能无法在当前会话内完成，请使用 HZL。

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

命令	效果
`hzl init --force`	删除所有数据。会提示确认。
`hzl init --force --yes`	删除所有数据，无需确认。
`hzl task prune ... --yes`	永久删除旧的已完成/已归档任务及其历史记录。

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

核心概念

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

项目设置

单智能体设置

使用一个共享项目。请求和计划应成为父任务，而非新项目。

hzl project list                    # 首先检查 — 仅在缺失时创建
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    # 用于跨智能体工作

池路由规则： 将任务分配给项目时不使用 --agent。任何符合条件的智能体都可以使用 --next 认领。

# 将工作分配给研究池（不使用 --agent）
hzl task add "研究竞争对手定价" -P research -s ready

# Kenji（或任何研究员）认领它
hzl task claim --next -P research --agent kenji

仅当你特别指定某个人时才使用 --agent。当任何符合条件的智能体都应该接手时，使用 --project。

会话启动（主要工作流）

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

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

此命令在一个命令中处理过期租约恢复和新任务认领。如果返回任务，则处理它。如果没有返回任何内容，则队列为空。

不使用工作流命令（备用方案）

hzl task list -P <project> --available     # 哪些任务就绪？
hzl task stuck                             # 有过期租约吗？

# 如果存在卡住的任务，在认领前先读取其状态
hzl task show <stuck-id> --json
hzl task steal <stuck-id> --if-expired --agent <agent-id>
hzl task show <stuck-id> --json | jq '.checkpoints[-1]'

# 否则认领下一个可用任务
hzl task claim --next -P <project> --agent <agent-id>

核心工作流

添加工作

hzl task add "功能 X" -P openclaw -s ready              # 单智能体
hzl task add "研究主题 Y" -P research -s ready        # 池路由（多智能体）
hzl task add "子任务 A" --parent <id>                      # 子任务
hzl task add "子任务 B" --parent <id> --depends-on <a-id>  # 带依赖关系

处理任务

hzl task claim <id>                          # 认领特定任务
hzl task claim --next -P <project>           # 认领下一个可用任务
hzl task checkpoint <id> "里程碑 X"       # 设置进度检查点
hzl task complete <id>                       # 完成任务

状态转换

hzl task set-status <id> ready               # 设为可认领状态
hzl task set-status <id> backlog             # 移回规划阶段
hzl task block <id> --comment "原因"       # 阻塞并说明原因
hzl task unblock <id>                        # 解除阻塞

状态流转：backlog → ready → in_progress → done（或 blocked）

完成子任务

hzl task complete <subtask-id>
hzl task show <parent-id> --json             # 还有剩余子任务吗？
hzl task complete <parent-id>               # 如果全部完成，则完成父任务

委派和交接工作

工作流命令（HZL v2+）

# 交接给另一个智能体或池 — 原子化地完成当前任务并创建后续任务
hzl workflow run handoff \
  --from <task-id> \
  --title "<新任务标题>" \
  --project <pool>              # 如果指定具体人员则用 --agent；池路由则用 --project

# 委派子任务 — 默认创建依赖关系
hzl workflow run delegate \
  --from <task-id> \
  --title "<委派任务>" \
  --project <pool> \
  --pause-parent                # 阻塞父任务，直到委派任务完成

--agent 和 --project 防护：交接时至少需要一个。省略 --agent 会创建一个池路由任务；此时需要 --project 来定义是哪个池。

手动委派（备用方案）

hzl task add "<委派标题>" -P <pool> -s ready --depends-on <parent-id>
hzl task checkpoint <parent-id> "已将 X 委派给 <pool> 池。等待 <task-id>。"
hzl task block <parent-id> --comment "等待 <delegated-task-id>"

依赖关系

# 创建时添加依赖
hzl task add "<标题>" -P <project> --depends-on <other-id>

# 创建后添加依赖
hzl task add-dep <task-id> <depends-on-id>

# 查询依赖关系
hzl dep list --agent <id> --blocking-only          # 什么在阻塞我？
hzl dep list --from-agent <id> --blocking-only     # 什么在阻塞我创建的工作？
hzl dep list --project <p> --blocking-only         # 什么在阻塞池中的工作？
hzl dep list --cross-project-only                  # 跨智能体阻塞项

# 验证无循环依赖
hzl validate

默认支持跨项目依赖。使用 hzl dep list --cross-project-only 检查跨项目依赖边。

设置检查点

在重要里程碑或暂停前设置检查点。一个好的检查点能回答：“如果这个会话现在终止，另一个智能体能从这里恢复吗？”

何时设置检查点：
- 在任何可能失败的工具调用之前
- 在生成子智能体之前
- 在完成一个有意义的单元工作之后
- 在交接或暂停之前

hzl task checkpoint <id> "已实现登录流程。下一步：添加令牌刷新。" --progress 50
hzl task checkpoint <id> "令牌刷新完成。测试完毕。" --progress 100
hzl task progress <id> 75          # 设置进度但不创建检查点

钩子交付

当任务状态变为 done 时，HZL 会将回调排入你配置的端点队列。drain 命令用于交付排队的回调。

hzl hook drain                     # 交付所有排队的回调（按计划运行）
hzl hook drain --dry-run           # 预览将要交付的内容

在 ~/.config/hzl/config.json 中配置（如果不存在则创建）：

{
  "hooks": {
    "on_done": {
      "url": "<OPENCLAW_GATEWAY_URL>/events/inject",
      "headers": {
        "Authorization": "Bearer <YOUR_GATEWAY_TOKEN>"
      }
    }
  }
}

HZL 使用主机进程模型 — 没有内置守护进程。在 OpenClaw 中，将 hzl hook drain 设置为每 2 分钟运行一次的定时任务。如果没有调度器，回调会排队但永远不会触发。

使用租约进行多智能体协调

# 使用租约认领（防止工作被孤立）
hzl task claim <id> --agent <agent-id> --lease 30       # 30分钟租约

# 监控卡住的任务
hzl task stuck

# 恢复被遗弃的任务
hzl task show <stuck-id> --json                          # 首先读取最后一个检查点
hzl task steal <stuck-id> --if-expired --agent <agent-id>

为每个智能体使用不同的 --agent ID（例如 henry、clara、kenji），以便追溯作者身份。

任务和项目规模

可完成性测试： “我完成了 [任务]” 应该描述一个真实的结果。
- ✓ “完成了车库运动传感器的安装”
- ✗ “完成了家庭自动化”（开放领域，永远无法完成）

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

添加上下文：

hzl task add "安装传感器" -P openclaw \
  -d "根据规范安装在 7 英尺高度。" \
  -l docs/sensor-spec.md,https://example.com/wiring-guide

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

扩展参考

# 设置
hzl init                                      # 初始化（安全，不会覆盖）
hzl status                                    # 数据库模式、路径、同步状态
hzl doctor                                    # 健康检查

# 列出和查找
hzl task list -P <project> --available        # 就绪且满足依赖关系的任务
hzl task list --parent <id>                   # 父任务的子任务
hzl task list --root                          # 仅顶级任务
hzl task list -P <project> --tags <csv>       # 按标签过滤

# 创建选项
hzl task add "<标题>" -P <project> --priority 2 --tags backend,auth
hzl task add "<标题>" -P <project> -s in_progress --agent <name>

# Web 仪表板
hzl serve                                     # 在端口 3456 启动
hzl serve --host 127.0.0.1                    # 限制为本地主机
hzl serve --background                        # 后台运行
hzl serve --status / --stop

# 作者身份
hzl task claim <id> --agent alice
hzl task checkpoint <id> "备注" --author bob  # 记录执行操作的人
hzl task claim <id> --agent "Claude" --agent-id "session-abc123"

# 云同步（可选）
hzl init --sync-url libsql://<db>.turso.io --auth-token <token>
hzl sync

Web 仪表板（常驻运行，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 不做什么

不进行编排 — 不会自动生成智能体或分配工作
不进行任务分解 — 不会自动分解任务
没有智能调度 — 使用简单的优先级 + FIFO 排序

这些功能属于你的编排层，而非任务账本。

注意事项

通过 exec 工具运行 hzl。
查看 TOOLS.md 了解你的身份字符串、需要监控的项目以及与你角色相关的命令。
在共享数据库中，为每个智能体使用不同的 --agent ID，并依赖租约来避免冲突。
hzl workflow run 命令需要 HZL v2+。如果不可用，请使用上面文档中记录的手动备用模式。

技能包地址：https://github.com/openclaw/skills/tree/main/skills/tmchow/hzl/SKILL.md

3 次点击 ∙ 0 人收藏

登录后收藏

目前尚无回复

0 条回复

hzl：OpenClaw 的持久化任务数据库