effective-liteparse

LiteParse を効果的に使う

高速でモデル不要のパーサーである lit CLI を使って、ドキュメントからテキストをローカルで抽出します。このスキルでは、低コストで使う方法を説明します。lit parse は実行するたびに抽出をすべてやり直し、会話に出力した行は、その後のターンごとにコストがかかります。以下のパターンは、同じ PDF が最大 9 回解析され、1 回の画像読み取りでコンテキストが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

その後、低コストなシェルツールでファイルを検索します。検索のために lit parse を再実行するのは絶対に避けてください。

検索の基本 — まずラウンドトリップを最小限にし、その後、結果を小さく保つ

Bash を呼び出すたびに、モデルとのラウンドトリップが発生します（遅延が生じ、コンテキストを読み直します）。解析の次に大きな無駄となるのは、逐次的なループです。grep → 確認 → 再び grep → sed で範囲を読む → また grep。トレースでは、ドキュメントを一度読むだけの場合と比べて、ターン数が 2 倍になっていました。次の 2 つのルールで解決できます。

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. 独立した検索を 1 つのコマンドにまとめる。 質問に複数の異なる事実（例：排出量と収益）が必要な場合、用語ごとに 1 ターン費やさないでください。ラベルを付けてまとめて検索します。

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 を使ってください。
• 無計画に検索を広げないでください。 1 つの質問を 3 回以下の検索コマンドで解決することを目指します。対象を絞った grep を 2 回試しても判明しない場合は、search.py（下記）に切り替えます。キーワードを変えながら 1 ターンずつ何度も検索するのは避けてください。
• Read ツールや Grep ツールよりも、保存済みファイルに対する Bash の grep／sed を優先してください。ラウンドトリップが少なく、出力サイズを正確に制御できます。

キーワードが不確かな場合のランキング検索（同梱ヘルパー）

対象を絞った grep を 2 回試しても答えが判明しない場合は、grep をやめてください。キーワードの候補を 1 ターンずつ試すのではなく、同梱の BM25 ランカーを一度実行し、関連性が最も高い行の範囲を 1 つのコマンドで表示します。

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

-k は一致件数、-e は一致箇所の前後に表示するコンテキスト行数です（範囲がそのまま出力されるため、後続の sed ターンは不要です）。行番号付きで、ランキングされた範囲が返されます。単一のキーワードではなく、複数の類義語を含む、自然な言葉での詳しい検索クエリを使ってください。これにより、推測に基づく grep を長々と繰り返す必要がなくなります。

デジタル生成 PDF とスキャン PDF の違い

• デジタル生成 PDF（実際のテキストレイヤーがあるもの。企業、金融、ESG のレポートのほとんどが該当します）：常に --no-ocr を渡してください。はるかに高速で、テキストも同一です。OCR を有効にしたままにすると時間が無駄になります。
• スキャン PDF／画像：--no-ocr を外してください。値が見つからない場合や数字が間違っているように見える場合は、OCR を信頼するのではなく、ページを視覚的に確認してください（下記参照）。

ページを視覚的に読む — 最終手段として、スクリーンショット 1 枚、適度な DPI で

スクリーンショットは、コンテキストに含められるものの中で最もコストがかかります。あるトレースでは、DPI の高いページ PNG 1 枚で約 14 万文字が消費され、エージェントが同じページを 2 回（デフォルトと高解像度で）レンダリングすることもよくありました。

テキストや表だけでは本当に答えられない場合（密度の高い複数列の表、図、グラフ）に限り、スクリーンショットを撮ります。その場合は、次のようにします。

• --target-pages "N" を使って、一度に1 ページだけレンダリングします（注意：--pages ではなく --target-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に自動変換されます）。