用 AI Agent 完成 Hexo 主题迁移：从 Next 到 Butterfly 的全自动化实践

背景：一个繁琐到让人崩溃的任务

最近想给自己的 Hexo 博客换个主题。用了好几年的 Next 主题，虽然经典，但想换个更现代的风格。

看起来很简单对吧？但实际操作过的朋友都知道，Hexo 主题迁移是一个极其繁琐的过程：

配置文件长达 1000+ 行，需要逐项对比新旧主题的配置格式
功能映射复杂：Next 的 leancloud_visitors 对应 Butterfly 的 busuanzi，Next 的 reading_progress 对应 Butterfly 的 preloader
两个站点要同步：中英文站都要改，而且配置略有不同
Font Awesome 版本兼容：Butterfly 默认配的 FA 7.1.0 根本不存在于 cdnjs
YAML 格式敏感：缩进、换行符都可能导致配置失效

如果手动操作，估计要花一整天，而且很容易出错。

这次我尝试了一个不同的方式：让 AI Agent（Hermes）全程接管这个任务。

AI Agent 的工作流程

整个过程，AI Agent 自主完成了以下工作：

环境分析：检查当前 Hexo 版本（7.0.0）、Node.js 版本（v24.14.0）、两个站点的配置差异
版本调研：查询 GitHub API，获取最新 Hexo 版本（8.1.2）和 breaking changes
依赖升级：批量更新 hexo 及所有插件到最新版本
主题对比：分析 Next 和 Butterfly 的功能覆盖度，生成对比表格
配置迁移：将 Next 的 1000+ 行配置逐项映射到 Butterfly 格式
问题排查：
- 发现 FA 7.1.0 在 cdnjs 上 404，降级到 6.7.2
- 发现知乎图标需要 fab 前缀
- 发现英文站菜单路径错误
- 发现 GA、百度统计、站长验证等关键配置丢失
测试验证：构建测试、本地预览服务器、检查 HTML 输出
代码提交：自动生成 commit message 并 push

关键技术点

1. Font Awesome 版本兼容性问题

这是最隐蔽的一个 bug。Butterfly 主题的 plugins.yml 配置了 FA 7.1.0：

1
2
3

fontawesome:
  name: '@fortawesome/fontawesome-free'
  version: 7.1.0

但 cdnjs 上根本没有这个版本！导致所有品牌图标（GitHub、StackOverflow、知乎）都不加载。

AI Agent 通过以下步骤定位问题：

检查生成的 HTML，发现加载的是 FA 7.1.0
请求 cdnjs API，确认 7.1.0 返回 404
测试 FA 6.7.2，确认包含所有需要的图标
在配置中覆盖 CDN 地址

2. YAML 配置迁移的陷阱

Hexo 的配置文件是 YAML 格式，对缩进和换行符非常敏感。AI Agent 在迁移过程中遇到了几个问题：

CRLF vs LF：Butterfly 默认配置是 CRLF 换行，用 sed 替换时匹配失败
重复键：patch 工具导致 scroll_percent 出现两次
值丢失：YAML 缩进不对导致配置值没有正确写入

最终用 Python 直接操作文件内容才解决了这些问题。

3. 多站点同步

中英文站的配置大部分相同，但有几处差异：

英文站的 language 需要改为 en
英文站的菜单需要指向中文站
英文站的 Valine placeholder 需要用英文

AI Agent 自动识别这些差异并分别处理。

效果对比

指标	手动操作	AI Agent
耗时	4-8 小时	30 分钟
出错率	高（容易遗漏配置）	低（系统化检查）
问题排查	需要逐个 Google	自动定位根因
代码提交	手动写 commit message	自动生成

AI Agent 的优势

这次实践让我深刻体会到 AI Agent 在这类繁琐、重复性工作中 的巨大优势：

1. 系统化思维

AI Agent 不会像人一样”想到哪改到哪”。它会：

先分析当前状态
制定完整计划
逐步执行并验证
发现问题及时修复

2. 跨领域知识

主题迁移涉及多个技术领域：

Hexo 配置
Font Awesome 版本管理
YAML 格式处理
Git 工作流
前端资源加载

AI Agent 能够在这些领域之间自由切换，而人类开发者通常只精通其中一两个。

3. 持久注意力

人类在处理 1000+ 行配置文件时，注意力会逐渐下降，容易遗漏。AI Agent 不会疲劳，每个配置项都会被检查到。

4. 自动化验证

AI Agent 不仅会修改配置，还会：

运行构建测试
启动本地服务器验证
检查 HTML 输出
确认关键配置生效

适用场景

基于这次经验，我认为 AI Agent 特别适合以下类型的工作：

配置迁移：不同系统之间的配置格式转换
依赖升级：批量更新多个包并处理兼容性问题
代码重构：大规模的代码格式调整
文档整理：从多个来源整合信息
环境搭建：新项目的初始化配置

局限性

当然，AI Agent 也有局限：

创意性工作：UI 设计、文案撰写等仍需人类主导
业务决策：是否升级、选择哪个主题等决策需要人类判断
复杂调试：某些运行时问题需要人工介入

总结

这次用 AI Agent 完成 Hexo 主题迁移的实践，让我看到了 LLM（大语言模型）在软件工程领域的巨大潜力。

AI Agent 不是来取代开发者的，而是来增强我们的能力。它把我们从繁琐、重复的工作中解放出来，让我们能够专注于更有价值的事情。

如果你也有类似的”体力活”，不妨试试让 AI Agent 来帮忙。你会发现，AI 辅助开发 不是未来，而是现在。

推荐订阅源

Mobility