# vi-studio

**Repository Path**: yushui_wang/vi-studio

## Basic Information

- **Project Name**: vi-studio
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vi-Studio

**仅用自然语言，在一个单文件 HTML 里构建的可视化 AI 工作流工作室。**

Vi-Studio 是一个运行在浏览器中的节点式 AI 工作流工具——无限画布、拖拽连线，把多模态模型（文本 / 图像 / 视频）的能力聚合在同一张画布上。

它同时是一个 **AI-Native 实验**：探索「AI 结对编程」的极限——从架构设计、状态管理到 UI 交互，主要由自然语言驱动完成，人负责判断与验收。

---

## 快速开始

```bash
npm install
npm run dev        # 开发：模块化工程 + HMR
npm run build      # 交付：产出 dist/Vi-Studio.html（单文件）
npm run typecheck  # 类型检查

./publish-gitee.sh check   # 发布前自检
```

`dist/Vi-Studio.html` 是一个**自包含**的 HTML：双击用浏览器打开即可，不需要 Node、不需要服务器、不需要联网加载任何 CDN 资源（约 667 KB）。

## 为什么源码不是单文件

同类单文件工具的做法是把两万多行 JSX 塞进一个 `<script type="text/babel">`，让 Babel 在浏览器里实时转译。代价是：

- 每次打开都要现场编译全部代码 —— 秒级白屏
- 没有 HMR、没有类型检查、没有 tree-shaking
- 全部逻辑在一个闭包里，加一种节点都要改到核心代码

Vi-Studio 把这两件事解耦：**源码是模块化工程（开发体验），产物是单文件（交付形态）**。两边的好处都拿到。

## 技术栈

| 层 | 选择 | 说明 |
|---|---|---|
| 构建 | Vite 8 + TypeScript | 构建期编译，无运行时转译 |
| UI | React 19 | |
| 画布 | **React Flow 12**（`@xyflow/react`） | 缩放 / 平移 / 连线 / Minimap 开箱即用 |
| 状态 | **Zustand**（6 个领域 store） | 画布 / 设置 / 界面 / 抽帧 / 对话 / 素材库，不做 Context 嵌套 |
| 样式 | Tailwind CSS 4（`@tailwindcss/vite`） | 真构建，不是 Play CDN |
| 抽帧 | **WebCodecs `VideoFrame`** + `requestVideoFrameCallback` | 无额外依赖，不引入 wasm 解复用器 |
| 持久化 | **IndexedDB**（手写，无依赖） | 能直接存 Blob，避开 localStorage 的 5 MB 配额 |
| 单文件 | `vite-plugin-singlefile` | 把 JS / CSS 全部内联进 HTML |

## 节点清单（22 种 / 5 大类）

| 分类 | 节点 |
|---|---|
| **输入**（4） | 文本、小说输入、图片输入、视频输入 |
| **生成**（4） | 大模型、图像生成、视频生成、智能分镜表 |
| **分析**（4） | 视频拆解、抽取角色场景、角色描述、场景描述 |
| **工具**（4） | 图像对比、预览窗口、保存到本地、子工作流 |
| **角色场景**（6） | 创建角色、创建场景、角色定妆图、角色动态、场景概念图、场景动态 |

## 目录结构

```
src/
├── types/graph.ts            节点 / 边 / 数据的类型定义
├── registry/
│   ├── appearance.ts         节点的视觉标识（配色），单独放以避免循环依赖
│   └── nodeRegistry.ts       ★ 节点注册表 —— 全项目唯一的「节点清单」（22 条）
├── nodes/                    节点组件（BaseNode 外壳 + 22 种节点 + 错误边界）
├── store/                    6 个 store：graph / settings / ui / analysis / chat / library
├── providers/                ★ 厂商适配器注册表（对话 / 图像 / 视频 / 轮询）
├── lib/
│   ├── tasks.ts              任务登记表（AbortController，支撑「取消」）
│   ├── poll.ts               异步任务轮询（递增间隔、可中断）
│   ├── videoFrames.ts        ★ WebCodecs 抽帧 + 自适应镜头切分
│   ├── persist.ts            IndexedDB 存档（画布 / 素材库 / 对话 / 关键帧）
│   ├── createNode.ts         建节点（刻意独立，让 store 不依赖注册表）
│   ├── layout.ts             DAG 自动布局
│   ├── nodeClipboard.ts      应用内节点剪贴板（区别于系统剪贴板）
│   ├── run*.ts               各节点的运行编排（Prompt / Image / Video / Analysis / …）
│   └── reversePrompt.ts      逐镜头反推提示词
├── components/               工具栏、节点面板、画布、三个侧栏、预览弹窗
└── App.tsx
tools/
├── dev-cors-proxy.mjs        本地 CORS 中转（开发用）
└── local-cache-server.mjs    本地落盘服务（「保存到本地」节点用）
```

