夜雨聆风代码写完，只算把事情做了一半；文档建起来，这件事才算完整。
个人开源项目的宿命，大多是这样的：代码写完，发一个 README，心里默念「文档以后再补」—— 而「以后」永远不会来。不是不想补，是完整性太贵。一个像样的文档站，意味着选型、配置、部署、CI、内容规范、校验脚本……每一项都得查资料、踩坑、返工。于是索性砍掉，美其名曰「聚焦核心」。
前面介绍过 aifei-go —— Java 版 Aifei 的 Go 移植。它的处境比一般项目更尴尬：这是一个宣称「为 AI Coding 而生」的框架，Java 版有官方文档 aifei.cn/doc 摆在那里当基准，Go 版要是只有一个 README，多少有点打脸。而且这里还藏着一个顺理成章的推论 —— 既然是为 AI Coding 而生的框架，它的文档，本来就该由 AI 来写。于是花了两天，把文档站建了起来：https://crazy-airhead.github.io/aifei-go/。
完整性的坑，AI 都记得
技术上没什么新鲜事：VitePress + pnpm + GitHub Actions，push 到 master 自动构建、发布到 gh-pages。新鲜的不是技术，是细节有人替你想着。随手摘两段：
- name: Checkout（完整历史，供 lastUpdated 读取时间）uses: actions/checkout@v6with:fetch-depth: 0- name: Deploy to gh-pagesuses: peaceiris/actions-gh-pages@v4with:publish_dir: docs/.vitepress/dist# dist 是纯生成产物：单提交孤儿分支，保证删除的页面同步消失force_orphan: true
配置里的这些注释，本身就说明创建一个文档站不是一件容易的事情。没写进注释里的还有一堆：base 路径要配 /aifei-go/、head 里的 favicon 不会自动加前缀得写全路径、paths 过滤让只有 docs 变更才触发构建、concurrency 把排队的旧部署取消掉、sitemap 要配 hostname……但这些坑，每一个都是前人踩过的，AI 都记得。以前要花一个下午翻 issue 才能凑齐的事，现在是一轮对话。
先写「怎么写」，再写「写什么」
真正值得记的不是部署，是内容的生产方式。开工第一步，不是让 AI 写文档，而是先写「文档怎么写」—— 一份 docs/guide/_STYLE.md 写作规范。统一模板大纲（背景 → 架构 → 关键 API → 核心机制 → 配置集成 → 模块结构 → 总结）、风格规则（多用表格和代码块、交叉链接、信息密度要高），再加几条质量红线：
内容来源必须实际读取源码，不得凭记忆编造； 代码示例的类型名 / 方法签名 / 配置键必须与源码一致，逐项核实； 篇幅 300~500 行，完成后用 wc -l和grep自查行数与标题结构。
规范开头有一句：「本规范人与 AI 均适用」。人做决策，AI 生成 —— 落到这件事上，就是人定标准、立标杆（风格范例是那篇五百行的 data-isolate 文档），AI 读源码、照模板写。最后落地的，是二十五篇模块文档。这套招数其实是框架自己的招数：Just Service 用命名约定让 AI 稳定生成代码，_STYLE.md 用模板和红线让 AI 稳定生成文档，一回事。
抽卡之后，要有验收
规范把写作经验沉淀了下来，让下一篇的起点更高。但光有规范还不够 —— AI 的输出是基于概率的，「抽卡」式的不确定性不会因为换了任务就消失。git 历史里躺着证据：首次部署之后，紧跟一串提交 —— 更新 Logo、更新文档图、把 Actions 升级到 Node 24 运行时、修 Markdown 语法错误、修 index.md 语法错误。所以要有验收闭环：构建、校验、人工过目，一轮下来，概率性的输出才算变成确定性的成品。
最让我意外的是 scripts/check-mermaid.mjs。VitePress 构建时并不校验 mermaid 图表的语法，错了要到浏览器渲染时才暴露。这件事我没有让 AI 做，是它自己想到的：文档里有图、图会坏、坏了要在上线前发现 —— 于是有了这个脚本：jsdom 搭环境，调 mermaid.parse 把 docs 下所有 mermaid 代码块逐个校验，内部文件自动跳过。这种「想到你没让它想的事」，是完整性的另一个来源：人容易在「能用」的地方停下来；AI 不会累，也就没有「差不多得了」。
过程留痕，成品干净
仓库里有个 docs/issues/ 目录，编号归档了移植过程中发现的十九个缺陷：enjoy 的算术精度降级、for 循环迭代不了 map、内置指令缺失、db 缺方言……每一条都是留了案的复盘。这些记录通过 srcExclude 排除在发布站点之外 —— 对外的成品要干净，对内的过程要留痕。完整，不是把所有东西都端出去，而是该在的都在。
完整是长出来的
有了 AI 的帮助，让自己做事情更完整 —— 改变的到底是什么？不是 AI 会写文档了，文档它一直会写；是完整性的成本变了。以前文档、CI、校验、sitemap、孤儿分支，这些收尾活最劝退；现在它们的边际成本趋近于零，「能用」和「完整」之间的那段距离，走着走着就走完了。
你得知道「完整」长什么样—— 当然也不必一开始就知道。完整是在深入的过程中长出来的：每一步追问一句「还差什么」，追问多了，「完整」的认知自然成形。这两天下来，我对「完整」的理解，就比开工时具体得多。
最后是个自举：一个为 AI Coding 而生的框架，它自己的文档站，也是 AI Coding 做出来的。文档站的地址挂在那里，往后每一次 push，它都会自己生长。
人负责想要什么，AI 负责让它完整。
