migrating-to-cloudcannon

迁移到 CloudCannon

此技能会统筹将现有 SSG 网站完整迁移到 CloudCannon。它协调五个阶段，并将特定领域的工作委托给可独立使用的技能。

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

支持的 SSG

SSG	指南
Astro	astro/overview.md

与上游技能串联

如果网站是在此任务中生成的（例如，从 WordPress 转换而来），请先阅读 astro/cc-friendly-conventions.md，再进行脚手架搭建 — 其中介绍了有助于顺利迁移的结构选择。搭建好脚手架后，返回此处并执行迁移阶段。

步骤 1：检测 SSG

从项目根目录运行：

npx @cloudcannon/cli configure detect-ssg

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

迁移阶段

各 SSG 指南会按以下顺序逐步引导。委托给独立技能的阶段会在下方标明。

1. 审计 — 在进行任何更改之前，分析内容结构、组件、路由和构建流程。
2. 配置 — 生成并自定义 CloudCannon 配置文件。
   • 阅读 cloudcannon-configuration 技能。
   • 如果网站在内容中使用 MDX 组件或内联 HTML，也要阅读 cloudcannon-snippets 技能。
3. 内容 — 根据需要重构内容文件，使其适合 CMS。
4. 可视化编辑 — 添加可由 CloudCannon Visual Editor 编辑的区域。
   • 阅读 cloudcannon-visual-editing 技能。
5. 构建与测试 — 端到端验证迁移结果。

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

各阶段工作流程

按顺序执行每个阶段：

1. 阅读 — 在修改任何文件之前，从头到尾阅读该阶段的文档。
2. TaskCreate — 为该阶段文档中的每个检查项创建一个任务。开始处理前将任务设为 in_progress；只有在满足检查项要求后才能标记为 completed。不要等到阶段结束时再批量完成任务。
3. 执行工作 — 可以在任意阶段处理小型、机械式的跨阶段修复（例如添加缺失字段、规范化值）；结构性更改（移动文件、重组集合、更改渲染方式）应留到对应阶段处理。
4. 编写 — 在 .cloudcannon/migration/<phase>.md 中记录决策、发现以及需要用户审核的事项。
5. 检查下方的交接准备情况。 若已满足要求，则可将该阶段安全地交接给新的对话。是否实际开启新对话由你酌情决定（见下方的分块处理大型迁移）；若继续使用当前对话，只需接着处理即可。

原因： 检查清单能避免 Agent 忽略某些事项，例如未将数据集合加入 collections_config、未为引用的数据文件添加 data_config 条目、专注于页面构建器区块时漏掉博客/详情页的可编辑区域，以及数组未关联到结构定义。TaskCreate 会让这些疏漏显现出来。

阶段交接准备情况

这些条目定义了一个阶段在什么条件下才适合由新对话安全接手。它们不是单次对话中的壁垒——按照上文第 3 步所述，跨阶段修复仍然可以进行。设置这些条件，是为了让分块迁移的后续运行能够从干净的起点开始。

阶段完成后	交接准备就绪的条件……
1. 审计	.cloudcannon/migration/audit.md 已存在，包含普查表，并列出每个集合和每个页面路由。已评估分节阈值（见下文）；如果达到阈值，.cloudcannon/migration/plan.md 已存在。
2. 配置	cloudcannon.config.yml 通过已发布的 JSON schema 验证（IDE 中没有红色波浪线）。审计中的每个集合都有一个 collections_config 条目；每个被引用的数据文件都有一个 data_config 条目。已编写 .cloudcannon/migration/configuration.md。
3. 内容	阶段 2 的所有结构性内容变更均已反映到文件中。npm run build（或项目对应命令）成功。已编写 .cloudcannon/migration/content.md。
4. 可视化编辑	审计普查中标记为“需要可编辑区域”的每个分区都已接入，或已记录未接入的理由。registerComponents.ts 已注册封装分区中使用的每个组件。已编写 .cloudcannon/migration/visual-editing.md。
5. 构建和测试	本地生产构建成功。用户已完成 CloudCannon 端的验证（预览、行内编辑、保存到 Git）。已编写 .cloudcannon/migration/build.md。

大型迁移分块处理

迁移可以在一次对话中端到端完成，但在较大型的网站上，上下文会逐渐填满——当 Agent 需要通过很长的对话记录回想早期阶段的决策时，后续阶段（尤其是阶段 4：可视化编辑）的质量会下降。分块到新的对话中处理，可以避免这种情况。

