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,88 @@
+# L3 · UI 槽位：胶囊、工具栏、视图、面板、iframe 页
+
+> 前置：[L0](./01-hello-plugin.md)。宿主开放 5 个数据驱动 UI 槽位 + 1 个 iframe 页形态。**数据驱动**意味着插件只提交数据，渲染与样式由宿主统一负责——这是 UI 一致性的第一道保障（自定义视觉见 [DESIGN.md](./DESIGN.md) 与 [L4](./05-renderer-components.md)）。
+
+## 1. 状态胶囊（TitleBar 顶部）
+
+轻量状态提示，点击可深链跳转：
+
+```js
+api.ui.setStatusItem('conn', {
+  text: '已连接 · 3 任务',
+  tone: 'accent',                       // default | accent | warn | danger
+  openView: { view: 'my-plugin' }       // 点击跳到插件整页视图（可省略）
+})
+api.ui.removeStatusItem('conn')
+```
+
+## 2. 工具栏按钮（输入区工具行）
+
+```js
+api.ui.registerToolbarButton({
+  id: 'open',
+  title: '打开我的面板',
+  icon: '<svg .../>',                   // 16-20px 线条风，currentColor
+  openView: { view: 'my-plugin' }
+})
+```
+
+## 3. 整页视图 + 侧栏入口
+
+manifest 声明 `icon` / `order` 后，插件自动出现在侧栏（有 UI 能力时）；任何槽位用 `openView` 深链：
+
+```js
+api.ui.openView('my-plugin', { section: 'detail' })   // params 透传给插件 UI
+api.ui.openView('chat')                               // 回到聊天
+```
+
+## 4. 面板 tab（右侧 SidePanel）
+
+manifest 加 `"panel": true`，插件在右侧面板获得一个 tab。
+
+## 5. iframe 插件页（entry.page）
+
+需要**完全自定义的 Web UI** 且不想构建 React 时用。物理隔离（sandbox iframe），经桥通信：
+
+```
+<插件目录>/index.html + 页面 JS
+manifest: "entry": { "page": "index.html" }
+```
+
+页面侧用 SDK 桥（`@aso/plugin-sdk/client`）：
+
+```html
+<script type="module">
+  import { getHarnessClient, useHarnessTheme, useDeepLinkParams } from './sdk-client.mjs'
+  const harness = getHarnessClient('my-plugin')
+  harness.openView('chat')                 // 深链
+  harness.setStatus('state', { text: '就绪' })
+  harness.invoke('getState')               // 白名单：getState / send / getSettings
+</script>
+```
+
+**样式统一（强制）**：插件页 `<head>` 里必须引宿主 token 表，并用自己的 Tailwind 按同样 token 名编译——
+
+```html
+<link rel="stylesheet" href="peer://assets/tokens.css" />
+```
+
+主题（深浅色/accent）由宿主推送（`useHarnessTheme`），禁止自行探测。详细规则见 [DESIGN.md](./DESIGN.md#iframe-插件页)。
+
+## 6. 安全边界速记
+
+| 形态 | 代码位置 | 能力 |
+|---|---|---|
+| main.mjs | 主进程 | 全权（与 pi 扩展同信任级） |
+| renderer.mjs（L4） | 渲染层 | 宿主 React + window.api 受控面 |
+| iframe 页 | 沙箱 iframe | 仅白名单桥（getState/send/getSettings/setStatus/openView） |
+
+## 7. 验证
+
+1. 状态胶囊：`setStatusItem` 后 TitleBar 立即出现，`removeStatusItem` 消失
+2. 面板 tab：`panel: true` + 任一 UI 形态 → 右侧面板出现 tab
+3. iframe 页：改页面文件 → 插件页开关触发重载 → iframe 换 src 整页刷新
+4. 全部 UI 状态在日志可查（`plugin activated` 之后你在 main.mjs 里的 `api.log` 输出）
+
+---
+
+**上一篇** [L2](./03-settings.md) · **下一篇**：[L4 React 组件](./05-renderer-components.md)——宿主内真 React 组件。