眼鏡款式類目檢索
把雜亂的來源目錄（Excel / CSV / PDF 畫冊）標準化成統一類目索引，再用自然語言或結構化條件檢索。
何時使用
- 需要從集團款式目錄、SKU 總表、產品畫冊中找款 / 篩款 / 統計類目
- 需要把不同部門、不同格式的目錄表統一口徑後合併
- 需要回答「有哪些板材中性款」「50–54mm 鏡圈有幾款」「這系列的價格帶分佈」這類問題
核心流程
Step 1 — 定位來源資料
先找來源檔案，不要憑空作業。用 Glob 在工作區與使用者目錄搜尋
*.xlsx、*.xls、*.csv，以及檔名含「款式 / 目錄 / catalog / SKU / collection / 產品」的檔案；
同時確認是否另有 PDF 或圖片型畫冊。
找不到就停下來問使用者路徑，不要用假資料示範。
Step 2 — 建立索引
python scripts/build_index.py --input <來源檔1> <來源檔2> --out ./catalog_index
python scripts/build_index.py --dir ./source --out ./catalog_index --name "2026SS"
支援 .csv .tsv .xlsx .xlsm .json。.xls 舊格式請先另存為 .xlsx 或 .csv。
只依賴 Python 標準庫；環境若有 openpyxl 會自動優先使用。
跑完必須逐欄檢查覆蓋率，不要只看「有沒有報錯」：
- 覆蓋率 0% 的欄位 → 來源欄位名沒被認出來，去 fields_report.json 看 unmapped_columns
- 覆蓋率 100% 反而要起疑 —— 來源根本沒這欄卻全滿，代表別名子字串誤命中
（實際案例：ti 命中 fit 使全部款式判成鈦金屬、uni 命中 Universal fit
使全部判成 unisex）。抽 2–3 筆人工核對，別只看百分比。
修正一律改 scripts/taxonomy.py 的 FIELD_ALIASES / VALUE_SYNONYMS，
重跑 build_index.py 即生效，不需改任何腳本，也不要手動改來源 CSV 欄位名。
加別名前先讀 references/taxonomy.md 第 3 節的比對規則。
Step 3 — 檢索
python scripts/search.py --index ./catalog_index/index.json --query "適合方臉、偏商務、輕量的光學架"
python scripts/search.py --index ./catalog_index/index.json --filter '{"material_group":["acetate"],"lens_width":[50,54],"status":["in_stock"]}'
python scripts/search.py --index ./catalog_index/index.json --facets material_group,price_band
python scripts/search.py --index ./catalog_index/index.json --query "板材 太陽鏡" --format html --out result.html
先用 --explain 確認語意被正確解析（哪些變成硬性篩選、哪些只是加分），再出正式結果。
若零命中：用 --facets <欄位> 看索引裡實際有哪些值，通常是標準值和來源寫法對不上。
Step 4 — 呈現
結果優先輸出可篩選的 HTML（--format html），再用 present_files 開預覽；
貼進郵件或報告時用 --format md。
回覆時要附一句判斷（命中幾筆、主要落在哪個材質／價格帶），不要只丟表格。
PDF / 圖片型畫冊
本 skill 不內嵌 OCR，由模型自己看圖辨識。先確認 PDF 有沒有文字層
（用 pdfplumber 抽一次，全空就是純點陣圖）。
- 有文字層：直接用 Read 工具讀 PDF。
- 純點陣圖（設計稿轉出的畫冊常見，檔案可達數百 MB）：不要直接 Read，會失敗。
用pypdfium2渲染成頁面圖再讀：
python
import pypdfium2 as pdfium
doc = pdfium.PdfDocument("catalog.pdf")
for i in range(len(doc)):
pg = doc[i]; w, h = pg.get_size()
pg.render(scale=1600/max(w,h)).to_pil().save(f"pages/page{i+1:02d}.png")
先讀整頁取款名／類型／配色，再放大裁切局部核對文字與鏡框本體。
框形與結構必須逐款看鏡框本體再判，不要憑整頁縮圖猜。
把每款轉成一條 JSON，欄位名用 references/taxonomy.md 的標準欄位，
存成 pdf_extracted.json（[{"sku":"...","name_cn":"...","material_raw":"板材",...}]），
再跑 build_index.py --input pdf_extracted.json。
辨識不出來的欄位留空，不要編造；來源自相矛盾時照抄並標為待確認。
資源
scripts/taxonomy.py— 標準類目詞表與中英別名對照（擴充詞表只改這裡）scripts/build_index.py— 來源檔 → 統一索引scripts/search.py— 自然語言 / 條件檢索references/taxonomy.md— 類目定義、判斷規則（板材 vs 注塑、Wayfarer vs Boston 等）、面型配適表、PDF 萃取方法
需要確認某個類目怎麼判、或某個詞為何沒命中時，讀 references/taxonomy.md。
