hd-garden 0.10.3 → 0.10.4

package/README.en.md

@@ -17,9 +17,46 @@ npm install
 make dev
 ```
 
-The published npm package is `hd-garden`; once installed inside a site, you can run `npx garden` (do not run `npx garden init` directly, as `garden` on npm is an unrelated package). Running `make dev` for the first time creates `.env.local`, installs the three AI skills under `.agents/skills/`, installs the pre-commit check in `.git/hooks/pre-commit`, and starts the dev server at `http://localhost:3000` (with the built-in handbook at `http://localhost:3000/garden/en`).
+The published npm package is `hd-garden`; once installed inside a site, you can run `npx garden` (do not run `npx garden init` directly, as `garden` on npm is an unrelated package). `init` copies the VS Code / Cursor and Typora Intelligent UI plugins into the site and, in an interactive terminal, asks whether to install each one (see the next section). Running `make dev` for the first time creates `.env.local`, installs the three AI skills under `.agents/skills/`, installs the pre-commit check in `.git/hooks/pre-commit`, and starts the dev server at `http://localhost:3000` (with the built-in handbook at `http://localhost:3000/garden/en`).
 
-## 2. Describe components in plain language (humans and Agents share the same CLI)
+## 2. Write interactives in VS Code, Cursor, and Typora
+
+The Intelligent UI plugins ship inside `hd-garden`. You do not compile them in the site. They insert a one-sentence idea, preview the rendered component in the editor, open the component catalog, and hand the post to the `garden-ui` skill to compile.
+
+`npx hd-garden init` copies the files to `.garden/editors/` (a `.vsix` for VS Code / Cursor, and the Typora plugin). In an interactive terminal it asks about VS Code / Cursor first, then Typora. The first `npx garden sync` (`make dev` syncs first) asks again if that prompt has not happened yet. `y` installs; pressing Enter skips.
+
+With no TTY (a pipe or a CI log), with `CI=1`, or with `GARDEN_SKIP_EDITORS=1`, the command does not wait for input. It prints the install command below. You can run it later, and running it again is safe:
+
+```bash
+npx garden editors install                 # Ask again about VS Code and Typora
+npx garden editors install --yes           # Install both, without asking
+npx garden editors install --vscode        # VS Code / Cursor only
+npx garden editors install --typora        # Typora only
+```
+
+### VS Code / Cursor
+
+- **Insert an idea**: `Cmd+Alt+I` on macOS, `Ctrl+Alt+I` on Windows and Linux. The Command Palette and the editor context menu have the same Garden command. It inserts a plain `garden` fence: a short brief for the `garden-ui` skill, which compiles it later. In Typora, type `/` and choose `/garden`; the next list gives each component a small preview image.
+- **Preview**: Open the Markdown preview. A `ui` fence renders the same component as the blog. An `intent` fence renders as an idea card. The extension reads sidecar data files next to the post.
+- **Check**: Errors show up in the Problems panel and as squiggles in the source. A CodeLens above each block says whether it is ok, broken, stale, or not compiled yet.
+- **Catalog**: The Garden catalog command inserts a recipe at the cursor when you choose to start from it. The same catalog from the terminal is `npx garden ui catalog` (it writes `.garden/ui-catalog.html`).
+- **Compile**: Copy the compile prompt. On an English site (`locale: en_US`) it is `Compile this post:` plus the path. Paste that to an Agent that has the `garden-ui` skill. The skill runs `npx garden ui scan`, reads `npx garden ui prompt`, and writes the fence back with `npx garden ui apply`. The plugin does not call a model and does not store a key.
+
+When `code` or `cursor` is on `PATH`, `garden editors install` runs `--install-extension`. 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 (on macOS it patches `index.html` inside `Typora.app`). `garden editors install` looks in the usual locations. If the framework is missing, it still copies the plugin and prints that prerequisite.
+
+The plugin is copied to `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`. On macOS it is also copied to `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`, which is the directory the Installed Plugins list reads. Open Typora and enable Garden Intelligent UI under Settings, Installed plugins.
+
+Use it the same way as VS Code: leaving a fence previews `ui` / `intent` (as with Mermaid, click into the fence to edit the source; clicks on sliders and buttons stay in the preview). Type `/`, choose `/garden`, or use the insert command (`Ctrl+Alt+I` on Windows and Linux; on macOS, Option rewrites the key, so record a shortcut under Settings, Keyboard Shortcuts). Copy compile prompt hands the post to the `garden-ui` skill.
+
+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, and `make dev` still previews them.
+
+The Obsidian plugin is not installed by this command.
+
+## 3. Describe components in plain language (humans and Agents share the same CLI)
 
 Where you want a component or interactive calculation, write an unnamed `garden` fence describing what the reader should adjust and see:
 
