docs: 渐进式插件教程（L0→L5）+ DESIGN.md 视觉规范 + plugin-template 脚手架

2026-09-11 02:18:01 +08:00
parent 8e4b5496e8
commit 4ed31a34fc
16 changed files with 844 additions and 1 deletions
@@ -0,0 +1,44 @@
+# plugin-template · 插件脚手架
+
+复制本目录到插件位置（改目录名 = 改前先改 manifest.id），改掉 `id`/`name`/`description` 即完成最小定制。
+
+## 目录
+
+```
+manifest.json       清单（id/name/version/minContract 必改）
+main.mjs            主进程侧：Agent 能力 + 设置声明 + 日志埋点（范例齐备）
+src/renderer.tsx    宿主内 React 组件源码（JSX）
+shims/              构建期把 react 别名到宿主单例（勿改）
+```
+
+## 构建渲染层组件
+
+```sh
+esbuild src/renderer.tsx --bundle --format=esm --outfile=renderer.mjs \
+  --jsx=automatic \
+  --alias:react=./shims/react.js --alias:react/jsx-runtime=./shims/jsx-runtime.js
+```
+
+（esbuild 可用 `pnpm dlx esbuild@<版本>` 或任意 ≥0.17 版本；`--alias` 需 ≥0.17。）
+不需要 UI 时：删除 `entry.renderer` 与 `src/`、`shims/`，只保留 main.mjs。
+
+## 放置位置（三选一，按优先级）
+
+1. `userData/plugins/<id>/`（应用托管目录）
+2. `<工作区>/.pi/extensions/<id>/`（项目级）
+3. `~/.pi/agent/extensions/<id>/`（全局）
+
+第三方装载仅开发版开启（`ASO_EXTERNAL_PLUGINS=1` 豁免）。
+
+## 验证
+
+1. 重启或开关重载 → 设置 → 插件 → 对应作用域出现插件
+2. 日志 `userData/logs/main-*.log` 有 `plugin activated pluginId=my-plugin`
+3. 对 Agent 说"ping 一下我的插件" → 触发 `my_plugin_ping`
+4. 面板/侧栏出现 React 组件，点击 +1 正常（hooks 生效）
+
+## 下一步
+
+- 教程索引：`docs/plugins/README.md`（L0→L5）
+- 视觉规范：`docs/plugins/DESIGN.md`（提发布前过一遍自检清单）
+- 契约全集：`docs/plugins.md`