hd-garden 0.10.3 → 0.10.4

package/docs/handbook/en/start.md

@@ -90,3 +90,16 @@ To upgrade the engine, edit `package.json` in your site root, update the `"hd-ga
 npm install
 make check
 ```
+
+## 5. Editor Plugins
+
+To write an interactive component, insert an idea in VS Code, Cursor, or Typora, preview it, open the catalog, and let the `garden-ui` skill compile it. The plugins ship inside `hd-garden`. You do not compile them yourself.
+
+`npx hd-garden init` copies the files to `.garden/editors/`. An interactive terminal asks whether to install VS Code / Cursor and whether to install Typora. The first `npx garden sync` asks again if that prompt has not happened yet. With no TTY, `CI=1`, or `GARDEN_SKIP_EDITORS=1`, Garden only prints the hint. Install later with:
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+```
+
+Typora needs typora-community-plugin installed first; then enable the plugin under Settings, Installed plugins. If `code` or `cursor` is not available, use Install from VSIX and select the file under `.garden/editors/vscode/`. Insert, preview, catalog, and compile steps are in [Writing with AI](/garden/en/ai-writing) and [Checks & Shortcuts](/garden/en/workflow).

package/docs/handbook/en/workflow.md

@@ -1,7 +1,7 @@
 ---
 title: Checks & Shortcuts
 navTitle: Checks & Shortcuts
-description: Validate posts and diagnostic codes with npx garden check, install the Git pre-commit hook, and use editor snippets and Agent skills.
+description: Validate posts with npx garden check, install the VS Code and Typora plugins, and set up the Git pre-commit hook and Agent skills.
 section: workflow
 order: 40
 ---
@@ -80,3 +80,41 @@ Garden provides three ways to insert or generate components quickly:
    - `garden-ui`: Compiles natural-language `garden` idea fences into concrete component blocks.
    - `garden-interactive-chart`: Authors `interactive`, `chart`, `figure`, and `html` components from article data.
    - `garden-post-review`: Reviews an entire post against layout and component rules.
+
+## 5. VS Code, Cursor, and Typora Plugins
+
+The Intelligent UI plugins are the editor entry point for interactive components: insert a one-sentence idea, preview it, open the catalog, then hand compilation to the `garden-ui` skill. They ship inside `hd-garden`. A site does not compile `editors/vscode` or `editors/typora` from source.
+
+### Install
+
+`npx hd-garden init` copies the files to `.garden/editors/` (a VSIX for VS Code / Cursor, and the Typora plugin). An interactive terminal asks whether to install VS Code / Cursor, then whether to install Typora. The first `npx garden sync` or `npx garden dev` asks again when that prompt has not happened yet. `y` installs; Enter skips.
+
+With no TTY, when `CI` is `1`, or when `GARDEN_SKIP_EDITORS` is set, Garden does not wait for input and only prints how to install later. `GARDEN_SKIP_EDITORS` skips that automatic prompt. The commands below still install, and they are safe to run again:
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+npx garden editors install --vscode
+npx garden editors install --typora
+```
+
+`garden help` lists `editors install`.
+
+**VS Code / Cursor.** When `code` or `cursor` is on `PATH`, install adds the VSIX to that editor. If both commands exist, it installs into both. Without a CLI, open the Extensions view, choose the `...` menu, then Install from VSIX, and select the file under `.garden/editors/vscode/`.
+
+**Typora.** Typora has no official plugin API. Install [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md) first. The install command checks the usual locations. If the framework is missing, it still copies the plugin to `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/` and prints that prerequisite. On macOS it also copies to `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`. Open Typora and enable Garden Intelligent UI under Settings, Installed plugins. A Typora upgrade overwrites the community framework inside the app. Reinstall typora-community-plugin, then enable this plugin again. The fences stay in the Markdown.
+
+The Obsidian plugin is not installed by this command.
+
+### Use the plugins while writing
+
+1. **Insert an idea.** In VS Code / Cursor, use `Cmd+Alt+I` on macOS or `Ctrl+Alt+I` on Windows and Linux, or the Garden insert command. In Typora, type `/` and choose `/garden` (the next list has a small preview image on each row), or use the insert command to open the component list directly; Windows and Linux default to `Ctrl+Alt+I`. On macOS, record a shortcut under Settings, Keyboard Shortcuts, because Option rewrites the key. The insertion is a plain `garden` fence: a short brief naming the component and the facts to mention, which the `garden-ui` skill compiles later.
+2. **Preview.** Open the Markdown preview. In Typora, move the cursor out of the fence. A `ui` block renders the same component as the blog. An `intent` block renders as an idea card. Clicks on sliders and buttons stay in the preview.
+3. **Open the catalog.** In VS Code / Cursor, the catalog command inserts a recipe at the cursor. The terminal builds the same page:
+
+   ```bash
+   npx garden ui catalog
+   ```
+
+   That writes `.garden/ui-catalog.html`.
+4. **Compile with the skill.** Copy compile prompt. On an English site (`locale: en_US`) the clipboard text is `Compile this post:` plus the post path. Paste it to an Agent that has the `garden-ui` skill. The skill runs `npx garden ui scan`, reads `npx garden ui prompt`, and replaces only that fence with `npx garden ui apply`. The plugin does not call a model. Check the result with `npx garden ui check` or the pre-commit hook.

package/docs/handbook/index.md

