將 Glyphs 3 外掛遷移至 Glyphs 4

建立一份可審查的 Python 外掛遷移副本。將靜態遷移視為在 Glyphs 4 中進行手動啟動測試的準備工作，而非執行時期相容性的證明。

防護措施

保留原始外掛或儲存庫。
絕不原地遷移。拒絕現有的輸出路徑。
除非使用者另行要求，否則絕不安裝、執行、重新載入、重新啟動 Glyphs，或變更現用的 Plugins 資料夾。
使用 Glyphs MCP docs_search 和 docs_get 工具作為主要的開發知識庫。工具命名空間因用戶端而異；請根據最終的工具名稱和描述來解析它們。
在變更 GlyphsApp API、外掛生命週期方法、選擇器、回呼、套件中繼資料或形狀處理之前，先擷取重點官方指南。
一般工作請勿呼叫 docs_enable_page_resources。應按需擷取頁面。
優先使用 schriftgestalt/GlyphsSDK 的目前 Glyphs4 分支；不要假定 Glyphs 3 範本或快取載入器是最新的。
將行為變更與機械性遷移變更分開處理。

在審查 API 特定發現之前，請先閱讀 references/glyphs-mcp-development-kb.md 。

確認 Glyphs MCP 伺服器已提供 docs_search 和 docs_get。
在編輯前建立文件基準：
- 搜尋 plugins 並擷取官方外掛手冊結果。
- 搜尋 Info.plist 並擷取 Python 外掛範本總覽和 plist 範本。
- 搜尋確切的基底類別，例如 GeneralPlugin、ReporterPlugin、FilterWithoutDialog、PalettePlugin、SelectTool 或 FileFormatPlugin；擷取其指南、原始碼範本以及相關的外掛 API 章節。
分別搜尋每個不熟悉的類別、屬性、回呼或選擇器。偏好使用簡短的確切符號，例如 GSLayer、shapes 或 addCallback。
透過傳回的 doc_id 或 path 來擷取結果。如果 truncated 為 true，請從 nextOffset 繼續，直到相關章節完整為止。
記錄每個擷取頁面的標題、docId、sourceKind、sourceUrl 以及其所支援的遷移決策。將此證據納入交接文件。
如果工具無法使用，請回報 Glyphs MCP 文件檢閱受阻。靜態審計可繼續進行，但請勿將未經驗證的 API 或生命週期變更視為可遷移。

在複製前進行審計：

python3 scripts/migrate_plugin.py "/path/to/source" \
  --sdk "/path/to/GlyphsSDK"

閱讀 references/migration-review.md。對於每個 API 特定發現，搜尋內含的 Glyphs 文件中該類別、屬性、回呼、選擇器或外掛類型，並僅擷取相關頁面。

建立遷移副本並套用保守的框架匯入修正：

python3 scripts/migrate_plugin.py "/path/to/source" \
  --output "/path/to/new-glyphs4-copy" \
  --sdk "/path/to/GlyphsSDK" \
  --apply-safe-fixes

僅在審查其影響後才使用選擇性重寫：
- 新增 --rewrite-wildcard-imports 以使用 Glyphs 4 .pyi 存根中找到的符號，取代簡單的 from GlyphsApp import * 陳述式。
- 新增 --replace-loader 以將 SDK 範本的 Contents/MacOS/plugin 複製到每個套件中。
- 新增 --align-glyphs4-plist 以移除目前 Glyphs 4 範本中不存在的舊版更新饋送金鑰。首先確認該外掛不依賴其自身的更新饋送。
檢閱產生的遷移報告和完整的原始碼差異。手動修正生命週期、API、依賴項、UI 或混合形狀的問題。將每個 API 特定的變更連結到一個擷取的知識庫頁面。
驗證每個套件：
- 使用目標 Glyphs Python 版本解析所有 Python 檔案。
- 對每個 Contents/Info.plist 執行 plutil -lint。
- 確認 NSPrincipalClass、PyMainFileNames 和主要的 Python 類別一致。
- 將套件結構與相符的目前 Glyphs 4 SDK 範本進行比較。
- 當介面變更時，重新編譯 .xib 檔案。
交接一份手動測試計畫。在 Glyphs 4 中測試一個可拋棄的副本，執行每個選單項目和回呼，檢查巨集面板和控制台輸出，並測試與此外掛相關的復原、匯出、繪圖和依賴路徑。

對於 僅 Glyphs 4，在目前存根中確認後，允許 Glyphs 4 執行時期支援的 API 和 Python 語法。
對於 Glyphs 3 與 4，在可行時保持共用程式碼路徑，使用能力檢查來區分真正的 API 差異，並測試兩個應用程式。請勿僅為了註解而新增僅限 Glyphs 4 的語法。
如果外掛重構 layer.paths、layer.components 或 layer.shapes，請檢查它是否必須保留混合形狀順序或較新的形狀類型。切勿推斷僅路徑的重寫是無損的。

傳回新的副本、遷移報告、相容性目標、靜態驗證結果以及剩餘的手動 Glyphs 4 測試。包含一份文件證據表，列出每個頁面的標題、Glyphs MCP docId、官方 sourceUrl 以及其所支援的決策。明確說明未進行即時安裝或執行時期測試（除非確實有進行）。

scripts/migrate_plugin.py：審計和非破壞性複製輔助工具。
references/migration-review.md：基於證據的審查檢查清單和升級點。
references/glyphs-mcp-development-kb.md：精確的 MCP 查詢、分頁、證據和復原協定。
.mcp.json：Claude Code 外掛與本地 Glyphs MCP 伺服器的連線。
mcp.json：Cursor 外掛與本地 Glyphs MCP 伺服器的連線。
.claude-plugin/plugin.json：Claude Code 社群/外掛中繼資料；使用 claude --plugin-dir 載入此資料夾。
.cursor-plugin/plugin.json：Cursor 外掛中繼資料，用於註冊根目錄的 SKILL.md 和 mcp.json。
agents/openai.yaml：Codex 顯示中繼資料和 Glyphs MCP 依賴項。