分析 Figma 匯出檔案 (analyze-fig)
分析 Figma 匯出檔案 (.fig)，無需呼叫 Figma API：讀取檔案中的節點樹、文字與點陣圖，而作者＊留言＊（.fig 檔案中不存在）則透過 MCP 連結個別取得。結果為 spcfctn/ui/ 目錄下的 Markdown 檔案，可供後續使用，無需重複讀取 Figma。
何時不應執行
有關已解析設計稿的問題（例如「篩選器的留言說什麼…」、「畫面上有哪些欄位…」）應直接閱讀 spcfctn/ui/*.md 來解答，而非執行此技能。只有在匯入新的或更新的 .fig 檔案，或當 Markdown 檔案中沒有答案時（參閱 spcfctn-code.md），才需要執行解析。
目錄（僅草稿目錄 draft，不納入 Git 版本控制）
spcfctn/ui/draft/— 輸入的.fig檔案（及其他草稿）。由使用者放置。spcfctn/ui/draft/<名稱>/— 解壓結果：message.json（所有節點）、meta.json、images/、screens.json和screens.txt，以及收集到的留言 (comments.json)。由.fig檔案還原，不納入 Git。沒有獨立的raw/或data/（參閱modeling.md）。spcfctn/ui/*.md— 分析結果；僅此部分保留在 Git 中。
<名稱> 為檔案名稱不含副檔名，並轉為小寫連字號格式（例如 internal-interfaces）。
步驟 0 — 準備
- 找出專案的
spcfctn/。如果不存在，請要求使用者建立（參閱spcfctn-code.md）。ui/及其子目錄draft/請自行建立。 - 檢查
spcfctn/ui/.gitignore（成品儲存庫）：應包含draft（參閱modeling.md）；如果缺少，請透過gitignore.org補上。 - Figma 檔案：使用者需指定檔案名稱；若未指定，請列出
spcfctn/ui/draft/*.fig並詢問。 - 閱讀專案的
CLAUDE.md（語言慣例、規則）及既有的spcfctn/ui/*.md：解析結果應延續其結構與術語，而非從零開始。 - 需要在
PATH中安裝python3和zstd。
步驟 1 — 解壓與解碼
python3 ~/.claude/skills/analyze-fig/scripts/fig.py spcfctn/ui/draft/X.fig spcfctn/ui/draft/<名稱>
此指令會顯示格式版本、節點數量、blob 數量與圖片數量。此腳本已驗證可在格式版本 106 上運作；若遇到其他版本或錯誤，請勿猜測格式或使用其他解碼器，直接告知使用者。meta.json 中包含 exported_at：匯出時間將在步驟 5 中使用。message.json 檔案很大，請勿直接列印。
步驟 2 — 解析為章節與畫面
python3 ~/.claude/skills/analyze-fig/scripts/screens.py spcfctn/ui/draft/<名稱>
此指令會輸出頁面清單、章節（頂層框）與畫面（其子層），並顯示文字與點陣圖的數量。精髓在 screens.txt：針對每個畫面，文字圖層會從上到下、從左到右分組排列（便於讀取篩選器、欄位標題與按鈕），並附上點陣圖的連結。
- 將數量與預期值（例如舊的 Markdown 檔案）進行比對；若有差異應停止。
- 文字圖層無法看到無文字的元件（純圖示）與點陣圖內容。對於
images/中的每個點陣圖，請開啟檔案（Read）並描述文字圖層中缺少的內容；並標註這是從圖片讀取到的。節點樹與文字是主要依據，圖片則為輔助。 - 元件實例 (
INSTANCE) 可能包含未被腳本偵測到的覆寫文字；screens.txt會對此提出警告。
步驟 3 — 寫入 spcfctn/ui/*.md
- 每個章節一個 Markdown 檔案（若僅有一個章節則一個檔案即可）。若檔案已存在，請完整讀取並更新，而非覆寫：即使 Markdown 檔案僅由代理人管理，也不能遺失先前的釐清內容。
- 語言風格遵循專案的
CLAUDE.md。 - 結構（範例請參閱
job/vale/kylada中的spcfctn/ui/internal-dashboard.md）：開頭應包含來源與驗證資訊（讀取內容、匯出日期、畫面數量與文字數量）、版型閱讀規則、UI 標籤與內部術語的對應、按順序排列的畫面（篩選器按版型順序、清單按鈕、欄位、列操作）、待解決問題。 - 所有屬於你的解讀，而非版型或留言原文的內容，請標示為 inferred。
- 專案的版型閱讀規則（例如「欄位標題下方的
Select是排序控制」）請從CLAUDE.md取得並套用，而非自行臆測。
步驟 4 — 透過 MCP 連結取得留言
.fig 檔案中不含留言（已驗證）：留言只留在 Figma 伺服器上。
- 需要 Figma 中該檔案的連結（可有
node-id或無）。若無，請向使用者索取。 - 僅使用專案中已連接的 Figma MCP 伺服器所提供的
comments工具（名稱請從已連接的伺服器清單中取得）；參數file為該連結。若無此工具，請告知使用者。官方figma-cs不提供留言，請勿直接以 token 呼叫 REST API，也不要碰.env。 - 不帶
node_id的呼叫會取得該檔案所有分支的所有留言（編號、日期、狀態、節點@id、內容、回覆）。除非必要，否則不要設定refresh。留言端點與檔案讀取的計費方式不同，即使讀取回傳429，留言仍可正常運作。 - 將留言對應到畫面的規則：
- 若
@id與screens.json中的畫面 id 相符，則畫面已確定； - 若
@id為章節或頁面的 id，則需根據幾何位置決定畫面：需要留言的node_id和node_offset。將字串關鍵字 節點 X Y（例如#144 979:3 500 5471）輸入:python3 ~/.claude/skills/analyze-fig/scripts/place.py spcfctn/ui/draft/<名稱> < 字串輸出：關鍵字、章節、畫面；若座標不在畫面上，則顯示原因與最近的畫面。 - 檢查輸出：
comments工具可能不輸出node_offset（技能建立時即有此情況）。此時，屬於章節或頁面的留言無法被正確對應：請勿根據內容猜測畫面，而應將其歸類為章層級，標註＊畫面未確定＊，並告知使用者需要留言的偏移量才能正確對應。
- 若
- 回覆 (
↳) 屬於父留言的討論串。
步驟 5 — 驗證留言與檔案內容是否一致
對於每個已確定畫面的留言（以及章節層級的留言群組），請檢查：
- 留言中提到的欄位、列、按鈕、數值是否存在於該畫面的文字圖層中（例如「整合服務數量」對應「服務」欄位；引用需有引號；列舉數值）。
- 留言是否與版型衝突（欄位數量、順序、元件類型、「有篩選器」/「無」）。
- 日期：若留言日期晚於
meta.json中的exported_at，則表示匯出已過時。請要求使用者在spcfctn/ui/draft/中放置新的匯出檔案。 - 留言的節點不在檔案中（已刪除或重新命名）— 此為孤立留言。
- 留言無對應畫面且內容無法辨識。
將所有差異整理成一個小型表格（編號 #N、畫面、差異說明），並詢問使用者哪個是正確的：請勿擅自修正或自行決定版型與留言何者為準。在使用者回應之前，請在 Markdown 中標示為 conflict。
步驟 6 — 撰寫摘要
- 在 Markdown 中新增一個章節，包含作者留言摘要（說明這些留言的目的）以及按畫面排列的所有留言（附編號
#N）。若留言釐清了之前標註為 inferred 的內容，請修正記錄並引用該留言。 - 更新開頭的「Verification」部分：顯示已讀取的內容（
.fig檔案、版本、匯出日期、文字、點陣圖、留言、取得留言的日期）以及未涵蓋的內容。 - 待解決問題以獨立清單列出；使用者的回應請移至「已解決」。
- 未經要求，請勿提交任何內容。請以口頭（繁體中文）摘要：章節數量、畫面數量、留言數量、差異數量以及需要釐清的具體事項。
不應做的事項
- 請勿以 token 呼叫 Figma REST API，也請勿讀取或編輯
.env。 - 請勿讀取第三方程式碼（如 kiwi 解碼器等）：格式已在
scripts/中實作。 - 請勿將
.fig及其解析結果（draft/下的所有內容）納入 Git。 - 當有文字圖層可用時，請勿根據文字內容猜測留言所屬的畫面，也勿根據圖片猜測版型內容。