从其他 CMS 或内容系统迁移/replatform 到…

当需要把 AEM、Contentful、Strapi、Webflow、WordPress、Payload、Drupal、Markdown/MDX/frontmatter、WXR/XML、CMS API、数据库转储或静态 HTML 迁移到 Sanity 时使用。

适用场景

解决思路

1. 把 CMS 到 Sanity 的迁移当作内容策略和 ETL 项目，而不是盲目 lift-and-shift。
2. 先阅读 `references/general.md`。
3. 如果源平台是 AEM/Adobe Experience Manager，读取 `references/aem.md`。
4. 如果源平台是 Contentful，读取 `references/contentful.md`。
5. 如果源平台是 Strapi，读取 `references/strapi.md`。
6. 如果源平台是 Webflow，读取 `references/webflow.md`。
7. 如果源平台是 WordPress/WXR/Elementor，读取 `references/wordpress.md`。
8. 如果源平台是 Payload，读取 `references/payload.md`。
9. 如果源平台是 Drupal，读取 `references/drupal.md`。
10. 如果源平台是 Markdown/MDX/frontmatter 文件，读取 `references/markdown.md`。
11. 在写代码之前，产出简短迁移计划，覆盖源访问、内容范围、schema 决策、抽取、转换、导入、验证、重定向和切换。
12. 对真实迁移优先使用确定性、可重复脚本；编写并审查迁移脚本、映射和验证检查；不要依赖一次性内容操作处理大内容量。
13. 对于实现或规划任务，产出以下工件，或解释为何不需要。
14. 产出内容清单：源类型、数量、语言环境、状态/草稿范围、资产和关系类型。
15. 产出源到 Sanity 映射：文档类型、对象类型、引用、Portable Text 字段、资产字段、ID 和被跳过内容。
16. 产出抽取方式：所需凭据/访问、API/导出命令、原始快照位置和已知盲点。
17. 产出转换/导入计划：确定性 ID、写入顺序、资产处理、富文本转换、验证和重跑策略。
18. 产出切换计划：增量同步/内容冻结、重定向、断链检查、SEO 元数据和手动清理。
19. 使用从源 ID、slug、路径或哈希派生的稳定文档 ID。
20. 使用 `createOrReplace`、`createIfNotExists` 或 `sanity datasets import --replace`，使重跑收敛。
21. 转换前将抽取的源数据快照到磁盘。
22. 先导入或创建被引用文档，再导入引用它们的文档。
23. 将富文本转换为 Portable Text，而不是存储原始 HTML 或 Markdown 字符串。
24. 将资产上传到 Sanity 或 Media Library；不要让生产内容依赖旧 CDN URL。
25. 跟踪每文档质量问题，并在切换前生成验证摘要。
26. 保留旧 URL 和源 ID，用于重定向、QA 和未来调试。
27. 对内容本身建模，而不是对旧站点如何渲染它建模。
28. 可复用或独立管理的实体用文档；由单个文档拥有的内容用对象。
29. 编写 Sanity schema 时使用 `defineType`、`defineField` 和 `defineArrayMember`。
30. 使用 image/file 字段搭配已上传的 Sanity 资产或 Media Library 资产，而不是旧 CDN URL。
31. 富文本和自定义块使用 Portable Text 数组；不要把原始 HTML 存为规范正文。
32. 当项目使用 TypeScript 时，在 schema 或 GROQ 查询变更后运行 schema extraction 和 TypeGen。
33. 对目标 dataset 使用 MCP/content 工具前，先部署或应用 schema 变更。
34. 如需更深入的 Sanity 实现指导，若已安装 `sanity-best-practices` 则使用它。
35. 若未安装 `sanity-best-practices`，告知用户可用 `npx skills add sanity-io/agent-toolkit --skill sanity-best-practices` 添加。
36. 当源访问路径、凭据、导出文件或数据库连接不明确时，编码前停止并询问。
37. 当目标 Sanity 项目/dataset 或是否应使用临时 dataset 不明确时，编码前停止并询问。
38. 当草稿、归档、定时、语言环境或版本历史范围不明确时，编码前停止并询问。
39. 当媒体文件是否应迁移，以及资产 URL/文件是否可访问不明确时，编码前停止并询问。
40. 当目标 schema 已存在，还是应作为迁移的一部分设计不明确时，编码前停止并询问。
41. 不要为源支持的文档创建随机 ID。
42. 不要先获取再创建被引用文档；使用确定性 ID 和 `createIfNotExists`/`createOrReplace`。
43. 当 NDJSON 或脚本合适时，不要通过 MCP content 工具运行批量迁移。
44. 除非要求，不要把语言环境回退值扁平化为翻译。
45. 不要为必需媒体、作者、引用或富文本转换留下 TODO。
46. 没有数量检查、样本检查、引用检查和路由/重定向检查，不要宣布迁移完成。
47. 使用 `references/general.md` 了解共享迁移原则，并使用平台参考了解源特定抽取路径、建模陷阱和验证检查。
48. 对未明确覆盖的源系统，应用 `references/general.md` 并适配最接近的平台模式。
49. API-first CMS：从 Contentful、Strapi 或 Payload 开始。
50. 单体/page-builder 系统：从 WordPress、Drupal、Webflow 或 AEM 开始。
51. HTML 重的导出：从 WordPress 和 Webflow 富文本指导开始。
52. Markdown-first 源：从 `references/markdown.md` 开始。

适用边界 · 注意事项

• 当源访问路径、凭据、导出文件或数据库连接，目标 Sanity 项目/dataset，草稿/归档/定时/语言环境/版本范围，媒体迁移范围，或目标 schema 等关键信息不明确时，不要开始编码。
• 不适用于非 Sanity 目标，或没有 Sanity 项目/dataset、schema、Media Library、MCP/content 工具等目标环境的迁移。
• 不适合把迁移当作盲目 lift-and-shift，或用一次性内容操作处理大内容量。