hd-garden 0.8.0 → 0.8.2

package/docs/handbook/components/figure.md

@@ -1,72 +1,59 @@
 ---
 title: 分区结构图（figure）
 navTitle: 分区结构图
-description: 为 SVG 结构图加上分区高亮按钮，点击切换对应区域与文字说明。
+description: 一张带切换按钮的结构图，点到哪个部分就高亮并显示对应说明。
 section: components
 order: 36
 badge: figure
 ---
 
-在 `garden` 想法块里写一句「用 `figure` 画一张静态发布流程的结构图，点到哪一步就高亮并显示那一步的说明」，Agent 会按 `garden-ui` skill 生成下面的 `garden figure`（手写格式附后）。
-
 ```garden figure
 caption: 点击上方按钮切换高亮各步骤
 svg: |
-  <svg viewBox="0 0 680 110" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)">
-    <rect data-p="sync" x="12" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <text data-p="sync" x="110" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">1. garden sync</text>
-    <text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">解析 Markdown 与图片尺寸</text>
-    <path d="M214 55 H236" stroke="var(--muted)" stroke-width="1.5"/>
-    <rect data-p="build" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <text data-p="build" x="340" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">2. garden build</text>
-    <text data-p="build" x="340" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">生成静态页面与搜索索引</text>
-    <path d="M444 55 H466" stroke="var(--muted)" stroke-width="1.5"/>
-    <rect data-p="validate" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <text data-p="validate" x="570" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">3. pages:validate</text>
-    <text data-p="validate" x="570" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">检查 index.html 与禁用文件</text>
+  <svg viewBox="0 0 560 194" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)" style="max-width: 380px; margin-inline: auto">
+    <rect data-p="sync" x="2" y="4" width="180" height="186" rx="16" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="2.5"/>
+    <text data-p="sync" x="92" y="42" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">1. garden</text>
+    <text data-p="sync" x="92" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">sync</text>
+    <text data-p="sync" x="92" y="108" text-anchor="middle" font-size="24" fill="var(--muted)">解析</text>
+    <text data-p="sync" x="92" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">Markdown 与</text>
+    <text data-p="sync" x="92" y="166" text-anchor="middle" font-size="24" fill="var(--muted)">图片尺寸</text>
+    <path d="M183.5 97 H188.5" stroke="var(--muted)" stroke-width="2.5"/>
+    <rect data-p="build" x="190" y="4" width="180" height="186" rx="16" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="2.5"/>
+    <text data-p="build" x="280" y="42" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">2. garden</text>
+    <text data-p="build" x="280" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">build</text>
+    <text data-p="build" x="280" y="108" text-anchor="middle" font-size="24" fill="var(--muted)">生成静态页面</text>
+    <text data-p="build" x="280" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">与搜索索引</text>
+    <path d="M371.5 97 H376.5" stroke="var(--muted)" stroke-width="2.5"/>
+    <rect data-p="validate" x="378" y="4" width="180" height="186" rx="16" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="2.5"/>
+    <text data-p="validate" x="468" y="42" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">3. pages:</text>
+    <text data-p="validate" x="468" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">validate</text>
+    <text data-p="validate" x="468" y="108" text-anchor="middle" font-size="24" fill="var(--muted)">检查</text>
+    <text data-p="validate" x="468" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">index.html 与</text>
+    <text data-p="validate" x="468" y="166" text-anchor="middle" font-size="24" fill="var(--muted)">禁用文件</text>
   </svg>
 parts:
   - id: sync
     label: 1. 同步内容
-    text: 扫描 `content/` 与 `docs/handbook/`，复制随文附件并生成 `.garden/generated-content.ts`。
+    text: 扫描正文与随文附件，生成站点内容数据。
   - id: build
     label: 2. 构建页面
-    text: 根据 `STATIC_EXPORT=1` 预渲染所有页面路由，输出 RSS、sitemap 与全文搜索文件。
+    text: 预渲染所有页面路由，输出 RSS、sitemap 与全文搜索文件。
   - id: validate
     label: 3. 导出校验
-    text: 运行 pages:validate，确认导出目录里有 `index.html`，且没有 `.env`、源码目录、`.map` 或 `.md` 文件和软链接。
+    text: 确认导出目录里有 `index.html`，且没有混入源码或配置文件。
 ```
 
