liteparse

高效使用 LiteParse

使用 lit CLI 在本地从文档中提取文本——一个快速、无模型的解析器。本技能的核心是低成本使用：每次 lit parse 都会重新完整提取，而你每次将内容放入对话中，后续每次交互都会为此付费。以下模式来自对真实代理轨迹的分析，其中同一份 PDF 被解析了多达 9 次，单次图片读取消耗了 14 万+ 字符的上下文。不要重复这些错误。

黄金法则：解析一次到文件，然后搜索该文件

每次调用 lit parse 都会重新提取整个文档。按搜索重新解析是轨迹中看到的 #1 浪费。每个文档只解析一次到临时文件，然后针对该文件执行所有搜索：

# 每个文档只执行一次。对于原生数字 PDF（几乎所有报告），使用 --no-ocr —— 快得多。
lit parse "/abs/path/doc.pdf" --format text --no-ocr -o /tmp/doc.txt && wc -l /tmp/doc.txt

然后使用廉价的 shell 工具搜索该文件——永远不要为了再次搜索而重新运行 lit parse。

搜索纪律——最小化往返次数，然后保持结果精简

每次 Bash 调用都是一次完整的模型往返（延迟 + 重新读取上下文）。解析之后最大的浪费是串行循环：grep → 查看 → 再次 grep → 用 sed 读取窗口 → 再次 grep。在轨迹中，这比直接读取文档多了一倍的轮次。两条规则可以解决这个问题：

1. 在同一个命令中获取上下文——不要先 grep 再 sed。 使用 grep -C，这样匹配行周围的上下文会一起返回。这消除了常见情况下后续的 sed 轮次：

grep -n -i -C4 "total assets" /tmp/doc.txt | head -40      # 位置及其窗口，一次完成

仅当你已经知道确切行号并且需要比 -C 提供的更宽的窗口时，才回退到 sed -n 'A,Bp'。

2. 将独立的查找批量放入一个命令中。 当一个问题需要几个不同的事实（例如排放量和收入）时，不要每个术语花费一轮。使用标签一起探测：

for q in "carbon intensity" "scope 1" "total revenue"; do \
  echo "=== $q ==="; grep -n -i -C3 "$q" /tmp/doc.txt | head -25; done

然后保持结果精简：

• 始终使用 head 限制输出，并使用 -n 显示行号。
• 不要盲目发散。 目标是在 ≤3 次搜索命令内解决问题。如果两次有针对性的 grep 没有定位到，切换到 search.py（见下文）——不要一次一轮地继续尝试关键词变体。
• 优先使用 Bash grep/sed 处理保存的文件，而不是使用读取和 grep 工具——往返次数更少，并且你可以精确控制输出大小。

关键词不确定时的排序搜索（附带的助手）

当两次有针对性的 grep 没有定位到答案时，停止 grep——不要一次一轮地迭代关键词变体。一次性运行附带的 BM25 排序器，在单个命令中展示最相关的行窗口：

./.claude/skills/effective-liteparse/scripts/search.py /tmp/doc.txt -q "materiality assessment priority topics" -k 8 -e 5

-k = 匹配数量，-e = 每个匹配周围的上下文行数（这样窗口会内联返回——无需后续的 sed 轮次）。它返回带有行号的排序窗口。使用丰富的自然语言查询（一个字符串中包含多个同义词），而不是单个关键词。这取代了一长串推测性的 grep。

原生数字 vs 扫描文档

• 原生数字 PDF（具有真实文本层——几乎所有企业/金融/ESG 报告）：始终传递 --no-ocr。这样快得多，且文本相同。保留 OCR 会浪费时间。
• 扫描 PDF / 图片：去掉 --no-ocr。如果值缺失或数字看起来错误，请视觉读取页面（见下文），而不是信任 OCR。

视觉读取页面——最后手段，一张截图，适中的 DPI

截图是你能放入上下文的最昂贵的东西：一张高 DPI 的页面 PNG 在一次轨迹中消耗了 ~14 万字符，而且代理经常渲染同一页面两次（默认 + 高分辨率）。

仅当文本/表格确实无法回答问题（密集的多列表格、图形、图表）时才截图。然后：

• 使用 --target-pages "N" 一次渲染一页（注意：是 --target-pages，不是 --pages）。
• 使用适中的 DPI（约 150–200）。不要从 300+ 开始；除非文本确实难以辨认，否则不要以更高 DPI 重新渲染同一页面。

lit screenshot "/abs/path/doc.pdf" --target-pages "13" --dpi 150 -o /tmp/shots/   # 然后读取 PNG

关于同一文档的多个问题

解析一次到文件已经涵盖了这一点：保留 /tmp/doc.txt 并在每个问题中重复使用，而不是重新解析。

不要在开场白上浪费轮次

跳过 lit --version、ls -la 和 lit … --help，除非确实出了问题。直接开始解析。你需要的关键标志：

--format text|json · --no-ocr · --target-pages "1-5,10" · --dpi <n>（默认 150）·
--ocr-language <iso>。仅当你需要边界框/布局时才使用 --format json——它大得多；仍然搜索它，不要整体加载。

设置

PDF 开箱即用。如果缺少 lit：npm i -g @llamaindex/liteparse。Office 文档需要 LibreOffice；图片需要 ImageMagick（两者都会自动转换为 PDF）。