docs(plugin): 插件系统 - 设计扩展合同与显示形态

2026-08-21 16:29:05 +08:00
parent 16359271f6
commit 2d8d72d1c4
2 changed files with 342 additions and 0 deletions
--- a/docs/content/docs/plugins/plugin-surfaces.mdx
+++ b/docs/content/docs/plugins/plugin-surfaces.mdx
@@ -0,0 +1,22 @@
+---
+title: 插件显示形态
+description: 画布插件的非全屏、全屏和混合工作台形态
+---
+
+# 插件显示形态
+
+画布插件支持三种显示形态：
+
+- 非全屏（`node`）：插件作为画布节点嵌入当前画布，适合素材引用、角色卡、提示词、分析结果和轻量编辑。
+- 全屏（`fullscreen`）：插件打开独立的全屏工作台，适合素材浏览、时间线、批量生成、复杂编辑和外部服务管理。退出后返回原画布和原节点上下文。
+- 混合（`node` + `fullscreen`）：同时提供紧凑节点和全屏编辑器。节点负责预览与输入输出，全屏界面负责复杂操作；Eagle 素材连接器建议采用这种形态。
+
+全屏界面由宿主提供 `openSurface` / `closeSurface` 能力，插件不能自行修改宿主路由。宿主负责传入当前项目、当前节点、主题、权限和未保存状态。
+
+插件清单可以声明支持的显示形态：
+
+```json
+{
+  "surfaces": ["node", "fullscreen"]
+}
+```
--- a/docs/content/docs/plugins/plugin-system.mdx
+++ b/docs/content/docs/plugins/plugin-system.mdx
@@ -0,0 +1,320 @@
+---
+title: 插件系统设计
+description: 影策网页插件系统的目标、扩展边界、插件合同与 Eagle 素材连接器方案
+---
+
+# 插件系统设计
+
+> 状态：设计草案
+>
+> 本文定义后续网页插件系统的目标和接口边界，不代表当前版本已经实现全部能力。
+
+## 1. 背景与范围
+
+当前项目已经包含一个面向 Codex App 的 `plugins/infinite-canvas` 插件。该插件负责注册 MCP、连接本地 Canvas Agent，并让 Codex 读取或操作画布。
+
+本文讨论的是另一套能力：让网页应用能够安装、启用和管理由其他开发者提供的扩展。两者保持边界清晰：
+
+- Codex 插件：面向 Codex / MCP / Canvas Agent。
+- 网页插件：面向影策画布、素材、工作流和外部服务集成。
+
+网页插件的第一目标不是开放所有页面代码，而是提供稳定、可审计、可逐步扩展的宿主 API，让第三方开发者能够在不修改主应用源码的情况下接入能力。
+
+## 2. 设计目标
+
+- 第三方开发者可以独立开发、构建和发布插件。
+- 用户可以查看插件信息、安装、启用、停用、更新和卸载插件。
+- 插件不直接依赖页面内部 React 组件和 Zustand store。
+- 宿主可以通过 `apiVersion` 和权限声明控制兼容性与风险。
+- 插件的错误、超时、权限拒绝和版本不兼容必须可见，不能静默降级。
+- 插件产生的本地数据必须按插件 ID 隔离，并在卸载时可清理。
+- 未来可以加入官方注册表，也可以使用组织内部或本地插件源。
+
+## 3. 非目标
+
+第一阶段不开放以下能力：
+
+- 任意修改宿主路由、全局布局和认证流程。
+- 任意访问用户 Cookie、API Key、数据库或后端数据目录。
+- 插件自行注册 Gin 路由、GORM model 或后台 Worker。
+- 插件在没有用户确认的情况下上传、删除或覆盖资源。
+- 用插件机制替代现有 AI 渠道、资源存储和权限服务合同。
+
+需要服务端能力的插件，应通过明确的后端集成接口或独立服务完成，而不是让远程 JavaScript 直接访问敏感数据。
+
+## 4. 插件分类
+
+插件分类用于权限、市场筛选和能力发现，不直接决定代码目录结构。
+
+### 4.1 画布节点插件
+
+新增自定义节点类型、节点内容渲染、节点详情面板、节点工具栏和节点输入输出资源。
+
+适合：角色卡、场景卡、分镜卡、Markdown、SVG、HTML、提示词、素材引用和分析结果节点。
+
+### 4.2 工作流插件
+
+在用户确认后创建节点、连接节点、批量处理、触发生成、执行重试或进行结果整理。
+
+适合：`剧本 → 角色 → 场景 → 分镜 → 提示词 → 生图` 等可复用流程。
+
+### 4.3 AI 能力插件
+
+提供提示词处理、图片分析、批量生成、结果评分或模型能力适配。涉及真实 API Key 的请求必须经过宿主现有渠道中转合同或受控后端服务。
+
+### 4.4 素材与数据连接器
+
+连接外部素材库、提示词库、知识库、云盘或项目管理工具，提供搜索、导入、上传、同步和来源追踪。
+
+Eagle 插件属于此类，具体方案见第 8 节。
+
+### 4.5 导入导出插件
+
+扩展剧本、分镜、提示词、素材包、JSON、Markdown、PDF 等格式的导入或导出。
+
+### 4.6 Agent / MCP 插件
+
+为 Codex、Claude 或其他 Agent 暴露画布工具。这一类与网页插件可以协同，但仍使用独立的 Agent / MCP 安全边界。
+
+## 5. 插件包与清单
+
+插件以一个远程或本地可解析的清单作为入口。清单负责描述插件，不负责承载业务逻辑。
+
+建议的最小清单：
+
+```json
+{
+  "id": "eagle-asset-connector",
+  "name": "Eagle 素材库",
+  "version": "0.1.0",
+  "apiVersion": "1",
+  "entry": "https://example.com/plugins/eagle-asset-connector.js",
+  "category": "asset-connector",
+  "permissions": [
+    "canvas.read",
+    "canvas.write",
+    "asset.read",
+    "asset.import",
+    "asset.upload"
+  ],
+  "dependencies": {},
+  "integrity": "sha256-..."
+}
+```
+
+字段约束：
+
+- `id`：全局唯一，使用小写 kebab-case；安装后不能随意变更。
+- `version`：遵循 SemVer，用于更新和回滚判断。
+- `apiVersion`：表示插件依赖的宿主 API 版本，不等同于插件版本。
+- `entry`：插件入口地址；正式环境应支持 HTTPS。
+- `permissions`：最小权限集合，宿主在安装和首次使用时展示。
+- `dependencies`：插件依赖的其他插件或宿主能力。
+- `integrity`：用于校验远程产物是否被替换。
+
+## 6. 宿主 API 边界
+
+插件不得直接导入页面组件、store 或内部 API 文件。宿主通过版本化 SDK 提供能力。
+
+建议第一版 SDK 包含以下能力：
+
+```ts
+export interface CanvasPlugin {
+  id: string;
+  version: string;
+  apiVersion: string;
+  setup(api: PluginSetupApi): void | (() => void);
+  nodes?: CanvasNodeDefinition[];
+}
+
+export interface PluginSetupApi {
+  canvas: CanvasApi;
+  commands: CommandRegistry;
+  events: PluginEventBus;
+  storage: PluginStorage;
+  assets: AssetApi;
+  permissions: PermissionApi;
+}
+```
+
+第一阶段的能力合同：
+
+| 能力 | 说明 |
+| --- | --- |
+| 节点注册 | 注册节点类型、标题、图标、默认尺寸和渲染组件 |
+| 节点面板 | 编辑节点 metadata，展示插件自己的控制项 |
+| 工具栏命令 | 在节点工具栏、画布工具栏或上下文菜单增加动作 |
+| 画布读写 | 读取节点和连线；在用户确认后应用结构化操作 |
+| 资源读写 | 通过资源服务获取、导入和上传媒体，不在插件中拼接资源 URL |
+| 事件订阅 | 监听节点、项目、生成任务和插件生命周期事件 |
+| 插件存储 | 使用带插件命名空间的轻量配置和索引数据 |
+| 清理函数 | 停用或卸载时移除事件、样式、命令和临时资源 |
+
+写操作必须通过结构化指令进入宿主，不能直接修改 React 状态。所有写操作都要保留失败原因和用户可见反馈。
+
+## 7. 生命周期
+
+```text
+发现 → 查看清单 → 安装 → 校验兼容性和权限 → 启用 → 使用
+                         ↓                       ↓
+                 拒绝 / 失败                  停用 → 卸载
+                         ↑                       ↓
+                  更新 / 回滚 ← 版本检查 ← 清理
+```
+
+生命周期要求：
+
+1. 发现阶段只读取清单，不执行插件代码。
+2. 安装阶段下载入口和依赖，校验 HTTPS、版本、完整性和权限。
+3. 启用阶段先申请权限，再执行 `setup`。
+4. 停用阶段禁止新请求进入，等待可取消任务结束后调用清理函数。
+5. 卸载阶段清理插件存储、事件订阅、注册命令和可选的插件节点数据。
+6. 更新失败时保留旧版本，不能留下半启用状态。
+
+## 8. Eagle 素材连接器方案
+
+Eagle 插件的主分类是“素材与数据连接器”，可以附带一个 `EagleAsset` 画布节点。
+
+### 8.1 连接器职责
+
+- 配置 Eagle 本地地址、端口和访问 Token。
+- 检查 Eagle 服务是否可用。
+- 浏览库、文件夹和标签。
+- 按关键词、标签和文件类型搜索素材。
+- 将素材以 `resource:<id>` 或宿主资源合同导入画布。
+- 将画布中的生成图片、视频或音频上传回 Eagle。
+- 保存 Eagle 资产 ID、库 ID、文件夹 ID 和来源信息。
+- 提供“在 Eagle 中打开”和“重新同步”动作。
+
+### 8.2 画布节点
+
+`EagleAsset` 节点只保存可迁移的引用信息和展示 metadata，不把 Eagle 的完整文件内容塞进画布 JSON：
+
+```ts
+type EagleAssetMetadata = {
+  assetId: string;
+  libraryId?: string;
+  folderId?: string;
+  title: string;
+  tags: string[];
+  sourceUrl?: string;
+  syncedAt?: string;
+};
+```
+
+节点可以提供：
+
+- 预览缩略图。
+- 标签、尺寸和来源展示。
+- 导入本地资源副本。
+- 在 Eagle 中打开。
+- 更新节点中的 Eagle metadata。
+- 将当前生成结果上传到 Eagle。
+
+### 8.3 Eagle 权限
+
+第一版建议只申请：
+
+```text
+asset.read
+asset.search
+asset.import
+asset.upload
+canvas.read
+canvas.write
+```
+
+删除 Eagle 资源、批量覆盖和修改原始文件属于高风险权限，应单独申请并逐次确认，不能包含在普通 `asset.write` 中。
+
+### 8.4 推荐交互
+
+第一阶段只做单向流程：
+
+```text
+Eagle 搜索 → 选择素材 → 导入画布 → 参与创作
+```
+
+第二阶段再做回写：
+
+```text
+画布生成结果 → 用户确认 → 上传 Eagle → 自动归档和打标签
+```
+
+## 9. 安全边界
+
+当前远程 JavaScript 插件如果直接在页面上下文执行，可能接触页面可见数据和本地配置。因此正式开放第三方插件前必须完成以下事项：
+
+- 插件默认无权限，按能力逐项授权。
+- API Key、登录 Cookie 和后端会话不得通过通用插件 API 暴露。
+- 外部请求优先经过宿主服务或明确的连接器 API。
+- 远程产物支持完整性校验、版本锁定和撤销。
+- 插件错误不能吞掉，必须记录插件 ID、版本和可读错误。
+- 公开市场只允许可信来源；组织内部插件可使用私有注册表。
+- 高风险写入、上传、删除和外部同步必须有用户确认。
+
+长期方向是将不可信插件放入 iframe、Worker 或 Capability 沙箱，避免插件默认拥有宿主页面权限。
+
+## 10. 开发者接入流程
+
+后续应提供一个独立 SDK 和模板，使开发者可以：
+
+1. 创建插件模板。
+2. 安装 SDK 和类型定义。
+3. 在本地启动 watch 构建。
+4. 使用宿主提供的模拟画布和测试数据验证插件。
+5. 生成插件清单和构建产物。
+6. 发布到静态地址或组织注册表。
+7. 在影策的插件管理器中通过 URL 安装。
+
+推荐目录：
+
+```text
+plugins/
+  eagle-asset-connector/
+    plugin.json
+    package.json
+    src/
+      index.ts
+      eagle-client.ts
+      eagle-node.tsx
+    README.md
+    dist/
+```
+
+## 11. 实施顺序
+
+### Phase 1：稳定插件核心
+
+- 插件清单和 `apiVersion`。
+- 本地插件发现。
+- 安装、启用、停用、更新和卸载。
+- 节点注册、工具栏命令、事件和插件存储。
+- Eagle 只读搜索和素材导入。
+
+### Phase 2：连接器和工作流
+
+- 资源连接器合同。
+- 上传回写和标签同步。
+- 批量处理和工作流触发器。
+- 插件配置页面和错误诊断。
+- 插件 SDK、模板和本地测试工具。
+
+### Phase 3：生态安全
+
+- 官方和私有注册表。
+- 完整性校验、签名和版本回滚。
+- 权限审核和风险分级。
+- 不可信插件沙箱。
+- 插件兼容性测试和自动化发布。
+
+## 12. 第一版验收标准
+
+- 第三方开发者可以只依赖 SDK 新增一个画布节点。
+- 插件可以通过 URL 安装，不需要修改宿主业务代码。
+- 用户能看到插件名称、版本、来源和权限。
+- 插件停用后不再响应事件，也不残留工具栏命令。
+- 插件更新失败时旧版本仍可用。
+- Eagle 插件可以搜索素材并把选中素材导入画布。
+- Eagle Token 不进入画布节点、任务正文、日志或 URL。
+- 插件错误和权限拒绝能够显示给用户。
+