已有说明
AI 摘要只在构建期生成
浏览器只负责展示 front matter 中已经存在的摘要，不会在访客打开文章时请求 AI 接口。API Key 不会进入前端。
之前写文章，通常是打开本地编辑器，找到 content/posts，新建一个 Markdown 文件，再手动检查 front matter、图片路径和构建结果。这个流程没有什么问题，只是每次想在别的电脑上改两句话，都要先找到仓库，再把环境准备好。
Pages CMS 解决的不是“怎么写 Markdown”这个问题，而是把这件事搬到了一个可以直接登录使用的网页里。文章仍然保存到 GitHub，Hugo 仍然负责构建，Cloudflare Pages 仍然负责发布，只是中间多了一个更适合写作的入口。
这篇文章把整个流程记下来：怎么连接仓库，怎么写第一篇文章，什么时候要切到 Source mode，以及文章保存以后，AI 摘要是怎么自动生成的。
这个项目没有把 CMS 当成一个独立的数据库。Pages CMS 改的还是仓库里的 Markdown 文件，保存后直接提交到 main 分支。
所以，一次正常发布大致会经过这些步骤：
main。Deploy to Cloudflare Pages。ai_summary。Pages CMS 不需要再点击一个单独的“部署”按钮。文章提交成功后，后面的事情交给 Actions 就可以了。
打开 Pages CMS，使用 GitHub 登录。第一次进入时，需要授权 Pages CMS 访问 GitHub 仓库，按页面提示完成即可。
登录之后，选择博客对应的仓库：
进入仓库后，确认当前查看的是 main 分支。这个项目采用直接提交 main 的方式，没有另外维护用于写作的 edit 分支。
仓库根目录的 .pages.yml 是 Pages CMS 的配置文件。当前项目只开放两个内容集合：
content/posts；content/changelog。第一次连接后，先确认这两个集合能正常显示。如果看到了 _index.md，不要把它当成普通文章编辑。它是 Hugo section 的索引文件，负责文章列表页的标题和描述。
如果只是编辑已经有 ai_summary 的文章，CMS 本身不需要 AI Key。但新文章发布时，Actions 可能需要调用摘要接口，所以 GitHub 仓库里要提前配置好变量。
进入 GitHub 仓库的：
在 Secrets 中配置：
| Secret | 用途 |
|---|---|
AI_SUMMARY_API_KEY |
AI 摘要服务的 API Key |
CLOUDFLARE_API_TOKEN |
部署 Cloudflare Pages |
CLOUDFLARE_ACCOUNT_ID |
Cloudflare 账户 ID |
AI_SUMMARY_API 也可以作为 Secret 配置，用来覆盖默认的 OpenAI 兼容接口地址。
在 Variables 中可以配置：
| Variable | 用途 |
|---|---|
AI_SUMMARY_MODEL |
摘要使用的模型 |
AI_SUMMARY_MAX_INPUT |
发送给模型的最大正文长度 |
AI_SUMMARY_PROMPT |
自定义摘要提示词 |
密钥只放在 GitHub Secrets 或本地 .env，不要写进 .pages.yml、hugo.yaml、文章 front matter 或正文代码块里。
进入 Posts / 文章 集合，点击新建文章。这里的字段基本对应文章 front matter。
title：文章标题。slug：文章地址使用的小写英文标识，只允许小写字母、数字和连字符，例如 pages-cms-writing-guide。date：发布日期和时间，站点时区是 Asia/Shanghai。description：文章列表、搜索和分享时使用的描述。cover：可以填写 /img/... 的本地图片，也可以填写外部 HTTPS 图片地址。categories、tags、series：按需要填写数组。toc：文章较长、需要目录时打开。comment：是否开启评论。locate：文章位置说明，不需要时可以留空。recommend：只有确实要推荐文章时才打开。新文章的文件名由 slug 生成：
这个博客的文章链接由 Hugo 配置为 /p/:slug，所以 slug 不是一个随手填写的内部字段。文章发布以后，尽量不要再改它，否则公开 URL 也会跟着变化。
标题、段落、列表、普通链接和普通图片，都可以直接使用 Pages CMS 的 Editor mode。这个模式适合日常写作，写完之后看起来和普通 Markdown 编辑器差不多。
例如下面这段内容不需要特殊处理：
写作时可以先不用考虑 AI 摘要。正文保存后，后面的工作流会自动处理它。
这个主题提供了不少 Hugo shortcode，比如提示框、折叠面板、标签页、Mermaid 和卡片。Pages CMS 不负责解析它们，只是把文章里的 Markdown 保存回 GitHub。
因此，正文里出现下面这些内容时，建议切换到 Source mode：
{{< note >}}、{{< fold >}} 这类 Hugo shortcode；比如这段提示框就应该在 Source mode 中编辑：
这里代码块里的 /* 和 */ 是为了让示例原样显示，实际文章中使用 shortcode 时不需要加这层转义。
如果把包含大量 shortcode 的文章交给 Editor mode，编辑器可能会重新排列 Markdown，或者把 shortcode 当成普通文本处理。文章看起来可能没问题，但构建时才发现标签没有闭合。遇到这类文章，Source mode 更稳妥。
Pages CMS 的媒体配置指向 static/img，文章正文图片建议放在：
上传后，在文章中使用公开路径：
提交前检查三件事：
static/img/posts/；/img/posts/...，而不是 static/img/posts/...。图片不会放进 content/posts。文章目录存 Markdown，静态资源目录存图片，这是 Hugo 处理静态文件的方式。
在 CMS 中保存文章以后，先确认页面提示已经提交成功，再打开 GitHub Actions 查看 Deploy to Cloudflare Pages。
Actions 会先运行摘要脚本。它会读取 content/posts 下的文章，清理 front matter、代码块、图片地址、HTML 标签和 Markdown 符号，然后把正文发送给配置好的 OpenAI 兼容接口。
生成结果会写回 front matter：
随后 Hugo 使用带有摘要的工作树继续构建，Cloudflare Pages 部署的也是这次构建结果。
摘要脚本默认只处理没有 ai_summary 的文章。这样修改一篇已有文章时，不会因为普通发布再次消耗模型额度，也不会让摘要在每次构建时发生变化。
如果确实需要重新生成已有文章的摘要，可以在 GitHub Actions 页面手动运行工作流，并把：
设为 true。
有一种情况会始终跳过：文章明确写了：
这表示作者不希望这篇文章生成摘要。普通发布和强制重新生成都不会覆盖这个停用标记。
如果想在提交前检查哪些文章会被处理，可以在博客仓库根目录执行：
这条命令只列出候选文章，不调用 AI 接口，也不会修改文件。确认配置和文章都没有问题后，再运行完整命令：
本地摘要配置放在 .env 中：
.env 已经被 Git 忽略。不要把真实 Key 填进 .env.example，更不要把它放进文章里作为示例提交。
普通段落用 Editor mode 没问题，但一篇文章只要包含多个 shortcode，最好从头到尾在 Source mode 中检查一次。尤其要确认：
摘要接口返回错误、Key 缺失、模型名称错误或接口超时，Actions 会失败，后面的 Hugo 构建和 Cloudflare 部署不会继续执行。
这时先看 Actions 日志中的失败文件和错误信息，检查 AI_SUMMARY_API_KEY、接口地址、模型名称以及服务商状态。配置修好后，在原来的 workflow 页面重新运行即可。
ai_summary 是文章正文前的展示内容，description 才是文章的描述字段。两者用途不同，不要为了显示摘要而删掉 description，也不要把 API 返回结果直接塞进站点全局配置。
现在这套流程可以概括成一句话：Pages CMS 负责写，GitHub 负责存，Actions 负责补齐摘要和构建，Cloudflare Pages 负责发布。
第一次使用时，我建议按下面的顺序走一遍：
kemiao-moretti/meowloge，确认分支是 main。content/posts。static/img/posts/。这样以后想写文章时，不必先打开本地开发环境。打开 Pages CMS，写完，保存，等它跑完发布流程就可以了。偶尔需要改主题或调脚本时，再回到仓库里处理，两套入口各自负责擅长的事情，反而更清楚。
]]>这篇文章把接入过程记下来。以后重装主题，或者想给别的 Hugo 站点照着改时，不用再翻聊天记录。
文章的 front matter 里有 ai_summary 时，页面会在正文前显示摘要卡：
没有这个字段的文章不会显示空卡片。摘要卡的颜色、边框和阴影都跟着 Solitude 的主题变量走，所以切换明暗模式时不需要另外维护两套样式。
摘要文字默认会有一个很短的打字效果。浏览器开启了“减少动态效果”后，组件会直接显示完整内容。
文章模板是：
在文章元信息和正文之间加一行 partial：
摘要模板在：
模板只做一件事：读取 .Params.ai_summary。字段为空就什么也不输出，这样旧文章不需要批量修改，也不会出现一张写着“暂无摘要”的占位卡。
站点的 hugo.yaml 里有一段摘要配置：
title 是卡片标题，model 会显示在右侧的小标签里，loading 是脚本还没有开始打字时的备用文字。
这些配置只是展示层设置。真正请求 AI 的接口和密钥不放在这里。
.env接口信息放在博客根目录的 .env 文件里，也就是：
可以先复制示例文件：
Windows PowerShell 可以这样复制：
然后打开 .env，填入自己的接口信息：
.env 已经被加入 .gitignore，不会提交到 Git。不要把真实密钥写进 .env.example，也不要把 .env 发给别人。
脚本会自动读取博客根目录的 .env。如果当前终端已经设置了同名环境变量，环境变量优先，不会被 .env 覆盖。
SiliconFlow 的 Qwen3 默认可能开启思考模式。摘要脚本已经固定发送 enable_thinking: false，并设置 stream: false，这样会直接返回普通 JSON 摘要，不会等待或解析流式响应。
生成脚本位于：
它使用 OpenAI 兼容的 Chat Completions 接口，整体行为参考了 hexo-ai-summary：只在构建准备阶段处理 Markdown，不在访客浏览器里请求 AI；默认跳过已有摘要的文章，也支持并发、输入清洗、摘要字段自定义、覆盖控制和分级日志。脚本会遍历 content/posts/ 下的 Markdown 文章，然后把生成结果写回 front matter。
先做一次 dry-run 比较稳妥：
这一步只会列出准备处理的文章，不会修改文件。
确认 .env 已经填好后，直接生成：
如果不想创建 .env，也可以临时用 PowerShell 设置配置：
如果只想临时覆盖 .env 里的配置，仍然可以使用环境变量：
PowerShell 写法：
脚本默认只生成缺少摘要的文章。想重新生成已有摘要时，加上 --force：
生成完成后，再运行 Hugo：
目前这两个步骤是分开的。也就是说，hugo 不会偷偷调用 AI 接口；需要生成摘要时，先手动运行脚本，再构建站点。这样构建过程更可控，也不容易因为接口临时超时而卡住发布。
脚本还支持这些和插件思路对应的配置：
AI_SUMMARY_COVER_ALL=true 或运行时加 --force 会覆盖已有摘要；AI_SUMMARY_CONCURRENCY 控制同时请求的文章数，建议不要设得太大；AI_SUMMARY_SLEEP_TIME 可以在每篇文章处理后增加间隔。推理模型可以打开 AI_SUMMARY_THINKING=true，脚本会发送 reasoning_effort=medium，但摘要场景默认关闭更稳妥。
发送给模型前，脚本会先做一些清理：
默认输入上限是 12000 个字符，可以在 .env 里调整，也可以用环境变量临时覆盖：
提示词也可以通过 .env 里的 AI_SUMMARY_PROMPT 自定义。默认提示词要求模型只返回一段中文摘要，不要输出标题、列表或 Markdown。
最开始也想过在文章页放一个“生成摘要”按钮，但那样需要把 API Key 交给浏览器。只要打开开发者工具，Key 就能被看到，后面还可能被别人拿去刷接口额度。
所以现在的做法是：
访客不会接触到 API Key，文章页面也不依赖 AI 接口才能打开。对博客来说，这种方式简单一点，但更踏实。
脚本遇到某篇文章请求失败时，会在终端打印文件名和错误原因，并继续处理后面的文章。失败的文章不会被写入半截摘要。
如果最后有失败项，脚本会返回非零退出码。发布前看一眼终端输出就能知道有没有文章漏掉，不需要专门去页面里排查。
常见问题通常是：
AI_SUMMARY_API_KEY 没有设置/v1/chat/completions改完后，我一般会按这个顺序检查：
然后打开一篇有 ai_summary 的文章，看四件事：摘要是不是在正文前、暗色模式下文字是否清楚、手机宽度有没有横向滚动，以及没有摘要的旧文章是否保持原样。
这套组件现在只负责摘要展示，没有把摘要当成 SEO 的 description，也没有把请求逻辑塞进访客浏览器。以后如果觉得摘要质量不够，优先改提示词；如果觉得卡片太抢眼，再调整组件 CSS，不需要动文章正文。