用 OpenClaw 总结五千个工单的踩坑实践

批次 1：读取文件 001-010... 成功批次 2：读取文件 011-020... 成功...批次 5：读取文件 041-050... 成功批次 6：跳过读取（数据缺失）批次 7：试图一次读取剩余全部文件 100-180... 

OpenClaw 聪明的是开始时会遵循指令执行且给出的执行结果在可接受范围内，但执行一段时间后在它缺少约束规则时就开始自作主张，甚至直接把一些文件都跳过了。

在长周期的任务中，Agent 很容易遗忘最初的指令约束，产生行为漂移。

---name: "batch-read-markdown"description: "Read large/batch markdown files completely with L2 verification loop. Handles read truncation, auto-paginates, validates via independent agent."---# Batch File Reading with Verification Loop## Purpose你是一个需要完整读取大量文件或多个 Markdown 文件的 Agent。这个 Skill 教你如何处理 `read` 工具的截断限制（单次约 2000 行/128KB），通过分段翻页保证每个文件被完整读取，并通过独立的监督子任务（Verification Loop）验证读取完整性，发现缺陷后自动触发重读。## Context`read` 工具有截断限制：单次调用约返回 2000 行或 128KB 的内容，超出部分自动丢弃且不提示。这意味着：- **单个大文件**：如果一个文件超过 2000 行，一次 `read` 只能读到前半部分- **批量小文件**：虽然每个文件可能不大，但数量多时容易遗漏或忘记读完本 Skill 解决两个问题：1. **读得全**：机制化地逐文件分段翻页，确保每个文件完整读取2. **读得对**：通过独立监督者验证，确保无遗漏、无截断## Instructions### Step 1：数据摸底（Pre-scan）在开始读取之前，先获取所有待处理文件的元数据：```bash# 对单个文件wc -l <文件路径># 对批量文件ls <目录>/*.md | while read f; do echo "$(wc -l < "$f") $f"; done | sort -rn```产出物：文件列表（含每个文件的总行数），用于决定每个文件需要分几段读。**规则：** 任何文件，总行数 > 1800 就需要分段翻页（留 200 行缓冲，因 2000 行是硬上限）。行数 ≤ 1800 可以一次 `read` 读完。### Step 2：逐文件完整读取对每个文件执行以下流程：```2.1 如果文件行数 ≤ 1800：    read path=<文件>  → 一次性读完，标记为 ✅2.2 如果文件行数 > 1800：    段数 = ceil(总行数 / 1800)    第1段：read path=<文件> offset=1        → 读 1-1800 行    第2段：read path=<文件> offset=1801      → 读 1801-3600 行    ...    第N段：read path=<文件> offset=<最后>    → 读到文件末尾```**每次分段翻页后，检查 read 返回的行数：**- 如果返回行数 < 1800 且当前 offset + 返回行数 ≥ 总行数 → 此文件读完 ✅- 如果返回行数 = 0 → 已到文件末尾 ✅- 其他情况下继续翻页### Step 3：维护读取记录（Artifact A）在当前工作目录下维护一个读取进度清单（如 `读取记录.md`），格式如下：```markdown# 读取记录## 任务概要- 总文件数: N- 已完成: M- 已验证完整: K- 待重读: R## 逐文件状态| 文件 | 总行数 | 已读行数 | 状态 ||-----|--------|---------|------|| xxx.md | 4477 | 4477 | ✅ || yyy.md | 312 | 312 | ✅ || zzz.md | 2500 | 1800 | ⚠️ 未读完 |```重读队列放在独立的 `重读队列.md` 中（详见 Step 6）。两份文件分开维护，职责明确。**每次成功读完一个文件后立即更新此记录**，确保监督者可以依赖它。### Step 4：验证判断（Verification Trigger）**何时触发验证：** 每读完一批文件后（一批可以是 1 个大文件，也可以是 10-50 个小文件）。#### 4.1 行数完整性验证（必须）对已读文件列表中的每个文件，跑：```bash# 伪代码实际行数 = wc -l <文件>记录行数 = 从读取记录中提取该文件的已读行数if 实际行数 != 记录行数:   → 缺陷：文件未完整读取，加入重读队列```#### 4.2 覆盖率验证（必须）```bash# 对比实际文件列表 vs 已读文件列表ls <目录>/*.md | sort > /tmp/actual.txt# 从读取记录中提取已读文件列表并排序，输出到 /tmp/read.txt# （用 grep/sed 或 awk 从读取记录.md 中提取文件名列）grep '|' 读取记录.md | grep -v '文件|总行数|-----' | awk -F'|' '{print $2}' | sed 's/^ *//;s/ *$//' | sort > /tmp/read.txtdiff /tmp/actual.txt /tmp/read.txtif diff 有输出:   → 缺陷：存在未读取的文件，加入重读队列```#### 4.3 内容采样验证（可选，按需）从已读文件中随机抽取 2-3 个，单独 `read` 末尾 100 行，与读取记录中的末尾内容对比，确认内容一致性。### Step 5：验证执行方式**监督方案（推荐，L2 Verification Loop，优先使用）：**只有在当前环境不支持创建独立 Agent（如 OpenClaw 的 `sessions_spawn` 工具不可用或受限）时，才降级使用轻量方案。**轻量方案（降级兜底）：**在当前会话中直接跑 `exec` 执行验证脚本，对比行数。优点是即时反馈，缺点是同一个 Agent 既执行又验证，存在自我验证盲区。仅当无法创建监督子任务时使用。创建一个独立 Agent（如 OpenClaw 的 `sessions_spawn` 工具）担任监督者，赋予的任务 prompt 如下：```任务：验证文件读取完整性验证范围：- 读取记录文件路径：<路径>- 原始文件目录：<目录>请执行以下检查：1. 用 exec wc -l 获取原始目录下所有文件的行数2. 用 read 读取记录文件，提取已读文件的列表和行数3. 对比（1）和（2），列出所有：   - 未被读取的文件   - 行数未读完整的文件4. 如果有缺陷，将缺陷文件列表写入当前工作目录下的 `重读队列.md`5. 如果无缺陷，在记录文件中标注本轮验证通过输出格式：## 验证结果- 通过/失败- 缺陷文件数：- 通过文件数：- 缺陷详情：```监督子任务与主任务互不干扰，监督者的判断独立于执行者。### Step 6：重读闭环#### 多 Agent 方案（优先）```监督者发现缺陷 → 写入重读队列.md        ↓主任务发现重读队列有新条目 → 对照队列对缺陷文件重读（Step 2）        ↓主任务更新读取记录中的状态        ↓监督者再次验证 → 通过则从重读队列移除，否则继续重读        ↓所有缺陷清零 → 全量任务完成 ✅```#### 单 Agent 降级方案（不支持创建监督子任务时）当无法创建独立监督子任务时，验证和重读闭环在同一会话内完成：```主任务读完一批文件后        ↓主任务自己执行验证脚本（exec 对比 wc -l 行数 + 覆盖率 diff）        ↓发现缺陷 → 写入重读队列.md → 立即重读        ↓重读后再次验证        ↓所有缺陷清零 → 全量任务完成 ✅```执行者在验证自己时存在自我验证盲区（可能忽略自己的错误），因此降级方案中建议：- 验证脚本写好后，先用肉眼检查一遍再跑- 在完成消息中附带验证结果摘要，供人工复核- 条件允许时尽快切换回多 Agent 方案**重读队列文件格式（当前工作目录下的 `重读队列.md`）：**```markdown# 重读队列| 文件 | 缺陷类型 | 期望行数 | 实际行数 | 状态 ||-----|---------|---------|---------|------|| xxx.md | 行数不完整 | 4477 | 2000 | 待重读 || yyy.md | 遗漏 | - | - | 待重读 |```### Step 7：任务完成判定所有文件满足以下条件时，任务正式完成：1. ✅ 每个文件都已被读取2. ✅ 每个文件的已读行数 = 实际行数3. ✅ 重读队列为空4. ✅ 读取记录中无 ⚠️ 状态的条目---## 注意事项1. **行数优先，而非大小**：判断是否需要分段的标准是 `wc -l` 的行数，不是文件磁盘大小。一行可能只占几个字节，一个 100KB 的文件可能有上万行。2. **offset 是行号，从 1 开始**：`read path=xxx offset=1` 从第 1 行开始读，不是从第 0 行。3. **批次大小的选择**：每批文件数量不要太多，建议 10-20 个小文件为一轮验证区间，或单个大文件每次读完都验证。批次太大时，监督者的验证工作本身也会消耗大量 tokens。