HZL

# HZL: Persistent task tracking for agents

HZL (https://github.com/tmchow/hzl) 是一个本地优先的任务账本（数据库支持，可选云端同步备份），代理可以使用它来：

- 将多步骤工作规划为项目 + 任务 - 检查点进度（以便工作跨越会话边界仍然存在） - 使用租约协调子代理或多个编码工具 - 生成可靠的状态报告（“已完成 vs 待办”）

本技能将教代理如何使用 `hzl` CLI。

## 何时使用 HZL

**OpenClaw 没有原生的任务跟踪工具。** 与 Claude Code（拥有 TodoWrite）或 Codex（拥有 update_plan）不同，OpenClaw 依赖内存和 Markdown 文件来跟踪工作。这使得 HZL 对 OpenClaw 尤其有价值。

**默认将 HZL 用于任何非平凡的任务跟踪：**

- 具有真实排序（依赖关系）和交接的多步骤项目 - 可能在此会话之外存活或跨越多个工具/代理的工作 - 编排：将工作委托给子代理，并在它们崩溃时需要恢复 - 任何“精确恢复到我们中断的地方”都很重要的情况 - **任何你想在当前会话之外持久化的工作** - **任何需要结构（嵌套、依赖关系、进度跟踪）的工作** - **任何受益于决策或所有权的持久记录的工作**

多会话或多代理工作是使用 HZL 的常见原因，而非硬性要求。 当任务非平凡时，即使对于单会话、单代理的工作，也请使用 HZL。

**为什么 HZL 是 OpenClaw 的正确选择：**

如果没有 HZL，OpenClaw 在上下文中跟踪任务（消耗空间，压缩时碎片化）或在 Markdown 文件中跟踪（需要手动管理，无嵌套/依赖关系，无仪表板）。HZL 提供了：

- 跨越会话边界存活的持久存储 - 嵌套（父任务 + 子任务）和依赖关系 - 用于人工可见性的 Web 仪表板（`hzl serve`） - 用于多代理协调的租约 - 用于进度恢复的检查点

**仅在以下情况跳过 HZL：**

- 真正琐碎、一步到位且你将在当前会话立即完成的任务 - 基于时间的提醒/警报（请改用 OpenClaw Cron） - 长篇笔记或知识捕获（请使用笔记或记忆系统）

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

示例：“调查失败的测试并修复根本原因” -> 使用 HZL，因为它可能涉及多个子任务，即使你期望在会话内完成。

个人任务：HZL 不是一个精致的人类待办事项应用，但它可用于个人任务跟踪，也可以作为轻量级 UI 的后端。

## 核心概念

- **项目 (Project)**：稳定的容器。对于 OpenClaw，请使用单个 `openclaw` 项目——这可以保持 `hzl task next` 的简单性。创建前请检查 `hzl project list`。 - **任务 (Task)**：顶层工作项。对于多步骤请求，这将成为父任务。 - **子任务 (Subtask)**：将任务分解为部分（`--parent <id>`）。最多 1 级嵌套。父任务是组织容器——永远不会由 `hzl task next` 返回。 - **检查点 (Checkpoint)**：用于支持恢复的简短进度快照 - **租约 (Lease)**：时限声明（防止多代理流程中的孤立工作）

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

以下命令**永久删除 HZL 数据**且无法撤消：

| 命令 | 效果 | |---------|--------| | `hzl init --force` | **删除所有数据。** 提示确认。 | | `hzl init --force --yes` | **未经确认删除所有数据。** 极其危险。 | | `hzl task prune ... --yes` | **永久删除**旧的已完成/已归档任务及其事件历史。 |

**AI 代理：除非用户明确要求你删除数据，否则绝不运行这些命令。**

- `hzl init --force` 删除整个事件数据库：所有项目、任务、检查点和历史记录 - `hzl task prune` 仅删除处于终止状态（已完成/已归档）且超过指定年限的任务 - 没有撤消。没有备份就无法恢复。

## 反模式：项目泛滥

使用单个 `openclaw` 项目。请求和计划成为**父任务**，而非新项目。

**错误（造成泛滥）：** ```bash hzl project create "garage-sensors" hzl project create "query-perf" # Now you have to track which project to query ```

**正确（单个项目，父任务）：** ```bash # Check for existing project first hzl project list

# Use single openclaw project hzl task add "Install garage sensors" -P openclaw # → Created task abc123

hzl task add "Wire sensor to hub" --parent abc123 hzl task add "Configure alerts" --parent abc123

# hzl task next --project openclaw always works ```

为何这很重要： - 项目会永远累积；你将有数十个被遗弃的一次性项目 - `hzl task next --project X` 需要知道查询哪个项目 - 使用单个项目，`hzl task next --project openclaw` 始终有效

## 规划父任务大小

HZL 支持一级嵌套（父任务 → 子任务）。将父任务限定为可完成的结果。

**可完成性测试：**“我完成了 [父任务]”应该描述一个真实的结果。 - ✓ “完成了车库运动传感器的安装” - ✓ “修复了查询性能” - ✗ “完成了家庭自动化”（开放式领域，永无止境） - ✗ “完成了后端工作”（如果功能发布还需要前端待定）

**按问题而非技术层界定范围。** 如果全栈功能（前端 + 后端 + 测试）是一起发布的，通常是一个父任务。

**在以下情况拆分为多个父任务：** - 各部分交付独立价值（可以单独发布） - 你正在解决恰好相关的不同问题

**添加上下文：** 使用 `-d` 添加详细信息，使用 `-l` 添加参考文档： ```bash hzl task add "Install garage sensors" -P openclaw \ -d "Per linked spec. Mount sensors at 7ft height." \ -l docs/sensor-spec.md,https://example.com/wiring-guide ```

**不要将规范重复到描述中**——这会导致差异。请参考文档。

**如果文档不存在**，请包含足够的详细信息以便另一个代理完成任务： ```bash hzl task add "Configure motion alerts" -P openclaw -d "$(cat <<'EOF' Trigger alert when motion detected between 10pm-6am. Use Home Assistant automation. Notify via Pushover. EOF )" ``` 描述支持 Markdown（最大 16KB）。

## 核心工作流

**设置：** ```bash hzl project list # Always check first hzl project create openclaw # Only if needed ```

**添加工作：** ```bash hzl task add "Feature X" -P openclaw -s ready # Ready to claim hzl task add "Subtask A" --parent <id> # Subtask hzl task add "Subtask B" --parent <id> --depends-on <subtask-a-id> # With dependency ```

**处理任务：** ```bash hzl task next -P openclaw # Next available task hzl task next --parent <id> # Next subtask of parent hzl task next -P openclaw --claim # Find and claim in one step hzl task claim <id> # Claim specific task hzl task checkpoint <id> "milestone X" # Notable progress or before pausing ```

**更改状态：** ```bash hzl task set-status <id> ready # Make claimable (from backlog) hzl task set-status <id> backlog # Move back to planning ``` 状态：`backlog` → `ready` → `in_progress` → `done`（或 `blocked`）

**当受阻时：** ```bash hzl task block <id> --comment "Waiting for API keys from DevOps" hzl task unblock <id> # When resolved ```

**完成工作：** ```bash hzl task comment <id> "Implemented X, tested Y" # Optional: final notes hzl task complete <id>

# After completing a subtask, check parent: hzl task show <parent-id> --json # Any subtasks left? hzl task complete <parent-id> # If all done, complete parent ```

**故障排除：** | 错误 | 修复方法 | |-------|-----| | "not claimable (status: backlog)" | `hzl task set-status <id> ready` | | "Cannot complete: status is X" | 先声明：`hzl task claim <id>` |

---

## 扩展参考（需要时查阅 —— 首次阅读时可跳过）

```bash # Setup hzl init # Initialize (safe, won't overwrite) hzl init --reset-config # Reset config to default location hzl status # Database mode, paths, sync state hzl doctor # Health check for debugging

# Create with options hzl task add "<title>" -P openclaw --priority 2 --tags backend,auth hzl task add "<title>" -P openclaw --depends-on <other-id> hzl task add "<title>" -P openclaw -s in_progress --assignee <name> # Create and claim

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

# Dependencies hzl task add-dep <task-id> <depends-on-id> hzl validate # Check for circular dependencies

# Web Dashboard hzl serve # Start on port 3456 (network accessible) hzl serve --host 127.0.0.1 # Restrict to localhost only hzl serve --background # Fork to background hzl serve --status # Check if running hzl serve --stop # Stop background server

# Multi-agent recovery hzl task claim <id> --assignee <agent-id> --lease 30 hzl task stuck hzl task steal <id> --if-expired --author <agent-id> ```

提示：当工具需要解析输出时，首选 `--json`。

## 作者身份跟踪

HZL 在两个级别跟踪作者身份：

| 概念 | 跟踪内容 | 设置方式 | |---------|----------------|--------| | **受托人 (Assignee)** | 任务归谁所有 | `claim` 或 `add` 时的 `--assignee` | | **事件作者 (Event author)** | 谁执行了操作 | 其他命令上的 `--author` |

`claim` 和 `add`（配合 `-s in_progress`）上的 `--assignee` 标志设置任务所有权。其他命令（checkpoint、comment、block 等）上的 `--author` 标志记录谁执行了每个操作：

```bash # Alice owns the task hzl task claim 1 --assignee alice

# Bob adds a checkpoint (doesn't change ownership) hzl task checkpoint 1 "Reviewed the code" --author bob

# Task is still assigned to Alice, but checkpoint was recorded by Bob ```

对于需要会话跟踪的 AI 代理，请在 claim 时使用 `--agent-id`： ```bash hzl task claim 1 --assignee "Claude Code" --agent-id "session-abc123" ```

## 推荐模式

### 启动多步骤项目

1) 使用单个 `openclaw` 项目（仅在不存在时创建）。 2) 为该计划创建父任务。 3) 分解为具有依赖关系的子任务。 4) 验证。

