hd-garden 0.13.3 → 0.14.2

package/docs/handbook/workflow.md

@@ -38,25 +38,20 @@ order: 40
 
 | 诊断码 | 级别 | 触发原因与修复方法 |
 | :--- | :--- | :--- |
-| `missing-title` / `missing-description` | 错误 | Front Matter 缺少有效的 `title` 或 `description` |
+| `missing-title` / `invalid-description` | 错误 | `title` 缺失或为空，或 `description` 不是字符串／空值；摘要可以留空 |
 | `unexpected-slug` | 错误 | Front Matter 中手写了 `slug` 字段（文件名即标识，删掉 `slug`） |
 | `date-format` | 错误 | `date` 不是合法的 `YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss` 或带时区的 ISO 时间 |
-| `missing-cover` / `missing-asset` | 错误 | `cover` 封面图、正文图片或 `garden file` 引用的本地文件不存在 |
+| `missing-cover` / `missing-asset` | 错误 | `cover` 封面图、正文图片或 Compose `file` 引用的本地文件不存在 |
 | `heading-h1` / `heading-skip` | 错误 | 正文使用了 `#` 一级标题，或标题层级跳级（例如从 `##` 直接跳到 `####`） |
 | `reference-heading` | 错误 | 正文写了 `## 参考` 或 `## 参考资料` 标题（应改放到 Front Matter 的 `references` 列表） |
 | `callout-type` | 错误 | `> [!TYPE]` 使用了不支持的提示框类型 |
 | `title-split` | 警告 | 标题包含 `丨` 分隔符，但分隔符左边或右边为空（应写成「主题丨副题」） |
 | `diff-orphan` | 错误 | `diff` 代码块前面没有紧挨着的完整代码块 |
-| `legacy-fence` | 错误 | 使用了旧版围栏名（如 `garden:stat`、`widget`、`embed`、`html garden`），需改为 `garden <name>` |
-| `garden-idea` | 错误 | 非草稿文章里还有未编译的空白 `garden` 想法块 |
 | `compose-uncompiled` | 错误 | 非草稿里的 `garden compose` 还是白话，没有编译成标记 |
 | `compose-invalid` | 错误 | `garden compose` 的标记不合法：未知标签、没闭合，或写成了 YAML 槽 |
-| `garden-name` | 错误 | 未知的 `garden` 组件名（支持 `card`、`stat`、`compare`、`timeline`、`chart`、`compose`、`html`、`interactive`、`file`、`relations`、`list`、`choice`） |
-| `garden-yaml` | 错误 | `garden` 围栏内 YAML 语法错误、顶层不是键值/列表，或包含该组件不支持的键名 |
-| `garden-relations` | 错误 | `garden relations` 的要素数量不在 3～6 个之间，或 `links` 配置不合法（要素更多或有分支改用 `mermaid` 流程图，只走一遍的步骤用 `garden list`） |
-| `garden-file` / `file-outside` | 错误 | `garden file` 手写了 `resolved`、缺少有效的 `src` / `files`，或本地路径越出了 `content/` 目录 |
-| `file-large` | 警告 | `garden file` 引用的单个本地文件体积超过 `5 MB` |
-| `compare-long` | 错误 | `garden compare` 并排模式下单个对比格的正文超过约 60 字（带 `verdict` 的上下对照不受此限） |
+| `garden-name` | 错误 | 作者组件围栏统一使用 `garden compose`。 |
+| `compose-file` / `file-outside` | 错误 | Compose `file` 手写了 `resolved`、缺少有效的 `src` / `files`，或本地路径越出了 `content/` 目录 |
+| `file-large` | 警告 | Compose `file` 引用的单个本地文件体积超过 `5 MB` |
 | `interactive-trivial` / `steps-prose` | 错误 | `garden compose` 只有一次简单乘法，或步骤只是散文而没有状态变化 |
 
 ## 3. Git 提交前钩子与组件画廊
@@ -77,15 +72,14 @@ Garden 通过以下三种方式提供组件模板与智能辅助：
 1. **新建文章自动附带速查表**：运行 `make new SLUG=xxx TITLE="..."` 创建文章时，生成的 `.md` 文件底部会自动带有一段 `<!-- 组件速查 ... -->` HTML 注释，列出想法块和各个组件的示例写法，复制需要的那块即可。这段注释不会显示在页面上，写完可以删掉。
 2. **代码片段模板文件**：`hd-garden` 包内的 `templates/` 目录自带两份模板文件：
    - `templates/garden-blocks.md`：想法块和内置组件的可复制 Markdown 模板。