+- **什么时候用**：一张架构图或数据流图，读者点一个区域就能看清那一部分做什么。
+- **什么时候不用**：不需要分区点击说明的普通流程图或截图，直接贴图片或画 Mermaid 图。
+
+可以这样对 AI 说：
+
 ````markdown
-```garden figure
-caption: 点击上方按钮切换高亮各步骤
-svg: |
-  <svg viewBox="0 0 680 110" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)">
-    <rect data-p="sync" x="12" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <text data-p="sync" x="110" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">1. garden sync</text>
-    <text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">解析 Markdown 与图片尺寸</text>
-    <rect data-p="build" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <rect data-p="validate" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-  </svg>
-parts:
-  - id: sync
-    label: 1. 同步内容
-    text: 扫描 `content/` 与 `docs/handbook/`，复制随文附件并生成 `.garden/generated-content.ts`。
-  - id: build
-    label: 2. 构建页面
-    text: 根据 `STATIC_EXPORT=1` 预渲染所有页面路由，输出 RSS、sitemap 与全文搜索文件。
-  - id: validate
-    label: 3. 导出校验
-    text: 运行 pages:validate，确认导出目录里有 `index.html`，且没有 `.env`、源码目录、`.map` 或 `.md` 文件和软链接。
+```garden
+画一张静态发布流程的结构图，点到哪一步就高亮那一步并显示说明。
 ```
 ````
 
-- **用**：展示模块架构或数据流向，需要读者点击按钮逐块查看对应区域职责时（SVG 内优先使用 `var(--well)`、`var(--ink)`、`var(--muted)` 等主题变量以兼容深色模式）。
-- **别用**：不需要分区点击说明的普通流程图或截图，直接用标准 Markdown 图片或 `mermaid` 代码块。
+## 字段说明
 
-| 字段 | 必填 | 类型 | 说明 |
-| :--- | :--- | :--- | :--- |
-| `svg` | 与 `image` 二选一 | 多行字符串 | 内联 `<svg>` 源码；在需要高亮的分组上标注 `data-p="<id>"` |
-| `image` | 与 `svg` 二选一 | 路径字符串 | 普通图片路径（可写成 `{ src, alt }`） |
-| `parts` | 否 | `{ id, label, text }[]` | 顶部分区切换按钮及底部对应的说明文字 |
-| `caption` | 否 | 字符串 | 图框下方的图注说明 |
+全部字段、默认值、取值限制和报错代码见 [组件参考 · figure](/garden/reference/figure)。

package/docs/handbook/components/file.md

@@ -1,34 +1,29 @@
 ---
 title: 文件下载与预览（file）
 navTitle: 文件下载与预览
-description: 提供单个或一组附件下载，自动显示格式与大小，支持在页内展开预览。
+description: 给读者提供一份或一组可下载的文件，支持在当前页展开预览。
 section: components
 order: 39
 badge: file
 ---
 
-在 `garden` 想法块里写一句「用 `file` 给读者一份可以下载和页内预览的发布前检查清单」，Agent 会按 `garden-ui` skill 生成下面的 `garden file`（手写格式附后）。
-
 ```garden file
 src: ./file/checklist.md
 title: 发布前检查清单
 note: Markdown 附件示例，可点击「预览」在当前页展开阅读，或直接下载原文件
 ```
 
+- **什么时候用**：随文章提供配置文件、PDF、压缩包或 Markdown 附件供读者下载与页内预览。
+- **什么时候不用**：只是引用一个外部网页时用[知识卡片](/garden/components/card)；正文里本来就要直接展示的配图直接贴图片。
+
+可以这样对 AI 说：
+
 ````markdown
-```garden file
-src: ./file/checklist.md
-title: 发布前检查清单
-note: Markdown 附件示例，可点击「预览」在当前页展开阅读，或直接下载原文件
+```garden
+把同目录下的 checklist.md 放成附件，让读者可以在页面里预览或下载。
 ```
 ````
 