@@ -31,7 +68,7 @@ Where you want a component or interactive calculation, write an unnamed `garden`
 
 Ask your Agent to compile the post using the bundled `garden-ui` skill: it runs `npx garden ui scan` to locate uncompiled or broken blocks, reads the component catalog from `npx garden ui prompt`, generates a `garden interactive` block (or `card`, `stat`, `compare`, `timeline`, `chart`, `figure`, `html`, `file`, `relations`, `list`, `choice`, or a `diff` block right below a code snippet), and writes only that fence back via `npx garden ui apply`. If you run `git commit` before compiling, the pre-commit hook runs `npx --no-install garden ui check --staged --quiet`, stops the commit, and prints a ready-to-paste fix prompt for your AI.
 
-## 3. Common commands
+## 4. Common commands
 
 ```bash
 make new SLUG=writing-pace TITLE="Writing Pace" # Create a draft post in content/posts/
@@ -42,9 +79,10 @@ make update MESSAGE="Add writing-pace post"     # Check, commit, and push to ori
 npx garden check content/posts/writing-pace.md  # Validate front matter, components, and assets
 npx garden ui check --staged                    # Check staged posts for uncompiled ideas or UI errors
 npx garden ui catalog                           # Generate an offline component gallery at .garden/ui-catalog.html
+npx garden editors install --yes                # Install the Intelligent UI plugins into VS Code / Cursor and Typora
 ```
 
-## 4. Excalidraw
+## 5. Excalidraw
 
 Point a Markdown image at the `.excalidraw` source. `garden build` exports one light flat SVG beside that file, with a transparent background, and embeds that SVG in the article so its text can be selected. No separate export command.
 
@@ -54,7 +92,7 @@ Point a Markdown image at the `.excalidraw` source. `garden build` exports one l
 
 The first page that references `.excalidraw` downloads the exporter (Chromium is not required; fonts are embedded in the SVG). See [Local Image](docs/handbook/en/components/image.md).
 
-## 5. Handbook and reference docs
+## 6. Handbook and reference docs
 
 Start `make dev` and open `/garden/en` (Chinese at `/garden`), or read the markdown sources directly:
 

package/README.md

@@ -17,11 +17,48 @@ npm install
 make dev
 ```
 
-公开包名是 `hd-garden`，装进站点后可使用 `npx garden`（不要直接运行未安装的 `npx garden init`，npm 上的 `garden` 是另一个包）。首次运行 `make dev` 会生成 `.env.local`、补齐 `.agents/skills/` 下的三个 AI skill，并在 `.git/hooks/pre-commit` 安装提交前检查，默认预览地址是 `http://localhost:3000`（使用说明在 `http://localhost:3000/garden`）。
+公开包名是 `hd-garden`，装进站点后可使用 `npx garden`（不要直接运行未安装的 `npx garden init`，npm 上的 `garden` 是另一个包）。`init` 会把 VS Code / Cursor 与 Typora 的 Intelligent UI 插件放进站点，并在交互终端里分别询问要不要装上（见下一节）。首次运行 `make dev` 会生成 `.env.local`、补齐 `.agents/skills/` 下的三个 AI skill，并在 `.git/hooks/pre-commit` 安装提交前检查，默认预览地址是 `http://localhost:3000`（使用说明在 `http://localhost:3000/garden`）。
 
 如果在本地使用了 npm 镜像，请把 `registry` 留在 `~/.npmrc`，不要让镜像域名写进 `package-lock.json`（提交前可运行 `node node_modules/hd-garden/scripts/check-lockfile-registry.mjs` 检查）。
 
