Agent Batch Guard — AI skill for Claude Code

---

name: agent-batch-guard version: 1.1.0 description: AI Agent 大任务防卡死指南。解决 agent 在批量操作中 session transcript 膨胀导致 compaction 超时、agent 卡死的问题，并补充可复用的长任务执行骨架：目标、成功标准、状态落盘、断点续跑、熔断器和脚本模板。

Agent 大任务防卡死指南

AI Agent 执行大任务（批量抓取、翻页采集、历史数据导出）时，极易因 session transcript 膨胀导致卡死。本指南提供从认知层到配置层的完整防护方案。

快速开始

适合什么场景

• 批量抓取、翻页采集、历史导出
• 需要断点续跑的长任务
• 需要把中间状态写盘、避免 transcript 膨胀的任务
• 需要给 agent 一个统一“长任务执行合同”的场景

仓库里现在有什么

文件	作用
SKILL.md	给 agent 直接加载的技能说明
scripts/goal_loop.py	可复用的长任务执行 helper
scripts/cli.py	查看状态文件的最小 CLI
templates/long_task_runner.py	可直接改造成自己任务的模板
references/long-task-execution-model.md	长任务状态模型说明
tests/test_goal_loop.py	回归测试与对抗测试

最小使用示例

from scripts.goal_loop import GoalLoop, LoopConfig

loop = GoalLoop(
    goal="按月导出 2025 全年订单",
    criteria={"done": True},
    config=LoopConfig(
        max_attempts=24,
        check_interval_seconds=30,
        max_consecutive_failures=5,
        state_dir="data/batch_state",
    ),
)

result = loop.run(run_one_batch, resume=True)
print(result)

查看任务状态

python -m scripts.cli status --state-dir data/batch_state

1.1 新增：可复用长任务执行骨架

这一版把 GoSkill 里最有价值的部分整合进来了，但做了更贴近这个 skill 的改写：重点不在“持续尝试”四个字，而在**把长任务的执行状态从对话里拿出来，落到文件和统一状态结构里**。

新增文件：

• scripts/goal_loop.py：长任务执行 helper
• scripts/cli.py：最小状态查看 CLI
• templates/long_task_runner.py：可直接改造的批处理模板
• references/long-task-execution-model.md：统一状态模型说明
• tests/test_goal_loop.py：最小测试集

新增的稳态能力

• 状态文件使用原子写，避免写一半留下坏文件
• 执行过程使用文件锁，避免同一状态目录被两个 runner 同时写坏
• 结果附带 elapsed_seconds / started_at / ended_at
• 可通过 python -m scripts.cli status --state-dir 直接查看状态 JSON

新增的执行合同

长任务启动前，先明确四件事：

1. goal：这次到底要达成什么
2. criteria：怎样才算完成
3. state_file：进度和最近结果写到哪里
4. terminal_status：任务为什么结束

推荐统一状态文件结构：

{
  "goal": "导出 2025 全年订单",
  "criteria_signature": "sha256:...",
  "attempts": 3,
  "consecutive_failures": 0,
  "terminal_status": null,
  "last_res