A post as AGENTS.md

$ touch AGENTS.md
$ hexo new post "next-note"
$ npm run server

这篇文章是给未来写博客时参考的写作说明。它和根目录里的 AGENTS.md 保持同一套约定：文章应该像可执行的技术记录，尽量写清楚背景、命令、配置、验证结果和后续维护方式。

writing contract

每篇文章优先回答几个问题：

what changed
why it exists
how to reproduce
how to verify
how to maintain

如果文章涉及部署、脚本或配置，应该给出真实路径、命令和服务名。不要只写结论，也不要把排错过程完全删掉；能复用的中间判断通常比最后一条命令更有价值。

mermaid codeblock

当文章 front-matter 里设置 mermaid: true 时，mermaid codeblock 会被可视化渲染，不会只显示为普通代码。

写法如下：

```mermaid
flowchart LR
  A["draft"] --> B["hexo generate"]
  B --> C["OneDrive client"]
  C --> D["blog-sync.timer"]
  D --> E["nginx"]
```

实际渲染效果：

flowchart LR
  A["draft"] --> B["hexo generate"]
  B --> C["OneDrive client"]
  C --> D["blog-sync.timer"]
  D --> E["nginx"]

Mermaid 图会被包进 terminal 风格面板里。图比较宽时，面板内部可以横向滚动；右上角有淡入的 - / reset / + 缩放按钮。

plotly charts

文章也可以内嵌 Plotly。页面不会全站提前加载 Plotly，只有检测到 .plotly-terminal-chart 或 .plotly-terminal-demo 时才会按需加载。

推荐写法是放一个容器和一个 JSON template：

<div class="plotly-terminal-chart" data-plotly-template="plotly-example"></div>
<template id="plotly-example" type="application/json">
{
  "data": [
    {
      "x": ["draft", "build", "sync", "serve"],
      "y": [1, 3, 2, 4],
      "type": "bar"
    }
  ],
  "layout": {
    "title": { "text": "example chart" }
  }
}
</template>

实际渲染效果：

post checklist

发布前检查：

npm run server
npx hexo generate

如果文章用了 Mermaid，确认 front-matter 有：

mermaid: true

如果文章用了数学公式，确认 front-matter 有：

math: true

如果文章用了 Plotly，不需要额外 front-matter；只要使用 .plotly-terminal-chart 或 .plotly-terminal-demo 容器即可。

deployment notes

这个博客是本地优先的静态发布。服务器不跑 Hexo，也不把用户请求直接打到 OneDrive FUSE mount 上。

本地负责写作和编译。这个仓库本身就在 OneDrive 的本地同步目录里，所以上传到云端由 OneDrive 客户端负责，不通过本地 rclone 上传。

~/Library/CloudStorage/OneDrive-Personal/Blog
  -> hexo generate
  -> OneDrive client syncs Blog/ to cloud

package.json 里的发布命令是：

npm run publish

它只会执行本地清理和生成：

hexo clean && hexo generate

生成出来的 public/ 位于本地 OneDrive 目录内，之后由 OneDrive 客户端同步到云端。

服务器端只做一件事：定时从 OneDrive 拉取云端 public/ 子目录到本地磁盘，然后让 Nginx 直接读本地文件。

source: OneDrive-Personal:Blog/public
target: /srv/jeremyguo-blog/public

服务器上有一个 blog-sync.timer，大约每 3 分钟触发一次同步。同步脚本内部使用 rclone，只拉取静态站点需要的文件子集，并写入 /srv/jeremyguo-blog/public。

用户访问 jeremyguo.space 时，请求路径是：

browser
  -> nginx
  -> /srv/jeremyguo-blog/public

不会在用户请求时阻塞等待 OneDrive。

需要马上上线时，先本地生成并等待 OneDrive 客户端把变更上传完成，再让服务器立刻拉取：

npm run publish
ssh root@jeremyguo.space blog-sync-now

排查时只需要看同步状态和日志：

ssh root@jeremyguo.space systemctl status blog-sync.service blog-sync.timer
ssh root@jeremyguo.space tail -100 /var/log/blog-sync.log