liteparse

有效使用 LiteParse

使用 lit CLI 在本機從文件中提取文字——快速、無需模型。此技能的重點在於低成本使用：每次 lit parse 都會重新執行完整提取，而你每次轉存到對話中的每一行，都會在後續每次互動中付出代價。以下模式來自分析真實的 AI 代理軌跡，其中同一份 PDF 被解析了多達 9 次，而單次圖片讀取耗費了 14 萬字元以上的上下文。別重蹈這些覆轍。

黃金法則：只解析一次到檔案，然後搜尋該檔案

每次呼叫 lit parse 都會重新提取整個文件。在軌跡中，每次搜尋都重新解析是最大的浪費。將文件解析一次到暫存檔，然後對該檔案執行所有搜尋：

# 每個文件只做一次。--no-ocr 適用於原生數位 PDF（幾乎所有報告）——速度快很多。
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，而非 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。

原生數位 vs 掃描文件

• 原生數位 PDF（具有真實文字層——幾乎所有企業/金融/ESG 報告）：務必傳入 --no-ocr。速度快很多，且文字完全相同。保留 OCR 只是浪費時間。
• 掃描 PDF / 圖片：不要使用 --no-ocr。如果數值遺失或數字看起來有誤，請以視覺方式讀取該頁（見下方），而不是信任 OCR。

視覺讀取頁面——最後手段，一次截圖，適中 DPI

截圖是你能放入上下文中最昂貴的東西：在一個軌跡中，單張高 DPI 頁面 PNG 耗費了 約 14 萬字元，而且 AI 代理經常重複渲染同一頁（預設 + 高解析度）。

只有在文字/表格確實無法回答問題時（密集的多欄表格、圖形、圖表）才使用截圖。然後：

• 使用 --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）。