<p align="center"><img src=".github/readme/banner.svg" alt="Flow Workspace MCP — 连接 Flow 与本地制作流程" width="100%"></p>

<h1 align="center">Flow Workspace MCP · 连接 Flow 与本地制作流程</h1>

<p align="center">复用 Google Flow 登录会话，跟踪生成任务，并交付身份可核对的本地素材。</p>

<p align="center"><img src="https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-60a5fa?style=flat-square&amp;labelColor=172033" alt="docs: 中文"> <img src="https://img.shields.io/badge/maintainer-QIANLING--0831-60a5fa?style=flat-square&amp;labelColor=172033" alt="maintainer: QIANLING-0831"> </p>

<p align="center"><a href="#解决什么问题">解决什么问题</a> &nbsp; · &nbsp; <a href="#有什么优势">有什么优势</a> &nbsp; · &nbsp; <a href="#如何工作">如何工作</a> &nbsp; · &nbsp; <a href="#快速开始">快速开始</a></p>

---

## 项目概览

| 方向 | 内容 |
| --- | --- |
| **工作区连接** | 隔离账号会话与实际能力读取 |
| **任务跟踪** | 同一编号查询，保存分镜组进度 |
| **素材交接** | 精确匹配原视频并记录下载信息 |

**将 Google Flow 接入本地视频制作：持久化任务、复用登录、原视频接口下载。**

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

> 开发状态：提供持久化整组分镜调度。后端余额与历史任务额度错误码读取已实测，原视频 HTTP 下载已实测。生成提交仍依赖网页；最新新生成测试在网页设置阶段失败，未提交，纯后端生成尚未完成。此前两段分镜回归在调试恢复后完成，不代表本轮最新生成验收通过。具体证据见 [验证记录](docs/VALIDATION.md)。多输出和放大未验收。

## 解决什么问题

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

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

## 有什么优势

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

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

## 如何工作

### 后端额度读取

项目内优先调用 GetCredits RPC 读取余额，不需要点击账号菜单；读不到或结构变化仍回退到界面。额度失败优先读取会话中结构化工具结果的 `error_code`，不依赖中文/英文错误措辞。提交前保存会话轮次基线，只接受新增轮次中唯一精确匹配的请求，避免历史失败误伤当前任务。

目前识别用户额度、模型每日额度（含可升级类别）、工作区账号额度；用户额度码已实测，其余来自 Google 当前客户端分类与自动化测试。明确请求限流不作为额度切号。旧任务无提交前基线时不借用历史错误自动重做；后端读取不支持时保留原有界面路径。私有协议不保证长期稳定，也没有把生成提交迁移成纯 HTTP。详见 [接口依据](docs/FLOW-API-SOURCES.md)。

### 接口优先的原视频下载

`flow_download_job` 对已追踪素材 ID 的单输出、未放大视频，优先通过 HTTP 获取登录校验参数、查询精确素材并下载原视频，不导航编辑器或点击控件。校验响应素材 ID、下载域名、视频类型及本地媒体信息；记录 `downloadTransport=http`。无法使用该路径时保留已有网页下载流程，绝不猜测最新素材。

目前是**混合实现，不是纯后端生成**：生成提交和可用模型配置仍依赖网页；额度与余额优先 HTTP 读取，排队及其他失败仍使用界面路径；登录会话仍由本地浏览器管理。HTTP 读取依赖未公开的网页 RPC，可能随网站更新而变化。独立 HTTP 查询与原片哈希一致性已实测，见 [接口验证](docs/READ-API-PROBE.md)。

### 额度查询与自动切号

`flow_account_credits` 优先读取 GetCredits RPC，必要时回退到账号菜单，不生成素材、不购买额度。无法识别时返回 `null`，不会当成零；当前不推算“今日免费余额”，因为读取的是可用余额，不推断免费和订阅额度的拆分。

先分别连接已有账号，再调用 `flow_configure_account_switching`，例如 `{"accountIds":["personal","backup"]}`。顺序为默认生成顺序；生成时显式指定 `accountId` 则该账号优先。传空数组关闭自动切号。

每个分镜使用 `outputs=1`。提交前余额明确为零，或当前配置的请求出现明确的额度不足提示时，自动尝试下一个账号，保留同一提示词和参数，并记录实际使用账号与跳过账号。每个账号最多尝试一次。

**排队、超时或状态不明的任务不会换号重提。** 当前请求对应回复明确失败且提示额度不足（包括 Flow 的“you've reached your credit or daily limit”）时，自动用下一账号重做独立片段，不要求“不扣额度”文字或提前报价。原任务记录替代任务编号；后续查原编号跟踪替代任务。验证码、明确限流、政策拦截、登录失效和原因不明的失败不会触发切号。每个账号最多尝试一次；全部耗尽则停止，不循环切换。

当前 Agent 提交控件未提供可确认的本次生成费用，因此尚未实现按“余额低于报价”跳过账号；不使用旧任务扣费、宣传额度或固定模型价格猜测当前费用。

### 只重做未完成的片段

按分镜逐段提交，每段 `outputs=1`。例如第 1、2 段已成功，第 3 段明确因额度不足失败：保留前两段，只用备用账号从头重做第 3 段，复制该段提示词、模型、比例、时长、本地参考素材和文件名前缀。原任务与替代任务双向关联，查询原编号可跟踪替代任务，重复查询不会重复提交。不是在另一账号续接已生成的半段视频。

使用 `flow_generate_sequence` 一次提交有序分镜数组，随后只查询同一个 `flow_sequence_status` 编号。调度器保留完成段，完成当前段的精确素材下载后自动提交下一段，并沿用成功账号、跳过本组已确认耗尽的账号。`results` 按分镜编号排列，不按下载时间；每段默认文件名前缀为 `shot-001` 等。状态查询会继续已授权的生成，并不是只读查询；`waitSeconds=0` 只读保存的快照。

进度保存在本地 `sequences/`，重启后查询原编号继续，不重新创建整组。并发查询使用跨进程锁；提交过程中异常退出且尚未保存任务编号时停止并要求检查，不能猜测是否提交成功再重提。调度由状态查询驱动，服务关闭时不会在后台继续生成，不是常驻无人值守队列。不能保证跨账号重生成画面完全一致；Flow 项目不跨账号复制，本地参考文件会复用。

支持 Agent 界面及中文普通生成界面；不同阶段的真实回归结果见验证文档，不能把早期失败记录当成最新状态。

```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 时，还记录时长、分辨率和编码信息。

生成通过真实网页工作区执行；符合条件的原视频下载优先通过网页自身的 HTTP 接口执行。它不是 Google 官方开发者 API，也不改变 Flow 的额度规则。网页及未公开接口的变化仍可能需要维护。

## 快速开始

需要 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_generate_sequence` / `flow_sequence_status` | 整组分镜启动一次、按同一编号推进；失败段换号重做后继续下一段 |
| `flow_job_status` | 按原任务编号查询进度 |
| `flow_download_job` | 下载该任务对应的素材 |
| `flow_upscale_video` | 使用账号实际提供的升级分辨率选项，可能额外消耗额度 |

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

例如对 AI 助手说：

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

## 边界

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

## 开发与来源

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

本项目由 QIANLING-0831 维护，重点开发接口优先的结果下载、新版工作区适配、会话复用、任务可追踪性和本地视频制作交接。继承代码的来源与版权说明见 [SOURCE.md](SOURCE.md) 和 [LICENSE](LICENSE)。

本项目与 Google 无官方关联。