# DECISIONS — 為什麼這個專案是這樣做的

> 這不是教學文件，是決策記錄。每一條包含：背景、決定、理由、代價、驗證。
> 讀者應該能在這裡找到「為什麼不是另一種做法」的答案。

## 一句話總結

**把「可驗證」放在「聰明」前面。** 能算的就不要猜，能擋的就不要提醒，能單一實作的就不要有兩份。

---

## D1. 節點身份是結構 hash，不是名稱、也不是 Figma ID

| | |
|---|---|
| **背景** | 設計師複製畫面後常不改圖層名稱，或改成不一致的名字；同一頁面會有多份複本 |
| **決定** | 身份 = Merkle hash over `(type, ordered children)`；名稱只作為排序先驗與漂移訊號 |
| **理由** | 名稱不可靠是可量測的事實（見證據）；結構 hash 對改名、複製、重排都穩定 |
| **代價** | 結構微調（例如多一個裝飾節點）就會變成新家族；需要另外的「近構」層來補 |
| **證據** | 153 個 390×844 畫面：27 個名稱 vs **68 種結構**；15 個名稱對到多種結構（最糟 1 個名稱涵蓋 9 種）；1 種結構被拆成 2 個名稱 |

**反面做法**：用名稱當 key。結果是「同一結構被拆散」與「不同結構被合併」同時發生，而且不會報錯。

---

## D2. 版面原型用 z-order 遮罩判斷，不是用面積

| | |
|---|---|
| **背景** | 彈窗在檔案裡常是「整頁畫布 + 黑色遮罩 + 面板」，用面積猜會誤判 |
| **決定** | 遮罩 = 與畫布同尺寸（±3px）、**這一層不含文字**、且緊鄰上方還有更小的兄弟節點；三者同時成立才算 overlay |
| **理由** | 這正是設計師的分類方式（「頁面上蓋了一層遮罩」），z-order 是資料裡已有的 `child_index` |
| **代價** | 規則依賴「遮罩是獨立圖層」的慣例；某些檔案把遮罩畫進元件內，需要先拆 wrapper |
| **證據** | 早期用面積規則把首頁 `49:157422` 誤判成彈窗（`content` 390×828 太接近 844）。加上「無文字」與「上方有更小兄弟」後，42 個人工標註 precision/recall = 1.00 |

**學到的**：判斷規則要對齊設計師的工作習慣，不是對齊幾何。

---

## D3. 變體軸不做語意，語意是人類的一層

| | |
|---|---|
| **背景** | 「成功／失敗／處理中」這種詞彙只存在於這個團隊、這個檔案 |
| **決定** | `variants` 只回答「哪個 component 在成員之間出現／消失、文案差在哪」，不推導狀態名 |
| **理由** | 換一份 Figma，詞彙可能完全不同甚至不存在；把語意寫進核心等於把工具綁死在一個專案 |
| **代價** | 使用者要自己解讀輸出；需要額外的標註層（`labels/`）來沉澱語意 |
| **證據** | 同一套流程在「支付結果頁」與「Tap & Pay」上都能抽出軸，不需要預先知道任何詞 |

---

## D4. `unknown` 是合法結果，不是失敗

| | |
|---|---|
| **背景** | 分類器一定會遇到兩邊都不像的畫面 |
| **決定** | 分數低於 floor（預設 0.55）**且** 與第二名的差距 < 0.25 時，回 `unknown`；任何一邊贏得夠清楚就照判 |
| **理由** | 硬分會污染標註；棄權讓人來補，成本更低 |
| **代價** | 需要人工複審佇列；`unknown` 比例高的話代表標註不足 |
| **證據** | 首輪 249 個待分類中，33 個是「分裂」（≤0.33），133 個多數、83 個全票；全票的 LOO 準確率 86%，分裂的不該自動採用 |

---

## D5. 一個核心，三個薄 adapter；parity 用位元比對

| | |
|---|---|
| **背景** | CLI、MCP、DSH plugin 都需要同一批計算 |
| **決定** | 所有計算在 `server/core/`；adapter 只做參數解析與排版；`npm run test:parity` 比對 CLI 的 `--json` 與 core 的結果是否**逐位元相同** |
| **理由** | 兩份實作一定會漂移，而且漂移不會報錯；位元比對是唯一能自動抓到的辦法 |
| **代價** | 每次改 core 都要跑 parity；adapter 不能「順手最佳化」 |
| **證據** | 重構前 CLI 自己算 `sheet/diff/find`，與 MCP 各一份；重構後 parity 三個案例全綠 |

---

## D6. 錯誤是型別化的，不是 `process.exit`

| | |
|---|---|
| **背景** | MCP server 若在 handler 裡 exit，整個服務會死 |
| **決定** | `ToolError{code, message, fix}`；CLI 最外層捕捉後設定 exit code；MCP 轉成 `isError: true` |
| **理由** | 同一份邏輯要被 CLI 與 server 共用，就不能假設「錯誤＝結束進程」 |
| **代價** | 呼叫端要處理五種 code（`invalid_argument` / `not_found` / `missing_input` / `guard_rejected` / `internal`） |
| **證據** | MCP 呼叫不存在的節點回 `{ok:false,error:{code:"tool_error"}}` 且 `isError:true`，server 繼續服務 |

---

## D7. 產物只能進 `.scratch/`；`labels/` 是來源

