migrate-to-cloudcannon

迁移到 CloudCannon

此技能负责协调将现有 SSG 网站完整迁移到 CloudCannon。迁移分为五个阶段，并将特定领域的工作委派给也可单独使用的独立技能。

模型建议： 迁移涉及跨越五个阶段的多文件架构决策。为获得最佳效果，请使用推理能力较强的模型（而非速度快或轻量级模型）。

必须： 将此技能作为迁移协调器运行。第一阶段开始前，请阅读 orchestration.md，随后将各阶段分别委派给子 Agent，并由你自己继续与用户对话。在不支持子 Agent 的主机上，请按顺序自行完成各阶段。

适用场景

• 现有 SSG 网站需要端到端地适配 CloudCannon
• 网站模板需要改造为兼容 CloudCannon
• 网站作为任务的一部分生成（例如从 WordPress 生成），并且需要生成后即可用于 CloudCannon

不适用场景

• 网站已经部署在 CloudCannon 上，只需添加一项功能——直接使用对应的功能技能：cloudcannon-configuration、cloudcannon-snippets 或 cloudcannon-visual-editing
• 只需要多语言或翻译工作——make-site-multilingual，然后是 translate-site。这两项都不属于五个阶段。
• 某项 CloudCannon 功能在正常运行的网站上出现异常——使用负责该功能的技能，而不是完整迁移

内容

文件	涵盖内容
SKILL.md（此文件）	五个阶段、交接准备情况、命名约定、常见错误
astro/overview.md	Astro 从这里开始——各阶段指南
hugo/overview.md	Hugo 从这里开始——各阶段指南
eleventy/overview.md	Eleventy 从这里开始——各阶段指南
audit.md	通用审查规则——对静态页面进行分类
page-building.md	当普查将页面归入 pages 集合或页面构建器时阅读
cc-friendly-conventions.md	共享 UI 处理对照表
orchestration.md	在子 Agent 中运行各阶段、问题、验证、规模评估
handoff.md	与用户收尾——谁测试什么，以及需要询问哪些反馈
reading-order.md	各阶段需要阅读哪些文档，以及何时可以跳过
scripts/README.md	用于确定性步骤的自动化脚本

支持的 SSG

SSG	指南
Astro	astro/overview.md
Hugo	hugo/overview.md
Eleventy	eleventy/overview.md

与上游技能衔接

如果此任务需要生成网站（例如从 WordPress 转换），请在搭建前阅读目标 SSG 的脚手架约定——Astro：astro/cc-friendly-conventions.md——其中介绍了有助于顺利完成迁移的结构选择。搭建完成后，返回此处并执行迁移阶段。

第 1 步：检测 SSG

从项目根目录运行：

npx @cloudcannon/cli configure detect-ssg

根据检测到的 SSG 选择上方对应的指南。

迁移阶段

每份 SSG 指南都会按以下顺序介绍各阶段。委托给独立技能的阶段会在下方标明。

1. 审查 — 在做出任何更改之前，分析内容结构、组件、路由和构建流程。
2. 配置 — 生成并自定义 CloudCannon 配置文件。
   • 阅读 cloudcannon-configuration 技能。
   • 如果内容使用了组件（MDX 组件、Hugo 或 Eleventy 短代码）或内嵌 HTML，也要阅读 cloudcannon-snippets 技能。
3. 内容 — 必要时重构内容文件，使其更适合 CMS。
4. 可视化编辑 — 添加可供 CloudCannon Visual Editor 编辑的区域。
   • 阅读 cloudcannon-visual-editing 技能。
5. 构建与测试 — 端到端验证迁移结果。

并非每个网站都需要完成所有阶段。如果内容结构已经清晰，小型网站可以跳过第 3 阶段。第 4 阶段为可选项，但价值很高。

每阶段工作流

阶段子代理负责步骤 1–4；编排器负责步骤 5。请参阅 orchestration.md。

