magpie-gemini-web 0.5.3 → 0.5.5

package/README.en.md

@@ -17,7 +17,7 @@ The plugin provides two independent providers that can be used individually or t
 | **Thinking levels** | `minimal` / `low` / `medium` / `high` (`minimal` is fastest & cheapest) | `low` (base) / `high` (`-thinking` extended thinking) |
 | **Sign-in method** | Sign in directly in an isolated popup browser window | Copy `cookie` from a private/incognito window |
 | **Usage cards** | Shows models currently on cooldown and recovery times | Syncs **5-hour** & **weekly** usage and reset times from the web |
-| **Local backend** | AIStudio2API (`v0.2.13`) | gemini-web2api-go (`4.22.0-magpie.1` optimized build) |
+| **Local backend** | AIStudio2API (`v0.2.14`) | gemini-web2api-go (`4.22.0-magpie.1` optimized build) |
 
 ---
 
@@ -29,7 +29,7 @@ Install **magpie-gemini-web** from the Magpie plugin market, then sign in to eit
 
 1. Sign in to **Google AI Studio** in Magpie and choose **「用 Google 账号登录（推荐）」** (Sign in with a Google account).
 2. Sign in to your Google account in the separate login window that opens (your regular browser is unaffected), then close the window.
-   > On first run, the login browser Camoufox (~300 MB) is downloaded first, so the window may take a few minutes to appear. Complete sign-in within 15 minutes.
+   > On first run, the local service (~25 MB) and the login browser Camoufox (~300 MB) are downloaded first, so the window may take a few minutes to appear. While they download, Magpie opens a progress page in your browser. Magpie waits at most 10 minutes, downloads included, so finish signing in promptly; if GitHub is unreachable, set `studio.proxy` first (see plugin options and proxy settings below).
 3. **Managing accounts:** Choose "Sign in with a Google account" again at any time to **add a new account**, create a card for an existing local account, or **re-authenticate** an expired account.
 
 ### Option 2: Gemini Web (`gemini-web`)
@@ -74,6 +74,10 @@ magpie plugin options magpie-gemini-web '{"allowImages":true}'
 magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:7890"}}'
 ```
 
+> **Windows PowerShell**: `magpie` runs the `magpie.cmd` wrapper, which loses the double quotes inside the JSON when it passes the arguments on. Call the program behind it directly instead: it is in the same folder as `magpie.cmd` (which `where.exe magpie` finds), named something like `magpie-windows-amd64.exe`, and Magpie's Settings > Command line shows it too. How to write it depends on the PowerShell version (`$PSVersionTable.PSVersion` shows it):
+> - PowerShell 7.3 or later, default settings: `& "<full path to the program>" plugin options magpie-gemini-web '{"allowImages":true}'`
+> - Windows PowerShell 5.1 (built into Windows): it doesn't escape the double quotes in an argument for you, so write them as `\"`: `& "<full path to the program>" plugin options magpie-gemini-web '{\"allowImages\":true}'`
+
 | Option | Default | Scope | Description |
 | :--- | :--- | :--- | :--- |
 | `allowTools` | `true` | Shared (override via `studio.allowTools`) | Allow tool calls. When `false`, requests with tools return 400 |
@@ -89,8 +93,8 @@ magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:78
 **Using a proxy to reach Google:**
 - **AI Studio:** Preferably set it in the local admin page. Open the address on the usage card's "管理页" (admin page) line (default `http://127.0.0.1:2048`) and sign in as `magpie` with `adminPassword` from `config.json` in the data directory. Save the proxy, then restart the service from the admin page. The plugin keeps the saved value when it restarts the backend.
   - Alternatively, `studio.proxy` or `AI_STUDIO_PROXY` take precedence over the saved proxy. A change applies after the local service restarts (`npm run studio:stop`; the next request starts it again).
-  - With neither set, the backend falls back to the `HTTPS_PROXY` environment variable or the system proxy (Windows proxy settings).
-  - **The provider proxy set for `ai-studio` in Magpie is not passed to the local backend**; use one of the options above.
+  - With none set, the backend goes out directly, or on Windows through the system proxy (Windows proxy settings).
+  - **The backend uses neither Magpie's proxies (including the provider proxy set for `ai-studio`) nor `HTTPS_PROXY` and similar variables**: it keeps running after Magpie quits, when a proxy borrowed from Magpie may be gone. Use one of the options above. A backend started by a plugin version from before this fix may still be using a proxy from the environment it was started in (Magpie's, for example); the "代理出口" line marks it and says what a restart changes.
   - The usage card's "代理出口" (proxy) line, the Google sign-in instructions and failure messages, and `npm run studio:status` show the proxy the backend actually uses, where it comes from, and whether a new setting still needs a restart.
   - The listen address, API key and admin credentials are managed by the plugin; changing them in the admin page has no effect.
 - **Gemini Web:** The backend ignores `HTTP_PROXY`. Add your proxy to the proxy pool in the local admin panel at `http://127.0.0.1:8083/admin` (password is `adminToken` in `secrets.json` inside the data directory).
@@ -109,6 +113,11 @@ After upgrading the plugin, run `magpie provider models gemini-web` to refresh a
 
 <br>
 