分块处理只是建议，不是硬性规定。 Agent 不会在阶段之间_停止_——它会告诉用户“上下文已过长；可以考虑为阶段 N 开启新对话”，然后由用户决定。如果用户选择在同一次对话中继续，也完全可以。

何时建议开启新对话

在第 1 阶段结束时，根据 .cloudcannon/migration/audit.md 评估以下规模阈值：

信号	阈值	来源
页面总数	> 30	Audit § Pages and routing
硬编码的 .astro → YAML 转换	> 15	Audit 人口普查表中建议使用 page-builder 或固定架构集合的行
不同集合的数量	> 5	Audit § Content collections + 人口普查中新建的集合

如果有任意 2 项阈值被触发，请使用下方模板编写 .cloudcannon/migration/plan.md，然后建议用户在新的对话中运行后续阶段。第 4 阶段（视觉编辑）最消耗上下文，因此最可能需要从新对话开始。

结构	适用情况
纵向（按集合）	页面构建器页面或独特结构的集合占主导——每个单元都有自己的架构和视觉编辑决策
横向（按阶段）	集合大多较为统一——按集合重复进行的工作，每次采用一种思路会更有帮助

.cloudcannon/migration/plan.md 模板

# Migration plan

## Sizing

- Total pages: <n> (threshold >30: <tripped|ok>)
- Hardcoded → YAML conversions: <n> (threshold >15: <tripped|ok>)
- Distinct collections: <n> (threshold >5: <tripped|ok>)
- Tripped: <count>/3 → <chunked recommended|single-pass fine>

## Shape (if chunking)

<vertical|horizontal> — because: <one-line reason>

## Chunks

Each chunk is intended as a single agent run, ideally in a fresh conversation
once context is heavy. The agent reads `.cloudcannon/migration/audit.md` + this file + the
listed phase doc, then works the listed scope.

| #   | Scope                            | Phase(s) | Inputs                     | Output artefact                           |
| --- | -------------------------------- | -------- | -------------------------- | ----------------------------------------- |
| 1   | <e.g. all collections — config>  | 2        | audit.md                   | cloudcannon.config.yml + configuration.md |
| 2   | <e.g. blog collection — content> | 3        | audit.md, configuration.md | content.md (blog section)                 |
| 3   | <...>                            | ...      | ...                        | ...                                       |

## Global decisions locked in chunk 1 (do not revisit)

- Collection URL patterns
- Shared structures (`_structures`)
- Snippet configs (if MDX/inline HTML)
- `registerComponents.ts` setup

恢复工作概要（粘贴到新对话中）：“阅读 .cloudcannon/migration/audit.md、.cloudcannon/migration/plan.md，以及为区块 N 列出的阶段文档。处理区块 N 的范围。编写输出成果，然后停止。”

**重复工作 → 脚本规则：**迁移 2 个相同结构的条目后，为其余条目编写一次性脚本。手动转换 23 篇结构相同的文章会浪费令牌，还会放大出错概率。

脚本

确定性的迁移步骤已在 scripts/ 中编写为脚本。请在相关阶段之前或期间运行这些脚本。

迁移记录

所有文件都写入 .cloudcannon/migration/（位于 .cloudcannon/ 下，以免 CLI 将该文件夹识别为集合）：每个阶段一个文件（audit.md、configuration.md、content.md、visual-editing.md、build.md）；如果迁移分为多个区块，还要添加 plan.md。各文件对应的检查点请参阅上文的各阶段工作流。

交接与验证

测试范围

检查	负责人
本地构建（npm run build 或 package.json 中定义的其他命令）	Agent
构建、grep、小型脚本、检查 dist/	Agent
在 CloudCannon 中进行保真度检查（预览、内联编辑、保存到 git）	人工

与其在 Agent 会话中启动长期运行的开发服务器或进行繁重的端到端测试，不如优先请用户运行 CloudCannon 验证。

何时结束与用户的协作

在完成有实际意义的区块后结束，而不是每做完一个小改动就结束。至少应在第 5 阶段（构建与测试）完成首次完整迁移后结束。如果用户提前停止（例如只完成配置），则在该里程碑交接。

如何说明

简洁直接：

1. 简要总结所做的更改。
2. 提供用户可执行的检查清单。
3. 明确提出一项反馈请求。

避免空洞的客套话（“如果需要任何帮助，请告诉我”）。感谢对方检查一次即可。

请用户验证的内容

