轮询最佳实践

一种以指导风格设计的技能，用于通过 兼容 cron 的轮询模式 自动化长期运行、异步执行的任务。当某项任务无法同步完成时（例如：一个触发后台作业并返回作业 ID 的 CLI 命令），该技能将引导智能体完成以下步骤：(1) 判断轮询是否适用；(2) 与用户进行一次性预检确认；(3) 创建任务专属目录；(4) 编写轮询脚本；(5) 启动后台作业；(6) 持续监控直至完成或超时。

语言要求：所有面向用户的确认信息均须使用用户当前会话所用语言（请检查会话语言 — 若用户使用中文交流，则以中文回复；若为英文，则以英文回复）。

1. 适用性核查清单

开始前，智能体必须回答以下问题：

✅ 适用于轮询 — 当且满足以下全部条件时：

• 目标命令/API 能 立即返回 一个 进程 ID、作业 ID、产物 ID 或类似句柄
• 存在 明确、可被机器解析的完成判定条件（例如：JSON/TOML 中的某个字段、状态字符串、退出码、某个文件的出现）
• 该条件可通过 重复执行同一命令 或调用一个轻量级查询命令来验证
• 等待时间 可预期（通常为 1–15 分钟）
• 执行过程中 无需实时用户交互

❌ 不适用于轮询 — 当满足以下任一条件时：

• 任务完成与否需依赖 复杂的 LLM 判断（例如：“该输出是否已足够好？”）
• 任务需向用户 实时流式输出或展示输出内容
• 任务结果在轮询过程中会因中间状态而 动态变化
• 完成判定条件 模糊或主观
• 用户希望在执行中途 中止或重定向任务

若任务不适用于轮询，请告知用户，并建议替代方案（例如：同步执行、仅对最终等待阶段使用子智能体配合轮询等）。

2. 预检确认（一次性确认全部参数）

启动任何轮询任务前，必须以单条消息向用户确认全部参数。此举可避免来回沟通，并明确各方预期。

确认信息须使用用户当前会话语言。

示例（英文）：

Before starting, please confirm the following:

① Polling target
  - Task: [brief description]
  - Command to check status: [exact command]
  - Expected completion condition: [e.g., output contains "status: completed"]

② Poll interval: every [X] minutes (default: 5 minutes)
③ Max duration: up to [Y] polls = [Z] minutes max (default: 40 min / 8 polls)
④ On completion: [download file / run command / send message / do nothing]
⑤ On failure/timeout: [notify me / stay silent]
⑥ Output directory: [path] (default: ~/Downloads or relevant workspace folder)
⑦ Temp folder retention: keep for review after completion? [yes / no]

Reply with any changes, or "ok" to proceed with defaults.

示例（中文 — 结构相同，内容翻译）：

启动前请确认以下参数：

① 轮询对象
  - 任务：[简短描述]
  - 状态查询命令：[具体命令]
  - 成功判定条件：[例如输出包含 "status": "completed"]

② 轮询频率：每 [X] 分钟一次（默认：5 分钟）
③ 最长持续时间：最多 [Y] 次轮询 = [Z] 分钟（默认：40 分钟 / 8 次）
④ 完成后动作：[下载文件 / 运行命令 / 发消息 / 不做处理]
⑤ 失败/超时时：[通知我 / 不通知]
⑥ 产物保存位置：[路径]（默认：~/Downloads 或相关工作目录）
⑦ 临时文件夹保留：完成后保留供复查？[是 / 否]

直接回复修改项，或"确认"以默认参数启动。

未获用户确认前，不得启动轮询。 若用户在合理时间内未响应，请仅跟进一次。

3. 临时目录结构

每个轮询任务均拥有独立的临时目录。这使任务具备自包含性、可恢复性，也便于后续检查或清理。

/tmp//                          ← category：例如 notebooklm、deep-research、generic
  _/  ← 按时间戳命名的单任务目录
    task.json          ← 任务元数据及全部参数
    progress.json      ← 当前轮询状态（轮询次数、上次检查时间、各类句柄）
    poll.log           ← 每次轮询尝试的日志（时间戳 + 结果）
    error.log          ← 遇到的错误
    done.flag          ← 空文件，任务成功完成后创建
    
     ← 下载或生成的任意产物

命名规则：

• 分类目录名：小写、使用连字符分隔、能准确描述任务类型（例如：notebooklm-audio、deep-research、generic-async）
• 任务子目录名：YYMMDD-HHmm + _ + 清洗后的任务名（空格→连字符，最长 40 字符，剔除特殊字符）

若分类目录尚不存在，则创建之；若任务子目录已存在（例如此前已有尝试），则询问用户：“继续之前任务，还是重新开始？”

task.json 格式定义

{
  "category": "notebooklm-audio",
  "task_name": "example-notebook-audio",
  "poll_command": "nlm studio status ",
  "parse_rule": {
    "type": "json",
    "path": ".[0].status",
    "success_value": "completed",
    "failure_value": "failed"
  },
  "on_complete_command": "nlm download audio  --id  -o ",
  "verify_output": true,
  "poll_interval_seconds": 300,
  "max_polls": 8,
  "timeout_action": "notify",
  "failure_action": "notify",
  "output_path": "/path/to/output.m4a",
  "temp_dir": "/tmp/notebooklm-audio/260325-1400_example-audio",
  "created_at": "2026-03-25T22:00:00Z",
  "user_confirmed": true
}

