magpie-gemini-web 0.1.0 → 0.1.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 (6) hide show
  1. package/README.md +50 -15
  2. package/index.mjs +7 -1
  3. package/lib/native.mjs +3 -3
  4. package/package.json +1 -1
  5. package/patches/argon.patch +1716 -100
  6. package/scripts/backend-argon.mjs +2 -2
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # magpie-gemini-web
2
2
 
3
- Gemini Web provider plugin for [Magpie](https://usemagpie.ai/)（遵循 OpenCode v1 插件接口规范），基于 [zexadev/gemini-web2api-go](https://github.com/zexadev/gemini-web2api-go) (v4.21.0) 独立原生后端构建。
3
+ Gemini Web provider plugin for [Magpie](https://usemagpie.ai/)（遵循 OpenCode v1 插件接口规范），基于 [zexadev/gemini-web2api-go](https://github.com/zexadev/gemini-web2api-go) (v4.22.0) 独立原生后端构建。
4
4
 
5
5
  ---
6
6
 
@@ -39,11 +39,11 @@ Gemini Web provider plugin for [Magpie](https://usemagpie.ai/)（遵循 OpenCode
39
39
  git clone https://github.com/BUKOWSKIREAL/magpie-gemini-web.git
40
40
  cd magpie-gemini-web
41
41
  ```
42
- 首次使用 Argon 请直接按第 5 节构建补丁版后端，再完成 Cookie 配置和插件登录；不要先启动官方后端占用同一端口。
42
+ 官方后端自 v4.22.0 起已包含 `gemini-4-argon` / `gemini-4-argon-thinking`，但不核对上游实际返回的模型：无权限、Cookie 失效或配额耗尽时会被静默降级成 3.5 Flash-Lite。需要身份校验与延迟优化时，请直接按第 5 节构建补丁版后端，再完成 Cookie 配置和插件登录；不要先启动官方后端占用同一端口。
43
43
 
44
44
  ### 步骤 1：安装后端二进制（macOS arm64）
45
45
 
46
- 运行内置下载安装脚本（锁定版本 v4.21.0，SHA-256 为 `f27006e6a5146a01f596235fb485d6b2118dcf90e61563f653078cbd74a63ed6`）：
46
+ 运行内置下载安装脚本（锁定版本 v4.22.0，SHA-256 为 `c69ca75cf43017cf2a62dbf5c12b07f6bde66f403f714c32209b1ad350ed24c9`）：
47
47
 
48
48
  ```bash
49
49
  npm run backend:install
@@ -54,6 +54,15 @@ npm run backend:install
54
54
  2. 初始化 `config.json`（将 host 显式绑定为 `127.0.0.1`，权限 `0600`）。
55
55
  3. 生成随机的 `apiKey` 和 `adminToken` 并写入 `secrets.json`（权限 `0600`）。
56
56
 
57
+ `secrets.json` 位于上述数据目录下（默认 `~/.local/share/magpie-gemini-web/secrets.json`），包含两个本地随机凭证，均与 Google 账号无关：
58
+
59
+ | 字段 | 用途 |
60
+ | :--- | :--- |
61
+ | `apiKey` | 插件访问后端的密钥（`gw_` 开头），在 Magpie 登录插件时填写 |
62
+ | `adminToken` | 后端管理面板 `http://127.0.0.1:8083/admin` 的登录口令 |
63
+
64
+ 只要不删除 `secrets.json`，重复执行 `backend:install` 不会重新生成这两个值；若重新生成了 `apiKey`，需要在 Magpie 中重新登录插件。
65
+
57
66
  ### 步骤 2：启动后端服务
58
67
 
59
68
  ```bash
@@ -74,7 +83,10 @@ npm run backend:start
74
83
  ```
75
84
  http://127.0.0.1:8083/admin
76
85
  ```
77
- - 输入 `secrets.json` 中的 `adminToken` 登录管理面板。
86
+ - 输入 `secrets.json` 中的 `adminToken` 登录管理面板。可用以下命令把它复制到剪贴板（macOS，不在终端显示）：
87
+ ```bash
88
+ 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
89
+ ```
78
90
  - 在 Cookie 管理页面导入 Gemini 网页请求的完整 Cookie header；上游文档列出的关键项包括 `SID`、`HSID`、`SSID`、`APISID`、`SAPISID`、`__Secure-1PSID`、`__Secure-1PSIDTS`。仅有两个 `__Secure-*` 值未必足够。
79
91
  - **注意**：Cookie 仅保存在后端的本地 SQLite 数据库中，插件绝不存储或转发 Cookie。
80
92
 
@@ -90,8 +102,16 @@ http://127.0.0.1:8083/admin
90
102
  ```bash
91
103
  magpie plugin login gemini-web
92
104
  ```
93
- - **Gemini Web backend API key**：填入 `secrets.json` 中的 `apiKey`。
94
105
  - **Backend OpenAI base URL**：留空使用默认的 `http://127.0.0.1:8083/v1`，或填入其他自定义本地/代理地址。
106
+ - **Gemini Web backend API key**：填入 `secrets.json` 中的 `apiKey`（不是 Google Cookie）。可先用以下命令把它复制到剪贴板（macOS，不在终端显示），登录时直接粘贴：
107
+ ```bash
108
+ 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
109
+ ```
110
+ 其他系统去掉末尾的 `| tr -d '\n' | pbcopy` 即可直接输出。
111
+
112
+ > 重新登录（例如更换 API key 或 base URL）后，正在运行的 Magpie 不会重新读取 provider 地址，需要执行 `magpie plugin off magpie-gemini-web && magpie plugin on magpie-gemini-web` 或重启 Magpie App 才会生效。
113
+ >
114
+ > 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`。
95
115
 
96
116
  3. **配置插件选项（开启工具或图片支持）**：
97
117
  插件默认关闭工具调用与图片输入以确保安全和兼容性。若 Coding Agent（如 Claude Code / OpenCode / Cursor）需要使用工具调用，**必须显式开启 `allowTools`**，否则发送工具请求时将被插件直接返回 400 拦截：
@@ -124,30 +144,45 @@ http://127.0.0.1:8083/admin
124
144
 
125
145
  ## 5. 本地开发与实验性 Argon 支持 (Local Development & Argon Support)
126
146
 
127
- 针对具备 Gemini 4 Argon 访问权限的账号，本项目提供了本地构建与接入支持：
147
+ 官方后端自 v4.22.0 起已支持 Gemini 4 Argon。本项目的补丁版在其基础上增加 Argon 身份校验与延迟优化，适合拥有 Argon 访问权限（付费 / Ultra）的账号：
128
148
 
129
149
  ### 5.1 架构与协议保护机制
130
- - **模型标识**：`gemini-4-argon`（固定 HexID `95a4c0abcba24364`，Mode 8，仅支持 low thinking 基础档位）。
131
- - **账号权限要求**：必须在后端管理面板配置拥有 Argon 访问权限的 Google 登录 Cookie；无 Cookie 或未获授权的账号无法使用该模型（未配 Cookie 时后端自动隐藏）。
132
- - **结构化元数据校验**：由于 Google Web 存在对未授权模型静默降级的问题，后端在底层响应解析层（`argon.go`）对 Argon 请求实行严格的结构化元数据身份校验（解析 `wrb.fr` payload 中的模型 hex 与显示名，而非依赖模型自述文本）。在确认模型身份前，Argon 响应会完整缓冲，客户端要等上游生成结束后才收到内容；一旦检测到非 Argon 标识或元数据缺失，请求将报错，不会发送未验证的内容。非 Argon 基础模型仍保持原生的真增量实时流式输出。
133
- - **协议验证状态**：已通过真实 Magpie 网关验证普通对话和 SSE；后端记录的实际模型均为 `4 Argon`。首轮工具调用名称与参数正确，第二轮含正确测试值但附带额外说明，不代表工具兼容性已完全解决。本地验收记录不随公开仓库或 npm 包分发。
150
+ - **模型标识**（模型定义来自上游 v4.22.0）：均为 HexID `95a4c0abcba24364`、Mode 8。
151
+
152
+ | 模型 | 网页思考档位 | 上游自报模型名 |
153
+ | :--- | :--- | :--- |
154
+ | `gemini-4-argon` | 低 | `4 Argon` |
155
+ | `gemini-4-argon-thinking` | 高（带 `reasoning_content`） | `4 Argon High` |
156
+
157
+ 网页端的「中」档上游尚未支持（见 [#5](https://github.com/BUKOWSKIREAL/magpie-gemini-web/issues/5)）。
158
+ - **账号权限要求**：必须在后端管理面板配置拥有 Argon 访问权限的 Google 登录 Cookie；无 Cookie 时后端自动隐藏这两个模型。
159
+ - **结构化元数据校验**：由于 Google Web 对无权限、Cookie 失效或配额耗尽的请求会静默降级，后端在底层响应解析层（`argon.go`）对 Argon 请求实行严格的结构化元数据身份校验（解析 `wrb.fr` payload 中的模型 hex 与显示名，而非依赖模型自述文本），并按请求的思考档位只接受对应的显示名（普通档 `4 Argon`、扩展思考 `4 Argon High`），档位被静默替换同样视为不符。流式请求逐帧校验：确认 Argon 身份之前的帧先暂存、不发给客户端，确认后放行并继续增量转发（实测身份与首段正文同帧到达）。身份缺失或首次出现即不符时请求报错，不发送任何未验证内容；若放行之后上游又报告了其他模型，后端立即停止读取并发送流错误，但已发出的内容无法撤回。非流式请求仍完整读取后再校验。
160
+ - **协议验证状态**：`4.22.0-argon.1` 已通过真实 Magpie 网关验证两档的普通对话和 SSE：`gemini-4-argon` 后端记录实际模型 `4 Argon`，`gemini-4-argon-thinking` 记录 `4 Argon High` 并返回 `reasoning_content`。工具调用沿用 `4.21.0-argon.2` 的结论：首轮工具调用名称与参数正确，第二轮含正确测试值但附带额外说明，不代表工具兼容性已完全解决。本地验收记录不随公开仓库或 npm 包分发。
161
+ - **延迟优化**（自 `4.21.0-argon.2` 起；2026-10-14 直连后端实测，单次样本、上游波动大，仅供参考）：
162
+ - XSRF token 按账号身份缓存，不再因每次响应刷新 SIDCC 而失效，登录态请求的前置开销由约 0.9–1.3 秒降至约 10 毫秒；Cookie 轮转后在后台重取 token。
163
+ - Argon 流式首字约 5.4 秒（同次总耗时 9.8 秒），不再等待整段生成结束。
164
+ - 工具调用块闭合且函数名有效时即结束读取上游并返回 `tool_calls`，Argon 首轮工具调用约 6.1 秒。
165
+ - 超过 `max_prompt_bytes` 的请求转附件时，工具定义（紧凑 JSON）与末尾格式提醒保留在正文，附件只含对话历史；158KB 带工具请求实测可正确发起工具调用并回传结果。
166
+ - 客户端断开或超时后，后端中止上游读取、上传与重试等待，并在请求记录中记为 499。
134
167
 
135
168
  ### 5.2 本地构建与安装步骤 (macOS arm64)
136
169
 
137
170
  需要 upstream `go.mod` 声明的 Go 版本（Go 1.26+）与 Git。从插件根目录执行：
138
171
  ```bash
139
172
  git clone https://github.com/zexadev/gemini-web2api-go.git backend-source
140
- git -C backend-source checkout 93d9b384b2453c495942080f5838b8e71d6c1e6f
173
+ git -C backend-source checkout a65b1d1a5ac614c1b455857334b4f1c73ab8fcfb
141
174
  git -C backend-source apply ../patches/argon.patch
142
175
  ```
143
176
 
144
- 源码基于 upstream tag `v4.21.0`（锁定 commit `93d9b384b2453c495942080f5838b8e71d6c1e6f`）：
177
+ 源码基于 upstream tag `v4.22.0`（锁定 commit `a65b1d1a5ac614c1b455857334b4f1c73ab8fcfb`）。
178
+
179
+ > **从 `4.21.0-argon.*` 升级**：旧补丁新增的文件会与新补丁冲突，请删除 `backend-source/` 后按上面三行重新获取源码，再从下方第 1 步开始。
145
180
 
146
181
  1. **构建 Argon 增强版后端**：
147
182
  ```bash
148
183
  npm run backend:build:argon
149
184
  ```
150
- 该命令将在 `backend-source/` 目录执行 Go 编译，并在 `backend-build/` 生成校验清单 `manifest.json` 与二进制（版本 `4.21.0-argon.1`）。
185
+ 该命令将在 `backend-source/` 目录执行 Go 编译，并在 `backend-build/` 生成校验清单 `manifest.json` 与二进制（版本 `4.22.0-argon.1`）。
151
186
 
152
187
  2. **安装到本地数据目录**：
153
188
  ```bash
@@ -160,7 +195,7 @@ git -C backend-source apply ../patches/argon.patch
160
195
  npm run backend:start:argon
161
196
  ```
162
197
 
163
- > **版本切换提示**：如果重新执行官方标准的 `npm run backend:install`，将自动下载官方原版二进制并覆盖当前版本，Argon 模型将暂时不可用；重新执行 `npm run backend:install:argon` 即可切回 Argon 版本。
198
+ > **版本切换提示**：如果重新执行官方标准的 `npm run backend:install`，将自动下载官方原版二进制并覆盖当前版本：Argon 模型仍可用，但不再有身份校验与延迟优化；重新执行 `npm run backend:install:argon` 即可切回 Argon 版本。
164
199
 
165
200
  ---
166
201
 
@@ -168,7 +203,7 @@ git -C backend-source apply ../patches/argon.patch
168
203
 
169
204
  1. **实验性工具调用（Prompt Emulation）**：
170
205
  - Gemini 网页版无原生 OpenAI 格式 Function Calling 协议，上游通过系统提示词模拟实现。
171
- - 模拟工具调用会导致响应非增量，且准确度受模型指令遵循能力影响。
206
+ - 工具调用块需要完整解析后才以 `tool_calls` 返回（块外正文仍实时流式输出），准确度受模型指令遵循能力影响；实测 Flash 系列经常拒绝调用模拟工具。
172
207
  - 默认配置下（`allowTools: false`），若请求包含 `tools` 或 `functions`，插件会直接拒绝并返回 400 提示，绝不静默剥离工具参数。
173
208
  2. **媒体输入类型限制**：
174
209
  - 即使开启 `allowImages: true`，插件也仅允许 `text` 与包含有效 URL 的 `image_url`，其他媒体类型（如 `input_audio` 等）将被严格拒绝。
package/index.mjs CHANGED
@@ -28,7 +28,13 @@ export const GeminiWebPlugin = async (_input, options = {}) => {
28
28
  return e.message;
29
29
  }
30
30
  }
31
- }]
31
+ }],
32
+ // Magpie stores raw prompt inputs as metadata unless authorize returns its own;
33
+ // write the resolved URL so a blank answer doesn't persist as baseURL: "".
34
+ authorize: async inputs => ({
35
+ type: 'success',
36
+ metadata: { baseURL: normalizeBaseURL(inputs?.baseURL || opts.baseURL) }
37
+ })
32
38
  }],
33
39
  async loader(getAuth) {
34
40
  const auth = await getAuth();
package/lib/native.mjs CHANGED
@@ -4,8 +4,8 @@ import os from 'node:os';
4
4
  import crypto from 'node:crypto';
5
5
  import { spawn } from 'node:child_process';
6
6
 
7
- export const PINNED_SHA256 = 'f27006e6a5146a01f596235fb485d6b2118dcf90e61563f653078cbd74a63ed6';
8
- export const PINNED_URL = 'https://github.com/zexadev/gemini-web2api-go/releases/download/v4.21.0/gemini-web2api-go_v4.21.0_darwin_arm64';
7
+ export const PINNED_SHA256 = 'c69ca75cf43017cf2a62dbf5c12b07f6bde66f403f714c32209b1ad350ed24c9';
8
+ export const PINNED_URL = 'https://github.com/zexadev/gemini-web2api-go/releases/download/v4.22.0/gemini-web2api-go_v4.22.0_darwin_arm64';
9
9
 
10
10
  export function getDataDir(env = process.env) {
11
11
  return env.GEMINI_WEB_DATA_DIR || path.join(os.homedir(), '.local', 'share', 'magpie-gemini-web');
@@ -24,7 +24,7 @@ export async function installBackend(options = {}) {
24
24
  const fetchFn = options.fetchFn || globalThis.fetch;
25
25
 
26
26
  if (platform !== 'darwin' || arch !== 'arm64') {
27
- throw new Error('Automatic binary install currently supports macOS arm64 only. For other platforms, download gemini-web2api-go v4.21.0 manually from https://github.com/zexadev/gemini-web2api-go/releases/tag/v4.21.0');
27
+ 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');
28
28
  }
29
29
 
30
30
  const dataDir = options.dataDir || getDataDir();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "magpie-gemini-web",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Gemini Web provider for Magpie, backed by gemini-web2api-go",
5
5
  "type": "module",
6
6
  "main": "./index.mjs",