@@ -182,6 +182,7 @@ make dev
 写完运行 `make update`，检查通过后会提交并推送。细节见各章：
 
 - **[快速开始](/garden/start)**：目录结构、`make new` 新建长文、草稿预览与日常命令。
+- **[用 AI 写作](/garden/ai-writing)** 与 **[语法检查与快捷输入](/garden/workflow)**：在 VS Code、Cursor、Typora 里插入想法、预览组件、打开清单，并用 `npx garden editors install` 安装插件。
 - **[站点与专栏配置](/garden/config)**：`site.config.yaml` 各字段含义、自定义 SVG 图标与 `content/columns.yaml` 专栏编排。
 - **[发布到 GitHub Pages](/garden/deploy)**：单个公开仓库或「私有源码仓库 + 公开页面仓库」的完整 Actions 工作流。
 - **[写文章与随想](/garden/writing)** 与 **[阅读排版是怎么工作的](/garden/design)**：Front Matter 字段、三级自适应宽度与色彩变量。链接卡片、来源胶囊和本地图片见 [组件总览](/garden/components)。

package/docs/handbook/start.md

@@ -90,3 +90,16 @@ CONTENT_INCLUDE_DRAFTS=1 make dev
 npm install
 make check
 ```
+
+## 5. 编辑器插件
+
+写交互组件时，可以在 VS Code、Cursor 或 Typora 里插入想法、预览组件、打开清单，再把编译交给 `garden-ui` skill。插件随 `hd-garden` 发布，不用自己编译。
+
+`npx hd-garden init` 会把产物放到 `.garden/editors/`。终端可交互时分别询问是否安装 VS Code / Cursor 和 Typora。第一次 `npx garden sync` 如果还没问过，会再问一次。没有 TTY、`CI=1` 或 `GARDEN_SKIP_EDITORS=1` 时只打印提示。之后运行：
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+```
+
+Typora 需要先安装 typora-community-plugin，再在「设置 → 已安装插件」里勾选。没有 `code` 或 `cursor` 命令时，用 Install from VSIX 选择 `.garden/editors/vscode/` 里的文件。插入、预览、清单和编译的步骤见 [用 AI 写作](/garden/ai-writing) 与 [语法检查与快捷输入](/garden/workflow)。

package/docs/handbook/workflow.md

@@ -1,7 +1,7 @@
 ---
 title: 语法检查与快捷输入
 navTitle: 语法检查与快捷输入
-description: 使用 npx garden check 检查文章诊断码，配置 Git 提交前检查钩子、编辑器代码片段与 Agent 技能。
+description: 使用 npx garden check 检查文章诊断码，安装 VS Code 与 Typora 插件，配置 Git 提交前检查钩子与 Agent 技能。
 section: workflow
 order: 40
 ---
@@ -80,3 +80,41 @@ Garden 通过以下三种方式提供组件模板与智能辅助：
    - `garden-ui`：把文章里的 `garden` 想法描述编译成具体的组件围栏。
    - `garden-interactive-chart`：根据文章数据编写 `interactive`、`chart`、`figure` 与 `html` 组件。
    - `garden-post-review`：按排版与组件规范审阅整篇文章。
+
+## 5. VS Code、Cursor 与 Typora 插件
+
+Intelligent UI 插件是写交互组件的编辑器入口：插入一句想法、在编辑器里预览、打开组件清单，再把编译交给 `garden-ui` skill。插件随 `hd-garden` 发布，站点不用从 `editors/vscode` 或 `editors/typora` 源码编译。
+
+### 安装
+
+`npx hd-garden init` 把产物复制到 `.garden/editors/`（VS Code / Cursor 的 VSIX，以及 Typora 插件）。终端可交互时会分别询问要不要装进 VS Code / Cursor、要不要装进 Typora。第一次 `npx garden sync` 或 `npx garden dev` 如果还没问过，会再问一次。`y` 安装，直接回车跳过。
+
+没有 TTY、环境变量 `CI` 为 `1`，或设置了 `GARDEN_SKIP_EDITORS` 时，不会等待输入，只提示手动安装。`GARDEN_SKIP_EDITORS` 只跳过这次自动询问；下面的命令照常安装，并且可以重复执行：
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+npx garden editors install --vscode
+npx garden editors install --typora
+```
+
+`garden help` 里也能看到 `editors install`。
+
+**VS Code / Cursor。** 本机有 `code` 或 `cursor` 时，安装会把 VSIX 装进那个编辑器。两个命令都在时各装一次。没有命令行时，打开扩展视图，点右上角「…」，选择 Install from VSIX，文件在 `.garden/editors/vscode/`。
+
+**Typora。** Typora 没有官方插件接口，要先安装 [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md)。安装命令会检查常见位置；没找到时仍把插件复制到 `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`。macOS 还会复制到 `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`。然后打开 Typora，在「设置 → 已安装插件」里勾选 Garden Intelligent UI。升级 Typora 会覆盖社区框架改过的程序文件，需要重新安装 typora-community-plugin，再勾选本插件。围栏原文还在稿件里。
+
+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 编译。
+2. **预览。** 打开 Markdown 预览（Typora 里光标离开围栏即可）。`ui` 块画成和博客一样的组件，`intent` 块显示成想法卡片。点滑杆、按钮不会跳回源码。
+3. **看组件清单。** VS Code / Cursor 里用「查看组件清单」，点「用它开始」把配方插进当前稿件。终端里的同一份清单：
+
+   ```bash
+   npx garden ui catalog
+   ```
+
+   生成 `.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` 或提交前钩子再查一遍。