-- **用**：随文章提供配置文件、数据表、PDF、图片或 Markdown 附件供读者下载与页内预览时（多文件可用 `files` 数组）。
-- **别用**：正文里本来就要直接展示的配图用标准 Markdown 图片语法 `![]()`，不要放进 `file` 组件。
+## 字段说明
 
-| 字段 | 必填 | 类型 | 说明 |
-| :--- | :--- | :--- | :--- |
-| `src` | 单文件必填 | 路径或完整链接 | 相对当前 Markdown 文件的本地路径（不得越出 `content/`）、`/public` 路径或 `https://` 链接 |
-| `title` | 否 | 字符串 | 显示的文件标题（默认取文件名；多文件模式下作为分组标题） |
-| `note` | 否 | 字符串 | 文件名下方的简短说明 |
-| `files` | 多文件必填 | `{ src, title?, note? }[]` | 一次列出多个文件时使用（与顶层 `src` 二选一） |
+全部字段、默认值、取值限制和报错代码见 [组件参考 · file](/garden/reference/file)。

package/docs/handbook/components/html.md

@@ -1,17 +1,14 @@
 ---
 title: 嵌入网页片段（html）
 navTitle: 嵌入网页片段
-description: 在沙盒 iframe 中运行独立的 HTML、CSS 与 JavaScript 演示片段。
+description: 在沙盒中运行一段独立的网页小工具、画布动画或演示。
 section: components
 order: 37
 badge: html
 ---
 
-在 `garden` 想法块里写一句「用 `html` 嵌一个小工具，输入文字就实时算出字符数」，Agent 会按 `garden-ui` skill 生成下面的 `garden html`（手写格式附后）。
-
 ```garden html
 title: 字符长度与预计阅读耗时小工具
-height: 156
 code: |
   <!doctype html>
   <html lang="zh-CN">
@@ -36,34 +33,17 @@ code: |
   </html>
 ```
 
+- **什么时候用**：内置组件画不出来的画布动画、物理模拟或独立小工具。
+- **什么时候不用**：只需要拖动滑杆算公式时用[可调公式与参数](/garden/components/interactive)；静态图表或结构图优先用对应组件。
+
+可以这样对 AI 说：
+
 ````markdown
-```garden html
-title: 字符长度与预计阅读耗时小工具
-height: 156
-code: |
-  <!doctype html>
-  <html lang="zh-CN">
-  <head><meta charset="utf-8" /></head>
-  <body>
-    <input id="txt" value="把文章放在自己的 Git 仓库里，推送后自动构建。" />
-    <div>当前字符数：<strong id="count">23</strong> 字</div>
-    <script>
-      const input = document.getElementById("txt");
-      const count = document.getElementById("count");
-      input.addEventListener("input", () => { count.textContent = String(input.value.length); });
-    </script>
-  </body>
-  </html>
+```garden
+做一个网页小工具，让读者输入一句话就能实时看到字符数。
 ```
 ````
 
-- **用**：需要运行自定义 DOM 脚本、Canvas 绘图或独立 HTML 页面片段时（支持 `code` 内联或 `src` 引用文章同名目录下的 `.html` 文件）。
-- **别用**：只需要滑杆调参数算公式时用 [`interactive`](/garden/components/interactive)；静态结构图用 [`figure`](/garden/components/figure)。
+## 字段说明
 
-| 字段 | 必填 | 类型 | 说明 |
-| :--- | :--- | :--- | :--- |
-| `src` | 与 `code` 二选一 | 相对路径字符串 | 引用与当前 Markdown 同目录（或同名子目录）下的 `.html` 文件 |
-| `code` | 与 `src` 二选一 | 多行字符串 | 直接内联编写的 HTML 源码（也可用别名 `html`） |
-| `title` | 建议 | 字符串 | 卡片顶部栏标题及 `iframe` 的无障碍标题 |
-| `height` | 否 | 数字 | 初始高度（像素，默认 `260`；加载后也会随内容高度自动调整） |
-| `caption` | 否 | 字符串 | 底部的图注说明 |
+全部字段、默认值、取值限制和报错代码见 [组件参考 · html](/garden/reference/html)。

package/docs/handbook/components/interactive.md

@@ -1,14 +1,12 @@
 ---
 title: 可调公式与参数（interactive）
 navTitle: 可调公式与参数
-description: 提供滑杆或单选按钮，让读者调整变量并实时计算公式与图表结果。
+description: 让读者拖动滑杆或切换选项，实时看到公式和图表的计算结果。
 section: components
 order: 38
 badge: interactive
 ---
 
-在 `garden` 想法块里写一句「让读者拖动字数、阅读速度和配图数，看预计阅读时间怎么变」，Agent 会按 `garden-ui` skill 生成下面的 `garden interactive`（手写格式附后）。
-
 ```garden interactive #reading-time
 caption: 示例：按字数、阅读速度和配图数估算一篇文章的阅读时间。数字只用来演示组件，不是统计结果。
 ---
