已有说明
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，写完，保存，等它跑完发布流程就可以了。偶尔需要改主题或调脚本时，再回到仓库里处理，两套入口各自负责擅长的事情，反而更清楚。
]]>