hd-garden 0.11.0 → 0.12.1

package/.agents/skills/garden-ui/SKILL.md

@@ -2,16 +2,20 @@
 name: garden-ui
 description: >-
   Compiles the `garden` idea blocks in one Garden post into garden components
-  (garden compose, or card / stat / compare / ... , or prose, or garden
+  (garden compose DIL, or card / stat / compare / ... , or prose, or garden
   html), fixes broken garden compose blocks, and suggests where a post could
-  use interaction. Older intent / ui blocks are handled the same way. Use when
-  the user says 编译这篇 / 编译想法 / 重编译 <id> / 这篇哪里适合交互, or pastes a
-  garden ui check fix prompt.
+  use interaction. Older intent / ui / interactive blocks are handled the same
+  way. Use when the user says 编译这篇 / 编译想法 / 重编译 <id> / 这篇哪里适合交互,
+  or pastes a garden ui check fix prompt.
 ---
 
 # 编译 Garden 交互块
 
-作者在稿里用不带名字的 `garden` 围栏写一句想法，这个 skill 把它变成 `garden compose`、`garden compose` 或别的 `garden` 组件。`garden compose` 若还是白话，就在同一围栏里填 YAML 树，不要改围栏类型。交互组件和设计规则在 `npx garden ui prompt` 的输出里，各 `garden` 组件的用途和示例在 `node_modules/hd-garden/templates/garden-blocks.md`（在引擎仓库里是 `templates/garden-blocks.md`），以这两份为准，不凭记忆写组件。
+作者在稿里用不带名字的 `garden` 围栏写一句想法，这个 skill 把它变成 `garden compose`、别的 `garden` 组件，或写回正文。
+
+**`garden compose` 写的是 DIL，不是 YAML：** 叶子是 Markdown，结构是 compose 目录里的**小写标签** + 设计 token。作者原话放进 `<intent>`（或块头 `intent:`）。围栏类型始终是 `garden compose`——静态说明图与可调 play 都是它。不要发明 YAML 槽，不要用 interactive 的 PascalCase 当作者输入。
+
+交互组件、compose 目录和设计规则在 `npx garden ui prompt` 的输出里；各 `garden` 组件的用途和示例在 `node_modules/hd-garden/templates/garden-blocks.md`（在引擎仓库里是 `templates/garden-blocks.md`）。以这两份为准，不凭记忆写组件。改完引擎后若本 skill 或 prompt 过期，先 `npx garden ui prompt` 再写。
 
 作者提交时，提交前钩子跑的是同一个 `npx garden ui check`。你用来找块、写回、自查的命令，和拦住作者提交的命令是同一套。
 
@@ -42,22 +46,23 @@ description: >-
    npx garden ui prompt
    ```
 
-   里面是组件目录、配方和设计规则。按配方的骨架写，不发明目录里没有的组件或属性。
+   里面是 compose 目录（小写标签 + token）、interactive PascalCase 参考（兼容）、配方和设计规则。按配方的骨架写，不发明目录里没有的组件或属性。
 
 3. 每块读原话和所在小节，三选一：
    - **写回正文**：一句话、一张表或一张 Mermaid 就能说清时。
-   - **写 `garden compose`**：读者需要拖、点、翻才能看懂时。
+   - **写 `garden compose`（说明图）**：读者需要看见结构、关系、重点时。Markdown 叶子 + 小写目录标签；不要 YAML。
+   - **写 `garden compose`（play）**：读者需要拖、点、翻才能看懂时。仍用 `garden compose`；可用 `{@body}`、`{expr}`、`{#if}`/`{#each}` 与小写控件（`slider`/`choice`/`button`/`stat`…）。遗留 `garden interactive` + PascalCase 仅作兼容。
    - **写一段 `diff`**：想法紧跟在一段完整代码后面，说的是「和上一版比改了什么」时。按原话写出 diff，用一段普通 Markdown 写回（只有这一个 `diff` 围栏）。写回后它紧挨着那段代码，页面会合成「代码 / 对比上一版」切换；diff 里的新行要和上面的完整代码一致。
-   - **写别的 `garden` 组件**：一张或多张资源卡（`card` / `cards`）、几个指标（`stat`）、两种做法并排或好坏对照（`compare` / `verdict: good|bad`）、一条时间线（`timeline`）、一张静态图表（`chart`）、一张说明图（`compose`）、一份下载文件（`file`）、3～6 个要素的关系图（`relations`）、紧凑图标列表或分步列表（`list`）、两三个选项的选择卡（`choice`）。字段与校验约束见 `npx garden ui prompt` 与 `templates/garden-blocks.md`。
-   - **编译 `garden compose`**：`lang` 是 `garden-compose` 且 `status` 是 `uncompiled` 时，围栏头保持 `garden compose`。把扫描到的原话原样放进 `intent`，正文写成 YAML 树（`steps` + `notes`，或 `tree`）。不要改成 interactive，不要写 HTML、SVG 或脚本。配方在 `npx garden ui prompt` 的说明图一节。
+   - **写别的 `garden` 组件**：一张或多张资源卡（`card` / `cards`）、几个指标（`stat`）、两种做法并排或好坏对照（`compare` / `verdict: good|bad`）、一条时间线（`timeline`）、一张静态图表（`chart`）、一份下载文件（`file`）、3～6 个要素的关系图（`relations`）、紧凑图标列表或分步列表（`list`）、两三个选项的选择卡（`choice`）。字段与校验约束见 `npx garden ui prompt` 与 `templates/garden-blocks.md`。
+   - **编译已有 `garden compose`**：`lang` 是 `garden-compose` 且 `status` 是 `uncompiled` 时，围栏头保持 `garden compose`。把扫描到的原话原样放进 `<intent>`（或块头 `intent:`），正文写成 DIL（Markdown + 小写标签；play 时加 `{@body}` 等）。不要改成 interactive，不要写任意 HTML、SVG 或脚本。配方在 `npx garden ui prompt` 的说明图一节。
    - **写 `garden html`**：目录表达不了的画布动画、音频、物理模拟等。按 [garden-interactive-chart](../garden-interactive-chart/SKILL.md) 在同名目录写 HTML，用 `title` 写下判断。
 
 4. 写 `garden compose` 时：
-   - 格式：围栏头写 `garden compose #<id>`；`---` 上面是 `caption`、`intent`、可选的 `expect`；`---` 下面是 `npx garden ui prompt` 里的组件树。
-   - 原话原样放进 `intent`，一个字都不改。
-   - `caption` 摘原话里的判断。原话没有判断句，就根据小节内容补一句，并在回复里说明。
-   - 原话里有已知点（"batch 1 时是 512 MiB"），写进 `expect`。
-   - 数据写在块里。原话提到同名目录里已有的数据文件时，才用 `Data` 引用。
+   - 格式：围栏头写 `garden compose`（可选 `#<id>`）；作者原话进 `<intent>…</intent>` 或块头 `intent:`；静态说明图直接写 Markdown + 标签树；play 可在 `---` 块头写 `caption` / `intent`，正文用 `{@body}` 与小写控件。
+   - 原话原样放进 intent，一个字都不改。
+   - 芯片内部 `gap={0}`/`gap={1}`；章节堆叠 `gap={2}`/`gap={3}`；日横幅等宽；phrasing 叶子保留前导 `*`。
+   - play 时：`caption` 摘原话里的判断；原话有已知点可写 `expect`（若引擎/校验支持）。
+   - 不要写色值、宽度、任意 HTML/SVG/脚本；图标用 `<icon name="…"/>`（名字须在目录里）。
    - 块太大就拆成两块，各自就近放在要讲的段落旁边，不挪到别的文件。
 
 5. 每块用 `apply` 写回，新内容从标准输入给：
@@ -65,17 +70,16 @@ description: >-
    ````bash
    npx garden ui apply content/posts/路径.md --id <id> --base <hash> <<'GARDEN_UI'
    ```garden compose #id
-   caption: ...
-   intent: |
-     ...
-   ---
+   <intent>
    ...
+   </intent>
+   <row gap={2}>...</row>
    ```
    GARDEN_UI
    ````
 
    - 想法块没有 id，用 `--intent-hash <intentHash>` 定位；原话重复时改用 `--at <startLine>`。
-   - 新内容可以是一个 `garden` 组件围栏（interactive、card、stat……），或一段普通 Markdown（写回正文时）。旧稿里的 `ui` 块也可以按原格式写回。
+   - 新内容可以是一个 `garden` 组件围栏（compose、interactive、card、stat……），或一段普通 Markdown（写回正文时）。旧稿里的 `ui` 块也可以按原格式写回。
    - 新内容里不能再有没编译的想法。
    - 成功时 stdout 是 `{"ok":true,...}`。失败时 stderr 是 JSON，按 `code` 处理：
      - `apply-invalid`：新内容没通过校验，按 `diagnostics` 改了再写。
@@ -96,7 +100,7 @@ description: >-
 
    | id | 选择 | 配方 | 假设 | expect |
    | --- | --- | --- | --- | --- |
-   | kv-memory | garden compose | 参数台 | 默认序列取 4K | batch 1 时 512 MiB |
+   | kv-memory | garden compose play | 参数台 | 默认序列取 4K | batch 1 时 512 MiB |
 
    "假设"写原话没说、你替作者定下的东西（默认值、范围、补的 caption）。没有就写"无"。
 
@@ -106,14 +110,16 @@ description: >-
 - 编造原话里没有的数字。需要数字但原话没给时，用原话里的公式算，或者问作者。
 - 使用远程地址（图片、脚本、数据）。
 - 改动目标块之外的正文。
+- 把 compose 写成 YAML 槽，或禁止作者/模型使用合法的 `{@body}` / `{expr}` / `{#if}` / `{#each}`（play 需要时）。
 
 ## 建议模式：这篇哪里适合交互
 
 只读，不改稿。先运行 `npx garden ui prompt` 读设计规则，再通读全文，挑出纯文字或贴图说不清的段落：
 
-- 公式或数字随参数变化（参数台、换算器）
+- 公式或数字随参数变化（compose play / 参数台）
 - 多步过程（步进器、流程）
 - 两种做法的差别（对比）
 - 一组格子、字节或内存布局（格子图）
+- 结构关系说明图（compose 静态 DIL）
 
 每处给出：所在小节、为什么文字不够、一段可以直接粘贴到该段落后面的 `garden` 想法块草稿。草稿只写读者要做什么、看到什么，以及原文里已有的数字，不写组件名。最多 5 处；没有合适的就说没有。

package/app/lib/garden-docs-meta.ts

@@ -96,6 +96,7 @@ export const COMPONENT_BADGE: Record<string, string> = {
   "reference/timeline": "timeline",
   "reference/chart": "chart",
   "reference/compose": "compose",
+  "reference/compose-icons": "compose",
   "reference/html": "html",
   "reference/interactive": "interactive",
   "reference/file": "file",
@@ -118,6 +119,7 @@ export const NAV_SHORT_TITLE: Record<string, string> = {
   "components/timeline": "时间线",
   "components/chart": "条形图表",
   "components/compose": "说明图",
+  "reference/compose-icons": "compose 图标",
   "components/html": "嵌入网页片段",
   "components/interactive": "可调公式与参数",
   "components/file": "文件下载与预览",

package/docs/handbook/components/compose.md

@@ -20,17 +20,15 @@ badge: compose
 - **谁连谁**：谁先到谁、从一处散开，还是几处收到一起。没有先后顺序，就直接写「这几块没有先后」。
 - **哪块是重点**：直接点名，比如「中间那列是重点」「下面一行才是重点」。
 
-不要写颜色、圆角、灰胶囊、字重、间距、阴影、要不要撑满。外观由组件默认样式决定，写了反而乱。全部标签见 [组件参考 · compose](/garden/reference/compose)。
+不要写颜色、圆角、灰胶囊、字重、间距、阴影、要不要撑满。外观由组件默认样式决定，写了反而乱。
 
-## 最佳实践
+**完整标签与属性**见 [组件参考 · compose](/garden/reference/compose)；**全部图标名**见 [compose 图标](/garden/reference/compose-icons)。
 
-写围栏时，最常见的失误有两个：一是只写一个主题词，没给结构；二是把精力花在规定颜色、圆角和字重上。下面按五种常见结构，列出改写前后的写法。
+## 写法对照
 
-**三列并排，中间接起来**
-
-只写「画一张权限图」，AI 不知道分几列、每列放什么；写成「三列等宽，中间用浅灰圆角，字重轻一点」，又全在规定外观。
+写围栏时，最常见的失误有两个：一是只写一个主题词，没给结构；二是把精力花在规定颜色、圆角和字重上。下面按五种常见结构，列出改写后的写法。
 
-把三列的名字、每列底下的条目和中间的连接写出来：
+**三列并排，中间接起来**
 
 ````markdown
 ```garden compose
@@ -42,8 +40,6 @@ Role 在中间，把用户和权限接起来。Role 是重点。
 
 **先到一处，再散开**
 
-不要写「画个单点登录，箭头好看一点，间距均匀」。把谁先连向哪里、再同时分给哪几个系统写清楚：
-
 ````markdown
 ```garden compose
 用户浏览器先到身份提供方，再同时连到 HR、Finance、Project 三个系统。
@@ -53,8 +49,6 @@ Role 在中间，把用户和权限接起来。Role 是重点。
 
 **自上而下分层**
 
-不要写「五张通栏卡片，第二张和第五张上色，箭头画细」。直接列出五层的名字、哪两层需要突出，以及是不是每次请求都按顺序走完：
-
 ````markdown
 ```garden compose
 从上到下五层：浏览器、身份服务、BFF、业务服务、授权决策。
@@ -65,8 +59,6 @@ Role 在中间，把用户和权限接起来。Role 是重点。
 
 **一件事的多个切面**
 
-不要写「两行两列加下面两张卡片，标题不要加粗」。把六个切面的短名、每块要回答的问题，以及「没有先后顺序」交代清楚：
-
 ````markdown
 ```garden compose
 用户发起请求后，先看四件事：认证（你是谁）、凭证（怎么证明）、
@@ -77,8 +69,6 @@ Role 在中间，把用户和权限接起来。Role 是重点。
 
 **上下两行对比**
 
-不要写「上面无框，下面灰色胶囊，贴着内容，不要撑满」。直接写哪一行是常规背景、哪一行是真正要强调的循环：
-
 ````markdown
 ```garden compose
 上面一行是常规交付：理解需求 → 设计方案 → 开发上线。
@@ -87,13 +77,13 @@ Role 在中间，把用户和权限接起来。Role 是重点。
 ```
 ````
 
-## 能力示例
+## 图标与表面
 
-**下面这些图只是示例**，用来展示 `compose` 能拼出哪几类常见结构。图里的权限、登录、API 等词只是为了把格子填满，写文章时换成你自己的主题即可。
+状态符号用 `<icon name="check-circle"/>` 一类具名图标，不要塞 emoji。小格子、浅底、圆角用 `padding`、`background`、`radius` 组合，不要为单张图发明专用标签。
 
-### 三列中间接
+## 一张示例
 
-左右两列靠中间一列连起来，底下用 `<join>` 收成一句话。
+下面只留一张图；更多对照见仓库示例文，标签全表见参考页。
 
 ```garden compose
 <intent>
@@ -120,218 +110,9 @@ Role 在中间，把用户和权限接起来。Role 是重点。
 <text tone="muted" align="center">概念关系：User ↔ Role ↔ Permission</text>
 ```
 
-### 先汇再散
-
-先流向中间那一层，再用 `<fan>` 同时分到下面几列。
-
-```garden compose
-<intent>
-用户浏览器先到身份提供方。身份提供方再同时连到 HR、Finance、Project。三个系统信任同一个身份提供方。身份提供方是要先看见的一层。
-</intent>
-<stack align="center">
-  <pill>用户浏览器</pill>
-  <arrow dir="down"/>
-  <band tone="accent" align="center">
-    <title>Identity Provider（IdP）</title>
-    <text>统一完成身份验证、维护登录状态、签发身份断言</text>
-  </band>
-  <fan n="3"/>
-  <row align="center">
-    <title>HR 系统</title>
-    <title>Finance 系统</title>
-    <title>Project 系统</title>
-  </row>
-  <text tone="muted" align="center">三个系统都信任同一个身份提供方</text>
-</stack>
-```
-
-### 自上而下分层
-
-几层按顺序往下走，重点层用 `<band>`，经过的层只留文字。
-
-```garden compose
-<intent>
-从上到下五层：浏览器、身份服务、BFF、业务服务、授权决策。身份服务和授权决策是要强调的两层，其余是经过的路径。不是每次请求都按这个顺序走完。
-</intent>
-<stack align="center">
-  <box frame="text" align="center">
-    <badge>①</badge>
-    <title>浏览器 / App</title>
-    <text>Cookie、Session、OAuth Client</text>
-  </box>
-  <arrow dir="down"/>
-  <band tone="accent" align="center">
-    <badge>②</badge>
-    <title>身份服务 IdP / IAM</title>
-    <text>Passkey、MFA、OIDC、会话管理</text>
-  </band>
-  <arrow dir="down"/>
-  <box frame="text" align="center">
-    <badge>③</badge>
-    <title>BFF / API Gateway</title>
-    <text>会话验证、Token 校验、入口授权控制</text>
-  </box>
-  <arrow dir="down"/>
-  <box frame="text" align="center">
-    <badge>④</badge>
-    <title>业务服务</title>
-    <text>订单、支付、账户、资源对象</text>
-  </box>
-  <arrow dir="down"/>
-  <band tone="tip" align="center">
-    <badge>⑤</badge>
-    <title>授权决策系统</title>
-    <text>RBAC + ABAC + ReBAC + Policy Engine</text>
-  </band>
-  <text tone="muted" align="start">逻辑职责示意：并非所有请求都按此顺序经过各层。身份服务通常在登录阶段交互，业务服务则在请求执行时调用授权决策能力。</text>
-</stack>
-```
-
-### 一件事的多个切面
-
-没有严格先后的几块内容，用 `<row>` 和 `<box>` 分成上下两组并排摆开。
-
-```garden compose
-<intent>
-用户要改订单地址。先分成认证、凭证、授权、验证，每块一个问题。然后再看传输和保密。这六块不是严格的先后步骤。
-</intent>
-<stack align="center">
-  <title>用户发起 API 请求</title>
-  <text tone="muted">例如：修改订单收货地址</text>
-</stack>
-<arrow dir="down"/>
-<row>
-  <box>
-    <title>认证</title>
-    <text>你是谁？</text>
-    <text tone="muted">Authentication</text>
-  </box>
-  <box>
-    <title>凭证</title>
-    <text>如何证明你的身份？</text>
-    <text tone="muted">Credential</text>
-  </box>
-</row>
-<row>
-  <box>
-    <title>授权</title>
-    <text>你有权修改这笔订单吗？</text>
-    <text tone="muted">Authorization</text>
-  </box>
-  <box>
-    <title>验证</title>
-    <text>提交的数据是否合法？</text>
-    <text tone="muted">Verification</text>
-  </box>
-</row>
-<arrow dir="down"/>
-<stack align="center">
-  <title>业务操作与数据存储</title>
-</stack>
-<row>
-  <box>
-    <title>传输</title>
-    <text>网络中能否被窃听、篡改、冒充？</text>
-  </box>
-  <box>
-    <title>保密</title>
-    <text>敏感数据泄露后能否被读取？</text>
-  </box>
-</row>
-<text tone="muted">概念示意：六者并不是严格串行的执行阶段，传输保护贯穿网络通信，保密措施也可能覆盖客户端与服务端。</text>
-```
-
-### 外框套子项
-
-大框里再摆一排徽章或两列要点，适合画「一层里面包含几条检查」。
-
-```garden compose
-<intent>
-用户意图经过 Agent，再经过策略执行点，最后到工具执行器。策略点里是四条约束。策略点是要先看见的一层。
-</intent>
-<stack align="center">
-  <title>User Intent + Authorization</title>
-  <text tone="muted">明确任务目标、用户身份与授权范围</text>
-  <arrow dir="down"/>
-  <band align="center">
-    <title>Agent / LLM</title>
-    <text>负责理解、推理、规划和提出执行意图</text>
-    <row align="center">
-      <badge>Untrusted Context</badge>
-      <badge>Memory</badge>
-      <badge>Tool Results</badge>
-    </row>
-  </band>
-  <arrow dir="down"/>
-  <box align="center" mark="shield">
-    <title>Policy Enforcement Point</title>
-    <text tone="muted" align="center">独立于 LLM 的确定性执行控制</text>
-    <row align="center">
-      <text>权限与资源范围</text>
-      <text>操作参数校验</text>
-    </row>
-    <row align="center">
-      <text>任务意图约束</text>
-      <text>高风险操作审批</text>
-    </row>
-  </box>
-  <arrow dir="down"/>
-  <title>Tool Executor</title>
-  <text tone="muted">按最小权限执行、记录审计、支持中断</text>
-</stack>
-```
-
-### 多角色来回交互
-
-几个角色按先后发消息、退回结果时，用 `<lanes>` 画成泳道。
-
-```garden compose
-<intent>
-用户、客户端、授权服务器三条泳道，六步授权码加 PKCE。
-</intent>
-<lanes>
-  <actor>用户</actor>
-  <actor>客户端</actor>
-  <actor>授权服务器</actor>
-  <message from="1" to="2" tone="forward">点击登录 / 授权</message>
-  <message from="2" to="3" tone="forward">发起授权请求 + PKCE</message>
-  <message from="3" to="1" tone="back">用户身份验证与授权</message>
-  <message from="3" to="2" tone="back">重定向返回 Code</message>
-  <message from="2" to="3" tone="forward">Code + Verifier 换 Token</message>
-  <message from="3" to="2" tone="back">返回 Token</message>
-</lanes>
-<text tone="muted">简化示意：真实流程还包含浏览器跳转、回调绑定、授权码及令牌校验等细节。</text>
-```
-
-### 两行流程对比
-
-上面一行放常规做法当背景，中间加 `<divider/>`，下面一行用胶囊突出真正想讲的循环。
-
-```garden compose
-<intent>
-上面一行是交付顺序：理解需求、设计方案、开发上线。下面一行才是要强调的决策循环：提出假设、低成本验证、迭代或放弃。上面是背景，下面是重点。
-</intent>
-<row align="center">
-  <title align="center">理解需求</title>
-  <arrow dir="right"/>
-  <title align="center">设计方案</title>
-  <arrow dir="right"/>
-  <title align="center">开发上线</title>
-</row>
-<divider/>
-<row align="center">
-  <pill tone="muted">提出假设</pill>
-  <arrow dir="right"/>
-  <pill tone="muted">低成本验证</pill>
-  <arrow dir="right"/>
-  <pill tone="muted">迭代或放弃</pill>
-</row>
-<text tone="muted">第二行才是产品探索更强调的决策循环。</text>
-```
-
 ## 可调参数（play）
 
-静态说明图还差一步、读者要拧参数时，仍写 `garden compose`，在围栏里用同一套 DIL 写法：
+静态说明图还差一步、读者要拧参数时，仍写 `garden compose`：
 
 - `{@body const [n, setN] = DIL.useState(3)}` 声明状态
 - `{@body const total = n * 24}` 派生值
@@ -339,7 +120,7 @@ Role 在中间，把用户和权限接起来。Role 是重点。
 - `{#if …}{:else}{/if}`、`{#each … as item, i}{/each}` 控制流
 - 小写控件：`<slider>`、`<choice>`、`<button>`、`<pie>` / `<chart>`、`<stat>`
 
-旧的 `garden interactive` 与 PascalCase `<State>` / `<Slider>` 仅作兼容，新文章不要再写。完整映射见仓库 `docs/compose-dil.md`。
+旧的 `garden interactive` 与 PascalCase 仅作兼容。完整映射见仓库 `docs/compose-dil.md`。
 
 ```garden compose #compose-play-demo
 caption: 拧一下席位，看月费。
@@ -351,4 +132,3 @@ intent: |
 <slider min={1} max={12} value={seats} onChange={setSeats} label="席位" />
 <stat label="月费" value={total} unit="USD" />
 ```
-