# Flow Workspace MCP

**把 Google Flow 的网页生成流程，接入可追踪、可重复的本地视频制作流程。**

适合需要持续制作教学视频、科普视频和多个分镜素材的创作者。通过 MCP，AI 助手可以读取账号实际可用的模型与参数、提交生成任务、查询进度，并把对应素材下载到本地。无需另购视频生成 API，但仍使用你的 Google Flow 权限和额度。

> 开发状态：正在适配新版 `flow.google.com`。登录会话复用和工作区读取已实测；单张图片和一个 4 秒视频已生成、下载并通过解码检查。测试期间修复了问题并恢复原任务，尚未验证修复后新任务全程无干预运行；多输出和放大也未验收。当前不应视作稳定生产版。最新证据见 [验证记录](docs/VALIDATION.md)。

## 解决什么问题

做一条视频往往需要多个片段。重复复制提示词、选择模型和比例、等待生成、确认素材、下载改名，会把制作过程拆成很多人工操作。让 AI 助手逐次通过截图点击，也需要反复读取界面，耗时且容易受页面变化影响。

本项目将这些动作收束为有明确输入、任务编号和输出文件的工具调用。提示词来自你自己的脚本或分镜；Flow 负责生成；本项目负责连接工作区、执行参数、跟踪任务和交付素材。

## 有什么优势

| 能力 | 对制作流程的意义 |
|---|---|
| 复用本地登录会话 | 会话有效时继续工作，减少重复登录 |
| 记住上次工作区 | 重启后回到已有项目，减少反复创建空项目 |
| 读取实际模型和参数 | 以账号当前界面为准，不把写死的模型列表当成可用能力 |
| 持久化任务编号 | 等待、查询和下载围绕同一任务进行，避免排队时重复提交 |
| 匹配具体生成素材 | 不简单下载图库里“最后一个”或“最新的”文件 |
| 本地文件与参数记录 | 素材能交给 FFmpeg 或其他剪辑流程，便于按镜头管理 |
| 截图与控件诊断 | 页面改版或识别失败时留下证据，方便定位问题 |

相比 AI 助手逐步操作浏览器，明确参数和简短任务状态通常能减少界面读取及交互次数；具体 Token 和时间收益需要按同一任务实测。项目不提升视频模型本身的画质，也不减少 Flow 对生成任务收取的额度。

## 如何工作

```mermaid
flowchart LR
  A[脚本与分镜提示词] --> B[AI 助手调用 MCP]
  B --> C[本地 Flow 工作区适配器]
  C --> D[Google Flow 生成]
  D --> E[任务与素材身份跟踪]
  E --> F[本地视频及参数清单]
  F --> G[配音、字幕与剪辑流程]
```

1. **连接账号**：浏览器扩展将你已有的 Google 登录会话发送到本机回环地址。账号使用隔离的本地浏览器配置；不会要求把密码写入项目。
2. **识别工作区**：校验当前 Flow 地址、项目与编辑器控件，读取实际显示的模型、比例和输出数量。适配器同时兼容已有控件和新版 Angular Material 控件。
3. **执行任务**：每次生成都有独立任务编号与状态记录。请求必须明确允许消耗额度；项目不购买订阅或额外额度。
4. **确定素材**：生成前记录素材基线，之后按素材标识与来源匹配新增输出。匹配不明确时返回错误，避免交付错误视频。
5. **保存结果**：下载到指定绝对路径，记录文件大小与 SHA-256。有可用 FFprobe 时，还记录时长、分辨率和编码信息。

它通过真实网页工作区执行操作，并非 Google 官方生成 API。因此网页改版仍可能需要更新适配器；任务记录和诊断能帮助维护，但不能保证永远免维护。

## 快速开始

需要 Node.js 20+、已安装的 Chrome/Chromium，以及可以访问 Flow 的 Google 账号。Windows 是目前实际调试的平台。

```powershell
git clone https://github.com/QIANLING-0831/flow-workspace-mcp.git
cd flow-workspace-mcp
npm ci
npm run check
```

使用绝对路径注册到 Codex，例如：

```powershell
codex mcp add flow-workspace -- node "C:\tools\flow-workspace-mcp\dist\index.js"
```

其他支持 stdio 的 MCP 客户端也可以配置 `node` 加绝对路径 `dist/index.js`。首次连接步骤见 [安装说明](INSTALL.md)。后续先读取账号状态，已有有效连接就直接使用；仅在会话失效、退出登录或更换账号时重新连接。

### 主要工具

| 工具 | 用途 |
|---|---|
| `flow_list_accounts` | 查询已连接账号与默认账号 |
| `flow_inspect_account` | 验证工作区、读取可用能力和诊断 |
| `flow_begin_account_connection` / `flow_complete_account_connection` | 首次连接或重新连接账号 |
| `flow_generate_video` / `flow_generate_image` | 提交生成请求，返回任务状态 |
| `flow_job_status` | 按原任务编号查询进度 |
| `flow_download_job` | 下载该任务对应的素材 |
| `flow_upscale_video` | 使用账号实际提供的升级分辨率选项，可能额外消耗额度 |

工具保留 `flow_*` 名称，以便复用已有客户端和制作流程。

例如对 AI 助手说：

> 读取我的 Flow 账号可用的视频模型。用我确认的模型生成一个横版纸艺动画镜头，只生成一个输出，不升级分辨率，保存到我指定的素材目录。如果仍在生成，查询同一任务，不要再次提交。

## 边界

- 这是素材生成自动化工具，不是完整的脚本、配音、字幕或剪辑软件。
- 模型、时长、参考素材和升级分辨率是否可用，以账号当前能力为准。
- 自动化不绕过账号访问限制或验证码，不承诺免费无限生成。
- 默认保留本地账号配置、任务和诊断；不要将这些运行数据上传到仓库。
- 生成等待超时不等于任务失败。查询已有任务，避免重复生成和重复消耗额度。

## 开发与来源

```powershell
npm run check
npm pack --dry-run
```

本项目由 QIANLING-0831 维护，基于 Google Flow MCP 的 MIT 代码发展而来，保留原始贡献历史。我们重点维护新版工作区适配、会话复用、任务可追踪性和本地视频制作交接。来源与改动说明见 [SOURCE.md](SOURCE.md)，许可证见 [LICENSE](LICENSE)。

本项目与 Google 无官方关联。