+**When the local service starts and stops:**
+- It starts in the background when the plugin loads (when Magpie opens, for example); after that, a request or a usage card refresh starts it again if it isn't running.
+- It is a process of its own: **quitting Magpie doesn't stop it**, and Magpie picks it up again the next time it opens.
+- To stop it, use `studio:stop` below (or the full command the card or an error gives). A stop lasts until the next request, which starts it again.
+
 When a plugin error asks you to run a command, it includes the full ready-to-copy path. From the plugin directory, you can also run:
 
 | Command | Description |
@@ -135,8 +144,8 @@ When a plugin error asks you to run a command, it includes the full ready-to-cop
 - Concurrency is capped at 1, but Google account rate-limiting or flagging cannot be completely ruled out—use at your own risk.
 
 **AI Studio upgrades and model selection:**
-- The plugin pins SHA-256-verified `v0.2.13-magpie.1`, based on upstream `v0.2.13`. Upgrade the plugin to update the backend. Official managed releases at or below that upstream version are upgraded on the next managed startup, preserving accounts, port and sign-in credentials.
-- **Online updates are disabled in the managed backend on macOS, Linux, and Windows.** The admin page directs users to upgrade through the Magpie plugin; the update endpoint returns HTTP 403 and update checks do not contact GitHub. Independently managed external servers are unaffected. See [docs/studio-release.md](docs/studio-release.md) for the patch and reproducible build process.
+- The plugin pins SHA-256-verified `v0.2.14-magpie.1`, based on upstream `v0.2.14`. Upgrade the plugin to update the backend. Official releases at or below that upstream version, and managed backends an older plugin installed, are upgraded on the next managed startup, preserving accounts, port and sign-in credentials.
+- **Online updates are disabled in the managed backend on macOS, Linux, and Windows.** The admin page says updates are managed by magpie-gemini-web; the update endpoint returns HTTP 409 and update checks do not contact GitHub. Independently managed external servers are unaffected. See [docs/studio-release.md](docs/studio-release.md) for how the managed build is made and reproduced.
 - Managed Unix installs still attempt to set `package/` to `0555` as additional file protection. Permission failures do not block service, and disabling online updates does not depend on permissions. To reset by manually deleting the data directory, stop the service first, then run `chmod -R u+w "<data-dir>/package"` before deleting it; replace `<data-dir>` with the actual path.
 - If a newer or custom version is installed, the plugin reports a conflict with `stop`, `install`, and `start` commands carrying the correct `--data-dir`. Stop can recover a changed listener PID and verifies its executable path before signaling it. If HTTP is down but the process is still alive, the plugin refuses to reinstall or launch a second process.
 - When stopped, a replaced executable is restored from the verified pinned archive; failed verification never launches the replacement. Existing account and runtime data files are kept, but **an older backend may not read data migrated by a newer version**. Before manually downgrading, stop the service and back up the entire data directory, including `auth/` and `runtime/requests.db`. If data migration is known to have occurred, update the plugin to match the newer backend.

package/README.md

@@ -17,7 +17,7 @@
 | **思考档位** | `minimal` / `low` / `medium` / `high` 四档（`minimal` 最快最省） | `low`（普通）/ `high`（`-thinking` 扩展思考）两档 |
 | **登录方式** | 弹出独立浏览器窗口直接登录 Google | 用无痕窗口登录并复制 `cookie` |
 | **额度卡片** | 显示冷却中的模型与恢复时间 | 同步网页版 **5 小时** 与 **每周** 用量及重置时间 |
-| **本地后端** | AIStudio2API (`v0.2.13`) | gemini-web2api-go (`4.22.0-magpie.1` 优化版) |
+| **本地后端** | AIStudio2API (`v0.2.14`) | gemini-web2api-go (`4.22.0-magpie.1` 优化版) |
 
 ---
 
@@ -29,7 +29,7 @@
 
 1. 在 Magpie 中登录 **Google AI Studio**，选择 **「用 Google 账号登录（推荐）」**。
 2. 在弹出的独立登录窗口中登录 Google 账号（不影响日常浏览器），完成后直接关闭窗口。
-   > 首次使用会自动下载登录浏览器 Camoufox（约 300 MB），弹窗可能需要等几分钟才出现；请在 15 分钟内完成登录。
+   > 首次使用要先下载本地服务（约 25 MB）和登录浏览器 Camoufox（约 300 MB），弹窗可能需要等几分钟才出现。需要下载时，Magpie 会在浏览器里打开一个进度页，显示下载进度。Magpie 最多等 10 分钟（下载的时间也算在内），请尽快完成登录；连不上 GitHub 时，先按下面「插件选项与代理配置」设置 `studio.proxy`。
 3. **后续管理**：再次点击「用 Google 账号登录」，可选择**添加新账号**、为本机已有账号建卡，或为过期账号**重新登录**。
 
 ### 方式二：Gemini Web (`gemini-web`)
