← Back to Communication
Communication by @fogyoy

let-me-know

Notify the user before starting any long-running task and keep them

0
Source Code

Let Me Know

Purpose

Ensure the user is informed before long-running tasks start, gets periodic updates on a configurable interval (default 5 minutes), and receives an immediate completion/failure notice. Heartbeat messages must reflect real-time progress, not a repeated template.

Trigger

Use this skill whenever a task will take noticeable time (>2–3 minutes) or involves long-running installs/builds/tests.

Workflow (required)

  1. Pre-flight message (before starting):
  • Send a short message: what will run, estimated time, and explicitly state:
    • “完成或失败都会立刻通知你；期间我每 X 分钟 发一次进度心跳，您也可以修改心跳时间间隔。”
  1. Start a heartbeat (configurable interval, with pre-check)
  • Default interval = 5 minutes (everyMs=300000). If the user specifies a different interval, use it.
  • Schedule repeating updates while the task runs.
  • Before each heartbeat message, read the latest progress (state file/logs) and send current progress (no repeated template):
    • Running → include latest step, progress metrics, and next step.
    • Failed → send failure notice and stop the heartbeat.
  • 优先推荐：同一条 agentTurn 内“原地心跳”（不创建额外 cron）：
    • 在长任务执行期间，用循环 sleep <interval> → 读取进度 → message send 发一次动态进度。
    • 任务结束自然停止，不会遗留心跳任务。
  • 只有在必须脱离当前执行流时才用 cron 心跳，并且必须满足：
    • 通过 cron add 创建心跳 job 时，payload.deliver=false（避免“收到/启动”之类消息被转发给用户）。
    • 心跳 job 内部用 message send 主动推送进度。
    • 创建后把返回的 heartbeatJobId 写入状态文件（例如 <task>-state.json），供清理使用。
    • 创建前先 cron list，若已存在同名心跳 job，先 remove（去重）。
  • Content template (dynamic):
    • Running: 进度：<最新步骤/阶段>（<关键指标>）。下一步：<next>。完成/失败会立刻通知你。
    • Failed: 失败：<task> 发生错误（简述原因）。已停止心跳提醒。
  1. Run the task
  • Execute the long-running command(s).
  1. Completion message (immediately after finish)
  • Send result summary (success/failure + key output).
  1. Stop heartbeat（必须做到）
  • 如果你使用了“原地心跳”（推荐）：任务结束即可，不会遗留任何 cron。
  • 如果你使用了 cron 心跳：
    • 在任务成功/失败的 finally 里调用 cron remove <heartbeatJobId>。
    • 若 remove 失败（gateway timeout）：至少重试 2 次（指数退避 2s/8s）。
    • 仍失败：创建一个 2 分钟后的一次性 cleanup cron 再次 remove（避免永远刷屏）。

Heartbeat interval (user-configurable)

  • Default: 5 minutes.
  • If the user specifies an interval (e.g., “每 2 分钟/10 分钟”), use that value.
  • If the user changes the interval mid-task, update the cron schedule and acknowledge in the next heartbeat.

Message Delivery

Prefer outbound normal chat messages:

  • Use message send with the correct target format.
  • Example for Discord DM: user:<id>.

Safety

  • Do not start long tasks without the pre-flight message.
  • If blocked/failed, notify immediately, set state=failed, and stop the heartbeat.
  • If cron removal fails due to gateway timeout, retry removal; if still stuck, use gateway restart (requires commands.restart: true) and retry.

Example (Discord DM)

Start message:

  • 即将开始：安装依赖并运行测试（预计 5–10 分钟）。完成或失败都会立刻通知你；期间我每 5 分钟发一次进度心跳，你也可以修改心跳时间间隔。

Heartbeat (every 5 min, example):

  • 进度：已完成安装依赖（1/2），测试运行中（已用时 4 分钟）。下一步：汇总测试结果。完成/失败会立刻通知你。

Completion:

  • 完成：安装成功，测试通过。