一、起因：一个文件夹引发的思考

前两天发博客的时候我突然意识到一件事：我这套 Hexo 博客环境，从安装依赖、配置主题、写文章到部署上线，整个流程已经被 AI 跑得很顺了——顺到我自己都快要记不住具体命令了。

然后我就冒出一个想法：既然这套东西对我来说已经是”一键”的，为什么不把它打包出来，让别人也能一键拥有？

于是有了这个项目：HexoBlogStarter —— 一个开箱即用的 Hexo 博客工具包，内置 Fluid 主题，clone 下来改 3 处配置，10 分钟就能拥有自己的博客。

但它真正有意思的地方不在”又一个 Hexo 模板”，而在于它的设计思路。

二、双通道设计：README 给人看，AGENTS.md 给 AI 看

这个仓库里有两份”说明书”：

  • README.md —— 传统的，给人类看的教程：四步上手、目录结构、FAQ
  • AGENTS.md —— 给 AI Agent 看的操作手册：环境怎么装、文章怎么发、故障怎么排查、红线是什么

为什么要专门给 AI 写一份？因为这是我上一篇文章里那个观点的又一次实践：Markdown 正在同时成为人和 AI 的共同语言。

拿到这个仓库的人有两种用法：

1
2
3
4
5
6
7
# 玩法一：自己来
git clone https://github.com/luodeCoding/HexoBlogStarter.git
# 读 README.md，跟着四步走

# 玩法二：让 AI 来
# 把仓库丢给任意 AI Agent（Kimi / Claude / Cursor / GPT...）
# 说一句："读 AGENTS.md，帮我把博客搭好"

AGENTS.md 里我写了 AI 需要的全部上下文：关键文件在哪、每个任务的标净操作流程、发布前要确认什么、什么事情不许做（比如未获许可不许 deploy、不许删已有文章）。它本质上是一份”给 AI 的岗位说明书”。

我越来越觉得，未来开源项目的完整交付物应该是三件套：代码 + 人读的文档 + AI 读的文档。缺了第三样，就等于放弃了”AI 代劳”这个越来越主流的使用入口。

三、工具包里面有什么

1
2
3
4
5
6
7
8
9
10
11
HexoBlogStarter/
├── README.md      ← 给人：四步上手教程
├── AGENTS.md      ← 给 AI：完整操作手册
├── bin/           ← 4 个一键脚本
│   ├── 1-安装环境.sh
│   ├── 2-新建文章.sh
│   ├── 3-本地预览.sh
│   └── 4-一键发布.sh
├── _config.yml    ← 只有 3 处 TODO 要改
├── scaffolds/     ← 文章模板
└── themes/fluid/  ← 主题内置，离线可用

设计上有几个刻意的取舍：

  1. 主题直接打进包里。不依赖 npm install hexo-theme-fluid 或 clone 主题仓库，断网也能跑。代价是包大一点（zip 3.6M），换来的是零网络依赖的确定性。
  2. 脚本用中文命名。4-一键发布.sh 比 deploy.sh 对新手友好得多，编号的顺序就是使用顺序。
  3. 配置只留 3 个 TODO。_config.yml 里把需要改的地方全部标了出来，其他的都给了合理默认值。配置项越少，放弃的人越少。
  4. 发布脚本带防呆。没填仓库地址直接运行发布，会拦住你并提示去哪改，而不是抛一串 git 报错。

四、踩到的坑：Hexo 的保留目录

打包过程中实测踩了一个值得记录的坑：我一开始把脚本放在 scripts/ 目录，结果 Hexo 构建时报了一堆 Script load failed。

查了一下才发现：**scripts/ 是 Hexo 的保留目录，它会尝试把里面的每个文件当作 JS 插件加载**——我的 shell 脚本被当成 JavaScript 执行，自然全线报错。改名为 bin/ 后解决。

另一个坑是 package.json 里必须保留 "hexo": { "version": "x.x.x" } 字段，否则 hexo-cli 识别不了站点，hexo generate 直接给你打印帮助信息，什么也不生成。

这类”约定大于配置”的隐式规则，官方文档里散落在各个角落，只有亲手打包一次才会撞上。这也是我觉得这类 starter 项目存在的意义：把别人撞过的坑提前填平。

五、写在最后

前两篇文章我聊了两个观点：AI 时代”细心、负责、钻研”比开发经验更值钱；Markdown 文档正在成为人和 AI 的共同语言。

这个项目算是把两个观点落到了地上：

  • 整个工具包是我和 AI 协作完成的，但每一版发布前我都要求实测验证——于是才撞上了 scripts/ 保留目录这个坑。这就是”把关”的价值：AI 负责速度，人负责正确性。
  • 而 AGENTS.md 这份”给 AI 看的文档”，让这个项目从”被人用”扩展到了”被 AI 用”。开源的受众，从今天起多了一整个物种。

项目地址在这里，欢迎 star、fork、提 issue：

👉 https://github.com/luodeCoding/HexoBlogStarter

如果你一直想开个博客但懒得折腾环境，这次真的没有借口了。

相关阅读：


技术分享  

AI 效率工具 Hexo 开源

本博客所有文章除特别声明外，均采用 CC BY-SA 3.0协议 。转载请注明出处！