feat: 动态插件系统 M0-M3（两层能力模型 + pi 原生契约 + Obsidian 式 SDK）
This commit is contained in:
Rick Ye
@@ -67,3 +67,15 @@
|
||||
- ✅ Electron 桌面端（本仓库 `apps/desktop`）
|
||||
- ⛔ NestJS 后端、Ant Design Pro 后台、PostgreSQL —— 未设计，不创建、不实现
|
||||
- 业务插件中依赖服务器 API 的部分，先留接口占位（不依赖后端即可运行的本地能力可先行）
|
||||
|
||||
## 5. D7 动态插件系统（两层能力模型）
|
||||
|
||||
harness 收敛为「壳 + 聊天 + 插件系统」，业务功能以插件交付（详见 docs/plugins.md）：
|
||||
|
||||
- **两层能力**：内置插件（代码注册，宿主树组件 + 第一方工厂 + 全量宿主能力，浏览器面板即首个实例）/ 外置插件（`userData/plugins/`，iframe 隔离页 + 动态 import 的 main.mjs + 仅 SDK 桥接 API）。同 id 高 semver 胜、外置可遮蔽内置（组件级需 `replacesNative` 声明）→ **内置插件也能在线热更而不发安装包**。
|
||||
- **pi 原生契约**：插件工厂收到 `{ pi, ui, storage }`——`pi` 为真实 `ExtensionAPI`，工具/事件/命令/消息走 `pi.registerTool` 等原生路径（harness 挂一个聚合 extension 扇出）；`ui` 为 Electron 版槽位（对位 pi TUI 的 `ctx.ui.*`）：侧栏入口/整页视图/面板 tab/状态胶囊/深链，内联 UI 一律数据驱动。
|
||||
- **iframe 隔离的动机**：外置 UI 与宿主无 React 实例共享问题、插件崩溃不拖垮宿主、热重载 = 换 src；代价（跨桥交互、主题靠 tokens.css 连续）已接受。`plugin://`/`peer://` 特权协议 + CSP `frame-src plugin:` + 路径穿越防护 + origin/source 双重校验。
|
||||
- **SDK 即 npm 包**（`packages/plugin-sdk`，Obsidian 模式）：类型 + `definePlugin` + 页面桥 client（postMessage 白名单 invoke）+ hooks；仓库根 pnpm workspace（apps/* + packages/*）。
|
||||
- **在线更新（M5）**：索引检查 → 下载 → ed25519 验签（公钥钉 harness）→ minContract 兼容检查 → 原子替换 → 热重载；自动/手动并存。
|
||||
- **pi 原生目录（M7）**：pi resource-loader 默认已加载 `~/.pi/agent/extensions`（事实），M7 补开关与可见性管控。
|
||||
|
||||
|
||||
+115
@@ -0,0 +1,115 @@
|
||||
# 插件系统（harness 插件契约）
|
||||
|
||||
> 状态：v0.8 进行中（M0–M3 已落地；M4 更新管道 / M6 模板与外置示例 / M7 pi 原生目录管控见 roadmap）
|
||||
> 契约版本：`HARNESS_CONTRACT_VERSION = 0.1.0`（`src/main/plugins/plugin-host.ts`；manifest.minContract 与之比对，不满足拒载）
|
||||
|
||||
## 两层能力模型
|
||||
|
||||
| | 内置插件 | 外置插件 |
|
||||
|---|---|---|
|
||||
| 位置 | 代码注册（`src/main/plugins/builtin/index.ts`），UI 组件编译进宿主 bundle | `userData/plugins/<id>/`（manifest.json + 页面资产 + main.mjs） |
|
||||
| UI 形态 | 宿主树 React 组件（`renderer/src/plugins/builtin-components.ts`，key=插件 id） | iframe 页 `plugin://<id>/<entry.page>`（自带 React，物理隔离） |
|
||||
| main 侧 | 第一方工厂（不动态 import） | 动态 `import()`（cache-bust 重载） |
|
||||
| 宿主能力 | 全量（BrowserSlot/原生视图协调/window.api） | 仅 SDK 桥接 API（postMessage，白名单 invoke） |
|
||||
| 信任 | 随包分发，免签名 | 签名校验（M5 接入；当前未签名也可装载——TODO） |
|
||||
| 管理 | 同一份 manifest/生命周期/管理页（可禁用） | 同左 + zip 导入/在线更新（M4/M5） |
|
||||
|
||||
同 id 冲突：高 semver 胜、平级外置胜；**外置遮蔽"组件级"内置必须声明 `replacesNative: true`**（能力降级声明，防原生视图能力被页面级外置静默顶掉）。
|
||||
|
||||
## manifest.json
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "hotwords", // ^[a-z][a-z0-9-]*$
|
||||
"name": "热点词",
|
||||
"version": "1.2.0", // semver（x.y.z）
|
||||
"minContract": "0.1.0",
|
||||
"description": "…",
|
||||
"icon": "<svg…/>", // 侧栏/面板图标（svg 字符串；宿主清除事件属性与 script）
|
||||
"order": 10, // 侧栏排序（只在插件间；核心入口恒在前）
|
||||
"panel": true, // 在右侧 SidePanel 出现一个 tab
|
||||
"entry": { "page": "index.html", "main": "main.mjs" }, // 内置插件省略 entry
|
||||
"replacesNative": false,
|
||||
"updateURL": "https://…/index.json"
|
||||
}
|
||||
```
|
||||
|
||||
## 主进程插件契约（`@aso/plugin-sdk` 主入口）
|
||||
|
||||
```ts
|
||||
import { definePlugin } from '@aso/plugin-sdk'
|
||||
|
||||
export default definePlugin((api) => {
|
||||
// pi 原生扩展 API：工具/事件/命令/消息（语义与 pi CLI 扩展一致）
|
||||
api.pi.registerTool(myTool)
|
||||
api.pi.on('agent_end', () => { /* … */ })
|
||||
|
||||
// harness UI 槽位（数据驱动）
|
||||
api.ui.setStatusItem('task', { text: '任务 3/5', tone: 'accent', openView: { view: 'hotwords', params: { id: 1 } } })
|
||||
api.ui.registerToolbarButton({ id: 'gen', title: '生成标题', openView: { view: 'hotwords' } })
|
||||
api.ui.openView('hotwords', { tab: 2 }) // 深链打开插件页
|
||||
|
||||
// 插件私有 KV（userData/aso-plugin-storage.json，按 pluginId 隔离）
|
||||
api.storage.set('lastQuery', 'xxx')
|
||||
|
||||
return () => { /* dispose：宿主在 session_shutdown / 禁用 / 重载时调用 */ }
|
||||
})
|
||||
```
|
||||
|
||||
实现：harness 在 pi `extensionFactories` 挂**一个聚合 extension**，工厂内创建真实 `ExtensionAPI` 上下文后扇出给所有已启用插件——工具注册走 pi 原生路径（提示词注入、审批拦截、事件时序由 pi 管）。
|
||||
|
||||
## 插件页（iframe）契约（`@aso/plugin-sdk/client`）
|
||||
|
||||
```ts
|
||||
import { getHarnessClient, useHarnessTheme, useDeepLinkParams } from '@aso/plugin-sdk/client'
|
||||
|
||||
const harness = getHarnessClient('hotwords')
|
||||
harness.openView('chat') // 深链返回聊天/其他插件
|
||||
harness.setStatus('task', { text: '进行中' }) // 状态胶囊（写主进程单一事实源）
|
||||
harness.invoke('getState') // 白名单：getState / send / getSettings
|
||||
useDeepLinkParams('hotwords') // openView 携带的参数（含挂起重放）
|
||||
useHarnessTheme('hotwords') // { dark, accent }（深浅色/accent 变化推送）
|
||||
```
|
||||
|
||||
- 通信：postMessage（页 → `window.parent`；宿主 → iframe.contentWindow）
|
||||
- 安全：宿主校验 `event.source === iframe.contentWindow` **且** `event.origin === 'plugin://<id>'`；sandbox 无 `allow-top-navigation`；iframe 页**无** window.api 直达
|
||||
- 主题连续性：插件页 `<link rel="stylesheet" href="peer://assets/tokens.css">`（宿主 beautifului.css 的 token 表，深浅色由 `.dark` 类 + 下发的 accent 生效）；建议插件自带 Tailwind 按同 token 编译
|
||||
|
||||
## UI 槽位总览（对位 pi 的 ctx.ui）
|
||||
|
||||
| 槽位 | 机制 | 状态 |
|
||||
|---|---|---|
|
||||
| 侧栏入口（B1） | manifest icon/name/order；点进插件整页视图 | ✅ |
|
||||
| 插件整页 Main | 内置组件级 / 外置 iframe；聊天列 display:none 保活 | ✅ |
|
||||
| 面板 tab（B6） | `panel: true`；SidePanel 零改动承载（内置组件或 iframe） | ✅ |
|
||||
| 状态胶囊（B2） | `setStatusItem` 数据驱动，TitleBar 渲染，两种视图均可见 | ✅ |
|
||||
| 深链 | `openView(view, params)`（main 侧 IPC 广播 / 页侧桥直通） | ✅ |
|
||||
| 工具栏按钮（B5） | `registerToolbarButton` 数据已通，Composer 工具行渲染 | ⏳ 下版本 |
|
||||
| 聊天流富组件（B4） | ```类型``` 围栏块 → 宿主元组件（data-table/stat-grid/step-list/kv-card） | ⏳ 下版本 |
|
||||
| 聊天区浮动胶囊（B3） | 与 B2 同源数据，折叠/展开双态 | ⏳ 下版本 |
|
||||
|
||||
## 交互基线
|
||||
|
||||
- 整页替换：点插件入口 → 主列（聊天）隐藏保活；TitleBar 常驻（显示插件名 + 窗口控制 + 胶囊）
|
||||
- 返回聊天：点会话/新会话/Ctrl+N（全局）；Esc 只关弹窗、**不**切视图
|
||||
- Ctrl+K / Ctrl+, 仅聊天视图；切回聊天自动重新吸底（ChatView `visible`）
|
||||
- 侧栏"会话"区头徽标：插件视图期间提示代理活动（待审批 > 出错 > 流式中）
|
||||
- 重载：主进程 `plugins:reload`（重扫 manifest + 重导入 main.mjs + 清内联 UI + 重建 runtime）；渲染层收到列表变化后 iframe 换 src 整页重载（= pi `/reload` 等效）
|
||||
|
||||
## 安全清单
|
||||
|
||||
- `plugin://` 特权协议：路径解析后必须落在该插件目录内（防穿越）；`peer://` 仅暴露白名单资产（tokens.css）
|
||||
- CSP：宿主页只加 `frame-src plugin:`（iframe 方案不动 script-src）
|
||||
- 外置 main.mjs 全权运行于主进程（与 pi 扩展同信任级）——**签名校验前，仅自行放置的插件目录可装载**（M5 后强制）
|
||||
|
||||
## pi 原生目录（M7，未实现）
|
||||
|
||||
事实：pi resource-loader **默认自动加载** `~/.pi/agent/extensions/*.ts` 与 `<cwd>/.pi/extensions/*.ts`（`noExtensions` 可关）——即本应用当前已在运行用户为 pi CLI 安装的扩展（逻辑部分；其 TUI UI 调用按 pi 非 TUI 模式语义降级）。M7 计划：设置开关（默认关 → `noExtensions`）+ 管理页可见/单禁 + 参与统一重载。
|
||||
|
||||
## 开发工作流（外置插件，M6 模板落地后）
|
||||
|
||||
```
|
||||
packages/plugin-template → npm i（workspace 引 @aso/plugin-sdk）
|
||||
页面：vite build --watch → dist/ # 改即重编
|
||||
宿主：开发者模式开 fs.watch → 自动 plugins:reload → iframe 换 src
|
||||
```
|
||||
+22
-1
@@ -11,7 +11,28 @@
|
||||
| v0.3.0 | 模型与设置 | 模型选择、Provider/API key 管理（写入 ~/.pi auth）、系统提示词自定义、连通性测试 |
|
||||
| v0.4.0 | 工具与审批 | 工具调用卡片（参数/结果折叠展示）、tool_call 拦截 → Approval Card、defineTool 业务工具骨架（本地可跑的演示工具） |
|
||||
| v0.5.0 | 打磨 | 深浅主题、GSAP 动效细节、快捷键、错误态/空态、队列可视化、自动滚动策略 |
|
||||
| 未来 | | electron-builder 打包与自动更新、i18n（中/英）、sqlite 持久化与迁移、本地备份恢复、CDP 插件、热点词/生成/模板业务插件、手动模式编排 UI、RPC 子进程隔离模式 |
|
||||
| v0.8.0 | 动态插件系统（M0–M3） | 两层能力模型（内置组件级/外置 iframe）、pi 原生契约聚合 extension、@aso/plugin-sdk、plugin://peer:// 协议、视图切换+聊天保活+徽标、侧栏/面板/胶囊/深链槽位、浏览器面板插件化、插件重载 |
|
||||
| 未来 | | 插件管理与 zip 导入（M4）、ed25519 签名在线更新（M5）、外置插件模板与开发工作流（M6）、pi 原生扩展目录管控（M7）、B3/B4/B5 槽位、electron-builder 打包与自动更新、i18n（中/英）、sqlite 持久化与迁移、本地备份恢复、热点词/生成/模板业务插件、手动模式编排 UI、RPC 子进程隔离模式 |
|
||||
|
||||
---
|
||||
|
||||
## v0.8.0 — 动态插件系统（M0–M3）
|
||||
|
||||
**交付**：
|
||||
- 仓库根 pnpm workspace（apps/* + packages/*）+ `@aso/plugin-sdk`（类型 + definePlugin + 页面桥 client/hooks；源码形态被 workspace 消费，无构建步骤）
|
||||
- 主进程 `PluginHost`：内置（代码注册）+ 外置（`userData/plugins/`，manifest 校验/契约版本检查/main.mjs 动态 import）双目录合并（高 semver 胜、外置遮蔽组件级内置需 replacesNative）；聚合 InlineExtension 扇出真实 pi `ExtensionAPI`；内联 UI（状态胶囊/工具栏按钮）主进程单一事实源 + 事件广播；插件 KV 存储；`plugin://`（路径穿越防护）/`peer://`（tokens.css）特权协议；CSP 加 `frame-src plugin:`；插件启停/重载联动 runtime 重建
|
||||
- 渲染层：插件列表/内联 UI hooks；`PluginPageFrame`（iframe + 桥宿主侧：origin+source 双校验、白名单 invoke、主题下发、深链参数、热重载换 src）；`PluginErrorBoundary`；`PluginStatusCapsules`（TitleBar 槽，两视图可见）；App 视图切换（activeView{view,params}、聊天列 display:none 保活、Ctrl+N 全局/Ctrl+K,Ctrl+, 仅聊天、插件禁用自动回落）；SidebarNav 插件入口 + 会话区头代理活动徽标（待审批>出错>流式）；SidePanel 零改动承载插件 tab
|
||||
- 浏览器面板 → 内置插件：browserTools 迁 `pi.registerTool`（customTools 摘除）、面板 tab 按启用态门控、状态胶囊示范（"浏览器 N 页"）
|
||||
- 验证：typecheck/build 通过（含 SDK 打包、tokens.css 构建期拷贝）；dev 启动截图核验（聊天布局无回归、浏览器面板正常、无报错）
|
||||
- 关键事实澄清：pi resource-loader **默认自动加载** `~/.pi/agent/extensions`——M7（原生目录管控）从"建设加载"降为"开关+可见性"
|
||||
|
||||
**自省**（v0.8.0 → 指导 M4+）：
|
||||
1. **外置插件尚未强制签名**——当前 `userData/plugins/` 直接装载（代码里已留 TODO）；M5 验签落地前不对外分发任何外置插件。
|
||||
2. **B3/B4/B5 槽位数据已通、渲染未接**——状态胶囊已在 TitleBar 生效；Composer 工具行按钮、聊天流围栏块元组件（data-table 等）、聊天区浮动胶囊排 M4 同批或下版本。
|
||||
3. **切换回聊天未自动聚焦输入框**——保活后焦点丢失，需 Composer 暴露 focus 入口（data 属性 + App effect）。
|
||||
4. **插件管理 UI 仍占位**——SettingsModal"插件"tab 转正（列表/启停/重载/导入）排 M4。
|
||||
5. **TS7（typescript 7 native）增量缓存坑**——改 `declare global` 后 typecheck 可能读到旧程序，删 `out/tsconfig.{node,web}/` 下 tsbuildinfo 即恢复。
|
||||
6. **workspace 迁移副作用**——根 workspace 化后 electron postinstall 偶发不跑（"Electron uninstall"），手动 `node node_modules/.pnpm/electron@*/node_modules/electron/install.js` 修复；新克隆/重装后注意。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user