feat: 完善创作工作台与用户诊断支持 (#295)
* feat(canvas): 参考素材 - 增加移除按钮并删除对应连线 * feat(canvas): 完善节点面板交互与拖拽反馈 * fix(canvas): 画布交互与小地图 - 统一浮层层级并完善节点识别 * feat(prompt-optimizer): 增加 AI 提示词优化器及宿主接入 * feat(canvas): 画布 - 增加自动整理节点按钮并补充文档 * chore(web): 前端 - 修正提示词优化器格式 * chore(backend): 后端 - 修正 Go 格式检查 * feat(workspace): 完善诊断导出与本地排障支持 * chore(web): 格式化诊断导出文件 * fix(web-test): 兼容 Bun 测试运行时 * fix(web-test): 对齐模型目录协议断言
This commit is contained in:
QAyong
68
docs/content/docs/backend/local-development.mdx
Normal file
68
docs/content/docs/backend/local-development.mdx
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: 本地开发
|
||||
description: 在宿主机启动影策前后端开发服务
|
||||
---
|
||||
|
||||
# 本地开发
|
||||
|
||||
## 一键启动（Windows PowerShell）
|
||||
|
||||
在仓库根目录执行：
|
||||
|
||||
```powershell
|
||||
.\scripts\start-local.ps1
|
||||
```
|
||||
|
||||
脚本会：
|
||||
|
||||
- 使用 `.local/project-workbench-debug` 作为后端 SQLite 开发数据目录；
|
||||
- 创建 `.local/cache/go-build` 和 `.local/cache/go-mod` 缓存目录；
|
||||
- 首次启动时，如果 `web/node_modules` 不存在，执行 `bun install --frozen-lockfile`；
|
||||
- 打开两个 PowerShell 窗口，分别运行后端和前端；
|
||||
- 将前端 `/api` 请求代理到 `http://127.0.0.1:8080`。
|
||||
|
||||
启动后访问 <http://localhost:3000>。后端健康检查地址是 <http://127.0.0.1:8080/api/health>。
|
||||
|
||||
脚本使用固定的本地开发端口：前端 `3000`，后端 `8080`。如果端口被占用，脚本会先退出，不会关闭已有进程。请分别在两个开发窗口中按 `Ctrl+C` 停止服务。
|
||||
|
||||
如果 PowerShell 的执行策略阻止脚本运行，可以只对当前进程临时放行：
|
||||
|
||||
```powershell
|
||||
Set-ExecutionPolicy -Scope Process Bypass
|
||||
.\scripts\start-local.ps1
|
||||
```
|
||||
|
||||
## 手工启动
|
||||
|
||||
后端：
|
||||
|
||||
```bash
|
||||
mkdir -p .local/project-workbench-debug .local/cache/go-build .local/cache/go-mod
|
||||
cd backend
|
||||
CANVAS_BACKEND_ADDR=127.0.0.1:8080 \
|
||||
CANVAS_BACKEND_DATA_DIR=../.local/project-workbench-debug \
|
||||
GOCACHE=../.local/cache/go-build \
|
||||
GOMODCACHE=../.local/cache/go-mod \
|
||||
go run ./cmd/server
|
||||
```
|
||||
|
||||
前端另开终端：
|
||||
|
||||
```bash
|
||||
cd web
|
||||
bun install
|
||||
bun run dev
|
||||
```
|
||||
|
||||
前端默认监听 `0.0.0.0:3000`，Vite 将 `/api` 和 OAuth 回调代理到 `127.0.0.1:8080`。如需修改代理目标，可设置 `VITE_API_PROXY_TARGET`。
|
||||
|
||||
## Docker 开发
|
||||
|
||||
需要容器化热更新时，在仓库根目录执行：
|
||||
|
||||
```bash
|
||||
LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) \
|
||||
docker compose -f docker-compose.dev.yml up --build
|
||||
```
|
||||
|
||||
Docker 开发编排也使用 `.local/project-workbench-debug`，并默认暴露前端 `3000` 和后端 `8080`。端口冲突时，可通过 `CANVAS_WEB_HOST_PORT` 和 `CANVAS_BACKEND_HOST_PORT` 调整宿主机端口。
|
||||
93
docs/content/docs/overview/features.mdx
Normal file
93
docs/content/docs/overview/features.mdx
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: 功能清单
|
||||
description: 影策当前已实现的核心工作台能力与使用入口
|
||||
---
|
||||
|
||||
# 功能清单
|
||||
|
||||
## AI 提示词优化器
|
||||
|
||||
提示词优化器是一个内置 AI 能力插件，用于把模糊的生图或生视频想法整理成可以直接使用的提示词。它复用宿主已经配置的文本模型和渠道，不在浏览器中保存或拼接第三方密钥。
|
||||
|
||||
### 使用入口
|
||||
|
||||
- 创作页 `/create` 的提示词输入框中，点击“优化”。
|
||||
- 画布中的图片或视频节点提示词编辑器中，点击“优化”。
|
||||
|
||||
面板使用紧凑的聊天式交互，跟随当前输入框定位，支持拖动、边缘调整尺寸和窗口尺寸变化。打开与关闭不使用延迟动效，避免遮挡画布或让用户误以为请求卡住。
|
||||
|
||||
### 优化方式
|
||||
|
||||
| 方式 | 用途 |
|
||||
| --- | --- |
|
||||
| 扩展想法 | 从模糊想法补齐主体、场景、构图、光线、镜头等可执行细节。 |
|
||||
| 精修已有提示词 | 尽量保留原意，只修正表达并补充必要细节。 |
|
||||
| 强化风格 | 保留主体和动作，强化色彩、材质、光影与指定风格。 |
|
||||
| 适配模型 | 按当前生成模型和协议调整提示词结构，避免使用未确认的参数语法。 |
|
||||
| 结合参考 | 使用已连接的图片或文本补充外观、一致性、构图和关联关系。 |
|
||||
|
||||
面板底部可以单独选择优化所使用的文本模型；目标生成模型仍取当前图片或视频生成配置。两者职责不同：前者负责整理提示词，后者负责最终生成内容。
|
||||
|
||||
### 结果与安全边界
|
||||
|
||||
- 优化结果以结构化内容返回，包含正向提示词、规避项、修改说明、假设和可选备选版本。
|
||||
- 结果可以继续编辑；只有点击“采用”才会回填当前输入框，并自动关闭面板。
|
||||
- 请求支持流式反馈、取消和错误提示，不会在优化失败时覆盖原提示词。
|
||||
- 参考素材只提交当前已连接且符合类型的内容；插件不自行访问素材库或后端密钥。
|
||||
|
||||
### 相关实现
|
||||
|
||||
- `web/src/lib/plugins/builtin/prompt-optimizer.ts`：插件清单、优化方式和模型适配策略。
|
||||
- `web/src/components/canvas/canvas-prompt-optimizer-drawer.tsx`：聊天面板、拖动缩放和结果采用交互。
|
||||
- `web/src/services/plugin-host.ts`：将插件文本请求接入宿主现有模型渠道。
|
||||
- `web/src/pages/create/index.tsx`、`web/src/components/canvas/canvas-node-prompt-panel.tsx`：两个入口的接入。
|
||||
|
||||
## 用户诊断包导出
|
||||
|
||||
设置页的“问题诊断”入口和任务失败快捷入口支持导出脱敏诊断包，帮助普通用户提交问题时保留足够的排障上下文。
|
||||
|
||||
### 当前能力
|
||||
|
||||
- 浏览器内存中保留最近的全局错误、未处理 Promise、API 请求和任务创建事件。
|
||||
- 后端按当前登录用户、时间范围、任务或项目聚合 `Task`、`TaskLog` 和 `ApiCallLog`。
|
||||
- 下载前显示数据量预览，并生成包含清单、运行时信息和 JSONL 日志的 ZIP。
|
||||
- 默认排除提示词、任务输入、API Key、Cookie、上游请求/响应体和 URL 查询参数。
|
||||
|
||||
### 使用入口
|
||||
|
||||
- 设置页：`/settings?section=diagnostics`。
|
||||
- 失败任务详情中的“导出诊断包”按钮会自动带入任务和项目范围。
|
||||
|
||||
相关设计和接口边界见[用户诊断包设计](../../../design/user-diagnostic-bundle.mdx)。
|
||||
|
||||
## Eagle 外部素材库
|
||||
|
||||
内置 Eagle 插件可以从用户配置的 Eagle 服务读取素材、文件夹和标签，并将素材映射为工作台可引用的外部资源。
|
||||
|
||||
### 当前能力
|
||||
|
||||
- 支持按文件夹、关键词和素材类型查询 Eagle 素材。
|
||||
- 素材没有文件夹或标签时，仍返回稳定的空集合，工作台可以继续展示和引用素材。
|
||||
- 保留素材的文件夹路径、标签、扩展名、尺寸、大小和修改时间等排障与展示信息。
|
||||
|
||||
### 相关实现
|
||||
|
||||
- `backend/internal/service/eagle.go`：Eagle 响应解析和集合字段归一化。
|
||||
- `web/src/lib/plugins/builtin/eagle.ts`：外部素材映射、预览和引用处理。
|
||||
|
||||
## 画布节点自动整理
|
||||
|
||||
画布底部的“自动整理节点”按钮用于快速改善节点排布，适合处理节点散落、间距不一致或流程方向不清晰的画布。
|
||||
|
||||
### 使用规则
|
||||
|
||||
- 选中了两个或以上节点时，只整理选中的可移动节点；没有选中节点时，整理所有顶层可移动节点。
|
||||
- 候选节点存在连线时，按连线依赖关系进行流程布局；没有连线时，自动使用网格布局。
|
||||
- 锁定节点、容器节点和折叠批次中的隐藏子节点不会被移动。
|
||||
- 节点位置变化会进入现有画布历史记录，可使用“撤销”恢复整理前的布局，并继续由画布生命周期自动保存。
|
||||
|
||||
### 相关实现
|
||||
|
||||
- `web/src/components/canvas/canvas-zoom-controls.tsx`：底部视图控制 Dock 与“自动整理节点”入口。
|
||||
- `web/src/pages/canvas/use-canvas-node-operations.ts`：候选节点筛选、流程/网格布局选择和位置提交。
|
||||
- `web/src/lib/canvas/canvas-layout.ts`：流程、网格、行列排列和对齐算法。
|
||||
@@ -5,9 +5,9 @@ description: 影策网页插件系统的目标、扩展边界、插件合同与
|
||||
|
||||
# 插件系统设计
|
||||
|
||||
> 状态：已实现首版（Eagle 外部素材来源）
|
||||
> 状态：已实现首版（Eagle 外部素材来源 + AI 提示词优化器）
|
||||
>
|
||||
> 当前版本已经包含 Eagle 专属素材管理页面、后端本地桥接、原始文件树浏览、文件读取和写入；第三方远程插件安装与完整 SDK 仍按后续阶段建设。
|
||||
> 当前版本已经包含 Eagle 专属素材管理页面、后端本地桥接、原始文件树浏览、文件读取和写入，以及内置 `prompt-optimizer` AI 能力插件；第三方远程插件安装与完整 SDK 仍按后续阶段建设。
|
||||
|
||||
## 1. 背景与范围
|
||||
|
||||
@@ -62,6 +62,8 @@ description: 影策网页插件系统的目标、扩展边界、插件合同与
|
||||
|
||||
提供提示词处理、图片分析、批量生成、结果评分或模型能力适配。涉及真实 API Key 的请求必须经过宿主现有渠道中转合同或受控后端服务。
|
||||
|
||||
当前内置的 `prompt-optimizer` 插件用于在创作页和图片、视频节点的提示词编辑器中优化用户输入。它通过宿主的 `ai.text` 服务调用已配置的文本模型，不直接读取 API Key；结果先以可编辑内容展示，用户点击“采用”后才回填当前输入框。
|
||||
|
||||
### 4.4 素材与数据连接器
|
||||
|
||||
连接外部素材库、提示词库、知识库、云盘或项目管理工具，提供搜索、导入、上传、同步和来源追踪。
|
||||
@@ -152,6 +154,12 @@ export interface PluginSetupApi {
|
||||
|
||||
写操作必须通过结构化指令进入宿主，不能直接修改 React 状态。所有写操作都要保留失败原因和用户可见反馈。
|
||||
|
||||
### 6.1 内置 AI 文本服务
|
||||
|
||||
声明 `ai.text` 权限的插件可以使用宿主提供的文本模型服务。请求包含消息、可选的工具定义、工具选择、取消信号和流式增量回调；宿主负责选择当前配置的模型、经过现有渠道中转并返回结构化工具调用结果。插件不得自行创建平行的 HTTP 客户端或把密钥写入请求正文、日志和 URL。
|
||||
|
||||
提示词优化器使用 `optimize_prompt` 工具返回以下结构：优化后的提示词、规避项、变化说明、假设和最多两个备选版本。`model-adapt` 模式会根据目标生成模型和协议选择适配策略，但不会臆造未确认的模型参数。
|
||||
|
||||
## 7. 生命周期
|
||||
|
||||
```text
|
||||
|
||||
@@ -1,4 +1,38 @@
|
||||
# 待测试清单
|
||||
---
|
||||
title: 待测试
|
||||
description: 影策已实现功能的手工验证清单与未确认边界
|
||||
---
|
||||
|
||||
# 待测试
|
||||
|
||||
## AI 提示词优化器
|
||||
|
||||
当前代码和生产构建已完成，但以下场景仍需要在真实配置和不同窗口尺寸下由用户确认：
|
||||
|
||||
- [x] `web` 前端 TypeScript 检查与生产构建通过。
|
||||
- [x] 优化面板打开、关闭不再等待 Popover 入场或退出动效。
|
||||
- [ ] 在 `/create` 中分别测试图片和视频模式的打开、发送、取消、失败重试和关闭。
|
||||
- [ ] 在图片、视频画布节点中测试优化入口、结果采用和原提示词回填。
|
||||
- [ ] 逐项测试五种优化方式，确认模式切换不会丢失当前输入。
|
||||
- [ ] 测试优化模型切换，并确认目标生成模型与优化模型显示和请求职责分离。
|
||||
- [ ] 测试已连接图片、文本参考，以及“结合参考”没有参考内容时的提示和禁用状态。
|
||||
- [ ] 测试长提示词、长优化结果、滚动、拖动和四边缩放；确认窗口接近边缘时不会跑出视口。
|
||||
- [ ] 测试浅色/深色主题和窄窗口布局，确认按钮、输入框和结果文本仍可读且可操作。
|
||||
- [ ] 使用自定义文本渠道实际发送一次，确认渠道、模型和权限配置正确时不会误报“必须指定系统渠道和模型”。
|
||||
|
||||
用户确认上述场景后，再将对应条目移动到功能文档的已验证范围。
|
||||
|
||||
## 画布节点自动整理
|
||||
|
||||
自动整理入口和布局提交逻辑已完成，以下场景仍需要在实际画布中手工确认：
|
||||
|
||||
- [x] `web` 前端 TypeScript 检查与生产构建通过。
|
||||
- [x] 画布底部视图控制中显示“自动整理节点”按钮。
|
||||
- [ ] 无选中节点时，确认多个顶层节点会按连线流程布局；无连线时会按网格布局。
|
||||
- [ ] 选中节点时，确认只移动选中的可移动节点，未选中节点保持原位。
|
||||
- [ ] 确认锁定节点、容器节点和折叠批次隐藏子节点不会被移动。
|
||||
- [ ] 点击“撤销”确认可以恢复整理前的位置，并确认刷新画布后布局仍能保存。
|
||||
- [ ] 在浅色/深色主题、窄窗口和节点数量较多的画布中确认底部按钮可见、可操作且不遮挡主要内容。
|
||||
|
||||
## 分镜脚本资产关联
|
||||
|
||||
@@ -16,3 +50,25 @@
|
||||
4. 零价 Token 任务在上游未返回 usage 时仍能以 `0` 结算；正价 Token 任务继续依赖 usage 结算。
|
||||
5. 管理端提交任一负价格仍会被拒绝。
|
||||
6. 未勾选价格已配置的默认零价模型仍不会向普通用户公开。
|
||||
|
||||
## 用户诊断包导出
|
||||
|
||||
当前实现已完成前后端链路、脱敏和设置页 UI，但仍需要真实环境验证下载链路和不同错误场景：
|
||||
|
||||
- [x] `web` 前端 TypeScript 检查与生产构建通过。
|
||||
- [x] 诊断服务已覆盖脱敏、ZIP 结构和跨用户任务拒绝测试。
|
||||
- [x] 设置页桌面布局和 680px 窄屏布局已完成浏览器预览。
|
||||
- [ ] 登录后从设置页导出成功，确认 ZIP、诊断编号和文件名均可用。
|
||||
- [ ] 从失败任务详情进入诊断页，确认 `taskId`、`projectId` 和对应日志范围正确带入。
|
||||
- [ ] 后端未重启或接口未部署时，确认前端能显示可操作的错误提示，而不是原始 Blob/502 文案。
|
||||
- [ ] 验证浅色/深色主题、15 分钟到 24 小时范围、长问题描述和导出中的 loading 状态。
|
||||
|
||||
## Eagle 素材库
|
||||
|
||||
- [x] 增加素材无文件夹、无标签时的空集合归一化单元测试。
|
||||
- [ ] 使用真实 Eagle 服务验证无文件夹素材、无标签素材、文件夹路径和预览引用。
|
||||
|
||||
## Windows 本地开发
|
||||
|
||||
- [ ] 在一台依赖已安装和一台全新工作区分别运行 `.\scripts\start-local.ps1`。
|
||||
- [ ] 验证端口被占用时脚本会安全退出，且不会关闭已有进程或使用正式开发数据目录。
|
||||
|
||||
Reference in New Issue
Block a user