用途
blume-migrate 是一个迁移技能，作用是把已有的文档站点仓库转换为符合 Blume 习惯用法的项目。Blume 是基于 Astro/Vite 的 Markdown 优先文档框架：把 Markdown/MDX 放入文件夹即可获得导航、搜索、主题、Open Graph 图片与组件库，无需应用样板代码。项目本身只拥有内容和一份 blume.config.ts，没有需要克隆的模板。
本技能的目标是产出「地道的 Blume 项目」，而不是逐字逐句的机械移植。迁移时需要阅读技能文件、检测来源框架、打开匹配的 references/<framework>.md 获取精确映射，并按工作流推进，最终报告所有被丢弃或近似处理的内容。
迁移理念
- 以地道的 Blume 为目标：优先使用文件系统推导的导航，而非穷举式显式 navigation.sidebar；优先使用 ::: 指令而非 JSX 提示块；优先使用 Blume 默认值而非在配置中重复声明。
- 每个字段都有默认值，{} 也是合法配置；只映射来源中显式声明的字段。若来源使用的是框架默认值，则不必写出。
- 丢弃没有 Blume 等价物的界面装饰并明确告知：导航栏 CTA、自定义主题、条件重定向、无法映射的图标等，都要报告给用户，而不是静默丢弃或伪造。
- 转换而非保留：Blume 的页面 frontmatter 模式是严格的，未知键会导致构建错误；仅来源专有的 frontmatter 键必须映射为 Blume 键或删除（并报告）。
主要能力
- 来源框架检测：依据配置文件与依赖识别来源框架。例如 docs.json / mint.json 对应 Mintlify；docusaurus.config.* 对应 Docusaurus；meta.json + fumadocs-* 依赖对应 Fumadocs；_meta.{js,ts,json} + nextra 依赖对应 Nextra；astro.config.* 调用 starlight({…}) 对应 Starlight；.vitepress/config.* 对应 VitePress，.vuepress/ 对应 VuePress；docus 依赖或 @nuxt-themes/docus 对应 Docus；mkdocs.yml 对应 MkDocs/Material for MkDocs；fern/docs.yml 对应 Fern；.gitbook.yaml / SUMMARY.md 对应 GitBook；book.toml 对应 mdBook；sidebars.yaml 或 @redocly/realm 系列依赖对应 Redocly；_order.yaml 或 rdme 对应 ReadMe；window.$docsify 或 docsify-cli 对应 Docsify；_config.yml 对应 Jekyll；<repo>.wiki.git 克隆对应 GitHub Wiki。其余情况按本文件的心智模型手工梳理。
- 托管仓库集成：若目标不是单一包文档目录（如 pnpm/Turbo 工作区、非 docs/ 内容布局、Vercel 部署），需读取 references/monorepo.md 完成集成步骤。
- 清点仓库：在改动前盘点配置文件、内容树、导航定义、片段/局部/包含文件、静态资源、OpenAPI/AsyncAPI 规范与 GraphQL 模式、重定向、i18n 语言、自定义组件与图标使用；区分声明项与默认项。
- 配置编写：使用 blume 的 defineConfig 编写 blume.config.ts，只映射已声明的字段。
- 内容重构：确定 content.root（默认 docs），用数字前缀排序、用 (group)/ 文件夹分组、必要时添加 meta.ts；来源已声明逐文件夹导航（如 Fumadocs meta.json、Nextra _meta.*）时应转为 meta.ts 并保留 title/icon/order/collapse。
- 页面重写：映射 frontmatter；将提示块 JSX 转为 ::: 指令（指令与 math/mermaid/package-install 围栏仅限 MDX，需要时把 .md 重命名为 .mdx）；重命名组件；把片段/局部转为 <include> 或内联；修正资源路径；重写内部链接（包括 OpenAPI/GraphQL 操作链接与 OpenAPI 描述内的链接）；为移动过的路由添加重定向；将图标名统一转为 Lucide（Blume 仅支持 Lucide）。
- 校验与报告：blume validate --strict 会报告旧站未检查过的片段引用，逐项修复或丢弃并报告。
使用方式
技能以工作流形式推进：检测来源框架并读取对应参考文件 → 清点仓库 → 编写 blume.config.ts → 重构内容 → 重写页面 → 添加重定向。部分来源配有 codemod 脚本，需先运行以完成确定性的机械转换，再人工处理剩余项。例如 Mintlify 使用 node <skill>/scripts/mintlify-codemod.mjs --write <content-dir>；Docus 使用 node <skill>/scripts/docus-codemod.mjs --write content；VitePress 使用 node <skill>/scripts/vitepress-codemod.mjs --write <srcDir>；MkDocs 先运行 node <skill>/scripts/mkdocs-codemod.mjs --write <content-dir>；Docsify、Jekyll、GitHub Wiki、Fern、ReadMe 等也各有对应脚本。<skill> 指包含 SKILL.md 的目录的绝对路径，需按实际读取位置替换，不是字面路径。
适用场景
需要把上述任一来源框架搭建的文档站点迁移到 Blume，并希望得到地道的 Blume 项目结构时使用。也适用于工作区、非标准内容布局或 Vercel 部署等需要额外集成步骤的场景。
限制
Blume 仅支持 Lucide 图标，不支持 FontAwesome/Tabler。Blume 的 frontmatter 模式严格，未知键会导致构建错误。Blume 没有基于 import 的包含机制（import Snippet from "…" 加 <Snippet /> 必须转为 <include> 或内联）。部分来源专有功能（导航栏 CTA、自定义主题、条件重定向、无法映射的图标等）没有等价物，会被报告而非保留。指令与部分围栏仅限 MDX。不同来源的重定向能力不同（如 Docsify 的哈希路由需要客户端脚本，GitHub Wiki 的旧 URL 无法重定向）。各来源的具体限制与映射细节见对应参考文件，本技能未展开的细节暂未提供。