@@ -74,6 +74,10 @@ magpie plugin options magpie-gemini-web '{"allowImages":true}'
 magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:7890"}}'
 ```
 
+> **Windows PowerShell**：`magpie` 实际运行的是 `magpie.cmd` 包装器，它转发参数时会弄丢 JSON 里的双引号。请直接调用它背后的可执行文件：这个文件和 `magpie.cmd` 在同一个文件夹（`where.exe magpie` 可以找到），文件名可能是 `magpie-windows-amd64.exe` 之类，Magpie 的「设置 → 命令行」里也会显示。写法取决于 PowerShell 版本（用 `$PSVersionTable.PSVersion` 查看）：
+> - PowerShell 7.3 及以上，默认设置：`& "<可执行文件的完整路径>" plugin options magpie-gemini-web '{"allowImages":true}'`
+> - Windows PowerShell 5.1（系统自带）：它不会替你转义参数里的双引号，要写成 `\"`：`& "<可执行文件的完整路径>" plugin options magpie-gemini-web '{\"allowImages\":true}'`
+
 | 选项 | 默认值 | 适用范围 | 说明 |
 | :--- | :--- | :--- | :--- |
 | `allowTools` | `true` | 共用（可用 `studio.allowTools` 单独覆盖） | 允许工具调用。设为 `false` 时带工具的请求返回 400 |
@@ -89,8 +93,8 @@ magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:78
 **配置代理访问 Google：**
 - **AI Studio**：推荐在本地管理页设置。打开额度卡片「管理页」一行里的地址（默认 `http://127.0.0.1:2048`），用户名 `magpie`，密码是数据目录 `config.json` 里的 `adminPassword`；保存代理后在管理页重启服务即可生效，之后插件重启后端也不会覆盖它。
   - 也可以用上表的 `studio.proxy` 或环境变量 `AI_STUDIO_PROXY`，它们优先于管理页里保存的代理。改了要重启本地服务才生效（`npm run studio:stop`，下一次请求会自动启动）。
-  - 都没设置时，后端自动使用 `HTTPS_PROXY` 环境变量或系统代理（Windows 的「代理」设置）。
-  - **Magpie 里给 `ai-studio` 设置的供应商代理不会传给本地后端**，请用上面两种方式之一设置。
+  - 都没设置时，后端直连；Windows 上会使用系统代理（Windows 的「代理」设置）。
+  - **后端不使用 Magpie 的代理（包括给 `ai-studio` 设置的供应商代理），也不读取 `HTTPS_PROXY` 等环境变量**：它在 Magpie 退出后仍会运行，借用 Magpie 的代理到时可能已经失效。请用上面两种方式之一设置。加入这项修复之前的插件版本启动的后端，可能还在用启动时环境变量里的代理（比如 Magpie 的）；「代理出口」一行会标出来，并说明重启后会怎样。
   - 额度卡片的「代理出口」一行会显示后端当前实际使用的代理、它来自哪里，以及新设置是否还要重启才生效；登录 Google 时的说明、登录失败的提示和 `npm run studio:status` 也会显示。
   - 监听地址、API Key、管理员账号等由插件管理，在管理页修改不会生效。
 - **Gemini Web**：后端不读取 `HTTP_PROXY`，请打开本地管理面板 `http://127.0.0.1:8083/admin` 在代理池中添加（登录口令为数据目录 `secrets.json` 中的 `adminToken`）。
@@ -109,6 +113,11 @@ magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:78
 
 <br>
 
+**本地服务什么时候启动、停止：**
+- 插件加载时（例如打开 Magpie）会在后台启动本地服务；之后发请求、刷新额度卡片时，服务没在运行也会自动启动。
+- 本地服务是独立进程，**退出 Magpie 不会停止它**，下次打开 Magpie 直接接着用。
+- 停止服务用下表的 `studio:stop`（或卡片、报错里给出的完整命令）。停止只是一次性的：下一次请求会再次启动它。
+
 当插件报错提示运行命令时，直接复制报错中的完整命令执行即可。在插件目录下也可使用：
 
 | 命令 | 作用 |
@@ -135,8 +144,8 @@ magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:78
 - 插件将请求并发限制为 1，但仍无法完全排除 Google 账号风控风险，请自行评估使用。
 
 **AI Studio 升级与模型范围：**
-- 插件固定使用经过 SHA-256 校验的 `v0.2.13-magpie.1`（基于上游 `v0.2.13`），通过升级插件更新后端。同基线或更旧的官方托管后端在下次管理启动时自动升级，保留账号、端口与登录凭据。
-- **托管后端已在 macOS、Linux、Windows 统一禁用在线更新**：管理页提示“请通过 Magpie 插件升级”，更新接口返回 HTTP 403，检查更新也不会访问 GitHub。用户自行连接的外部服务不受影响。补丁和可复现构建流程见 [docs/studio-release.md](docs/studio-release.md)。
+- 插件固定使用经过 SHA-256 校验的 `v0.2.14-magpie.1`（基于上游 `v0.2.14`），通过升级插件更新后端。同基线或更旧的官方版、以及旧版插件装的托管后端，在下次管理启动时自动升级，保留账号、端口与登录凭据。
+- **托管后端已在 macOS、Linux、Windows 统一禁用在线更新**：管理页提示“更新由 magpie-gemini-web 管理”，更新接口返回 HTTP 409，检查更新也不会访问 GitHub。用户自行连接的外部服务不受影响。托管构建方式和可复现构建流程见 [docs/studio-release.md](docs/studio-release.md)。
 - Unix 的 `package/` 仍尽力设置为 `0555`，作为额外的文件保护；权限设置失败不阻断服务，在线更新的禁用也不依赖该权限。若要手动删除数据目录来重置，请先停止服务，再运行 `chmod -R u+w "<数据目录>/package"` 恢复可写权限，然后删除；将 `<数据目录>` 替换为实际路径。
 - 若自行更新到更新版或定制版，插件会提示版本冲突，并提供带正确 `--data-dir` 的 `stop`、`install`、`start` 命令。停止时会找回更新后的监听进程 PID，并核对可执行文件路径；无法核实身份就不会发送终止信号。HTTP 端口关闭但进程尚未退出时，插件不会重装或启动第二个进程。
 - 已停止但文件被替换的后端会从校验通过的固定版本安装包恢复；校验失败不会启动替换文件。安装会保留账号和运行数据文件，但**不保证旧版本能读取新版迁移过的数据**。手动降级前先停止服务并备份整个数据目录（包括 `auth/`、`runtime/requests.db` 等）；已知发生数据迁移时应升级插件以匹配新版后端。

