Skip to content

readme_for_ai.md

Latest commit

 

History

History
315 lines (268 loc) · 35.6 KB

readme_for_ai.md

File metadata and controls

315 lines (268 loc) · 35.6 KB
Raw

Browser API Proxy AI Readme

目标

这份文档服务于后续 AI，说明 api_proxy/ 这个独立实验模块的职责、入口和边界。

读取完本文后，后续 AI 应该立刻知道：

  1. api_proxy/ 是什么，什么时候应该进入这里。
  2. 它不是 app/ 主流程的一部分，不能把它误当成正式 provider 接入层。
  3. 它已经不是单一 Flow 目录，而是“浏览器 API 原型容器”；当前稳定落地的是 Flow、Doubao，以及一个已接入容器并已能跑商品目录 / 购买前表单链路的 Dyks provider。

文档记录规则：

  • 只记录当前稳定的目录职责、入口文件、运行方式和仍然有效的限制。
  • 不记录一次性排障过程、临时试验日志或某一次运行结果。

模块定位

api_proxy/ 是一个本地优先、但现在已经部署到 Ubuntu 服务器的浏览器自动化 API 原型容器。

当前已落地 provider：

  • flow
    • 通过真实浏览器自动操作 Google Flow，再封装成本地 HTTP API
  • doubao
    • 通过真实浏览器自动操作豆包聊天 / 图片 / 视频生成页面，再封装成本地 HTTP API

当前另有一个已接线、但功能范围仍然收敛的 provider：

  • dyks
    • 目标站点是 http://ccwl.dyks123.top/indexPc.html#/
    • 当前已经挂到容器里，提供账号缓存管理、session/check、支持账号密码初始化登录的 session/init，以及“打开充值 / 账户页面”、“全量商品目录统计”、“单商品表单 schema 提取”和“购买页预填写但不提交”的接口；暂时还没有管理页、扣费确认或购买结果回传

适用场景：

  • 用户明确要研究或试做“通过真实浏览器驱动网站工作台，再封装成本地 API”的方案。
  • 需要调试 Playwright 驱动、持久化浏览器 profile、页面选择器、生成结果抓取与下载。
  • 需要在同一个实验模块下继续增加第二个、第三个浏览器型 provider。

不适用场景：

  • 正式的 app/ 主流程功能开发。
  • app/providers/ 下的正式 provider 接入。
  • 通用的图像/视频/3D 正式能力扩展。

详细用法入口：

  • 先读 README.md
  • 如果只是想在 Windows 下一键拉起本地 API，先看 run_local_windows.py
  • 如果要看 Ubuntu 服务器部署入口，先看 deploy/
  • 如果要看共享运行时和容器入口，读 core/ 和 app.py
  • 如果要看 provider 层，先读 providers/readme_for_ai.md
  • 如果目标是 Flow provider，继续读 providers/flow/readme_for_ai.md
  • 如果目标是 Doubao provider，继续读 providers/doubao/readme_for_ai.md
  • 如果目标是 Dyks provider，继续读 providers/dyks/readme_for_ai.md
  • 如果要看对外 API 文档，先读 api_doc/readme_for_ai.md

