agent-batch-guard

# 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 配置中显式告知。

### 核心原则

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

### 判断标准

| 任务规模 | 做法 |
|---------|------|
| < 5 页/轮 | 可以在对话里直接操作 |
| 5-20 页/轮 | 写脚本，一次跑完，结果存文件 |
| 20+ 页/轮 | 写脚本 + 分批（按月/按平台/按类别），每批存档 |

### 黄金规则

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

### 建议写入 AGENTS.md 的模板

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

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

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

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

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