-## 2. 用一句话写组件（人和 Agent 用同一套工具）
+## 2. 在 VS Code、Cursor 和 Typora 里写交互
+
+Intelligent UI 插件随 `hd-garden` 一起发布，不用在站点里编译源码。它做四件事：插入一句想法、在编辑器里预览画好的组件、打开组件清单，以及把「编译这篇」交给 `garden-ui` skill。
+
+`npx hd-garden init` 把产物复制到站点的 `.garden/editors/`（VS Code 的 `.vsix`，以及 Typora 插件目录）。终端可交互时，会先问要不要装进 VS Code / Cursor，再问要不要装进 Typora。第一次 `npx garden sync`（`make dev` 会先同步）如果还没问过，会再问一次。回答 `y` 才会安装；直接回车是不装。
+
+没有 TTY（管道或 CI 日志）、`CI=1`，或设置了 `GARDEN_SKIP_EDITORS=1` 时，命令不会停下来等输入，只打印下面这条安装命令。之后随时可以装，重复执行也安全：
+
+```bash
+npx garden editors install                 # 再问一次 VS Code 和 Typora
+npx garden editors install --yes           # 两个都装，不再询问
+npx garden editors install --vscode        # 只装 VS Code / Cursor
+npx garden editors install --typora        # 只装 Typora
+```
+
+### VS Code / Cursor
+
+- **插入想法**：macOS 用 `Cmd+Alt+I`，Windows / Linux 用 `Ctrl+Alt+I`，或命令「插入 Garden 块」。插入的是不带组件名的 `garden` 围栏，正文用中文告诉你要写什么，交给 `garden-ui` skill 编译。Typora 里先输入 `/` 选 `/garden`，再从带小预览图的列表里选组件。
+- **预览**：打开 Markdown 预览。`ui` 围栏画成和博客一样的组件，`intent` 围栏显示成想法卡片。同名目录里的数据文件由扩展读取。
+- **检查**：错误进「问题」面板，并在源码上画波浪线。每个块上方的 CodeLens 标出正常、有错、过期或未编译。
+- **组件清单**：命令「查看组件清单」。点「用它开始」把配方插进当前稿件。终端里的同一份清单是 `npx garden ui catalog`（生成 `.garden/ui-catalog.html`）。
+- **编译**：命令「复制编译提示词」。中文站点复制 `编译这篇：<相对路径>`，英文站点（`locale: en_US`）复制 `Compile this post: <相对路径>`。把这句话发给装了 `garden-ui` skill 的 Agent，由它 `npx garden ui scan`、读 `npx garden ui prompt`、再 `npx garden ui apply`。插件不调用模型，也不保存密钥。
+
+本机有 `code` 或 `cursor` 命令时，`garden editors install` 会执行 `--install-extension`。两个命令都在时，会各装一次。没有命令行时，打开扩展视图，点右上角「…」，选 **Install from VSIX**（从 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) 装上社区框架（macOS 上它会修改 `Typora.app` 里的 `index.html`）。`garden editors install` 会检查常见安装位置；没找到时仍会复制插件，并打印这个前提。
+
+插件文件复制到 `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`。macOS 同时写到 `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`。打开 Typora，在「设置 → 已安装插件」里勾选 Garden Intelligent UI。
+
+用法和 VS Code 同一套：光标离开围栏时预览 `ui` / `intent`（和 Mermaid 一样，点进围栏编辑源码；点滑杆或按钮不会跳进源码）；先输入 `/` 再选 `/garden`，或用命令「插入 Garden 块」，都会插入想法围栏（Windows / Linux 默认 `Ctrl+Alt+I`，macOS 的 Option 会改写按键，请到「设置 → 快捷键」里自己录）；「Garden：复制编译提示词」交给 `garden-ui` skill。
+
+升级 Typora 会覆盖社区框架改过的程序文件，插件跟着失效。需要重新安装 typora-community-plugin，再勾选本插件。稿件里的围栏原文还在，也可以用 `make dev` 预览。
+
+Obsidian 插件这一轮不随包安装。
+
+## 3. 用一句话写组件（人和 Agent 用同一套工具）
 
 在正文想放组件的位置写一个不带名字的 `garden` 围栏，只描述想让读者做什么、看到什么：
 
@@ -33,7 +70,7 @@ make dev
 
 让 Agent 按站点里的 `garden-ui` skill 处理这篇稿件：Agent 先用 `npx garden ui scan` 读取待编译块的哈希，再读 `npx garden ui prompt` 的组件规则，生成 `garden interactive`（或 `card`、`stat`、`compare`、`timeline`、`chart`、`figure`、`html`、`file`、`relations`、`list`、`choice` 等内置组件，或在完整代码下方生成 `diff`），最后用 `npx garden ui apply` 只替换该围栏。如果你在编译前直接 `git commit`，pre-commit 钩子会运行同一条 `npx --no-install garden ui check --staged --quiet` 拦下提交，并打印一段可直接粘贴给 AI 的修复提示词。
 
-## 3. 常用命令
+## 4. 常用命令
 
 ```bash
 make new SLUG=writing-pace TITLE="慢慢写"      # 在 content/posts/ 下创建文章草稿
@@ -44,9 +81,10 @@ make update MESSAGE="新增一篇文章"             # 检查通过后提交并
 npx garden check content/posts/writing-pace.md # 单独检查一篇文章的标题、组件与资源路径
 npx garden ui check --staged                   # 检查暂存区稿件中的想法块与交互组件
 npx garden ui catalog                          # 在 .garden/ui-catalog.html 生成离线组件清单
+npx garden editors install --yes               # 把 Intelligent UI 插件装进 VS Code / Cursor 与 Typora
 ```
 
-## 4. Excalidraw
+## 5. Excalidraw
 
 正文用 Markdown 图片指向 `.excalidraw` 源文件。`garden build` 会在同目录导出一张浅色扁平 SVG，画布背景透明，并把这张 SVG 嵌进正文，图里的文字可以选中。不需要单独的导出命令。
 