```bash # Check if project exists first hzl project list # Create only if needed hzl project create openclaw

# Parent task for the initiative hzl task add "Implement auth system" -P openclaw --priority 3 # → abc123

# Subtasks with sequencing hzl task add "Clarify requirements + acceptance criteria" --parent abc123 --priority 5 hzl task add "Design API + data model" --parent abc123 --priority 4 --depends-on <reqs-id> hzl task add "Implement endpoints" --parent abc123 --priority 3 --depends-on <design-id> hzl task add "Write tests" --parent abc123 --priority 2 --depends-on <impl-id> hzl task add "Docs + rollout plan" --parent abc123 --priority 1 --depends-on <tests-id>

hzl validate ```

### 从之前的会话恢复

这是 OpenClaw 代理的核心用例 —— 你重新启动并需要从上次会话中断的地方继续。

```bash # 1. Check what's in progress or stuck hzl task list -P openclaw --available # What's ready to work? hzl task stuck # Any expired leases from crashed sessions?

# 2. If there are stuck tasks, review their checkpoints before stealing hzl task show <stuck-id> --json # Read last checkpoint to understand state

# 3. Steal the expired task and continue hzl task steal <stuck-id> --if-expired --author orchestrator

# 4. Read the last checkpoint to know exactly where to resume hzl task show <stuck-id> --json | jq '.checkpoints[-1]'

# 5. Continue working, checkpoint your progress hzl task checkpoint <stuck-id> "Resumed from previous session. Continuing from: <last checkpoint>" ```

