Agent 大任务防卡死指南

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

这个 Skill 解决什么问题

AI Agent（如 OpenClaw agent）在执行大量重复操作时，每一轮工具调用的输入和输出都会堆积在 session transcript 中。当 transcript 膨胀到数 MB 级别后：

1. Compaction 超时 — 压缩旧对话的过程本身超过时间限制
2. Agent 彻底卡死 — 无法处理新消息，也无法自行恢复
3. 用户无感知 — agent 停止响应，但没有任何报错通知

真实案例：agent 被要求翻阅手机 App 抓取 1 年的订单数据，在对话中逐页执行 scroll → uiautomator dump → parse → repeat，200+ 轮后 transcript 膨胀到 9.6MB，compaction 两次超时，agent 静默卡死数小时。

第一层：Agent 行为规范（写入 AGENTS.md）

这是最重要的一层。Agent 不具备对自身运行环境的 meta 认知——它不知道 transcript 有容量上限，需要在 workspace 配置中显式告知。

核心原则

数据写文件，不要堆在对话里。

判断标准

黄金规则

1. 超过 5 页的翻页操作 → 写脚本，不在对话里循环
2. 数据写文件（如 data/scrape/），不堆在 transcript 里
3. 分批 + 断点续传（每批存档，支持中断恢复）
4. 对话里只做三件事：写脚本 → 检查进度 → 汇总回复
5. 超过 10 轮重复操作 = 立刻停下来写脚本
6. 熔断保护：连续失败 5 次暂停，不要无脑重试

建议写入 AGENTS.md 的模板

## 大任务处理规范（防止 session 卡死）

**核心原则：数据写文件，不要堆在对话里。**

当任务涉及大量重复操作时（批量处理、翻阅多页数据、爬取历史记录），
**禁止**在对话中逐页循环。

详细批处理模式请读取：
~/.openclaw/skills/agent-batch-guard/SKILL.md

### 快速规则
1. 超过 5 页的翻页操作 → 写脚本，不在对话里循环
2. 数据写文件，不堆在 transcript 里
3. 分批 + 断点续传（每批存档，支持中断恢复）
4. 对话里只做三件事：写脚本 → 检查进度 → 汇总回复
5. 超过 10 轮重复操作 = 立刻停下来写脚本
6. 熔断保护：连续失败 5 次暂停，不要无脑重试

第二层：正确的大任务执行模式

模式一：脚本化批处理（推荐）

把循环操作封装成独立脚本，agent 只负责写脚本、运行脚本、读取结果。

错误做法（agent 在对话中循环）：

对话轮 1: scroll 到第 1 页 → 截图 → 解析
对话轮 2: scroll 到第 2 页 → 截图 → 解析
...
对话轮 200: scroll 到第 200 页 → 截图 → 解析
→ transcript 9.6MB → compaction 超时 → 卡死

正确做法（agent 写脚本后一次执行）：

对话轮 1: 写 /tmp/scrape_orders.py（脚本内部处理循环和翻页）
对话轮 2: python3 /tmp/scrape_orders.py → 结果存到 data/scrape/orders.json
对话轮 3: 读取 orders.json → 汇总回复
→ transcript 3 轮 → 安全

模式二：分批执行 + 文件存档

大任务拆成小批次，每批结果立即写入独立文件：

data/scrape/
├── orders_taobao_2025-01.json
├── orders_taobao_2025-02.json
├── ...
├── orders_taobao_2025-12.json
└── orders_summary.json    ← 最终汇总

脚本示例（Python，ADB 翻页采集）：

#!/usr/bin/env python3
"""批量采集 App 订单 — 分批存档 + 断点续传"""
import json, os, subprocess, time
from pathlib import Path

SERIAL = "DEVICE_SERIAL"
OUTPUT_DIR = Path("data/scrape")
PROGRESS_FILE = OUTPUT_DIR / "progress.json"

def load_progress():
    if PROGRESS_FILE.exists():
        return json.loads(PROGRESS_FILE.read_text())
    return {"last_page": 0, "total_items": 0}

def save_progress(progress):
    PROGRESS_FILE.write_text(json.dumps(progress, ensure_ascii=False, indent=2))

def dump_ui():
    """读取当前屏幕元素"""
    subprocess.run(["adb", "-s", SERIAL, "shell", "uiautomator", "dump", "/sdcard/ui.xml"], check=True)
    subprocess.run(["adb", "-s", SERIAL, "pull", "/sdcard/ui.xml", "/tmp/ui.xml"], check=True)
    return Path("/tmp/ui.xml").read_text()

def scroll_down():
    subprocess.run(["adb", "-s", SERIAL, "shell", "input", "swipe", "500", "1500", "500", "500", "300"])
    time.sleep(1.5)  # 等待加载