sanity-migration

Sanity 遷移

使用此技能進行 CMS 到 Sanity 的遷移工作。將遷移視為內容策略與 ETL 專案，而非盲目的搬移。

必要工作流程

1. 先閱讀 references/general.md。
2. 如果已知來源平台，也請閱讀其指南：
   • AEM / Adobe Experience Manager：references/aem.md
   • Contentful：references/contentful.md
   • Strapi：references/strapi.md
   • Webflow：references/webflow.md
   • WordPress / WXR / Elementor：references/wordpress.md
   • Payload：references/payload.md
   • Drupal：references/drupal.md
   • Markdown / MDX / frontmatter 檔案：references/markdown.md
3. 在撰寫程式碼之前，先產出一份簡短的遷移計畫，涵蓋來源存取、內容範圍、結構描述決策、萃取、轉換、匯入、驗證、重新導向與切換。
4. 對於實際遷移，偏好使用確定性、可重複執行的腳本。撰寫並審查遷移腳本、對應與驗證檢查；不要依賴一次性內容操作來處理大量內容。

應產出的交付物

對於實作或規劃任務，請產出以下產出物，或解釋為何不需要：

• 內容盤點：來源類型、數量、語言、狀態/草稿範圍、資產與關聯類型。
• 來源到 Sanity 對應：文件類型、物件類型、參考、Portable Text 欄位、資產欄位、ID 與跳過的內容。
• 萃取方式：所需的憑證/存取權、API/匯出指令、原始快照位置與已知盲點。
• 轉換/匯入計畫：確定性 ID、寫入順序、資產處理、富文本轉換、驗證與重新執行策略。
• 切換計畫：增量同步/內容凍結、重新導向、失效連結檢查、SEO 中繼資料與手動清理。

預設值

• 使用從來源 ID、slug、路徑或雜湊衍生的穩定文件 ID。
• 使用 createOrReplace、createIfNotExists 或 sanity dataset import --replace，以便重新執行時能收斂。
• 在轉換之前，先將萃取的來源資料快照到磁碟。
• 先匯入或建立被參考的文件，再匯入參考它們的文件。
• 將富文本轉換為 Portable Text，而非儲存原始 HTML 或 Markdown 字串。
• 將資產上傳至 Sanity 或媒體庫；不要讓正式環境內容依賴舊有 CDN URL。
• 追蹤每份文件的品質問題，並在切換前產出驗證摘要。
• 保留舊有 URL 與來源 ID，以利重新導向、品質保證與日後除錯。

Sanity 護欄

• 建模內容的本質，而非舊網站的呈現方式。
• 對於可重複使用或獨立管理的實體，使用文件；對於僅屬於單一文件的內容，使用物件。
• 如果撰寫 Sanity 結構描述，請使用 defineType、defineField 與 defineArrayMember。
• 使用已上傳至 Sanity 資產或媒體庫資產的圖片/檔案欄位，而非舊有 CDN URL。
• 使用 Portable Text 陣列來處理富文本與自訂區塊；不要將原始 HTML 儲存為正文字段。
• 在結構描述或 GROQ 查詢變更後，若專案使用 TypeScript，請執行結構描述萃取與 TypeGen。
• 在使用 MCP/內容工具針對目標資料集之前，先部署或套用結構描述變更。

如需更深入的 Sanity 實作指引，若 sanity-best-practices 已可用，請使用它。若未安裝，請告知使用者可透過以下指令新增：

npx skills add sanity-io/agent-toolkit --skill sanity-best-practices

停下來詢問

在以下情況不明確時，請在撰寫程式碼前停下來詢問：

• 來源存取路徑、憑證、匯出檔案或資料庫連線。
• 目標 Sanity 專案/資料集，或是否應使用暫存資料集。
• 草稿、封存、排程、語言或版本歷史的範圍。
• 媒體檔案是否應遷移，以及資產 URL/檔案是否可存取。
• 目標結構描述是否已存在，或應作為遷移的一部分來設計。

禁止事項

• 不要為來源支援的文件建立隨機 ID。
• 不要先擷取再建立被參考的文件；請使用確定性 ID 與 createIfNotExists/createOrReplace。
• 當 NDJSON 或腳本更合適時，不要透過 MCP 內容工具執行大量遷移。
• 除非要求，否則不要將語言備援值扁平化為翻譯。
• 不要留下關於必要媒體、作者、參考或富文本轉換的待辦事項。
• 未經計數檢查、抽樣檢查、參考檢查與路由/重新導向檢查，不要宣告遷移完成。

參考對應

使用 references/general.md 取得共通的遷移原則，並使用平台參考取得特定來源的萃取路徑、建模陷阱與驗證檢查。

對於未明確涵蓋的來源系統，請套用 references/general.md 並調整最接近的平台模式：

• API 優先的 CMS：從 Contentful、Strapi 或 Payload 開始。
• 單體/頁面建構器系統：從 WordPress、Drupal、Webflow 或 AEM 開始。
• HTML 密集的匯出：從 WordPress 與 Webflow 的富文本指南開始。
• Markdown 優先的來源：從 references/markdown.md 開始。