progress.json 格式定义

{
  "poll_count": 3,
  "last_poll_at": "2026-03-25T22:15:00Z",
  "last_poll_result": "in_progress",
  "artifact_id": "abc123...",
  "current_handle": "..."
}

4. 编写轮询脚本

将脚本写入任务临时目录（/poll.sh）。脚本必须 完全自包含 —— 除标准 Unix 工具外，不得依赖任何外部组件。

必需特性：

• 脚本开头必须包含 set -euo pipefail
• 启动时须检查 done.flag —— 若已存在，则立即以 0 退出（任务已完成）
• 发生任何错误（如认证过期、命令失败、超时）时，须记录至 error.log 并在退出前保存当前进度
• 每次轮询尝试后均须更新 progress.json
• 每次轮询结果均须追加至 poll.log（含时间戳 + 截断后的输出）
• 禁止删除临时目录 —— 清理时机由用户决定

脚本模板（最小可用版）：

#!/bin/bash
set -euo pipefail

TASK_DIR="/tmp/category/YYMMDD-HHmm_taskname"
cd "$TASK_DIR"

# Check if already done
[[ -f done.flag ]] && echo "Already complete." && exit 0

# Load progress
POLL_COUNT=$(grep '"poll_count"' progress.json 2>/dev/null | sed 's/[^0-9]//g') || POLL_COUNT=0
MAX_POLLS=8
INTERVAL=300

while true; do
  POLL_COUNT=$((POLL_COUNT + 1))

  if [[ $POLL_COUNT -gt $MAX_POLLS ]]; then
    echo "[$(date)] TIMEOUT after $MAX_POLLS polls" >> error.log
    exit 1
  fi

  echo "[$(date)] Poll $POLL_COUNT/$MAX_POLLS" >> poll.log

  # Run the poll command
  RESULT=$( 2>&1) || true
  echo "$RESULT" >> poll.log

  # Parse result — adapt to your command's output format
  if echo "$RESULT" | grep -q '"status": "completed"'; then
    touch done.flag
    # Run on-complete command if set
    echo "Done." >> poll.log
    exit 0
  fi

  # Save progress
  sed -i "s/"poll_count": [0-9]*/"poll_count": $POLL_COUNT/" progress.json

  sleep "$INTERVAL"
done

5. 启动与监控

启动被轮询的后台作业

1. 首先执行 触发命令（例如：nlm audio create ），以启动后台任务并捕获其 ID/句柄。
2. 将返回的 ID 写入 progress.json 和 task.json。
3. 随后以后台进程方式启动轮询脚本。

# In the task's temp dir:
nohup bash poll.sh > /dev/null 2>&1 &
echo "Polling started in background (PID: $!)"

轮询脚本应独立于 OpenClaw 会话长期存活。 智能体无需保持活跃即可维持轮询运行。

监控策略

• 禁止在 OpenClaw 会话内执行轮询（子智能体或 exec 循环会浪费资源，且增加故障恢复复杂度）。
• 若 OpenClaw 收到用户询问“是否已完成？”的消息，智能体可直接检查临时目录下的 done.flag 或 poll.log 来回应，无需发起新的轮询。
• 若新会话启动后用户要求检查某任务状态，则读取 progress.json 判断当前进展。

6. 超时与错误处理

超时/失败后：禁止自动重试。应明确告知用户任务未完成，并提供如下选项：

1. 使用相同参数重试
2. 调整参数后重试
3. 手动清理临时目录

7. 任务完成时的操作

1. 验证输出文件是否存在且非空（[[ -s "$output_path" ]]）
2. 创建 done.flag
3. 若已设置 output_path 且用户确认了目标路径，则将文件移动或复制至该位置
4. 通知用户：
   • 任务已完成
   • 输出文件保存位置
   • 共执行多少次轮询、耗时多久
   • 临时目录路径（供需要时人工检查）
5. 若用户此前确认保留临时目录，则保持原状；否则，主动提供清理选项

通知语言：使用用户当前会话语言。

8. 模板就绪型任务（高频模式）

若某类任务频繁执行（例如 NotebookLM 音频生成、Gemini Deep Research 状态检查），可将轮询逻辑提取为 可复用的脚本模板，存于分类目录层级：

/tmp/notebooklm-audio/
  poll-template.sh        ← 此分类专用的可复用模板
  /260325-1400_task1/    ← 各个任务目录基于该模板生成
  /260326-0915_task2/

各任务目录下的 poll.sh 可直接复制模板，或基于模板生成，从而保证任务目录本身尽可能精简。

9. 总结核查清单

启动轮询任务前，请确认全部满足以下条件：

• 任务适用于轮询（全部适用性条件 ✅）
• 用户已在单条消息中确认全部参数
• 已创建临时目录，且其中 task.json 与 progress.json 内容正确
• 已执行触发命令，并捕获 ID/句柄
• 已编写 poll.sh 并通过语法校验（bash -n）
• 已使用 nohup 启动后台进程
• 已通知用户：任务已启动、如何查询状态、完成时将发生什么