sanity-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sanity Migration

Sanity 迁移

Use this skill for CMS-to-Sanity migration work. Treat migration as a content strategy and ETL project, not a blind lift-and-shift.

本技能适用于CMS到Sanity的迁移工作。请将迁移视为内容策略与ETL项目，而非盲目地直接迁移。

Required Workflow

必备工作流程

Read
```
references/general.md
```
first.
If the source platform is known, also read its guide:
- 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 files:
```
references/markdown.md
```
Before writing code, produce a short migration plan covering source access, content scope, schema decisions, extraction, transformation, import, validation, redirects, and cutover.
Prefer deterministic, repeatable scripts for real migrations. Write and review migration scripts, mappings, and validation checks; do not rely on one-off content operations for large content volumes.

首先阅读
```
references/general.md
```
。
若源平台已知，还需阅读对应指南：
- 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
```
编写代码前，需生成一份简短的迁移计划，涵盖源访问权限、内容范围、架构决策、提取、转换、导入、验证、重定向及切换步骤。
实际迁移时优先使用确定性、可重复的脚本。编写并审查迁移脚本、映射关系及验证检查；处理大量内容时，请勿依赖一次性内容操作。

Deliverables to Produce

需交付的成果

For implementation or planning tasks, produce these artifacts or explain why they are not needed:

Content inventory: source types, counts, locales, status/draft scope, assets, and relationship types.
Source-to-Sanity mapping: document types, object types, references, Portable Text fields, asset fields, IDs, and skipped content.
Extraction approach: credentials/access needed, API/export commands, raw snapshot location, and known blind spots.
Transform/import plan: deterministic IDs, write order, asset handling, rich text conversion, validation, and rerun strategy.
Cutover plan: delta sync/content freeze, redirects, broken-link checks, SEO metadata, and manual cleanup.

对于实施或规划任务，需生成以下成果，或说明无需生成的原因：

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

Defaults

默认规则

Use stable document IDs derived from source IDs, slugs, paths, or hashes.

Use

createOrReplace

createIfNotExists

, or

sanity dataset import --replace

so reruns converge.

Snapshot extracted source data to disk before transforming it.
Import or create referenced documents before documents that reference them.
Convert rich text to Portable Text instead of storing raw HTML or Markdown strings.
Upload assets to Sanity or the Media Library; do not leave production content dependent on legacy CDN URLs.
Track per-document quality issues and produce a validation summary before cutover.
Preserve legacy URLs and source IDs for redirects, QA, and future debugging.

使用源自源ID、slug、路径或哈希值的稳定文档ID。

使用

createOrReplace

、

createIfNotExists

或

sanity dataset import --replace

命令，确保重新运行时能收敛结果。

在转换前将提取的源数据快照保存到磁盘。
在导入引用它们的文档之前，先导入或创建被引用的文档。
将富文本转换为Portable Text，而非存储原始HTML或Markdown字符串。
将资产上传至Sanity或媒体库；请勿让生产内容依赖旧版CDN URL。
跟踪每个文档的质量问题，并在切换前生成验证摘要。
保留旧版URL和源ID，用于重定向、QA及未来调试。

Sanity Guardrails

Sanity 约束规则

Model what content is, not how the old site rendered it.
Use documents for reusable or independently managed entities; use objects for content owned by one document.
Use
```
defineType
```
,
```
defineField
```
, and
```
defineArrayMember
```
if authoring Sanity schemas.
Use image/file fields with uploaded Sanity assets or Media Library assets, not legacy CDN URLs.
Use Portable Text arrays for rich text and custom blocks; do not store raw HTML as the canonical body.
Run schema extraction and TypeGen after schema or GROQ query changes when the project uses TypeScript.
Deploy or apply schema changes before using MCP/content tools against the target dataset.

For deeper Sanity implementation guidance, use

sanity-best-practices

if it is already available. If it is not installed, tell the user they can add it with:

bash

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

建模内容本身，而非旧站点的渲染方式。
文档用于可复用或独立管理的实体；对象用于归属于单个文档的内容。
编写Sanity架构时使用
```
defineType
```
、
```
defineField
```
和
```
defineArrayMember
```
。
使用图片/文件字段存储已上传的Sanity资产或媒体库资产，而非旧版CDN URL。
使用Portable Text数组存储富文本和自定义块；请勿将原始HTML作为标准正文存储。
当项目使用TypeScript时，在架构或GROQ查询变更后运行架构提取和TypeGen。
在针对目标数据集使用MCP/内容工具之前，先部署或应用架构变更。

如需更深入的Sanity实施指导，若

sanity-best-practices

已可用，请使用该技能。若未安装，请告知用户可通过以下命令添加：

bash

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

Stop and Ask

需暂停并确认的情况

Stop before coding when any of these are unclear:

Source access path, credentials, export file, or database connection.
Target Sanity project/dataset or whether a scratch dataset should be used.
Draft, archived, scheduled, locale, or version history scope.
Whether media files should be migrated and whether asset URLs/files are accessible.
Whether the destination schema exists or should be designed as part of the migration.

当以下任何事项不明确时，请暂停编码：

源访问路径、凭证、导出文件或数据库连接。
目标Sanity项目/数据集，或是否应使用临时数据集。
草稿、归档、计划发布、区域设置或版本历史的范围。
是否应迁移媒体文件，以及资产URL/文件是否可访问。
目标架构是否已存在，或是否应作为迁移的一部分进行设计。

Do Not Do This

禁止操作

Do not create random IDs for source-backed documents.
Do not fetch-then-create referenced documents; use deterministic IDs and
```
createIfNotExists
```
/
```
createOrReplace
```
.
Do not run bulk migrations through MCP content tools when NDJSON or scripts are appropriate.
Do not flatten locale fallback values into translations unless requested.
Do not leave TODOs for required media, authors, references, or rich text conversion.
Do not declare a migration done without count checks, sample checks, reference checks, and route/redirect checks.

请勿为源相关文档创建随机ID。
请勿先获取再创建被引用的文档；请使用确定性ID及
```
createIfNotExists
```
/
```
createOrReplace
```
命令。
当NDJSON或脚本更合适时，请勿通过MCP内容工具运行批量迁移。
除非有要求，否则请勿将区域设置回退值平展到翻译内容中。
请勿遗留未处理的必要媒体、作者、引用或富文本转换的TODO项。
未完成数量检查、样本检查、引用检查及路由/重定向检查前，请勿宣布迁移完成。

Reference Map

参考映射

Use

references/general.md

for shared migration principles and the platform references for source-specific extraction routes, modeling traps, and validation checks.

For source systems not explicitly covered, apply

references/general.md

and adapt the closest platform pattern:

API-first CMSes: start from Contentful, Strapi, or Payload.
Monolithic/page-builder systems: start from WordPress, Drupal, Webflow, or AEM.
HTML-heavy exports: start from the WordPress and Webflow rich-text guidance.
Markdown-first sources: start from
```
references/markdown.md
```
.

使用

references/general.md

获取通用迁移原则，使用平台参考文档获取源特定的提取路径、建模陷阱及验证检查。

对于未明确覆盖的源系统，请应用

references/general.md

的原则，并适配最相近的平台模式：

API优先的CMS：从Contentful、Strapi或Payload的模式开始。
单体/页面构建器系统：从WordPress、Drupal、Webflow或AEM的模式开始。
以HTML为主的导出文件：从WordPress和Webflow的富文本指导开始。
以Markdown为主的源：从
```
references/markdown.md
```
开始。