| | |
|---|---|
| **背景** | 測試會產生大量 HTML、JSONL、DB 快照，很容易散落在 repo |
| **決定** | `--out` 只接受 `.scratch/`，寫到別處直接拒絕；`labels/*.json` 視為原始碼，只有 `apply` 能改 |
| **理由** | 清理只要 `rm -rf .scratch`；資料與程式碼的邊界清楚 |
| **代價** | 想把產物留在 repo 時要手動搬 |
| **證據** | 發布前把 1.9 GB 資料與 labels 移出 repo，程式碼仍只有 7 MB |

---

## D8. MCP 用 stdio JSON-RPC，不引 SDK、不 spawn CLI

| | |
|---|---|
| **背景** | 需要一個標準出口，讓其他 agent 也能用 |
| **決定** | 手寫 JSON-RPC（`initialize` / `tools/list` / `tools/call`），直接 import `core/` |
| **理由** | 專案 stack lock 只允許既有依賴；spawn CLI 每次要多付 1.5 秒並丢失型別 |
| **代價** | 協議細節要自己維護（但目前只用到三個方法） |
| **證據** | 官方 SDK client 1.29.0 可連線、列出工具、正常呼叫與錯誤路徑 |

---

## D9. DSH 內以 plugin 為主體，MCP 當出口

| | |
|---|---|
| **背景** | 目標使用者是 DSH 上的設計師，不是其他 agent |
| **決定** | 斜線命令與未來的原生工具走 plugin；MCP 保持可用但不再投入 |
| **理由** | 命令零 token、可常駐、能走 DSH 原生權限；MCP 每次呼叫都是外部進程 |
| **代價** | plugin 綁 DSH 版本，要打包、要重啟 |
| **證據** | `/rea-figma-review` 直接生成並開啟看板；MCP 版本需要一輪模型 + 1–3 秒 |

---

## D10. 斜線命令不接受參數

| | |
|---|---|
| **背景** | 一度讓 `/rea-figma-review <分類>` 吃參數 |
| **決定** | 命令回歸無參數；分類名稱由 agent 解析後回填 CLI |
| **理由** | DSH 的命令輸入只有非結構化文字：沒有補全、沒有拼字檢查，打錯只會靜默失敗 |
| **代價** | 使用者要多說一句話，由 agent 轉譯 |
| **證據** | 打錯分類時 CLI 回 `did you mean: 首頁`；命令層不再有「打了但沒生效」的可能 |

---

## D11. 產品與資料分離

| | |
|---|---|
| **背景** | 測試用的 1.9 GB 資料與 42 個標註若留在 repo，會干擾新使用者與新 agent |
| **決定** | repo 內 `data/`、`backups/`、`.scratch/` 為空；`labels/*.json` 是空骨架；資料放外部目錄 |
| **理由** | 新 checkout 應該是「可執行但還沒資料」，不是「帶著別人的樣本」 |
| **代價** | 要沿用既有資料得設 `REA_DB_PATH` 或放回 `data/`；全新抽取則自動建立 |
| **證據** | 乾淨 checkout 的 `doctor` 回 `RESULT: OK (3 warnings)`；`npm run start:server` 從任何目錄啟動都會把 sink 建在 repo 的 `data/rea-figma.sqlite` |

---

## D12. 來源可追溯才算成功

| | |
|---|---|
| **背景** | 模型可以生成看起來合理但不存在的 ID |
| **決定** | `verify-source` 檢查 labels／predictions／佇列裡的每個 ID 是否存在、名稱是否與 DB 一致；掛在 `sync` 最後一步 |
| **理由** | 對設計師而言「ID 能貼回 Figma」比「預測準」重要 |
| **代價** | 每次 sync 多幾秒；ID 拼錯會擋住整條流程 |
| **證據** | 42 labels + 249 predictions + 249 queue rows 全部通過；任何一筆不存在就 FAIL |

---

## D13. MCP 工具表面要覆蓋三種查詢形狀

| | |
|---|---|
| **背景** | 寫 `docs/graph.html` 時要回答「有多少個彈窗頁面」，才發現 MCP 沒有「列出全部畫面」的工具；列舉原語只存在於 CLI 的 `sheets --unique`。工具集是按「單頁 / 家族 / 待分類」的場景長出來的 |
| **決定** | 每一層資料至少要能用三種形狀查詢：**列舉**（有哪些）、**單體**（這一頁）、**聚合**（有多少）。MCP 至少各有一個代表工具（`list_screens` / `screen_sheet` / `list_screens.byArchetype`） |
| **理由** | agent 的第一個問題幾乎都是「有哪些」或「有多少」，不是「這一頁」。只有單體工具時，模型被迫先猜一個 ID，或退回去用 CLI |
| **代價** | 工具數增加到 11，schema 面積變大；用 enum、數值範圍與描述收斂 |
| **證據** | `list_screens` 上線後，291 / 172 / 87 / 32 可由 MCP 直接回答；在此之前同一問題只能走 CLI |

**沒有加的工具**：

- `manifest`：`tools/list` 已經提供工具表面，重複沒有價值。
- `verify_source`：它是 CI 的 gate，不是查詢；MCP 保持唯讀查詢面。若未來做 hosted 模式再補。

---

## 決策之間的依賴

```
D1 結構身份 ──┬─→ D2 版面原型（用 z-order，不用面積）
              ├─→ D3 變體軸（不用詞彙）
              └─→ D5 單一核心（同一套 hash 給三個 adapter）

D4 unknown ───→ D12 來源可追溯（寧可棄權，不要編造）

D7 產物隔離 ──→ D11 產品與資料分離

D9 plugin 主體 ─→ D10 命令不吃參數（命令只做確定的事）
```