@@ -27,41 +25,17 @@ caption: 示例：按字数、阅读速度和配图数估算一篇文章的阅
 </Chart>
 ```
 
-````markdown
-```garden interactive #reading-time
-caption: 示例：按字数、阅读速度和配图数估算一篇文章的阅读时间。数字只用来演示组件，不是统计结果。
----
-<State words={6000} speed={400} images={8} />
-<Let textMinutes={round(words / speed)} />
-<Let imageMinutes={round(images * 12 / 60)} />
-<Let parts={[{ part: "正文", minutes: textMinutes }, { part: "配图", minutes: imageMinutes }]} />
+- **什么时候用**：公式或结论随多个变量变化，读者自己拧一下参数比读干巴巴的数字更容易明白。
+- **什么时候不用**：一次简单乘法就能算清（触发 `interactive-trivial`），或者只是把几段文字拆成步骤而没有任何状态与输入控件（触发 `steps-prose`）时，直接写在正文里。
 
-<Slider bind="words" label="正文字数" min={1000} max={20000} step={500} unit="字" />
-<Slider bind="speed" label="阅读速度" min={200} max={800} step={50} unit="字/分钟" />
-<Slider bind="images" label="配图数" min={0} max={30} step={1} unit="张" />
+可以这样对 AI 说：
 
-<Stat label="示例：预计阅读时间" value={textMinutes + imageMinutes} unit="分钟" hint="配图按每张 12 秒估算" />
-<Chart data={parts} x={part} yLabel="分钟">
-  <Bar y={minutes} label="示例" />
-</Chart>
+````markdown
+```garden
+让读者拖动正文字数、阅读速度和配图数，看预计阅读时间怎么变。
 ```
 ````
 
-- **用**：解释带多个变量的数学关系、容量估算或参数权衡，需要读者拖动滑杆实时观察结果变化时。
-- **别用**：只有 `<Steps>` 而没有任何状态或输入控件，会报 `steps-prose` 错误；所有 `<Let>` 都只是一次乘法（形如 `a * b`），会报 `interactive-trivial` 错误。遇到这两种情况，改用普通段落。
-
-分隔线 `---` 上方是块头，下方是标签。常用的写法：
-
-| 字段或标签 | 必填 | 说明 |
-| :--- | :--- | :--- |
-| `#reading-time` | 建议 | 写在围栏头，块的标识，只能用小写字母、数字和连字符 |
-| `caption` | 是 | 一句话说明这块交互想让读者看到什么 |
-| `intent` | 否 | 这块交互由哪句想法编译而来，写成文字 |
-| `expect` | 否 | 数组，每条写成 `{ given: {...}, 名字: 期望值 }`，检查时会按给定状态算一遍 |
-| `<State />` | 是 | 声明会变的量和默认值，例如 `<State words={6000} />` |
-| `<Let />` | 否 | 由别的量算出来的值，也可以写数据数组 |
-| `<Slider />` / `<Choice />` / `<Toggle />` | 是 | 输入控件，用 `bind` 绑定一个状态；`Slider` 必填 `label`、`min`、`max` |
-| `<Stat />` | 否 | 显示一个醒目的数字，必填 `label` 与 `value` |
-| `<Chart />` | 否 | 用 `sweep` 画函数曲线，或用 `data` 加 `<Bar>` / `<Line>` 画数据 |
+## 字段说明
 
