effective-liteparse

高效使用 LiteParse

使用 lit CLI 在本地提取文档文本——它是一款快速、无需模型的解析器。本指南介绍如何节省成本：每次运行 lit parse 都会重新提取全文，而你输出到对话中的每一行，在后续每一轮都会产生费用。以下模式来自对真实 Agent 执行轨迹的分析：同一份 PDF 被解析多达 9 次，单次读取图像就消耗了 140k+ 个字符的上下文。不要重蹈这些覆辙。

黄金法则：只解析一次并保存到文件，然后搜索文件

每次调用 lit parse，都会重新提取整个文档。根据执行轨迹，每次搜索都重新解析是最主要的浪费。每份文档只解析一次，并保存到临时文件，然后在文件中进行所有搜索：

# ONE TIME, per document. --no-ocr for born-digital PDFs (almost all reports) — much faster.
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      # location AND its window, one turn

只有在已知确切行号，并且需要比 -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 搜索已保存的文件，而不是 Read 和 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 链。

原生数字文档与扫描件

• 原生数字 PDF（有真实文本层——几乎所有企业、金融和 ESG 报告都属于此类）：始终传入 --no-ocr。这样速度快得多，而且提取的文本相同。开启 OCR 只会浪费时间。
• 扫描版 PDF / 图像：不要使用 --no-ocr。如果缺少数值或数字看起来不对，应直接查看页面图像（见下文），而不是相信 OCR。

以图像方式查看页面——最后手段，只截一张图，使用适中 DPI

截图是放入上下文中成本最高的内容：在一次执行轨迹中，单张高 DPI 页面 PNG 就占用了 约 140k 个字符，而且 Agent 经常将同一页面渲染两次（默认分辨率 + 高分辨率）。

只有在文本或表格确实无法回答问题时（例如密集的多列表格、图表或数据图），才截图。然后：

• 每次只渲染一页，使用 --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/   # then Read the 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）。