hd-garden 0.3.6 → 0.3.8

package/.agents/skills/garden-post-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: garden-post-review
+description: >-
+  Reviews one specified Garden post in three steps: fix script-reported
+  structure errors, fix widgets with the chart skill, then suggest prose
+  improvements without editing. Use when the user asks to 审查 / 审稿 /
+  review a Garden blog post.
+---
+
+# 审查一篇 Garden 博文
+
+只审用户点名的稿。三步按顺序做，后一步看到的是前一步改完的稿。
+
+硬性检查命令（在站点根目录）：
+
+```bash
+npx garden check content/posts/路径.md
+```
+
+stdout 是 JSON。`ok` 为 true 才算通过。不要自己再查一遍标题、日期或参考列表。
+
+## 1. 脚本报错，模型只修这些
+
+运行 `garden check`。有 `errors` 就只改这些条目，改完再跑同一条命令，直到 `ok` 为 true。
+
+- 只动报错指出的位置。
+- 脚本没报的结构问题不要顺手改。
+- `references` 是推荐额外阅读，不必和正文里的外链一一对应。不要因为正文有链接就补进表，也不要因为表里的材料正文没提到就删掉。
+- `reference-heading`：把 `## 参考` / `## 参考资料` 收进 `references`，删掉这个标题。`## 参考文献` 留在正文里。
+- 缺 widget 文件时，只修正写错的 `src`。不要在这一步新做图表。
+
+## 2. 图表按图表 skill 审并修
+
+这一步只在稿里有 `widget` 时做。先读 [garden-interactive-chart](../garden-interactive-chart/SKILL.md)。
+
+可以改同名目录里的 HTML，以及对应围栏的 `caption`。周围正文不动。`caption` 必须是一句判断。
+
+改完再跑一次 `garden check`，直到通过。
+
+没有 `widget` 就跳过这一步。
+
+## 3. 通读整篇，只出建议
+
+`garden check` 已经通过，并且图表该改的已经改完。通读全文。不要改文件。
+
+目标只有一个：这篇是不是从第一性原理出发，自洽，并且把一个点讲到闭环。读者读完应能说出这是什么、为什么必然如此，以及这个「为什么」怎样落到一段实践上。实践是代码、故障、测量或一次推导的落地，用来验证同一条链，不是另起一篇教程。
+
+第一性原理指：从拆不开的事实、约束或不变量推上去，而不是从「别人都这么做」或一个比喻出发。拆完还要装回去；只列出现有方案的洞、没有推出结论，不算讲完。类比和业界做法可以出现，但只能当作这条推导的对照，不能代替推导。
+
+只在下面的情况写出建议：
+
+- 开头站在名词、惯例或比喻上，读者看不到这件事被什么事实卡住
+- 后文的机制、术语或结论，不能从前面的事实推出来，或同一个词前后不是同一个意思
+- 一个点只停在「是什么」：没有为什么，或者为什么没有落到可核对的实践
+- 实践和前面的原理各讲各的，对不上同一条链
+- 铺开多个相邻话题，没有把其中一点收回来。讲透一个点，好过点到许多点
+- 数字、比较、「通常如此」没有从推导、实践或来源里长出来
+
+每条建议包含：所在标题、闭环断在哪里、可以怎么补。没有就写没有。不要把稿子改成「问题—方案」模板，也不要要求每段都加不适用说明。译文若已经在复述原文的推导，不要另要求作者发明一套练习。
+
+这一步禁止修改博文、图表和 front matter。

package/.env.example

@@ -8,11 +8,14 @@ ADMIN_URL=https://admin.example.com
 # 可选：反向代理或多域名后台时，显式指定 GitHub OAuth 回调地址。
 # GITHUB_OAUTH_REDIRECT_URI=https://admin.example.com/api/auth/github/callback
 
-# Giscus：在 https://giscus.app 配置后复制以下四项。
-GISCUS_REPO=owner/repository
-GISCUS_REPO_ID=R_xxxxxxxxxx
-GISCUS_CATEGORY=Announcements
-GISCUS_CATEGORY_ID=DIC_xxxxxxxxxx
+# 评论默认关闭。打开 https://giscus.app/zh-CN 安装后，去掉注释并填入真实值。
+# 仓库必须是 owner/name 这种公开仓库，且已开启 Discussions。
+# 线上还要把同名四项写进 GitHub Actions Variables。留空会让发布失败。
+# 确定不开放评论时，把 Actions Variable GISCUS_DISABLED 设为 1。
+# GISCUS_REPO=
+# GISCUS_REPO_ID=
+# GISCUS_CATEGORY=
+# GISCUS_CATEGORY_ID=
 
 # Webmention.io：注册正式域名后填写域名，不含 https://。
 WEBMENTION_IO_DOMAIN=example.com

