hd-garden 0.3.6 → 0.3.7

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/bin/garden.mjs

@@ -174,14 +174,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() {
@@ -252,24 +245,27 @@ function initSite() {
   process.stdout.write("  make dev\n");
 }
 
-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 +277,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 +309,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.7",
   "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,6 @@ 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。Cursor / Codex 打开这个仓库后会读到 `.agents/skills/`。要更新 skill，再运行 `npx garden skill`。
 
 升级引擎：把 `package.json` 里的 `hd-garden` 改到新版本，例如 `^0.4.0`，再运行 `npm install`。