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

2026-08-22 02:30:26 +08:00
parent b54e001425
commit ec5aa5ef82
35 changed files with 2512 additions and 214 deletions
--- a/docs/content/docs/plugins/plugin-system.mdx
+++ b/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。
 - 插件错误和权限拒绝能够显示给用户。

--- a/docs/design/canvas-node-visual-contrast.mdx
+++ b/docs/design/canvas-node-visual-contrast.mdx
@@ -0,0 +1,76 @@
+# 画布节点可读性设计沉淀：节点与图片创作面板
+
+> 范围：无限画布中的节点外壳、节点内容空态、节点标题和图片创作面板。
+> 目标：节点在浅色、深色，以及点阵/线稿/空白画布背景上都能被快速识别和操作。
+> 状态：已实现首版，浏览器回归待确认。
+
+## 1. 问题定义
+
+画布节点可能直接落在白色或黑色背景上。只依赖全局卡片表面会造成两个问题：
+
+- 节点边界消失，空态内容看起来像画布的一部分。
+- 图片创作面板的“将使用默认模型与参数”提示、输入区和操作控件缺少稳定的表面层级。
+
+这不是生成逻辑或参考图尺寸逻辑的问题，因此本次只调整视觉契约，不改变节点数据、生成参数、定位和交互流程。
+
+## 2. 设计决策
+
+### 2.1 节点使用画布主题 token
+
+`canvasThemes`（画布主题 token）中的 `node` 语义负责节点自身的可读性：
+
+- `fill`：节点主体表面。
+- `panel`：节点内部面板和空态子表面。
+- `edge`：节点与画布之间的低对比边界。
+- `shadow` / `hoverShadow`：静止与悬停时的空间层级。
+- `text` / `muted` / `faint`：正文、辅助说明和占位内容。
+
+浅色和深色主题必须成对提供这些 token。节点不能回退到全局 `--card-surface`，因为它不知道当前画布背景和节点层级。
+
+### 2.2 节点外壳与空态
+
+`CanvasNode`（画布节点外壳）使用 `node.fill`、`node.edge` 和主题阴影。选中状态继续使用现有 active stroke，边界只用于提供识别度，不作为装饰性竖线或强调色。
+
+`CanvasNodeContent`（节点内容渲染）的绘图空态在节点内部增加一个轻量子表面和图标边界，使“打开绘图”在白色和黑色背景下都能被识别；真实媒体内容不增加额外遮罩，不改变原始比例。
+
+### 2.3 图片创作面板同步适配
+
+`CanvasNodePromptPanel`（图片/视频/文本/音频创作面板）把面板变量绑定到同一组画布主题：
+
+- 面板表面使用 `node.panel`，边界使用 `node.edge`，阴影使用 `node.shadow`。
+- 模型选择器、参考素材、放大编辑和参数折叠按钮使用 `toolbar.itemHover` 与 `toolbar.activeBg`，不再依赖只适合深色背景的白色 hover。
+- 展开编辑 Modal 使用相同的表面、边界和阴影，避免节点内面板与放大面板产生两套视觉语言。
+- “将使用默认模型与参数”仍是状态说明，不改变模型解析或生成默认值。
+
+## 3. 状态与边界
+
+| 状态 | 处理 | 目的 |
+| --- | --- | --- |
+| 默认 | `node.panel` + `node.edge` + `node.shadow` | 与点阵、线稿或空白背景分离 |
+| 悬停 | `hoverShadow`，控件使用 `activeBg` | 提示可操作性，不改变布局 |
+| 选中 | 沿用 active stroke | 与节点选中态保持一致 |
+| 禁用/无内容 | 沿用 `faint` 和既有空态文案 | 不伪造生成成功或配置状态 |
+| 展开编辑 | Modal 复用同一套主题 token | 保持放大编辑与节点内编辑一致 |
+
+本次不调整画布背景色、节点尺寸、面板定位、参考图尺寸选项、生成参数和资源同步逻辑。
+
+## 4. 实现地图
+
+- `web/src/lib/canvas-theme.ts`：维护浅色/深色节点边界和阴影 token。
+- `web/src/components/canvas/canvas-node.tsx`：应用节点外壳和节点标题的主题表面。
+- `web/src/components/canvas/canvas-node-content.tsx`：应用绘图空态子表面。
+- `web/src/components/canvas/canvas-node-prompt-panel.tsx`：注入图片创作面板和放大编辑面板的主题变量。
+- `web/src/styles/globals.css`：维护面板控件 hover 与尺寸调整手柄的唯一规则。
+
+## 5. 验证与待回归
+
+已完成：
+
+- `git diff --check` 通过。
+- Impeccable 受限扫描未发现本次新增的反模式；扫描到的渐变文字、宽高过渡和既有布局规则位于其他历史区域。
+
+待确认：
+
+- 浏览器中分别切换浅色/深色主题，检查图片创作面板默认、悬停、选中和展开编辑状态。
+- 在点阵、线稿和空白背景下检查节点边缘、空绘图态和“将使用默认模型与参数”的对比度。
+- 本项目按规则未自动运行 TypeScript、构建或测试；提交前只做了静态 diff 检查。
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,6 +6,8 @@

 - [工作区外壳设计沉淀](design/workspace-shell-design.mdx)：侧栏（260px 可折叠导航 + 分组折叠）、主区卡片、顶部栏（账户/公告/主题）的设计决策与样式约束。

+- [画布节点可读性设计沉淀](design/canvas-node-visual-contrast.mdx)：节点外壳、空态和图片创作面板在浅色/深色画布上的表面、边界、阴影与控件状态约束。
+
 ## 本地协作文档（不随仓库分发）

 - [beautifului 创作设计](beautifului-creation-design.md)：本地设计参考，未纳入版本控制。