1. 阅读 — 在修改任何文件之前，通读阶段文档。
2. 跟踪 — 使用宿主提供的任务／待办工具，为该阶段文档中的每项检查清单任务单独创建一项任务。如果没有此类工具，请在阶段迁移记录中保留检查清单，并在完成后逐项勾选。开始任务前将其设为 in_progress；只有在满足检查清单项目要求后才标记为 completed。不要等到阶段结束时才批量完成任务。
3. 执行工作 — 可以在任意阶段进行小型、机械式的跨阶段修复（添加缺失字段、规范化值）；请在交接内容中逐项列出。结构性更改（移动文件、重组集合、更改渲染方式）应留到对应阶段处理。
4. 编写 .cloudcannon/migration/<phase>.md，记录发现，并包含后续阶段需要依赖的两个部分：
   • 决策及原因 — 记录每项选择及其原因，以便后续阶段遵循，而不是重新决策。
   • 未决问题 — 记录留给用户、不会阻碍工作的疑问，并注明采用的默认方案。
5. 验证交接就绪情况 — 由编排器或全新的验证者根据 orchestration.md § Verification 验证下方的交接就绪情况行。不得由执行该阶段的子代理验证。

原因： 检查清单可以发现 Agent 容易忽略的问题——collections_config 中缺少数据集合、引用的数据文件缺少对应的 data_config 条目、专注于页面构建器区块而漏掉博客／详情页的可编辑区域、数组未关联到结构。逐项跟踪任务可以清晰呈现检查过程。

阶段交接准备情况

这些条目定义了下一阶段子 Agent 启动前必须满足的条件。跨阶段修复（见上文第 3 步）仍然可以进行。

阶段结束后	满足以下条件即可交接……
1. 审计	.cloudcannon/migration/audit.md 存在，包含普查表，并列出每个集合和每个页面路由。已评估规模阈值（orchestration.md § Sizing）；如果触发阈值，则 .cloudcannon/migration/plan.md 存在。
2. 配置	cloudcannon.config.yml 通过已发布的 JSON 架构验证（IDE 中没有红色波浪线）。审计中的每个集合都有一个 collections_config 条目；每个引用的数据文件都有一个 data_config 条目。已编写 .cloudcannon/migration/configuration.md。
3. 内容	文件中已反映第 2 阶段的所有结构性内容更改。npm run build（或项目对应命令）成功。已编写 .cloudcannon/migration/content.md。
4. 可视化编辑	审计普查表中 需要可编辑区域？ 一栏为“是”的每一行，都已完成接入，或已记录未接入的理由。包装后的分节中使用的每个组件都可以重新渲染——已注册（Astro：registerComponents.ts）或可解析（Hugo：一个 partial；Eleventy：一个 Liquid include——Nunjucks 分节仅使用基本区域）。已编写 .cloudcannon/migration/visual-editing.md。
5. 构建与测试	本地生产构建成功。用户已运行 CloudCannon 侧的验证（预览、行内编辑、保存到 Git）。已编写 .cloudcannon/migration/build.md。

脚本

确定性的迁移步骤已作为脚本自动化，存放在 scripts/ 中。请在相关阶段之前或期间运行这些脚本。

迁移说明

所有说明均写入 .cloudcannon/migration/（位于 .cloudcannon/ 下，以免 CLI 将此文件夹识别为集合）：每个阶段一个文件（audit.md、configuration.md、content.md、visual-editing.md、build.md）；如果迁移分为多个部分，还需包含 plan.md。每个文件对应的验收条件请参阅上文的各阶段工作流程。

命名约定

如果项目已有约定，请遵循现有约定。否则：

• 文件使用 kebab-case
• JavaScript 和 JSON 使用 camelCase
• Markdown frontmatter 和 YAML：与现有组件属性名称保持一致，确保 frontmatter 键无需翻译即可传递
• 没有现有约定的新字段：优先使用 snake_case

已知问题的交叉引用

有关特定架构决策和配置语法错误，请参阅：