package/docs/studio-release.md

@@ -1,29 +1,29 @@
 # AI Studio 托管后端构建
 
-插件使用 `0.2.13-magpie.1`，基于 AIStudio2API `v0.2.13` 的固定 commit。上游版本、commit、Go 工具链、安装包及二进制 SHA-256 均记录在 `lib/studio-release.json`。MIT 许可见 `LICENSE-AISTUDIO`。
+插件使用 `0.2.14-magpie.1`，基于 AIStudio2API `v0.2.14` 的固定 commit。上游版本、commit、Go 工具链、安装包及二进制 SHA-256 均记录在 `lib/studio-release.json`。`upstream.camoufox` 是这个 commit 要求的 Camoufox 版本（上游 `internal/camoufoxnative/download.go` 里的 `camoufoxRelease`），插件靠它判断登录时要不要重新下载 Camoufox；更新上游 commit 时要一起改，构建脚本发现不一致会报错。MIT 许可见 `LICENSE-AISTUDIO`。
 
 ## 在线更新策略
 
-`patches/studio-managed.patch` 包含后端与管理页面修改：
+上游从 v0.2.14 起支持由分发方管理更新，不再需要补丁。构建时通过 `-ldflags` 写入两个值：
 
-- 后端移除在线更新的下载、文件替换逻辑；`GET /api/update`（包括 `?refresh=1`）仅返回本地版本及 `mode: managed`，不访问 GitHub。
-- `POST /api/update` 返回 HTTP 403，提示通过 Magpie 插件升级；不替换文件、不重启。此策略无环境变量或管理页开关，在所有构建平台相同。
-- 管理页版本面板显示当前版本及中英文升级提示，不提供检查更新或安装更新按钮。
-- 设置明确的 `v0.2.13-magpie.1` 版本标识。插件将同基线或更旧的官方版视为需要升级；更新的官方版或不认识的定制版仍提示冲突。
-- 普通插件升级、账户登录、模型调用及管理功能继续保留。用户自行连接的外部 AIStudio2API 服务不受此补丁控制。
+- `internal/app.version=v0.2.14-magpie.1`：明确的版本标识。插件把同基线或更旧的官方版、以及更旧的托管版（`-magpie.N` 的基线更低，或同基线但 N 更小）视为需要升级；更新的官方版、更新的托管版或不认识的定制版仍提示冲突。
+- `internal/app.managedBy=magpie-gemini-web`：更新模式为 `managed`。`GET /api/update`（包括 `?refresh=1`）只返回本地版本、`mode: managed` 和 `managed_by`，不访问 GitHub；`POST /api/update` 返回 HTTP 409，说明更新由 magpie-gemini-web 管理，不下载、不替换文件、不重启。这两个值在链接时写死，没有环境变量或管理页开关，在所有构建平台相同。
+- 管理页版本面板显示当前版本和"更新由 magpie-gemini-web 管理"，不显示检查更新或安装按钮。上游的在线更新代码仍然编译在内，但托管模式下走不到；`studio:managed:smoke` 用真实二进制验证这一点。
+- 构建不带 `desktop` 标签，即上游的命令行版，不包含桌面窗口。
+- 普通插件升级、账户登录、模型调用及管理功能继续保留。用户自行连接的外部 AIStudio2API 服务不受影响。
 
 ## 复现构建
 
 维护者需要 Git、tar、Node.js 26.8.2（构建页面用）、Go 1.27.1。Windows 使用 Git Bash 执行以下命令，安装包运行和解压使用 Windows 自带 PowerShell。最终用户不需要这些构建工具。
 
 ```bash
-# 按固定源代码和补丁构建所有五个平台，并核对现有 pin。
+# 按固定源代码构建所有五个平台，并核对现有 pin。
 npm run studio:release:build
 
 # 仅构建当前平台。
 node scripts/studio-release.mjs --target=host --verify
 
-# 制作新版本：审查源码/补丁后重新生成所有平台 pin。
+# 制作新版本：审查上游源码后重新生成所有平台 pin。
 node scripts/studio-release.mjs --write-pins
 
 # 可复用本地上游 git 仓库，但始终导出固定 commit，不使用工作区修改。
@@ -42,8 +42,8 @@ npm run studio:managed:smoke
 AI_STUDIO_TEST_ARCHIVE=/absolute/path/to/archive.tar.gz npm test
 ```
 
-真实安装验证检查启动、版本、GET 更新状态、POST 更新返回 403、二进制及 PID 不变、管理页面无更新入口、停止与状态。`.github/workflows/studio.yml` 在五种系统/架构上重新构建、对比 SHA-256 并运行该验证；本机交叉编译不代替 Windows 真机验证。
+真实安装验证检查启动、版本、GET 更新状态、POST 更新返回 409、二进制及 PID 不变、管理页面显示托管提示、停止与状态。`.github/workflows/studio.yml` 在五种系统/架构上重新构建、对比 SHA-256 并运行该验证；本机交叉编译不代替 Windows 真机验证。
 