-全部标签和属性见 `npx garden ui catalog` 生成的组件目录。
+全部字段、默认值、取值限制和报错代码见 [组件参考 · interactive](/garden/reference/interactive)。

package/docs/handbook/components/list.md

@@ -0,0 +1,65 @@
+---
+title: 图标列表（list）
+navTitle: 图标列表
+description: 用线条图标配短句列出几条并列动作，或带小标题列出分步做法。
+section: components
+order: 41
+badge: list
+---
+
+```garden list
+items:
+  - icon: search
+    text: 搜索这个月的书名
+  - icon: eye
+    text: 看了 3 篇书评
+  - icon: heart
+    text: 收藏了活动页面
+  - icon: chat
+    text: 在群里问能不能只听不说
+```
+
+- **什么时候用**：几条并列的行为、信号或做法，每条配一个线条图标；或者带小标题与分段说明的做法列表。
+- **什么时候不用**：只是一组带编号的先后顺序时用普通有序列表；按时间演进的节点用[时间线](/garden/components/timeline)。
+
+可以这样对 AI 说：
+
+````markdown
+```garden
+把新成员报名前常做的四件事列成带图标的列表：搜书名、看书评、收藏页面、在群里问能不能只听不说。
+```
+````
+
+## 带小标题的分段步骤列表
+
+当任一条目包含 `title` 时，组件自动切换为带分隔线的步骤列表，`text` 可以写多段说明：
+
+```garden list
+items:
+  - icon: flask
+    title: 实验一：一个月读一本是不是太多？
+    text:
+      - 前两次活动分别选一本中篇和一本长篇，记录每个人读完的比例。
+      - 读完比例明显下降时，下次改成只读前半本。
+  - icon: chat
+    title: 实验二：怎样让第一次来的人开口？
+    text:
+      - 一半活动先轮流说一句话，另一半直接自由讨论。
+      - 比较第一次来的人发言的次数。
+  - icon: bell
+    title: 实验三：提醒要提前几天发？
+    text:
+      - 分别在活动前三天和前一天发提醒，看到场人数有没有差别。
+```
+
+可以这样对 AI 说：
+
+````markdown
+```garden
+把这三个小实验列成带图标和小标题的步骤：确认阅读量、让新成员开口、测试提前几天发提醒。
+```
+````
+
+## 字段说明
+
+全部字段、默认值、取值限制和报错代码见 [组件参考 · list](/garden/reference/list)。

package/docs/handbook/components/relations.md