当前结构

  • app.py
    • FastAPI 容器入口；负责挂载 Flow / Doubao / Dyks provider 路由、统一异常处理、React 管理页静态文件托管，以及 Doubao 每日额度缓存的后台跨日维护
  • run_local_windows.py
    • Windows 一键启动脚本；负责自动准备 .venv、补装 requirements.txt、复用或探测本地代理，并优先使用显式配置的系统浏览器；未显式配置时，Windows 会自动探测本机 Chrome，其次 Edge；只有没有可用系统浏览器时才会继续依赖 Playwright Chromium。脚本也会优先复用已装好的 Playwright 浏览器目录；如果 data/shared/pw-browsers/ 只是空目录而旧的 data/pw-browsers/ 已有浏览器，会自动回退到旧目录；随后在新 PowerShell 窗口里拉起后端并轮询 /providers/flow/health。启动完成或复用已有实例时，会显式打印 Shared UI、Flow UI、Doubao UI、Dyks UI、Docs 和 Health 地址
  • deploy/
    • Ubuntu 服务器部署入口；当前包含 install_ubuntu.sh、start_backend.sh、start_remote_desktop.sh、check_provider_sessions.sh 和 systemd/ 模板。部署完成后，api-proxy-backend.service 监听 127.0.0.1:8011，api-proxy-desktop.service 维护 Xvfb + openbox + autocutsel + x11vnc + noVNC/websockify，并由 api-proxy-session-check.timer 每天 03:15 固定请求 Flow + Doubao 的 session/check 刷新缓存登录状态，再由根目录 nginx.conf 反代到 /ui/、/providers/、/docs 和 /desktop/。start_backend.sh 目前仍保留全局 BROWSER_API_HEADLESS=true，但会显式给 Flow 覆盖 FLOW_HEADLESS=false，因为这个服务器上的 Flow 图像生成在 headless 模式下会稳定复现“页面无最终结果”的超时，而 headed 模式正常
  • web/
    • React + Vite + Mantine 管理页前端项目；构建产物在 web/dist/，由 app.py 挂载到 /ui/
    • 当前管理页支持在 Guide / Flow / Doubao / Dyks 四个标签之间切换；/providers/<provider>/ui 在 web/dist/ 存在时会统一跳到 /ui/?tab=<provider>，让共享页直接落到对应 provider 标签页。共享页现在额外提供 ?tab=guide 的使用说明页，给非开发者汇总当前部署入口、登录流程、常用 API 路由和最小请求示例；完整字段定义仍以 /docs、/redoc 和 api_doc/ 为准。共享页顶部现在包含 /desktop/ 的 noVNC 远程桌面面板，但默认不自动连接；只有手动点“连接桌面”或点击 “打开登录窗口” / session/init 后，才会真正挂载 iframe 并连接服务器桌面；session/init 如果以 logged_in=true 成功返回，当前页面会自动断开这个嵌入式桌面连接；如有需要也仍可单独打开 /desktop/。Flow 测试面板支持 Banana 图片和 Veo 3.1 视频，Doubao 测试面板支持 Seedream 图片生成、Seedance 视频后台任务提交、直接选择本地参考图文件、任务轮询状态展示、图片上限启发式展示和视频每日额度字段展示，Dyks 测试面板支持缓存管理、商品目录统计、单商品 schema 和购买前表单预填写
    • 开发时 npm run dev 在 5174 端口运行，Vite 会代理 API 到后端 8000 端口
  • core/settings.py
    • 共享运行时配置；管理 Playwright 浏览器目录、系统浏览器探测、结果目录根路径、代理、轮询间隔、通用超时和旧环境变量兼容
  • core/errors.py
    • OpenAI 风格错误对象和统一错误 payload
  • results/api_proxy/
    • 该实验模块的结果目录；当前按 provider 分到 providers/<provider>/output/<run_id>/
  • providers/readme_for_ai.md
    • provider 容器索引；先从这里确认当前有哪些浏览器 provider
  • providers/flow/readme_for_ai.md
    • Flow provider 的 AI 入口文档
  • providers/flow/router.py
    • Flow 对外 FastAPI 路由；当前暴露 provider-scoped 路由、管理页和旧的兼容别名
  • providers/flow/service.py
    • Flow 浏览器自动化主逻辑；负责按浏览器缓存 profile 启动持久化 Chromium、进入 Flow、填 prompt、控制图片 / 视频设置面板、读取账号缓存积分和本次生成消耗、在调用前做额度预检与自动选号，并优先通过结果预览页 Download 菜单导出媒体；图片模式会通过底部 Create 资产选择器处理 Banana 参考图，视频模式会通过项目资产选择器处理首尾帧 / Ingredients 参考图；session/init 现在会先判断是否需要登录，只点击明确的 sign-in 入口，不会在未登录时先点 Flow landing/onboarding 的 workspace 按钮，而且一旦页面已经跳到 Google 登录就会立刻停止后续 workspace 点击；同时按账号 + 项目累计已生成媒体数，达到阈值后在调用前清空当前项目历史媒体。Flow 现在也有独立的默认 headless 配置：优先读 FLOW_HEADLESS，再回退全局 BROWSER_API_HEADLESS；当前服务器部署显式把它设成 false
  • providers/flow/settings.py
    • Flow provider 配置；集中管理 Flow URL、浏览器缓存 profile 根目录、输出目录、历史计数文件、默认超时和 selector/pattern 默认值
  • providers/flow/account_store.py
    • Flow 浏览器缓存注册表；维护 accounts.json 和 profiles/<account_id>/ 目录，以及启用/禁用状态、登录状态、缓存积分快照
  • providers/flow/history_store.py
    • Flow 历史媒体计数注册表；维护 history_counters.json，按 account_id + project scope 记录累计媒体数与最近清理时间
  • providers/flow/usage_store.py
    • Flow API 调用日志与聚合统计存储；维护 usage_events.json，支持按日 / 周 / 月汇总各缓存调用情况
  • providers/flow/management_page.py
    • Flow 旧版管理页（纯 HTML/CSS/JS 字符串拼接）；新版已迁移到 web/ 的 React 项目，旧版仍保留在 /providers/flow/ui/legacy
  • providers/flow/models.py
    • OpenAI 风格 Banana 图片接口、Veo 3.1 视频接口与内部 Flow 请求/响应模型
  • providers/doubao/readme_for_ai.md
    • Doubao provider 的 AI 入口文档
  • providers/doubao/router.py
    • Doubao 对外 FastAPI 路由；当前暴露 provider-scoped 路由、管理页入口、Seedream 图片生成接口、Seedance 同步视频生成接口，以及管理页专用的后台视频任务提交 / 状态查询接口
  • providers/doubao/service.py
    • Doubao 浏览器自动化主逻辑；负责按浏览器缓存 profile 启动持久化 Chromium、进入豆包聊天 / 图片 / 视频页面、切换图像生成模式、设置图片模型 / 比例 / 风格、填 prompt、轮询排队 / 完成状态、抓取图片或视频结果，并读取 / 缓存视频每日额度、本次消耗、实际模型文案和预计等待时间；视频导出现在会优先尝试分享链路，通过提取 share_id + video_id 调用 POST /creativity/share/get_video_share_info 下载分享页视频，拿不到分享信息时才回退到页面直存；Doubao 不再在服务启动时为了刷新额度主动开页面，而是只做本地跨日额度缓存重置，真实额度继续依赖手动 session 检查或实际视频调用时从页面文案回写；图片生成会用确认文案 我将为你生成...图片 做上限启发式判断，并收集单次任务返回的整组新图片；视频生成不再把 timeout_sec 当作最终成片总等待上限，而是把它作为提交阶段保护和页面失联 watchdog
  • providers/doubao/settings.py
    • Doubao provider 配置；集中管理豆包 chat / create-video URL、浏览器缓存 profile 根目录、输出目录、后台视频任务状态文件、默认超时和 selector / pattern 默认值
  • providers/doubao/account_store.py
    • Doubao 浏览器缓存注册表；维护 accounts.json 和 profiles/<account_id>/ 目录，以及启用 / 禁用状态、登录状态、额度快照
  • providers/doubao/usage_store.py
    • Doubao API 调用日志与聚合统计存储；维护 usage_events.json，支持按日 / 周 / 月汇总各缓存调用情况
  • providers/doubao/video_job_store.py
    • Doubao 管理页视频后台任务注册表；维护 video_jobs.json，记录后台视频任务的状态、最近进度和最终结果快照
  • providers/doubao/models.py
    • OpenAI 风格 Doubao 图片 / 视频接口与内部 Doubao 请求 / 响应模型
  • providers/dyks/readme_for_ai.md
    • Dyks provider 的 AI 入口文档
  • providers/dyks/router.py
    • Dyks 对外 FastAPI 路由；当前暴露 provider-scoped 的健康检查、浏览器缓存账号管理、session/check、支持账号密码登录的 session/init、/providers/dyks/v1/topups、/providers/dyks/v1/goods/list、/providers/dyks/v1/goods/schema、/providers/dyks/v1/purchases/open 和 /providers/dyks/v1/purchases/prepare
  • providers/dyks/service.py
    • Dyks 自动化主逻辑；负责按浏览器缓存 profile 启动持久化 Chromium、支持账号密码登录并把登录态写回持久化缓存、判断是否已登录、尽力读取余额、抓取 /api/goodsList 商品目录、解析 ParamsTemplate、补齐商品页可见控件，并直接打开或预填写账户 / 充值目标页、商品购买页
  • providers/dyks/settings.py
    • Dyks provider 配置；集中管理目标站点 URL、账户 / 充值页 URL、站点信息接口、商品目录接口、浏览器缓存 profile 根目录、输出目录、默认超时，以及登录 / 余额探测相关 pattern
  • providers/dyks/account_store.py
    • Dyks 浏览器缓存注册表；维护 accounts.json 和 profiles/<account_id>/ 目录，并会为默认浏览器缓存自动注册 default 账号
  • providers/dyks/models.py
    • Dyks 请求 / 响应模型；当前已覆盖 session、账号管理、topup、goods-list、goods-schema、purchase-page 和 purchase-prepare 入口
  • api_doc/readme_for_ai.md
    • 对外 API 文档索引；按 provider 分组管理
  • api_doc/flow/readme_for_ai.md
    • Flow provider API 文档索引
  • api_doc/flow/banana.md
    • 面向调用方的 Flow Banana OpenAI 风格接口文档
  • api_doc/flow/veo31.md
    • 面向调用方的 Flow Veo 3.1 OpenAI 风格视频接口文档
  • api_doc/doubao/readme_for_ai.md
    • Doubao provider API 文档索引
  • api_doc/doubao/video.md
    • 面向调用方的 Doubao Seedance OpenAI 风格视频接口文档
  • api_doc/doubao/image.md
    • 面向调用方的 Doubao Seedream OpenAI 风格图片接口文档
  • api_doc/doubao/usage_summary.md
    • 面向调用方的 Doubao 缓存监控聚合接口文档
  • api_doc/dyks/readme_for_ai.md
    • Dyks provider API 文档索引
  • api_doc/dyks/topup.md
    • 面向调用方的 Dyks 账户 / 充值页打开接口文档
  • api_doc/dyks/goods_list.md
    • 面向调用方的 Dyks 全量商品目录统计接口文档
  • api_doc/dyks/goods_schema.md
    • 面向调用方的 Dyks 单商品表单 schema 接口文档
  • api_doc/dyks/purchase_open.md
    • 面向调用方的 Dyks 商品购买页打开接口文档
  • api_doc/dyks/purchase_prepare.md
    • 面向调用方的 Dyks 购买前表单预填写接口文档