-发布时先审查构建记录和各平台 CI 结果，再将安装包及许可证上传到本仓库 `studio-v0.2.13-magpie.1` release。该 release 可公开下载后，才能发布引用它的插件版本，否则新安装会遇到 404。构建脚本及 CI 不自动发布 release，也不发布 npm 包。
+发布时先审查构建记录和各平台 CI 结果，再将安装包及许可证上传到本仓库 `studio-v0.2.14-magpie.1` release。该 release 可公开下载后，才能发布引用它的插件版本，否则新安装会遇到 404。构建脚本及 CI 不自动发布 release，也不发布 npm 包。
 
-本地试用无需发布：先停止当前托管后端，再执行 `node scripts/studio.mjs install --archive /absolute/path/to/archive` 和 `node scripts/studio.mjs start`。可用 `--data-dir` 指定目录。修改前备份账号和配置；该定制版本与上游 v0.2.13 使用相同的数据格式。
+本地试用无需发布：先停止当前托管后端，再执行 `node scripts/studio.mjs install --archive /absolute/path/to/archive` 和 `node scripts/studio.mjs start`。可用 `--data-dir` 指定目录。修改前备份账号和配置；该版本与上游 v0.2.14 使用相同的数据格式。v0.2.14 对数据的改动都是新增的（账号记录的可选字段、新的 `runtime/prompts.db`、`.env` 的新设置），用真实账号验证过：`v0.2.13-magpie.1` 的数据可以直接被它读取，用它运行过之后退回 `v0.2.13-magpie.1` 也能正常使用。

package/lib/studio-native.mjs