@@ -0,0 +1,95 @@
+---
+title: 关系图（relations）
+navTitle: 关系图
+description: 把三到六个要素排成环或中心辐射结构，画出谁影响谁、哪些是双向的。
+section: components
+order: 40
+badge: relations
+---
+
+```garden relations
+items:
+  - title: 选书
+    text: 定下这个月读什么
+  - title: 共读
+    text: 每周读完约定的章节
+  - title: 讨论
+    text: 见面聊各自的看法
+  - title: 复盘
+    text: 记下下次要改的地方
+links:
+  - from: 1
+    to: 2
+  - from: 2
+    to: 3
+  - from: 3
+    to: 4
+  - from: 4
+    to: 1
+  - from: 3
+    to: 1
+    style: dashed
+    label: 影响选书
+  - from: 2
+    to: 4
+    style: dashed
+caption: 四个环节互相提供信息，而不是按固定顺序走一遍。
+```
+
+- **什么时候用**：三到六个关键要素，读者需要看清谁影响谁、哪些是双向的；首尾相接的循环或单中心向外辐射的关系都用它。
+- **什么时候不用**：要素更多、有条件分支时用 Mermaid 流程图；只走一遍的步骤用[图标列表](/garden/components/list)。
+
+可以这样对 AI 说：
+
+````markdown
+```garden
+把选书、共读、讨论、复盘这四个环节的循环关系画出来，再标出讨论影响选书、共读影响复盘。
+```
+````
+
+## 中心节点与外圈要素（`center`）
+
+当其中一个要素居中、其余要素围在外圈时，在 `items` 与 `links` 之间写 `center: <序号或标题>`（不会自动猜测中心节点；指定的要素放在正中，其余要素从正上方起顺时针均布在外圈）：
+
+```garden relations
+items:
+  - title: 组织者
+    text: 每月发一次通知
+  - title: 成员
+    text: 八到十个邻居
+  - title: 场地
+    text: 咖啡馆或图书馆
+  - title: 书单
+    text: 大家轮流提名
+center: 组织者
+links:
+  - from: 1
+    to: 2
+    label: 邀请
+  - from: 1
+    to: 3
+    label: 预约
+  - from: 1
+    to: 4
+    label: 汇总
+  - from: 2
+    to: 4
+    style: dashed
+    direction: both
+    label: 提名
+caption: 组织者放在正中，连着外圈的其余三个；成员和书单互相影响。
+```
+
+可以这样对 AI 说：
+
+````markdown
+```garden
+把组织者放在正中间，外圈放成员、场地、书单：组织者分别邀请成员、预约场地、汇总书单，成员和书单之间双向提名。
+```
+````
+
+各要素按椭圆均布（不设 `center` 时从正上方 12 点钟方向起顺时针排列；设了 `center` 时中心节点居于正中，其余要素在外圈从正上方起顺时针均布），外圈相邻要素之间的连线向外轻弧弯曲，跨节点或连向中心的连线从中间直穿而过。
+
+## 字段说明
+
+全部字段、默认值、取值限制和报错代码见 [组件参考 · relations](/garden/reference/relations)。

package/docs/handbook/components/stat.md

@@ -1,14 +1,12 @@
 ---
 title: 数字指标（stat）
 navTitle: 数字指标
-description: 将 2～4 组关键数字、单位与简短说明并排展示。
+description: 把 2～4 个关键数字、单位与一句说明并排摆出来。
 section: components
 order: 32
 badge: stat
 ---
 
-在 `garden` 想法块里写一句「用 `stat` 列出正文列、宽图区、宽表区三个宽度上限」，Agent 会按 `garden-ui` skill 生成下面的 `garden stat`（手写格式附后）。
-
 ```garden stat
 items:
   - label: 正文列宽
@@ -25,33 +23,17 @@ items:
     caption: 左右各最多向外延伸 300px
 ```
 
+- **什么时候用**：把分散在段落里的两到四个关键数字、阈值或规格并排展示。
+- **什么时候不用**：只有一个数字时留在正文句子里；数字会随读者选择变化时让 AI 做成[可调公式与参数](/garden/components/interactive)；有多行多列维度时直接用表格。
+
+可以这样对 AI 说：
+
 ````markdown