@@ -56,7 +94,7 @@ npx garden ui catalog                          # 在 .garden/ui-catalog.html 生
 
 页面里第一次出现 `.excalidraw` 时，构建会下载导出程序（不需要 Chromium；字体写进 SVG）。说明见[本地图片](docs/handbook/components/image.md)。
 
-## 5. 使用说明与深入文档
+## 6. 使用说明与深入文档
 
 本地运行 `make dev` 后访问 `/garden`（英文版在 `/garden/en`），或直接阅读仓库内的文档：
 

package/bin/garden.mjs

@@ -4,6 +4,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 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 { langOf, siteCliLang } from "../ui/core/cli-locale.mjs";
 
@@ -196,29 +197,30 @@ function copyIfMissing(from, to) {
   return true;
 }
 
-function ensureSiteKit(destinationRoot = siteRoot) {
-  if (samePath(destinationRoot, gardenPackageRoot)) return;
+async function ensureSiteKit(destinationRoot = siteRoot) {
   const lang = siteCliLang(destinationRoot);
+  if (!samePath(destinationRoot, gardenPackageRoot)) {
+    const added = [];
+    if (
+      copyIfMissing(
+        path.join(gardenPackageRoot, "templates", "site", lang === "en" ? "Makefile.en" : "Makefile"),
+        path.join(destinationRoot, "Makefile"),
+      )
+    ) {
+      added.push("Makefile");
+    }
+    if (added.length) {
+      process.stdout.write(
+        lang === "en"
+          ? `Added missing site files: ${added.join(", ")}\n`
+          : `已补齐站点文件：${added.join("、")}\n`,
+      );
+    }
 
-  const added = [];
-  if (
-    copyIfMissing(
-      path.join(gardenPackageRoot, "templates", "site", lang === "en" ? "Makefile.en" : "Makefile"),
-      path.join(destinationRoot, "Makefile"),
-    )
-  ) {
-    added.push("Makefile");
+    installSkill(destinationRoot, { onlyMissing: true, lang });
+    if (process.env.GARDEN_SKIP_HOOKS !== "1") installHook(destinationRoot, { quiet: true, lang });
   }
-  if (added.length) {
-    process.stdout.write(
-      lang === "en"
-        ? `Added missing site files: ${added.join(", ")}\n`
-        : `已补齐站点文件：${added.join("、")}\n`,
-    );
-  }
-
-  installSkill(destinationRoot, { onlyMissing: true, lang });
-  if (process.env.GARDEN_SKIP_HOOKS !== "1") installHook(destinationRoot, { quiet: true, lang });
+  await offerEditorsOnce(destinationRoot, lang);
 }
 
 const HOOK_MARKER = "# garden: ui check";
@@ -272,19 +274,19 @@ function installHook(destinationRoot = siteRoot, { quiet = false, force = false,
   );
 }
 
-function prepare() {
+async function prepare() {
   ensureEnv();
   ensurePublic();
   fs.mkdirSync(path.join(siteRoot, "content", "posts"), { recursive: true });
   fs.mkdirSync(path.join(siteRoot, "content", "thoughts"), { recursive: true });
-  ensureSiteKit();
+  await ensureSiteKit();
 }
 
-function sync() {
+async function sync() {
   if (!fs.existsSync(path.join(siteRoot, "site.config.yaml"))) {
     fail(`当前目录不是 Garden 站点（缺少 site.config.yaml）：${siteRoot}`);
   }
-  prepare();
+  await prepare();
   runNode("scripts/build-content.mjs");
 }
 
@@ -313,8 +315,8 @@ function ensureDevGitHubLogin() {
   fs.writeFileSync(local, text.endsWith("\n") ? text : `${text}\n`);
 }
 
-function runVinext(vinextArgs, { copyDist = false } = {}) {
-  sync();
+async function runVinext(vinextArgs, { copyDist = false } = {}) {
+  await sync();
   const cwd = vinextRoot();
   const result = spawnSync(process.execPath, [resolveVinext(), ...vinextArgs], {
     cwd,
@@ -378,7 +380,7 @@ function writeEngineDependency(destination) {
   fs.writeFileSync(sitePkgPath, `${JSON.stringify(sitePkg, null, 2)}\n`);
 }
 
-function initSite() {
+async function initSite() {
   const { destination, lang } = parseInitArgs(rest);
   const template = path.join(gardenPackageRoot, "templates", "site");
   if (!fs.existsSync(template)) fail("Garden 包里缺少 templates/site。");
@@ -405,9 +407,10 @@ function initSite() {
     }
   }
   writeEngineDependency(destination);
+  process.stdout.write(lang === "en" ? `Created site: ${destination}\n` : `已创建站点：${destination}\n`);
+  installSkill(destination, { lang });
+  await offerEditorsOnce(destination, lang);
   if (lang === "en") {
-    process.stdout.write(`Created site: ${destination}\n`);
-    installSkill(destination, { lang });
     process.stdout.write("Next steps:\n");
     process.stdout.write(`  cd ${destination}\n`);
     process.stdout.write("  npm install\n");
@@ -417,8 +420,6 @@ function initSite() {
     printGiscusGuide("en");
     return;
   }
-  process.stdout.write(`已创建站点：${destination}\n`);
-  installSkill(destination);
   process.stdout.write("下一步：\n");
   process.stdout.write(`  cd ${destination}\n`);
   process.stdout.write("  npm install\n");
@@ -428,6 +429,35 @@ function initSite() {
   printGiscusGuide("zh");
 }
 
+function editorInstallFlags(argv) {
+  const known = new Set(["--vscode", "--typora", "--yes"]);
+  for (const arg of argv) {
+    if (!known.has(arg)) {
+      const lang = siteCliLang(siteRoot);
+      fail(lang === "en" ? `Unknown option: ${arg}` : `未知参数：${arg}`);
+    }
+  }
+  return {
+    vscode: argv.includes("--vscode"),
+    typora: argv.includes("--typora"),
+    yes: argv.includes("--yes"),
+  };
+}
+
+async function editorsCommand(argv) {
+  const lang = siteCliLang(siteRoot);
+  const sub = argv[0];
+  if (sub !== "install") {
+    fail(
+      lang === "en"
+        ? "Usage: garden editors install [--vscode] [--typora] [--yes]"
+        : "用法：garden editors install [--vscode] [--typora] [--yes]",
+    );
+  }
+  const status = await editorsInstall(siteRoot, lang, editorInstallFlags(argv.slice(1)));
+  if (status) process.exit(status);
+}
+
 function packagedSkills() {
   const root = path.join(gardenPackageRoot, ".agents", "skills");
   if (!fs.existsSync(root)) return [];
@@ -473,6 +503,7 @@ function help() {
   garden check <文章.md>  检查一篇博文的硬性结构
   garden ui <子命令>      Intelligent UI：scan、check、apply、prompt、schema、catalog
   garden hooks            安装提交前检查（检查暂存稿件里的 ui 块）
+  garden editors install  安装 Intelligent UI 插件到 VS Code / Cursor 与 Typora（--vscode、--typora、--yes）
   garden skill            把引擎自带的 skill 装进当前站点
   garden pages:validate   检查 dist/client
   garden pages:prepare    写入公开产物仓库
@@ -480,85 +511,92 @@ function help() {
 `);
 }
 
-switch (command) {
-  case "help":
-  case "--help":
-  case "-h":
-    help();
-    break;
-  case "sync":
-    sync();
-    break;
-  case "dev":
-    ensureDevGitHubLogin();
-    runVinext(["dev", ...rest]);
-    break;
-  case "build":
-    // Favicons are refetched on every build; failures fall back to link-assets.json.
-    if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/link-assets.mjs");
-    // Remote image sizes: only new images are probed; the rest come from image-sizes.json.
-    if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/image-sizes.mjs");
-    // Sizes of remote files in garden file blocks; failures fall back to file-sizes.json.
-    if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/file-sizes.mjs");
-    runVinext(["build", ...rest], { copyDist: true });
-    // /favicon.ico from the site's own icon (brand.favicon).
-    runNode("scripts/favicon-ico.mjs");
-    // Pages for old addresses listed under redirects in site.config.yaml (static export only).
-    if (process.env.STATIC_EXPORT === "1") {
-      // What the export wrote for empty dynamic routes (ui/garden/static-params.mjs).
-      runNode("scripts/static-placeholders.mjs");
-      runNode("scripts/redirects.mjs");
-      // <html lang="en"> on the English handbook pages.
-      runNode("scripts/html-lang.mjs");
-      // 404.html also under basePath when the host serves that folder alone.
-      runNode("scripts/static-404.mjs");
-    }
-    break;
-  case "links":
-    runNode("scripts/link-assets.mjs");
-    break;
-  case "images":
-    runNode("scripts/image-sizes.mjs");
-    break;
-  case "files":
-    runNode("scripts/file-sizes.mjs");
-    break;
-  case "start":
-    runVinext(["start", ...rest]);
-    break;
-  case "new":
-    runNode("scripts/new-post.mjs", rest);
-    break;
-  case "embed":
-    runNode("scripts/fetch-embed.mjs", rest);
-    break;
-  case "check":
-    runNode("scripts/check-post.mjs", rest);
-    break;
-  case "ui":
-    runNode("scripts/ui-cli.mjs", rest, { cwd: process.cwd() });
-    break;
-  case "hooks":
-    installHook(siteRoot, { force: rest.includes("--force") });
-    break;
-  case "init":
-    initSite();
-    break;
-  case "skill":
-  case "skills":
-    installSkill();
-    break;
-  case "pages:validate":
-    runNode("scripts/prepare-pages-output.mjs", [
-      rest[0] ?? path.join(siteRoot, "dist", "client"),
-    ]);
-    break;
-  case "pages:prepare":
-    runNode("scripts/prepare-pages-output.mjs", rest);
-    break;
-  case "webmentions":
-    runNode("scripts/send-webmentions.mjs", rest);
-    break;
-  default:
-    fail(`未知命令：${command}`);
+async function main() {
+  switch (command) {
+    case "help":
+    case "--help":
+    case "-h":
+      help();
+      break;
+    case "sync":
+      await sync();
+      break;
+    case "dev":
+      ensureDevGitHubLogin();
+      await runVinext(["dev", ...rest]);
+      break;
+    case "build":
+      // Favicons are refetched on every build; failures fall back to link-assets.json.
+      if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/link-assets.mjs");
+      // Remote image sizes: only new images are probed; the rest come from image-sizes.json.
+      if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/image-sizes.mjs");
+      // Sizes of remote files in garden file blocks; failures fall back to file-sizes.json.
+      if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/file-sizes.mjs");
+      await runVinext(["build", ...rest], { copyDist: true });
+      // /favicon.ico from the site's own icon (brand.favicon).
+      runNode("scripts/favicon-ico.mjs");
+      // Pages for old addresses listed under redirects in site.config.yaml (static export only).
+      if (process.env.STATIC_EXPORT === "1") {
+        // What the export wrote for empty dynamic routes (ui/garden/static-params.mjs).
+        runNode("scripts/static-placeholders.mjs");
+        runNode("scripts/redirects.mjs");
+        // <html lang="en"> on the English handbook pages.
+        runNode("scripts/html-lang.mjs");
+        // 404.html also under basePath when the host serves that folder alone.
+        runNode("scripts/static-404.mjs");
+      }
+      break;
+    case "links":
+      runNode("scripts/link-assets.mjs");
+      break;
+    case "images":
+      runNode("scripts/image-sizes.mjs");
+      break;
+    case "files":
+      runNode("scripts/file-sizes.mjs");
+      break;
+    case "start":
+      await runVinext(["start", ...rest]);
+      break;
+    case "new":
+      runNode("scripts/new-post.mjs", rest);
+      break;
+    case "embed":
+      runNode("scripts/fetch-embed.mjs", rest);
+      break;
+    case "check":
+      runNode("scripts/check-post.mjs", rest);
+      break;
+    case "ui":
+      runNode("scripts/ui-cli.mjs", rest, { cwd: process.cwd() });
+      break;
+    case "hooks":
+      installHook(siteRoot, { force: rest.includes("--force") });
+      break;
+    case "editors":
+      await editorsCommand(rest);
+      break;
+    case "init":
+      await initSite();
+      break;
+    case "skill":
+    case "skills":
+      installSkill();
+      break;
+    case "pages:validate":
+      runNode("scripts/prepare-pages-output.mjs", [
+        rest[0] ?? path.join(siteRoot, "dist", "client"),
+      ]);
+      break;
+    case "pages:prepare":
+      runNode("scripts/prepare-pages-output.mjs", rest);
+      break;
+    case "webmentions":
+      runNode("scripts/send-webmentions.mjs", rest);
+      break;
+    default:
+      fail(`未知命令：${command}`);
+  }
 }
+
+await main();

package/docs/handbook/ai-writing.md

@@ -1,7 +1,7 @@
 ---
 title: 用 AI 写作
 navTitle: 用 AI 写作
-description: 用一句话描述想要的组件，交给 Agent 生成；提交前由同一个脚本检查，失败时打印可粘贴给 AI 的修复提示词。
+description: 用编辑器插件插入想法并预览，交给 Agent 编译；提交前由同一个脚本检查。
 section: getting-started
 order: 2
 ---
@@ -82,15 +82,41 @@ pages:
 
 Agent 按 `garden-ui` skill 会把这个想法块替换成一段紧挨着完整代码的 `diff` 围栏。页面渲染时会把完整代码和 `diff` 合成一个带「代码 / 对比上一版」切换按钮的代码框，手写 `diff` 的规则见 [写文章与随想](/garden/writing)。
 
-## 6. 不使用 Agent 时的快捷输入
+## 6. 在编辑器里插入、预览，再交给 skill 编译
+
+VS Code、Cursor 和 Typora 的 Intelligent UI 插件把上面的流程放到写稿的地方。插件随 `hd-garden` 发布。`npx hd-garden init` 把产物复制到 `.garden/editors/`，并在交互终端里询问要不要安装。第一次 `npx garden sync` 如果还没问过，会再问一次。非交互环境、`CI=1` 或 `GARDEN_SKIP_EDITORS=1` 只打印提示，不阻塞。手动安装：
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+npx garden editors install --vscode
+npx garden editors install --typora
+```
+
+装好之后，一篇组件通常是这四步：
+
+1. **插入想法。** 在要放组件的位置运行「插入 Garden 块」（VS Code / Cursor 的快捷键是 macOS `Cmd+Alt+I`，Windows / Linux `Ctrl+Alt+I`）。Typora 里输入 `/` 后选 `/garden`，下一层列表每一项有一张小预览图；命令的快捷键在 Windows / Linux 是 `Ctrl+Alt+I`，macOS 需要在「设置 → 快捷键」里自己录。插入的是给 `garden-ui` skill 编译的想法围栏，例如选「资源卡」得到：
+
+   ````markdown
+   ```garden
+   做成资源卡。一篇论文、一个仓库或一本书，读者需要标题、链接和一句说明。请写上链接、标题、一句说明。
+   ```
+   ````
+2. **预览。** 打开 Markdown 预览，或在 Typora 里把光标移出围栏。`intent` 显示成想法卡片；skill 写回 `ui` 之后，预览画成和博客一样的组件。错误会标在源码上（VS Code / Cursor 的「问题」面板和 CodeLens）。
+3. **看清单。** 命令「查看组件清单」，或在终端运行 `npx garden ui catalog` 打开 `.garden/ui-catalog.html`。清单里的「用它开始」把配方插进当前稿件，适合已经知道要用哪一种组件的时候。
+4. **编译。** 「复制编译提示词」。中文站点得到 `编译这篇：<相对路径>`，英文站点得到 `Compile this post: <相对路径>`。把这句话发给 `garden-ui` skill。Agent 用 `npx garden ui scan` 定位，用 `npx garden ui prompt` 读规则，用 `npx garden ui apply` 写回。插件不调用模型。
+
+**Typora 的前提。** 先安装 [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md)。`npx garden editors install --typora` 把插件复制到 `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`（macOS 同时写到 `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`），然后在「设置 → 已安装插件」里勾选 Garden Intelligent UI。升级 Typora 会覆盖社区框架，需要重装框架后再勾选。没找到 `code` 或 `cursor` 时，用扩展视图的 Install from VSIX 选择 `.garden/editors/vscode/` 里的文件。安装细节见 [语法检查与快捷输入](/garden/workflow)。
+
+## 7. 不使用 Agent 时的快捷输入
 
 不借助 AI 手写组件时，可以直接使用包内自带的模板与代码片段：
 
 - `make new` 创建的草稿底部自带一段 `<!-- 组件速查 ... -->` 注释，包含想法块和 12 个组件的示例，写完可直接删掉。
 - `templates/garden-blocks.md` 汇总了想法块与 12 个组件的适用场景（`when` / `whenNot`）和可复制示例；macOS 与 Typora / Alfred 用户可导入 `templates/garden-snippets.plist`，输入 `;gidea`（或 `;garden想法`）、`;gcard`、`;gstat`、`;gcompare`、`;gtimeline`、`;gchart`、`;gfigure`、`;ghtml`、`;ginteractive`、`;gfile`、`;grel`、`;glist`、`;gchoice` 即可展开对应围栏。
-- 引擎仓库的 `editors/vscode`、`editors/typora` 与 `editors/obsidian` 目录提供了对应的编辑器片段与插件支持，运行 `npx garden ui catalog` 则可在本地生成 `.garden/ui-catalog.html` 离线组件画廊。
+- 编辑器插件的用法见上一节。`npx garden ui catalog` 在本地生成 `.garden/ui-catalog.html` 离线组件画廊。
 
-## 7. 可选的独立管理后台
+## 8. 可选的独立管理后台
 
 Garden 引擎仓库内置了可选的 `/admin` 管理后台（位于 `app/admin` 与 `worker/`），可通过 `npm run admin:local`、`npm run admin:cloudflare` 或 Docker 单独部署。配置环境变量后，后台提供以下网页端功能：
 

package/docs/handbook/en/ai-writing.md

@@ -1,7 +1,7 @@
 ---
 title: Writing with AI
 navTitle: Writing with AI
-description: Describe components in one sentence for an Agent to compile, and validate staged files with the same CLI in the pre-commit hook.
+description: Insert and preview ideas with the editor plugins, let an Agent compile them, and validate staged files with the same CLI.
 section: getting-started
 order: 2
 ---
@@ -82,15 +82,35 @@ Compared with the previous version: split the title into two lines with " | " in
 
 Following the `garden-ui` skill, the Agent replaces that idea fence with a `diff` fence right below the code block. The page merges the adjacent code and `diff` fences into a single code frame with a toggle between the full code and the diff; see [Writing Posts & Thoughts](/garden/en/writing) for the hand-written `diff` format.
 
-## 6. Templates and Snippets Without an Agent
+## 6. Insert, Preview, and Compile from the Editor
+
+The VS Code, Cursor, and Typora Intelligent UI plugins put the flow above in the editor. They ship inside `hd-garden`. `npx hd-garden init` copies them to `.garden/editors/` and asks whether to install them when the terminal is interactive. The first `npx garden sync` asks again if that prompt has not happened yet. A non-interactive shell, `CI=1`, or `GARDEN_SKIP_EDITORS=1` prints the hint and does not block. Install later with:
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+npx garden editors install --vscode
+npx garden editors install --typora
+```
+
+A component then takes four steps:
+
+1. **Insert an idea.** Where the component should go, run the Garden insert command (`Cmd+Alt+I` on macOS, `Ctrl+Alt+I` on Windows and Linux in VS Code / Cursor). In Typora, type `/` and choose `/garden` to open a picker with a small preview image on each row; the command shortcut is `Ctrl+Alt+I` on Windows and Linux, and macOS needs a shortcut recorded under Settings, Keyboard Shortcuts. The insertion is a plain `garden` fence whose body tells the `garden-ui` skill which component to compile and which facts to include.
+2. **Preview.** Open the Markdown preview, or in Typora move the cursor out of the fence. An `intent` block shows as an idea card. After the skill writes a `ui` block, the preview matches the blog. VS Code / Cursor also report errors in Problems and in the CodeLens above the block.
+3. **Open the catalog.** Use the catalog command, or run `npx garden ui catalog` and open `.garden/ui-catalog.html`. Starting from a recipe inserts it at the cursor when you already know which component you want.
+4. **Compile.** Copy the compile prompt. On an English site the clipboard text is `Compile this post:` plus the post path. Paste it to the `garden-ui` skill. The Agent locates the block with `npx garden ui scan`, reads the rules with `npx garden ui prompt`, and writes it back with `npx garden ui apply`. The plugin does not call a model.
+
+**Typora prerequisite.** Install [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md) first. `npx garden editors install --typora` copies the plugin to `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`. On macOS it also copies to `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`. Enable Garden Intelligent UI under Settings, Installed plugins. A Typora upgrade overwrites the community framework; reinstall the framework, then enable the plugin again. If `code` or `cursor` is not on `PATH`, use Install from VSIX in the Extensions view and select the file under `.garden/editors/vscode/`. Install details are in [Checks & Shortcuts](/garden/en/workflow).
+
+## 7. Templates and Snippets Without an Agent
 
 When writing components by hand without AI, you can use the templates and snippets shipped in the package:
 
 - Every draft created by `make new` includes an HTML comment at the bottom with copy-ready examples for idea fences and all 12 components; delete the comment whenever you are done.
 - `templates/garden-blocks.md` lists `when` / `whenNot` guidance and copyable templates for every block; macOS, Typora, and Alfred users can import `templates/garden-snippets.plist` to expand `;gidea`, `;gcard`, `;gstat`, `;gcompare`, `;gtimeline`, `;gchart`, `;gfigure`, `;ghtml`, `;ginteractive`, `;gfile`, `;grel`, `;glist`, and `;gchoice`.
-- The engine repository also ships editor integrations under `editors/vscode`, `editors/typora`, and `editors/obsidian`, and `npx garden ui catalog` generates an offline component catalog at `.garden/ui-catalog.html`.
+- Editor plugin usage is in the previous section. `npx garden ui catalog` writes an offline component catalog at `.garden/ui-catalog.html`.
 
-## 7. Optional Standalone Admin
+## 8. Optional Standalone Admin
 
 The Garden engine includes an optional `/admin` console (under `app/admin` and `worker/`) that can be deployed separately with `npm run admin:local`, `npm run admin:cloudflare`, or Docker. Once configured via environment variables, it provides:
 

package/docs/handbook/en/index.md

@@ -187,6 +187,7 @@ make dev
 Run `make update` when a post is ready; it runs the full check and build before committing and pushing. Read the chapters for details:
 
 - **[Quick Start](/garden/en/start)**: Directory layout, creating posts with `make new`, previewing drafts, and daily commands.
+- **[Writing with AI](/garden/en/ai-writing)** and **[Checks & Shortcuts](/garden/en/workflow)**: Insert an idea, preview the component, and open the catalog in VS Code, Cursor, or Typora, and install the plugins with `npx garden editors install`.
 - **[Site & Column Config](/garden/en/config)**: Every field in `site.config.yaml`, custom SVG icons, and ordering series in `content/columns.yaml`.
 - **[Deploy to GitHub Pages](/garden/en/deploy)**: A single GitHub Actions workflow that supports both one public repository and a private source repo paired with a public Pages repo.
 - **[Writing Posts & Thoughts](/garden/en/writing)** and **[How the Reading Layout Works](/garden/en/design)**: Front Matter fields, three-tier adaptive widths, and color tokens. Link cards, source chips, and local images are on [Components Overview](/garden/en/components).