-   - `templates/garden-snippets.plist`：macOS 系统文本替换词条（可拖入「系统设置 → 键盘 → 文本替换」），触发词是 `;gidea`（也可以输入 `;garden想法`）、`;gcard`、`;gstat`、`;gcompare`、`;gtimeline`、`;gchart`、`;gcompose`、`;ghtml`、`;ginteractive`、`;gfile`、`;grel`、`;glist`、`;gchoice`。`;gcompose` 展开成带一句白话的 `garden compose`；其余展开成对应围栏。
-3. **安装 AI Agent 技能（`npx garden skill`）**：在站点目录运行 `npx garden skill`（`npx hd-garden init` 时也会自动执行），会把三个技能复制到站点根目录下的 `.agents/skills/`：
-   - `garden-ui`：把文章里的 `garden` 想法描述编译成具体的组件围栏。
-   - `garden-interactive-chart`：根据文章数据编写 `interactive`、`chart`、`compose` 与 `html` 组件。
+   - `templates/garden-snippets.plist`: one Compose author entry; choose components inside the scene.
+3. **安装 AI Agent 技能（`npx garden skill`）**：在站点目录运行 `npx garden skill`（`npx hd-garden init` 时也会自动执行），会把两个技能复制到站点根目录下的 `.agents/skills/`：
+   - `garden-compose`：把文章里的 Compose 意图编译成同一入口内的布局、内容与交互。
    - `garden-post-review`：按排版与组件规范审阅整篇文章。
 
 ## 5. VS Code、Cursor 与 Typora 插件
 
-Intelligent UI 插件是写交互组件的编辑器入口：插入一句想法、在编辑器里预览、打开组件清单，再把编译交给 `garden-ui` skill。插件随 `hd-garden` 发布，站点不用从 `editors/vscode` 或 `editors/typora` 源码编译。
+Intelligent UI 插件是写交互组件的编辑器入口：插入一句想法、在编辑器里预览、打开组件清单，再把编译交给 `garden-compose` skill。插件随 `hd-garden` 发布，站点不用从 `editors/vscode` 或 `editors/typora` 源码编译。
 
 ### 安装
 
@@ -110,7 +104,7 @@ Obsidian 插件这一轮不随包安装。
 
 ### 在编辑器里怎么用
 
-1. **插入想法。** VS Code / Cursor：macOS 用 `Cmd+Alt+I`，Windows / Linux 用 `Ctrl+Alt+I`，或命令「插入 Garden 块」。Typora：输入 `/` 后选 `/garden`（下一层列表每一项有一张小预览图），或命令「插入 Garden 块」直接打开组件列表（Windows / Linux 默认 `Ctrl+Alt+I`，macOS 请到「设置 → 快捷键」里自己录，因为 Option 会改写按键）。插入的是不带组件名的 `garden` 围栏，正文说明要写成哪种组件、写上哪些事实，交给 `garden-ui` skill 编译。
+1. **插入想法。** VS Code / Cursor：macOS 用 `Cmd+Alt+I`，Windows / Linux 用 `Ctrl+Alt+I`，或命令「插入 Garden 块」。Typora：输入 `/` 后选 `/garden`（下一层列表每一项有一张小预览图），或命令「插入 Garden 块」直接打开组件列表（Windows / Linux 默认 `Ctrl+Alt+I`，macOS 请到「设置 → 快捷键」里自己录，因为 Option 会改写按键）。插入的是不带组件名的 `garden` 围栏，正文说明要写成哪种组件、写上哪些事实，交给 `garden-compose` skill 编译。
 2. **预览。** 打开 Markdown 预览（Typora 里光标离开围栏即可）。`ui` 块画成和博客一样的组件，`intent` 块显示成想法卡片。点滑杆、按钮不会跳回源码。
 3. **看组件清单。** VS Code / Cursor 里用「查看组件清单」，点「用它开始」把配方插进当前稿件。终端里的同一份清单：
 