-```garden stat
-items:
-  - label: 正文列宽
-    value: "740"
-    unit: px
-    caption: 默认阅读列宽度
-  - label: 宽图上限
-    value: "1040"
-    unit: px
-    caption: 左右各最多向外延伸 150px
-  - label: 宽表上限
-    value: "1340"
-    unit: px
-    caption: 左右各最多向外延伸 300px
+```garden
+把正文列宽 740px、宽图上限 1040px 和宽表上限 1340px 三个数字并排摆出来。
 ```
 ````
 
-- **用**：把分散在段落里的 2～4 个核心数字、阈值或规格并排摆出来时。
-- **别用**：只有一个数字时直接写在正文句子里；有多行多列维度时改用 Markdown 表格。
+## 字段说明
 
-| 字段 | 必填 | 类型 | 说明 |
-| :--- | :--- | :--- | :--- |
-| `items` | 否 | 对象数组 | 展示多项指标时使用；单卡可直接把字段写在顶层 |
-| `label` | 是 | 字符串 | 指标名称（显示在数字上方） |
-| `value` | 是 | 字符串或数字 | 核心数值（等宽大字号显示） |
-| `unit` | 否 | 字符串 | 紧跟在数值右侧的单位 |
-| `caption` | 否 | 字符串 | 数值下方的简短说明 |
-| `text` | 否 | 字符串 | 补充说明文字 |
-| `source` | 否 | 字符串或 `{ title, url }` | 数据出处角标 |
+全部字段、默认值、取值限制和报错代码见 [组件参考 · stat](/garden/reference/stat)。

package/docs/handbook/components/timeline.md

@@ -1,52 +1,37 @@
 ---
 title: 时间线（timeline）
 navTitle: 时间线
-description: 按时间或步骤顺序排列版本演进、排查过程与关键节点。
+description: 按时间或阶段顺序排开版本演进、排查经过或关键节点。
 section: components
 order: 34
 badge: timeline
 ---
 
-在 `garden` 想法块里写一句「用 `timeline` 按顺序列出静态发布流水线的三个步骤」，Agent 会按 `garden-ui` skill 生成下面的 `garden timeline`（手写格式附后）。
-
 ```garden timeline
 title: 静态发布流水线执行步骤
 items:
   - date: 步骤 1
     title: 同步内容与静态资源
-    text: 运行 `npx garden sync`，校验 Front Matter、复制图片附件并生成搜索索引与 RSS。
+    text: 校验文章信息、复制图片附件并生成搜索索引与 RSS。
   - date: 步骤 2
     title: 构建静态站点产物
-    text: 运行 `STATIC_EXPORT=1 npx garden build`，把全部路由预渲染到 `dist/client/`。
+    text: 把全部页面预渲染到静态目录。
   - date: 步骤 3
     title: 校验静态页面并部署
-    text: 运行 `npm run pages:validate` 确认有 `index.html`，且没有混入 `.env`、源码目录、`.map` 或 `.md` 文件和软链接，通过后发布到 GitHub Pages。
+    text: 检查导出文件完整无误后发布到 GitHub Pages。
 ```
 
+- **什么时候用**：版本演进、故障排查时间点或按先后顺序推进的阶段。
+- **什么时候不用**：没有时间顺序的并列要点用普通列表或[图标列表](/garden/components/list)。
+
+可以这样对 AI 说：
+
 ````markdown
-```garden timeline
-title: 静态发布流水线执行步骤
-items:
-  - date: 步骤 1
-    title: 同步内容与静态资源
-    text: 运行 `npx garden sync`，校验 Front Matter、复制图片附件并生成搜索索引与 RSS。
-  - date: 步骤 2
-    title: 构建静态站点产物
-    text: 运行 `STATIC_EXPORT=1 npx garden build`，把全部路由预渲染到 `dist/client/`。
-  - date: 步骤 3
-    title: 校验静态页面并部署
-    text: 运行 `npm run pages:validate` 确认有 `index.html`，且没有混入 `.env`、源码目录、`.map` 或 `.md` 文件和软链接，通过后发布到 GitHub Pages。
+```garden
+按时间顺序把静态发布流水线的三个阶段列出来。
 ```
 ````
 
-- **用**：按先后顺序记录故障排查时间点、演进阶段或构建流水线步骤（至少 2 个节点）时。
-- **别用**：没有时间或先后顺序的并列要点，直接用无序列表。
+## 字段说明
 
-| 字段 | 必填 | 类型 | 说明 |
-| :--- | :--- | :--- | :--- |
-| `title` | 否 | 字符串 | 时间线顶部的总标题 |
-| `items` | 是 | 对象数组（至少 2 项） | 按顺序排列的节点列表 |
-| `items[].date` | 否 | 字符串 | 时间、阶段或步骤编号（显示在节点标题上方） |
-| `items[].title` | 是 | 字符串 | 节点标题 |
-| `items[].text` | 否 | 字符串 | 节点详细说明 |
-| `items[].source` | 否 | 字符串或 `{ title, url }` | 节点出处角标 |
+全部字段、默认值、取值限制和报错代码见 [组件参考 · timeline](/garden/reference/timeline)。