hd-garden 0.14.11 → 0.14.13

package/bin/garden.mjs

@@ -9,6 +9,7 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import { editorsInstall, offerEditorsOnce } from "../scripts/editors-kit.mjs";
 import { gardenPackageRoot, gardenSiteRoot } from "../scripts/garden-paths.mjs";
+import { ensureVinextRuntime, samePath } from "../scripts/vinext-runtime.mjs";
 import { langOf, siteCliLang } from "../ui/core/cli-locale.mjs";
 
 const siteRoot = gardenSiteRoot();
@@ -17,10 +18,17 @@ const command = args[0] ?? "help";
 const rest = args.slice(1);
 
 function siteEnv(extra = {}) {
+  const moduleRoots = [
+    path.join(siteRoot, "node_modules"),
+    path.join(gardenPackageRoot, "node_modules"),
+  ].filter((dir) => fs.existsSync(dir));
+  const inherited = (process.env.NODE_PATH ?? "").split(path.delimiter).filter(Boolean);
+  const nodePath = [...new Set([...moduleRoots, ...inherited])].join(path.delimiter);
   return {
     ...process.env,
     ...extra,
     GARDEN_SITE: siteRoot,
+    ...(nodePath ? { NODE_PATH: nodePath } : {}),
     WRANGLER_LOG_PATH:
       process.env.WRANGLER_LOG_PATH ?? path.join(siteRoot, ".wrangler", "wrangler.log"),
   };
@@ -59,27 +67,6 @@ function resolveVinext() {
   }
 }
 
-function samePath(left, right) {
-  return path.resolve(left) === path.resolve(right);
-}
-
-function isPackageSite() {
-  return samePath(siteRoot, gardenPackageRoot);
-}
-
-function ensureLink(from, to) {
-  fs.mkdirSync(path.dirname(to), { recursive: true });
-  try {
-    const stat = fs.lstatSync(to);
-    if (stat.isSymbolicLink() && fs.readlinkSync(to) === from) return;
-    if (stat.isSymbolicLink()) fs.unlinkSync(to);
-    else return;
-  } catch (error) {
-    if (error.code !== "ENOENT") throw error;
-  }
-  fs.symlinkSync(from, to);
-}
-
 function ensurePublic() {
   const dest = path.join(siteRoot, "public");
   fs.mkdirSync(dest, { recursive: true });
@@ -128,61 +115,12 @@ function ensureEnv() {
   }
 }
 