package/Makefile

@@ -26,7 +26,6 @@ skill:
 
 prepare:
 	@if [ ! -d node_modules ]; then npm ci; fi
-	@if [ ! -f .env.local ]; then cp .env.example .env.local; fi
 
 dev: prepare
 	node bin/garden.mjs dev

package/README.md

@@ -55,11 +55,11 @@ make update    # 检查、提交并触发自动发布
 make update MESSAGE="新增一篇文章"
 ```
 
-`make dev` 会在首次运行时自动安装依赖并创建 `.env.local`。`make update` 会先检查，再提交并推送工作区中的所有改动。不想发布的文件请先移出仓库或加入 `.gitignore`。
+`make dev` 会在首次运行时自动安装依赖并创建 `.env.local`，同时说明如何接上评论。线上发布要求 Actions Variables 里有 `GISCUS_REPO`、`GISCUS_REPO_ID`、`GISCUS_CATEGORY`、`GISCUS_CATEGORY_ID`；留空会让构建失败。确定不开放评论时设置 `GISCUS_DISABLED=1`。`make update` 会先检查，再提交并推送工作区中的所有改动。不想发布的文件请先移出仓库或加入 `.gitignore`。
 
 ## 进一步配置
 
-首次跑通以后，再按需查看：
+评论接法见[从零开始](docs/quick-start.md)。跑通以后，再按需查看：
 
 - [评论、Webmentions 与内容分发](docs/integrations.md)
 - [随想管理后台](docs/admin-service.md)

package/app/components/Comments.tsx

@@ -1,29 +1,9 @@
 import { ChatCircle, GithubLogo } from "@phosphor-icons/react/ssr";
-import {
-  GiscusComments,
-  type GiscusConfig,
-} from "./GiscusComments";
-
-function giscusConfig(): GiscusConfig | undefined {
-  const config = {
-    repo:
-      process.env.GISCUS_REPO ?? process.env.NEXT_PUBLIC_GISCUS_REPO,
-    repoId:
-      process.env.GISCUS_REPO_ID ?? process.env.NEXT_PUBLIC_GISCUS_REPO_ID,
-    category:
-      process.env.GISCUS_CATEGORY ??
-      process.env.NEXT_PUBLIC_GISCUS_CATEGORY,
-    categoryId:
-      process.env.GISCUS_CATEGORY_ID ??
-      process.env.NEXT_PUBLIC_GISCUS_CATEGORY_ID,
-  };
-  return Object.values(config).every(Boolean)
-    ? (config as GiscusConfig)
-    : undefined;
-}
+import { readGiscusConfig } from "../lib/giscus-config";
+import { GiscusComments } from "./GiscusComments";
 
 export function Comments({ slug }: { slug: string }) {
-  const config = giscusConfig();
+  const config = readGiscusConfig();
 
   return (
     <section className="comments" aria-labelledby={`comments-heading-${slug}`}>
@@ -34,7 +14,7 @@ export function Comments({ slug }: { slug: string }) {
           <p>
             {config
               ? "评论由 GitHub Discussions 保存和管理。"
-              : "评论接入已准备好，补充 GitHub Discussions 配置后即可开放。"}
+              : "评论还没开放。配好下面四项后，这里才会出现评论框。"}
           </p>
         </div>
       </div>
@@ -45,8 +25,14 @@ export function Comments({ slug }: { slug: string }) {
         <div className="integration-notice">
           <GithubLogo size={20} weight="fill" />
           <p>
-            需要一个公开 GitHub 仓库，并为它启用 Discussions、安装 Giscus
-            App、选择评论分类。
+            打开{" "}
+            <a href="https://giscus.app/zh-CN" target="_blank" rel="noreferrer">
+              Giscus
+            </a>
+            ，安装到一个已开启 Discussions 的公开仓库，把仓库、仓库 ID、分类、分类 ID
+            写入 <code>.env.local</code> 和 GitHub Actions Variables：
+            <code>GISCUS_REPO</code>、<code>GISCUS_REPO_ID</code>、
+            <code>GISCUS_CATEGORY</code>、<code>GISCUS_CATEGORY_ID</code>。
           </p>
         </div>
       )}

package/app/components/GiscusComments.tsx

@@ -2,12 +2,9 @@
 
 import { useEffect, useRef } from "react";
 
-export type GiscusConfig = {
-  repo: string;
-  repoId: string;
-  category: string;
-  categoryId: string;
-};
+import type { GiscusConfig } from "../lib/giscus-config";
+
+export type { GiscusConfig };
 
 function currentGiscusTheme() {
   return document.documentElement.dataset.theme === "dark" ? "dark" : "light";

package/app/globals.css

@@ -2934,6 +2934,17 @@ button {
   font-size: 11px;
 }
 
+.integration-notice a,
+.integration-notice code {
+  text-decoration: underline;
+  text-underline-offset: 0.18em;
+}
+
+.integration-notice code {
+  text-decoration: none;
+  font-family: var(--font-mono), ui-monospace, monospace;
+}
+
 .integration-status {
   margin: 22px 0 0;
   color: var(--muted);

package/app/lib/giscus-config.ts

@@ -0,0 +1,39 @@
+export type GiscusConfig = {
+  repo: string;
+  repoId: string;
+  category: string;
+  categoryId: string;
+};
+
+const PLACEHOLDERS = new Set([
+  "owner/repository",
+  "R_xxxxxxxxxx",
+  "DIC_xxxxxxxxxx",
+]);
+
+function configuredValue(
+  env: Record<string, string | undefined>,
+  primary: string,
+  fallback: string,
+) {
+  const value = (env[primary] ?? env[fallback] ?? "").trim();
+  if (!value || PLACEHOLDERS.has(value)) return undefined;
+  return value;
+}
+
+export function readGiscusConfig(
+  env: Record<string, string | undefined> = process.env,
+): GiscusConfig | undefined {
+  const repo = configuredValue(env, "GISCUS_REPO", "NEXT_PUBLIC_GISCUS_REPO");
+  const repoId = configuredValue(env, "GISCUS_REPO_ID", "NEXT_PUBLIC_GISCUS_REPO_ID");
+  const category = configuredValue(env, "GISCUS_CATEGORY", "NEXT_PUBLIC_GISCUS_CATEGORY");
+  const categoryId = configuredValue(
+    env,
+    "GISCUS_CATEGORY_ID",
+    "NEXT_PUBLIC_GISCUS_CATEGORY_ID",
+  );
+  if (!repo || !repoId || !category || !categoryId) return undefined;
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repo)) return undefined;
+  if (!repoId.startsWith("R_") || !categoryId.startsWith("DIC_")) return undefined;
+  return { repo, repoId, category, categoryId };
+}

package/bin/garden.mjs

@@ -88,11 +88,25 @@ function ensurePublic() {
   }
 }
 
+function printGiscusGuide() {
+  process.stdout.write(`评论默认关闭。发布前要接上自己的 Giscus，留空会让 GitHub Actions 构建失败：
+  1. 准备一个公开 GitHub 仓库，并开启 Discussions。公开源码仓库可以直接用；私有源码要另建一个公开仓库。
+  2. 打开 https://giscus.app/zh-CN ，安装 Giscus App，只授权这个仓库，并选一个分类。
+  3. 把仓库、仓库 ID、分类、分类 ID 写入 .env.local 的 GISCUS_REPO、GISCUS_REPO_ID、GISCUS_CATEGORY、GISCUS_CATEGORY_ID。
+  4. 在源码仓库 Settings → Secrets and variables → Actions → Variables 写入同样四项。
+示例值不会被当成已配置。确定不开放评论时，把 Actions Variable GISCUS_DISABLED 设为 1。
+`);
+}
+
 function ensureEnv() {
+  // CI injects the real values. Copying .env.example there would fill any
+  // unset key with a sample, which used to turn comments on for owner/repository.
+  if (process.env.GITHUB_ACTIONS === "true") return;
   const example = path.join(gardenPackageRoot, ".env.example");
   const local = path.join(siteRoot, ".env.local");
   if (!fs.existsSync(local) && fs.existsSync(example)) {
     fs.copyFileSync(example, local);
+    printGiscusGuide();
   }
 }
 
@@ -174,14 +188,7 @@ function ensureSiteKit(destinationRoot = siteRoot) {
     process.stdout.write(`已补齐站点文件：${added.join("、")}\n`);
   }
 
-  const skillFile = path.join(
-    destinationRoot,
-    ".agents",
-    "skills",
-    "garden-interactive-chart",
-    "SKILL.md",
-  );
-  if (!fs.existsSync(skillFile)) installSkill(destinationRoot);
+  installSkill(destinationRoot, { onlyMissing: true });
 }
 
 function prepare() {
@@ -248,28 +255,33 @@ function initSite() {
   process.stdout.write("下一步：\n");
   process.stdout.write(`  cd ${destination}\n`);
   process.stdout.write("  npm install\n");
+  process.stdout.write("  按下面四步接上评论，再写文章\n");
   process.stdout.write("  make new TITLE=\"你好，世界\" SLUG=hello\n");
   process.stdout.write("  make dev\n");
+  printGiscusGuide();
 }
 
-function packagedSkillRoot() {
-  return path.join(
-    gardenPackageRoot,
-    ".agents",
-    "skills",
-    "garden-interactive-chart",
-  );
+function packagedSkills() {
+  const root = path.join(gardenPackageRoot, ".agents", "skills");
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, "SKILL.md")))
+    .map((entry) => entry.name);
 }
 
-function installSkill(destinationRoot = siteRoot) {
-  const from = packagedSkillRoot();
-  if (!fs.existsSync(path.join(from, "SKILL.md"))) {
-    fail("Garden 包里缺少图表 skill。");
+function installSkill(destinationRoot = siteRoot, { onlyMissing = false } = {}) {
+  const names = packagedSkills();
+  if (!names.length) fail("Garden 包里没有 skill。");
+  const installed = [];
+  for (const name of names) {
+    const to = path.join(destinationRoot, ".agents", "skills", name);
+    if (onlyMissing && fs.existsSync(path.join(to, "SKILL.md"))) continue;
+    fs.cpSync(path.join(gardenPackageRoot, ".agents", "skills", name), to, { recursive: true });
+    installed.push(name);
+  }
+  if (installed.length) {
+    process.stdout.write(`已安装 skill：${installed.join("、")}\n`);
   }
-  const to = path.join(destinationRoot, ".agents", "skills", "garden-interactive-chart");
-  fs.cpSync(from, to, { recursive: true });
-  const shown = path.relative(destinationRoot, to) || to;
-  process.stdout.write(`已安装图表 skill：${shown}\n`);
 }
 
 function help() {
@@ -281,7 +293,8 @@ function help() {
   garden new              创建文章草稿
   garden embed            拉取外链摘要
   garden init [目录]      创建只含稿和配置的新站点
-  garden skill            把可交互图表 skill 装进当前站点
+  garden check <文章.md>  检查一篇博文的硬性结构
+  garden skill            把引擎自带的 skill 装进当前站点
   garden pages:validate   检查 dist/client
   garden pages:prepare    写入公开产物仓库
   garden webmentions      发送 Webmentions
@@ -312,6 +325,9 @@ switch (command) {
   case "embed":
     runNode("scripts/fetch-embed.mjs", rest);
     break;
+  case "check":
+    runNode("scripts/check-post.mjs", rest);
+    break;
   case "init":
     initSite();
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",

package/scripts/check-post.mjs

@@ -0,0 +1,282 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { parse as parseYaml } from "yaml";
+import { canonicalSiteDate } from "./site-date.mjs";
+import { gardenSiteRoot } from "./garden-paths.mjs";
+
+const siteRoot = gardenSiteRoot();
+const calloutTypes = new Set([
+  "NOTE",
+  "INFO",
+  "TIP",
+  "SUCCESS",
+  "IMPORTANT",
+  "WARNING",
+  "CAUTION",
+  "DANGER",
+  "FAILURE",
+]);
+const authorDate = /^(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})$/u;
+const matterOptions = {
+  engines: {
+    yaml: {
+      parse: (input) => parseYaml(input) ?? {},
+    },
+  },
+};
+
+const error = (errors, code, line, message) => {
+  errors.push({ code, line, message });
+};
+
+const isExternalAsset = (value) =>
+  /^(?:[a-z]+:)?\/\//iu.test(value) ||
+  value.startsWith("/") ||
+  value.startsWith("data:") ||
+  value.startsWith("#");
+
+const normalizeUrl = (value) => {
+  try {
+    const url = new URL(value);
+    for (const key of [...url.searchParams.keys()]) {
+      if (key.startsWith("utm_")) url.searchParams.delete(key);
+    }
+    url.hash = "";
+    if (url.pathname.length > 1) url.pathname = url.pathname.replace(/\/+$/u, "");
+    return url.toString();
+  } catch {
+    return value.trim();
+  }
+};
+
+const markdownStem = (markdownPath) => path.basename(markdownPath, path.extname(markdownPath));
+
+const assertLocalFile = (errors, value, baseDir, sourcePath, line, label) => {
+  if (!value || isExternalAsset(value)) return;
+  const [assetPath] = value.split(/(?=[?#])/u, 2);
+  const decoded = decodeURIComponent(assetPath.replace(/^<|>$/gu, ""));
+  const absolute = path.resolve(baseDir, decoded);
+  if (!fs.existsSync(absolute)) {
+    error(errors, "missing-asset", line, `${sourcePath}: 找不到${label} ${value}`);
+  }
+};
+
+const checkReferences = (data, sourcePath, errors) => {
+  if (data.references === undefined) return [];
+  if (!Array.isArray(data.references)) {
+    error(errors, "references-type", 1, `${sourcePath}: references 必须是数组`);
+    return [];
+  }
+  const seen = new Set();
+  data.references.forEach((item, index) => {
+    const where = `references[${index}]`;
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      error(errors, "references-type", 1, `${sourcePath}: ${where} 必须是包含 title 的对象`);
+      return;
+    }
+    for (const key of Object.keys(item)) {
+      if (key !== "title" && key !== "url") {
+        error(errors, "reference-key", 1, `${sourcePath}: ${where} 不支持 ${key}`);
+      }
+    }
+    if (typeof item.title !== "string" || !item.title.trim()) {
+      error(errors, "reference-title", 1, `${sourcePath}: ${where} 缺少有效的 title`);
+    }
+    if (item.url === undefined || item.url === null || item.url === "") return;
+    if (typeof item.url !== "string") {
+      error(errors, "reference-url", 1, `${sourcePath}: ${where}.url 必须是字符串`);
+      return;
+    }
+    let parsed;
+    try {
+      parsed = new URL(item.url.trim());
+    } catch {
+      parsed = null;
+    }
+    if (!parsed || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
+      error(errors, "reference-url", 1, `${sourcePath}: ${where}.url 必须是 http 或 https 链接`);
+      return;
+    }
+    const normalized = normalizeUrl(item.url.trim());
+    if (seen.has(normalized)) {
+      error(errors, "reference-duplicate", 1, `${sourcePath}: ${where}.url 与前面的参考重复`);
+      return;
+    }
+    seen.add(normalized);
+  });
+};
+
+const checkWidget = (errors, body, markdownPath, sourcePath, line) => {
+  let data;
+  try {
+    data = parseYaml(body);
+  } catch {
+    error(errors, "widget-yaml", line, `${sourcePath}: widget 围栏不是有效的 YAML`);
+    return;
+  }
+  if (data == null || typeof data !== "object" || Array.isArray(data)) {
+    error(errors, "widget-yaml", line, `${sourcePath}: widget 围栏必须是包含 src 与 caption 的 YAML 对象`);
+    return;
+  }
+  const caption = typeof data.caption === "string" ? data.caption.trim() : "";
+  const src = typeof data.src === "string" ? data.src.trim() : "";
+  if (!caption) error(errors, "widget-caption", line, `${sourcePath}: widget 缺少 caption`);
+  if (!src) {
+    error(errors, "widget-src", line, `${sourcePath}: widget 缺少 src`);
+    return;
+  }
+  const [assetPath] = src.split(/(?=[?#])/u, 2);
+  const decoded = decodeURIComponent(assetPath.replace(/^<|>$/gu, ""));
+  if (isExternalAsset(decoded)) {
+    error(errors, "widget-src", line, `${sourcePath}: widget src 必须是同名目录里的本地 .html 或 .pdf`);
+    return;
+  }
+  const absolute = path.resolve(path.dirname(markdownPath), decoded);
+  const sidecar = path.join(path.dirname(markdownPath), markdownStem(markdownPath));
+  const relative = path.relative(sidecar, absolute);
+  const extension = path.extname(absolute).toLowerCase();
+  if (relative.startsWith("..") || path.isAbsolute(relative) || ![".html", ".pdf"].includes(extension)) {
+    error(
+      errors,
+      "widget-src",
+      line,
+      `${sourcePath}: widget src 必须位于同名目录 ${markdownStem(markdownPath)}/ 内的 .html 或 .pdf`,
+    );
+    return;
+  }
+  if (!fs.existsSync(absolute)) {
+    error(errors, "widget-missing", line, `${sourcePath}: 找不到 widget 文件 ${src}`);
+    return;
+  }
+  if (data.kind == null || data.kind === "") return;
+  if (typeof data.kind !== "string" || !["chart", "html", "pdf"].includes(data.kind.trim())) {
+    error(errors, "widget-kind", line, `${sourcePath}: widget kind 必须是 chart、html 或 pdf`);
+    return;
+  }
+  const kind = data.kind.trim();
+  if (kind === "pdf" && extension !== ".pdf") {
+    error(errors, "widget-kind", line, `${sourcePath}: kind: pdf 只能用于 .pdf`);
+  }
+  if ((kind === "chart" || kind === "html") && extension !== ".html") {
+    error(errors, "widget-kind", line, `${sourcePath}: kind: ${kind} 只能用于 .html`);
+  }
+};
+
+const checkEmbed = (errors, body, sourcePath, line) => {
+  let data;
+  try {
+    data = parseYaml(body);
+  } catch {
+    error(errors, "embed-url", line, `${sourcePath}: embed 围栏不是有效的 YAML`);
+    return;
+  }
+  const url = data && typeof data === "object" && !Array.isArray(data) ? data.url : undefined;
+  if (typeof url !== "string" || !url.trim()) {
+    error(errors, "embed-url", line, `${sourcePath}: embed 缺少 url`);
+    return;
+  }
+  try {
+    const parsed = new URL(url.trim());
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error("protocol");
+  } catch {
+    error(errors, "embed-url", line, `${sourcePath}: embed url 必须是 http 或 https 链接`);
+  }
+};
+
+const scanBody = (errors, content, markdownPath, sourcePath) => {
+  let fence = null;
+  let previousDepth = 1;
+  const lines = content.split(/\r?\n/u);
+  lines.forEach((line, index) => {
+    const lineNumber = index + 1;
+    const opener = line.match(/^(`{3,}|~{3,})(.*)$/u);
+    if (fence) {
+      if (opener && opener[1][0] === fence.marker && opener[1].length >= fence.marker.length && !opener[2].trim()) {
+        if (fence.lang === "widget") checkWidget(errors, fence.body.join("\n"), markdownPath, sourcePath, fence.line);
+        if (fence.lang === "embed") checkEmbed(errors, fence.body.join("\n"), sourcePath, fence.line);
+        fence = null;
+      } else {
+        fence.body.push(line);
+      }
+      return;
+    }
+    if (opener) {
+      fence = { marker: opener[1], lang: opener[2].trim().split(/\s+/u)[0]?.toLowerCase() ?? "", body: [], line: lineNumber };
+      return;
+    }
+
+    const heading = line.match(/^(#{1,6})\s+(.+?)\s*#*$/u);
+    if (heading) {
+      const depth = heading[1].length;
+      const text = heading[2].trim();
+      if (depth === 1) error(errors, "heading-h1", lineNumber, `${sourcePath}: 正文不要用一级标题，页面标题写在 front matter`);
+      if (depth > previousDepth + 1) {
+        error(errors, "heading-skip", lineNumber, `${sourcePath}: 标题从 ${previousDepth} 级跳到了 ${depth} 级`);
+      }
+      if (depth === 2 && (text === "参考" || text === "参考资料")) {
+        error(errors, "reference-heading", lineNumber, `${sourcePath}: 「${text}」不要写成标题，改放到 front matter 的 references`);
+      }
+      previousDepth = depth;
+    }
+
+    const callout = line.match(/^>\s*\[!([A-Za-z]+)\]/u);
+    if (callout && !calloutTypes.has(callout[1].toUpperCase())) {
+      error(errors, "callout-type", lineNumber, `${sourcePath}: 不支持的警告框类型 ${callout[1]}`);
+    }
+
+    for (const image of line.matchAll(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/gu)) {
+      assertLocalFile(errors, image[2], path.dirname(markdownPath), sourcePath, lineNumber, "图片");
+    }
+  });
+
+  if (fence?.lang === "widget") checkWidget(errors, fence.body.join("\n"), markdownPath, sourcePath, fence.line);
+  if (fence?.lang === "embed") checkEmbed(errors, fence.body.join("\n"), sourcePath, fence.line);
+};
+
+const checkFile = (filePath) => {
+  const absolute = path.resolve(siteRoot, filePath);
+  const sourcePath = path.relative(siteRoot, absolute);
+  const errors = [];
+  if (!fs.existsSync(absolute)) {
+    error(errors, "missing-file", 1, `${sourcePath}: 找不到文件`);
+    return { file: sourcePath, errors };
+  }
+  const parsed = matter(fs.readFileSync(absolute, "utf8"), matterOptions);
+  const data = parsed.data ?? {};
+  if (typeof data.title !== "string" || !data.title.trim()) {
+    error(errors, "missing-title", 1, `${sourcePath}: front matter 缺少有效的 title`);
+  }
+  if (typeof data.description !== "string" || !data.description.trim()) {
+    error(errors, "missing-description", 1, `${sourcePath}: front matter 缺少有效的 description`);
+  }
+  if (typeof data.topic !== "string" || !data.topic.trim()) {
+    error(errors, "missing-topic", 1, `${sourcePath}: front matter 缺少有效的 topic`);
+  }
+  if (data.slug !== undefined) {
+    error(errors, "unexpected-slug", 1, `${sourcePath}: 不要写 slug，文件名就是标识`);
+  }
+  if (typeof data.date !== "string" || !authorDate.test(data.date.trim()) || !canonicalSiteDate(data.date)) {
+    error(errors, "date-format", 1, `${sourcePath}: date 必须是 2026-09-18 或 2026-09-18 14:39:00`);
+  }
+  if (typeof data.cover === "string" && data.cover.trim() && !isExternalAsset(data.cover.trim())) {
+    const coverPath = path.join(siteRoot, "content", "covers", data.cover.trim());
+    if (!fs.existsSync(coverPath)) {
+      error(errors, "missing-cover", 1, `${sourcePath}: 找不到封面 ${data.cover}`);
+    }
+  }
+  checkReferences(data, sourcePath, errors);
+  scanBody(errors, parsed.content, absolute, sourcePath);
+  return { file: sourcePath, errors };
+};
+
+const files = process.argv.slice(2);
+if (!files.length) {
+  process.stderr.write("用法：garden check content/posts/文章.md\n");
+  process.exit(1);
+}
+
+const results = files.map((file) => checkFile(file));
+const ok = results.every((result) => result.errors.length === 0);
+process.stdout.write(`${JSON.stringify({ ok, results }, null, 2)}\n`);
+process.exit(ok ? 0 : 1);

package/templates/site/README.md

@@ -8,6 +8,8 @@ make new TITLE="你好，世界" SLUG=hello
 make dev
 ```
 
-第一次 `npx garden dev` 会补齐 Makefile、写稿脚本和图表 skill。Cursor / Codex 打开这个仓库后会读到 `.agents/skills/garden-interactive-chart`。要更新 skill，再运行 `npx garden skill`。
+第一次 `npx garden dev` 会补齐 Makefile 和 skill，并创建 `.env.local`。Cursor / Codex 打开这个仓库后会读到 `.agents/skills/`。要更新 skill，再运行 `npx garden skill`。
+
+评论默认关闭。发布前打开 [Giscus](https://giscus.app/zh-CN)，把仓库、仓库 ID、分类、分类 ID 写入 `.env.local`，并在 GitHub Actions Variables 设置同名的 `GISCUS_REPO`、`GISCUS_REPO_ID`、`GISCUS_CATEGORY`、`GISCUS_CATEGORY_ID`。留空会让发布失败。确定不开放评论时，把 `GISCUS_DISABLED` 设为 `1`。
 
 升级引擎：把 `package.json` 里的 `hd-garden` 改到新版本，例如 `^0.4.0`，再运行 `npm install`。