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. 编写代码前，先制定简短的迁移计划，涵盖源平台访问、内容范围、Schema 决策、提取、转换、导入、验证、重定向和切换。
4. 对实际迁移，优先使用确定性、可重复执行的脚本。编写并审查迁移脚本、映射和验证检查；对于大量内容，不要依赖一次性的内容操作。

需要交付的内容

对于实施或规划任务，请产出以下内容，或说明为何无需产出：

• 内容清单：源内容类型、数量、语言区域、状态／草稿范围、资源和关系类型。
• 源平台到 Sanity 的映射：文档类型、对象类型、引用、Portable Text 字段、资源字段、ID 以及跳过的内容。
• 提取方案：所需凭据／访问权限、API／导出命令、原始快照位置和已知盲点。
• 转换／导入计划：确定性 ID、写入顺序、资源处理、富文本转换、验证和重新运行策略。
• 切换计划：增量同步／内容冻结、重定向、失效链接检查、SEO 元数据和人工清理。

默认做法

• 使用源 ID、slug、路径或哈希生成稳定的文档 ID。
• 使用 createOrReplace、createIfNotExists 或 sanity datasets import --replace，确保重新运行后结果一致。
• 在转换数据前，将提取的源数据快照保存到磁盘。
• 先导入或创建被引用的文档，再导入或创建引用这些文档的文档。
• 将富文本转换为 Portable Text，而不是存储原始 HTML 或 Markdown 字符串。
• 将资源上传到 Sanity 或 Media Library；不要让生产内容依赖旧版 CDN URL。
• 按文档跟踪质量问题，并在切换前生成验证摘要。
• 保留旧版 URL 和源 ID，以便用于重定向、QA 和后续调试。

Sanity 使用规范

• 对内容本身建模，而非对旧网站的渲染方式建模。
• 对可复用或独立管理的实体使用文档；对归属于单个文档的内容使用对象。
• 编写 Sanity Schema 时使用 defineType、defineField 和 defineArrayMember。
• 图像／文件字段应使用已上传的 Sanity 资源或 Media Library 资源，而非旧版 CDN URL。
• 对富文本和自定义区块使用 Portable Text 数组；不要将原始 HTML 存储为规范正文。
• 如果项目使用 TypeScript，在 Schema 或 GROQ 查询发生更改后运行 Schema 提取和 TypeGen。
• 使用 MCP／内容工具操作目标数据集前，先部署或应用 Schema 更改。

如需更深入的 Sanity 实施指导，请在 sanity-best-practices 已可用时使用。如果尚未安装，请告知用户可以通过以下方式添加：

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

停止并询问

以下任一事项不明确时，请在编写代码前停止：

• 源平台的访问方式、凭据、导出文件或数据库连接。
• 目标 Sanity 项目／数据集，或是否应使用临时数据集。
• 草稿、已归档、已排期、语言区域或版本历史的范围。
• 是否应迁移媒体文件，以及资源 URL／文件是否可访问。
• 目标 Schema 是否已存在，或是否应作为迁移的一部分进行设计。

不要这样做

• 不要为有来源依据的文档创建随机 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 入手。