运行与调试入口

启动顺序：

Ubuntu 服务器部署优先使用：

  1. 在 api_proxy/ 下执行 bash deploy/install_ubuntu.sh
  2. 把 deploy/systemd/api-proxy-backend.service 和 deploy/systemd/api-proxy-desktop.service 安装到 /etc/systemd/system/
  3. 启用并启动 api-proxy-desktop.service 和 api-proxy-backend.service
  4. 根目录 nginx.conf 当前已经把 api_proxy 暴露到 https://yonderseek.com/ui/、/providers/、/docs 和 https://yonderseek.com/desktop/
    • 其中 /providers/ 当前显式使用 3600s 的代理 connect/send/read timeout，避免管理页里的 session/init 被默认 60 秒反代超时截断；共享管理页里的登录按钮默认也会传 timeout_sec=3600，后端三个 provider 的 SessionInitRequest 校验上限也已经同步放宽到 3600
  5. 上述入口都走 Basic Auth；认证文件当前是 data/nginx_basic_auth.htpasswd
  6. 共享管理页本身已经包含远程桌面面板；如果单独打开 https://yonderseek.com/desktop/，也会看到同一个服务器虚拟显示桌面。管理页默认不会自动连接这个桌面；在页面里点击 session/init / “打开登录窗口”或手动点“连接桌面”后，才会真正连到该桌面并看到真实浏览器窗口；一旦 session/init 成功返回 logged_in=true，当前页面会自动断开这个嵌入式桌面连接
  7. 如果浏览器窗口起不来，先优先怀疑 Playwright Chromium 缺系统依赖，检查 deploy/install_ubuntu.sh 是否已经执行过 playwright install-deps chromium

