把一个文档站迁移到地道的 Blume，需要 codemod 无法替代的判断力：哪些已声明的导航应该变成文件夹，哪些组件应该变成指令，以及哪些东西在 Blume 里没有对应物。所以 blume migrate 把这件事交给一个编码 agent，它依据 Blume 的迁移手册来完成，你只需逐处审阅它的修改。
一条命令完成迁移#
在你要迁移的文档项目根目录里运行：
npx blume migrate fumadocs --codex把 fumadocs 换成你自己的框架，把 --codex 换成 --claude 即可使用 Claude Code。在 pnpm 12 上，要在 pnpm dlx 后面加 --allow-build=esbuild，因为 pnpm 12 未经批准不会运行 esbuild 的安装脚本。agent 会在你的终端里交互式打开，因此每一次修改都走它自己的权限流程。它就地工作，所以请从干净的工作区开始，并把整次迁移当作一个 diff 来审阅。
迁移来源#
写明你要从哪个框架迁移，或者留空、由 Blume 从项目自身的文件里检测。当你写明了某个来源、而项目看起来像另一个时，Blume 会给出警告，并继续使用你写明的那个：
| 来源 | 检测依据 |
|---|---|
mintlify |
docs.json 或 mint.json |
fumadocs |
source.config.ts，或 package.json 里的 fumadocs-core、fumadocs-ui、fumadocs-mdx |
docusaurus |
docusaurus.config.* |
starlight |
package.json 里的 @astrojs/starlight |
nextra |
package.json 里的 nextra |
每个来源在手册里都有各自的映射参考。用别的东西构建的站点同样能迁移：不写来源地运行该命令，agent 会先给整个仓库做一份清单，然后依据手册里的通用规则动手。
agent 会做什么#
agent 会按手册的工作流，从来源的配置一路走到一次通过的构建：
- 写入
blume.config.ts，只映射你来源里声明过的部分，其余交给 Blume 的默认值覆盖。 - 把内容重组为文件系统导航，把按文件夹排序的文件（Fumadocs 的
meta.json、Nextra 的_meta）转成meta.ts。 - 重写页面：frontmatter 转成 Blume 的 schema，callout 提示框转成指令，图标换成 Lucide，代码片段改为内联。
- 为每一个改动的 URL 添加一个重定向，这样不会有任何链接失效。
- 把
package.json的脚本指向blume dev和blume build，并用blume替换掉旧框架的依赖。 - 反复运行
blume build和blume validate，直到两者都通过。
最后它会给出一份总结，说明哪些内容被迁移了、被丢弃了，或只是做了近似处理 —— 比如页脚链接或导航栏按钮在 Blume 里没有对应物 —— 这样你可以逐项决定怎么处理。
其它 agent#
不加 --codex 或 --claude 时，该命令会报告它检测到的来源，打印手册的路径 —— 即随包一起分发的 blume-migrate skill —— 然后不做任何修改就退出。把那个 SKILL.md 指向任意其它 agent，或者用它打印出来的命令把该 skill 安装到你的 agent 查找 skill 的位置：
npx skills add haydenbleasel/blume --skill blume-migrate先做对比#
常见问题里把 Blume 与 Mintlify、Fumadocs 等工具逐项对比，并说明了迁移到 Blume 时每个框架的映射关系。