• 本地构建 — 项目实际使用的构建入口，而不是不完整的命令。如果失败，请粘贴完整的错误输出（命令、退出代码、stderr 的最后约 30 行）。
• 已运行的检查 — 用一行说明，避免用户重复工作。
• CloudCannon（人工） — 在托管环境中确认：
  • 可在具有代表性的页面预览中编辑内联文本区域
  • 点击图像区域会打开图像选择器
  • 数组区域会显示添加／移除／重新排序控件（已接入数组的区域）
  • 跨文件可编辑项（@file、共享局部模板）会更新预期的源文件
  • 保存的更改会写入 Git 中预期的文件

请用户反馈的具体内容

具体信息：运行的确切命令、远程构建失败时的 CloudCannon 构建日志片段、编辑器行为异常时的页面 URL 和点击操作，或简要说明与预期不符之处。

迭代

最后用一行邀请用户进行下一轮——运行完这些检查后，请回复任何失败情况或异常行为。

命名约定

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

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

已知问题的交叉参考

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

主题	负责人
对静态页面进行分类（可编辑源文件的页面、页面构建器页面或集合）	astro/audit.md § 静态页面分类
home.md 与 index.md、单项集合	astro/page-building.md § 常见错误
共享 UI（CTA 横幅、页脚、分享区块）	astro/cc-friendly-conventions.md § 共享 UI 处理表
多模式集合（使用 z.union 的 pages）	../cloudcannon-configuration/astro/configuration.md § 模式
配置语法幻觉（错误的键/类型）	cloudcannon-configuration § 常见无效键
尽管使用了 prose prose-lg 类，Markdown 正文仍显示为无样式文本——没有标题字号、列表项目符号或链接颜色	未安装或未注册 @tailwindcss/typography。Tailwind 4 需要在主 CSS 中（@import "tailwindcss"; 之后）添加 @plugin "@tailwindcss/typography";。两行修复：npm install @tailwindcss/typography + 添加 @plugin 指令。

常见错误

借口	实情
“这个网站很简单，不用做审查”	审查能及早发现结构问题。跳过审查意味着要到配置过程中才发现问题。
“我最后再看检查清单”	开始每个阶段之前，都要先阅读检查清单。它会告诉你该以什么为目标。
“内容重组可以以后再做”	如果缺少某个字段会阻碍配置，就现在补上。各阶段是依次推进的，并非互不相关。
“视觉编辑是可选的，所以我会跳过”	对编辑者而言，这是价值最高的阶段。只有用户明确提出要求时，才能跳过。
“构建通过了，所以就完成了”	构建通过不代表编辑器能正常工作。用户必须在 CloudCannon 中进行验证。
“我会把主页文件叫作 home.md——这个名字更能说明用途”	CloudCannon 会根据 slug 解析 URL；home.md 配上 url: "/[slug]/" → /home/。请使用 index.md，这样 Astro 会将 slug 折叠为 /。
“这是硬编码的，所以只有开发者能编辑”	只要编辑者能在页面上看到内容，就必须能编辑它。具体方式取决于页面：共享 UI（CTA 横幅、页脚、分享区块、作者卡片）→ 数据文件；包含 2 个或更多区块的独特布局页面 → pages 集合条目，并使用页面构建器；长篇正文页面 → 使用固定架构的集合，并包含 Markdown 正文。data-editable="source" 仅适用于长篇正文，不能作为任何单次字符串的默认方案。请参阅 astro/cc-friendly-conventions.md § 共享 UI 处理表 和 astro/page-building.md § 何时使用页面构建器。
“这个页面很独特，所以应该允许直接编辑源文件”	包含 2 个或更多区块的独特布局页面应放入 pages 集合，并使用页面构建器架构。直接编辑源文件仅适用于长篇正文。请参阅 astro/audit.md § 静态页面分类。
“我会创建一个只有一条记录的 homepage 集合”	使用一个 pages 集合，并将 index.md 作为其中一条记录。再添加 our-team.md、about.md 等更多记录。CloudCannon 集合支持在同一个集合中使用多个架构——既可以通过 schemas: 配置，也可以通过 Astro 内容配置中的 Zod z.union 实现。请参阅 ../cloudcannon-configuration/astro/configuration.md § 架构。
“这几页用页面构建器太复杂了”	对于包含多个独特布局页面的网站，页面构建器是默认方案。成本只是添加一个 [...slug].astro 全匹配文件和一个 BlockRenderer——这两项工作都是机械性的。这样做的好处是编辑者可以在无需工程支持的情况下添加新页面。