diff --git a/apps/desktop/electron.vite.config.ts b/apps/desktop/electron.vite.config.ts index 8f74fbb..ecccd98 100644 --- a/apps/desktop/electron.vite.config.ts +++ b/apps/desktop/electron.vite.config.ts @@ -74,6 +74,10 @@ export default defineConfig({ // 允许 dev server 读取工作区源码包（@aso/plugin-sdk 从 packages/ 链接进来） fs: { allow: [resolve(__dirname, '../..')] } }, + optimizeDeps: { + // sdk 是源码形态（exports 指向 .ts/.tsx），必须走源码 transform 而非预打包 + exclude: ['@aso/plugin-sdk'] + }, plugins: [react(), tailwindcss(), copyTokensCss()], resolve: { alias: { diff --git a/docs/plugins.md b/docs/plugins.md index d62c35d..505f3ae 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -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`） diff --git a/docs/plugins/05-renderer-components.md b/docs/plugins/05-renderer-components.md index 8e8bb20..16d9b60 100644 --- a/docs/plugins/05-renderer-components.md +++ b/docs/plugins/05-renderer-components.md @@ -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=/index.ts --alias:@aso/plugin-sdk/ui=/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)——别手写样式，宿主把标准模式做成了组件。 diff --git a/docs/plugins/07-ui-components.md b/docs/plugins/07-ui-components.md new file mode 100644 index 0000000..30ef745 --- /dev/null +++ b/docs/plugins/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 ? ( + setTick((t) => t + 1)} /> +) : items === null ? ( + +) : items.length === 0 ? ( + +) : ( + items.map((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)——超时、重试与机器关卡。 diff --git a/docs/plugins/08-performance.md b/docs/plugins/08-performance.md new file mode 100644 index 0000000..2391c86 --- /dev/null +++ b/docs/plugins/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) diff --git a/docs/plugins/DESIGN.md b/docs/plugins/DESIGN.md index bdbc905..a3c51a1 100644 --- a/docs/plugins/DESIGN.md +++ b/docs/plugins/DESIGN.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` diff --git a/docs/plugins/README.md b/docs/plugins/README.md index fc3ac85..58d857b 100644 --- a/docs/plugins/README.md +++ b/docs/plugins/README.md @@ -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 秒总览 diff --git a/docs/roadmap.md b/docs/roadmap.md index d906572..ae8bcdc 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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 子进程隔离模式 | --- diff --git a/package.json b/package.json index ad32828..97f7aca 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,7 @@ "scripts": { "typecheck": "pnpm -r --if-present typecheck", "build": "pnpm -r --if-present build", - "dev": "pnpm --dir apps/desktop dev" + "dev": "pnpm --dir apps/desktop dev", + "plugin:check": "node scripts/check-plugin.mjs" } } diff --git a/packages/plugin-template/README.md b/packages/plugin-template/README.md index a0ad951..51402bf 100644 --- a/packages/plugin-template/README.md +++ b/packages/plugin-template/README.md @@ -7,7 +7,8 @@ ``` manifest.json 清单（id/name/version/minContract 必改） main.mjs 主进程侧：Agent 能力 + 设置声明 + 日志埋点（范例齐备） -src/renderer.tsx 宿主内 React 组件源码（JSX） +src/renderer.tsx 宿主内 React 组件源码（JSX；公共组件库 + 三态示范） +renderer.mjs 预构建产物（开箱即用；改了源码需重新构建） shims/ 构建期把 react 别名到宿主单例（勿改） ``` @@ -16,11 +17,14 @@ 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 + --alias:react=./shims/react.js --alias:react/jsx-runtime=./shims/jsx-runtime.js \ + --alias:@aso/plugin-sdk=../../packages/plugin-sdk/src/index.ts \ + --alias:@aso/plugin-sdk/ui=../../packages/plugin-sdk/src/ui.tsx ``` -（esbuild 可用 `pnpm dlx esbuild@<版本>` 或任意 ≥0.17 版本；`--alias` 需 ≥0.17。） -不需要 UI 时：删除 `entry.renderer` 与 `src/`、`shims/`，只保留 main.mjs。 +（esbuild 可用 `pnpm dlx esbuild@<版本>` 或任意 ≥0.17 版本；`--alias` 需 ≥0.17。 +两条 sdk alias 指向仓库内源码——本目录复制到别处后，改成 sdk 源码的实际路径即可。） +不需要 UI 时：删除 `entry.renderer` 与 `src/`、`shims/`、`renderer.mjs`，只保留 main.mjs。 ## 放置位置（三选一，按优先级） @@ -32,13 +36,16 @@ esbuild src/renderer.tsx --bundle --format=esm --outfile=renderer.mjs \ ## 验证 -1. 重启或开关重载 → 设置 → 插件 → 对应作用域出现插件 -2. 日志 `userData/logs/main-*.log` 有 `plugin activated pluginId=my-plugin` -3. 对 Agent 说"ping 一下我的插件" → 触发 `my_plugin_ping` -4. 面板/侧栏出现 React 组件，点击 +1 正常（hooks 生效） +1. `pnpm plugin:check <本目录>` → 0 error（性能与样式机器关卡，见 L7） +2. 重启或开关重载 → 设置 → 插件 → 对应作用域出现插件 +3. 日志 `userData/logs/main-*.log` 有 `plugin activated pluginId=my-plugin` +4. 对 Agent 说"ping 一下我的插件" → 触发 `my_plugin_ping` +5. 面板/侧栏出现 React 组件：等待/数据/开关/重载齐全（三态示范，hooks 生效） ## 下一步 -- 教程索引：`docs/plugins/README.md`（L0→L5） +- 教程索引：`docs/plugins/README.md`（L0→L7） +- 公共组件库与三态铁律：`docs/plugins/07-ui-components.md`（renderer.tsx 即示范） +- 性能与检验器：`docs/plugins/08-performance.md` - 视觉规范：`docs/plugins/DESIGN.md`（提发布前过一遍自检清单） - 契约全集：`docs/plugins.md` diff --git a/packages/plugin-template/renderer.mjs b/packages/plugin-template/renderer.mjs new file mode 100644 index 0000000..25bed8e --- /dev/null +++ b/packages/plugin-template/renderer.mjs @@ -0,0 +1,177 @@ +// shims/react.js +var R = window.__ASO_PLUGIN_HOST__.react; +var { + useState, + useEffect, + useRef, + useMemo, + useCallback, + createContext, + useContext, + Fragment, + memo, + forwardRef, + createElement +} = R; + +// ../plugin-sdk/src/async.ts +var TimeoutError = class extends Error { + constructor(message) { + super(message); + this.name = "TimeoutError"; + } +}; +function withTimeout(promise, ms, label) { + let timer; + const timeout = new Promise((_, reject) => { + timer = setTimeout(() => { + reject(new TimeoutError(`${label ?? "\u64CD\u4F5C"} \u8D85\u65F6\uFF08${ms}ms\uFF09`)); + }, ms); + }); + return Promise.race([promise, timeout]).finally(() => clearTimeout(timer)); +} + +// shims/jsx-runtime.js +var { jsx, jsxs, Fragment: Fragment2 } = window.__ASO_PLUGIN_HOST__.jsxRuntime; + +// ../plugin-sdk/src/ui.tsx +function cn(...classes) { + return classes.filter(Boolean).join(" "); +} +function Spinner({ size = 14, className }) { + return /* @__PURE__ */ jsx( + "span", + { + role: "status", + "aria-label": "\u52A0\u8F7D\u4E2D", + className: cn("inline-block shrink-0 animate-spin rounded-full border-line-strong", className), + style: { width: size, height: size, borderWidth: 2, borderTopColor: "var(--accent)" } + } + ); +} +function LoadingState({ label = "\u52A0\u8F7D\u4E2D\u2026", className }) { + return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col items-center justify-center gap-2 py-10 text-center", className), children: [ + /* @__PURE__ */ jsx(Spinner, {}), + /* @__PURE__ */ jsx("div", { className: "text-[11.5px] text-ink-3", children: label }) + ] }); +} +function ErrorState({ title = "\u51FA\u9519\u4E86", description, onRetry, retryLabel = "\u91CD\u8BD5", className }) { + return /* @__PURE__ */ jsxs( + "div", + { + className: cn("flex flex-col items-center justify-center gap-1.5 rounded-card border border-line bg-red/10 px-6 py-10 text-center", className), + role: "alert", + children: [ + /* @__PURE__ */ jsx("div", { className: "text-[12.5px] font-medium text-ink", children: title }), + description !== void 0 && description !== null && description !== "" && /* @__PURE__ */ jsx("div", { className: "max-w-full whitespace-pre-wrap break-words text-[11.5px] leading-4 text-ink-3", children: description }), + onRetry && /* @__PURE__ */ jsx(Button, { variant: "ghost", size: "sm", className: "mt-2", onClick: onRetry, children: retryLabel }) + ] + } + ); +} +function EmptyState({ title, description, action, className }) { + return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col items-center justify-center gap-1 rounded-card border border-dashed border-line py-12 text-center", className), children: [ + /* @__PURE__ */ jsx("div", { className: "text-[13px] font-medium text-ink-2", children: title }), + description !== void 0 && description !== null && description !== "" && /* @__PURE__ */ jsx("div", { className: "max-w-full break-words text-[11.5px] text-ink-3", children: description }), + action && /* @__PURE__ */ jsx("div", { className: "mt-2", children: action }) + ] }); +} +function Button({ variant = "ghost", size = "md", loading = false, disabled, className, children, ...rest }) { + const variantCls = variant === "primary" ? "bg-accent text-white hover:opacity-90" : variant === "danger" ? "border border-line-strong text-red hover:bg-red/10" : "border border-line-strong text-ink hover:bg-hover"; + const sizeCls = size === "sm" ? "px-2 py-1 text-[11px]" : "px-3 py-1.5 text-[11.5px]"; + return /* @__PURE__ */ jsxs( + "button", + { + type: "button", + disabled: disabled || loading, + className: cn( + "inline-flex items-center justify-center gap-1.5 rounded-control font-medium transition-colors disabled:pointer-events-none disabled:opacity-50", + variantCls, + sizeCls, + className + ), + ...rest, + children: [ + loading && /* @__PURE__ */ jsx(Spinner, { size: size === "sm" ? 10 : 12 }), + children + ] + } + ); +} +function Switch({ checked, defaultChecked, onCheckedChange, disabled, "aria-label": ariaLabel }) { + const [inner, setInner] = useState(defaultChecked ?? false); + const isControlled = checked !== void 0; + const value = isControlled ? checked : inner; + return /* @__PURE__ */ jsx( + "button", + { + type: "button", + role: "switch", + "aria-checked": value, + "aria-label": ariaLabel, + disabled, + onClick: () => { + const next = !value; + if (!isControlled) setInner(next); + onCheckedChange?.(next); + }, + className: cn( + "relative h-5 w-9 shrink-0 rounded-full transition-colors disabled:pointer-events-none disabled:opacity-50", + value ? "bg-accent" : "bg-line-strong" + ), + children: /* @__PURE__ */ jsx( + "span", + { + className: "absolute top-0.5 size-4 rounded-full bg-white shadow transition-transform", + style: { transform: `translateX(${value ? 16 : 2}px)` } + } + ) + } + ); +} +function SettingRow({ label, description, children, className }) { + return /* @__PURE__ */ jsxs("div", { className: cn("flex items-center justify-between gap-3 rounded-card border border-line px-3 py-2.5", className), children: [ + /* @__PURE__ */ jsxs("div", { className: "min-w-0", children: [ + /* @__PURE__ */ jsx("div", { className: "text-[12.5px] text-ink", children: label }), + description !== void 0 && description !== null && description !== "" && /* @__PURE__ */ jsx("div", { className: "mt-0.5 break-words text-[11px] leading-4 text-ink-3", children: description }) + ] }), + children + ] }); +} + +// src/renderer.tsx +function fetchItems() { + return withTimeout(Promise.resolve(["\u6761\u76EE\u4E00", "\u6761\u76EE\u4E8C", "\u6761\u76EE\u4E09"]), 3e3, "\u62C9\u53D6\u6570\u636E"); +} +function mount(ctx) { + function Panel() { + const [items, setItems] = useState(null); + const [error, setError] = useState(null); + const [verbose, setVerbose] = useState(false); + const [tick, setTick] = useState(0); + useEffect(() => { + let alive = true; + setItems(null); + setError(null); + fetchItems().then((data) => { + if (alive) setItems(data); + }).catch((err) => { + if (alive) setError(err instanceof Error ? err.message : String(err)); + }); + return () => { + alive = false; + }; + }, [tick]); + return /* @__PURE__ */ jsxs("div", { className: "flex h-full flex-col gap-2 overflow-y-auto p-3", children: [ + /* @__PURE__ */ jsx("div", { className: "text-[12.5px] text-ink", children: "\u6211\u7684\u63D2\u4EF6\u9762\u677F" }), + error !== null ? /* @__PURE__ */ jsx(ErrorState, { title: "\u6570\u636E\u52A0\u8F7D\u5931\u8D25", description: error, onRetry: () => setTick((t) => t + 1) }) : items === null ? /* @__PURE__ */ jsx(LoadingState, { label: "\u6B63\u5728\u62C9\u53D6\u6570\u636E\u2026" }) : items.length === 0 ? /* @__PURE__ */ jsx(EmptyState, { title: "\u6682\u65E0\u6570\u636E", description: "\u68C0\u67E5\u6570\u636E\u6E90\u540E\u70B9\u51FB\u91CD\u65B0\u52A0\u8F7D" }) : items.map((it) => /* @__PURE__ */ jsx(SettingRow, { label: it, description: "\u793A\u4F8B\u6761\u76EE" }, it)), + /* @__PURE__ */ jsx(SettingRow, { label: "\u8BE6\u7EC6\u6A21\u5F0F", description: "\u5F00\u542F\u540E main \u4FA7\u8F93\u51FA\u66F4\u8BE6\u7EC6\u7684\u65E5\u5FD7", children: /* @__PURE__ */ jsx(Switch, { checked: verbose, onCheckedChange: setVerbose, "aria-label": "\u8BE6\u7EC6\u6A21\u5F0F" }) }), + /* @__PURE__ */ jsx(Button, { variant: "ghost", size: "sm", className: "self-start", onClick: () => setTick((t) => t + 1), children: "\u91CD\u65B0\u52A0\u8F7D" }) + ] }); + } + ctx.registerPanel(Panel); + ctx.registerView(Panel); +} +export { + mount as default +}; diff --git a/packages/plugin-template/src/renderer.tsx b/packages/plugin-template/src/renderer.tsx index e32d2d1..c90d80e 100644 --- a/packages/plugin-template/src/renderer.tsx +++ b/packages/plugin-template/src/renderer.tsx @@ -3,23 +3,65 @@ * 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 * 产物 renderer.mjs 是自包含单文件，放回插件目录即被宿主装载。 - * 样式类名只用 DESIGN.md 里的宿主词汇。 + * + * UI 一律用 @aso/plugin-sdk/ui 公共组件：token 与宿主同源、深浅色自动跟随， + * 等待/失败/空态统一呈现（规范见 docs/plugins/07-ui-components.md 与 DESIGN.md）。 + * 一切异步操作都要有超时（withTimeout/withRetry 见 '@aso/plugin-sdk'）， + * 区块三态：LoadingState → ErrorState（可重试） / EmptyState / 数据。 */ -import { useState } from 'react' +import { useEffect, useState } from 'react' +import { withTimeout } from '@aso/plugin-sdk' +import { Button, EmptyState, ErrorState, LoadingState, SettingRow, Switch } from '@aso/plugin-sdk/ui' + +/** 模拟异步数据源：换成真实 IPC / 请求时保持「必超时、必 catch」的形状 */ +function fetchItems(): Promise { + return withTimeout(Promise.resolve(['条目一', '条目二', '条目三']), 3000, '拉取数据') +} export default function mount(ctx) { function Panel() { - const [count, setCount] = useState(0) + const [items, setItems] = useState(null) // null=加载中 + const [error, setError] = useState(null) + const [verbose, setVerbose] = useState(false) + const [tick, setTick] = useState(0) + + useEffect(() => { + let alive = true + setItems(null) + setError(null) + fetchItems() + .then((data) => { + if (alive) setItems(data) + }) + .catch((err) => { + if (alive) setError(err instanceof Error ? err.message : String(err)) + }) + return () => { + alive = false + } + }, [tick]) + return ( -
+
我的插件面板
-
计数：{count}
- + + {error !== null ? ( + setTick((t) => t + 1)} /> + ) : items === null ? ( + + ) : items.length === 0 ? ( + + ) : ( + items.map((it) => ) + )} + + + + + +
) }