标 ★ 的三处是扩展点：

- **加一种节点** = 写一个组件 + 在 `nodeRegistry.ts` 加一条。不改 store、不改画布、不用在任何分支判断里补 if。
- **接一个厂商** = 写一个 adapter + 在 `providers/index.ts` 加一条。节点只认 `ProviderAdapter` 接口。
- **改抽帧策略** = 只动 `lib/videoFrames.ts`。

依赖方向是单向的（`nodes → store`、`registry → nodes`），`graphStore` 刻意不引用注册表，避免 `graphStore → nodeRegistry → PromptNode → graphStore` 成环。

## 视频分析是怎么做的

这是相对同类工具刻意做厚的一块。抽帧用 WebCodecs 的 `VideoFrame`（拿不到时回退 `drawImage(video)`），**不引入 mp4box 之类的 wasm 解复用器**——否则单文件产物会直接膨胀。

转场判定不看单一像素差，而是三个互补信号加权：

| 信号 | 权重 | 擅长分辨 |
|---|---|---|
| 亮度直方图距离 | 0.5 | 整体影调变化（切景最敏感） |
| 4×4 分区亮度签名 | 0.3 | 构图 / 画面布局变化 |
| 逐像素平均绝对差 | 0.2 | 运动量 |

阈值不写死，取 **均值 + k×标准差**（默认 k=2.2）并留一个绝对下限（0.06）：静态画面不会被切碎，快剪片子也不会只切出一刀。另外只认局部峰值，一次转场不会连切好几刀。

关键帧取在**镜头中点**而不是转场那一帧——转场帧通常带运动模糊或叠化，拿它去反推提示词会跑偏。

采集方式：优先边播边采（`playbackRate=4`，长片也能几十秒扫完），没有 `requestVideoFrameCallback` 时回退到按固定时间点逐个 seek。

**装载与定位都有超时上限**（装载 20 s / 定位 10 s）。没有上限时，一个「连得上但永远不给数据」的地址（半死的 CDN、被中间设备吞掉的连接、浏览器解不了的编码）会让 `<video>` 停在 `readyState 0` 且不触发任何事件，界面上就是「读取元信息…」无限转下去。现在会明确失败并给出可读原因。

## 数据存在哪里

| 内容 | 位置 | 刷新后 |
|---|---|---|
| 画布（节点 / 连线 / 名称） | IndexedDB `vi-studio` → `kv.canvas` | 保留 |
| 素材库（历史 / 角色 / 提示词） | IndexedDB → `kv.library` | 保留 |
| AI 对话会话 | IndexedDB → `kv.chat` | 保留 |
| 视频拆解的关键帧（Blob） | IndexedDB → `scenes.<节点 id>` | 保留（object URL 读回时重建） |
| 主题、高性能模式 | localStorage | 保留 |
| 模型接入配置 | localStorage | 保留 |

换浏览器或清缓存会丢，需要先「导出」备份。导出走 File System Access API 流式写盘（一个节点一段），大图不会一次性在内存里拼字符串。节点删除时会顺手清掉它对应的关键帧，不留孤儿数据。

> IndexedDB 在 `file://` 下也可用，所以双击打开的单文件同样能存档。

## 本地配套工具

两个零依赖的 Node 脚本，都不是运行必需——只在对应场景下起：

```bash
node tools/dev-cors-proxy.mjs      # 本地 CORS 中转，默认 8788
node tools/local-cache-server.mjs  # 本地落盘服务，默认 9527
```

- **CORS 中转**：浏览器直连本地推理服务时，对方通常不返回 CORS 头，请求会被浏览器拦掉（表现为 `Failed to fetch`）。这个中转补上响应头，把它当成 Base URL 即可。它的价值是**不要求你改推理服务的启动参数**。
- **本地落盘服务**：「保存到本地」节点用。浏览器不能随便往任意目录写文件，这个服务提供一个 `/save` 端点，把结果落到本地目录（默认 `./vi-studio-output`）。

