feat: 插件检验器 plugin:check + L6/L7 教程 + 模板接入组件库——性能与样式标准成为机器关卡
This commit is contained in:
Rick Ye
+14
-1
@@ -120,7 +120,20 @@ export const { jsx, jsxs, Fragment } = J
|
||||
```
|
||||
|
||||
- 装载时机与热重载：插件列表变化（扫描/启停/`plugins:reload`）即按 `?t=` cache-bust 重装；被禁用/移除的插件注册随之清除
|
||||
- 门控：仅开发版装载（`import.meta.env.DEV` + 主进程 `EXTERNAL_PLUGINS_ENABLED`）；错误隔离到单插件（装载失败仅 console.error，渲染崩溃由 PluginErrorBoundary 兜底）
|
||||
- 门控：仅开发版装载（`import.meta.env.DEV` + 主进程 `EXTERNAL_PLUGINS_ENABLED`）
|
||||
- 性能护栏：读源与 import 各限时 8s，超时/失败由宿主槽位呈现统一等待/失败态（ErrorState + 重试，见 `plugins/renderer-host`）；渲染期崩溃由 PluginErrorBoundary 兜底
|
||||
|
||||
## 公共 UI 组件库与异步工具（`@aso/plugin-sdk/ui` · `withTimeout`/`withRetry`）
|
||||
|
||||
- **`./ui` 子入口**：宿主视觉规范的代码化——`Button`/`Input`/`Select`/`Switch`/`Card`/`SettingRow`/`Badge`
|
||||
+ 三态组件 `LoadingState`/`ErrorState`/`EmptyState`/`Spinner`。仅 renderer 组件槽位可用
|
||||
（渲染在宿主 DOM，复用宿主样式表）；组件目录与三态铁律见 [docs/plugins/07-ui-components.md](./plugins/07-ui-components.md)
|
||||
- **异步工具（主入口导出）**：`withTimeout(promise, ms, label?)`、`withRetry(fn, { retries, delayMs, timeoutMs, onRetry })`、
|
||||
`TimeoutError`——插件内一切可能挂起的异步（网络/子进程/文件轮询）必须自带超时与重试
|
||||
- **宿主兜底**：插件激活限时 10s（异步工厂超时/reject 即标记插件失败，不拖垮 runtime 重建）；
|
||||
renderer 装载限时 8s
|
||||
- **机器关卡**：`pnpm plugin:check <插件目录>` 校验契约完整性、同步 IO、console.*、
|
||||
React 单实例、hex 色值、三态使用等（error 级不通过即 exit 1），规则见 [docs/plugins/08-performance.md](./plugins/08-performance.md)
|
||||
|
||||
## 插件设置（声明式 schema，`api.ui.registerSettings`）
|
||||
|
||||
|
||||
@@ -42,9 +42,13 @@ export default function mount(ctx) {
|
||||
```sh
|
||||
esbuild renderer.tsx --bundle --format=esm --outfile=renderer.mjs \
|
||||
--jsx=automatic \
|
||||
--alias:react=./shims/react.js --alias:react/jsx-runtime=./shims/jsx-runtime.js
|
||||
--alias:react=./shims/react.js --alias:react/jsx-runtime=./shims/jsx-runtime.js \
|
||||
--alias:@aso/plugin-sdk=<sdk源码路径>/index.ts --alias:@aso/plugin-sdk/ui=<sdk源码路径>/ui.tsx
|
||||
```
|
||||
|
||||
> 最后两条 alias 只在用到 `@aso/plugin-sdk`（withTimeout 等）或 `./ui` 组件库时需要；
|
||||
> sdk 以源码形态发布（exports 指向 .ts/.tsx），esbuild 无法按包名解析，指路径即可。
|
||||
|
||||
```js
|
||||
// shims/react.js —— 从宿主全局取单例
|
||||
const R = window.__ASO_PLUGIN_HOST__.react
|
||||
@@ -72,13 +76,14 @@ export const { jsx, jsxs, Fragment } = window.__ASO_PLUGIN_HOST__.jsxRuntime
|
||||
|
||||
## 5. 样式
|
||||
|
||||
组件直接跑在宿主树里——**宿主的 Tailwind 类与 token 全部可用**（`text-ink`、`border-line`、`rounded-card`、`bg-accent` …）。必须遵守 [DESIGN.md](./DESIGN.md) 的类名词汇与布局模式，禁止硬编码色值/阴影。
|
||||
组件直接跑在宿主树里——**宿主的 Tailwind 类与 token 全部可用**。标准模式已代码化：优先 `import { Button, SettingRow, LoadingState, ErrorState, EmptyState, Switch } from '@aso/plugin-sdk/ui'`（组件目录与三态铁律见 [L6](./07-ui-components.md)），不要手写；遵守 [DESIGN.md](./DESIGN.md) 的类名词汇，禁止硬编码色值/阴影。
|
||||
|
||||
## 6. 生命周期
|
||||
|
||||
- 装载：插件列表变化（启停/重载/启动）即重装；`mount` 同步执行注册
|
||||
- 卸载：插件禁用/移除 → 注册的组件自动从宿主卸载
|
||||
- 崩溃隔离：渲染错误被 `PluginErrorBoundary` 捕获，不影响宿主；装载失败仅 console.error + 日志
|
||||
- 性能护栏：读源与 import 各限时 8s——超时/失败时槽位呈现宿主统一「装载失败」ErrorState（带重试），见 [L7](./08-performance.md)
|
||||
- 崩溃隔离：渲染错误被 `PluginErrorBoundary` 捕获，不影响宿主
|
||||
|
||||
## 7. 验证
|
||||
|
||||
@@ -88,4 +93,4 @@ export const { jsx, jsxs, Fragment } = window.__ASO_PLUGIN_HOST__.jsxRuntime
|
||||
|
||||
---
|
||||
|
||||
**上一篇** [L3](./04-ui-slots.md) · **下一篇**：[L5 自诊断](./06-self-diagnosis.md)——让 Agent 能发现并修复你的插件问题。
|
||||
**上一篇** [L3](./04-ui-slots.md) · **下一篇**：[L6 公共组件库](./07-ui-components.md)——别手写样式，宿主把标准模式做成了组件。
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
# L6 · 公共 UI 组件库（@aso/plugin-sdk/ui）
|
||||
|
||||
> 前置：[L4 React 组件](./05-renderer-components.md)。约 15 分钟。
|
||||
> 目标：不写一行样式代码，做出与宿主完全一致的界面；等待/失败/空态不再自造。
|
||||
|
||||
## 为什么必须用它
|
||||
|
||||
[DESIGN.md](./DESIGN.md) 定了「长什么样」，组件库把它变成「直接拿来的代码」：
|
||||
|
||||
- **token 同源**：组件内部只用宿主已核验的类词汇（`text-ink-3`、`rounded-control`…）
|
||||
与 `var(--token)` 内联变量，深浅色自动跟随宿主主题
|
||||
- **三态统一**：等待 `LoadingState` / 失败 `ErrorState`（可重试）/ 空 `EmptyState`，
|
||||
任何插件的加载体验与宿主一致
|
||||
- **零依赖**：`./ui` 是 sdk 源码子路径，随 esbuild 一起打进 renderer.mjs，
|
||||
不引任何第三方 UI 库（shadcn/ui 的思路——无运行时、复制即用——由宿主承担）
|
||||
|
||||
## 导入与构建
|
||||
|
||||
```tsx
|
||||
import { Button, LoadingState, ErrorState, EmptyState, SettingRow, Switch } from '@aso/plugin-sdk/ui'
|
||||
```
|
||||
|
||||
构建命令与 L4 完全相同——`ui` 随 sdk 源码一起被打包，react 别名照旧：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
## 组件目录
|
||||
|
||||
| 组件 | 用途 | 要点 |
|
||||
|---|---|---|
|
||||
| `Spinner` | 行内旋转指示 | `size` 默认 14px |
|
||||
| `LoadingState` | 区块等待态 | `label` 可换文案，默认「加载中…」 |
|
||||
| `ErrorState` | 区块失败态 | `title`/`description`（错误消息）、`onRetry` 提供即显示重试按钮 |
|
||||
| `EmptyState` | 区块空态 | `title` + `description` + `action`（如「去设置」按钮） |
|
||||
| `Button` | 按钮 | `variant: 'primary' \| 'ghost' \| 'danger'`；`loading` 置灰并显示 Spinner，防重复提交 |
|
||||
| `Input` / `Textarea` | 输入 | 与宿主设置页同款外观 |
|
||||
| `Select` | 下拉 | `options: { value, label }[]`，原生 select |
|
||||
| `Switch` | 开关 | 受控 `checked`/`onCheckedChange`，或非受控 `defaultChecked` |
|
||||
| `Card` | 卡片容器 | `rounded-card` + line 边框 |
|
||||
| `SettingRow` | 设置行 | label 左 / 控件右（DESIGN §4 标准模式） |
|
||||
| `Badge` | 徽标 | `tone: 'neutral' \| 'accent' \| 'danger'`，版本/来源/状态元信息 |
|
||||
|
||||
全部组件接受 `className` 追加布局类（flex/间距/尺寸），**不接受**颜色/字号覆写——
|
||||
那两条路（hex、新字号）被 [L7 检验器](./08-performance.md)拦截。
|
||||
|
||||
## 三态铁律
|
||||
|
||||
任何异步区块的状态机：**loading → data | error | empty**，四选一，不允许第五种
|
||||
（白屏、裸文本「加载中」、无反馈的失败）。模板（plugin-template）是完整示范：
|
||||
|
||||
```tsx
|
||||
{error !== null ? (
|
||||
<ErrorState title="数据加载失败" description={error} onRetry={() => setTick((t) => t + 1)} />
|
||||
) : items === null ? (
|
||||
<LoadingState label="正在拉取数据…" />
|
||||
) : items.length === 0 ? (
|
||||
<EmptyState title="暂无数据" description="检查数据源后点击重新加载" />
|
||||
) : (
|
||||
items.map((it) => <SettingRow key={it} label={it} />)
|
||||
)}
|
||||
```
|
||||
|
||||
配套铁律：异步调用必须 `withTimeout`/`withRetry`（见 L7），否则 loading 态可能永远挂着。
|
||||
|
||||
## 宿主兜底
|
||||
|
||||
renderer 模块的读源与 import 宿主各限时 8 秒：超时或失败时，插件槽位自动呈现宿主侧
|
||||
「插件界面装载失败」ErrorState（带重试按钮）；组件渲染期崩溃由 PluginErrorBoundary
|
||||
兜底。也就是说**装载失败不需要插件自己处理**，插件只需管好自己组件内部的异步。
|
||||
|
||||
## 边界
|
||||
|
||||
- 仅 renderer 组件槽位可用（渲染在宿主 DOM，复用宿主样式表）；iframe 插件页是物理
|
||||
隔离文档，请按 [DESIGN.md](./DESIGN.md) §4 的 HTML 模式自行实现
|
||||
- 需要新形态时：先用现有组件拼；确实不够，在 DESIGN.md 约束内组合 token，
|
||||
并把新形态沉淀回团队公共代码，而不是留在单个插件里
|
||||
|
||||
---
|
||||
|
||||
**上一篇** [L5 自诊断](./06-self-diagnosis.md) · **下一篇**：[L7 性能与检验](./08-performance.md)——超时、重试与机器关卡。
|
||||
@@ -0,0 +1,100 @@
|
||||
# L7 · 性能与检验（plugin:check）
|
||||
|
||||
> 前置：L0–L6。约 20 分钟。
|
||||
> 目标：插件百花齐放，但**绝不卡宿主、绝不风格跑偏**；发布前有机器关卡把关。
|
||||
|
||||
## 性能铁律
|
||||
|
||||
### 1. 主进程不阻塞（检验器：error）
|
||||
|
||||
`main.mjs` 运行在宿主主进程。任何同步 IO——`fs` 的 `*Sync`、`execSync`、
|
||||
`spawnSync`——都会卡住**整个应用**的事件循环（聊天流、其他插件全部冻结）。
|
||||
一律用 `node:fs/promises` 与异步子进程：
|
||||
|
||||
```js
|
||||
// ❌ const text = fs.readFileSync(path, 'utf8')
|
||||
// ✅
|
||||
import { readFile } from 'node:fs/promises'
|
||||
const text = await readFile(path, 'utf8')
|
||||
```
|
||||
|
||||
### 2. 激活限时 10 秒（宿主强制）
|
||||
|
||||
插件工厂若返回 Promise，宿主限时 10s；超时或 reject 即把插件标记为失败
|
||||
（插件管理页可见红字），绝不无限等待拖垮 runtime 重建。因此：
|
||||
|
||||
- 激活路径只做「注册」级别的工作，重活（预取数据、预热连接）放到工具首次调用
|
||||
- 自己 `catch` 并 `api.log.error`——被宿主兜住意味着插件没跑起来
|
||||
|
||||
### 3. renderer 装载限时 8 秒（宿主强制）
|
||||
|
||||
读源与 import 各限时 8s，超时/失败由宿主呈现统一失败态（重试按钮）；
|
||||
组件渲染期崩溃由 PluginErrorBoundary 兜底。插件只需管好组件内部的异步。
|
||||
|
||||
### 4. 自己的异步自己兜（sdk 提供 `withTimeout` / `withRetry`）
|
||||
|
||||
先于宿主超时并自行恢复，而不是等宿主判死：
|
||||
|
||||
```js
|
||||
import { withTimeout, withRetry, TimeoutError } from '@aso/plugin-sdk'
|
||||
|
||||
// 网络请求：3s 超时，失败退避重试 2 次（300ms → 600ms）
|
||||
const data = await withRetry(() => callApi(), { retries: 2, delayMs: 300, timeoutMs: 3000 })
|
||||
|
||||
// 单次限时
|
||||
const cfg = await withTimeout(loadConfig(), 2000, '加载配置')
|
||||
try {
|
||||
await risky()
|
||||
} catch (err) {
|
||||
if (err instanceof TimeoutError) { /* 降级路径 */ }
|
||||
throw err
|
||||
}
|
||||
```
|
||||
|
||||
注意：`withTimeout` 只是竞速，底层操作不会被取消——有 `AbortController` 的
|
||||
调用方请把 signal 接到底层，再用它兜底计时。
|
||||
|
||||
### 5. 渲染不卡顿
|
||||
|
||||
长列表分页/虚拟化，不要一次渲染数万节点；重计算放进工具（Agent 侧）或
|
||||
`setTimeout(fn, 0)` 分帧，不占渲染主线程。
|
||||
|
||||
## 三态呈现（检验器：warn）
|
||||
|
||||
任何异步 UI 必须是四态之一：`LoadingState` / `ErrorState` / `EmptyState` / 数据。
|
||||
`alert`/`confirm`/`prompt` 是阻塞式同步对话框，禁止（用 `Button` + 状态组件替代）。
|
||||
详见 [L6](./07-ui-components.md)。
|
||||
|
||||
## 样式一致性（检验器：error）
|
||||
|
||||
- 只用公共组件库 + [DESIGN.md](./DESIGN.md) token；硬编码 hex 色值是 error
|
||||
（`#fff`/`#ffffff` 白字除外）
|
||||
- renderer.mjs 必须经宿主 shim 使用单实例 React（`__ASO_PLUGIN_HOST__`）——
|
||||
自带 React 副本 = hooks 全部失效
|
||||
|
||||
## 日志（检验器：error）
|
||||
|
||||
`main.mjs` 禁 `console.*`，统一 `api.log.*`——Agent 自诊断闭环见 [L5](./06-self-diagnosis.md)。
|
||||
|
||||
## 检验器：`pnpm plugin:check <插件目录>`
|
||||
|
||||
发布前必跑；Agent 自迭代时，**通过检验器是完成定义（DoD）的一部分**。
|
||||
|
||||
| 级别 | 检查项 |
|
||||
|---|---|
|
||||
| error | manifest 缺失/不可解析；id/name/version(semver) 缺失；minContract 高于宿主契约；entry 指向的文件不存在；renderer.mjs > 8MB / main.mjs > 2MB；main.mjs 同步 IO；main.mjs `console.*`；renderer.mjs 未引用 `__ASO_PLUGIN_HOST__`；任何源码硬编码 hex 色值 |
|
||||
| warn | 缺 minContract；renderer.mjs > 300KB（疑似打包自带 React）；注册 view/panel 但未用三态组件；`alert/confirm/prompt`；entry.renderer 产物缺失但有 src/renderer.tsx（未构建） |
|
||||
|
||||
宿主契约版本从 `plugin-host.ts` 源码提取（单一事实源），检验器与宿主永不会各执一词。
|
||||
|
||||
## 一张自查表
|
||||
|
||||
- [ ] `pnpm plugin:check <目录>` 0 error
|
||||
- [ ] main.mjs 无同步 IO，激活 10s 内完成
|
||||
- [ ] 一切异步有超时与重试，catch 后 `api.log` + `ErrorState`
|
||||
- [ ] 长列表不整批渲染
|
||||
- [ ] 深浅色各看一眼（token 正确时自动成立）
|
||||
|
||||
---
|
||||
|
||||
**上一篇** [L6 公共组件库](./07-ui-components.md) · 返回 [教程索引](./README.md)
|
||||
@@ -68,6 +68,11 @@
|
||||
|
||||
## 4. 标准模式（复制即用）
|
||||
|
||||
> **renderer 组件优先用组件库**：本节模式已在 `@aso/plugin-sdk/ui` 代码化
|
||||
> （`Button`/`SettingRow`/`EmptyState`/`LoadingState`/`ErrorState`/`Badge`…，
|
||||
> 见 [L6](./07-ui-components.md)），直接 import，不要手写。
|
||||
> 下面的 HTML 形态留给 iframe 插件页作者。
|
||||
|
||||
### 设置行（label 左 / 控件右）
|
||||
|
||||
```html
|
||||
@@ -116,14 +121,16 @@
|
||||
|
||||
## 6. renderer 组件附加规则
|
||||
|
||||
- 类名直接用宿主词汇（§2），无需引样式
|
||||
- 类名直接用宿主词汇（§2），无需引样式；**优先 import 公共组件库**（[L6](./07-ui-components.md)），不要手写标准模式
|
||||
- React 必须来自 `ctx.react`（见 [L4](./05-renderer-components.md)），否则 hooks 失效
|
||||
- 禁止操作宿主 DOM（document 全局查询/改样式），一切交互限制在自己的组件子树
|
||||
- 机器关卡：`pnpm plugin:check <插件目录>`（hex 色值 / React 副本 / 三态缺失等，见 [L7](./08-performance.md)）
|
||||
|
||||
## 7. 自检清单（提发布前）
|
||||
|
||||
- [ ] `pnpm plugin:check <插件目录>` 0 error（机器关卡，见 [L7](./08-performance.md)）
|
||||
- [ ] 无硬编码色值/阴影/圆角（铁律 1）
|
||||
- [ ] 字号都在 §3 的阶上
|
||||
- [ ] 深浅色都检查过（切主题看一眼；token 正确时自动成立）
|
||||
- [ ] 复用了 §4 模式而非新造形态
|
||||
- [ ] 复用了 §4 模式（renderer 直接用组件库）而非新造形态
|
||||
- [ ] iframe 页引了 tokens.css 且无 `prefers-color-scheme`
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 插件开发教程（渐进式）
|
||||
|
||||
> 面向「写插件的人（含 Agent）」。从零到高级共 6 篇，每篇 10-30 分钟，逐篇递进、可独立验证。
|
||||
> 面向「写插件的人（含 Agent）」。从零到高级共 8 篇，每篇 10-30 分钟，逐篇递进、可独立验证。
|
||||
> 契约细节（类型/字段全集）见 [../plugins.md](../plugins.md)；UI 规范见 [DESIGN.md](./DESIGN.md)。
|
||||
|
||||
## 学习路径
|
||||
@@ -13,6 +13,8 @@
|
||||
| [L3 UI 槽位](./04-ui-slots.md) | 状态胶囊/工具栏按钮/视图/面板 tab/iframe 页 | 界面存在感 |
|
||||
| [L4 React 组件](./05-renderer-components.md) | entry.renderer：宿主内 React 组件 + JSX 构建配方 | 一等公民级 UI |
|
||||
| [L5 自诊断](./06-self-diagnosis.md) | 日志规范、排障闭环、Agent 自迭代约定 | 可被 Agent 维护的插件 |
|
||||
| [L6 公共组件库](./07-ui-components.md) | @aso/plugin-sdk/ui：统一三态（等待/失败/空）与基础控件 | 与宿主零差异的 UI |
|
||||
| [L7 性能与检验](./08-performance.md) | 主线程不阻塞、超时重试、plugin:check 机器关卡 | 可发布、不卡宿主的插件 |
|
||||
|
||||
## 30 秒总览
|
||||
|
||||
|
||||
+1
-1
@@ -12,7 +12,7 @@
|
||||
| v0.4.0 | 工具与审批 | 工具调用卡片（参数/结果折叠展示）、tool_call 拦截 → Approval Card、defineTool 业务工具骨架（本地可跑的演示工具） |
|
||||
| v0.5.0 | 打磨 | 深浅主题、GSAP 动效细节、快捷键、错误态/空态、队列可视化、自动滚动策略 |
|
||||
| v0.8.0 | 动态插件系统（M0–M3） | 两层能力模型（内置组件级/外置 iframe）、pi 原生契约聚合 extension、@aso/plugin-sdk、plugin://peer:// 协议、视图切换+聊天保活+徽标、侧栏/面板/胶囊/深链槽位、浏览器面板插件化、插件重载 |
|
||||
| v0.9.0 | 插件一等公民 + 可观测 | entry.renderer 宿主内 React 组件（Blob 装载+单实例 React）、.pi/extensions 一等插件源（build 开关门控）、声明式设置体系（13 控件+一级导航入口）、统一日志系统（滚动文件/api.log/IPC 追踪/渲染层错误归档）、渐进式教程 docs/plugins/ + DESIGN.md + plugin-template |
|
||||
| v0.9.0 | 插件一等公民 + 可观测 | entry.renderer 宿主内 React 组件（Blob 装载+单实例 React）、.pi/extensions 一等插件源（build 开关门控）、声明式设置体系（13 控件+一级导航入口）、统一日志系统（滚动文件/api.log/IPC 追踪/渲染层错误归档）、渐进式教程 docs/plugins/ + DESIGN.md + plugin-template、性能/样式标准与检验器（激活 10s/装载 8s 护栏、@aso/plugin-sdk/ui 组件库+三态、withTimeout/withRetry、plugin:check） |
|
||||
| 未来 | | 插件管理与 zip 导入（M4）、ed25519 签名在线更新（M5）、外置插件模板与开发工作流（M6）、pi 原生扩展目录管控（M7）、B3/B4/B5 槽位、electron-builder 打包与自动更新、i18n（中/英）、sqlite 持久化与迁移、本地备份恢复、热点词/生成/模板业务插件、手动模式编排 UI、RPC 子进程隔离模式 |
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user