-function resolveNodeModules() {
-  const siteModules = path.join(siteRoot, "node_modules");
-  const packageModules = path.join(gardenPackageRoot, "node_modules");
-  if (fs.existsSync(path.join(siteModules, "vinext"))) return siteModules;
-  if (fs.existsSync(path.join(packageModules, "vinext"))) return packageModules;
-  return siteModules;
-}
-
 function vinextRoot() {
-  if (isPackageSite()) return gardenPackageRoot;
-
-  const runtime = path.join(siteRoot, ".garden", "runtime");
-  fs.mkdirSync(runtime, { recursive: true });
-
-  const links = [
-    ["app", path.join(gardenPackageRoot, "app")],
-    ["build", path.join(gardenPackageRoot, "build")],
-    ["worker", path.join(gardenPackageRoot, "worker")],
-    [".openai", path.join(gardenPackageRoot, ".openai")],
-    ["vite.config.ts", path.join(gardenPackageRoot, "vite.config.ts")],
-    ["next.config.ts", path.join(gardenPackageRoot, "next.config.ts")],
-    ["postcss.config.mjs", path.join(gardenPackageRoot, "postcss.config.mjs")],
-    ["tsconfig.json", path.join(gardenPackageRoot, "tsconfig.json")],
-    ["package.json", path.join(gardenPackageRoot, "package.json")],
-    ["node_modules", resolveNodeModules()],
-    ["public", path.join(siteRoot, "public")],
-    ["content", path.join(siteRoot, "content")],
-    ["site.config.yaml", path.join(siteRoot, "site.config.yaml")],
-  ];
-
-  for (const name of [".env", ".env.local"]) {
-    const from = path.join(siteRoot, name);
-    if (fs.existsSync(from)) links.push([name, from]);
-  }
-
-  for (const [name, from] of links) {
-    if (fs.existsSync(from) || name === "public" || name === "content") {
-      if ((name === "public" || name === "content") && !fs.existsSync(from)) {
-        fs.mkdirSync(from, { recursive: true });
-      }
-      ensureLink(from, path.join(runtime, name));
-    }
-  }
-
-  // English sites: the runtime manifest is a copy with the English description, not a link.
-  // Remove the link first so the write never goes through it into the engine's own package.json.
-  if (siteCliLang(siteRoot) === "en") {
-    const target = path.join(runtime, "package.json");
-    const manifest = JSON.parse(fs.readFileSync(path.join(gardenPackageRoot, "package.json"), "utf8"));
-    manifest.description = "A personal blog engine: write in Markdown, publish with GitHub Pages.";
-    fs.rmSync(target, { force: true });
-    fs.writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`);
-  }
-
-  return runtime;
+  return ensureVinextRuntime({
+    siteRoot,
+    gardenPackageRoot,
+    lang: siteCliLang(siteRoot),
+  });
 }
 
 function publishDist(fromRoot) {
@@ -483,12 +421,12 @@ function installSkill(destinationRoot = siteRoot, { lang = siteCliLang(destinati
 
 function help() {
   process.stdout.write(`Garden 命令：
-  garden dev              同步内容并本地预览
+  garden dev [--worker]   同步内容并本地预览（默认 Node RSC；--worker 使用 Cloudflare workerd）
   garden build            同步内容并构建静态站点
   garden start            启动已构建的服务
   garden sync             只从 Markdown 生成索引
   garden new              创建文章草稿
-  garden embed            拉取外链摘要
+  garden embed            打印可粘贴的规范化视频链接或网页地址
   garden links            重新拉取外链图标与卡片元数据（dev / build 时也会自动做）
   garden images           读取新的远程图片尺寸，写入 .garden/image-sizes.json（build 时会自动做）
   garden files            读取 Compose <file> 里远程文件的大小，写入 file-sizes.json（build 时会自动做）
@@ -521,8 +459,10 @@ async function main() {
       // Scoped to this CLI process: sync, Vinext and its watcher inherit it;
       // later build/check commands do not.
       process.env.CONTENT_INCLUDE_DRAFTS ??= "1";
+      if (rest.includes("--worker")) process.env.GARDEN_DEV_WORKER = "1";
+      else process.env.GARDEN_DEV_WORKER ??= "0";
       ensureDevGitHubLogin();
-      await runVinext(["dev", ...rest]);
+      await runVinext(["dev", ...rest.filter((arg) => arg !== "--worker")]);
       break;
     case "build":
       // Favicons are refetched on every build; failures fall back to link-assets.json.

package/docs/handbook/components/compose.md

@@ -9,7 +9,9 @@ badge: compose
 
 `garden compose` 是唯一的 Garden 作者入口。在围栏内组合 Markdown、安全 HTML 内容岛、布局、资源、文件、关系图、选择卡与 Play 交互。具体能力、内容边界和默认样式见[组件参考](/garden/reference/compose)，完整可用属性以 `npx garden ui schema` 为准。
 
-需要 AI 生成结构图时，输入 `/garden` 选「compose（想法）」。文章里会插入一个 `garden compose` 围栏。你在里面用白话写清结构，再对 AI 说「编译这篇」，AI 就会把这句话留在 `<intent>` 里，并用 Markdown 叶子和组件标签拼出静态说明图。
+需要 AI 生成结构图时，输入 `/garden`，在图示列表里选一种（最后一项是「其他」）。选中后会直接插入一个 `garden compose` 围栏，里面是针对该图示的说明草稿。你补全材料和目标，再对 AI 说「编译这篇」；你的原话会留在 `<intent>` 里，结构则用 Markdown 叶子和组件标签拼出静态说明图。
+
+全部内置图示的名称、示意图、适用场景和推荐说明草稿，见[推荐图示](/garden/components/diagrams)。
 
 ## 怎么写
 

package/docs/handbook/components/diagrams/chart.md

@@ -0,0 +1,38 @@
+---
+title: "数据图"
+navTitle: "数据图"
+description: "适合把已有数字画成柱状、折线或占比"
+section: diagrams
+order: 131
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![数据图示意](./previews/chart.svg)
+
+适合把已有数字画成柱状、折线或占比。
+
+不要编造数据；结果可由公式随输入变化时，优先用参数调节图。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「数据图」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「数据图」是推荐起点：只用材料里的真实数据做图，标明轴和单位；不要编造数值
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/code-walkthrough.md

@@ -0,0 +1,38 @@
+---
+title: "代码走查"
+navTitle: "代码走查"
+description: "适合一行行看代码执行到哪、变量是多少"
+section: diagrams
+order: 161
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![代码走查示意](./previews/code-walkthrough.svg)
+
+适合一行行看代码执行到哪、变量是多少。
+
+只需要展示代码时用普通代码块；代码太长时先截关键段。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「代码走查」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「代码走查」是推荐起点：对着不长的关键代码，讲清每一步执行到哪一行、变量此刻是多少，不要改写原文代码的事实
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/columns-join.md

@@ -0,0 +1,38 @@
+---
+title: "关联图"
+navTitle: "关联图"
+description: "适合说明两边如何通过中间一项关联起来"
+section: diagrams
+order: 11
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![关联图示意](./previews/columns-join.svg)
+
+适合说明两边如何通过中间一项关联起来。
+
+没有中间连接关系时，不必强行加连接。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「关联图」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「关联图」是推荐起点：先写清两边各是什么、中间一项如何把两边接上，哪一块是重点
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/compare.md

@@ -0,0 +1,38 @@
+---
+title: "对比图"
+navTitle: "对比图"
+description: "适合比较两三种方案在同一条件下的差异"
+section: diagrams
+order: 91
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![对比图示意](./previews/compare.svg)
+
+适合比较两三种方案在同一条件下的差异。
+
+只是罗列各自特点、没有共同条件时，用普通表格或并列图即可。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「对比图」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「对比图」是推荐起点：只在有真实共同条件时做对比，保留各方事实，不要发明输赢或排序
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/converter.md

@@ -0,0 +1,38 @@
+---
+title: "换算图"
+navTitle: "换算图"
+description: "适合一个输入同时算出好几项结果"
+section: diagrams
+order: 151
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![换算图示意](./previews/converter.svg)
+
+适合一个输入同时算出好几项结果。
+
+只有一个结果时用参数调节图；各项要分别调时先拆开。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「换算图」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「换算图」是推荐起点：一个输入同时换算出多项结果，保留公式和单位，不要发明材料里没有的换算关系
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/facets.md

@@ -0,0 +1,38 @@
+---
+title: "并列图"
+navTitle: "并列图"
+description: "适合说明一件事的几个方面，没有先后顺序"
+section: diagrams
+order: 41
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![并列图示意](./previews/facets.svg)
+
+适合说明一件事的几个方面，没有先后顺序。
+
+没有先后就不要画成流程；没有同一条件的比较时，也不要画成对比图。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「并列图」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「并列图」是推荐起点：列出各方面的短名和说明，并写明这几块有没有严格先后
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/fan-out.md

@@ -0,0 +1,38 @@
+---
+title: "发散图"
+navTitle: "发散图"
+description: "适合说明先到一处，再同时连到好几处"
+section: diagrams
+order: 21
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![发散图示意](./previews/fan-out.svg)
+
+适合说明先到一处，再同时连到好几处。
+
+没有真正的先到再分支时，不要画成发散。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「发散图」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「发散图」是推荐起点：先写清谁先到谁，再同时连到哪几处，哪一处是重点
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/icon-rail.md

@@ -0,0 +1,38 @@
+---
+title: "图文列表"
+navTitle: "图文列表"
+description: "适合逐条说明互不依赖的内容"
+section: diagrams
+order: 61
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![图文列表示意](./previews/icon-rail.svg)
+
+适合逐条说明互不依赖的内容。
+
+这些条目没有先后依赖，不要画成流程，也不要写成要照着做的清单。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「图文列表」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「图文列表」是推荐起点：用图标带出一条条独立说明，标题和正文写在一起；这不是流程，不要加顺序箭头
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/inspect-grid.md

@@ -0,0 +1,38 @@
+---
+title: "格子图"
+navTitle: "格子图"
+description: "适合标出二维结构里哪几格特别、为什么"
+section: diagrams
+order: 201
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![格子图示意](./previews/inspect-grid.svg)
+
+适合标出二维结构里哪几格特别、为什么。
+
+只是普通数据表、没有哪一格要特别解释时，用普通表格即可。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「格子图」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「格子图」是推荐起点：用格子呈现二维结构，并指出需要特别解释的格子及其原因；不要把普通表格硬做成格子图
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/lanes.md

@@ -0,0 +1,38 @@
+---
+title: "时序图"
+navTitle: "时序图"
+description: "适合说明谁在什么时候向谁发了什么"
+section: diagrams
+order: 111
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![时序图示意](./previews/lanes.svg)
+
+适合说明谁在什么时候向谁发了什么。
+
+不是通用建模语言，也不支持任意分支、循环或自动布线。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「时序图」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「时序图」是推荐起点：按原文写出参与者和他们之间的消息方向与顺序，不要补出原文没有的分支或循环
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/layers.md

@@ -0,0 +1,38 @@
+---
+title: "分层图"
+navTitle: "分层图"
+description: "适合说明自上而下的层次，不必按顺序走完"
+section: diagrams
+order: 31
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![分层图示意](./previews/layers.svg)
+
+适合说明自上而下的层次，不必按顺序走完。
+
+层次不是自动变成必须按顺序走完的流程。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「分层图」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「分层图」是推荐起点：写出各层名称和哪些是重点，并说明是不是每次都按这个顺序走完
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````

package/docs/handbook/components/diagrams/other.md

@@ -0,0 +1,37 @@
+---
+title: "其他"
+navTitle: "其他"
+description: "适合现成图形无法表达、需要自由组合图文的内容"
+section: diagrams
+order: 211
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![其他示意](./previews/other.svg)
+
+适合现成图形无法表达、需要自由组合图文的内容。
+
+不要把列表里的常用图示当成合法白名单，也不要为此学习新语法。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+「其他」不是又一种现成模板。现成图示无法表达、或需要把几种内容放在一起时，在同一个 `garden compose` 里用任意 Markdown、安全 HTML，以及卡片、行列、步骤等基础块自由组合。推荐说明草稿不是语法课，也不要把列表当成合法白名单。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，在统一的 garden compose 里自由组合图文。现成图形无法表达、或需要把几种内容组合在一起时，用任意 Markdown / HTML 以及已有的基础块做成合适的说明。
+
+我的材料：
+- （粘贴要呈现的内容、关系和原文）
+
+我的表达目标：
+- （读者应该理解什么、重点是什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习新语法或写 CSS
+- 列表里的常用图示只是起点，不是合法白名单；没有现成配方也可以，先抽取真实关系再组合基础块
+- 不要把结果限制为某一个现成模板；需要时可以混合普通 Markdown、安全 HTML，以及卡片、行列、步骤等基础块
+```
+````

package/docs/handbook/components/diagrams/plan.md

@@ -0,0 +1,38 @@
+---
+title: "步骤清单"
+navTitle: "步骤清单"
+description: "适合读者照着一项项做，并回来查看进度"
+section: diagrams
+order: 191
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![步骤清单示意](./previews/plan.svg)
+
+适合读者照着一项项做，并回来查看进度。
+
+只是概念上的几个阶段时写列表或分步图；步骤之间要观察状态变化时用逐步演示。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 `/garden` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 `garden compose` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。
+
+````markdown
+```garden compose
+请根据我提供的材料和表达目标，用 garden compose 做一个「步骤清单」说明图。
+
+我的材料：
+- （粘贴原文条目和需要保留的措辞）
+
+我的表达目标：
+- （读者要一眼看出什么）
+
+请你：
+- 只根据材料组织内容，不要发明事实或结论
+- 自行处理图形语法、布局和手机阅读适配，不要让我学习标签或写 CSS
+- 「步骤清单」是推荐起点：按读者会照着做的顺序列出清单，保留原文步骤，不要把概念阶段硬写成待办
+- 推荐图示不是唯一合法写法；需要时仍可在同一 compose 里搭配必要的 Markdown / HTML 基础块
+- 不要另起一种作者围栏或新语法，只使用 garden compose
+```
+````