gflow-cli 是一个 Python 命令行工具与 MCP 服务器，用于从终端驱动 Google Flow，调用 Veo（图生视频、文生视频）和 Imagen（文生图）能力。它面向需要批量、脚本化、可接入流水线的用户，并让编码类 AI 智能体也能通过 MCP 控制生成过程。
用途与定位
该项目让拥有 Flow 访问权限的 Google 账号用户，以编程方式完成原本需要在网页中手动点击的生成操作。官方描述称其适用于：从 shell 循环批量生成图片；使用 Veo 的 t2v / i2v / r2v 以及视频延长（extend）超出 Flow 的 8 秒上限；通过 character 创建可复用的人物（面部与身体参考）以保持主体一致；使用 --tool creative-director 按 Google 的五要素公式改写简短提示词；将 Veo 接入内容自动化、AI 视频栈或批量实验。
主要能力
- 图片：文生图、图生图、上传、放大、批量处理；支持 Nano Banana 2.1（nano2）/ 2 Lite / Pro，五种宽高比（16:9、4:3、1:1、3:4、9:16），数量 1–4。已迁移的前端支持用 @Name 标记角色。
- 视频：t2v、i2v、r2v、chain、extend、放大；提供 5 个 Veo 模型的选择器以及 --duration 和 --count。
- 超越单次生成：gflow movie 渲染多场景清单；gflow instructions 管理持久化的 Agent-Mode 简报卡（不消耗积分）；gflow character 处理可复用主体；gflow scene 做免费的服务端拼接；--tool 应用提示词改写工具。
- 智能体集成：MCP 服务器（gflow mcp run stdio / gflow serve Streamable HTTP）向 AI 智能体暴露核心能力，并有 CI 强制检查的 CLI 与 MCP 功能对等契约。提供四个智能体入口，可按工具读取顺序选择；Claude Code 插件安装后默认禁用，需手动启用，或用 gflow mcp run --no-spend 自行注册以避免暴露消耗积分的工具。Codex 用户可用 codex plugin marketplace add 与 codex plugin add gflow@gflow-cli。
使用方式
首次使用执行 gflow auth login 后即可留在终端内操作；输出默认写入 $GFLOW_CLI_OUTPUT_DIR，可通过 GFLOW_CLI_STORAGE_URI 路由到 S3、MinIO 或 Google Cloud Storage。官方给出 60 秒快速开始与 10 分钟用户指南（USER_GUIDE: Journey 1）。首次调用需 30–90 秒等待 Chromium 预热，之后复用热会话。--browser chrome 是唯一会把配置文件标记为真实 Chrome 配置的策略；从本地检出安装时，uv tool install <path> 会忽略 uv.lock 并从 pyproject.toml 的范围解析依赖，可能带入未经测试的 Playwright 版本，需显式固定锁定版本；从 PyPI 安装（uv tool install gflow-cli）不受影响。
适用场景与限制
适用场景：拥有 Flow 权限和 Veo 积分、需要真实批量作业的用户；希望把 Veo 接入内容自动化或实验流水线的开发者；让编码智能体程序化调用生成能力的团队。 限制与风险（官方明确说明）：项目处于 alpha 阶段且为逆向工程实现，与 Google 无关联；通过持久化 Playwright Chromium 配置驱动有头浏览器，自动化受 Google 服务条款约束，端点和 UI 可能随时变化；视频生成会消耗账号的 Flow 积分，图片与合成操作免费；UI 漂移时会快速失败并给出不同退出码（如选择器漂移为 exit 23），批量项在提交前本地记录以避免在陈旧状态下消耗积分。文档 ACCOUNT_SAFETY.md 说明其保持低调的做法（真实有头 Chrome、随机交互时序、控制提交节奏）以及明确不做的事（不使用代理、不做指纹伪装、不假装不是自动化）。当前视频生成的纯 HTTP 传输被阻断：非 Chrome 浏览器下视频上传端点返回 HTTP 401，且存在无法无头复现的 reCAPTCHA 环节；三种早期 HTTP 策略仅保留在研究目录中。
其他信息
代码采用 MIT 许可证（© 2026 Flavio Oliva），仅覆盖 gflow-cli 代码，不授予 Flow、Veo 模型输出或任何 Google 服务的权利，生成内容受 Google 自身条款约束。项目由个人维护，接受赞助。