Windows 本地一键启动优先使用：

  1. 在 api_proxy/ 下运行 python run_local_windows.py
  2. 脚本会优先复用 BROWSER_API_PYTHON，否则创建或复用模块自己的 .venv
  3. 缺少 requirements.txt 依赖时自动安装；若未检测到可复用的系统浏览器，才会继续补装 Playwright Chromium
  4. 如果本地 127.0.0.1:7890 可达且未显式设置代理环境变量，脚本会自动补 HTTP_PROXY / HTTPS_PROXY
  5. 脚本在新 PowerShell 窗口启动 uvicorn app:app，并轮询 /providers/flow/health，确认服务就绪后才返回
  6. 启动完成后，脚本会在终端显式打印 Shared UI、Flow UI、Doubao UI、Dyks UI、Docs 和 Health 地址；打开 /providers/flow/ui、/providers/doubao/ui 或 /providers/dyks/ui 时，若 web/dist/ 存在会自动重定向到共享的 /ui/?tab=<provider> React 管理页，并直接定位到对应 provider tab；否则 Flow 仍可回退到 legacy 管理页，而 Doubao / Dyks 会提示 React 管理页尚未构建

手动启动顺序：

  1. 在 api_proxy/ 下安装 requirements.txt
  2. 先把 PLAYWRIGHT_BROWSERS_PATH 指到模块自己的浏览器目录，再安装 Playwright Chromium
  3. 如需刷新 React 管理页，在 web/ 目录下 npm install && npm run build
  4. 启动 uvicorn app:app
  5. 打开 /providers/flow/ui、/providers/doubao/ui 或 /providers/dyks/ui 进入管理页；如果前端已构建，这些入口都会跳到共享 /ui/?tab=<provider>
  6. 再按 provider 调用对应的 /providers/flow/...、/providers/doubao/... 或 /providers/dyks/... 接口；Dyks 现在已经有独立的 provider-scoped 管理页入口路由，且会直达共享 React 管理页里的 Dyks tab，可直接调试 session / topup / goods-list / goods-schema / purchase-page / purchase-prepare