**如果没有受阻任务：** 只需使用 `hzl task next -P openclaw --claim` 来获取下一个可用的工作。

### 使用检查点处理任务

在重要里程碑之前或暂停工作之前进行检查点。检查点应简短且具有可操作性： - 你完成了什么 - 下一步是什么（如果继续）

**何时进行检查点（针对 AI 代理）：** - 在任何可能失败的工具调用之前（API 调用、部署、安装） - 在生成子代理之前（以防其崩溃） - 在会话可能压缩之前（长时间运行的工作） - 在完成有意义的工作单元之后 - 在暂停之前或交接给另一个代理之前

**经验法则：** 如果会话现在结束，另一个代理能否从你上一个检查点恢复？如果不能，立即检查点。

```bash hzl task claim <id> --assignee orchestrator # ...do work... hzl task checkpoint <id> "Implemented login flow. Next: add token refresh." --progress 50 # ...more work... hzl task checkpoint <id> "Added token refresh. Testing complete." --progress 100 hzl task complete <id> ```

你也可以在不使用检查点的情况下设置进度： ```bash hzl task progress <id> 75 ```

### 处理受阻任务

当卡在外部依赖项上时，将任务标记为受阻：

```bash hzl task claim <id> --assignee orchestrator hzl task checkpoint <id> "Implemented login flow. Blocked: need API key for staging." hzl task block <id> --comment "Blocked: waiting for staging API key from DevOps"

# Later, when unblocked: hzl task unblock <id> --comment "Unblocked: received API key from DevOps" hzl task checkpoint <id> "Got API key, resuming work" hzl task complete <id> ```

**注释最佳实践：** 包含有关操作的上下文，而不仅仅是状态： - 好：“受阻：等待基础设施团队提供 API 密钥” - 好：“已解除受阻：密钥已收到，恢复工作” - 坏：“等待 API 密钥”（缺少操作上下文）

