liteparse

LiteParse

使用 lit CLI 在本地提取文档文本——这是一款快速、无需模型的解析器。本技能的重点是节省成本：每次运行 lit parse 都会重新完整提取文档，而你在对话中输出的每一行内容，后续每轮都会再次计费。以下模式来自对真实 Agent 轨迹的分析：同一份 PDF 最多被解析了 9 次，单次读取图片就消耗了 14 万多个字符的上下文。不要重蹈这些覆辙。

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

每次调用 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 仍无法确定答案，就停止 greping——不要每轮都尝试不同的关键词变体。运行内置的 BM25 排序器一次，通过一条命令找出最相关的行及其上下文：

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 就消耗了约 14 万个字符，而 Agent 往往会把同一页面渲染两次（默认分辨率 + 高分辨率）。

只有在文本/表格确实无法回答问题时（例如密集的多栏表格、图表）才截图。此时：

• 每次只渲染一页，使用 --target-pages "N"（注意：是 --target-pages，不是 --pages）。
• 使用适中 DPI（约 150–200）。不要一开始就使用 300 以上的 DPI；除非文本确实无法辨认，否则不要以更高 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）。