调试优先级：

  • 如果服务起不来，先看 app.py、core/settings.py、providers/flow/router.py
  • 如果监控接口或统计口径异常，先看 providers/flow/usage_store.py、providers/flow/router.py、providers/flow/service.py
  • 如果管理页或浏览器缓存异常，先看 providers/flow/account_store.py、providers/flow/management_page.py、providers/flow/router.py
  • 如果浏览器打不开、登录态异常、页面跳错，先看 providers/flow/service.py 中的 _browser_session()、_open_flow()、_get_login_state()、_best_effort_open_login()
  • 如果找不到输入框或按钮，先看 providers/flow/service.py 中的 _best_effort_prepare_workspace()、_find_prompt_input()、_find_generate_button()、_prepare_generation_controls()、_find_settings_summary_button()，再检查 providers/flow/settings.py
  • 如果模型 / 比例 / 次数没有切成功，先看 providers/flow/service.py 中的 _prepare_generation_controls()、_select_settings_tab()、_select_model()、_read_generation_controls()
  • 如果 Banana 图片参考图没有挂到当前请求，先看 providers/flow/service.py 中的 _prepare_image_input_assets()、_assign_image_reference_asset()、_open_image_reference_picker()、_select_asset_from_picker()
  • 如果 Veo 3.1 的首尾帧 / Ingredients 参考图没有选中，先看 providers/flow/service.py 中的 _prepare_video_input_assets()、_assign_video_frame_asset()、_assign_video_ingredient_asset()、_select_asset_from_picker()
  • 如果账号积分没有读到，先看 providers/flow/service.py 中的 _open_account_menu()、_read_account_credit_snapshot()、_refresh_account_credit_snapshot()
  • 如果本次生成消耗没有读到或额度预检异常，先看 providers/flow/service.py 中的 _read_generation_credit_cost()、_ensure_credits_sufficient()、_list_candidate_accounts()
  • 如果结果抓取失败，先看 providers/flow/service.py 中的 _collect_generation_artifacts()、_inspect_generation_state()、_list_fresh_media_candidates()、_list_progress_markers()、_list_failure_markers()
  • 如果结果导出分辨率不对、Download 菜单点不开或文件下载失败，先看 providers/flow/service.py 中的 _save_media_candidate()、_download_media_candidate_from_preview()、_find_preview_download_button()、_find_download_resolution_menu_item()、_close_media_preview()
  • 如果长期调用后图片历史清理异常，先看 providers/flow/service.py 中的 _cleanup_history_if_needed()、_clear_project_media_history()、_find_project_media_more_button()，再看 providers/flow/history_store.py 和 providers/flow/settings.py
  • 如果 Doubao 登录态、聊天页 / 图片 / 视频页切换异常，先看 providers/doubao/service.py 中的 _open_doubao()、_get_login_state()、_ensure_image_mode()、_ensure_video_page()
  • 如果 Doubao 找不到输入框或发送按钮，先看 providers/doubao/service.py 中的 _find_prompt_input()、_fill_prompt()、_find_send_button()，再检查 providers/doubao/settings.py
  • 如果 Doubao 视频额度、图片上限启发式、排队状态或完成反馈没有读到，先看 providers/doubao/service.py 中的 _read_page_quota_snapshot()、_inspect_generation_state()、_list_relevant_status_fragments()、_extract_quota_snapshot()、_extract_acknowledgement_text()、_extract_limit_message()
  • 如果 Doubao 图片或视频结果没抓到，先看 providers/doubao/service.py 中的 _collect_generation_artifacts()、_snapshot_thread_urls()、_find_new_thread_url()、_list_fresh_media_candidates()、_build_generation_results()、_save_media_candidate()、_save_video_candidate_via_share()、_save_media_candidate_from_preview()
  • 如果 Doubao 后台视频任务状态不更新、任务丢失或页面刷新后拿不到结果，先看 providers/doubao/video_job_store.py 和 providers/doubao/router.py
  • 如果 Doubao 监控口径异常，先看 providers/doubao/usage_store.py、providers/doubao/router.py、providers/doubao/service.py
  • 如果是 Dyks 相关问题，先看 providers/dyks/router.py、providers/dyks/models.py 和 providers/dyks/service.py 是否仍保持一致，再确认 app.py 的 /providers 列表和 Dyks 路由是否一起更新
  • 如果 Dyks 登录态或业务数据读不到，先确认账号密码登录链路是否仍有效、目标站点是否仍落到 #/login，以及 /api/userInfo?Switch=4 是否仍要求 Authorization: Bearer <ACCESS_TOKEN>；不要再把“必须先手工准备缓存登录”当成前提

稳定边界

