一般搜尋與選用的本機索引

	一般（預設）	進階：本機索引（選用）
作用	每次呼叫都讀取 .fig，回答 search、find、inspect 和 export。	為選定範圍一次建立搜尋索引，之後 search 從索引作答，並跨來源統一排序。
寫入內容	不建立 workspace 或索引資料庫（export 只寫入你要求的檔案）。	使用者 state 目錄或所選 --storage 下的本機 workspace（SQLite 資料庫）。
適用情境	一次性提問、腳本、CI。	反覆搜尋同一檔案；把專案的多個檔案當作一個語料搜尋（--workspace <dir>）；查找元件、變數、樣式和圖片的精確使用位置。

一般的設計問題不會建立索引。你只需明確選擇啟用一次（「為這個設計建立索引」）；儲存位置由 figlens 決定，不需要設定 SQLite 或其他東西。

# 一般：無狀態，不建立任何東西
figlens search design.fig "checkout button"

# 進階，僅一次：選擇範圍（節點 id，整個檔案用 0:0）；建置在前景執行
figlens index prepare design.fig --scope 0:0

# 索引搜尋；若索引範圍不是整個檔案，加上 --node
figlens search --file design.fig "checkout button" --node 0:0

# 編輯或重新匯出 .fig 後：只重建位元組有變化的範圍
figlens index refresh --file design.fig

# 移動 .fig 後：保留 workspace，再 refresh（使用 prepare 輸出的 workspaceId）
figlens index relocate <sourceId> new/design.fig --id <workspaceId>
figlens index refresh --id <workspaceId>

MCP：index 的 prepare 會回傳一個 job；輪詢 jobs 直到 succeeded，再用回應中的 workspaceId 搜尋。

{"tool": "index", "arguments": {"action": "prepare", "file": "/abs/path/design.fig", "scope": "0:0"}}
{"tool": "jobs", "arguments": {"action": "status", "jobId": "<jobId from the reply>"}}
{"tool": "search", "arguments": {"workspaceId": "<workspaceId from the reply>", "node": "0:0", "query": "checkout button"}}

生命週期：refresh 只重建 .fig 位元組有變化的範圍；rebuild 即使沒有變化也重建；clear_cache 只刪除建置可重新產生的資料，保留註冊表和已發布的索引；reset 刪除此 workspace 的資料庫（絕不刪除 .fig 或匯出），僅在你明確要求時執行。新增來源、擴大範圍、reset 和重新建立，各自都需要單獨的明確請求。

移動了 .fig？index relocate 保留 workspaceId、sourceId 和儲存位置；接著對受影響的範圍執行 refresh。沒有自動探索，也沒有以雜湊為基礎的自動合併，不需要 reset。

一個資料夾裡有多個設計？index add <dir> --workspace DIR 一次登記該目錄下最多 10 個 .fig 檔案，並略過指向目錄之外的連結；回覆列出 added、existing、skipped 和 truncated，重複執行不會新增任何內容，每個檔案仍需各自執行 prepare --scope。在資料夾內移動的檔案會成為新來源，除非使用 relocate。 將回覆中的 nextCursor 作為 --cursor C（MCP 為 cursor）傳入，即可繼續登記接下來的 10 個。分頁的搜尋與 library 游標有效一小時，過期後會回傳 cursor_expired，請重新搜尋。

資料：SQLite 資料庫保存已註冊的本機路徑、所選範圍的圖層名稱與有效文字、實例的元件屬性值、搜尋 postings、精確關係（包含、實例、變體、變數/樣式/圖片綁定、原型目標）及其指向的定義、雜湊、generation 和 job。原始 .fig 留在原處且保持不變；其原始位元組不會存入資料庫。 語意與視覺模型層會加入其嵌入的向量；你啟用的視覺索引即使沒有模型也會加入已索引圖層的 PNG 渲染圖；查詢圖片從不保存。

Pi、OpenCode 和 OMP 透過各自的 opt-in 入口使用同一個索引，workspace 可跨重啟和宿主重複使用。尚未實作：檔案事件（watch 以輪詢讀取檔案，且只在有 holder 執行時進行）與推送事件。