@@ -5,8 +5,13 @@ import crypto from 'node:crypto';
 import net from 'node:net';
 import { fileURLToPath } from 'node:url';
 import { spawn, execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
 import release from './studio-release.json' with { type: 'json' };
 
+// execFileAsync is execFile awaited: unpacking a download this way leaves the plugin host free to answer
+// meanwhile, a sign-in's progress page among others.
+const execFileAsync = promisify(execFile);
+
 export const STUDIO_VERSION = `v${release.version}`;
 export const PINNED_ARCHIVES = release.binaries;
 // The port a new setup tries first: AIStudio2API's own default.
@@ -17,6 +22,16 @@ const LOG_ROTATE_BYTES = 10 * 1024 * 1024;
 const adminSessions = new Map();
 const inFlightStarts = new Map();
 const inFlightReady = new Map();
+// setupSteps is where a start of the service stands, by data dir, while one is in flight:
+// { step: 'download', received, total } (bytes; total 0 while unknown), { step: 'install' } or
+// { step: 'start' }. A sign-in's progress page reads it (setupStep).
+const setupSteps = new Map();
+
+// setupStep is where the start of the service in dataDir stands, null when none is in flight or
+// it hasn't got to a step yet (as while it waits for another's lock).
+export function setupStep(dataDir) {
+  return setupSteps.get(dataDir) ?? null;
+}
 
 export function studioDataDir(env = process.env) {
   return env.AI_STUDIO_DATA_DIR || path.join(os.homedir(), '.local', 'share', 'magpie-ai-studio');
@@ -122,7 +137,7 @@ export function pluginProxy(explicit) {
 
 // downloadProxy is the proxy an install downloads through: the one given (an empty one turns it
 // off), else AI_STUDIO_PROXY, else the service's saved one, else the one an older config.json kept.
-function downloadProxy(dataDir, explicit, savedConfig) {
+export function downloadProxy(dataDir, explicit, savedConfig) {
   if (explicit !== undefined) return validateProxy(explicit);
   if (process.env.AI_STUDIO_PROXY !== undefined) return validateProxy(process.env.AI_STUDIO_PROXY);
   let saved;
@@ -178,9 +193,12 @@ const ENV_KEYS = [
   'WARM_WORKER_LIMIT', 'MAX_ACTIVE_WORKERS', 'WARM_STARTUP_CONCURRENCY', 'PER_ACCOUNT_CONCURRENCY',
   'ROUTING_STRATEGY', 'UPSTREAM_CHANNELS', 'MODEL_MAPPING', 'TEMPORARY_CHAT', 'WAA_BACKEND', 'AUTO_START',
   'REQUEST_BODY_LOG', 'LOG_FILE', 'LOG_MAX_TOTAL_MB', 'ADMIN_AUTH_ENABLED', 'ADMIN_USERNAME', 'ADMIN_PASSWORD',
-  'BUILD_NATIVE_NONSTREAM'
+  'BUILD_NATIVE_NONSTREAM', 'MODEL_CHANNELS', 'MEDIA_OUTPUT', 'MEDIA_BASE_URL'
 ];
 
+// PROXY_ENV are the proxy variables the service would fall back to with no PROXY of its own.
+const PROXY_ENV = ['HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY'];
+
 // SETTING_DEFAULTS are the settings the admin page owns, as a new setup has them. They are written
 // to .env when it lacks them and left as the admin page saves them after that.
 const SETTING_DEFAULTS = {
@@ -550,7 +568,8 @@ export const PROXY_SOURCES = {
   saved: '管理页',
   startup: '服务启动时的设置',
   unknown: '来源待确认',
-  system: '自动检测：HTTPS_PROXY 环境变量或系统代理',
+  system: '自动检测：系统代理设置',
+  legacy: '旧版插件启动的服务自动检测到的，可能来自启动时的环境变量或系统代理设置',
   direct: '直连'
 };
 
@@ -570,10 +589,13 @@ export function redactProxy(value) {
 // LAUNCH_RECORD says, for the service process this plugin last started, whether it was started
 // with a PROXY of the plugin's over the saved one, and whose: 'option' or 'env' (see pluginProxy),
 // null for none. A caller that doesn't know the plugin's options (the CLI) reads it from there.
+// proxyEnv 'none' says it was started with no *_PROXY in its environment (see launchStudio); a
+// record without it is an older plugin's, whose service may have had one: Magpie's, a shell's,
+// or none, which nothing kept tells apart.
 const LAUNCH_RECORD = 'backend.launch.json';
 
 function writeLaunchRecord(dataDir, pid, proxy) {
-  const record = { pid, proxy: pluginProxy(proxy)?.source ?? null };
+  const record = { pid, proxy: pluginProxy(proxy)?.source ?? null, proxyEnv: 'none' };
   try {
     fs.writeFileSync(path.join(dataDir, LAUNCH_RECORD), JSON.stringify(record) + '\n', { mode: 0o600 });
   } catch {}
@@ -637,8 +659,12 @@ export async function studioProxy(local, options = {}) {
   if (!active) source = 'direct';
   else if (unsure) source = 'unknown';
   else if (pending) source = 'startup';
-  else if (!loaded) source = 'system';
-  else source = wantedSource;
+  else if (!loaded) {
+    // An older plugin started it, maybe with a proxy in its environment, which the system's can't
+    // be told from
+    const record = launchRecord(local.dataDir);
+    source = record && record.proxyEnv !== 'none' ? 'legacy' : 'system';
+  } else source = wantedSource;
 
   return {
     active: redactProxy(active),
@@ -668,6 +694,20 @@ export function isConnectRefused(err) {
   return false;
 }
 
+// olderStudioVersion says whether a version (without its v) is one this plugin may replace: an
+// official X.Y.Z at or below the upstream base, or a managed X.Y.Z-magpie.N on an older base, or
+// on the same base with a lower N.
+function olderStudioVersion(version) {
+  const running = /^(\d+)\.(\d+)\.(\d+)(?:-magpie\.(\d+))?$/.exec(version);
+  if (!running) return false;
+  const ours = /-magpie\.(\d+)$/.exec(release.version);
+  const base = running.slice(1, 4).map(Number);
+  const expected = release.upstream.version.split('.').map(Number);
+  const different = base.findIndex((n, i) => n !== expected[i]);
+  if (different !== -1) return base[different] < expected[different];
+  return running[4] === undefined || Number(running[4]) < Number(ours[1]);
+}
+
 // checkStudioHealth says what answers on the setup's port: 'down' (nothing), 'up' (this setup's
 // service, at the pinned version), 'outdated' (an older official version),
 // 'version_conflict' (a newer or custom version installed outside this plugin),
@@ -713,20 +753,113 @@ export async function checkStudioHealth(local, fetchFn) {
     }
   }
 
-  // Official releases at or below our upstream base can move to the managed
-  // build. Newer/custom installations require an explicit recovery decision.
+  // Official releases at or below our upstream base, and managed builds older than this one, can
+  // move to this managed build. Newer/custom installations require an explicit recovery decision.
   const runningVersion = String(status.version).replace(/^v/, '');
   if (runningVersion !== release.version) {
-    const parts = /^\d+\.\d+\.\d+$/.test(runningVersion) ? runningVersion.split('.').map(Number) : null;
-    const expected = release.upstream.version.split('.').map(Number);
-    const different = parts?.findIndex((n, i) => n !== expected[i]);
-    const older = parts && (different === -1 || parts[different] < expected[different]);
+    const older = olderStudioVersion(runningVersion);
     return { state: older ? 'outdated' : 'version_conflict', status, reason: `Running version ${status.version}, expected ${STUDIO_VERSION}` };
   }
 
   return { state: 'up', status };
 }
 
+// CAMOUFOX_EXECUTABLES are where upstream's Camoufox, the browser it signs Google accounts in
+// with, has its executable in its folder, by platform (camoufoxnative.camoufoxExecutablePath).
+const CAMOUFOX_EXECUTABLES = {
+  win32: 'camoufox.exe',
+  linux: 'camoufox-bin',
+  darwin: path.join('Camoufox.app', 'Contents', 'MacOS', 'camoufox')
+};
+// How much of the end of backend.log camoufoxState reads for the download's size
+const LOG_TAIL_BYTES = 256 * 1024;
+// CAMOUFOX_VERSION is the Camoufox the pinned upstream takes (camoufoxnative.camoufoxRelease): it
+// downloads that one over any other it finds.
+export const CAMOUFOX_VERSION = release.upstream.camoufox;
+
+// camoufoxState says whether the service in dataDir has Camoufox, which it downloads (from GitHub,
+// some 300 MB) when an account first signs in and whenever the one it has isn't CAMOUFOX_VERSION:
+// { ready: true }, or how far that download has got, as upstream's camoufoxnative leaves it in
+// runtime/ under the service's working directory (dataDir): the bytes received of the archive's
+// total (0 while not known), and whether it is unpacking. One named by CAMOUFOX_PATH is the only
+// one upstream takes, and never downloads over.
+export function camoufoxState(dataDir, platform = process.platform, env = process.env) {
+  const exe = CAMOUFOX_EXECUTABLES[platform];
+  if (!exe || env.CAMOUFOX_PATH?.trim()) return { ready: true };
+  const runtime = path.join(dataDir, 'runtime');
+  const candidates = [path.join(runtime, 'camoufox', exe), path.join(dataDir, 'package', 'runtime', 'camoufox', exe)];
+  if (platform === 'win32' && env.LOCALAPPDATA) candidates.push(path.join(env.LOCALAPPDATA, 'camoufox', 'camoufox', 'Cache', exe));
+  if (candidates.some(camoufoxPinned)) return { ready: true };
+
+  let names = [];
+  try { names = fs.readdirSync(runtime); } catch {}
+  const part = names.find(n => /^camoufox-.+\.zip\.part$/.test(n));
+  let received = 0;
+  try { if (part) received = fs.statSync(path.join(runtime, part)).size; } catch {}
+  const total = camoufoxSize(path.join(dataDir, 'backend.log'));
+  return {
+    ready: false,
+    received,
+    // the log rounds the size down to a MiB
+    total: total && Math.max(total, received),
+    unpacking: names.some(n => n.startsWith('.camoufox-stage-'))
+  };
+}
+
+// camoufoxPinned says whether exe is a Camoufox upstream takes as it is: the version its
+// application.ini gives, beside it or in the app's Resources (macOS), is CAMOUFOX_VERSION
+// (camoufoxnative.validateCamoufoxExecutable).
+function camoufoxPinned(exe) {
+  try {
+    if (fs.statSync(exe).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  const dir = path.dirname(exe);
+  for (const ini of [path.join(dir, 'application.ini'), path.join(path.dirname(dir), 'Resources', 'application.ini')]) {
+    let text;
+    try {
+      text = fs.readFileSync(ini, 'utf8');
+    } catch (err) {
+      if (err.code === 'ENOENT') continue;
+      return false;
+    }
+    for (const line of text.split('\n')) {
+      const version = line.trim().match(/^Version=(.*)$/);
+      if (version) return version[1].trim() === CAMOUFOX_VERSION;
+    }
+  }
+  return false;
+}
+
+// camoufoxSize is the size of the Camoufox archive the service last began downloading, as its log
+// says it ("Camoufox 下载已开始", in whole MiB), 0 when it doesn't.
+function camoufoxSize(logPath) {
+  let tail;
+  try {
+    const fd = fs.openSync(logPath, 'r');
+    try {
+      const size = fs.fstatSync(fd).size;
+      const length = Math.min(size, LOG_TAIL_BYTES);
+      tail = Buffer.alloc(length);
+      fs.readSync(fd, tail, 0, length, size - length);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return 0;
+  }
+  const lines = tail.toString('utf8').split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].includes('Camoufox 下载已开始')) continue;
+    try {
+      const mib = JSON.parse(lines[i]).size_mib;
+      if (Number.isFinite(mib) && mib > 0) return mib * 1024 * 1024;
+    } catch {}
+  }
+  return 0;
+}
+
 export async function studioStatus(options = {}) {
   const dataDir = options.dataDir || studioDataDir();
   const platform = options.platform || process.platform;
@@ -963,6 +1096,20 @@ async function withLock(dataDir, fn, timeoutMs = 600000) {
   }
 }
 
+// downloadProgress is a download's step as curl writes it: the bytes in file so far, of the
+// Content-Length the last response in headersFile gave (the archive's, after GitHub's redirects),
+// 0 while that isn't known.
+export function downloadProgress(file, headersFile) {
+  let received = 0;
+  let total = 0;
+  try { received = fs.statSync(file).size; } catch {}
+  try {
+    const lengths = [...fs.readFileSync(headersFile, 'latin1').matchAll(/^content-length:\s*(\d+)/gim)];
+    if (lengths.length) total = Number(lengths.at(-1)[1]);
+  } catch {}
+  return { step: 'download', received, total: total >= received ? total : 0 };
+}
+
 export async function installStudio(options = {}) {
   const platform = options.platform || process.platform;
   const arch = options.arch || process.arch;
@@ -1026,6 +1173,7 @@ export async function installStudio(options = {}) {
       const downloadUrl = `https://github.com/${release.repository}/releases/download/${release.tag}/${pin.asset}`;
       archivePath = path.join(stageDir, pin.asset);
       const proxy = downloadProxy(dataDir, options.proxy, savedConfig);
+      setupSteps.set(dataDir, { step: 'download', received: 0, total: 0 });
 
       if (options.fetchFn && options.fetchFn !== globalThis.fetch) {
         const res = await options.fetchFn(downloadUrl, { signal: AbortSignal.timeout(300000) });
@@ -1044,18 +1192,26 @@ export async function installStudio(options = {}) {
         if (proxy) {
           curlArgs.push('--proxy', proxy);
         }
-        curlArgs.push('-o', archivePath, downloadUrl);
-        await new Promise((resolve, reject) => {
-          execFile('curl', curlArgs, (err, _stdout, stderr) => {
-            if (err) {
-              const status = err.code || err.status || 'failed';
-              const reason = String(stderr || '').trim().slice(0, 500);
-              reject(new Error(`Failed to download AIStudio2API archive via curl (status: ${status})${reason ? `: ${reason}` : ''}`));
-            } else {
-              resolve();
-            }
+        // The headers curl dumps as they come say the archive's size, and the file it writes says
+        // how much has come: together they show the download's progress.
+        const headersPath = path.join(stageDir, 'headers.txt');
+        curlArgs.push('-D', headersPath, '-o', archivePath, downloadUrl);
+        const watch = setInterval(() => setupSteps.set(dataDir, downloadProgress(archivePath, headersPath)), 500);
+        try {
+          await new Promise((resolve, reject) => {
+            execFile('curl', curlArgs, (err, _stdout, stderr) => {
+              if (err) {
+                const status = err.code || err.status || 'failed';
+                const reason = String(stderr || '').trim().slice(0, 500);
+                reject(new Error(`Failed to download AIStudio2API archive via curl (status: ${status})${reason ? `: ${reason}` : ''}`));
+              } else {
+                resolve();
+              }
+            });
           });
-        });
+        } finally {
+          clearInterval(watch);
+        }
         const downloadedHash = computeFileHash(archivePath);
         if (downloadedHash !== expectedHash) {
           throw new Error(`SHA256 checksum mismatch for downloaded archive: expected ${expectedHash}, got ${downloadedHash}`);
@@ -1068,11 +1224,12 @@ export async function installStudio(options = {}) {
       fs.chmodSync(retainedArchive, 0o600);
     }
 
+    setupSteps.set(dataDir, { step: 'install' });
     const extractDir = path.join(stageDir, 'extracted');
     fs.mkdirSync(extractDir, { recursive: true, mode: 0o700 });
 
     if (platform === 'win32') {
-      execFileSync('powershell', [
+      await execFileAsync('powershell', [
         '-NoProfile',
         '-NonInteractive',
         '-Command',
@@ -1082,7 +1239,7 @@ export async function installStudio(options = {}) {
         windowsHide: true
       });
     } else {
-      const listOutput = execFileSync('tar', ['-tvf', archivePath], { encoding: 'utf8' }).split('\n').filter(Boolean);
+      const listOutput = (await execFileAsync('tar', ['-tvf', archivePath], { encoding: 'utf8' })).stdout.split('\n').filter(Boolean);
       for (const line of listOutput) {
         const parts = line.split(/\s+/);
         const mode = parts[0];
@@ -1090,14 +1247,14 @@ export async function installStudio(options = {}) {
           throw new Error(`Symlinks or special files in archive rejected: ${line}`);
         }
       }
-      const listing = execFileSync('tar', ['-tf', archivePath], { encoding: 'utf8' }).split('\n').filter(Boolean);
+      const listing = (await execFileAsync('tar', ['-tf', archivePath], { encoding: 'utf8' })).stdout.split('\n').filter(Boolean);
       for (const entry of listing) {
         const entryParts = entry.replace(/\\/g, '/').split('/');
         if (entryParts.includes('..') || entry.startsWith('/') || entry.startsWith('\\') || /^[a-zA-Z]:/.test(entry)) {
           throw new Error(`Dangerous member in archive rejected: ${entry}`);
         }
       }
-      execFileSync('tar', ['-xzf', archivePath, '-C', extractDir]);
+      await execFileAsync('tar', ['-xzf', archivePath, '-C', extractDir]);
     }
 
     let topDir = extractDir;
@@ -1268,7 +1425,8 @@ function shared(map, key, fn) {
 // it to take requests; a managementOnly caller doesn't wait for the latter.
 export async function ensureStudio(options = {}) {
   const dataDir = options.dataDir || studioDataDir();
-  const { local, status } = await shared(inFlightStarts, dataDir, () => launchStudio({ ...options, dataDir }));
+  const { local, status } = await shared(inFlightStarts, dataDir,
+    () => launchStudio({ ...options, dataDir }).finally(() => setupSteps.delete(dataDir)));
   if (options.managementOnly) return local;
   return shared(inFlightReady, dataDir, () => readyStudio(local, status, options));
 }
@@ -1361,12 +1519,17 @@ async function launchStudio(options) {
     // would hide the ones saved in .env
     const cleanEnv = {};
     for (const [k, v] of Object.entries(process.env)) {
-      if (!k.startsWith('AISTUDIO_') && !k.startsWith('WAA_') && !ENV_KEYS.includes(k.toUpperCase())) {
+      if (!k.startsWith('AISTUDIO_') && !k.startsWith('WAA_') && !ENV_KEYS.includes(k.toUpperCase()) && !PROXY_ENV.includes(k.toUpperCase())) {
         cleanEnv[k] = v;
       }
     }
+    // Nor a proxy of the starter's: the service outlives Magpie, whose plugin host gives a program it
+    // starts with none of these the proxy of the request it starts in, or Magpie's own, which may be
+    // gone by the time the service uses it. Empty ones keep the host from adding its own.
+    for (const k of PROXY_ENV) cleanEnv[k] = '';
     Object.assign(cleanEnv, serviceEnv(dataDir, config, { proxy: options.proxy }));
 
+    setupSteps.set(dataDir, { step: 'start' });
     const logPath = path.join(dataDir, 'backend.log');
     rotateLog(logPath);
     const logFd = fs.openSync(logPath, 'a', 0o600);