magpie-gemini-web 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/LICENSE-AISTUDIO +21 -0
  2. package/README.en.md +108 -126
  3. package/README.md +118 -136
  4. package/docs/studio-release.md +49 -0
  5. package/lib/studio-native.mjs +218 -45
  6. package/lib/studio-release.json +26 -15
  7. package/lib/studio.mjs +5 -3
  8. package/package.json +9 -2
  9. package/patches/studio-managed.patch +625 -0
  10. package/scripts/studio-archive.go +92 -0
  11. package/scripts/studio-managed-smoke.mjs +66 -0
  12. package/scripts/studio-release.mjs +85 -0
  13. package/scripts/studio.mjs +8 -4
package/README.md CHANGED
@@ -2,177 +2,159 @@
2
2
 
3
3
  中文 | [English](README.en.md)
4
4
 
5
- 让 [Magpie](https://usemagpie.ai/) 通过你的 Google 账号使用 Gemini 网页版与 Google AI Studio。插件在本机运行 [gemini-web2api-go](https://github.com/zexadev/gemini-web2api-go) 与 [AIStudio2API](https://github.com/Mag1cFall/AIStudio2API) 后端，把 Google 网页转成 OpenAI 兼容接口。
5
+ 让 [Magpie](https://usemagpie.ai/) 通过你的 Google 账号使用 **Google AI Studio** 与 **Gemini 网页版**。插件在本机自动运行 [AIStudio2API](https://github.com/Mag1cFall/AIStudio2API) 与 [gemini-web2api-go](https://github.com/zexadev/gemini-web2api-go)，将网页端能力转为 OpenAI 兼容接口。
6
6
 
7
- 插件提供两个互相独立的 Provider：
8
- - `gemini-web`：Gemini 网页版，见下面的[开始使用](#开始使用-gemini-web)；
9
- - `ai-studio`：Google AI Studio，原生工具调用，见 [Google AI Studio](#google-ai-studio-ai-studio)。
7
+ > **2026-10-16 更新**：正价支付的 Google AI Pro 现可直接在 Antigravity 中使用 `gemini-4-argon`，同理也可直接用 Magpie 反代。
10
8
 
11
- > **2026-10-16 更新**：现在正价支付的 Google AI Pro 可以直接在 Antigravity 中使用 `gemini-4-argon`，同理也可以直接用 Magpie 反代。
9
+ ## 怎么选？
12
10
 
13
- ## 开始使用 (Gemini Web)
11
+ 插件提供两个互相独立的 Provider，可按使用场景选择（也可同时配置）：
14
12
 
15
- 1. 在 Magpie 插件市场安装 **magpie-gemini-web**。
16
- 2. 登录 Gemini Web，选 **「一键配置本地 Gemini Web（推荐）」**。插件会自动下载本项目发布的优化后端、校验 SHA-256，并在后台启动；不需要安装 Go 或手动打补丁。
17
- 3. 按提示复制 Cookie，**一定要用无痕 / 隐私窗口**（推荐 Firefox）：
18
- 1. 在无痕窗口打开 <https://gemini.google.com/app>，登录要使用的 Google 账号；
19
- 2. 按 F12（macOS 按 ⌥⌘I），切到 **Network（网络）**，刷新页面；
20
- 3. 点任意一个 `gemini.google.com` 请求 → **Headers（标头）** → **Request Headers（请求标头）**；
21
- 4. 复制 `cookie` 那一行的值，粘贴回 Magpie；
22
- 5. 直接关掉无痕窗口，**不要点退出登录**（退出会让这份 Cookie 失效）。
23
- 4. 插件检测账号可用后自动完成登录。
24
-
25
- > **为什么要用无痕窗口？** 后端会定时刷新这份登录来保活。如果它和你平时用的浏览器是同一个登录会话，Google 会把会话作废，你的浏览器就会退出所有 Google 服务。无痕窗口能给后端一份独立的会话；更稳妥的做法是给后端单独用一个 Google 小号。
26
-
27
- 之后 Magpie 每次启动都会自动拉起后端，不用再管。想加更多账号，再走一遍一键配置即可。
28
-
29
- > 需要代理才能访问 Google？后端不读 `HTTP_PROXY`，请在管理面板 `http://127.0.0.1:8083/admin` 的代理池里添加（登录口令是数据目录 `secrets.json` 里的 `adminToken`）。
30
-
31
- **连接已有后端**：如果你自己运行了 gemini-web2api-go，登录时选「连接已有后端（自定义地址 + API key）」，填后端地址（以 `/v1` 结尾）和它的 `API_KEY`。
32
-
33
- ## 插件选项 (Gemini Web)
34
-
35
- 工具调用默认开启（Coding Agent 每个请求都带工具），图片输入默认关闭。需要图片输入时：
36
-
37
- ```bash
38
- magpie plugin options magpie-gemini-web '{"allowImages":true}'
39
- ```
40
-
41
- | 选项 | 默认值 | 说明 |
13
+ | 对比项 | Google AI Studio (`ai-studio`) | Gemini Web (`gemini-web`) |
42
14
  | :--- | :--- | :--- |
43
- | `allowTools` | `true` | 允许工具调用（实验性，由上游用提示词模拟）。设为 `false` 时带工具的请求会返回 400 |
44
- | `allowImages` | `false` | 允许图片输入 |
45
- | `baseURL` | `http://127.0.0.1:8083/v1` | 默认后端地址 |
46
- | `contextLimit` / `outputLimit` | `1000000` / `8192` | 向客户端声明的上下文 / 输出上限 |
47
- | `requestTimeoutMs` / `modelTimeoutMs` | `240000` / `10000` | 请求 / 拉取模型列表的超时（毫秒）。请求超时按每次等待后端计算，回复持续输出时不会被打断 |
48
- | `stripCitations` | `true` | 去掉 Gemini 在回复里加的引用标记 `[cite: 1]`、`[cite_start]`（包括工具调用参数）。让 Gemini 编辑本身含有这类文本的代码时，可以设为 `false` |
49
-
50
- ## 思考档位
15
+ | **适用场景** | **推荐 Coding Agent 使用** | 日常对话、使用网页版专属模型与额度 |
16
+ | **工具调用** | **原生 Function Calling**，稳定可靠 | 提示词模拟（实验性，Flash 系列常不调工具） |
17
+ | **思考档位** | `minimal` / `low` / `medium` / `high` 四档（`minimal` 最快最省） | `low`（普通）/ `high`（`-thinking` 扩展思考）两档 |
18
+ | **登录方式** | 弹出独立浏览器窗口直接登录 Google | 用无痕窗口登录并复制 `cookie` |
19
+ | **额度卡片** | 显示冷却中的模型与恢复时间 | 同步网页版 **5 小时** 与 **每周** 用量及重置时间 |
20
+ | **本地后端** | AIStudio2API (`v0.2.13`) | gemini-web2api-go (`4.22.0-magpie.1` 优化版) |
51
21
 
52
- 有 `-thinking` 版本的模型可以在 Magpie 里切换 `low` / `high`：`low` 用普通模型，`high` 用 `-thinking` 模型（扩展思考）。`-thinking` 模型因此不再单独列出。升级插件后执行 `magpie provider models gemini-web` 刷新模型列表。Argon 的「中」档等上游支持（[#5](https://github.com/BUKOWSKIREAL/magpie-gemini-web/issues/5)）。
22
+ ---
53
23
 
54
- ## 安全与数据
24
+ ## 快速开始
55
25
 
56
- - 后端只监听 `127.0.0.1`；Cookie 只交给本机后端，Magpie 保存的是本地生成的 API key。
57
- - 默认后端为本项目发布的 **4.22.0-magpie.1**，基于固定的上游 v4.22.0 源码应用本仓库补丁。下载和启动新进程前校验 SHA-256。支持 macOS、Linux、Windows（x64 / arm64），发布页提供源码、构建记录和校验和。
58
- - 数据目录：`~/.local/share/magpie-gemini-web`（可用 `GEMINI_WEB_DATA_DIR` 修改），日志在 `backend.log`。
59
- - 插件限制并发为 1，但无法保证账号不被 Google 风控，请自行承担风险。
26
+ 在 Magpie 插件市场安装 **magpie-gemini-web** 后，按需登录以下任一（或两个）Provider。插件会自动下载对应后端、校验 SHA-256 并在后台自启，无需安装 Go 或其它依赖。
60
27
 
61
- ## 用量
28
+ ### 方式一：Google AI Studio (`ai-studio`)
62
29
 
63
- Magpie 的额度卡片会显示 Google 账号的 **5 小时** 和 **每周** 用量与重置时间，和 <https://gemini.google.com/usage> 页面一致。每个 Google 账号单独一张卡片，标题是它的邮箱：
30
+ 1. 在 Magpie 中登录 **Google AI Studio**，选择 **「用 Google 账号登录（推荐）」**。
31
+ 2. 在弹出的独立登录窗口中登录 Google 账号（不影响日常浏览器），完成后直接关闭窗口。
32
+ > 首次使用会自动下载登录浏览器 Camoufox（约 300 MB），弹窗可能需要等几分钟才出现；请在 15 分钟内完成登录。
33
+ 3. **后续管理**：再次点击「用 Google 账号登录」，可选择**添加新账号**、为本机已有账号建卡，或为过期账号**重新登录**。
64
34
 
65
- - 一键配置添加的账号会自动成为单独的一张卡片；
66
- - 后端里已有的账号（比如旧版本添加的），在 Magpie 里给 Gemini Web 再添加一个账号，选 **「添加本地后端里已有的 Google 账号」**，从列表里选择即可。之后可以删掉旧的 `API key …` 登录，它显示的是整个账号池合在一起的用量（每个窗口取用得最多的那个账号）。
35
+ ### 方式二：Gemini Web (`gemini-web`)
67
36
 
68
- 注意：请求最终由后端在账号池里轮流挑选 Google 账号，Magpie 在几张卡片之间怎么分配请求，不决定实际用的是哪个账号。只有一键配置的本地后端能显示用量；「连接已有后端」模式下读不到账号的 Cookie。
37
+ 1. 在 Magpie 中登录 **Gemini Web**，选择 **「一键配置本地 Gemini Web（推荐）」**。
38
+ 2. 打开浏览器**无痕 / 隐私窗口**（推荐 Firefox）获取 Cookie：
39
+ 1. 访问 <https://gemini.google.com/app> 并登录 Google 账号；
40
+ 2. 按 `F12`（macOS 按 `⌥⌘I`）切到 **Network（网络）**，刷新页面；
41
+ 3. 点击任意 `gemini.google.com` 请求 → **Headers** → **Request Headers**，复制 `cookie` 的值粘贴回 Magpie；
42
+ 4. **直接关闭无痕窗口，不要点退出登录**（点退出会使 Cookie 失效）。
43
+ 3. 插件验证账号可用后即完成登录。想添加更多账号，重复上述步骤即可。
69
44
 
70
- 为了少向 Google 发请求，用量不会每次刷新都去查：账号经后端用过、或者某个窗口到了重置时间，才重新读取，两次至少间隔 10 分钟；账号闲着时最多每 6 小时读一次（顺带反映你在 Gemini 网页里的用量）。
45
+ > **为什么必须用无痕窗口？** 后端会定时刷新会话来保活。若与日常浏览器共用同一登录会话，Google 会将整个会话作废，导致你的浏览器退出所有 Google 服务。使用无痕窗口（或单独准备 Google 小号）可提供独立会话。
71
46
 
72
- 读取用量和邮箱时，走的是后端访问 Google 的同一个出口。出口不确定时不读取，卡片上会写明原因：
47
+ ---
73
48
 
74
- - 配了代理池，但账号还没绑定代理（后端在它第一次请求时绑定）；
75
- - 账号绑定的代理已停用，或者是 SOCKS 代理。
49
+ ## 多账号与额度卡片
76
50
 
77
- 所以配了代理池时，一键配置刚添加的账号暂时没有邮箱。先用它发一次请求，再用「添加本地后端里已有的 Google 账号」重新登录它，然后删掉没有邮箱的那个登录。
51
+ - **一账号一卡片**：每个 Google 账号单独生成一张以邮箱命名的额度卡片。
52
+ - *旧版迁移（Gemini Web）*：若后端里已有早期版本添加的账号，在登录时选 **「添加本地后端里已有的 Google 账号」** 即可生成独立卡片，随后可删掉旧的 `API key …` 汇总卡片。
53
+ - **账号池自动调度**：请求实际使用哪个账号由本地后端决定（Gemini Web 在账号池中轮流挑选；AI Studio 先用一个，进入冷却再切下一个）。在 Magpie 界面切换卡片不会改变后端的账号调度。
54
+ - **用量刷新说明**：
55
+ - `gemini-web`：仅一键配置的本地后端可读取用量。为减少向 Google 发请求，仅在账号被使用或窗口重置后低频刷新（最短间隔 10 分钟，闲置时最多 6 小时刷新一次）。
56
+ - `ai-studio`：AI Studio 不提供剩余总额度，卡片会展示当前账号正在冷却的模型、恢复时间或重新登录提示。
78
57
 
79
- ## 局限 (Gemini Web)
58
+ ---
80
59
 
81
- - 工具调用由上游用提示词模拟，不一定可靠，Flash 系列经常不调用工具。
82
- - 只开放 `gemini-` 开头的文本模型；`cost` 显示为 0 不代表 Google 的实际配额。
60
+ ## 配置与进阶
83
61
 
84
- ## Google AI Studio (`ai-studio`)
62
+ <details>
63
+ <summary><b>⚙️ 插件选项与代理配置</b>（开启图片输入、设置代理、连接自建后端）</summary>
85
64
 
86
- 通过 [AIStudio2API](https://github.com/Mag1cFall/AIStudio2API)（固定 v0.2.12）使用 Google AI Studio。和 Gemini Web 相比，工具调用走原生 Function Calling，思考模型可以在 Magpie 里切换 `minimal` / `low` / `medium` / `high` 四档（`minimal` 最快、最省额度），日常生成不需要浏览器。
65
+ <br>
87
66
 
88
- ### 开始使用
67
+ 工具调用默认开启，图片输入默认关闭。可通过命令行修改插件配置：
89
68
 
90
- 1. 登录 Google AI Studio，选 **「用 Google 账号登录（推荐）」**。第一次用时，插件会自动下载 AIStudio2API、校验 SHA-256 并在后台启动。
91
- 2. 在弹出的独立登录窗口里登录 Google 账号（不影响你平时用的浏览器），完成后关掉窗口即可。第一次要先下载登录用的浏览器 Camoufox（约 300 MB），窗口可能要等几分钟才出现，期间 Magpie 里没有变化；需要在 15 分钟内完成登录。
92
-
93
- 之后再选「用 Google 账号登录」，会列出：
94
-
95
- - **添加新的 Google 账号**：打开登录窗口，再加一个账号；
96
- - **本机已有的账号**：直接给它建卡片；标着「需要重新登录」的账号会打开登录窗口重新登录。
97
-
98
- 每个 Google 账号一张卡片。和 Gemini Web 一样，每个请求实际用哪个账号由本地服务决定（先用一个，冷却了再换下一个），Magpie 在卡片之间怎么切换不影响这一点。
69
+ ```bash
70
+ # 开启图片输入（对两个 Provider 生效）
71
+ magpie plugin options magpie-gemini-web '{"allowImages":true}'
99
72
 
100
- 如果你自己运行了 AIStudio2API，选 **「连接已有 AIStudio2API」**，填它的地址（默认 `http://127.0.0.1:2048/v1`）和 `PROXY_API_KEY`。
73
+ # 为 AI Studio 配置代理
74
+ magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:7890"}}'
75
+ ```
101
76
 
102
- 额度卡片：AI Studio 不提供剩余额度。卡片显示这个账号正在冷却的模型和恢复时间；账号需要重新登录时会提示。
77
+ | 选项 | 默认值 | 适用范围 | 说明 |
78
+ | :--- | :--- | :--- | :--- |
79
+ | `allowTools` | `true` | 共用（可用 `studio.allowTools` 单独覆盖） | 允许工具调用。设为 `false` 时带工具的请求返回 400 |
80
+ | `allowImages` | `false` | 共用（可用 `studio.allowImages` 单独覆盖） | 允许图片输入 |
81
+ | `requestTimeoutMs` / `modelTimeoutMs` | Web：`240000` / `10000`；Studio：`1800000` / `10000` | 共用（`studio.*` 可覆盖） | 单次等待后端 / 拉取模型列表的超时（毫秒）；收到流数据后重新计时，显式配置优先 |
82
+ | `stripCitations` | `true` | 仅 `gemini-web` | 剥离回复与工具参数中的 `[cite: 1]`、`[cite_start]` 标记（AI Studio 不支持剥离） |
83
+ | `baseURL` | `http://127.0.0.1:8083/v1` | 仅 `gemini-web` | Gemini Web 默认后端地址 |
84
+ | `contextLimit` / `outputLimit` | `1000000` / `8192` | 仅 `gemini-web` | 向客户端声明的上下文 / 输出上限 |
85
+ | `studio.proxy` | 无 | 仅 `ai-studio` | 访问 Google 的代理（`http` / `https` / `socks5`），也可用环境变量 `AI_STUDIO_PROXY` |
86
+ | `studio.baseURL` | `http://127.0.0.1:2048/v1` | 仅 `ai-studio` | 连接已有 AIStudio2API 时的默认地址 |
87
+ | `studio.contextLimit` / `studio.outputLimit` | 模型目录默认值 | 仅 `ai-studio` | 向客户端声明的上限（仅支持在目录值基础上调低） |
103
88
 
104
- ### 插件选项
89
+ **配置代理访问 Google：**
90
+ - **AI Studio**：配置上表中的 `studio.proxy` 或环境变量 `AI_STUDIO_PROXY`。
91
+ - **Gemini Web**：后端不读取 `HTTP_PROXY`，请打开本地管理面板 `http://127.0.0.1:8083/admin` 在代理池中添加（登录口令为数据目录 `secrets.json` 中的 `adminToken`）。
92
+ - *注意*：配置代理池后，新添加的账号需先发送一次请求以绑定代理，再通过「添加本地后端里已有的 Google 账号」重新添加，才能正常读取邮箱和用量（不支持通过 SOCKS 代理读取用量）。
105
93
 
106
- `allowTools`、`allowImages`、`requestTimeoutMs`、`modelTimeoutMs` 两个 Provider 共用；其余 AI Studio 选项放在 `studio` 里，根级别的 `baseURL`、`contextLimit`、`outputLimit`、`stripCitations` 只对 Gemini Web 生效。
94
+ **连接自建后端：**
95
+ 如果你自己运行了 `gemini-web2api-go` 或 `AIStudio2API`，登录时选择 **「连接已有后端 / 连接已有 AIStudio2API」**，填入以 `/v1` 结尾的地址和对应的 API Key 即可。
107
96
 
108
- ```bash
109
- magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:7890"}}'
110
- ```
97
+ **刷新模型列表：**
98
+ 升级插件后，可执行 `magpie provider models gemini-web` 刷新模型列表。
111
99
 
112
- | 选项 | 默认值 | 说明 |
113
- | :--- | :--- | :--- |
114
- | `studio.proxy` | 无 | 访问 Google 用的代理（http / https / socks5）。也可以用环境变量 `AI_STUDIO_PROXY` |
115
- | `studio.baseURL` | `http://127.0.0.1:2048/v1` | 「连接已有 AIStudio2API」的默认地址 |
116
- | `studio.contextLimit` / `studio.outputLimit` | 模型目录的值 | 向客户端声明的上限，只会调低 |
117
- | `studio.allowTools` 等 | 同根级别 | 只对 AI Studio 覆盖根级别的同名选项 |
100
+ </details>
118
101
 
119
- AI Studio 的回复保留引用标记 `[cite: 1]`，不能去掉。
102
+ <details>
103
+ <summary><b>🛠️ AI Studio 命令行工具</b>（查看状态、重新登录、离线安装）</summary>
120
104
 
121
- ### 命令行
105
+ <br>
122
106
 
123
- 插件报错里需要你运行命令时，会给出带完整路径的命令，复制即可运行。在插件目录里也可以用：
107
+ 当插件报错提示运行命令时，直接复制报错中的完整命令执行即可。在插件目录下也可使用：
124
108
 
125
109
  | 命令 | 作用 |
126
110
  | :--- | :--- |
127
- | `npm run studio:status` | 查看服务和账号状态 |
111
+ | `npm run studio:status` | 查看本地服务与账号状态 |
128
112
  | `npm run studio:start` / `studio:stop` | 启动 / 停止本地服务 |
129
113
  | `npm run studio:login` | 添加 Google 账号 |
130
- | `npm run studio:relogin -- [<账号>]` | 重新登录过期的账号（只有一个时可省略） |
131
- | `npm run studio:install -- --archive <文件>` | 用下载好的安装包离线安装 |
132
- | `node scripts/studio.mjs import <目录>` | 服务停止时导入已有账号 |
133
- | `npm run studio:smoke` | 真实请求验收（会用掉账号额度） |
134
-
135
- ### 数据与安全
136
-
137
- - 服务只监听 `127.0.0.1`，Magpie 保存的是本地生成的 API key。
138
- - 数据目录：`~/.local/share/magpie-ai-studio`（可用 `AI_STUDIO_DATA_DIR` 修改）。日志在 `backend.log`，超过 10 MB 时下次启动换新。
139
- - 第一次配置使用 2048 端口；被占用时（比如你自己也在跑 AIStudio2API）自动换一个，记在数据目录的 `config.json`。
140
- - 下载的安装包留在数据目录，重装时校验通过就不再下载。
141
- - 支持 macOS、Linux（x64 / arm64）和 Windows x64。
142
-
143
- ## macOS 原生 Task（实验性）
144
-
145
- 在 macOS 上登录时会多出一个「macOS 原生 Task（实验性）」选项：请求不走 Gemini Web 后端，而是交给本机常驻服务，由 Gemini.app 自己的 Task 模式执行，工具调用走原生的 Function Calling 通道，模型为 `gemini-task-argon`。Windows 和 Linux 上不会出现这个选项，请继续使用上面的一键配置。
146
-
147
- 当前为 Alpha：仅支持已验证的 Gemini.app 版本，选这个选项之前需要先在本机完成 setup（需要 Gemini.app 已登录，以及会话模板），只完成过一次真实 Argon 的工具往返验证，读不到额度；Agent 中途打断时，未回传结果的工具调用会占住唯一的 Task 名额最长约 4 分钟。配置步骤、会话要求和限制见 [native-task/README.md](native-task/README.md)。
148
-
149
- ## 默认优化后端与回退
150
-
151
- 从插件 **0.4.1** 起，一键配置默认使用 [4.22.0-magpie.1](https://github.com/BUKOWSKIREAL/magpie-gemini-web/releases/tag/backend-v4.22.0-magpie.1)。它包含原先需要手动编译的优化：稳定的 XSRF 缓存、主要生成与上传请求的取消传播、完整工具调用后的提前收尾、浏览器请求头，以及 Argon 返回模型校验。Google 账号仍需具备对应模型权限。
152
-
153
- **已有用户升级**：插件不会中断正在运行的后端。先停止现有后端进程（进程 ID 在数据目录的 `backend.pid`），再启动 Magpie 或发送请求；停止状态的旧官方后端会自动更新，配置、Cookie 数据库和 API key 保留。已经手动安装的本地 Argon 构建会继续复用；要切到发布版，可在停止后端后运行下面的 `backend:install`。
154
-
155
- 需要回退时，在插件目录停止后端后运行：
156
-
157
- ```bash
158
- npm run backend:install:upstream
159
- ```
160
-
161
- 这会安装经过 SHA-256 校验的官方 v4.22.0，并记住回退选择，之后自动启动也使用官方版。恢复默认优化版：
162
-
163
- ```bash
164
- npm run backend:install
165
- ```
166
-
167
- 下载失败或校验不通过时保留旧二进制。Windows 上必须先停止旧进程，才能替换正在使用的可执行文件。
168
-
169
- 源码与构建记录随后端 Release 提供。开发者使用 Git、Node 22+、Go 1.27.1，可从本仓库复现全部六个平台的构建并核对哈希：
170
-
171
- ```bash
172
- npm run backend:release:build
173
- ```
174
-
175
- 构建脚本从固定的上游提交提取干净源码、应用 `patches/argon.patch`，不会修改本地 `backend-source` 的工作内容。发布流程见 [docs/backend-release.md](docs/backend-release.md)。
114
+ | `npm run studio:relogin -- [<账号>]` | 重新登录过期账号（仅一个账号时可省略参数） |
115
+ | `npm run studio:install -- --archive <文件>` | 使用已下载的安装包离线安装 |
116
+ | `node scripts/studio.mjs import <目录>` | 在服务停止状态下导入已有账号 |
117
+ | `npm run studio:smoke` | 发起真实请求验收（会消耗账号额度） |
118
+
119
+ </details>
120
+
121
+ <details>
122
+ <summary><b>🔒 安全、数据目录与后端版本管理</b>（日志位置、升级与回退、macOS 原生 Task）</summary>
123
+
124
+ <br>
125
+
126
+ **安全与数据目录：**
127
+ - 两个后端均只监听 `127.0.0.1`，Cookie 与登录态仅保存在本机，Magpie 仅保存本地生成的随机 API Key。
128
+ - **Gemini Web 数据目录**：`~/.local/share/magpie-gemini-web`（可通过 `GEMINI_WEB_DATA_DIR` 修改），日志位于 `backend.log`。支持 macOS、Linux、Windows（x64 / arm64）。
129
+ - **AI Studio 数据目录**：`~/.local/share/magpie-ai-studio`（可通过 `AI_STUDIO_DATA_DIR` 修改），日志位于 `backend.log`（超 10 MB 下次启动自动轮转）。默认使用 2048 端口，被占用时自动顺延并记录在 `config.json`。支持 macOS、Linux（x64 / arm64）与 Windows x64。
130
+ - 插件将请求并发限制为 1，但仍无法完全排除 Google 账号风控风险，请自行评估使用。
131
+
132
+ **AI Studio 升级与模型范围：**
133
+ - 插件固定使用经过 SHA-256 校验的 `v0.2.13-magpie.1`（基于上游 `v0.2.13`），通过升级插件更新后端。同基线或更旧的官方托管后端在下次管理启动时自动升级，保留账号、端口与登录凭据。
134
+ - **托管后端已在 macOS、Linux、Windows 统一禁用在线更新**：管理页提示“请通过 Magpie 插件升级”，更新接口返回 HTTP 403，检查更新也不会访问 GitHub。用户自行连接的外部服务不受影响。补丁和可复现构建流程见 [docs/studio-release.md](docs/studio-release.md)。
135
+ - Unix 的 `package/` 仍尽力设置为 `0555`，作为额外的文件保护；权限设置失败不阻断服务，在线更新的禁用也不依赖该权限。若要手动删除数据目录来重置，请先停止服务，再运行 `chmod -R u+w "<数据目录>/package"` 恢复可写权限，然后删除；将 `<数据目录>` 替换为实际路径。
136
+ - 若自行更新到更新版或定制版，插件会提示版本冲突，并提供带正确 `--data-dir` 的 `stop`、`install`、`start` 命令。停止时会找回更新后的监听进程 PID，并核对可执行文件路径；无法核实身份就不会发送终止信号。HTTP 端口关闭但进程尚未退出时，插件不会重装或启动第二个进程。
137
+ - 已停止但文件被替换的后端会从校验通过的固定版本安装包恢复；校验失败不会启动替换文件。安装会保留账号和运行数据文件，但**不保证旧版本能读取新版迁移过的数据**。手动降级前先停止服务并备份整个数据目录（包括 `auth/`、`runtime/requests.db` 等）；已知发生数据迁移时应升级插件以匹配新版后端。
138
+ - AI Studio 后端基础请求期限为 30 分钟；插件默认单次响应等待／流空闲超时也是 30 分钟（仍可用 `studio.requestTimeoutMs` 调整）。这允许非流式长回复在服务端完整收集；后端卡死时也可能等满 30 分钟，且单 worker 会拖住后续请求。可主动取消请求或设置更短的等待时间，但较短期限可能中断正常长回复。上游自动续写的期限按其规则计算。
139
+ - 已核对本机 Magpie `v0.1.1285`（`d783df46`）源码：插件请求走 `Provider.Do → plugin.Fetch → loader.fetch`，绕过普通 HTTP transport 的 10 分钟响应头限制；此插件生成路径没有发现更短的固定总超时。网关 5 分钟 `IdleTimeout` 仅针对请求之间的空闲连接。客户端或反向代理仍可设置更短期限；这不是一次实等 30 分钟的端到端验证。
140
+ - 模型列表过滤 `-build` / `assistant_route` 模型：这类模型附带 Build 写代码助手的系统提示词，不作为普通 Agent 模型提供。升级后可执行 `magpie provider models ai-studio` 刷新列表。
141
+
142
+ **Gemini Web 优化后端升级与回退：**
143
+ - 插件默认使用本仓库发布的 [4.22.0-magpie.1](https://github.com/BUKOWSKIREAL/magpie-gemini-web/releases/tag/backend-v4.22.0-magpie.1)（基于上游 v4.22.0 集成 XSRF 缓存、请求取消传播、工具调用提前收尾与 Argon 校验补丁）。
144
+ - **旧版升级**：插件不会打断运行中的后端。先停止旧进程（PID 见数据目录 `backend.pid`），下次启动 Magpie 或发请求时会自动更新二进制并保留原有配置与账号。
145
+ - **回退官方版 / 恢复优化版**（停止后端后在插件目录执行）：
146
+ ```bash
147
+ npm run backend:install:upstream # 回退并固定使用官方 v4.22.0
148
+ npm run backend:install # 恢复默认优化版
149
+ ```
150
+ - 源码复现构建与发布流程见 [docs/backend-release.md](docs/backend-release.md)。
151
+
152
+ **macOS 原生 Task（实验性）：**
153
+ macOS 用户登录 Gemini Web 时会额外看到「macOS 原生 Task（实验性）」选项，通过本机 `Gemini.app` 的原生 Task 通道调用 `gemini-task-argon`（原生 Function Calling）。当前处于 Alpha 阶段，需预先完成本机配置，详见 [native-task/README.md](native-task/README.md)。
154
+
155
+ </details>
156
+
157
+ ---
176
158
 
177
159
  ## 友链
178
160
 
@@ -180,4 +162,4 @@ npm run backend:release:build
180
162
 
181
163
  ## 许可证
182
164
 
183
- MIT。上游 gemini-web2api-go 同为 MIT（见 `LICENSE-UPSTREAM`）。
165
+ MIT。上游 `gemini-web2api-go` 同为 MIT（见 `LICENSE-UPSTREAM`）。
package/docs/studio-release.md ADDED
@@ -0,0 +1,49 @@
1
+ # AI Studio 托管后端构建
2
+
3
+ 插件使用 `0.2.13-magpie.1`，基于 AIStudio2API `v0.2.13` 的固定 commit。上游版本、commit、Go 工具链、安装包及二进制 SHA-256 均记录在 `lib/studio-release.json`。MIT 许可见 `LICENSE-AISTUDIO`。
4
+
5
+ ## 在线更新策略
6
+
7
+ `patches/studio-managed.patch` 包含后端与管理页面修改：
8
+
9
+ - 后端移除在线更新的下载、文件替换逻辑；`GET /api/update`（包括 `?refresh=1`）仅返回本地版本及 `mode: managed`，不访问 GitHub。
10
+ - `POST /api/update` 返回 HTTP 403，提示通过 Magpie 插件升级；不替换文件、不重启。此策略无环境变量或管理页开关，在所有构建平台相同。
11
+ - 管理页版本面板显示当前版本及中英文升级提示，不提供检查更新或安装更新按钮。
12
+ - 设置明确的 `v0.2.13-magpie.1` 版本标识。插件将同基线或更旧的官方版视为需要升级；更新的官方版或不认识的定制版仍提示冲突。
13
+ - 普通插件升级、账户登录、模型调用及管理功能继续保留。用户自行连接的外部 AIStudio2API 服务不受此补丁控制。
14
+
15
+ ## 复现构建
16
+
17
+ 维护者需要 Git、tar、Node.js 26.8.2（构建页面用）、Go 1.27.1。Windows 使用 Git Bash 执行以下命令，安装包运行和解压使用 Windows 自带 PowerShell。最终用户不需要这些构建工具。
18
+
19
+ ```bash
20
+ # 按固定源代码和补丁构建所有五个平台，并核对现有 pin。
21
+ npm run studio:release:build
22
+
23
+ # 仅构建当前平台。
24
+ node scripts/studio-release.mjs --target=host --verify
25
+
26
+ # 制作新版本：审查源码/补丁后重新生成所有平台 pin。
27
+ node scripts/studio-release.mjs --write-pins
28
+
29
+ # 可复用本地上游 git 仓库，但始终导出固定 commit，不使用工作区修改。
30
+ node scripts/studio-release.mjs --source=/path/to/AIStudio2API --verify
31
+ ```
32
+
33
+ 输出在 `studio-build/release/`，不进入 npm 包。包含 macOS x64/arm64、Linux x64/arm64、Windows x64 安装包，以及构建记录、SHA256SUMS 和上游许可证。每个安装包携带许可证和托管升级说明。Go 的标准 tar/zip/gzip 写入器固定文件顺序、权限与时间；编译使用 `-trimpath -buildvcs=false`。
34
+
35
+ ## 验证与发布
36
+
37
+ ```bash
38
+ # 在独立临时数据目录中安装当前平台真实安装包，无需 Google 账号。
39
+ npm run studio:managed:smoke
40
+
41
+ # 可选：让插件离线恢复测试使用刚构建的安装包。
42
+ AI_STUDIO_TEST_ARCHIVE=/absolute/path/to/archive.tar.gz npm test
43
+ ```
44
+
45
+ 真实安装验证检查启动、版本、GET 更新状态、POST 更新返回 403、二进制及 PID 不变、管理页面无更新入口、停止与状态。`.github/workflows/studio.yml` 在五种系统/架构上重新构建、对比 SHA-256 并运行该验证；本机交叉编译不代替 Windows 真机验证。
46
+
47
+ 发布时先审查构建记录和各平台 CI 结果，再将安装包及许可证上传到本仓库 `studio-v0.2.13-magpie.1` release。该 release 可公开下载后，才能发布引用它的插件版本，否则新安装会遇到 404。构建脚本及 CI 不自动发布 release，也不发布 npm 包。
48
+
49
+ 本地试用无需发布：先停止当前托管后端，再执行 `node scripts/studio.mjs install --archive /absolute/path/to/archive` 和 `node scripts/studio.mjs start`。可用 `--data-dir` 指定目录。修改前备份账号和配置；该定制版本与上游 v0.2.13 使用相同的数据格式。