---
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.txt
diff /tmp/actual.txt /tmp/read.txt
if 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。