feat(workbench): 插件素材与画布视觉 - 完成 Eagle 外部来源与节点可读性适配

docs/content/docs/plugins/plugin-system.mdx

@@ -1,13 +1,13 @@
 ---
 title: 插件系统设计
-description: 影策网页插件系统的目标、扩展边界、插件合同与 Eagle 素材连接器方案
+description: 影策网页插件系统的目标、扩展边界、插件合同与 Eagle 外部素材来源方案
 ---
 
 # 插件系统设计
 
-> 状态：设计草案
+> 状态：已实现首版（Eagle 外部素材来源）
 >
-> 本文定义后续网页插件系统的目标和接口边界，不代表当前版本已经实现全部能力。
+> 当前版本已经包含 Eagle 专属素材管理页面、后端本地桥接、原始文件树浏览、文件读取和写入；第三方远程插件安装与完整 SDK 仍按后续阶段建设。
 
 ## 1. 背景与范围
 
@@ -171,20 +171,18 @@ export interface PluginSetupApi {
 5. 卸载阶段清理插件存储、事件订阅、注册命令和可选的插件节点数据。
 6. 更新失败时保留旧版本，不能留下半启用状态。
 
-## 8. Eagle 素材连接器方案
+## 8. Eagle 外部素材来源方案
 
 Eagle 插件的主分类是“素材与数据连接器”，可以附带一个 `EagleAsset` 画布节点。
 
 ### 8.1 连接器职责
 
-- 配置 Eagle 本地地址、端口和访问 Token。
-- 检查 Eagle 服务是否可用。
-- 浏览库、文件夹和标签。
-- 按关键词、标签和文件类型搜索素材。
-- 将素材以 `resource:<id>` 或宿主资源合同导入画布。
-- 将画布中的生成图片、视频或音频上传回 Eagle。
-- 保存 Eagle 资产 ID、库 ID、文件夹 ID 和来源信息。
-- 提供“在 Eagle 中打开”和“重新同步”动作。
+- 使用 Eagle 本地 API（默认 `http://127.0.0.1:41595`）检查服务并读取当前素材库。
+- 在影策素材页进入 Eagle 专属素材管理页面，按 Eagle 的父子文件树浏览和搜索文件。
+- Eagle 文件仍由 Eagle 管理，影策只通过外部素材来源读取、下载和使用，不要求逐个选择或复制成本地素材。
+- 在当前 Eagle 文件夹中新建文件夹，并把本地图片、视频和音频直接写入 Eagle。
+- 返回 Eagle 素材 ID、文件夹 ID、完整文件夹路径和来源信息，供影策项目保存外部引用。
+- 通过影策后端本地桥接读取 Eagle 文件，避免浏览器直接打开 Eagle 的本机文件路径。
 
 ### 8.2 画布节点
 
@@ -218,27 +216,30 @@ type EagleAssetMetadata = {
 ```text
 asset.read
 asset.search
-asset.import
 asset.upload
-canvas.read
-canvas.write
+external.open
 ```
 
 删除 Eagle 资源、批量覆盖和修改原始文件属于高风险权限，应单独申请并逐次确认，不能包含在普通 `asset.write` 中。
 
 ### 8.4 推荐交互
 
-第一阶段只做单向流程：
+首版提供外部素材库浏览和双向写入：
 
 ```text
-Eagle 搜索 → 选择素材 → 导入画布 → 参与创作
+Eagle 文件树 / 搜索 → 打开素材 → 在影策中使用外部引用
+影策上传图片、视频或音频 → 选择 Eagle 目标文件夹 → 写入 Eagle
+影策生成图片、视频或音频 → 插件自动归档到 Eagle 目标文件夹
 ```
 
-第二阶段再做回写：
+### 8.5 当前实现边界
 
-```text
-画布生成结果 → 用户确认 → 上传 Eagle → 自动归档和打标签
-```
+- 素材页的“Eagle 素材库”进入插件专属页面，不使用抽屉，也不要求选择素材。
+- 左侧文件树直接继承 Eagle 的父子层级；影策保存外部引用时保留 Eagle 素材 ID、文件夹 ID 和路径信息。
+- 图片、视频、音频和模型可以从 Eagle 直接浏览、搜索和读取；当前不把文本类内容转换成影策文本素材。
+- 当前支持将本地图片、视频和音频写入 Eagle 当前文件夹；生成结果可以在插件设置中开启自动归档并指定 Eagle 文件夹。影策仍保留本地素材记录，外部写入成功或失败会记录到素材 metadata。实际可写入格式由本机 Eagle 版本/API 决定；如果 Eagle 拒绝某种媒体，影策保留本地结果并记录失败状态。删除、批量覆盖和冲突解决仍需后续权限设计。
+- Eagle 地址只允许本机默认端口，后端会校验本机地址和文件路径，避免把连接器变成任意内网访问代理。
+- Eagle 文件夹不会复制成影策项目中的独立资产文件夹；页面以 Eagle 原始文件树作为外部来源视图。自动归档默认使用 Eagle 根目录，用户可以在插件设置中关闭或改用具体文件夹。
 
 ## 9. 安全边界
 
@@ -289,7 +290,7 @@ plugins/
 - 本地插件发现。
 - 安装、启用、停用、更新和卸载。
 - 节点注册、工具栏命令、事件和插件存储。
-- Eagle 只读搜索和素材导入。
+- Eagle 外部素材来源页面、媒体写入和生成结果自动归档。
 
 ### Phase 2：连接器和工作流
 
@@ -314,7 +315,7 @@ plugins/
 - 用户能看到插件名称、版本、来源和权限。
 - 插件停用后不再响应事件，也不残留工具栏命令。
 - 插件更新失败时旧版本仍可用。
-- Eagle 插件可以搜索素材并把选中素材导入画布。
+- Eagle 插件可以浏览原始文件树、搜索和读取素材，并将图片、视频和音频写入 Eagle；用户可以配置生成结果是否自动归档及目标文件夹。
 - Eagle Token 不进入画布节点、任务正文、日志或 URL。
 - 插件错误和权限拒绝能够显示给用户。