## 接入自己的模型

右上角「设置」填几项即可，任何 OpenAI 兼容服务都能用：

| 项 | 说明 |
|---|---|
| Base URL | 例如 `http://127.0.0.1:18080/v1` |
| API Key | 本地服务不需要就留空 |
| 对话 / 反推模型 | 例如 `qwen3.8-flash-next` |
| 图像模型 | 留空则回落到对话模型 |
| 视频模型 | 留空则回落到对话模型 |
| 转录模型 | 口播提取用，例如 `whisper-1` |

四个模型分开填，是因为多数网关的对话 / 图像 / 视频模型 ID 并不通用。

涉及的端点：`/chat/completions`、`/images/generations`、`/images/tasks/{id}`、`/videos/generations`、`/videos/{id}`。路径集中在 `src/providers/openaiCompat.ts` 顶部的 `PATHS`，对不上就在那里改。

## 当前进度

已跑通并在真实浏览器里实测：

- [x] 节点画布：缩放 / 平移 / 框选 / 连线 / Minimap / Fit View / 连线高亮
- [x] **22 种节点 / 5 大类**，声明式注册表驱动
- [x] **大模型节点**：真实补全调用跑通（含读图的多模态分支），输出与错误都写在节点上
- [x] **图像节点**：提交 + 异步任务自动轮询
- [x] **视频节点**：提交 → 轮询 → 进度回写，全程可取消，不阻塞画布
- [x] **视频分析节点**：WebCodecs 抽帧 → 自适应镜头切分 → 关键帧导出 → 逐镜头反推提示词
- [x] **上游文本 / 图片自动汇入**：连了线就生效，不需要额外开关
- [x] **持久化**：画布 / 素材库 / 对话 / 关键帧存 IndexedDB，刷新不丢
- [x] **撤销重做**（同标签 450 ms 内合并成一步，连续打字只算一次）、**复制粘贴**（应用内剪贴板；粘贴保留片段的相对布局、对齐到落点，重编 id 并清掉上一次的运行结果）
- [x] **自动布局**（DAG 拓扑分层）
- [x] **画布性能层**：缩放 < 40 % 自动切精简显示（CSS 类驱动，不走 JS）、可选虚拟渲染、高性能模式
- [x] **深色模式**（Tailwind 4 自定义 dark 变体）
- [x] 三个侧栏：生成历史 / 素材库 / AI 对话
- [x] 存档导出（流式）/ 导入（JSON）、模型接入设置
- [x] **连接失败会给出可操作的诊断**，而不是浏览器原生的 `Failed to fetch`
- [x] 单个节点渲染出错有错误边界兜底，不会带崩整棵树
- [x] **单文件产物在 `file://` 下实测可用**，22 种节点全部渲染通过、控制台无报错

多镜头切分实测：现场合成一段 3 镜头视频（蓝 / 橙 / 青，各 1.5 秒），
识别结果为「共 3 个镜头 · 转场 2 处 · 自适应阈值 0.503」，边界 0.0s / 1.6s / 3.2s，
三张关键帧的平均色分别落在蓝、橙、青三段——切分与取帧都对。

后续方向：

- [ ] 单文件冷启动给一份可一键载入的示例工作流
- [ ] 视频节点的首帧 / 尾帧 / 参考图可视化连线
- [ ] 把 `run*.ts` 里的编排逻辑收成一个可声明的工作流 DSL

## 已知限制

- **编码支持取决于浏览器**。抽帧依赖浏览器自带的解码器，Chromium 一般不含 H.265 / HEVC；遇到解不了的地址会在超时后明确报错，而不是一直转圈。
- **抽帧是逐帧读进内存的**，超长视频（几十分钟以上）建议先剪短。
- **`file://` 下调用本地接口需要对方放行 `null` 来源**（多数服务配置成 `*` 即可），否则请用 `tools/dev-cors-proxy.mjs`。
- **API Key 存在浏览器 localStorage**。单文件、无后端意味着没有更安全的存放位置——只在本机自用，别在共享电脑上填真 Key。

## 灵感与参考

- [Tapnow-Studio](https://github.com/zhengxinlan1995-code/Tapnow-Studio--) —— 同类型的单文件节点式 AI 工作流工具，本项目的**形态**参考。（**未复用其任何代码**；该项目为 GPLv3，本项目独立实现并以 Apache-2.0 发布。）

## 许可

[Apache License 2.0](LICENSE)