heartbeat

Heartbeat Orchestrator

Heartbeat 技能充当 Agentic OS 的后台处理器。它读取 .agent/state/tasks.json 队列，识别待处理任务，将任务分派给相应技能，并在完成后更新任务状态。

工作原理

使用此技能 scripts/ 目录中的 heartbeat.py 脚本来管理队列：

1. 发现范围队列：如果不确定要处理什么，先运行 heartbeat.py scopes。它会列出 _<batch>_extension.<queue> 路径下所有可弹出的队列，并显示就绪、进行中和已完成的数量。
2. 弹出任务：运行 heartbeat.py pop（旧版模式），或运行 heartbeat.py pop --scope _round3_extension.ag_implementation_queue（范围模式）来获取下一个任务。如果 tasks.json 中存在 _*_extension 队列，不带 --scope 执行 pop 将拒绝操作并返回退出码 11——请传入匹配的 --scope。
3. 执行：阅读任务详情，并使用相应技能（例如 osint、deep-research）完成任务。
4. 容错与重试：如果任务意外失败，自主 Agent MUST 在正式报告失败前，尝试重试任务逻辑最多 两 次。
5. 完成/失败：运行 heartbeat.py complete <task_id> --scope <path> --outcome '{"result": "..."}'（范围模式），或运行 heartbeat.py complete <task_id> --outcome '...'（旧版模式）。失败记录会写入 .agent/state/errors.json。

路径因 Agent 而异：

• Gemini / Antigravity：python3 ~/.gemini/skills/heartbeat/scripts/heartbeat.py …
• Claude：python3 ~/.claude/skills/heartbeat/scripts/heartbeat.py …

（两个路径都会通过符号链接指向 ~/github/claude-skills 中同一个规范脚本，因此行为一致。）

范围队列（在 1.2.0 中添加）

当 tasks.json 包含类似 _round3_extension 的批次元数据块时，将其下每个由字典组成的列表（且每个条目都包含 task_id 字段）视为范围队列。脚本会根据项目 AGENTS.md § Agentic OS Operating Discipline 强制执行以下三条规则：

• 遵循明确指定的队列：如果存在范围队列，不带 --scope 执行 pop 将被拒绝（退出码 11）。范围队列处于活动状态时，不得处理更广泛的 pending 列表。
• 跳过受阻条目：如果队列条目的 gh_issue 或 task_id 出现在任何同级 blocked_on_* 数组中，则会自动跳过。脚本会告知你跳过了哪些条目及原因。
• 队列耗尽时停止：当范围队列中没有剩余的 ready 条目时，脚本以退出码 10 退出，并提醒你填写证据报告后停止，不要遍历 pending。

示例：

heartbeat.py scopes
# _round3_extension.ag_implementation_queue  (3 ready / 0 in_progress / 0 completed / 3 total)

heartbeat.py pop --scope _round3_extension.ag_implementation_queue
# pops the first ready item, marks status=in_progress in place

heartbeat.py complete round3-edit-item-33-southern-qualifier \
  --scope _round3_extension.ag_implementation_queue \
  --outcome '{"pr": 502, "merged": true}'

处理过期的 in_progress 条目（在 1.2.0 中添加）

如果 tasks.json 中存在来自先前崩溃或交接会话的 in_progress 条目，pop 将拒绝操作并返回退出码 12，同时打印过期条目。可通过以下任一方式解决：

heartbeat.py clear-stale          # move them all back to pending
heartbeat.py pop --accept-stale --scope <path>   # adopt and proceed

这可以防止新 Agent 在不知情的情况下继承其他会话尚未完成的工作——这是已记录的故障模式。

退出码

代码	含义
0	正常弹出任务 / 没有待处理任务（旧版向后兼容）
10	范围队列已耗尽——填写证据报告并停止
11	存在范围队列，但未传入 --scope——请选择一个
12	存在过期的 in_progress 条目——清除条目或使用 --accept-stale
13	调用方要求直接弹出受阻条目（保留）
14	--scope 路径未解析为由字典组成的列表

包装器（heartbeat-runner shell、AG 启动脚本）应根据这些退出码进行分支处理：退出码 10 表示停止；退出码 11/12 表示操作人员需要作出决定；退出码 14 表示配置错误。

任务格式

tasks.json 的旧版结构（仍受支持）：

{
  "pending": [
    {
      "id": "task-123",
      "priority": "high",
      "description": "Deep research the current state of local LLM orchestration.",
      "assigned_skill": "deep-research",
      "project_id": "claude-skills",
      "agent_id": "antigravity",
      "user_id": "matthias",
      "created_at": "2026-04-25T12:00:00Z",
      "completed_at": null
    }
  ],
  "in_progress": [],
  "completed": [],
  "failed": []
}

范围队列结构（与旧版字段并存）：

{
  "pending": [...],
  "in_progress": [],
  "completed": [],
  "failed": [],
  "_round3_extension": {
    "ag_implementation_queue": [
      {
        "order": 1,
        "task_id": "round3-edit-item-33-southern-qualifier",
        "gh_issue": 496,
        "estimate": "frontmatter only on 2 providers; ~10 min",
        "risk": "minimal"
      }
    ],
    "blocked_on_client": [
      { "items": "Spanish PDFs", "issues": [390, 391], "blocker": "translator pending" }
    ]
  }
}

脚本会将 _*_extension 下所有条目均包含 task_id 的内容视为可弹出的队列。以 blocked_on_ 开头的键是筛选输入项，而不是队列。ag_pushed_branches 等元数据列表（其中的条目不包含 task_id）会被 scopes 发现流程忽略。

执行

调用时（或在 Agent 启动时自动运行时），Heartbeat 应一次处理一个任务，以保持稳定并控制上下文长度，除非明确要求清空队列。在使用作用域队列的项目中，Agent 必须传入 --scope，并遵守队列清空后的停止信号——未经授权便处理队列外的工作，是本版本旨在防止的已记录故障模式。

Agentic OS 集成

作为核心 OS 组件，此技能 MUST 将自身执行情况记录到 .agent/state/last-run.json，注明处理的任务及其结果。1.2.0 版的 last-run 架构新增了 scope 字段，以便包装器区分带作用域的调用和旧版调用。