feat(canvas): 画布插件与视觉 - 合并 PR #289 并保留任务计费边界
This commit is contained in:
ddCat
22
docs/content/docs/plugins/plugin-surfaces.mdx
Normal file
22
docs/content/docs/plugins/plugin-surfaces.mdx
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: 插件显示形态
|
||||
description: 画布插件的非全屏、全屏和混合工作台形态
|
||||
---
|
||||
|
||||
# 插件显示形态
|
||||
|
||||
画布插件支持三种显示形态：
|
||||
|
||||
- 非全屏（`node`）：插件作为画布节点嵌入当前画布，适合素材引用、角色卡、提示词、分析结果和轻量编辑。
|
||||
- 全屏（`fullscreen`）：插件打开独立的全屏工作台，适合素材浏览、时间线、批量生成、复杂编辑和外部服务管理。退出后返回原画布和原节点上下文。
|
||||
- 混合（`node` + `fullscreen`）：同时提供紧凑节点和全屏编辑器。节点负责预览与输入输出，全屏界面负责复杂操作；Eagle 素材连接器建议采用这种形态。
|
||||
|
||||
全屏界面由宿主提供 `openSurface` / `closeSurface` 能力，插件不能自行修改宿主路由。宿主负责传入当前项目、当前节点、主题、权限和未保存状态。
|
||||
|
||||
插件清单可以声明支持的显示形态：
|
||||
|
||||
```json
|
||||
{
|
||||
"surfaces": ["node", "fullscreen"]
|
||||
}
|
||||
```
|
||||
320
docs/content/docs/plugins/plugin-system.mdx
Normal file
320
docs/content/docs/plugins/plugin-system.mdx
Normal file
@@ -0,0 +1,320 @@
|
||||
---
|
||||
title: 插件系统设计
|
||||
description: 影策网页插件系统的目标、扩展边界、插件合同与 Eagle 外部素材来源方案
|
||||
---
|
||||
|
||||
# 插件系统设计
|
||||
|
||||
> 状态：已实现首版（Eagle 外部素材来源）
|
||||
>
|
||||
> 当前版本已经包含 Eagle 专属素材管理页面、后端本地桥接、原始文件树浏览、文件读取和写入；第三方远程插件安装与完整 SDK 仍按后续阶段建设。
|
||||
|
||||
## 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 本地 API（默认 `http://127.0.0.1:41595`）检查服务并读取当前素材库。
|
||||
- 在影策素材页进入 Eagle 专属素材管理页面，按 Eagle 的父子文件树浏览和搜索文件。
|
||||
- Eagle 文件仍由 Eagle 管理，影策只通过外部素材来源读取、下载和使用，不要求逐个选择或复制成本地素材。
|
||||
- 在当前 Eagle 文件夹中新建文件夹，并把本地图片、视频和音频直接写入 Eagle。
|
||||
- 返回 Eagle 素材 ID、文件夹 ID、完整文件夹路径和来源信息，供影策项目保存外部引用。
|
||||
- 通过影策后端本地桥接读取 Eagle 文件，避免浏览器直接打开 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.upload
|
||||
external.open
|
||||
```
|
||||
|
||||
删除 Eagle 资源、批量覆盖和修改原始文件属于高风险权限，应单独申请并逐次确认，不能包含在普通 `asset.write` 中。
|
||||
|
||||
### 8.4 推荐交互
|
||||
|
||||
首版提供外部素材库浏览和双向写入：
|
||||
|
||||
```text
|
||||
Eagle 文件树 / 搜索 → 打开素材 → 在影策中使用外部引用
|
||||
影策上传图片、视频或音频 → 选择 Eagle 目标文件夹 → 写入 Eagle
|
||||
影策生成图片、视频或音频 → 插件自动归档到 Eagle 目标文件夹
|
||||
```
|
||||
|
||||
### 8.5 当前实现边界
|
||||
|
||||
- 素材页的“Eagle 素材库”进入插件专属页面，不使用抽屉，也不要求选择素材。
|
||||
- 左侧文件树直接继承 Eagle 的父子层级；影策保存外部引用时保留 Eagle 素材 ID、文件夹 ID 和路径信息。
|
||||
- 图片、视频、音频和模型可以从 Eagle 直接浏览、搜索和读取；当前不把文本类内容转换成影策文本素材。
|
||||
- 当前支持将本地图片、视频和音频写入 Eagle 当前文件夹；生成结果可以在插件设置中开启自动归档并指定 Eagle 文件夹。影策仍保留本地素材记录，外部写入成功或失败会记录到素材 metadata。实际可写入格式由本机 Eagle 版本/API 决定；如果 Eagle 拒绝某种媒体，影策保留本地结果并记录失败状态。删除、批量覆盖和冲突解决仍需后续权限设计。
|
||||
- Eagle 地址只允许本机默认端口，后端会校验本机地址和文件路径，避免把连接器变成任意内网访问代理。
|
||||
- Eagle 文件夹不会复制成影策项目中的独立资产文件夹；页面以 Eagle 原始文件树作为外部来源视图。自动归档默认使用 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；用户可以配置生成结果是否自动归档及目标文件夹。
|
||||
- Eagle Token 不进入画布节点、任务正文、日志或 URL。
|
||||
- 插件错误和权限拒绝能够显示给用户。
|
||||
64
docs/design/canvas-floating-controls.mdx
Normal file
64
docs/design/canvas-floating-controls.mdx
Normal file
@@ -0,0 +1,64 @@
|
||||
# 画布浮动控件设计沉淀：顶部操作区与底部 Dock
|
||||
|
||||
> 范围：无限画布的顶部项目操作区、底部画布工具 Dock，以及工作模式切换。
|
||||
> 目标：让画布操作控件形成统一的浮动面板系统，并在不同主题和视口下保持稳定对齐。
|
||||
> 状态：已实现首版，浏览器回归待确认。
|
||||
|
||||
## 1. 设计方向
|
||||
|
||||
画布本身是创作空间，操作控件不应占用固定内容栏，也不应把按钮散落在画布节点之间。因此控件采用独立浮动面板：
|
||||
|
||||
- 左上放置项目菜单、画布名称和重命名入口。
|
||||
- 右上放置搜索、导入、性能、积分、专注、分享和 Agent 等操作。
|
||||
- 左下保留画布视图控制和素材空间 Dock。
|
||||
- 工作模式切换放在右下，与左下 Dock 共用底部安全区，避免顶部中央出现额外的孤立控件。
|
||||
|
||||
## 2. 视觉合同
|
||||
|
||||
顶部操作区和底部 `FloatingDock`（浮动 Dock）复用 `canvasDockStyle`（画布 Dock 样式合同）：
|
||||
|
||||
- `--dock-surface`：浮动面板表面。
|
||||
- `--dock-border`：主题边界。
|
||||
- `--elevation-overlay`：面板层级阴影。
|
||||
- `--dock-command-hover`：控件悬停表面。
|
||||
- `--dock-command-active`：持续激活状态表面。
|
||||
|
||||
普通操作按钮默认透明，只有悬停或持续激活时才显示控件表面；面板本身负责边界和阴影，避免每个按钮都形成独立卡片。
|
||||
|
||||
## 3. 工作模式切换
|
||||
|
||||
`CanvasWorkspaceModeSwitch`（画布工作模式切换）是右下角独立浮动面板，不再挂在顶部栏中间：
|
||||
|
||||
- 触发器与底部 Dock 使用同一高度、圆角、边界和阴影。
|
||||
- 菜单从触发器上方展开，并与右侧边缘对齐，避免遮挡底部工具栏和画布主体。
|
||||
- 外层定位使用 `--canvas-inset-x` / `--canvas-inset-y`，与左下视图控制保持同一水平基线。
|
||||
- 简洁模式和专业模式继续使用原有 `workspaceMode` 状态，不改变节点渲染和生成逻辑。
|
||||
|
||||
## 4. 实现地图
|
||||
|
||||
- `web/src/pages/canvas/canvas-project-top-bar.tsx`：顶部左右浮动面板，以及工作模式切换组件和下拉菜单。
|
||||
- `web/src/pages/canvas/project.tsx`：将工作模式切换定位到画布右下角，并与底部控制使用同一安全区。
|
||||
- `web/src/components/canvas/canvas-zoom-controls.tsx`：底部视图控制 Dock 的既有实现，作为浮动控件视觉基准。
|
||||
- `web/src/lib/canvas/canvas-aceternity-style.ts`：提供 `canvasDockStyle` 样式合同。
|
||||
- `web/src/styles/globals.css`：维护顶部面板、控件状态和工作模式菜单的唯一样式规则。
|
||||
|
||||
## 5. 响应式与交互边界
|
||||
|
||||
- 桌面端顶部左右面板保持同一顶部安全区；底部左右面板保持同一底部安全区。
|
||||
- 窄视口沿用 `--canvas-inset-y + --space-16` 的底部避让规则，避免与移动端底部工具区域重叠。
|
||||
- 工作模式菜单打开时支持点击外部区域和 `Escape` 关闭。
|
||||
- `prefers-reduced-motion` 下关闭或缩短面板和选项的进入动画。
|
||||
- 本次只调整控件位置和视觉层级，不改变菜单命令、模式持久化和画布操作行为。
|
||||
|
||||
## 6. 验证与待回归
|
||||
|
||||
已完成：
|
||||
|
||||
- `git diff --check` 通过。
|
||||
- Impeccable 受限扫描未发现本次新增的 UI 反模式。
|
||||
|
||||
待确认：
|
||||
|
||||
- 浅色/深色主题下检查顶部左右面板、底部三个 Dock 的边界和阴影一致性。
|
||||
- 检查工作模式菜单在桌面、窄视口和底部工具栏打开时的对齐与遮挡关系。
|
||||
- 本项目按规则未自动运行 TypeScript、构建或测试；提交前只做了静态检查。
|
||||
90
docs/design/canvas-node-visual-contrast.mdx
Normal file
90
docs/design/canvas-node-visual-contrast.mdx
Normal file
@@ -0,0 +1,90 @@
|
||||
# 画布节点可读性设计沉淀：节点与图片创作面板
|
||||
|
||||
> 范围：无限画布中的节点外壳、节点内容空态、节点标题、图片创作面板和节点间连接线。
|
||||
> 目标：节点和连接在浅色、深色，以及点阵/线稿/空白画布背景上都能被快速识别和操作。
|
||||
> 状态：已实现首版，浏览器回归待确认。
|
||||
|
||||
## 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 使用相同的表面、边界和阴影，避免节点内面板与放大面板产生两套视觉语言。
|
||||
- “将使用默认模型与参数”仍是状态说明，不改变模型解析或生成默认值。
|
||||
|
||||
### 2.4 连接线可读性
|
||||
|
||||
`ConnectionPath`（节点连接线）把交互命中层和视觉展示层分开：透明路径继续保留 16px 点击区域，视觉路径不承担点击事件。
|
||||
|
||||
- 普通状态使用“柔和外层 + 清晰内芯”两层路径，提高连接在画布背景上的连续性，但不使用高亮色制造噪音。
|
||||
- 悬停或选中状态切换到 `accent.primary`（主题强调色），同时提高线宽、透明度和流动虚线强度。
|
||||
- 起点和终点使用轻量圆点标识，让用户能快速判断连接的两端。
|
||||
- 所有路径使用 `vectorEffect="non-scaling-stroke"`，保证缩放画布时线宽保持可读；动效继续服从 `prefers-reduced-motion`。
|
||||
|
||||
## 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/components/canvas/canvas-connections.tsx`：渲染连接线的命中层、普通层级、选中流动线和端点标识。
|
||||
- `web/src/styles/globals.css`：维护面板控件 hover 与尺寸调整手柄的唯一规则。
|
||||
|
||||
## 5. 验证与待回归
|
||||
|
||||
已完成：
|
||||
|
||||
- `git diff --check` 通过。
|
||||
- Impeccable 受限扫描未发现本次新增的反模式；扫描到的渐变文字、宽高过渡和既有布局规则位于其他历史区域。
|
||||
|
||||
待确认：
|
||||
|
||||
- 浏览器中分别切换浅色/深色主题，检查图片创作面板默认、悬停、选中和展开编辑状态。
|
||||
- 在点阵、线稿和空白背景下检查节点边缘、空绘图态和“将使用默认模型与参数”的对比度。
|
||||
- 在 25%、40% 和 100% 缩放下检查普通连接线、悬停/选中连接线及两个端点的可见度。
|
||||
- 本项目按规则未自动运行 TypeScript、构建或测试；提交前只做了静态 diff 检查。
|
||||
@@ -6,6 +6,10 @@
|
||||
|
||||
- [工作区外壳设计沉淀](design/workspace-shell-design.mdx)：侧栏（260px 可折叠导航 + 分组折叠）、主区卡片、顶部栏（账户/公告/主题）的设计决策与样式约束。
|
||||
|
||||
- [画布节点可读性设计沉淀](design/canvas-node-visual-contrast.mdx)：节点外壳、空态和图片创作面板在浅色/深色画布上的表面、边界、阴影与控件状态约束。
|
||||
|
||||
- [画布浮动控件设计沉淀](design/canvas-floating-controls.mdx)：顶部操作区、底部 Dock 和右下角工作模式切换的浮动面板、定位与响应式约束。
|
||||
|
||||
## 本地协作文档（不随仓库分发）
|
||||
|
||||
- [beautifului 创作设计](beautifului-creation-design.md)：本地设计参考，未纳入版本控制。
|
||||
|
||||
Reference in New Issue
Block a user