受阻任务在仪表板中保持可见（“受阻”列）并保留其受托人，但不会出现在 `--available` 列表中。

### 使用租约协调子代理

在委派时使用租约，以便检测被遗弃的工作并恢复。

```bash hzl task add "Implement REST endpoints" -P myapp-auth --priority 3 --json hzl task claim <id> --assignee subagent-claude-code --lease 30 ```

通过明确的指令进行委派： - 声明任务（使用其作者 ID） - 逐步检查点进度 - 完成时标记完成

监控： ```bash hzl task show <id> --json hzl task stuck hzl task steal <id> --if-expired --author orchestrator ```

### 使用子任务分解工作

使用父任务/子任务层次结构来组织复杂工作：

```bash # Create parent task hzl task add "Implement vacation booking" -P portland-trip --priority 2 # → abc123

# Create subtasks (project inherited automatically) hzl task add "Research flights" --parent abc123 hzl task add "Book hotel" --parent abc123 --depends-on <flights-id> hzl task add "Plan activities" --parent abc123

# View breakdown hzl task show abc123

# Work through subtasks hzl task next --parent abc123 ```

**重要：** `hzl task next` 仅返回叶任务（没有子任务的任务）。父任务是组织容器——永远不会作为“下一个可用工作”返回。

**完成子任务：** 完成每个子任务后，检查父任务是否仍有剩余工作： ```bash hzl task complete <subtask-id>

# Check parent status hzl task show abc123 --json # Any subtasks left? hzl task complete abc123 # If all done, complete parent ```

## Web 仪表板

HZL 包含一个内置的看板仪表板，用于监控任务状态。仪表板按列（待办 → 受阻 → 就绪 → 进行中 → 已完成）显示任务，并支持按日期和项目筛选。

### 设置仪表板（推荐用于 OpenClaw）

若要在 OpenClaw 设备上进行全天候访问，请将其设置为 systemd 服务（仅限 Linux）：

```bash # Check if service already exists before overwriting systemctl --user status hzl-web 2>/dev/null && echo "Service already exists — skip setup" && exit 0

# Create the systemd user directory if needed mkdir -p ~/.config/systemd/user

# Generate and install the service file hzl serve --print-systemd > ~/.config/systemd/user/hzl-web.service

# Enable and start systemctl --user daemon-reload systemctl --user enable --now hzl-web

# IMPORTANT: Enable lingering so the service runs even when logged out loginctl enable-linger $USER

# Verify it's running systemctl --user status hzl-web ```

仪表板将在 `http://<your-box>:3456`（可通过 Tailscale 访问）提供。

若要使用不同的端口： ```bash hzl serve --port 8080 --print-systemd > ~/.config/systemd/user/hzl-web.service ```

**macOS 说明：** systemd 仅限 Linux。在 macOS 上，请使用 `hzl serve --background` 或手动创建 launchd plist。

### 快速命令

```bash hzl serve # Start in foreground (port 3456) hzl serve --background # Fork to background process hzl serve --status # Check if background server is running hzl serve --stop # Stop background server hzl serve --host 127.0.0.1 # Restrict to localhost only ```

对于临时会话，请使用 `--background`。对于全天候访问，请使用 systemd。

## 最佳实践

1. **始终使用 `--json`** 进行程序化输出 2. **在里程碑处建立检查点** 或在暂停工作前 3. **完成任务前检查注释** 4. **对所有工作使用单个 `openclaw` 项目** 5. **使用依赖项** 来表达排序，而非优先级 6. **使用租约** 处理长时间运行的工作，以便检测卡死情况 7. **在接管卡死任务前审查检查点**

## HZL 不做什么

HZL 经过精心设计，功能有限：

- **无编排** - 不会生成代理或分配工作 - **无任务分解** - 不会自动拆解任务 - **无智能调度** - 使用简单的优先级 + FIFO 排序

这些是编排层的功能，而不是任务跟踪器的功能。

## OpenClaw 特定说明

- 通过 Exec 工具运行 `hzl ...`。 - OpenClaw 的技能门控检查会在技能加载时检查主机上的 `requires.bins`。如果启用了沙箱，二进制文件也必须存在于沙箱容器内部。请通过 `agents.defaults.sandbox.docker.setupCommand` 进行安装（或使用自定义镜像）。 - 如果多个代理共享同一个 HZL 数据库，请使用不同的 `--assignee` ID（例如：`orchestrator`、`subagent-claude`、`subagent-gemini`），并依靠租约来避免冲突。