主题	Astro	Hugo	Eleventy
静态页面分类（可编辑源文件、页面构建器或集合）	audit.md § 静态页面分类，然后参阅 astro/audit.md § 静态页面分类：可编辑源文件与内容集合	hugo/audit.md § 静态页面分类	eleventy/audit.md § 静态页面分类
首页文件名、单项集合	page-building.md § 常见错误，然后参阅 astro/page-building.md § Pages 集合速查表	hugo/page-building.md § 常见错误	eleventy/page-building.md § 常见错误
共享 UI（CTA 横幅、页脚、分享区块）	cc-friendly-conventions.md § 共享 UI 处理表	同一张表	同一张表
多模式集合	../cloudcannon-configuration/astro/configuration.md § 模式	../cloudcannon-configuration/hugo/configuration.md § 模式	../cloudcannon-configuration/schemas.md
配置语法幻觉（错误的键/类型）	cloudcannon-configuration § 无效键	同上	同上
构建验证	build.md § 构建验证清单，然后参阅 astro/build.md	build.md，然后参阅 hugo/build.md	build.md，然后参阅 eleventy/build.md

Common mistakes

借口	实际情况
“这个网站足够简单，可以跳过审计”	审计能及早发现结构问题。跳过审计意味着要到配置过程中才发现问题。
“我会在最后完成检查清单”	开始每个阶段之前都要先阅读检查清单。它们会告诉你目标是什么。
“内容重组可以以后再做”	如果缺少某个字段会阻碍配置，就现在添加。各阶段是依次进行的，并非彼此隔离。
“视觉编辑是可选的，所以我会跳过”	对编辑者而言，这是价值最高的阶段。只有用户明确要求时才跳过。
“构建通过了，所以我们完成了”	构建通过并不代表编辑器能正常工作。用户必须在 CloudCannon 中进行验证。
“我会把主页文件命名为 home.md——这样更有描述性”	CloudCannon 会根据 slug 确定 URL；home.md 配上 url: "/[slug]/" → /home/。使用 SSG 的索引文件名，让 slug 收敛为 /——Astro：index.md；Hugo：content/_index.md；Eleventy：输入目录中的 index.md。
“这是硬编码的，所以只有开发者能编辑”	如果编辑者能在页面上看到某项内容，就必须能编辑它。具体机制取决于页面类型：共享 UI（CTA 横幅、页脚、分享区块、作者卡片）→ 数据文件；编辑者可添加、移除或重新排序区块的页面 → 页面构建器 pages 集合条目；长篇正文页面 → pages 集合中的 default schema；结构由开发者维护的一次性页面 → data-editable="source"。参见 cc-friendly-conventions.md § 共享 UI 处理表 和 page-building.md § 何时使用页面构建器。
“这个页面很独特，所以应该可通过源码编辑”	独特与否并非判断标准。默认使用页面构建器；只有满足 page-building.md § 何时使用页面构建器 中的所有条件，才使用源码编辑。
“我会创建一个只有单个条目的 homepage 集合”	使用一个 pages 集合，并将 index.md 作为其中一个条目。再将 our-team.md、about.md 等添加为更多条目。CloudCannon 集合支持在同一集合中使用多个 schema——可通过 schemas: 配置实现；在 Astro 中，也可通过内容配置中的 Zod z.union 实现。参见 ../cloudcannon-configuration/schemas.md。
“这些页面很少，用页面构建器太小题大做了”	当项目拥有自己的布局，且有多个布局独特的页面时，默认使用页面构建器。由主题渲染的页面沿用主题的模型——参见 audit.md § 静态页面分类。代价是增加一个兜底路由和一个区块分发器——Astro：[...slug].astro + BlockRenderer；Hugo：在页面布局中对 content_blocks 执行 range；Eleventy：在布局中对 content_blocks 执行 for 循环。这些都只是机械性工作。好处是编辑者无需工程支持就能添加新页面。