Hexo 博客无法复制 Markdown 本地图片？我写了一个插件
不知道现在大家写博客、文章还多不多，我一直在用 Obsidian + Markdown 写文章，然后用 Hexo 生成静态站点发布到 GitHub Pages，绑定到域名 xiaoming.io。
几年前我写过一篇文章，分享我是怎么构建笔记和博客系统的。
构建自己的笔记博客系统（程序员版） | 搬砖的小明
遇到问题
最近我在 Obsidian 里面用了一个新插件，它会把我本地的图片转成 WebP 格式保存。这样能大大节省存储空间，图片画质也还不错。
用了 WebP 之后，我发现原先那套发博客的代码只支持JPG、PNG、GIF，没有正常把 WebP 图片复制到发布目录里。
我的第一反应是让 Codex 直接帮我解决这个问题，它 Debug 了半天，没有什么进展，看来还是需要我人工参与一下。
我又重新研究了一下 Hexo，已经很多年没研究它了。之前它有个问题，在本地写 Markdown 时，如果用相对路径引用本地图片，在有些情况不会把图片复制到public目录。
几年前，为了解决这个问题，我魔改了 Markdown 的渲染器，也就是hexo-renderer-markdown-it。在它解析完图片以后，我会把每一张图片都复制到固定目录，同时修改渲染的图片 URL 让其对应上。
当时之所以这么做，是因为我发现 Hexo 本身的 API 不会把每个 post 里的图片都暴露给我。为了拿到一篇 Markdown 里所有图片的路径，我就不得不在渲染器里插一段自己的代码，来实现这个效果。
但这种实现思路非常不好，耦合性太强。我改了现有渲染器以后，只要渲染器一更新，我又得重新改。这么多年来，我一直用的都是旧版本渲染器，没有更新。
最近我又看了一下，时隔多年，Hexo 还是没有原生很好的解决这个问题。尽管它有一个post_asset_folder参数，但这个参数只支持和 Markdown 文件同名的文件夹里的图片上传，也就是推荐在 Hexo 里面创建 Markdown，这太局限了。
https://hexo.io/zh-cn/docs/asset-folders
我也尝试在网上找现成插件，确实有一些插件支持这个功能，例如hexo-asset-image，但这个项目已经无效并且不维护了。有人Fork了一个版本修复，但是看起来和我想要的效果不太一样。
决定重新开发（第一版）
所以我决定让 Codex 帮我开发一个。我本来不知道这件事会不会很复杂，没想到 Codex 直接帮我写了一个不到 100 行的 script，放进项目里以后，图片确实就能复制了，比我原先的实现优雅很多。
Codex 的实现思路很直接，就是拿到 Markdown 源文件，然后用几个正则表达式去找里面所有图片，再把它们复制到目标目录。
其实当年我一开始想到的也是这种方式。正则表达式比较难写，担心写错，识别出错误图片或者漏掉，所以当时就直接走了魔改 Markdown 渲染器这条路，快速把问题解决了。
但在今天，AI 写代码已经这么强了，让 Codex 直接实现一个新的插件，反而是一个更快、更简单的办法。
于是我把这个插件发布到了 NPM 上，也把我原来那个魔改插件去掉了，重新改回原版的 Markdown 渲染器，并且升级到了最新版。
后来我又去 Hexo 的 GitHub 主页看了一下，到现在还是一直有人提这个问题。我把这个插件网址回复在了那个 GitHub Issue 里。不知道这些提 Issue 的人现在还在不在用 Hexo 写博客，还是已经迁移到别的工具上了。
发现更多问题（第二版）
当我实际用这个插件时，发现它对图片的判断还是太简单了。Markdown 里引用图片有很多种情况。
大概有这么几类：
相对路径，比如当前目录、子目录，或者父目录里的图片
绝对路径，比如以斜线开头的 Linux 路径，或者 Windows 上带盘符的路径
不是本地文件路径的情况，比如
data:这种 Base64 形式、#开头的路径，或者http、https这种链接
我去和 Codex 讨论，它只处理了https链接等场景，还有一些场景都没有处理。
于是我就和 Codex 继续讨论，把我想到的场景都补充进去了，也写了针对这些场景的测试代码。
写 test 也有一些细节。因为这是一个 Hexo 插件，理论上最彻底的测试方式，应该是端到端测试：准备一个真实的 Hexo 环境，放一些测试用的 Markdown 文件，运行插件和编译过程，再判断处理结果对不对。
但 Codex 认为这样做会依赖 Hexo 的版本，太重了，比较容易出现兼容问题。所以它建议我用集成测试：Mock 一个假的 Hexo 环境调用整个插件，判断它是不是按照设计的方式工作，有没有准确复制 Markdown 文件里引用的图片。
当时我觉得 Codex 说的有道理，集成测试也就够了，因为主要是测试这些格式的解析逻辑。
于是第二版就发出来了。
更全面系统的设计（第三版）
在我写这篇文章的时候，又去网上搜了一些相关的资料，包括 Hexo 官方文档，我发现事情没有这么简单。
例如 Hexo 里relative_link的配置选项可能会导致渲染不一样，还有些用户可能会在图片文件名里有特殊字符等。
我觉得有必要用更系统化的方式去实现这个工具。
在之前，我用 AI 做过好多个小工具，说实话，这个应该是真实解决现实问题当中功能最简单的一个项目。
但是正因为它是最简单的一个，我反而可以更清晰地学习如何用 AI 开发项目。因为它每一个步骤都相对简单，我可以把重点放在思考开发流程上，而不是让注意力陷入过多设计实现细节里出不来。
同时它也不是简单到完全不需要思考的程度，它也在解决一个有多种可能分支的现实问题，有一定的研究价值。
1、确定核心目标
首先是理清这个项目的核心目标。核心目标的重点不只是这个项目要做什么，还要关注这个项目不做什么。
这个项目的名字叫hexo-relative-post-image，顾名思义，它的核心目标应该是只处理相对路径引用的图片文件。如果是绝对路径，我们直接不处理，并且在 log 里面报一个 warning，通知用户自行处理。
我们的设计思路是，只做图片复制，不去干涉 Markdown 渲染成 HTML 的过程。
2、确定调研方向并调研
确定了这个核心目标以后，我们需要对 Markdown 有关的东西进行足够深入、系统的调研。
这里面包括 CommonMark 对 Markdown 语法的规定是什么样的、支持什么样的图片引用方式。
现有的 marked 和 markdown-it 这两个渲染器是怎么实现 Markdown 图片渲染的，这两个渲染器在 Hexo 上又有什么样的图片相关的配置参数。
目前已有的 Hexo 渲染器，用户都报了什么样的 Issue，能从这个 Issue 里面学习到哪些兼容性问题。
我让 AI 把这些调研来源和结果都放在了 Reference 文件中。
3、Spec 开发
在这个调研完成以后，就需要做一个详细的需求文档，一般称为 Spec (Specification，产品规格)。这个 Spec 里面除了有项目的核心目标，还有从调研结果学来的东西，有哪些语法格式需要考虑，有哪些可能的兼容性问题需要处理。
根据我们前面定的核心目标，有些兼容问题是可以在插件里处理的，而有些兼容问题则是和我们的设计目标冲突的，应该不做处理，而是直接报错抛给用户，例如绝对路径引用图片。
一开始我并没有把这个项目当成一个正经项目去做，只是从一个 100 行的小脚本慢慢补全了，所以前面的版本也没有 Spec。但是现在既然要更系统地实现这个项目，Spec 就是必要的。
一开始都是跟 AI 用几句话来描述需求，但是当需求的边界条件、各种分支越来越多，几句话就描述不清楚了。如果下次需要 AI 修改维护，Spec 就是最重要的依据。聊天结束了，上下文就没了，而 Spec 是以文件形式保存在项目里的，一直在。
4、代码实现
有了这个 Spec 以后才是写代码，代码分为插件本身的实现代码和测试代码两块。
实际上这个插件本身的代码量并不是很大，只有一个几百行的文件。但它的文档以及它的测试代码反而比实现代码更复杂。
5、测试
在测试代码的实现上，之前的集成测试也满足不了需求了，因为现在已经明确发现了不同的渲染插件可能也会有兼容性问题。
所以我让 AI 又加了真正的端到端测试，直接调用 Hexo 去验证兼容性问题。
6、README 文档
最后，还有一个精简的 README，是中英双语版的，为了更加国际化，默认英文版。README 分为两块。
1、给普通用户看的，要告诉用户怎么配置这个项目，支持什么场景，什么是不支持的。
2、给想要参与开发项目的人和 AI 看的。会介绍环境配置、开发约定、具体的发布流程。
实际上我的开发和发布都是让 AI 完成的，这个时候文档就非常重要了，如果没有文档，AI 没办法每次都按照固定的流程开发和发布项目，到时候就乱了。
一点思考
这是一个很简单的小项目，用 AI 帮忙写也很轻松。但你会发现，即使是这样的小项目，也还是需要人工参与，而且人工参与的程度并不低。
这不是我不会用 AI，而是很多实际问题本身就带着一堆隐性的背景知识。
比如 Markdown 引用图片这件事，由于Markdown编辑器五花八门，用户真的会用各种奇奇怪怪的方式去写，不只是标准语法，还可能有 HTML 标签、文件名有特殊字符、不同语法格式、网络图片，甚至不同渲染器还有自己的扩展。这些东西本身就没有一个固定范围。
AI 默认不会把这些情况全都想一遍，它一般只会给你一个“常见写法”的方案，而不会一上来就帮你把所有边界情况都覆盖掉。
如果要让 AI 自主探索所有可能的情况，复杂度可能会指数级增加。
这时候人的作用就体现出来了。我会用自己的经验去引导 AI，比如我会想到要看现有生态，比如 CommonMark 语法规范，Marked、Markdown-it 这些主流渲染库，相似插件以及它们的 Issue 里别人踩过的坑。
这些东西 AI 不是查不到，而是如果你不说，它通常不会主动意识到“这一步是必要的”，也不会自己把这些上下文串起来。
本质上就是，有些问题需要很大的上下文才能想清楚，而这些上下文很多是隐性的，不是直接搜就能出来的。
人能做的，是主动把这些上下文补上，确定问题范围；AI 更擅长的是，在这个范围里面把事情做快、做全。
那么利用 AI 开发项目的过程就是这样的：
1、我会利用我的知识经验，引导 AI 去做调研，确定问题范围，让 AI 写 Spec，写完了我再核查，再让它修改，直到 Spec 达到我比较满意的程度。
2、让 AI 根据 Spec 把代码实现出来。理论上只要 Spec 写得足够完备，代码实现就已经不重要了，不需要太多人工参与就能被 AI 自动完成。甚至可以把 AI 当成编译器来看待，AI 把 Spec 编译成代码，就像过去编译器把高级语言编译成机器码一样。
3、在编译过程中，如果由于 Spec 写的有硬性的逻辑问题导致编译报错，或者最终运行出来的效果和设想的不一样，我不会单独去干预代码，而是去完善 Spec，然后重新编译成代码，可以是增量编译的过程，不用全部重写。
整个项目的维护核心，从过去的代码，开始转向 Spec。用 AI 的话来说，Spec 是 Single Source of Truth。Spec 可能需要花很长的时间去开发，并且它是人工参与程度最高的文件。
之后无论是实现代码，还是测试代码，还是 README，只要有不对的，就应该从 Spec 里面找参考依据。每次修改项目的时候，都应该先改 Spec，然后才是代码和 README。
项目链接
如果你也在用 Hexo，遇到类似问题没解决，可以留意一下这个插件。
我发现似乎还有人在用我以前开发的那个版本的 Markdown 渲染器，因为我看到 NPM 上还有下载量。我把原先那个项目标记成了 Deprecated，也链接到了这个新项目。
如果你是单纯想了解这个项目的 Reference、Spec 和 Test 是怎么写的，也可以在项目中看到。
这个项目的 GitHub 主页在这里：
https://github.com/jzj1993/hexo-relative-post-images
如果觉得文章有帮助，欢迎分享转发，也欢迎关注我的公众号“搬砖的小明”，及时获取更新