AIStudio2API 使用 Go 直接调用 Google AI Studio 的 MakerSuite 私有协议,由 Vue 3 管理端展示账户、模型、冷却和请求状态。业务请求、流式解码、账户调度和公开协议适配都在 Go 进程内完成;默认的 SpiderMonkey 后端在服务进程内完成官方 WAA 初始化与 fresh proof 生成,WAA_BACKEND=camoufox 时这部分与界面运行的 GenerateContent 由 Camoufox 中的官网页面承担。
管理监听器、公开 API、账户池、协议运行时和内嵌 Vue 管理端位于同一进程。生成服务是可停止、可重新创建的公开 API 服务实例;原始 JSON+protobuf、WebChannel 与 WAA 格式见 protocol.md。
| 场景 | 必需组件 | 说明 |
|---|---|---|
| Release 运行 | aistudio2api |
需要时在后台自动下载 Camoufox,不需要 Python、Node.js 或 Playwright |
| 源码运行 | Go 1.27.3+、Node.js 22.18+、24.11+ 或 26+、配套 npm | Node.js 只用于构建 Vue 管理端 |
| Windows Chrome 导入 | Windows amd64、稳定版 Chrome | Go 程序直接读取本机 Profile 的 OAuth/DBSC 材料 |
Windows 用户解压发布包后双击 aistudio2api.exe。程序启动后自动打开管理页面,生成服务初始保持停止;账户登录、日志查看和生成服务启停均在该页面完成。
前端或 Go 源码变化需要重建时,先结束当前管理进程,再按下面“源码首次启动”的命令构建并运行。
发布包中的 Windows aistudio2api.exe、macOS AIStudio2API.app 与 Linux AppImage、deb 为桌面版:
- 启动时窗口先显示启动画面,管理服务就绪后打开管理页面
- 关闭窗口后程序在系统托盘继续运行:Windows 双击托盘图标显示窗口,Linux 单击托盘图标显示窗口,两者右键打开托盘菜单;macOS 单击菜单栏图标显示窗口、右键打开菜单,点 Dock 图标或从“应用程序”再次打开时显示窗口;菜单可以显示窗口、在浏览器中打开管理页面、开关开机自启动或退出
- 再次启动时唤回已运行实例的窗口;
-open-ui=false启动时只显示托盘图标 - 页面中的外部链接用系统浏览器打开;拖入窗口的链接与文件由页面中的上传区接收,其余位置的拖放被取消,窗口停留在管理页面
- 数据目录:Windows 为可执行文件所在目录,macOS 为
~/Library/Application Support/AIStudio2API/,Linux 为~/.config/AIStudio2API/(设置XDG_CONFIG_HOME时为其中的AIStudio2API/);.env、auth/与runtime/都在数据目录中 - Windows 桌面版以
cmd /c start /wait aistudio2api.exe setup的形式运行命令时在该控制台中输入输出,命令行等程序结束后返回 - Windows 在替换运行中的输出文件时可能留下
aistudio2api.exe~,它是旧进程占用目标文件期间产生的构建副本
源码首次启动:
cd web
npm ci
npm run build
cd ..
go run ./cmd/aistudio2api管理页面“账户”页的“添加账户”菜单提供从 Chrome 导入、粘贴 Cookie、从指纹浏览器导入、浏览器登录和远程添加,也可以重新登录、立即刷新、编辑、启停和删除账户。浏览器登录会在隔离 Camoufox 中完成并自动读取邮箱。启停账户保存后立即返回,停用后等待在途请求结束并关闭 Worker、启用后载入页面同步模型目录,都在后台完成。
浏览器登录与重新登录的显示方式由服务端按请求决定:
- Linux 上
DISPLAY与WAYLAND_DISPLAY都为空,或管理请求来自非回环地址、带Forwarded或X-Forwarded-For头时,使用管理页面登录窗口 - 其余情况在本机打开可见 Camoufox 窗口
管理页面为每次登录生成随机 ID,在 POST /api/accounts 或 POST /api/accounts/{id}/login 的 body 中以 view 带上该 ID,同时连接 GET /api/login-view/{ID} 的 WebSocket,两者在服务端取得同一个登录窗口。使用登录窗口时:
- 隔离 Camoufox 以无头方式启动,Linux 没有
DISPLAY时使用服务启动的 Xvfb,页面保持 Firefox 默认刷新帧率;导航 AI Studio 后立即返回,登录窗口显示载入过程 - 登录窗口连接期间,服务端经 WebDriver BiDi
browsingContext.captureScreenshot以 JPEG(质量 0.8)截取最后打开且仍存在的顶层页面,间隔不短于 100 ms,只推送与上一帧不同的画面;每帧先发 JSON 元数据(页面 context、URL、标题、CSS 视口宽高与 devicePixelRatio),再发 JPEG 二进制。弹窗关闭后画面回到原页面 - 管理页面把鼠标移动、按下与抬起、滚轮、按键按下与抬起和粘贴文本经同一连接发回,附带画面所属页面;服务端按到达顺序合并成
input.performActions:指针为 mouse,滚轮为 wheel,KeyboardEvent.key的命名键映射为 WebDriver 键码点,粘贴文本逐字符按下与抬起;页面已关闭的输入丢弃,输入内容不写日志 - 会话以
unhandledPromptBehavior让 alert、confirm 与 prompt 保持打开,browsingContext.userPromptOpened时登录窗口显示对话框,用户的选择以browsingContext.handleUserPrompt不经命令锁发送,打开对话框的输入命令随之返回 - 关闭登录窗口时管理页面中止登录请求,请求取消后服务端结束 Camoufox 并删除 profile 与隔离登录目录
登录期间登录用的 Camoufox 退出时,登录以以下错误结束:
- 浏览器以退出码 0 正常退出(关闭了 Camoufox 登录窗口):
登录窗口已关闭,登录没有完成 - 浏览器以其他退出码退出:
登录浏览器意外退出: Camoufox 已退出,退出码 <退出码>,并附 Camoufox 最近的输出;退出码的含义见 Camoufox 后端
setup 提供以下五种命令行导入入口:
| 入口 | 命令 | 适用场景 |
|---|---|---|
| 扫描本机 Chrome | aistudio2api setup |
交互选择可导入 Profile |
| 指定 Chrome 账户 | aistudio2api setup --profile <PROFILE> 或重复使用 --email |
批量、确定性导入 |
| 隔离登录 | aistudio2api setup --login |
可见 Camoufox 中手动完成 Google 登录,需要图形界面,没有图形界面时报错并指向管理页面的浏览器登录 |
| 文件导入 | aistudio2api setup --storage-state <file> |
导入 Playwright storage state 结构 |
| Cookie 导入 | aistudio2api setup --cookie-file <file>、--cookie <Cookie 请求头> 或 --cdp <调试地址>,账户邮箱按 Cookie 识别 |
导入浏览器扩展导出的 Cookie JSON、Netscape cookies.txt、一行 Cookie 请求头,或经远程调试地址读取指纹浏览器与 Chromium 中的 Cookie |
setup 还接受以下参数:
| 参数 | 作用 |
|---|---|
--chrome-root <DIR> |
指定 Chrome User Data 根目录 |
--proxy <URL> |
固定到账户初始化、WAA 与业务请求 |
--locale <LOCALE> |
设置账户语言,省略时按出口位置 |
--timezone <IANA_ZONE> |
设置账户时区,省略时按出口位置 |
--remote <origin> |
账户上传到该远程实例,非本机地址必须使用 HTTPS |
--token <TOKEN> |
远程实例的配对令牌,省略时从标准输入读取 |
--renew |
在前台为本机上传到 --remote 实例的 Chrome 导入账户按时续签,用于重启电脑后恢复续签;不带 --token 与导入参数 |
setup 的导入模式:
- 文件导入:
--storage-state - Cookie 导入:
--cookie、--cookie-file或--cdp,账户邮箱按 Cookie 识别,也可用一个--email指定;--authuser N选择 Cookie 中第 N 个 Google 会话(官网/u/N/)的账户并验证其邮箱;只保留 google.com 及其子域的 Cookie,缺少__Secure-1PSID、SAPISID、__Secure-1PAPISID或__Secure-3PAPISID时报告缺少的 Cookie --cdp接受host:port、HTTP 调试地址或浏览器级ws://地址,经 CDPStorage.getCookies读取该浏览器的全部未分区 Cookie- 管理页面导入 Cookie 只需粘贴 Cookie 或选择 Cookie 文件:页面在粘贴或输入停顿后自动识别,服务以 Cookie 打开 AI Studio 对话页,从页面全局数据
oPEP7c读取登录账户邮箱,再读取ListModels确认可用;页面转到登录页时返回signed_out - 管理页面的添加、导入与重新登录在服务端的账户任务中运行(
internal/api/account_tasks.go):请求返回 202 与任务后对话框即关闭,任务在请求结束后继续运行,逐个处理账户并把每个账户的状态、当前步骤、错误码与原因推送到管理事件流的account_tasks,账户页据此显示任务行;浏览器登录任务带登录窗口 ID,页内登录窗口隐藏或页面刷新后以同一 ID 重新连接 - “从指纹浏览器导入”从本机进程命令行找出带
--remote-debugging-port的浏览器(端口为 0 时读取用户数据目录的DevToolsActivePort),逐个读取 Cookie 并识别账户,列出可导入、已导入与未登录的浏览器 - 隔离登录:
--login - 浏览器导入:Chrome 导入参数
setup 写入本机时要求 AISTUDIO_AUTH_STATES 指向一个账户目录。
加 --remote 时,导入在本机完成,结果上传到远程实例:
- Chrome 导入、隔离登录、文件导入与 Cookie 导入照常在本机完成,结果凭远程实例账户页“远程添加”生成的配对令牌逐个上传;隔离登录同时上传 Camoufox 指纹
- 远程账户使用远程实例的默认代理,
--proxy只用于本机导入与登录 - 只含隔离登录、文件或 Cookie 导入的账户时,上传后命令退出
上传的账户带 Chrome OAuth 材料时(本机 Chrome 导入,或带该材料的认证状态文件),上传完成后命令留在前台为远程账户续签:
- 立即并每 100 分钟以本机 Chrome 来源与 OAuth 材料签发新会话,经
PUT /api/pairing/accounts/{account}/cookies凭上传响应的renewal_token替换远程账户的 Cookie,每次输出一行日志 - 失败时 5 分钟后重试,重试时沿用尚未送达、签发不到 100 分钟的会话
- 远程返回 401
pairing_renewal_invalid或 404account_not_found时停止该账户的续签并从记录中删除,其他失败照常重试 - 续签材料与凭据保存在本机
runtime/remote-renewals.json(权限 0600);--remote <origin> --renew读取该 origin 的记录恢复续签
setup 的代理与账户环境:
--proxy会同时固定到新账户的初始化、WAA 与业务请求,接受 HTTP、HTTPS 或 SOCKS5 URL,代理认证写在 URL 的user:password@部分;未指定时导入与登录使用PROXY中的第一个代理,新账户不设账户代理--locale和--timezone设置账户环境;未指定的项按 setup 出口(--proxy,未指定时为PROXY中的第一个代理或直连)的地理位置填写,命令输出出口 IP、国家与采用的语言和时区;--remote上传的账户由远程实例按它的出口填写
Camoufox 按以下顺序定位,只使用发行目录 application.ini 中 Version 与程序固定版本相同的 Camoufox:
- 进程环境变量
CAMOUFOX_PATH,版本不符时报告实际版本 runtime/camoufox/- 可执行文件旁的同名目录
- Windows 本机 Camoufox 缓存
版本不符的候选被跳过。都没有时自动下载当前平台的固定版本:
- 连接中断、停滞(连续 30 秒没有收到数据)或服务端返回 5xx 时,依次等 1、2、4、8 秒后从断点续传,共尝试 5 次
- 下载失败时,错误给出发行包地址与
runtime/camoufox/的绝对路径;手动下载并解压到该目录后,之后的启动直接使用它
各平台发行包的字体:
- Windows 发行包的
fonts目录只带 Firefox 自带的 Twemoji,页面使用系统字体 - Linux 与 macOS 发行包带 Windows 指纹读取的字体分组,Linux 上服务按其中的
groups.json生成 fontconfig
Camoufox 启动失败时的错误:
- Camoufox 在报告 WebDriver BiDi 端点前退出时,错误为
Camoufox 在报告 BiDi 端点前退出,退出码 <退出码>,最近的输出:加 Camoufox 最后 20 行输出,没有输出时只写退出码;退出码的格式与运行中退出相同(见下文) - 输出含
cannot open shared object file时,错误只写明退出码与ldd查到的 Camoufox 及其依赖库缺少的全部系统库;Debian 系发行版另附安装这些库与 Xvfb 的apt-get satisfy命令 - 没有
DISPLAY且找不到 Xvfb 时,错误同样附上该命令
日常启动只需运行二进制或 Go 入口,再从管理页面启动生成服务:
./aistudio2api.exe
go run ./cmd/aistudio2api --listen 127.0.0.1:2048 --open-ui日常服务入口接受以下参数:
| 参数 | 作用 | 默认来源 |
|---|---|---|
--auth <PATHS> |
覆盖本次进程使用的账户文件、目录或逗号分隔路径 | AISTUDIO_AUTH_STATES |
--listen <HOST:PORT> |
覆盖管理页面与 API 的监听地址 | LISTEN_ADDR |
--proxy <URL> |
覆盖每次新建生成服务实例使用的全局代理 | PROXY |
--open-ui |
启动后打开管理页面 | 无参数启动时为 true |
管理页面与 /api 控制面在生成服务停止时继续运行:
- 停止生成服务会取消活动生成请求并关闭 WAA worker;再次启动会重新读取账户模型目录
- 生成服务启动期间到达的公开 API 请求等启动结束再处理;已有公开目录时,模型列表与目录中已有模型的单模型查询直接返回,目录中还没有的模型等启动结束后再查
- 生成服务停止或启动失败时,公开 API 返回 503
service_stopped,错误信息说明在管理页面启动服务或开启自动启动 - 命令行版关闭启动窗口或按
Ctrl+C退出整个管理进程,桌面版从托盘菜单退出
cmd/aistudio2api/ 薄入口,只调用 internal/app 的 app.Run
internal/app/ 配置、账户装配、认证续签、信号、生成服务实例、调度和服务生命周期
internal/setup/ Chrome 导入、storage-state 导入、Cookie 导入与隔离登录命令
internal/aistudio/ 账户、MakerSuite、WAA、模型、工具、上传、媒体和规范事件
internal/api/ OpenAI、Responses、Anthropic、Gemini 与管理端 HTTP 路由
internal/camoufoxnative/ 原生 WebDriver BiDi、WAA 页面与隔离登录
internal/waa/ SpiderMonkey WAA:BotGuard VM、Firefox 形状宿主与 SpiderMonkey cgo 绑定
internal/imagecodec/ 生成图片的 JPEG 解码、CatmullRom 缩放、PNG 编码与经 cgo 链接 libwebp 的 WebP 编码
internal/resample/ 语音 PCM 的 Kaiser 窗 sinc 多相重采样
internal/proxydial/ 上游代理拨号与带认证代理的本机 SOCKS5 中转
internal/egress/ 经出口在线查询公网 IP、国家与时区,推出出口所在地的语言
internal/requestdb/ 请求用量账本与可选正文的 SQLite 存储
internal/statedb/ Responses 与 Interactions 续接节点的 SQLite 存储
internal/promptdb/ Playground 对话的 SQLite 存储
internal/sqlitedb/ SQLite 打开、按建表语句同步表结构与空闲页回收
internal/pricing/ 用量估算费用使用的 Gemini API 单价表
internal/chromeauth/ Windows Chrome OAuth/DBSC 发现、导入和续签
internal/config/ 全局配置的读取、校验和原子写回
internal/i18n/ 服务文案的翻译表、系统语言识别与控制台输出翻译
internal/webui/ 嵌入并提供 Vue 构建产物
internal/desktop/ 桌面版窗口、系统托盘、启动画面与 Wails 更新器接入
web/ Vue 3、TypeScript、Vite+ 和 Tailwind CSS 源码
docs/ 开发流程与私有协议说明
build/ 应用图标、Windows 资源、macOS Info.plist 与 Linux 打包配置
auth/ 每账户配置、认证状态和可恢复运行状态
runtime/camoufox/ Release 使用的 Camoufox 运行时
runtime/requests.db 请求用量账本与可选正文
runtime/states.db Responses、Interactions 与 Chat 音频回复的续接节点
runtime/prompts.db Playground 对话
runtime/media/ MEDIA_OUTPUT=url 时按内容命名保存的生成媒体,总量超过 1 GB 时删除最久未使用的文件
主依赖方向:
cmd/aistudio2api
-> internal/app
-> internal/api
-> internal/aistudio
-> internal/setup
-> internal/camoufoxnative
-> internal/config
-> internal/webui
internal/setup
-> internal/aistudio
-> internal/camoufoxnative
-> internal/chromeauth
-> internal/config
请求链保持单向:
HTTP route
-> client protocol decoder
-> canonical request
-> capability-aware account lease
-> AI Studio array encoder
-> per-account WAA proof
-> GenerateContent transport
spidermonkey (default): Go HTTP via account egress, Firefox headers and account Cookie
camoufox: XMLHttpRequest sent by the fingerprinted page, response pushed via WebDriver BiDi
-> incremental response decoder
-> canonical events
-> client protocol response
WebSocket 入口沿用相同分层:internal/api 解码公开协议,internal/app 绑定账户和运行状态,internal/aistudio 执行 WebChannel 与规范事件转换。公开适配器只消费规范请求与事件;账户文件、WAA 对象、原始数组和资源粘性由 internal/aistudio 与 internal/app 管理。
Camoufox 由 Go 通过 WebDriver BiDi 直接管理。启动数据面时,服务按 WARM_WORKER_LIMIT 逐个准备隔离、无头、长驻的账户 runtime,并在需要其他账户能力时替换最久未用的空闲 runtime。
无头 runtime 的刷新帧率与绘制:
- 软件 vsync 为每秒 60 次;浏览器启动与首次载入官网页面期间,页面每秒刷新 60 帧
- Worker 就绪后,
gfx.display.frame-rate-divisor设为 60,每 60 次 vsync 分发一次,页面每秒刷新 1 帧;同时服务经 WebDriver BiDi 访问浏览器界面层(Camoufox 以MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1启动),把标签页的renderLayers设为 false,标签页停止光栅化与合成,页面的可见状态、焦点、动画帧与定时器照常 - 界面运行的输入、点击与新开对话期间,分频设为 1、
renderLayers设为 true,页面从下一次 vsync 起每秒刷新 60 帧;全部界面操作结束后恢复每秒 1 帧并停止绘制 - WebRender 以单通道灰度光栅化字形;Windows 上定时器线程在最早的定时器到期时唤醒
- Worker 就绪 2 秒后与最后一次界面操作 5 分钟后,服务发出
memory-pressure,各进程回收 GC 堆与渲染缓存
各主机按账户指纹呈现 Windows 版 Firefox:
- WebGL 在所有主机上强制启用,取账户指纹中的 Windows 显卡配置;语音列表在所有主机上只含账户指纹中的语音
- 非 Windows 主机上,Camoufox 按 Windows 版 Firefox 的字体偏好解析字体名,字体白名单补入已声明字体所在字体文件的其他字体族名
- 非 Windows 主机上启用 WebGPU、Windows 10 滚动条样式与 2 声道 48 kHz 的 AudioContext,
prefers-reduced-motion为no-preference,站点存储的全局上限固定为 50 GiB;指纹没有window.innerHeight时取window.outerHeight减 Windows 浏览器界面高度 85 - 非 Windows 主机无头运行时,服务经 WebDriver BiDi 移动主窗口,使页面内容区的屏幕坐标与 Windows 版一致
- Linux 上 Camoufox 只加载发行包内的 Windows 字体(字形微调为
hintslight),按 Windows 字体替换表解析字体名 - macOS 上服务在启动 Camoufox 前把 Windows 字体替换名写入发行包字体的 name 表,并给这些字体的 PostScript 名加
-Windows后缀,与系统同名字体区分;快捷键修饰键为 Control - 没有
DISPLAY的 Linux 主机上,每个无头 Camoufox 使用服务启动的 Xvfb 虚拟显示,WebGL 经 Mesa GLX 软件渲染,Camoufox 退出时一并结束该 Xvfb
profile、缓存与进程:
- 每个 runtime 使用关闭时删除的临时 profile;创建临时 profile 的进程在 profile 内持有锁文件,运行时装配时删除锁已释放的遗留 profile
- HTTP 磁盘缓存写入账户目录的
camoufox-cache/,同一账户重启时复用官网静态资源;同一账户同时存在的第二个 runtime 使用临时 profile 内的缓存;账户缓存由后台关闭中的旧 Worker 占用时,新 runtime 在载入页面前等它释放 - Windows 上每个 Camoufox 进程树加入服务进程持有的 Job,服务进程退出时由系统一并结束
每个 runtime 以临时对话打开官网新对话页 /prompts/new_chat?model=<模型>&temporary=true:
- 页面脚本之前注入的预载脚本取得官网应用的 WAA service 对象
- 页面发出的 MakerSuite 请求提供动态请求头,
GetLoggingContext响应提供X-Goog-Ext-519733851-Bin
最后一轮是带文本的 user 轮次,或是回应页面最后一轮函数调用的函数结果时,GenerateContent 在页面界面运行:
- 服务先关闭页面上出现的已知弹层:欢迎对话框、引导浏览浮层与 Cookie 提示条
- 文本轮次:输入框没有焦点时,服务先以可信指针点击输入框(官网新开对话后焦点已在输入框中);再把该轮各文本 Part 以空格连接的文本开头写入剪贴板,以可信键盘按 Ctrl+V 粘贴到输入框,最后以可信指针点击 Run。写入的开头最多 25000 个 UTF-16 码元,与官网把更长的粘贴转为文本附件的长度相同
- 文本含官网粘贴时转为附件的 Google 文档、云端硬盘、YouTube 或 Figma 链接时按 Ctrl+Shift+V,官网按住 Shift 的粘贴保留原文
- 函数结果:在最后一轮是该函数调用的标签页上,服务把函数结果粘贴到函数调用块中并提交
- 页面应用生成 proof 并创建 GenerateContent 的
XMLHttpRequest,发送时正文换成 Go 编码的业务正文与这份 proof;响应头与响应块由页面经 WebDriver BiDiscript.message通道推送给 Go - 服务从页面发出这个请求起等待响应,页面仍在处理 Run 点击时也是如此
- 随后的 CountTokens 与统计上报由页面应用发出
- 请求取消时点击 Stop;取消在两次界面操作之间生效
一轮结束后标签页上的对话:
- 一轮返回 200、响应正文读完且回答不是函数调用时,服务在后台点击 New chat 并丢弃该对话(临时对话中新开的对话仍是临时对话),下一轮在空白对话中直接输入,期间到达的请求等待该标签页
- 回答是函数调用时,标签页留在当前对话等待函数结果
- 上游返回 200 以外的状态时,下一轮在当前对话中直接输入
- 其余情况下标签页保留该对话:下一轮与上一轮的对话相同时点击该轮的 Rerun,在其后追加 model 与 user 两轮时在当前对话中继续,其余对话先点击 New chat 并丢弃当前对话
- 同一账户同时进行的界面请求各用一个标签页;全部标签页都在运行对话时,服务在后台新建标签页并载入官网页面,同时等已有标签页空出,先到哪个用哪个
其余受保护请求的正文由 Go 编码,proof 由 WAA service 生成,通过同一固定指纹页面以官网同样的 XMLHttpRequest 发送,响应同样经 script.message 推送给 Go。其中 GenerateContent 带官网点击 Run 时的 Priority: u=0,页面在一次可信 Pause 按键的处理中发出它。
WebDriver BiDi 命令在同一连接上并发执行:
- 每条命令带唯一 ID,后台读取连接的 goroutine 按 ID 把响应交给等待的调用方
- 单条命令最长 150 秒
- 请求取消或超时时调用立即返回,迟到的响应被丢弃,其他命令照常执行
Camoufox 运行中与服务的 WebDriver BiDi 连接断开时,服务最多等 5 秒看浏览器进程是否退出,等待中的命令与请求、连接断开后新发的命令都以同一个错误结束:
- 进程已退出:错误为
Camoufox 已退出,退出码 <退出码>,最近的输出:加 Camoufox 最近 20 行输出,没有输出时只写退出码;网页脚本的控制台消息(JavaScript warning: https://…这类行)不计入 - 进程仍在运行:错误为
BiDi 连接已断开: <原因> - Windows 上退出码以十六进制显示,如
0xC0000409为浏览器崩溃;浏览器进程被其他程序强制结束时退出码由该程序决定,taskkill /F为0x00000001,PowerShellStop-Process为0xFFFFFFFF;其他系统为十进制退出码,进程被信号结束时为信号名
其他 MakerSuite、Drive 与媒体控制面请求使用账户固定出口的 Go HTTP transport。
WAA_BACKEND=spidermonkey 时 WAA 全部在服务进程内完成,生成服务不需要 Camoufox;账户页的浏览器登录在首次使用时准备 Camoufox。每个账户 runtime 依次:
- 在服务进程内请求官网页面、页面 HTML 引用的样式表与脚本、网站图标与 Cloud Console 认证预热 iframe
- 请求
GetLoggingContext得到公开请求头 - 调用
Waa/Create取得 challenge,按 hash 下载解释器并缓存到auth/.waa-interpreters/ - 在
internal/waa链接的 SpiderMonkey 与 Firefox 形状宿主中执行 program;program 插入的 iframe 由宿主以 Firefox iframe 导航请求
运行中:
- 页面子资源与解释器按 Firefox HTTP 缓存的新鲜度与条件请求规则发送,缓存元数据写入账户目录的
spidermonkey-cache.json - 带页面提示词的 GenerateContent 先在宿主页面的输入框填入提示词并点击 Run,再生成 proof
- 受保护请求携带 Firefox 请求头与账户 Cookie,由账户固定出口的 Go HTTP transport 发送,响应 Cookie 写回账户状态
程序从当前目录读取可选的 .env,进程环境变量覆盖同名配置,这些项在设置页中显示为由环境变量决定、不可修改。管理端保存设置时 .env 写入 WAA 后端与其余和默认值不同的项;取值无效的项按默认值运行,管理页面顶部与服务日志列出这些项与原值:
| 变量 | 作用 | 默认值 |
|---|---|---|
AISTUDIO_AUTH_STATES |
账户文件、目录或逗号分隔的多个路径 | auth |
LISTEN_ADDR |
管理页面与 API 的监听地址 | 127.0.0.1:2048 |
PREVIEW_LISTEN_ADDR |
API 试用页 HTML 预览来源的监听地址 | 127.0.0.1:2050 |
PROXY_API_KEY |
公开 API 访问密钥 | 空 |
API_KEY_ACCOUNTS |
各 API key 可用的账户 | 空 |
AUTO_START |
管理服务就绪后自动启动生成服务 | false |
HIDE_DOCK_ICON |
macOS 桌面版隐藏 Dock 图标 | false |
REQUEST_BODY_LOG |
保存公开 API 的请求与响应正文 | false |
LOG_FILE |
服务日志同时写入文件 | true |
LOG_MAX_TOTAL_MB |
日志目录总量上限(MB) | 500 |
ADMIN_AUTH_ENABLED |
管理员账号密码登录开关 | false |
ADMIN_USERNAME |
管理员账号 | admin |
ADMIN_PASSWORD |
管理员密码 | 空 |
PROXY |
全局出口代理或代理池 | 空 |
INIT_TIMEOUT |
单账户初始化超时 | 2m |
REQUEST_TIMEOUT |
单次请求最大执行时间 | 30m |
WARM_WORKER_LIMIT |
常驻预热账户数 | 10,Camoufox 后端 5 |
MAX_ACTIVE_WORKERS |
活动 Worker 容量上限 | 20,Camoufox 后端 10 |
WARM_STARTUP_CONCURRENCY |
同时冷启动的 Camoufox Worker 数 | 5 |
PER_ACCOUNT_CONCURRENCY |
单账号同时执行的请求数 | 2 |
ROUTING_STRATEGY |
账户选择策略 | round-robin |
ACCOUNT_ORDER |
fill-first 的账户顺序 |
空 |
MAX_ACCOUNT_SWITCHES |
非额度失败的换号次数上限 | 3 |
UPSTREAM_CHANNELS |
生成请求的上游通道 | playground |
MODEL_MAPPING |
模型别名映射 | 空 |
MODEL_CHANNELS |
按模型指定上游通道 | 空 |
MODEL_ACCOUNTS |
按模型限定可用账户 | 空 |
BUILD_NATIVE_NONSTREAM |
Build 非流式优先原生单次调用 | true |
NONSTREAM_KEEPALIVE |
非流式请求保活 | true |
FAKE_STREAM |
假流式输出 | false |
YOUTUBE_LINKS |
YouTube 链接作为视频发送 | false |
STRIP_THOUGHT_SIGNATURES |
去掉历史中的思考签名 | false |
SEARCH_MODEL_ALIASES |
提供 -search 型号 |
true |
DISCOVER_HIDDEN_MODELS |
探测官网隐藏模型 | false |
GOOGLE_SEARCH |
全模型启用 Google 搜索 | false |
CONTINUATION_REWRITE |
末尾 assistant 轮改写为续写 | true |
CONTINUATION_PROMPT |
续写提示词 | 内置英文续写句 |
FIRST_EVENT_HEDGE |
首字超时备用请求阈值 | off |
FIRST_EVENT_HEDGE_MODELS |
发起备用请求的模型 | gemini-4-argon |
WAA_BACKEND |
WAA 后端 | spidermonkey |
MEDIA_OUTPUT |
生成媒体的引用方式 | inline |
MEDIA_BASE_URL |
媒体 URL 的服务地址 | 空 |
各变量的取值与生效时机:
LISTEN_ADDR:HTTP 服务监听地址;端口被 Windows 保留(Hyper-V、WSL2 或 Docker 的 WinNAT 保留端口段)时改用其后第一个可监听的端口,管理页面顶部显示改用的地址PREVIEW_LISTEN_ADDR:只提供/shim.html;端口与LISTEN_ADDR不同,无法监听时改用同一主机上的空闲端口,实际地址为管理端配置中的active_preview_listen_addr;管理进程重启后生效PROXY_API_KEY:多个用逗号分隔API_KEY_ACCOUNTS:逗号分隔,每项以最后一个:分成PROXY_API_KEY中的 key 与以|分隔的账户 ID,该 key 的请求与文件上传只在这些账户中选号;未列出的 key 可用全部账户;只有PROXY_API_KEY中的 key 的项起作用;保存后立即生效,同时修改PROXY_API_KEY时,管理服务重启前仍被接受的 key 沿用原来的绑定AUTO_START:失败时记录ERROR日志,管理服务继续运行;账户与配置以外的原因失败时以 5 秒起、翻倍至 5 分钟的间隔重试,手动启动或停止后结束重试HIDE_DOCK_ICON:macOS 桌面版以 Accessory 激活策略启动,只显示菜单栏图标;设置页保存后管理页面向桌面壳发送dock:hide或dock:show,桌面壳在主线程切换激活策略REQUEST_BODY_LOG:保存 POST 请求与响应正文,各截断到 64 KiB,只保留最近 1000 条;保存后立即生效LOG_FILE:写入runtime/logs/aistudio2api.log,单文件 10 MB 轮转;保存后立即生效LOG_MAX_TOTAL_MB:超出时删除最旧的文件,不小于 20;保存后立即生效ADMIN_PASSWORD:开启登录时必填PROXY:setup 与未设置账户代理时使用的出口,多个代理用逗号分隔组成代理池;留空时生成服务使用系统代理REQUEST_TIMEOUT:自动续写的每一轮开始时重新计时MAX_ACTIVE_WORKERS:必须不小于热池目标WARM_STARTUP_CONCURRENCY:限制按需扩容时的冷启动数,预热逐个启动;WAA_BACKEND=spidermonkey时不限制ROUTING_STRATEGY:账户轮询round-robin或粘性优先fill-firstACCOUNT_ORDER:逗号分隔的账户 ID,fill-first依次使用并按此顺序预热,未列出的账户排在后面并按 ID 排序;保存后立即生效MAX_ACCOUNT_SWITCHES:一个请求因上游 401、403、404、5xx、连接断开等非额度失败换号的次数上限,0为不换号,额度失败不计入;保存后立即生效UPSTREAM_CHANNELS:playground、build(旧通道,上游已停用其生成),逗号分隔MODEL_MAPPING:逗号分隔,每项以最后一个:分成别名与模型 ID;保存后立即生效MODEL_CHANNELS:逗号分隔,每项以最后一个:分成模型 ID 与通道playground或build;保存后立即生效MODEL_ACCOUNTS:逗号分隔,每项以最后一个:分成模型 ID 与以|分隔的账户 ID,该模型的自动选号只在这些账户中进行并与API_KEY_ACCOUNTS取交集;指定账户与绑定文件的请求不受此限制;未列出的模型可用全部账户;保存后立即生效BUILD_NATIVE_NONSTREAM:启用 Build 通道时,非流式请求优先选择 Build 原生单次调用NONSTREAM_KEEPALIVE:非流式请求等待结果期间每 10 秒写出一个换行FAKE_STREAM:流式请求按非流式取得完整结果后再以流式输出YOUTUBE_LINKS:用户消息文本中的 YouTube 链接作为视频外部媒体发送STRIP_THOUGHT_SIGNATURES:发往上游前去掉对话历史中的思考签名,函数调用带skip_thought_signature_validator;保存后停止再启动生成服务生效SEARCH_MODEL_ALIASES:为支持搜索的模型提供-search型号,使用该型号时启用 Google 搜索;保存后立即作用于新请求DISCOVER_HIDDEN_MODELS:同步账户模型目录时读取账户页面载入的官网前端主程序,找出推荐模型页指向、ListModels没有列出的模型,经上游CountTokens确认可用后加入该账户目录;条目复制自同类已列出的推荐模型,ID 与名称为模型 ID 并带hidden: true;被ListModels列出后使用官方条目;保存后停止再启动生成服务生效GOOGLE_SEARCH:为 OpenAI、Anthropic、Gemini 与 Interactions 的生成请求启用 Google 搜索,包含普通型号与携带函数工具的请求;保存后立即作用于新请求CONTINUATION_REWRITE:以 assistant 轮结尾的请求在不支持原生续写的模型上改写为续写请求,规则见 协议规范;保存后停止再启动生成服务生效CONTINUATION_PROMPT:改写时与末尾 assistant 正文一起写入系统指令;键存在且为空时,末尾 assistant 正文作为最后一轮 user;保存后停止再启动生成服务生效FIRST_EVENT_HEDGE:off、auto(各模型与通道近 24 小时原请求首字等待的 p95)或正整数秒FIRST_EVENT_HEDGE_MODELS:模型 ID,逗号分隔WAA_BACKEND:spidermonkey或camoufox,其他取值按spidermonkey;未设置时,启动时按auth/确定后写入.env:已有账户而没有.waa-interpreters时为camoufox,否则为spidermonkeyMEDIA_OUTPUT:Chat Completions 与 Messages 正文中生成媒体的引用方式,inline或urlMEDIA_BASE_URL:http或https;留空时取请求的协议与 Host
取值规则:
LISTEN_ADDR与PREVIEW_LISTEN_ADDR使用host:port,端口范围为1..65535- 时长和容量字段必须为正值,
MAX_ACCOUNT_SWITCHES为非负整数 WARM_STARTUP_CONCURRENCY的有效范围为1..MAX_ACTIVE_WORKERS;没有设置WARM_WORKER_LIMIT或WARM_STARTUP_CONCURRENCY时取默认值且不超过MAX_ACTIVE_WORKERS- 全局代理 URL 使用
http、https或socks5的 origin 形状,可带user:password@认证信息 - 命令行
--auth与--proxy会覆盖每次启动生成服务时读取的保存值
GET /api/config 与 PUT /api/config 同时暴露保存值和当前生效值:
| 字段 | 语义 |
|---|---|
auth_states、proxy、init_timeout、request_timeout |
下一次启动生成服务时使用的保存值 |
warm_worker_limit、max_active_workers、warm_startup_concurrency、per_account_concurrency |
保存后立即作用于当前生成服务的容量参数 |
waa_backend、upstream_channels、build_native_nonstream |
下一次启动生成服务时使用的 WAA 与上游通道配置 |
nonstream_keepalive、fake_stream |
保存后立即作用于新请求的非流式保活与假流式设置 |
youtube_links |
下一次启动生成服务时使用的 YouTube 链接识别设置 |
search_model_aliases |
保存后立即作用于新请求与模型列表的搜索后缀型号开关 |
discover_hidden_models |
下一次启动生成服务时使用的官网隐藏模型探测开关 |
google_search |
保存后立即作用于新请求的全模型 Google 搜索开关 |
continuation_rewrite、continuation_prompt |
下一次启动生成服务时使用的末尾 assistant 轮改写开关与续写提示词 |
first_event_hedge、first_event_hedge_models |
下一次启动生成服务时使用的首字超时备用请求设置与模型 |
strip_thought_signatures |
下一次启动生成服务时使用的思考签名去除开关 |
routing_strategy、account_order |
保存后立即作用于账户选择的策略与 fill-first 顺序 |
max_account_switches |
保存后立即作用于换号判断的次数上限 |
api_key_accounts |
保存后立即作用于新请求的 API key 账户绑定 |
model_channels、model_accounts |
保存后立即作用于新请求的按模型通道与账户限定 |
media_output、media_base_url |
保存后立即作用于新请求的媒体引用方式与媒体服务地址 |
model_mapping |
保存后立即作用于新请求与模型列表的模型别名映射 |
auto_start |
下一次启动管理进程时是否自动启动生成服务 |
hide_dock_icon |
macOS 桌面版是否隐藏 Dock 图标,保存后立即生效 |
request_body_log |
保存后立即决定是否保存请求与响应正文 |
log_file、log_max_total_mb |
保存后立即开关日志文件并按新的总量上限轮转 |
admin_auth_enabled、admin_username、admin_password |
保存的管理登录配置;省略密码保留现值,密码只接受写入 |
admin_password_set |
是否已配置管理密码 |
listen_addr、proxy_api_key |
保存的管理监听配置 |
preview_listen_addr |
保存的 API 试用页预览来源监听地址,管理进程重启后生效 |
active_preview_listen_addr |
当前管理进程实际使用的预览来源地址 |
active_listen_addr、active_proxy_api_key |
当前管理进程固定使用的值 |
reserved_listen_addr |
被 Windows 保留而改用 active_listen_addr 的监听地址,没有改用时为空 |
active_proxy |
当前生成服务使用的出口,代理池为逗号分隔的全部代理,proxy 为空时为系统代理,没有系统代理时为空 |
proxy_pool |
当前生成服务的代理池:每个代理的地址、是否可用、绑定账户数、最近检测时间与最近错误 |
management_restart_required |
保存的监听地址、API key 或管理登录配置与当前管理进程不同 |
service_restart_required |
保存的生成服务配置与当前生成服务实例不同 |
environment |
取自进程环境变量、覆盖 .env 的配置键 |
invalid |
取值无效而按默认值运行的项,每项为 key、value 与 reason |
PROXY 含多个代理时组成代理池。账户出口的优先级为账户代理、代理池绑定、系统代理、直连。
分配:
- 启动生成服务时,在载入页面与预热 Worker 之前,先经每个代理建立到
aistudio.google.com:443的隧道检测(15 秒超时),检测失败的代理不参与分配 - 未设置账户代理的账户保留运行状态
proxy中仍可用的绑定,其余账户依次绑定到绑定账户最少的可用代理并写入运行状态 - 添加或导入账户时,登录使用该账户将绑定的代理
故障与改绑:
- 生成请求或 Worker 启动经代理出现网络错误时,错误累计到请求发出或 Worker 启动时账户绑定的代理,成功一次清零;网络错误包括 Go 传输层错误、页面
NetworkError,以及 Worker 载入 AI Studio 期间连不上代理 - 连续 3 次且存在其他可用代理时,该代理标为不可用,其账户改绑到其他可用代理,并在独占租约下按新出口重建请求头客户端与 Worker;只有一个代理时网络错误不改绑
- 代理池每 5 分钟重新检测全部代理:检测失败的代理标为不可用,每次检测后绑定在不可用代理上的账户改绑到可用代理,检测成功的代理重新参与新账户的分配
- 在管理端清空账户代理时,账户原有的代理池绑定不可用则先改绑到可用代理,再按新出口重建请求头客户端与 Worker
配置保存使用临时文件、Sync 和原子替换。保存后的生效时机:
- 监听地址、本地 API key 和管理登录配置由管理进程持有,进程重启后应用
- 换号次数上限作用于之后的换号判断
- 模型映射、非流式保活、假流式、搜索型号、全模型搜索、媒体输出方式与媒体服务地址在每个请求开始时读取,作用于新请求,进行中的请求沿用开始时的值
- 其余配置在停止并再次启动生成服务后应用
管理登录开启后,/api 使用独立的 HttpOnly、SameSite=Strict 会话 Cookie:
- 登录有效期为 12 小时;登录时勾选“30 天内保持登录”的会话有效期为 30 天,保存在
runtime/admin-sessions.json,管理进程重启后仍有效 - 退出登录撤销会话并结束它的管理 SSE 订阅
登录关闭时,管理 API 使用回环来源与回环 Host 校验。远程管理通过 HTTPS 反向代理,代理保留 Host 并设置 X-Forwarded-Proto: https。生成 API 的访问密钥独立配置。
生成服务启动顺序如下。源码中的 generation 表示一次 Stop/Start 创建的生成服务实例:
PUT /api/config
-> 校验并原子写入 .env
-> 返回 saved/active 差异
POST /api/control/stop
-> 取消 LAUNCHING、活动请求与后台扩容中的 Worker 启动
-> 等待模型目录刷新退出并关闭当前 Worker
-> 管理监听器继续提供 /api 与页面
POST /api/control/start
-> 完成当前已停止实例的清理
-> 重新读取 .env 并应用命令行 --auth/--proxy 覆盖
-> 创建并启用新的生成服务实例
-> 从账户目录的 catalog.json 建立模型目录
-> 有缓存目录:进入 RUNNING 并在后台预热 WAA Worker,首个 Worker 有结果后读取 enabled 且处于 ready、busy 或 cooldown 的账户中目录缓存缺失或最近一次同步已满 24 小时的账户的页面目录
-> 无缓存目录:同时读取全部 enabled 且处于 ready、busy 或 cooldown 的账户的页面目录,取得首个非空真实目录后进入 RUNNING 并在后台预热 WAA Worker
-> 可预热的账户全部处于冷却时,冷却结束后预热;首轮目录同步完成前预热失败时,同步完成后再预热一次,仍失败时记录 WARN 日志 `WAA Worker 预热失败`
-> 预热的首个 Worker 有结果之前到达的请求等待这个 Worker,指定账户的请求直接启动该账户的 Worker
-> 剩余目录同步与热池预热继续在后台运行
配置读取、校验、生成服务实例创建失败或启用前取消时,当前已停止实例保持不变。切换到新实例后启动失败时,该实例进入 STOPPED,管理端返回结构化错误。
模型目录缓存与预热:
- 账户的 ListModels 响应与 Build 模型目录在每次成功刷新后写入账户目录的
catalog.json;载入账户时只采用目录指纹与runtime-state.json一致的缓存,新的生成服务实例用上次同步的目录立即预热,请求编码所需的模型条目也从缓存恢复 catalog.json同时记录同步时刻;启动时只在后台刷新没有一致缓存或最近一次同步已满 24 小时的账户,其余账户沿用缓存,由每 24 小时的巡检刷新- 预热逐个启动账户的 Worker:候选账户的目录就绪后启动,上一个 Worker 启动结束后再启动下一个
模型目录刷新与当前生成服务共用 context(Go 取消信号)。启动失败、取消或 Stop 后等待刷新退出的上界为 2 秒;未完成的 lifecycle transition(启动或停止操作)最多等待 12 秒。超时与 Worker 清理错误通过 errors.Join 保留在同一错误链中。
每个账户目录包含:
| 文件 | 内容 | 生命周期 |
|---|---|---|
account.json |
label、enabled、proxy、locale、timezone、auth_user | 创建或编辑账户时写入 |
storage-state.json |
Cookie、localStorage 与可选 Chrome OAuth/DBSC 续签材料 | 合并 Set-Cookie、DBSC 刷新或认证续签后原子写回 |
camoufox-fingerprint.json |
账户固定的浏览器指纹、语言、时区与点击和粘贴的事件节奏 | 首次运行生成,空值、窗口几何与字体按 Camoufox 官方启动器规则规范化,语音、WebGL 与媒体设备按真实 Windows 用户的分布生成,事件节奏按官网页面上可信点击与粘贴的事件间隔分布生成;重新登录和 WAA runtime 继续复用 |
runtime-state.json |
权益等级、模型资格、冷却与资源账户绑定 | 权益同步、首次模型结果或资源变化后原子写回 |
catalog.json |
最近一次同步的 ListModels 响应、Build 模型目录、官网隐藏模型与同步时刻 | 每次目录刷新成功后原子写回 |
camoufox-cache/ |
该账户 Camoufox 的 HTTP 磁盘缓存(上限 32 MB,JS 字节码以 zlib 压缩存放)与 Firefox 启动缓存 | WAA runtime 运行期间独占写入,随账户目录删除 |
载入账户时,缺少 account.json 或 storage-state.json、或这两个文件与 runtime-state.json 无法读取解析的账户目录被跳过,其余账户照常载入;服务日志记下该目录与原因,管理端账户列表把它列为不可用、原因写明出错的文件,删除它即删除该目录。
runtime-state.json 的字段:
| 字段 | value |
|---|---|
benefit_tier |
账户权益:0 Free、1 Pro、2 Ultra、3 Plus |
catalog_fingerprint |
目录指纹,与 catalog.json 一致时采用目录缓存 |
model_access |
{state,checked_at,reason?},成功状态为 verified |
cooldowns |
{until,reason?,level?,fallback?,rejected_size?,rejected_until?,rejected_level?} |
resources |
{kind?,name?,mime?,size?,purpose?,created_at,video?,alias?,sha256?,video_duration?,used_at?,display_name?,expires_at?} |
proxy |
从 PROXY 代理池分配给账户的代理 |
restricted |
Google 拒绝账户使用 AI Studio 的原因与跳转页 |
assistant |
Build 写代码助手的应用与续接位置,见 Build 通道 |
- Drive file、视频任务、视频产物和 Bidi 恢复 token 均保持创建账户粘性
- 视频任务额外保存公开 video object 的 model、seconds、size 与 UTC 创建时间,生成服务或进程重启后的轮询继续投影相同字段
活动请求锁保护跨进程账户租约,短事务锁保护 runtime-state.json 合并写回。短事务锁位于 auth/.leases/<账户>.runtime.lock,以 25ms 间隔等到锁释放;取得锁后重读磁盘状态,只修改目标字段,原子替换文件,再同步内存与资源索引。取租约时同样在锁内读取所选账户的文件,内容与上次同步或写入时相同则沿用内存状态。接收 context 的资源事务会在取消或 deadline 到达时提前返回。
账户更新以 account.json 原子写入为持久提交点。internal/app 先准备 pending(尚未提交)的固定出口,关闭旧 Worker并锁定该账户的 Worker 配置,再调用 AccountLease.SaveConfig;保存成功后依次提交 Worker 配置与固定出口。准备、关闭或保存失败时丢弃 pending 更新;保存后的租约释放错误原样返回,已发布配置继续生效。
账户调度先按每个账户实时 ListModels 返回的模型和方法筛选,再选择已经就绪且有并发槽位的 Worker。
选号顺序:
ROUTING_STRATEGY=round-robin在每个模型的候选账户间轮询,按上次选中的账户 ID 继续fill-first持续使用ACCOUNT_ORDER顺序(未列出的账户在后并按 ID 排序)中的首个可用账户,并在并发槽位用满、冷却或不可用时切换- 带内联附件的生成请求优先选择已上传其中最多附件的账户,该账户并发槽位用满、冷却或不可用时再按策略选择
- 已有生成请求在等待或生成 WAA proof(Camoufox 后端界面运行时到页面发出请求为止)的账户排在其余已就绪账户之后:会话粘性没有指定账户时,请求按策略先在没有 proof 排队的账户中选择,都在排队时再在全部有空槽位的账户中选择
上游通道:
- 生成请求的候选为账户与
UPSTREAM_CHANNELS所启用通道的组合:Playground 按ListModels与权益判断,Build 按 Build 代理返回的 Gemini API 模型目录与相同权益判断 - 轮询与粘性在组合间按账户 ID 与通道顺序推进
- 冷却按通道记录(Build 为
build:<模型>),一个通道冷却后同一账户可由另一通道继续;全部启用通道都冷却时按下文的冷却规则排队或返回 429 -build模型只使用 Build 写代码助手通道assistant,冷却 scope 为-build模型 ID,同一账户同时只运行一个-build生成,对话续接得上某账户应用中的 trajectory 时该账户优先;通道规格见 Build 通道- 计数、Live、转录与 Drive 文件引用使用 Playground RPC
并发与 Cookie:
- 并发槽位、Worker 与 WAA 按账户共享
- 每个账号最多同时租用
PER_ACCOUNT_CONCURRENCY个请求槽位;首个请求获取跨进程文件锁,最后一个请求释放 - WAA proof 由账号 worker 串行生成,
GenerateContent由同一 Camoufox Worker 的页面并发发送并流式读取(WAA_BACKEND=spidermonkey时由账户 runtime 的 Go HTTP 发送) - 请求前使用 Worker 当前 Cookie 生成 Authorization,响应头到达后把 Worker Cookie 原子同步到账户持久状态;其他 MakerSuite HTTP 响应的 Cookie 在响应头到达时与最新账户状态合并
换号与重放:
- 未固定账户的请求遇到可重试的 401、403、404、429、5xx、收到响应前的连接断开或单账户初始化超时时,可以在首个上游语义事件前继续切换尚未尝试的同能力账户;额度以外的失败最多换
MAX_ACCOUNT_SWITCHES次,额度失败不计入 - 上游以 403、协议错误码 7 拒绝账户(官网不跳转拒绝页的情形)时,自上次成功后第一次被拒只换号;没有其他账户可换时在该账户上重试一次;连续第二次被拒起,该账户在该模型上冷却 1、5、15、30、60 分钟,成功一次后重新计数
- Drive 引用随需要临时复制到生成账户,显式账户和视频任务保持账户绑定
- Chrome 导入状态保留续签材料,HTTP
401时在同一固定出口续签一次、重建该账户 WAA runtime 并重放请求
Worker 容量由热池目标、活动上限和单账户并发共同约束。
启动与替换:
- 活动数低于
MAX_ACTIVE_WORKERS时直接启动并发布新 Worker - 容量已满且存在空闲旧实例时,先启动 pending Worker(正在启动、尚未发布的替代 Worker),再关闭旧实例并发布替代 Worker
- 被替换的空闲实例按以下顺序选择:对请求模型处于冷却(全局或该模型限额)的实例优先,同类中最久未用者优先;其次为最久未用实例
- 多个冷却实例可并行替换,每次替换预留独立的旧实例,启动期间新旧进程短暂共存
- 启动失败或取消时现有 Worker 继续服务
- 旧 Worker 与 pending 回收同时失败时,两份进程与租约均保留为 cleanup pending(仍待关闭)并占用容量槽,后续 Stop 会重试关闭
排队:
- 请求只在取得容量槽位时占用冷账户;没有可立即使用的槽位时释放该账户并重新分类,由任一空闲的热 Worker 或新释放的槽位接收
- 存在可调度账户但暂时没有空闲槽位的请求按相同选择条件排队,可用账户先按 API key 绑定、指定账户与模型绑定收窄:与前面等待中的请求共用的账户先到先服务,前面的请求用不到的账户直接使用;在租约释放或 Worker 状态变化时唤醒,直到请求超时
- 候选账户全部处于冷却时,最早恢复时间在 1 分钟内且不晚于请求期限的请求排队等待恢复,更晚的请求直接返回 429,错误信息给出最早恢复时间
- 有 Worker 的账户在某模型上进入超过 1 分钟的冷却时,若活动与启动中的 Worker 少于
MAX_ACTIVE_WORKERS,后台为一个对该模型未冷却、还没有 Worker 的候选账户启动 Worker,冷却账户的 Worker 保留
回收与容量设置:
- 超出
WARM_WORKER_LIMIT的 Worker 空闲 5 分钟后关闭,热池保持目标数量 - 管理端保存容量设置后立即作用于当前生成服务:Worker 数超过新的
MAX_ACTIVE_WORKERS时立即关闭多出的空闲 Worker,忙碌的在请求结束后的回收检查中关闭;热池少于新的WARM_WORKER_LIMIT时补足预热;等待中的启动与请求按新的WARM_STARTUP_CONCURRENCY与PER_ACCOUNT_CONCURRENCY放行
账户的 WAA runtime 租约由其他进程持有时:
- 该账户退出预热与调度候选,首次 5 秒后重新探测,每次仍被占用时间隔翻倍、上限 1 分钟,每段占用只记录一条日志
- 指定该账户或只剩该类账户的请求返回账户正在使用的错误
FIRST_EVENT_HEDGE 不为 off 时,FIRST_EVENT_HEDGE_MODELS 列出的模型的生成请求,原请求从取得账户起等待首个语义事件达到阈值后,为该请求发起一个备用请求。
阈值:
- 自定义秒数为固定阈值
auto取该模型与通道近 24 小时最近 200 个原请求首字等待的 p95,样本少于 20 个时不发起- 原请求的样本为取得账户到首事件的时长,被备用请求取代的原请求按已等时长计入,备用请求不计入;管理进程启动时从请求账本补入近 24 小时的样本
备用请求的账户:
- 先用 Worker 已就绪且没有活动请求的其他账户,没有时用原账户的其余并发槽位
- 引用已上传文件或指定账户的请求只用原账户的其余并发槽位
- 都没有时每秒复查;同时进行的备用请求最多 4 个
- 后台 Responses 与 Interaction、Deep Research 与 Antigravity 等经后台任务生成的 agent(
interaction_task)与-build写代码助手请求不发起备用请求
结果:
- 先出首事件的一方继续,另一方取消上游请求、清理临时文件并释放租约
- 被取消的请求同样计入上游的每日与每分钟请求额度
- 账本的
attempts以hedge标记备用请求,以superseded标记被取代的一方
同一模型与通道最近两个请求都在本请求开始前 30 秒内以连接断开失败、其间没有请求收到首个事件时,本请求在前两个账户上的尝试也都以连接断开失败就以原错误结束。
故障重置先等待同账户的活动请求释放租约;等待期间该账户暂停接收新请求。客户端取消只结束自身请求。启动预热在官网 Run 按钮启用后提交,请求在发送前再次检查账户冷却状态。
额度冷却按 quota_unit、quota_limit、quota_metric、错误文案依次判定周期:
| 额度错误 | 冷却期限 |
|---|---|
| 明确的每日限额 | 美国太平洋时间次日零点 |
| 分钟限额 | 按有效的 window_start_time |
| 写明恢复时间的套餐限额 | 错误写明的恢复时间 |
| 没有重试时间的套餐限额 | 按连续次数 1、5、15、30、60 分钟 |
| 通用 429 | 按连续次数 1、5、15、30、60 分钟 |
- 写明恢复时间的套餐限额形如
You've reached your usage limit for this model (resets in 10 hours, 2 minutes);没有重试时间的套餐限额为You've reached your usage limit,或 Build 写代码助手步骤带每用户额度标记 - 按连续次数冷却的错误按同一账户同一 scope 计数,该 scope 成功一次后从 1 分钟重新开始;没有重试时间的套餐限额在冷却未结束时的并发失败沿用当前期限
RetryInfo与Retry-After提供的重试时间优先;同范围已有更晚恢复的冷却时保留它- 错误列出的额度项上限全部为 0(
limit: 0)时冷却类型为无配额,期限同样按上述规则 - 全局范围由额度元数据确认,其余错误只冷却失败模型或能力 scope;正文后的额度错误与 Live 会话错误使用同一规则
- 订阅模型遇到额度错误时,后台立即刷新该账户的权益与目录,同一账户每分钟最多一次
全部候选账户都在冷却,且本请求累计排队已到 1 分钟、最早恢复晚于剩余时长或最早恢复的是权限拒绝冷却时,套餐限额、每日限额与权限拒绝冷却中的账户仍接收请求。上游按每个请求判定是否放行:额度用尽后较短的请求仍可能完成,权限拒绝也是间歇出现。
- 同一请求依次发往这些账户、每个账户一次,上游放行即完成
- 被拒的账户按上游原因更新冷却,套餐限额的恢复时间只精确到分钟,再次被拒算出的恢复时刻与已有冷却相差不到 1 分钟时沿用已有的恢复时刻;全部拒绝时按最后一次的原因返回 429 或 503
- 套餐限额与每日限额冷却中的账户被拒后,记下被拒请求的输入字节数(系统指令、各轮文本、函数参数与结果、内联附件);记录有效期为 5 分钟,失效后同一账户同一模型再次被拒时依次为 15、30、60 分钟,成功一次后从 5 分钟重新开始,有效期内再次被拒只把记下的字节数改为较小的一个;有效期内输入字节数不小于它的请求跳过该账户,更小的请求照常发送,记下的字节数越大的账户越先使用;被跳过的账户按记录失效与冷却恢复中较早的时刻计入重试时间
- 冷却中的账户在这类发送中收到恢复更早的其他额度错误(如不带细节的 429)时,该错误另记为回退冷却,按连续次数 1、5、15、30、60 分钟递增,原冷却不变;回退冷却未结束的账户不再接收这类发送
- 没有可发的账户时直接返回 429 与最早恢复时间
账户状态:
| 状态 | 含义 |
|---|---|
ready |
认证有效且存在可调度容量 |
busy |
账户存在独占操作、认证刷新或活动请求;调度仍按 PER_ACCOUNT_CONCURRENCY 判断剩余槽位 |
cooldown |
账户的全局 * 冷却仍有效;模型 scope(状态记录范围)冷却只影响对应请求的候选分类 |
auth_required |
账户级认证失败,需要重新登录或续签 |
restricted |
Google 拒绝账户使用 AI Studio(服务受限、年龄要求或 Workspace 停用),原因写入 runtime-state.json;启动、调度与巡检跳过,手动刷新读取成功后恢复;上游要求验证账户时,手动刷新另发一次生成请求,这次生成成功后恢复,其他结果保持受限并返回原因;账户状态改为就绪时直接清除受限记录,下一次请求仍被上游拒绝时重新标为受限 |
unavailable |
当前运行时无法使用账户 |
disabled |
账户配置已停用 |
认证结果携带 authGeneration(认证状态版本)与 checkedAt(检查时间),仅在账户对象、authGeneration 和时间顺序均匹配时应用;同一时间点的成功结果优先于失败。模型成功与冷却写回使用独立 modelAccessGeneration(模型状态版本)和 checked_at,目录变化时 modelAccessGeneration 递增,同一时间点已有 verified 时保留成功状态。
模型访问 scope:
| 操作 | scope | 成功与失败语义 |
|---|---|---|
| 普通 GenerateContent | <modelID> |
规范 EventFinish 到达后写 verified;Code 7 保留已有记录 |
| CountTokens | count-tokens:<modelID> |
成功清该 scope 冷却,模型 verified 保持原值 |
| Transcribe | <modelID> |
非空文本或 segments 写 verified;Code 7 保留已有记录 |
| Live 纯文本 | <modelID> |
setup 成功写 verified;每次 SendText 开始一次模型资格检查,turn_complete 更新成功 |
| Live 音频或图像 | bidi-media:<modelID> |
SendMedia 开始一次模型资格检查并更新媒体 scope |
| Robotics | bidi-media:<modelID> |
SendText 开始一次模型资格检查,turn_complete 更新成功 |
ModelAccessKey(scope, model)会移除models/前缀;空 scope 返回规范模型 ID,非空 scope 返回<scope>:<canonicalModelID>- Bidi setup 使用 lease(账户租约)时间,会话内每个 qualifying turn(一次模型资格检查)分配严格递增的 attempt 时间,
turn_complete消费对应 attempt - 普通流式生成在规范
EventFinish到达时写verified;此前的 text、reasoning、tool、usage 和首事件用于输出与性能统计,终态前断流、取消或错误保持原验证状态
模型目录取自账户会话页面载入时的 GetAiStudioBenefitTier 与 ListModels 响应:有常驻 Worker 的账户取它最近一次页面载入,没有的账户在 Worker 容量允许时启动 Worker,否则临时载入一个页面,取得响应后关闭。Worker 重新载入页面时在当前标签页按官网冷启动载入,当前标签页有进行中的请求时在新标签页中载入并切换过去。
启动期同步:
- 对全部 enabled 且处于 ready、busy 或 cooldown 的账户执行;还没有目录的账户同时读取,已有目录的账户按权益从高到低、同权益按账户 ID 逐个读取;每个账户占用一个普通并发槽位
- 同步报错或返回空目录的账户进入 generation 内的 pending ID 集合
- 每个非空结果立即更新公共目录、账户状态,并在 RUNNING 期间预热更多 Worker
运行期刷新:
- 启动期同步结束后,单个 30 秒 ticker(定时器)重新载入可用的 pending 账户的页面
- 同一循环从启动期同步开始时起每 24 小时按同样的顺序逐个重新载入全部 enabled 且处于 ready、busy 或 cooldown 的账户的页面;没有空闲槽位或正在冷却的账户在本轮最后等到槽位空闲再读;权益或目录变化时写回并发布账户与模型快照
- 冷却中的任务保留到期再试;需要登录、停用、不可用或已删除的账户退出重试,重新登录或启用后由账户更新流程重新同步
- 失败日志记录账户与原因,恢复成功记录模型数量
请求的模型不在任何账户的目录中时:
- 目录读取正在进行(启动期同步或巡检的一轮)时,请求等到该模型出现在某个账户的目录中或这一轮读完
- 没有进行中的一轮且距上一轮开始已超过 10 分钟时,巡检立即开始一轮,请求同样等到该模型出现或这一轮读完再查找模型
- 等待最长为
REQUEST_TIMEOUT
modelRevision 跟踪账户和配置变化,生成服务开始接收请求前会确认已应用当前 revision。
认证状态包含长期凭证和设备绑定材料,保存在本机受控目录。提交、Issue、CI 和普通日志使用脱敏材料,保留字段形状并替换 Cookie、token、proof、邮箱、账户 ID、提示词、响应正文和完整原始帧。
公开端点统一读取同一份实时模型目录和规范事件:
| 协议 | 端点 |
|---|---|
| OpenAI Chat | GET /v1/models、GET /v1/models/{model}、POST /v1/chat/completions |
| OpenAI Responses | POST /v1/responses、POST /v1/responses/input_tokens、POST /v1/responses/compact、GET/DELETE /v1/responses/{id}、GET /v1/responses/{id}/input_items、POST /v1/responses/{id}/cancel |
| Gemini Interactions | POST /v1beta/interactions、GET/DELETE /v1beta/interactions/{id}、POST /v1beta/interactions/{id}/cancel,/v1/interactions 下路径相同 |
| OpenAI 与 Anthropic Files | POST/GET /v1/files、GET/DELETE /v1/files/{file}、GET /v1/files/{file}/content |
| OpenAI 媒体 | POST /v1/images/generations、POST /v1/images/edits、POST /v1/audio/speech、POST/GET /v1/videos、GET/DELETE /v1/videos/{id}、GET /v1/videos/{id}/content |
| OpenAI Transcribe | POST /v1/audio/transcriptions、POST /v1/audio/translations |
| OpenAI Embeddings | POST /v1/embeddings |
| Anthropic | POST /v1/messages、POST /v1/messages/count_tokens |
| Gemini | GET /v1beta/models、GET /v1beta/models/{model}、POST /v1beta/models/{model}:generateContent、:streamGenerateContent、:countTokens、:embedContent、:batchEmbedContents、:predictLongRunning、GET /v1beta/operations/{id} |
| Gemini Files | POST /upload/v1beta/files、GET /v1beta/files、GET/DELETE /v1beta/files/{file} |
| Realtime | GET /v1/live、GET /v1/robotics/stream |
管理端路由:
| 能力 | 路由 |
|---|---|
| 健康与状态 | GET /health、GET /api/status |
| 模型与账户 | GET /api/models、GET/POST /api/accounts、GET /api/accounts/exits、GET/POST /api/accounts/import/chrome、GET /api/accounts/import/browsers、POST /api/accounts/import/cookies/discover、POST /api/accounts/import/cookies、PUT/DELETE /api/accounts/{id}、PUT /api/accounts/{id}/state |
| 账户任务 | GET /api/accounts/tasks、DELETE /api/accounts/tasks/{id} |
| 登录与刷新 | POST /api/accounts/{id}/login、POST /api/accounts/{id}/refresh、GET /api/login-view/{view}(WebSocket) |
| 远程配对 | GET /api/pairing、POST /api/pairing、POST /api/pairing/accounts、PUT /api/pairing/accounts/{account}/cookies |
| 生成服务 | POST /api/control/start、POST /api/control/stop |
| 配置 | GET /api/config、PUT /api/config、GET /api/paths?path=(列出服务所在机器的目录与账户状态文件 storage-state.json,path=roots 列出文件系统根)、POST /api/paths/pick?path=(桌面版以系统对话框选择账户目录) |
| 冷却与请求 | GET /api/cooldowns、GET /api/requests、POST /api/requests/{id}/cancel |
| 用量与正文 | GET /api/usage、GET /api/usage/pairs、GET /api/usage/records、GET /api/usage/records.csv、GET /api/requests/{id}/body |
| 日志与事件 | DELETE /api/logs、GET /api/events |
| 在线更新 | GET /api/update、POST /api/update |
/api 接受 loopback 请求,并在请求带 Origin 时执行 same-origin 校验。POST /api/pairing/accounts 只校验配对令牌,PUT /api/pairing/accounts/{account}/cookies 只校验续签凭据。/v1 与 /v1beta 使用公开 API key 与 CORS。
续接状态与本地数据库:
- OpenAI Responses 的
previous_response_id与 Gemini Interactions 的previous_interaction_id共用最多 256 个响应节点,用于重建下一轮完整 contents;生成期间上一轮节点被淘汰时,新响应保存请求开始时读取的完整上下文 - 已结束的节点写入
runtime/states.db;服务启动时读回节点 ID 与续接起点,节点正文在续接或查询时载入,重启前的 ID 仍可续接与查询 - 节点写入在释放节点表的锁之后按顺序提交,提交期间其他续接与查询照常进行
- 对话库与续接状态库在服务就绪后交还空闲页,请求账本在后台清理过期记录后交还
- Drive 文件、视频任务和产物文件的账户绑定写入
runtime-state.json,重启后仍可轮询和下载
新增上游能力从 internal/aistudio 开始:编码真实数组槽位、解码服务器事件,再由 internal/api 投影到公开协议。模型方法、上下文、输出上限、工具、声音、图片规格和视频规格均来自实时 ListModels。
runtimeManager 同时实现基础 Service 以及 Video、File、Bidi 和 Transcription 扩展接口。internal/app 负责资源账户绑定、跨账户文件复制、运行状态和重试流程;internal/api 负责 HTTP、SSE 与 WebSocket DTO,即公开协议使用的请求、响应和事件对象。完整请求字段、响应 DTO、SSE 和 WebSocket 事件见 protocol.md。
前端开发命令:
cd web
npm run dev
npm run typecheck
npm run lint
npm run format:check
npm run build前端工具链为 Vite+:vite.config.ts 同时配置开发服务、构建、Oxlint 与 Oxfmt。
npm run dev的开发服务把/api、各协议路径等请求转发到http://127.0.0.1:2048;环境变量SERVICE_TARGET指定另一个服务地址npm run lint先运行 Oxlint,再运行 ESLint;ESLint 只负责 eslint-plugin-vue 的recommended模板规则,<script lang="ts">由@typescript-eslint/parser解析,与 Oxlint 共有的规则由 eslint-plugin-oxlint 关闭,与格式化冲突的格式规则由 eslint-config-prettier 关闭npm run typecheck由 vue-tsc 检查脚本与模板类型npm run format:check由 Oxfmt 检查格式
Vite+ 将生产产物写入 internal/webui/dist,脚本、样式与 SVG 以 gzip 压缩后只保留 .gz 文件,index.html 与字体保持原样;KaTeX 经 web/src/playground/katex.scss 只打包 woff2 字体。管理端通过本机 /api 路由管理生成服务、日志、账户、配置、模型冷却、活动请求和 SSE 状态事件;认证状态与 WAA 对象只保存在服务端。
管理端提供简体中文、繁體中文、English、日本語、한국어、Français 与 Deutsch:
- 所选语言保存在浏览器的
user_lang,未选择时按浏览器首选语言选择,都不支持时为 English - 文案位于
web/src/locales/<语言>.ts,zh-CN.ts定义全部键,其他语言按同一键集合提供messages,缺键时类型检查失败 - 每种语言打包为单独的文件,页面只加载当前语言与切换到的语言
- 管理接口错误体的
error.code对应error.<code>文案,{detail}填入服务返回的error.message,未收录的错误码显示服务原文
服务生成的日志、错误、账户状态、冷却原因与命令行输出以简体中文写成,internal/i18n/messages/<语言>.json 是其他六种语言的翻译表:
- 键为源码中含中文的字符串字面量与 Go 格式串,值为译文,
{0}、{1}依次对应格式动词 - 新增或修改含中文的文案时,在六个翻译表中写入同一键的译文
- 上游原文、账户、模型名与数值保持原样
internal/i18n 与 web/src/messages.ts 按同一规则翻译:
- 整句匹配格式串,格式串开头的格式动词取最长匹配,格式动词的取值递归翻译
- 整句没有匹配时,依次按换行、
|、;、;分段 - 按第一个
:或:拆成外层说明与内层原因 - 按不含格式动词的文案前缀拆开
- 最后拆开
键=值
输出语言:
- 管理端各语言的界面文案
web/src/locales/<语言>.ts引入同一语言的翻译表,两者打包在同一个文件中,按界面语言显示服务文案 - 控制台与命令行按操作系统语言输出,日志文件保持简体中文
internal/webui/embed.go 使用 //go:embed dist,Go 构建前必须生成当前前端产物。管理端的静态文件与 /api 响应:
- 静态文件由
statigz返回,接受 gzip 的客户端直接收到.gz内容,其余客户端收到解压后的内容 /assets/下文件名带内容哈希的静态文件带Cache-Control: public, max-age=31536000, immutable;其余页面与静态文件带Cache-Control: no-store,对带If-None-Match的请求也返回完整正文- 入口页的内联脚本在资源载入失败、入口模块解析失败或
vite:preloadError时,以cache: reload重新取回本页的/assets/资源后重载,30 秒内只重试一次 /api的 JSON、CSV 与事件流响应同样以 gzip 返回给接受 gzip 的客户端,事件流每个事件写出后随即刷新- 管理端从
/api/events接收status、models、accounts、log、cooldowns和request事件
API 试用页位于 web/src/playground/,路由与官网相同(/prompts/new_chat、/prompts/new_image、/prompts/new_video、/generate-speech、/new_music、/live、/prompts/:id)。
请求与显示:
request.ts由对话轮次与运行设置组成 GeminigenerateContent请求protocols.ts把同一请求转换为 OpenAI Chat、OpenAI Responses、Anthropic Messages 或 OpenAI Images,并以eventsource-parser读取各协议的 SSE,以各协议完成事件结束请求;流内错误与提前断流显示为失败- 服务端的响应头、正文和心跳的刷新错误沿 HTTP 写入路径返回,事件转发在取消时释放账户租约
- 停止后可继续提交;运行快捷键在 User settings 中选择 Ctrl + Enter(默认)或 Enter
- 回复正文由
markdown-it按 Markdown 渲染,原始 HTML 按文本显示
对话保存:
- 对话保存在
runtime/prompts.db,经/api/prompts读写,在轮次、标题或运行设置变化后合并保存 - 历史页的重命名经
PATCH /api/prompts/{id}只改写标题与描述,复制经POST /api/prompts/{id}/copy在服务端完成 - 与官网一样,标题经
POST /api/prompts/title(GenerateTitle)生成:对话页在未命名时于运行结束后以最后一轮用户文本与模型回答生成,视频、音乐与 Imagen 页在提交时以提示词生成;失败时保持 Untitled prompt
运行设置按模型目录的能力字段显示,只发送界面上可见且已填写的参数,未填写的数值参数由模型默认值决定;所选协议无法表达的设置(protocols.ts 的 protocolSupports)在该协议下隐藏。
图片、视频、语音、音乐与实时对话页位于 media/,宽高比、分辨率与时长取自模型目录的 capability_options:
| 页面 | 端点 |
|---|---|
| 图片 | Gemini generateContent 或 OpenAI Images |
| 视频 | Gemini predictLongRunning 或 OpenAI Videos |
| 语音 | /v1/audio/speech 或 Gemini 端点 |
| 实时对话 | /v1/live WebSocket |
Gemini 端点返回的语音 audio/L16 在页面封装为 WAV。
日志页保留最近 2000 条事件,按请求与运行阶段合并后先显示最近 200 行。关闭自动滚动时,当前首行保持固定,新日志追加在末尾。请求详情与阶段步骤在首次展开时渲染。
新增上游能力按以下顺序实现:
- 在
internal/aistudio定义规范请求、响应类型与模型能力 - 编码 protocol.md 中对应的 JSON+protobuf 数组
- 将网络增量解码为规范事件
- 由
internal/api分别投影 OpenAI、Responses、Anthropic 和 Gemini 协议,响应的块、字段与顺序与各协议官方服务的输出一致 - 将结构化状态与操作入口绑定到管理端
internal/api 消费规范请求与事件,internal/aistudio 管理账户文件、WAA runtime、原始上游数组和实时模型能力。资源型操作在创建时记录账户 ID,后续轮询、下载与提示引用使用该账户。
已识别字段校验类型和 oneof 约束。未知非空槽保留为 provider 事件或原始扩展字段;无法解释的已消费字段和无效媒体内容返回结构化协议错误;缺失完成帧报告为上游流中断。
本地数据库使用经 cgo 编译的 SQLite,internal/waa 经 cgo 链接 SpiderMonkey 静态库,internal/imagecodec/libwebp 经 cgo 链接 libwebp 静态库。构建需要 C/C++ 编译器与当前平台的静态库:
| 平台 | C/C++ 编译器 |
|---|---|
| Windows | llvm-mingw 的 UCRT 版 clang |
| macOS | Xcode Command Line Tools |
| Linux 命令行版 | Zig |
| Linux 桌面版 | gcc |
静态库分别来自 Mag1cFall/firefox 与 Mag1cFall/libwebp 的 Releases,下载与 CC、CXX、CGO_CPPFLAGS、CGO_LDFLAGS 的设置见 README 的源码构建一节。发布二进制前先构建前端:
cd web
npm ci
npm run build
cd ..
go build -trimpath -o aistudio2api.exe ./cmd/aistudio2api提交前执行与修改相关的功能验收、前端检查及 Go 静态检查:
go vet ./...桌面版以构建标签 desktop 编译,internal/desktop 用 Wails v3 创建窗口与系统托盘,发布构建同时加 production 标签。Linux 桌面版另加构建标签 gtk3,需要 libgtk-3-dev 与 libwebkit2gtk-4.1-dev,链接 glibc 版静态库 linux-amd64-gnu:
go build -trimpath -tags desktop,production -ldflags "-H windowsgui" -o aistudio2api.exe ./cmd/aistudio2apiCGO_ENABLED=1 go build -trimpath -tags desktop,production -o aistudio2api ./cmd/aistudio2apiLinux 的主窗口与托盘菜单把 WebKitGTK 的硬件加速策略设为 WebviewGpuPolicyNever,页面由 CPU 绘制。
Linux AppImage 由 build/linux/appimage.sh 在 Ubuntu 22.04 上以 wails3 generate appimage 打包,随包带上 WebKitGTK、GTK 与 GLib,以及构建机的 GIO 模块(TLS、代理与设置)和 GTK 输入法模块(含 ibus 与 fcitx5);AppRun 以 GIO_MODULE_DIR 与 GTK_IM_MODULE_FILE 让程序只加载这些随包模块。
Windows 桌面版启动时经 Wails 查询 WebView2 运行时版本。查不到且以显示窗口方式启动时,用消息框询问是否安装,询问的同时在后台下载微软 Evergreen 引导程序:
- 确定后等下载完成,后台下载失败时重新下载一次,以
/install按当前用户权限安装;下载与安装进度显示在引导程序自己的窗口中,完成后创建桌面窗口 - 询问与安装期间管理服务照常启动,双击托盘图标或再次运行可执行文件在默认浏览器打开管理页面
- 取消询问时删除已下载的引导程序;在引导程序窗口中取消安装与取消询问相同;安装失败时先以消息框说明
- 取消、安装失败或以隐藏方式启动时只创建托盘:服务就绪后在默认浏览器打开管理页面,双击托盘图标或再次运行可执行文件也打开管理页面
Windows 桌面版的 WebView2 数据写入 %LocalAppData%\AIStudio2API\WebView2。
主窗口在显示时创建,关闭时连同 WebView 一起销毁,进程只保留托盘;再次运行或从托盘显示窗口时,以上次关闭前的位置、大小与最大化状态重新创建,并直接打开关闭前所在的管理页面路由。
页面经 busy:1、busy:0 消息告知桌面壳是否需要保留:有进行中的生成或管理写请求、待写入或写入失败的对话、未发送的对话输入、未保存的设置,或只存在于页面的生成图片与音频时,关闭窗口只隐藏窗口,页面报告空闲后再销毁,在此之前从托盘显示窗口取回原页面。托盘菜单在页面加载前按系统语言显示,页面加载后跟随界面语言。
Windows 与 Linux 的主窗口无边框,标题栏由页面绘制。Windows 上 WebView2 以合成托管方式运行,标题栏与最小化、最大化、关闭按钮作为非客户区参与系统命中测试:悬停最大化按钮时显示贴靠布局,右键标题栏打开系统菜单,双击标题栏最大化或还原。
托盘与菜单栏菜单:
- Windows 托盘菜单是
tray_windows.go以 Win32 GDI 绘制的弹出窗口:- 右键或用键盘打开托盘图标菜单时,以
Shell_NotifyIconGetRect取得的图标位置为排除区域贴着图标弹出,并限制在所在显示器的工作区内 - 配色与管理页面下拉框相同,页面经
theme:dark、theme:light消息告知界面主题,页面加载前跟随系统深浅色 - 字号与间距按所在显示器的 DPI 缩放
- 方向键、Home、End 移动高亮,回车与空格选择,Esc 或失去焦点时关闭
- 右键或用键盘打开托盘图标菜单时,以
- Linux 通过 Wails 小窗口渲染
tray.html,使用与 Windows 相同的菜单配色、行高和键盘操作,关闭菜单时销毁窗口;StatusNotifierItem 的Activate事件(单击)显示主窗口,ContextMenu事件打开自绘菜单 - macOS 菜单栏图标使用系统菜单,单击或右键时由系统弹出;应用菜单为应用、文件、编辑、显示与窗口五个系统标准菜单。两个菜单的文字跟随界面语言,用词取自同语言 macOS 的系统菜单;页面加载前按 macOS 首选语言显示
Windows 与 Linux 托盘菜单的“开机自启动”每次打开菜单时从系统读取勾选状态,macOS 菜单栏菜单的“登录时打开”在设置菜单与每次切换后读取;设置失败时以对话框显示错误:
- Windows:写入
HKCU\Software\Microsoft\Windows\CurrentVersion\Run的AIStudio2API值,命令为带引号的当前可执行文件加-open-ui=false;值指向其他可执行文件或被任务管理器在Explorer\StartupApproved\Run中停用时显示为关闭,开关时删除StartupApproved\Run中的记录 - Linux:写入
~/.config/autostart/aistudio2api.desktop,Exec为当前可执行文件(从 AppImage 运行时为 AppImage 文件)加-open-ui=false;指向其他程序或含Hidden=true、X-GNOME-Autostart-enabled=false时显示为关闭 - macOS:经 Wails 注册登录项,macOS 13 及以上从
.app运行时使用 SMAppService,登录后打开窗口;其余情况写入带-open-ui=false的 LaunchAgent
应用图标与打包配置在 build/:
appicon.svg为图标源文件,appicon.png与windows/icon.ico由wails3 generate icons从它生成darwin/appicon.svg是按 macOS 图标网格缩到 824/1024 并带投影的同一图标;darwin/icons.icns由它渲染的 1024 像素 PNG 经wails3 generate icons生成;同一 PNG 缩到 512 像素为internal/desktop/icons/appicon-mac.png,macOS 桌面版启动时设为 Dock 与对话框图标darwin/*.lproj/InfoPlist.strings为各语言的麦克风与摄像头使用说明,打包时与icons.icns一起放入.app的Contents/Resources/,系统对话框与菜单随之按系统语言显示cmd/aistudio2api/rsrc_windows_amd64.syso包含 Windows 图标、清单与版本信息,go build构建 Windows amd64 时自动嵌入;它由以下命令生成:
wails3 generate syso -arch amd64 -icon build/windows/icon.ico -manifest build/windows/wails.exe.manifest -info build/windows/info.json -out cmd/aistudio2api/rsrc_windows_amd64.sysoCamoufox 在首次浏览器登录时准备;WAA_BACKEND=camoufox 时在管理服务启动后于后台下载,生成服务等下载完成后就绪。
实现与评审按以下设计原则取舍:
- 全兼容:公开协议接受各协议标准的全部有效输入;上游或某个标准拒绝的输入,在适配与编码层改写成上游接受的形式
- fail fast:出错时在出错处以真实原因失败,错误让客户端能按自己的策略重试;找不到合理解释的输入在发送前返回说明原因的错误
- 默认行为先保证请求可用,其次照上游原样;上游的额度、权限与模型状态按上游返回处理
- 接口与官方 API 用法一致:同样的请求发给官方 API,模型看到的上下文相同
- 主路径只包含必需的步骤:可有可无的步骤删除,必需而耗时的步骤(下载、目录同步、预热)在后台或按需进行
- 请求、身份、节奏与界面行为对齐官网;官网能完成而服务失败属于服务缺陷
- 修复沿报错路径修根因,同类字段、嵌套结构与其他协议入口一起修
- 代码只处理真实会发生的情况,选能满足需求的最简单实现
- 模型、方法与能力以账户的实时目录为准
贡献内容聚焦单一功能或协议变更,并使用脱敏后的请求与响应样例。
GitHub Actions:
checks.yml对 Pull Request 与main推送执行前端类型检查、lint 与格式检查,以及go.mod最低版本的 Go 单元测试与 vetbuild.yml在v*标签上先运行同一组检查,再并行构建 Linux 两个架构的命令行版、Windows 版与各桌面版,以最高压缩级别打包,并发布 Release 与 Docker 镜像;手动触发时只编译与链接- 前端产物由单独的构建任务产出并在各 Go 任务间共享;各任务经
.github/actions/static-libraries下载对应目标的 SpiderMonkey 与 libwebp 静态库 - 前端任务由
actions/setup-node按web/package-lock.json缓存 npm 下载 - Go 模块与编译缓存的键由检查项或构建目标、Go 版本、
go.sum哈希与提交号组成,恢复时按去掉提交号的前缀取最近的缓存;SQLite、SpiderMonkey 与 libwebp 绑定的 C/C++ 编译产物随 Go 编译缓存复用 - 检查任务只在
main上保存缓存,Pull Request 与标签构建中的检查恢复main的缓存 - 构建任务每次运行后保存缓存,同一标签重新构建时恢复,标签构建也可恢复
main上手动触发的构建保存的缓存 - Docker 镜像构建的层缓存按平台写入 GitHub Actions 缓存
发布包使用当前稳定版 Go 构建:
- Windows amd64:桌面版 zip,只含
aistudio2api.exe - macOS:arm64 与 amd64 合并的桌面版,ad-hoc 签名的
AIStudio2API.app打成 zip 与 LZMA 压缩的 dmg - Linux amd64:桌面版 AppImage 与 deb
- Linux amd64/arm64 与 macOS amd64/arm64:命令行版 tar.gz,只含
aistudio2api
Linux 命令行版与 Docker 镜像中的程序由 zig cc 以 musl 静态链接,不依赖系统 C 库;从源码构建镜像时 npm、Go 模块与编译缓存经 BuildKit 缓存挂载在多次构建间复用;Windows 版在 Ubuntu 上经 llvm-mingw 交叉编译;macOS 各包在 macOS 构建机上编译,两个架构并行。
发布流程:
- 推送
v*版本标签后自动创建 Release 并附上这些发布包;含-的标签发布为预发布版本 - 同一标签的 linux/amd64 与 linux/arm64 镜像以 Dockerfile 的
release目标装入该标签的 Linux 命令行版程序,推送到ghcr.io/mag1cfall/aistudio2api,正式版本同时更新latest - 标签构建的发布包在 Actions 中保留七天,Release 附件长期保留
管理端“版本”页的在线更新由 internal/app/update.go 实现:
| 步骤 | 行为 |
|---|---|
| 读取版本 | GET /api/update 读取 https://api.github.com/repos/Mag1cFall/AIStudio2API/releases/latest,结果缓存一小时,?refresh=1 立即重新读取;请求经 PROXY 的第一个代理,未设置时经系统代理 |
| 更新方式 | 链接时写入更新管理方的构建为 managed;当前版本为正式版本号时为 binary;源码构建的伪版本、(devel) 与带 +dirty 的版本为 development;存在 /.dockerenv 或 /run/.containerenv 时为 container |
| 下载与校验 | POST /api/update 只在 binary 且有更新版本时执行,按当前系统与架构下载 aistudio2api-<版本>-<系统>-<架构>.zip(Windows)或 .tar.gz,macOS 桌面版下载 aistudio2api-<版本>-darwin-universal.zip,Linux 桌面版下载 aistudio2api-<版本>-linux-<架构>.AppImage 或 .deb,与 Release 资产的 digest 核对一致后取出其中的可执行文件或 AIStudio2API.app |
| 替换 | minio/selfupdate 替换当前可执行文件,失败时恢复原文件;Windows 上原文件改名为 .aistudio2api.exe.old |
| 重启 | 返回 202 后按收到 SIGTERM 的顺序停止 HTTP 服务、生成服务与 Camoufox(HTTP 服务最多等待进行中的连接 10 秒,之后断开),再以原参数加 -open-ui=false 启动新程序:Windows 上新进程沿用当前控制台,其他系统以 exec 替换当前进程 |
| 桌面版替换与重启 | Windows 与 macOS 桌面版经 Wails 更新器把新版本暂存到系统临时目录,返回 202 后启动更新辅助进程并按上一行的顺序退出;辅助进程等待原进程结束(最多 30 秒),替换可执行文件或 AIStudio2API.app,启动新版本后删除备份与暂存文件 |
| Linux 桌面版替换与重启 | 从 AppImage 运行时把新版本写到 APPIMAGE 所在目录后改名覆盖原文件;deb 安装时经 pkexec apt-get install 安装,桌面环境弹出管理员认证;返回 202 后启动等待原进程结束的 sh,按收到 SIGTERM 的顺序退出,原进程结束后以无参数启动 AppImage 文件或 /usr/bin/aistudio2api,与 Windows 和 macOS 一样显示主窗口 |
managed、development、container 与已是最新版本时 POST /api/update 返回 409;页面每秒读取 /api/status,版本变化或返回 401 时刷新。
分发方从源码编译时用两个链接参数写入版本号与更新管理方:
go build -trimpath -ldflags "-X github.com/Mag1cFall/AIStudio2API/internal/app.version=v0.2.14-magpie.1 -X github.com/Mag1cFall/AIStudio2API/internal/app.managedBy=Magpie" -o aistudio2api ./cmd/aistudio2api| 参数 | 作用 |
|---|---|
internal/app.version |
管理端与 /api/status 显示的版本号,不写时读取 Go 构建信息 |
internal/app.managedBy |
更新管理方名称;写入后更新方式为 managed,GET /api/update 只返回当前版本与 managed_by,不访问 GitHub,POST /api/update 返回 409,“版本”页显示更新由该分发方管理 |
源码提交包含协议实现、前端源码和公开文档。本机账户状态、Cookie、token、proof、提示正文、响应正文和运行产物留在本机。