magpie-gemini-web 0.1.3 → 0.2.0

package/README.md

@@ -4,125 +4,88 @@ Gemini Web provider plugin for [Magpie](https://usemagpie.ai/)（遵循 OpenCode
 
 ---
 
-## 1. 为什么选择此方案（选型理由与架构说明）
-
-将 Gemini 网页版接入 AI Agent 工具链通常面临复杂的网页抓包协议、Cookie 会话维持及接口兼容问题。本方案采用独立原生后端 + Magpie 接入插件的解耦架构：
-
-1. **架构解耦与职责划分**：
-   - **Magpie 插件层**（本目录）：纯 JavaScript (ESM)，无第三方依赖。负责实现 Magpie / OpenCode v1 规范的认证生命周期 (`auth`)、动态模型目录发现 (`models`)、请求流式转发与输入过滤 (`forward`)。
-   - **原生后端层**（`gemini-web2api-go`）：由上游独立 Go 进程运行，负责维护 Google 账户 Cookie 会话池与 OpenAI 兼容格式转换。
-   - **凭证安全隔离**：插件与 Magpie **绝不直接接触 Google 账号 Cookie 或用户浏览器会话**，仅通过本地生成的随机 `apiKey` 与本地后端通信。
-2. **本地回环安全保护**：
-   - 上游原生后端默认配置监听 `0.0.0.0`。本插件安装助手生成的默认配置将监听地址**严格锁定为本地回环 `127.0.0.1:8083`**，避免服务与管理端端口暴露至局域网或公网。
-   - 转发层在请求到达后端前剥离调用方所有的 `Cookie`、`Authorization`、`x-api-key`、`anthropic-*` 等敏感头部。
-3. **并发抑制**：
-   - 插件声明了 `maxConcurrency: 1`。该配置旨在降低短时间内并发请求频率，但**不能保证账号绝不被 Google 风控或封禁**；用户应知悉使用网页逆向服务的潜在风险。
-4. **开源协议**：
-   - 上游项目与本插件均基于宽松的 MIT 许可证。
-
----
-
-## 2. 运行环境要求
-
-- **Node.js**：版本 `>= 22`（用于执行安装与管理脚本 `npm run backend:*` 及单元测试）。
-- **Magpie / Bun**：Magpie 客户端内置管理其插件运行环境（基于 Bun 执行插件），无需全局安装 Bun。
-- **操作系统支持**：
-  - 本项目的自动安装与启动助手（`npm run backend:install` / `backend:start`）**仅针对 macOS (arm64 Apple Silicon)** 进行了二进制锁定与 SHA-256 完整性强校验。
-  - **其他操作系统（Linux / Windows / Intel Mac）**：请**不要**将其他平台二进制放入助手目录。请直接参考上游 [gemini-web2api-go 文档](https://github.com/zexadev/gemini-web2api-go) 手动运行上游服务，并在 Magpie 登录插件时将 `baseURL` 指向上游监听地址即可。
-
----
-
-## 3. 快速上手
-
-插件与后端需要分别安装。Magpie 安装插件时不会执行安装脚本，也不会自动启动 Go 后端。先获取管理脚本：
+## 1. 快速上手（推荐：一键配置）
+
+1. 在 Magpie 插件市场搜索并安装 **magpie-gemini-web**。
+2. 在 Magpie 里登录 Gemini Web 提供商，选择 **「一键配置本地 Gemini Web（推荐）」**（命令行为 `magpie plugin login gemini-web`）。插件会：
+   - 下载官方 [gemini-web2api-go](https://github.com/zexadev/gemini-web2api-go) v4.22.0 后端，并按发布页的 SHA-256 校验，校验不通过就不安装；
+   - 生成本地随机密钥，在后台启动后端（只监听 `127.0.0.1:8083`）；
+   - 打开 <https://gemini.google.com/app>，提示你复制 Cookie：
+     1. 确认网页已登录要使用的 Google 账号；
+     2. 按 F12（macOS 按 ⌥⌘I）打开开发者工具，切到 **Network（网络）**，刷新页面；
+     3. 点任意一个 `gemini.google.com` 的请求 → **Headers（标头）** → **Request Headers（请求标头）**；
+     4. 复制 `cookie` 那一行的值，粘贴回 Magpie。
+3. 插件把 Cookie 导入本地后端并检测能否登录 Gemini；检测通过即完成登录，检测失败会删掉这条账号并提示原因（例如缺少哪些 Cookie、账号未登录）。全程不需要手动填写 API key。
+
+之后每次 Magpie 启动，插件发现本地后端没在运行就会自动把它拉起来；请求时发现后端掉线也会先重启再重试一次。后端日志在数据目录下的 `backend.log`。
+
+> 要再加一个 Google 账号，重新走一遍一键配置即可，新账号会加入后端的账号池。
+>
+> Cookie 只发给本机的后端，保存在它的本地 SQLite 数据库里；Magpie 保存的是后端的本地 API key，而不是 Cookie。
+
+需要工具调用或图片输入时再开启插件选项（默认关闭，见第 4 节）：
 ```bash
-git clone https://github.com/BUKOWSKIREAL/magpie-gemini-web.git
-cd magpie-gemini-web
+magpie plugin options magpie-gemini-web '{"allowTools":true,"allowImages":true}'
 ```
-官方后端自 v4.22.0 起已包含 `gemini-4-argon` / `gemini-4-argon-thinking`，但不核对上游实际返回的模型：无权限、Cookie 失效或配额耗尽时会被静默降级成 3.5 Flash-Lite。需要身份校验与延迟优化时，请直接按第 5 节构建补丁版后端，再完成 Cookie 配置和插件登录；不要先启动官方后端占用同一端口。
 
-### 步骤 1：安装后端二进制（macOS arm64）
+**支持的平台**：一键配置为以下平台锁定了官方二进制及其 SHA-256：macOS（Apple Silicon / Intel）、Linux（x64 / arm64）、Windows（x64 / arm64）。其他平台请用第 3 节的「连接已有后端」。
 
-运行内置下载安装脚本（锁定版本 v4.22.0，SHA-256 为 `c69ca75cf43017cf2a62dbf5c12b07f6bde66f403f714c32209b1ad350ed24c9`）：
+---
 
-```bash
-npm run backend:install
-```
+## 2. 架构与安全说明
 
-该命令将在本地数据目录（默认 `~/.local/share/magpie-gemini-web`，或通过环境变量 `GEMINI_WEB_DATA_DIR` 自定义）完成：
-1. 校验哈希并原子化安装二进制至 `bin/gemini-web2api-go`（权限 `0700`）。
-2. 初始化 `config.json`（将 host 显式绑定为 `127.0.0.1`，权限 `0600`）。
-3. 生成随机的 `apiKey` 和 `adminToken` 并写入 `secrets.json`（权限 `0600`）。
+1. **架构解耦**：
+   - **Magpie 插件层**（本仓库）：纯 JavaScript (ESM)，无第三方依赖。负责认证与一键配置、动态模型目录 (`models`)、请求转发与输入过滤 (`forward`)，以及管理本地后端进程。
+   - **原生后端层**（`gemini-web2api-go`）：上游独立 Go 进程，维护 Google 账号 Cookie 池并提供 OpenAI 兼容接口。
+2. **凭证隔离**：一键配置时插件只把你粘贴的 Cookie 交给本机后端的管理接口，自身不保存、不转发到其他地方；之后插件与 Magpie 仅凭本地随机 `apiKey` 访问后端。
+3. **本地回环**：上游默认监听 `0.0.0.0`；本插件生成的配置**锁定为 `127.0.0.1:8083`**，启动前还会再次校验 host 与二进制哈希。若 8083 已被别的服务占用，一键配置会报错而不会覆盖，可修改数据目录下 `config.json` 的 `port`。
+4. **请求过滤**：转发前剥离调用方的 `Cookie`、`Authorization`、`x-api-key`、`anthropic-*` 等头部。
+5. **并发抑制**：插件声明 `maxConcurrency: 1`，降低请求频率，但**不能保证账号不被 Google 风控或封禁**；请知悉使用网页逆向服务的风险。
+6. **开源协议**：上游项目与本插件均为 MIT 许可证。
 
-`secrets.json` 位于上述数据目录下（默认 `~/.local/share/magpie-gemini-web/secrets.json`），包含两个本地随机凭证，均与 Google 账号无关：
+**数据目录**：默认 `~/.local/share/magpie-gemini-web`（可用环境变量 `GEMINI_WEB_DATA_DIR` 自定义），包含：
 
-| 字段 | 用途 |
+| 文件 | 内容 |
 | :--- | :--- |
-| `apiKey` | 插件访问后端的密钥（`gw_` 开头），在 Magpie 登录插件时填写 |
-| `adminToken` | 后端管理面板 `http://127.0.0.1:8083/admin` 的登录口令 |
-
-只要不删除 `secrets.json`，重复执行 `backend:install` 不会重新生成这两个值；若重新生成了 `apiKey`，需要在 Magpie 中重新登录插件。
-
-### 步骤 2：启动后端服务
+| `bin/gemini-web2api-go` | 后端二进制（权限 `0700`） |
+| `config.json` | 后端配置，host 固定 `127.0.0.1`（权限 `0600`） |
+| `secrets.json` | 本地随机生成的 `apiKey`（`gw_` 开头，插件访问后端用）和 `adminToken`（管理面板 `http://127.0.0.1:8083/admin` 的口令），均与 Google 账号无关（权限 `0600`） |
+| `gemini.db` | 后端的账号与请求记录 |
+| `backend.log` / `backend.pid` | 插件在后台启动的后端的日志与进程号 |
 
+只要不删除 `secrets.json`，重新配置不会更换这两个值。要查看或管理已导入的账号，可打开管理面板，用 `adminToken` 登录；把它复制到剪贴板（macOS，不在终端显示）：
 ```bash
-npm run backend:start
+node -p "require(require('path').join(process.env.GEMINI_WEB_DATA_DIR || require('os').homedir() + '/.local/share/magpie-gemini-web', 'secrets.json')).adminToken" | tr -d '\n' | pbcopy
 ```
 
-- 该服务在前台运行，会将日志输出至终端。
-- 可在另一终端执行以下命令确认后端已监听并响应：
-  ```bash
-  npm run backend:status
-  ```
-
-> 后端成功启动并列出基础模型目录，只代表本地服务通路正常，不代表全部能力可用。2026-10-14 已通过真实 Magpie 网关验证匿名 Flash Lite 普通对话；工具调用在非流式、流式和直连后端对照中均未成功，`tool_choice` 未得到满足。上游未返回缓存 token 统计，Magpie 显示的 0 不代表 Google 的实际缓存命中情况。登录态模型需要有效 Cookie。后续 Argon 补丁已验证真实 Magpie 普通对话、SSE 和首轮工具调用；工具结果回传含正确值但未严格遵循仅回显要求，图片和 Argon 缓存未验证。本地验收记录不随公开仓库或 npm 包分发。
-
-### 步骤 3：在后端管理后台配置 Google Cookie
+---
 
-在本地浏览器中打开：
-```
-http://127.0.0.1:8083/admin
-```
-- 输入 `secrets.json` 中的 `adminToken` 登录管理面板。可用以下命令把它复制到剪贴板（macOS，不在终端显示）：
-  ```bash
-  node -p "require(require('path').join(process.env.GEMINI_WEB_DATA_DIR || require('os').homedir() + '/.local/share/magpie-gemini-web', 'secrets.json')).adminToken" | tr -d '\n' | pbcopy
-  ```
-- 在 Cookie 管理页面导入 Gemini 网页请求的完整 Cookie header；上游文档列出的关键项包括 `SID`、`HSID`、`SSID`、`APISID`、`SAPISID`、`__Secure-1PSID`、`__Secure-1PSIDTS`。仅有两个 `__Secure-*` 值未必足够。
-- **注意**：Cookie 仅保存在后端的本地 SQLite 数据库中，插件绝不存储或转发 Cookie。
+## 3. 连接已有后端（自定义地址 + API key）
 
-### 步骤 4：在 Magpie 中加载插件与登录
+已经自己运行了 gemini-web2api-go（其他机器、反向代理或自定义端口）时，登录时选 **「连接已有后端（自定义地址 + API key）」**：
 
-1. **添加插件**（npm 安装）：
-   ```bash
-   magpie plugin add magpie-gemini-web
-   ```
-   > 尚未发布到 npm 或从源码调试时可用 `magpie plugin add github:BUKOWSKIREAL/magpie-gemini-web` 或 `magpie plugin add /absolute/path/to/magpie-gemini-web`。
+- **Backend OpenAI base URL**：留空使用默认的 `http://127.0.0.1:8083/v1`，或填入你的地址（必须以 `/v1` 结尾；本地只允许 loopback HTTP，远程须 HTTPS）。
+- **API key**：后端的 `API_KEY`（不是 Google Cookie）。
 
-2. **登录提供商**：
-   ```bash
-   magpie plugin login gemini-web
-   ```
-   - **Backend OpenAI base URL**：留空使用默认的 `http://127.0.0.1:8083/v1`，或填入其他自定义本地/代理地址。
-   - **Gemini Web backend API key**：填入 `secrets.json` 中的 `apiKey`（不是 Google Cookie）。可先用以下命令把它复制到剪贴板（macOS，不在终端显示），登录时直接粘贴：
-     ```bash
-     node -p "require(require('path').join(process.env.GEMINI_WEB_DATA_DIR || require('os').homedir() + '/.local/share/magpie-gemini-web', 'secrets.json')).apiKey" | tr -d '\n' | pbcopy
-     ```
-     其他系统去掉末尾的 `| tr -d '\n' | pbcopy` 即可直接输出。
+这种方式下插件不会安装或启动任何后端，Cookie 也需要你自己在后端管理面板导入（关键项包括 `SID`、`HSID`、`SSID`、`APISID`、`SAPISID`、`__Secure-1PSID`、`__Secure-1PSIDTS`，仅有两个 `__Secure-*` 值未必足够）。
 
-   > 重新登录（例如更换 API key 或 base URL）后，正在运行的 Magpie 不会重新读取 provider 地址，需要执行 `magpie plugin off magpie-gemini-web && magpie plugin on magpie-gemini-web` 或重启 Magpie App 才会生效。
-   >
-   > 0.1.0 登录时若留空 base URL，会把空字符串存进登录信息；0.1.1 起改为存入补全后的默认地址。若遇到网关返回 502「Gemini Web has no endpoint configured」（[#3](https://github.com/BUKOWSKIREAL/magpie-gemini-web/issues/3)），升级后重新登录一次，或登录时显式填写 `http://127.0.0.1:8083/v1`。
+> 重新登录（例如更换 API key 或 base URL）后，正在运行的 Magpie 不会重新读取 provider 地址，需要执行 `magpie plugin off magpie-gemini-web && magpie plugin on magpie-gemini-web` 或重启 Magpie App 才会生效。
+>
+> 0.1.0 登录时若留空 base URL，会把空字符串存进登录信息；0.1.1 起改为存入补全后的默认地址。若遇到网关返回 502「Gemini Web has no endpoint configured」（[#3](https://github.com/BUKOWSKIREAL/magpie-gemini-web/issues/3)），升级后重新登录一次，或登录时显式填写 `http://127.0.0.1:8083/v1`。
 
-3. **配置插件选项（开启工具或图片支持）**：
-   插件默认关闭工具调用与图片输入以确保安全和兼容性。若 Coding Agent（如 Claude Code / OpenCode / Cursor）需要使用工具调用，**必须显式开启 `allowTools`**，否则发送工具请求时将被插件直接返回 400 拦截：
+### 命令行管理脚本（开发者）
 
-   ```bash
-   # 显式开启工具调用与图片输入
-   magpie plugin options magpie-gemini-web '{"allowTools":true,"allowImages":true}'
+从源码仓库也可以手动管理同一个数据目录里的后端（需要 Node.js >= 22）：
+```bash
+git clone https://github.com/BUKOWSKIREAL/magpie-gemini-web.git
+cd magpie-gemini-web
+npm run backend:install   # 下载并校验 v4.22.0 二进制，创建 config.json / secrets.json
+npm run backend:start     # 前台运行后端
+npm run backend:status    # 检查后端是否响应
+```
+用这些脚本装好的后端，一键配置会直接复用（同一套密钥），不会重复下载。
 
-   # 仅保持默认保守配置（关闭工具与图片）
-   magpie plugin options magpie-gemini-web '{"allowTools":false,"allowImages":false}'
-   ```
+> 后端成功启动并列出基础模型目录，只代表本地服务通路正常，不代表全部能力可用。2026-10-14 已通过真实 Magpie 网关验证匿名 Flash Lite 普通对话；工具调用在非流式、流式和直连后端对照中均未成功，`tool_choice` 未得到满足。上游未返回缓存 token 统计，Magpie 显示的 0 不代表 Google 的实际缓存命中情况。登录态模型需要有效 Cookie。后续 Argon 补丁已验证真实 Magpie 普通对话、SSE 和首轮工具调用；工具结果回传含正确值但未严格遵循仅回显要求，图片和 Argon 缓存未验证。本地验收记录不随公开仓库或 npm 包分发。
 
 ---
 
@@ -209,6 +172,8 @@ git -C backend-source apply ../patches/argon.patch
    npm run backend:start:argon
    ```
 
+   装好后也可以不手动启动：插件认可已安装 Argon 版的哈希，Magpie 启动时会像官方版一样在后台拉起它。若插件已在后台运行旧版后端，先结束它（`kill $(cat ~/.local/share/magpie-gemini-web/backend.pid)`）再启动，否则端口会被占用。
+
 > **版本切换提示**：如果重新执行官方标准的 `npm run backend:install`，将自动下载官方原版二进制并覆盖当前版本：Argon 模型仍可用，但不再有身份校验与延迟优化；重新执行 `npm run backend:install:argon` 即可切回 Argon 版本。
 
 ---

package/index.mjs

@@ -1,9 +1,54 @@
-import { normalizeBaseURL, settings, credentials, listModels, forward } from './lib/backend.mjs';
+import { normalizeBaseURL, settings, credentials, listModels, forward, UNREACHABLE_HEADER } from './lib/backend.mjs';
+import { ensureBackend, localBackend } from './lib/native.mjs';
+import { parseCookieInput, importCookie } from './lib/setup.mjs';
 
 const ID = 'gemini-web';
+const GEMINI_URL = 'https://gemini.google.com/app';
+
+const COOKIE_STEPS = [
+  `在浏览器打开 ${GEMINI_URL}，确认已登录要使用的 Google 账号，然后：`,
+  '1. 按 F12（macOS 按 ⌥⌘I）打开开发者工具，切到 Network（网络）面板，刷新页面',
+  '2. 点列表里任意一个 gemini.google.com 的请求 → Headers（标头）→ Request Headers（请求标头）',
+  '3. 找到 cookie 那一行，复制它的值，粘贴到下面',
+  'Cookie 只保存在本机的 Gemini Web 后端里，不会发到别处。'
+].join('\n');
+
+// managedBackend is the local backend this plugin set up, when baseURL points at it.
+function managedBackend(baseURL) {
+  const local = localBackend();
+  return local && local.baseURL === baseURL ? local : null;
+}
+
+// forwardManaged is forward(), but when the backend this plugin manages can't be reached it
+// starts the backend and tries once more.
+async function forwardManaged(input, init, getAuth, opts) {
+  const retryInput = input instanceof Request ? input.clone() : input;
+  const res = await forward(input, init, getAuth, opts);
+  if (res.headers.get(UNREACHABLE_HEADER) !== 'unreachable') return res;
+  let c;
+  try {
+    c = credentials(await getAuth(), opts);
+  } catch {
+    return res;
+  }
+  if (!managedBackend(c.baseURL)) return res;
+  try {
+    await ensureBackend();
+  } catch {
+    return res;
+  }
+  return forward(retryInput, init, getAuth, opts);
+}
 
 export const GeminiWebPlugin = async (_input, options = {}) => {
   const opts = settings(options);
+
+  // Bring a backend set up earlier back after Magpie or the computer restarts. Not awaited:
+  // requests that arrive first start it themselves through forwardManaged.
+  if (localBackend()) {
+    ensureBackend().catch(err => console.error(`[gemini-web] could not start the local backend: ${err.message}`));
+  }
+
   return {
     config: async cfg => {
       cfg.provider ??= {};
@@ -13,8 +58,29 @@ export const GeminiWebPlugin = async (_input, options = {}) => {
       provider: ID,
       maxConcurrency: 1,
       methods: [{
+        type: 'oauth',
+        label: '一键配置本地 Gemini Web（推荐）',
+        // Installs and starts the pinned backend, then takes the Gemini cookie the user pastes.
+        // The result carries the backend's own API key, so Magpie saves an API-key sign-in.
+        async authorize() {
+          const local = await ensureBackend();
+          return {
+            url: GEMINI_URL,
+            method: 'code',
+            instructions: COOKIE_STEPS,
+            async callback(code) {
+              try {
+                await importCookie(local, parseCookieInput(code));
+              } catch (err) {
+                return { type: 'failed', error: err.message };
+              }
+              return { type: 'success', key: local.apiKey, metadata: { baseURL: local.baseURL } };
+            }
+          };
+        }
+      }, {
         type: 'api',
-        label: 'Gemini Web backend API key',
+        label: '连接已有后端（自定义地址 + API key）',
         placeholder: 'Backend API key (not a Google cookie)',
         prompts: [{
           type: 'text',
@@ -43,7 +109,7 @@ export const GeminiWebPlugin = async (_input, options = {}) => {
         return {
           apiKey: c.key,
           baseURL: c.baseURL,
-          fetch: (input, init) => forward(input, init, getAuth, opts)
+          fetch: (input, init) => forwardManaged(input, init, getAuth, opts)
         };
       }
     },
@@ -51,7 +117,14 @@ export const GeminiWebPlugin = async (_input, options = {}) => {
       id: ID,
       async models(provider, { auth } = {}) {
         if (auth?.type !== 'api') return provider.models;
-        return listModels(credentials(auth, opts), opts);
+        const c = credentials(auth, opts);
+        try {
+          return await listModels(c, opts);
+        } catch (err) {
+          if (!err.unreachable || !managedBackend(c.baseURL)) throw err;
+          await ensureBackend();
+          return listModels(c, opts);
+        }
       }
     }
   };

package/lib/backend.mjs

@@ -12,6 +12,10 @@ const LOW_EFFORTS = new Set(['none', 'minimal', 'low']);
 const MODEL_CACHE_MS = 10 * 60 * 1000;
 const knownModels = new Map();
 
+// Set on the 502 forward() returns when the backend can't be reached at all, so a caller that
+// manages the backend can start it and retry.
+export const UNREACHABLE_HEADER = 'X-Gemini-Web-Backend';
+
 const KNOWN_OPTIONS = new Set([
   'baseURL',
   'allowTools',
@@ -210,6 +214,7 @@ export async function listModels(c, opts) {
   } catch (err) {
     const error = new Error('Failed to reach backend models endpoint: ' + (err?.message || err));
     error.status = 502;
+    error.unreachable = true;
     throw error;
   }
 
@@ -485,7 +490,7 @@ export async function forward(input, init, getAuth, opts) {
     if (err?.name === 'AbortError') {
       throw err;
     }
-    return makeOpenAIError(502, 'Bad gateway: failed to reach backend service');
+    return makeOpenAIError(502, 'Bad gateway: failed to reach backend service', { [UNREACHABLE_HEADER]: 'unreachable' });
   }
 
   const respHeaders = new Headers(upstreamRes.headers);

package/lib/native.mjs

@@ -4,13 +4,35 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 
-export const PINNED_SHA256 = 'c69ca75cf43017cf2a62dbf5c12b07f6bde66f403f714c32209b1ad350ed24c9';
-export const PINNED_URL = 'https://github.com/zexadev/gemini-web2api-go/releases/download/v4.22.0/gemini-web2api-go_v4.22.0_darwin_arm64';
+export const BACKEND_VERSION = 'v4.22.0';
+const RELEASE_BASE = `https://github.com/zexadev/gemini-web2api-go/releases/download/${BACKEND_VERSION}/`;
+
+// Upstream release assets by `${process.platform}-${process.arch}`, SHA-256 from the release's SHA256SUMS.txt.
+export const PINNED_BINARIES = {
+  'darwin-arm64': { asset: 'gemini-web2api-go_v4.22.0_darwin_arm64', sha256: 'c69ca75cf43017cf2a62dbf5c12b07f6bde66f403f714c32209b1ad350ed24c9' },
+  'darwin-x64': { asset: 'gemini-web2api-go_v4.22.0_darwin_amd64', sha256: '384e617bcc30aacac6b7c4e4d0490e88d282b13b29f7a0a20d645b69514cd405' },
+  'linux-x64': { asset: 'gemini-web2api-go_v4.22.0_linux_amd64', sha256: '21fcc81e0ad8ce0921e6b6c2cafce1089852530142b37e0289355c6e72df5299' },
+  'linux-arm64': { asset: 'gemini-web2api-go_v4.22.0_linux_arm64', sha256: 'f2822fa0f1a7d2b37c2bc9cbb30a95c2e8028462453a110389511408bdfd4fd7' },
+  'win32-x64': { asset: 'gemini-web2api-go_v4.22.0_windows_amd64.exe', sha256: '17e37f7e5c813b2a8d90c9a0265e6cde3bcfa4e814822af999fe8c4178f02729' },
+  'win32-arm64': { asset: 'gemini-web2api-go_v4.22.0_windows_arm64.exe', sha256: 'b42e951bfc08d7fe8bdb436dca87fc6a1b7948bb8d10e110653bcf13a790756c' }
+};
+
+export function pinnedBinary(platform = process.platform, arch = process.arch) {
+  const pin = PINNED_BINARIES[`${platform}-${arch}`];
+  if (!pin) {
+    throw new Error(`No gemini-web2api-go ${BACKEND_VERSION} build for ${platform}/${arch}. Download one manually from https://github.com/zexadev/gemini-web2api-go/releases/tag/${BACKEND_VERSION}`);
+  }
+  return { url: RELEASE_BASE + pin.asset, sha256: pin.sha256 };
+}
 
 export function getDataDir(env = process.env) {
   return env.GEMINI_WEB_DATA_DIR || path.join(os.homedir(), '.local', 'share', 'magpie-gemini-web');
 }
 
+export function binaryPath(dataDir, platform = process.platform) {
+  return path.join(dataDir, 'bin', platform === 'win32' ? 'gemini-web2api-go.exe' : 'gemini-web2api-go');
+}
+
 export function computeFileHash(filePath) {
   const content = fs.readFileSync(filePath);
   return crypto.createHash('sha256').update(content).digest('hex');
@@ -19,14 +41,11 @@ export function computeFileHash(filePath) {
 export async function installBackend(options = {}) {
   const platform = options.platform || process.platform;
   const arch = options.arch || process.arch;
-  const expectedHash = options.expectedHash || PINNED_SHA256;
-  const downloadUrl = options.url || PINNED_URL;
+  const pin = options.expectedHash && options.url ? null : pinnedBinary(platform, arch);
+  const expectedHash = options.expectedHash || pin.sha256;
+  const downloadUrl = options.url || pin.url;
   const fetchFn = options.fetchFn || globalThis.fetch;
 
-  if (platform !== 'darwin' || arch !== 'arm64') {
-    throw new Error('Automatic binary install currently supports macOS arm64 only. For other platforms, download gemini-web2api-go v4.22.0 manually from https://github.com/zexadev/gemini-web2api-go/releases/tag/v4.22.0');
-  }
-
   const dataDir = options.dataDir || getDataDir();
   fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
   fs.chmodSync(dataDir, 0o700);
@@ -35,7 +54,7 @@ export async function installBackend(options = {}) {
   fs.mkdirSync(binDir, { recursive: true, mode: 0o700 });
   fs.chmodSync(binDir, 0o700);
 
-  const binPath = path.join(binDir, 'gemini-web2api-go');
+  const binPath = binaryPath(dataDir, platform);
   let binaryReady = false;
 
   if (fs.existsSync(binPath)) {
@@ -51,7 +70,7 @@ export async function installBackend(options = {}) {
   if (!binaryReady) {
     console.log(`Downloading backend binary from ${downloadUrl}...`);
     const res = await fetchFn(downloadUrl, {
-      signal: AbortSignal.timeout(60000)
+      signal: AbortSignal.timeout(300000)
     });
     if (!res.ok) {
       throw new Error(`Failed to download binary: HTTP ${res.status}`);
@@ -78,6 +97,11 @@ export async function installBackend(options = {}) {
     }
   }
 
+  return { binPath, ...ensureDataFiles(dataDir) };
+}
+
+// ensureDataFiles creates config.json and secrets.json when missing; existing ones are kept.
+function ensureDataFiles(dataDir) {
   const configPath = path.join(dataDir, 'config.json');
   if (!fs.existsSync(configPath)) {
     const defaultConfig = {
@@ -107,16 +131,58 @@ export async function installBackend(options = {}) {
     fs.chmodSync(secretsPath, 0o600);
   }
 
-  return { binPath, configPath, secretsPath };
+  return { configPath, secretsPath };
 }
 
 export function startBackend(options = {}) {
   const dataDir = options.dataDir || getDataDir();
-  const binPath = path.join(dataDir, 'bin', 'gemini-web2api-go');
+  const expectedHash = options.expectedHash || pinnedBinary().sha256;
+  const spawnFn = options.spawnFn || spawn;
+  const { binPath, args, env } = prepareLaunch(dataDir, [expectedHash]);
+
+  const child = spawnFn(binPath, args, {
+    env,
+    stdio: 'inherit'
+  });
+
+  const onSigInt = () => child.kill('SIGINT');
+  const onSigTerm = () => child.kill('SIGTERM');
+  process.on('SIGINT', onSigInt);
+  process.on('SIGTERM', onSigTerm);
+
+  const cleanupListeners = () => {
+    process.removeListener('SIGINT', onSigInt);
+    process.removeListener('SIGTERM', onSigTerm);
+  };
+
+  child.on('error', () => {
+    cleanupListeners();
+    console.error('Failed to start backend process');
+    process.exitCode = 1;
+  });
+
+  child.on('exit', (code, signal) => {
+    cleanupListeners();
+    if (typeof options.exitFn === 'function') {
+      options.exitFn(code, signal);
+      return;
+    }
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+
+  return child;
+}
+
+// prepareLaunch checks the installed backend before it is run: a binary whose hash is one of
+// trustedHashes, a loopback-only config and well-formed secrets. It returns what to spawn.
+function prepareLaunch(dataDir, trustedHashes, platform = process.platform) {
+  const binPath = binaryPath(dataDir, platform);
   const configPath = path.join(dataDir, 'config.json');
   const secretsPath = path.join(dataDir, 'secrets.json');
-  const expectedHash = options.expectedHash || PINNED_SHA256;
-  const spawnFn = options.spawnFn || spawn;
 
   if (!fs.existsSync(binPath)) {
     throw new Error(`Binary not found at ${binPath}. Run 'npm run backend:install' first.`);
@@ -129,8 +195,8 @@ export function startBackend(options = {}) {
   }
 
   const actualHash = computeFileHash(binPath);
-  if (actualHash !== expectedHash) {
-    throw new Error(`Binary integrity verification failed: expected ${expectedHash}, got ${actualHash}`);
+  if (!trustedHashes.includes(actualHash)) {
+    throw new Error(`Binary integrity verification failed: expected ${trustedHashes.join(' or ')}, got ${actualHash}`);
   }
 
   let config;
@@ -167,41 +233,151 @@ export function startBackend(options = {}) {
     ADMIN_TOKEN: secrets.adminToken
   };
 
-  const child = spawnFn(binPath, args, {
-    env,
-    stdio: 'inherit'
-  });
+  return { binPath, args, env, port: config.port, secrets };
+}
 
-  const onSigInt = () => child.kill('SIGINT');
-  const onSigTerm = () => child.kill('SIGTERM');
-  process.on('SIGINT', onSigInt);
-  process.on('SIGTERM', onSigTerm);
+// trustedHashes is what a backend binary in dataDir may hash to: the pinned upstream build for
+// this platform, plus a local Argon build installed by `backend:install:argon`.
+function trustedHashes(dataDir, platform, arch) {
+  const hashes = [];
+  try {
+    hashes.push(pinnedBinary(platform, arch).sha256);
+  } catch {}
+  try {
+    const argon = JSON.parse(fs.readFileSync(path.join(dataDir, 'argon-build.json'), 'utf8'));
+    if (/^[a-f0-9]{64}$/.test(argon.sha256)) hashes.push(argon.sha256);
+  } catch {}
+  return hashes;
+}
 
-  const cleanupListeners = () => {
-    process.removeListener('SIGINT', onSigInt);
-    process.removeListener('SIGTERM', onSigTerm);
-  };
+function readLocalSetup(dataDir) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(dataDir, 'config.json'), 'utf8'));
+    const secrets = JSON.parse(fs.readFileSync(path.join(dataDir, 'secrets.json'), 'utf8'));
+    if (config.host !== '127.0.0.1' || !Number.isInteger(config.port) || typeof secrets.apiKey !== 'string' || typeof secrets.adminToken !== 'string') {
+      return null;
+    }
+    const origin = `http://127.0.0.1:${config.port}`;
+    return { origin, baseURL: `${origin}/v1`, apiKey: secrets.apiKey, adminToken: secrets.adminToken };
+  } catch {
+    return null;
+  }
+}
 
-  child.on('error', () => {
-    cleanupListeners();
-    console.error('Failed to start backend process');
-    process.exitCode = 1;
-  });
+// localBackend returns the backend this plugin manages in dataDir ({ origin, baseURL, apiKey,
+// adminToken }), or null when none has been set up there.
+export function localBackend(options = {}) {
+  const dataDir = options.dataDir || getDataDir();
+  const platform = options.platform || process.platform;
+  if (!fs.existsSync(binaryPath(dataDir, platform))) return null;
+  return readLocalSetup(dataDir);
+}
 
-  child.on('exit', (code, signal) => {
-    cleanupListeners();
-    if (typeof options.exitFn === 'function') {
-      options.exitFn(code, signal);
-      return;
+// backendState says whether the backend at setup answers with this setup's API key.
+async function backendState(setup, fetchFn) {
+  let res;
+  try {
+    res = await fetchFn(`${setup.baseURL}/models`, {
+      headers: { Authorization: `Bearer ${setup.apiKey}` },
+      signal: AbortSignal.timeout(2000)
+    });
+  } catch {
+    return 'down';
+  }
+  return res.ok ? 'up' : 'foreign';
+}
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+// withLock serializes setup across plugin hosts (Magpie may run more than one) by a lock file.
+async function withLock(dataDir, fn, timeoutMs) {
+  const lockPath = path.join(dataDir, '.setup.lock');
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      fs.closeSync(fs.openSync(lockPath, 'wx', 0o600));
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        if (Date.now() - fs.statSync(lockPath).mtimeMs > timeoutMs) {
+          fs.rmSync(lockPath, { force: true });
+          continue;
+        }
+      } catch {}
+      if (Date.now() > deadline) throw new Error(`Timed out waiting for another Gemini Web setup (${lockPath})`);
+      await sleep(300);
     }
-    if (signal) {
-      process.kill(process.pid, signal);
+  }
+  try {
+    return await fn();
+  } finally {
+    fs.rmSync(lockPath, { force: true });
+  }
+}
+
+// ensureBackend makes sure the local backend is installed and running, and returns how to reach
+// it. A backend already answering with this setup's key is left alone. Otherwise a missing or
+// untrusted binary is (re)installed from the pinned upstream release, config and secrets are
+// created when missing, and the backend is started in the background (logging to backend.log)
+// so it outlives the caller.
+export async function ensureBackend(options = {}) {
+  const dataDir = options.dataDir || getDataDir();
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const spawnFn = options.spawnFn || spawn;
+  const startTimeoutMs = options.startTimeoutMs ?? 20000;
+
+  let setup = readLocalSetup(dataDir);
+  if (setup && fs.existsSync(binaryPath(dataDir, platform)) && await backendState(setup, fetchFn) === 'up') {
+    return setup;
+  }
+
+  fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+  return withLock(dataDir, async () => {
+    setup = readLocalSetup(dataDir);
+    if (setup && fs.existsSync(binaryPath(dataDir, platform)) && await backendState(setup, fetchFn) === 'up') {
+      return setup;
+    }
+
+    const trusted = trustedHashes(dataDir, platform, arch);
+    const binPath = binaryPath(dataDir, platform);
+    if (!fs.existsSync(binPath) || !trusted.includes(computeFileHash(binPath))) {
+      await installBackend({ dataDir, platform, arch, fetchFn });
     } else {
-      process.exit(code ?? 0);
+      ensureDataFiles(dataDir);
+    }
+    setup = readLocalSetup(dataDir);
+    if (!setup) throw new Error(`Invalid Gemini Web backend config in ${dataDir}`);
+    if (await backendState(setup, fetchFn) === 'foreign') {
+      throw new Error(`${setup.origin} is already used by another service; change "port" in ${path.join(dataDir, 'config.json')}`);
     }
-  });
 
-  return child;
+    const launch = prepareLaunch(dataDir, trusted, platform);
+    const logPath = path.join(dataDir, 'backend.log');
+    const log = fs.openSync(logPath, 'a', 0o600);
+    try {
+      const child = spawnFn(launch.binPath, launch.args, {
+        env: launch.env,
+        detached: true,
+        stdio: ['ignore', log, log],
+        windowsHide: true
+      });
+      child.on?.('error', () => {});
+      if (child.pid) fs.writeFileSync(path.join(dataDir, 'backend.pid'), `${child.pid}\n`, { mode: 0o600 });
+      child.unref?.();
+    } finally {
+      fs.closeSync(log);
+    }
+
+    const deadline = Date.now() + startTimeoutMs;
+    while (Date.now() < deadline) {
+      if (await backendState(setup, fetchFn) === 'up') return setup;
+      await sleep(300);
+    }
+    throw new Error(`Gemini Web backend did not start within ${Math.round(startTimeoutMs / 1000)}s; see ${logPath}`);
+  }, 600000);
 }
 
 export async function statusBackend(options = {}) {

package/lib/setup.mjs

@@ -0,0 +1,129 @@
+// Sign-in helpers for the one-click setup: turn what the user pasted into a Cookie header and
+// add it to the local backend's account pool through its admin API.
+
+// The sign-in cookies a gemini.google.com request carries; without these the backend serves
+// the request anonymously (or the account check fails).
+export const REQUIRED_COOKIES = ['SID', 'HSID', 'SSID', 'APISID', 'SAPISID', '__Secure-1PSID'];
+
+// Domains whose cookies the browser sends to gemini.google.com.
+const GEMINI_COOKIE_DOMAIN = /^\.?(gemini\.)?google\.com$/i;
+
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+function pairsFromHeader(text) {
+  const pairs = [];
+  for (const part of text.split(/;|\r?\n/)) {
+    const p = part.trim();
+    const i = p.indexOf('=');
+    if (i > 0) pairs.push([p.slice(0, i).trim(), p.slice(i + 1).trim()]);
+  }
+  return pairs;
+}
+
+// DevTools › Application › Cookies rows copied as text: name, value, domain, path, … separated
+// by tabs. Only cookies for google.com / gemini.google.com are kept.
+function pairsFromTable(text) {
+  const pairs = [];
+  for (const line of text.split(/\r?\n/)) {
+    const cols = line.split('\t').map(c => c.trim());
+    if (cols.length < 3 || !COOKIE_NAME.test(cols[0]) || !cols[1]) continue;
+    if (GEMINI_COOKIE_DOMAIN.test(cols[2])) pairs.push([cols[0], cols[1]]);
+  }
+  return pairs;
+}
+
+function pairsFromJSON(text) {
+  let v;
+  try {
+    v = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (Array.isArray(v)) {
+    // Cookie-editor style exports: [{ name, value, domain }, …]
+    return v.filter(c => c && typeof c.name === 'string' && typeof c.value === 'string' &&
+      (typeof c.domain !== 'string' || GEMINI_COOKIE_DOMAIN.test(c.domain)))
+      .map(c => [c.name, c.value]);
+  }
+  if (v && typeof v === 'object') {
+    if (typeof v.cookie === 'string') return pairsFromHeader(v.cookie);
+    return Object.entries(v).filter(([, val]) => typeof val === 'string').map(([k, val]) => [k, val]);
+  }
+  return null;
+}
+
+// parseCookieInput accepts the Cookie request header (with or without the "cookie:" prefix),
+// rows copied from DevTools' cookie table, or a JSON export, and returns a "k=v; k=v" header.
+// It throws a message meant for the user when the sign-in cookies are missing.
+export function parseCookieInput(input) {
+  let text = String(input ?? '').trim().replace(/^['"]|['"]$/g, '').trim();
+  text = text.replace(/^cookie\s*:\s*/i, '');
+  if (!text) throw new Error('没有收到 Cookie：请粘贴 gemini.google.com 请求头里 cookie 一行的值');
+
+  let pairs = null;
+  if (text.startsWith('{') || text.startsWith('[')) pairs = pairsFromJSON(text);
+  if (!pairs && text.includes('\t')) pairs = pairsFromTable(text);
+  if (!pairs) pairs = pairsFromHeader(text);
+
+  const cookies = new Map();
+  for (const [name, value] of pairs) {
+    if (!COOKIE_NAME.test(name) || /[\x00-\x1f\x7f;]/.test(value) || !value) continue;
+    if (!cookies.has(name)) cookies.set(name, value);
+  }
+
+  const missing = REQUIRED_COOKIES.filter(n => !cookies.has(n));
+  if (missing.length) {
+    throw new Error(`Cookie 不完整，缺少 ${missing.join('、')}。请在开发者工具 Network 面板里，从发往 gemini.google.com 的请求的请求头复制 cookie 一行的完整值（不要从 Application 面板逐条复制）。`);
+  }
+  return [...cookies].map(([n, v]) => `${n}=${v}`).join('; ');
+}
+
+async function adminCall(setup, fetchFn, method, path, body) {
+  let res;
+  try {
+    res = await fetchFn(`${setup.origin}/admin/api/${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${setup.adminToken}`,
+        ...(body ? { 'Content-Type': 'application/json' } : {})
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      redirect: 'error',
+      signal: AbortSignal.timeout(60000)
+    });
+  } catch (err) {
+    throw new Error(`连不上本地 Gemini Web 后端（${setup.origin}）：${err?.message || err}`);
+  }
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {}
+  if (!res.ok) throw new Error(`本地后端拒绝了请求（HTTP ${res.status}）：${data.error || 'unknown error'}`);
+  return data;
+}
+
+// importCookie adds the cookie to the backend's account pool and checks it signs in. An
+// account that fails the check is removed again, and the error says why.
+export async function importCookie(setup, cookie, options = {}) {
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const label = options.label || `Magpie ${new Date().toISOString().slice(0, 10)}`;
+  const added = await adminCall(setup, fetchFn, 'POST', 'cookies', {
+    label,
+    cookie,
+    note: 'Added by Magpie one-click setup'
+  });
+  if (!Number.isInteger(added.id)) throw new Error('本地后端没有返回新账号的 id');
+
+  let check;
+  try {
+    check = await adminCall(setup, fetchFn, 'POST', `cookies/${added.id}/check`);
+  } catch (err) {
+    await adminCall(setup, fetchFn, 'DELETE', `cookies/${added.id}`).catch(() => {});
+    throw err;
+  }
+  if (!check.ok) {
+    await adminCall(setup, fetchFn, 'DELETE', `cookies/${added.id}`).catch(() => {});
+    throw new Error(`这个 Cookie 无法登录 Gemini：${check.detail || '检测未通过'}`);
+  }
+  return { id: added.id, detail: check.detail || '' };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magpie-gemini-web",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Gemini Web provider for Magpie, backed by gemini-web2api-go",
   "type": "module",
   "main": "./index.mjs",