@@ -119,4 +113,14 @@ Obsidian 插件这一轮不随包安装。
    ```
 
    生成 `.garden/ui-catalog.html`。
-4. **交给 skill 编译。** 「复制编译提示词」在中文站点得到 `编译这篇：<相对路径>`，在 `locale: en_US` 的站点得到 `Compile this post: <相对路径>`。把这句话发给装了 `garden-ui` skill 的 Agent。它会运行 `npx garden ui scan`，阅读 `npx garden ui prompt`，再用 `npx garden ui apply` 只替换这一块。插件本身不调用模型。写完用 `npx garden ui check` 或提交前钩子再查一遍。
+4. **交给 skill 编译。** 「复制编译提示词」在中文站点得到 `编译这篇：<相对路径>`，在 `locale: en_US` 的站点得到 `Compile this post: <相对路径>`。把这句话发给装了 `garden-compose` skill 的 Agent。它会运行 `npx garden ui scan`，阅读 `npx garden ui prompt`，再用 `npx garden ui apply` 只替换这一块。插件本身不调用模型。写完用 `npx garden ui check` 或提交前钩子再查一遍。
+
+
+## 本地严格检查
+
+运行 `make check`：检查工作区所有文章的结构和全部 Compose/UI 块，包含草稿与未跟踪的新稿，不必先暂存。结构错误不会阻止 Compose 检查；有待编译/错误块时显示诊断和调用项目 `garden-compose` skill 的短指令，默认不生成提示词文件。不会调用 AI 或复制剪贴板。
+
+`make check FILE=content/posts/文章.md` 只限制内容预检范围；通过后仍执行原来的全站 sync/build（引擎仓库保留 lint/test）。预检失败返回非零并跳过后续阶段。这是编译/校验，不是自动格式化或自动改稿。
+
+
+`make check diff` 只检查 `content/` 下相对 HEAD 有改动的 Markdown（含已暂存、未暂存）和未跟踪新稿，读取工作区当前内容，去重、取重命名后的路径、跳过已删除文件。不会继续运行全站 sync/build/lint/tests，`make -j check diff` 也只执行一次改动检查。没有改动则成功退出；不在 Git 仓库或没有 HEAD 时明确报错，不回退全量。底层命令是 `garden verify --diff`。diff 模式优先于 FILE；不带 diff 的 `make check` 不变。

package/docs/handbook/writing.md

@@ -36,7 +36,7 @@ references:
 | :--- | :--- | :--- | :--- |
 | `title` | 是 | 字符串 | 文章标题。中间写 `丨`、`｜` 或 ` \| ` 会分成两行并按字数缩放字号 |
 | `date` | 是 | 日期字符串 | 发布日期（如 `2026-10-18` 或带时区的 ISO 时间） |
-| `description` | 是 | 字符串 | 文章摘要，显示在正文开头导语、列表页与搜索引擎摘要中 |
+| `description` | 否 | 字符串 | 文章摘要，显示在正文开头导语、列表页与搜索引擎摘要中；留空（如 `description: ""`）、省略、YAML `null` 或只写空白时，不渲染摘要，也不会自动截取正文替代 |
 | `updated` | 否 | 日期字符串 | 最后更新日期，显示在文章元信息栏并用于 RSS 排序 |
 | `publishAt` | 否 | 日期字符串 | 定时发布时间；早于当前构建时间（或设置 `CONTENT_INCLUDE_DRAFTS=1`）才会发布 |
 | `tags` | 否 | 字符串数组 | 文章标签列表，点击标签会跳转到 `/blog?t=<标签>` 筛选 |
@@ -62,12 +62,12 @@ func openStore(path string) (*Store, error) {
 }
 ```
 
-```garden
+```garden compose
 和上一版比：打开存储时的模式从 ModeJournal 改成了 ModeWAL。
 ```
 ````
 
-Agent 按 `garden-ui` skill 会通过 `npx garden ui apply` 把这段想法替换成紧挨着完整代码的 `diff` 围栏（详见 [用 AI 写作](/garden/ai-writing)）。页面渲染时会把这两段合成一个可切换 **「代码」** 和 **「对比上一版」** 的代码框，右上角的复制按钮始终复制新版完整代码：
+Agent 按 `garden-compose` skill 会通过 `npx garden ui apply` 把这段想法替换成紧挨着完整代码的 `diff` 围栏（详见 [用 AI 写作](/garden/ai-writing)）。页面渲染时会把这两段合成一个可切换 **「代码」** 和 **「对比上一版」** 的代码框，右上角的复制按钮始终复制新版完整代码：
 
 ```go
 func openStore(path string) (*Store, error) {