当前稳定事实：

  • 这是“本地 HTTP API + 真实浏览器自动化”的实验容器，不是官方 API。
  • 当前既支持 Windows 本地一键启动，也支持 Ubuntu 服务器部署；服务器部署形态是 api-proxy-backend.service + api-proxy-desktop.service + Nginx Basic Auth
  • 当前稳定落地的 provider 有 flow、doubao，以及已经能跑商品目录和购买前表单链路的 dyks。
  • 当前推荐的外部路由是 provider-scoped 风格：/providers/flow/...、/providers/doubao/...、/providers/dyks/...
  • providers/dyks/ 当前已经挂到 app.py 和 /providers 列表里；稳定能力暂时覆盖浏览器缓存管理、账号密码初始化登录、登录态探测、“打开账户 / 充值页”、全量商品目录统计、单商品表单 schema、“打开商品购买页”和“购买前表单预填写”，但还不包括管理页、真正下单提交、购买结果抓取或监控聚合
  • 为了兼容现有调用，Flow 仍保留 /session/*、/v1/images/generations、/v1/videos/generations、/v1/files/... 旧别名。
  • data/ 是该实验模块的运行状态目录，不参与 git 同步；其中包含浏览器缓存、账号注册表、调用日志、历史计数和 Playwright 浏览器二进制。生成结果目录独立放在 results/api_proxy/。
  • 共享 Playwright 浏览器目录默认走 data/shared/pw-browsers/；如果旧的 data/pw-browsers/ 已经有已安装浏览器，而 data/shared/pw-browsers/ 还只是空目录或没有实际浏览器 payload，服务会自动回退到旧路径。
  • 浏览器二进制优先级是：显式配置的 BROWSER_API_BROWSER_EXECUTABLE / FLOW_BROWSER_EXECUTABLE -> Windows 自动探测本机 Chrome -> Windows 自动探测本机 Edge -> Playwright 自带 Chromium。
  • 现在已提供 run_local_windows.py 作为 Windows 一键启动入口；默认端口是 8011，可通过 BROWSER_API_PORT 覆盖。
  • Flow 浏览器缓存注册表默认走 data/providers/flow/accounts.json，多缓存 profile 默认走 data/providers/flow/profiles/<account_id>/；如果旧的 data/profile/ 已存在，服务会把它作为兼容用的 default 浏览器缓存继续复用。
  • Flow output 默认走 results/api_proxy/providers/flow/output/；不再自动回退复用旧的 data/output/，如需旧路径只能显式设置 FLOW_OUTPUT_DIR。
  • Flow 历史媒体计数默认走 data/providers/flow/history_counters.json；按浏览器缓存账号 + Flow 项目维度累计。
  • Flow API 调用日志默认走 data/providers/flow/usage_events.json；按浏览器缓存记录 session/check、session/init、images/generations、videos/generations 的状态和统计摘要。
  • Doubao 浏览器缓存注册表默认走 data/providers/doubao/accounts.json，多缓存 profile 默认走 data/providers/doubao/profiles/<account_id>/；如果旧的 data/profile/ 已存在，服务会把它作为兼容用的 default 浏览器缓存继续复用。
  • Doubao output 默认走 results/api_proxy/providers/doubao/output/；不再自动回退复用旧的 data/output/，如需旧路径只能显式设置 DOUBAO_OUTPUT_DIR。
  • Doubao API 调用日志默认走 data/providers/doubao/usage_events.json；按浏览器缓存记录 session/check、session/init、images/generations、videos/generations 的状态、排队摘要、完成反馈、图片上限启发式和视频每日额度字段。
  • Doubao 管理页视频后台任务注册表默认走 data/providers/doubao/video_jobs.json；服务重启时会把未完成的后台视频任务标记为失败，避免页面继续误以为任务还在运行。
  • Doubao 不会在服务启动时为了查视频额度主动打开豆包页面；启动和跨午夜时只会本地把过期的每日额度缓存翻到当天并清空旧余额，等待当天第一次真实视频调用或手动 session/check / session/init 再回写页面里读到的额度字段。
  • 当前 Flow 请求按浏览器缓存维度串行执行；同一缓存共享一个持久化 profile，不允许并发抢占同一个 profile。
  • 当前 Flow 公开支持的模型 id 是 banana-2、banana-pro、veo-3.1-fast、veo-3.1-quality。
  • Flow 图片 / 视频生成默认超时都是 1800s；请求也可以单独传 timeout_sec 覆盖。
  • 当前 Flow 结果抓取不是“看到新图就保存”，而是要同时满足：新图数量达到请求次数、页面上没有任何 % 进度、这些新图已经稳定可见，然后才导出结果。
  • 当前图片工作流的模型、图像比例、生成次数、参考图和结果导出分辨率都可控；视频工作流支持 frames / ingredients 两种模式、项目资产选择器参考图、16:9 / 9:16、x1 到 x4、veo-3.1-fast / veo-3.1-quality；接口会把实际生效设置、生成进度样本和槽位级错误一并回传。
  • 当前 Banana 图片参考图支持两种来源：直接指定已在项目里的 project_asset_name，或提供本地文件 / URL / b64_json 让服务先上传进项目后，再通过图片模式底部 Create 资产选择器点击选中。
  • 当前 Flow 会从右上角账号菜单读取并缓存账号积分，从项目底部设置面板读取本次生成消耗；未显式传 account_id 时，会优先挑选缓存积分足够的浏览器缓存执行请求，并在成功后按本次消耗估算扣减缓存积分。
  • 当前 Veo 3.1 参考图支持两种来源：直接指定已在项目里的 project_asset_name，或提供本地文件 / URL / b64_json 让服务先上传进项目后再从资产选择器里点击选中。
  • 当前媒体工作流会按账号 + 项目累计已生成媒体数；累计达到 100 个媒体卡片后，会在下一次调用生成前通过项目历史卡片菜单逐张清空当前项目历史媒体，再继续请求。
  • 当前结果导出优先通过预览页 Download 菜单完成，公开分辨率值为 original 和 2k；Flow 页面里的 4k 仍是 Upgrade 项，不作为正式 API 能力暴露。
  • 当前 Veo 3.1 的 fast / quality 在 Flow 页面上的基础积分消耗分别是 20 / 100，并会随 xN 线性放大；服务会把实际读到的本次积分消耗写回响应和监控日志。
  • 当前 Doubao 图片公开支持的模型 id 是 seedream-5.0-lite、seedream-4.5、seedream-4.0；当前图片接口只支持单次一个图片任务，也就是 n=1，但会收集这一任务返回的整组新图片。
  • 当前 Doubao 视频公开支持的模型 id 是 seedance-2.0，并兼容 seedance / seedance-2 / seedance2 等别名；当前视频接口只支持单次一个视频任务，也就是 n=1。
  • Doubao 图片接口支持 1:1、2:3、3:4、4:3、9:16、16:9 比例，以及页面可见风格标签；图片生成默认超时是 600s。
  • Doubao 视频生成默认 watchdog 参数是 3600s；请求也可以单独传 timeout_sec 覆盖，但该参数不再作为最终成片总等待上限，而是用于提交阶段保护和页面失联保护。
  • Doubao 会在发送请求后轮询新的聊天消息和媒体卡片，记录排队状态、提交确认文本、完成文本，并优先抓取新的可播放视频；如果结果落在左侧历史线程里而不是当前新对话页，服务会切到新线程继续抓取。
  • Doubao 视频导出会优先尝试分享链路：自动提取分享 URL 或 share_id + video_id，调用 POST /creativity/share/get_video_share_info 下载分享页视频；只有拿不到分享信息时才回退到聊天页 <video> 直存或预览下载。
  • Doubao 管理页的视频测试不再直接挂住一个长 HTTP 请求等最终结果，而是先创建后台视频任务，再轮询 /providers/doubao/video-jobs/{job_id} 读取进度和结果；只要页面保持可检查状态，就允许豆包长时间排队或生成。
  • Doubao 图片生成会切到聊天页图像生成模式后再提交请求；如果在等待窗口内没有匹配到 我将为你生成...图片 的确认文案且也没有拿到最终图片，服务会把这次调用标记为疑似达到当日图片上限。
  • Doubao 会从聊天页可见状态文本里读取并缓存“本次消耗”“今日剩余”“预计等待时间”“实际使用模型文案”等字段；如果今天额度已知且为 0，服务会在真正提交前拒绝本次请求；如果视频调用命中“额度不足 / 已用完 / 明天再试”等限制反馈，服务会直接把当天该缓存的剩余额度写成 0。
  • 当前已提供 provider-scoped 管理页入口 /providers/flow/ui、/providers/doubao/ui 和 /providers/dyks/ui；构建后的 React 页面统一挂到 /ui/，并通过 ?tab=<provider> 直达对应标签页。共享页当前还提供 ?tab=guide 的使用说明标签页，汇总对外使用方式、登录流程、常用入口和最小请求示例。Flow 和 Doubao 支持浏览器缓存管理、测试 API 和按日 / 周 / 月聚合的监控数据；Dyks 当前支持浏览器缓存管理、商品目录统计、单商品 schema 和购买前表单预填写，但还没有稳定的 usage 监控面板。
  • Ubuntu 服务器当前通过根 Nginx 暴露受保护入口：/ui/、/providers/、/docs、/openapi.json、/redoc 和 /desktop/
  • Ubuntu 服务器当前还额外通过 api-proxy-session-check.timer 每天 03:15 固定巡检一次所有启用的 Flow / Doubao 浏览器缓存登录态；它只做 session/check，不自动发起重新登录
  • 服务器上的浏览器可见登录当前已经验证过 Flow 和 Doubao 两条链路：session/init 会把真实 Chromium 窗口拉到 Xvfb 桌面；这个桌面可以通过共享管理页里的远程桌面面板在需要时手动连接，也可以通过单独的 /desktop/ 页面呈现；共享页默认不再自动连接，避免一打开 /ui/ 就直接看到残留登录窗口；如果 session/init 成功返回 logged_in=true，共享页会自动断开当前嵌入式桌面连接
  • 远程桌面当前通过 autocutsel 同步 VNC cutbuffer、X11 CLIPBOARD 和 PRIMARY selection，目标是让 Windows 复制的文本更稳定地粘贴到服务器里的网页输入框
  • 当前图片和视频接口都支持通过 reference_images 传参考图；每个条目支持结构化对象 file_path / image_url / b64_json + filename，最多 10 张；服务会先物化成本地文件，再切到豆包参考图选项卡上传。
  • 当前 Doubao 管理页测试面板只保留本地参考图文件选择；前端会把文件转成 b64_json + filename 发给后端。
  • 当前监控聚合接口是 /providers/flow/usage/summary。
  • 当前 Doubao 监控聚合接口是 /providers/doubao/usage/summary。
  • Dyks 当前没有稳定对外的监控聚合接口；但已经有 provider-scoped 管理页入口 /providers/dyks/ui，会在前端已构建时跳到共享 React 管理页的 Dyks tab。已验证可运行的 provider-scoped API 目前是健康检查、账号管理、session 检查 / 初始化、topup 页面打开接口、商品目录统计接口、单商品 schema 接口、商品购买页打开接口，以及购买前表单预填写接口。
  • Dyks 目标站点当前首页在未登录时会落到 #/login；账号密码登录成功后，前端会把 ACCESS_TOKEN 和 user 写入 localStorage，随后 /api/userInfo?Switch=4 等接口通过 Authorization: Bearer <ACCESS_TOKEN> 头访问
  • Dyks 目标站点当前仍存在一些公开可读的基础接口，例如 /api/getSys、/admin/getSiteName、/common/getSettings、/api/ggList?IsTan=1；它们更适合用于页面结构和站点配置探测，不代表业务接口可免登录调用
  • Dyks 商品目录当前优先通过 /api/goodsList 获取；站点 id 当前优先通过 localStorage.setting.system.Id 或 /api/getSys 获取，而不是使用用户快照里的 AdminId
  • Dyks 商品表单结构当前优先通过 goodsList 返回的 ParamsTemplate 获取，再用商品页真实可见 DOM 控件补齐占位符、输入类型、下拉选项和数量范围；目录总数会随站点实时变化
  • Dyks 页面里曾观察到“游客登录”入口，但该链路不应视为稳定登录初始化方案；探测时对应的 POST /api/login 也可能直接返回账号或密码错误

当前限制：

  • 必须依赖真实 Google 登录态。
  • Flow 前端 DOM 不是稳定公开接口，选择器可能失效。
  • Dyks 当前不再要求“先有缓存登录态”才能初始化；推荐链路是用账号密码完成 session/init，再复用持久化缓存去访问余额、商品目录、充值页和商品购买页。
  • Dyks 前端 DOM 不是稳定公开接口，选择器可能失效。
  • Dyks 站点主前端资源当前是压缩后的 bundle，静态字符串检索对路由和接口定位帮助有限，实际调试更适合结合浏览器网络面板和运行时 DOM。
  • 当前目录仍然是 test/ 下的独立实验，不接入根目录 data/ / cache/ 规范，也不自动并入 app/。
  • 该模块定位是本地个人实验，不是正式多用户服务。

默认阅读顺序

收到与该模块相关的需求后，默认按以下顺序进入：

  1. 先读当前文件
  2. 再读 README.md
  3. 如果是 Windows 本地一键启动或依赖自举，读 run_local_windows.py
  4. 如果是容器级入口、共享异常、共享运行时，读 app.py、core/settings.py、core/errors.py
  5. 如果是 provider 层结构调整，读 providers/readme_for_ai.md
  6. 如果目标是 Flow provider，继续读 providers/flow/readme_for_ai.md
  7. 如果目标是 Doubao provider，继续读 providers/doubao/readme_for_ai.md
  8. 如果目标是 Dyks provider，继续读 providers/dyks/readme_for_ai.md
  9. 如果目标是调用文档，读 api_doc/readme_for_ai.md

文档维护规则

出现下列情况时，必须更新当前文件：

  • api_proxy/ 的职责变化，不再只是浏览器 API 实验容器
  • 新增或废弃 provider
  • API 路由、入口文件或运行方式变化
  • 持久化目录、代理约定或 Playwright 浏览器目录变化
  • 共享运行时和 provider 的分层方式发生变化
  • 新增或修改 provider 时，没有同步更新 providers/ 和 api_doc/ 下的对应 AI 文档索引