gemini-cli-leo 0.1.30-pre.3 → 0.1.30
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.
- package/docs/openai-provider-env-shadowing.md +502 -0
- package/docs/sidebar.json +4 -0
- package/gemini.mjs +423 -203
- package/package.json +1 -1
|
@@ -0,0 +1,502 @@
|
|
|
1
|
+
# OpenAI Provider 选择失败:环境变量遮蔽与错误归因缺陷
|
|
2
|
+
|
|
3
|
+
> 记录一次已复现并**已修复**的故障:在 `~/git/test` 下运行
|
|
4
|
+
> `gemini-leo`,选择 OpenAI 方式并挑选 provider `linksub-008`,报错
|
|
5
|
+
>
|
|
6
|
+
> ```
|
|
7
|
+
> Failed to use provider "linksub-008":
|
|
8
|
+
> Provider "ytoken-01" references the environment variable
|
|
9
|
+
> YTOKEN_01_API_KEY, which is not set.
|
|
10
|
+
> ```
|
|
11
|
+
>
|
|
12
|
+
> 报错里提到的 provider
|
|
13
|
+
> **不是**用户选择的那个。本文记录根因、复现证据,以及三处缺陷的修复实现与验证结果。
|
|
14
|
+
|
|
15
|
+
- 仓库:`~/git/gemini-cli`
|
|
16
|
+
- 版本:`0.67.0-nightly.20261020.gb041de017`(HEAD `41738191b`)
|
|
17
|
+
- 已安装产物:`/data/data/com.termux/files/usr/lib/node_modules/gemini-cli-leo/gemini.mjs`
|
|
18
|
+
- 环境:Termux / Android,Node v26.4.0
|
|
19
|
+
- 复现日期:2026-11-14
|
|
20
|
+
- **修复日期:2026-11-14**
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 1. 结论摘要
|
|
25
|
+
|
|
26
|
+
单个报错由 **三个独立缺陷叠加** 造成。按因果顺序:
|
|
27
|
+
|
|
28
|
+
| # | 缺陷 | 位置 | 后果 | 状态 |
|
|
29
|
+
| --- | ----------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------- | --------- |
|
|
30
|
+
| 1 | 项目 `.env` 遮蔽用户级 `.env`,不合并 | `packages/cli/src/config/settings.ts:607` `findEnvFile()` | 7 个 provider 的 key 全部不可见 | ✅ 已修复 |
|
|
31
|
+
| 2 | 会话级 provider 解析失败后吞掉原始错误,降级到第 0 条 | `packages/core/src/core/openai/integration.ts:172-188` | 报错归因到 `ytoken-01`;成功时还会**静默换端点** | ✅ 已修复 |
|
|
32
|
+
| 3 | 认证门只看第 0 条,且忽略持久化的 `openAiProviderId` | `integration.ts:246` + `packages/cli/src/config/auth.ts:45,110` | 配置完好也会退化成 "must specify GEMINI_OPENAI_BASE_URL" | ✅ 已修复 |
|
|
33
|
+
|
|
34
|
+
其中
|
|
35
|
+
**缺陷 2 是导致"报错说 ytoken-01"的直接原因**,缺陷 1 是让它被触发的条件。三者的修复实现见第 5 节。
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 2. 触发链详解
|
|
40
|
+
|
|
41
|
+
### 2.1 缺陷 1:项目 `.env` 整体遮蔽用户级 `.env`
|
|
42
|
+
|
|
43
|
+
`findEnvFile()` 自下而上(cwd → 家目录)查找,**命中第一个即返回,不做合并**:
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
// packages/cli/src/config/settings.ts:607
|
|
47
|
+
function findEnvFile(startDir, isTrusted, ignoreLocalEnv): string | null {
|
|
48
|
+
let currentDir = path.resolve(startDir);
|
|
49
|
+
while (true) {
|
|
50
|
+
if (isTrusted) {
|
|
51
|
+
const geminiEnvPath = path.join(currentDir, GEMINI_DIR, '.env');
|
|
52
|
+
if (fs.existsSync(geminiEnvPath)) return geminiEnvPath;
|
|
53
|
+
}
|
|
54
|
+
const envPath = path.join(currentDir, '.env'); // ← 先命中项目级
|
|
55
|
+
if (fs.existsSync(envPath)) {
|
|
56
|
+
if (!ignoreLocalEnv || currentDir === homedir()) return envPath;
|
|
57
|
+
}
|
|
58
|
+
// ... 只有一路走到家目录才会回落 ~/.gemini/.env
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
当前实际的文件布局与内容:
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
~/git/test/.env ← 69 字节,只有一行 NGROK_AUTHTOKEN=<已脱敏>
|
|
67
|
+
~/.gemini/.env ← 834 字节,7 个 provider 的 key 全在这里
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`~/git/test/.env` 一旦存在就立即返回,`~/.gemini/.env`
|
|
71
|
+
**永远读不到**。因此在该目录下:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
$ cd ~/git/test && node -e '...findEnvFile...'
|
|
75
|
+
chosen .env -> /data/data/com.termux/files/home/git/test/.env
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
验证(把 key 从 shell 环境剥离后,模拟干净启动):
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
$ env -i HOME=$HOME PATH=$PATH bash -lc 'env | grep -c "YTOKEN_01_API_KEY\|LINKSUB_008_API_KEY"'
|
|
82
|
+
0
|
|
83
|
+
fresh shell: 0 keys
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
也就是说 `.env` 是这些 key 的**唯一来源**;被遮蔽后它们全部缺失。
|
|
87
|
+
|
|
88
|
+
### 2.2 缺陷 2:错误归因到别的 provider(直接原因)
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
// packages/core/src/core/openai/integration.ts:160
|
|
92
|
+
export function resolveActiveProvider(options) {
|
|
93
|
+
const { requestedId, sessionProviderId, env, allowImplicitProvider } =
|
|
94
|
+
options;
|
|
95
|
+
const choice = requestedId ?? sessionProviderId;
|
|
96
|
+
// ...
|
|
97
|
+
if (choice) {
|
|
98
|
+
try {
|
|
99
|
+
return resolveProvider(choice, undefined, env); // ← linksub-008 在此抛错
|
|
100
|
+
} catch (error) {
|
|
101
|
+
// 只有 caller 显式指定的 id 才重新抛出
|
|
102
|
+
if (requestedId !== undefined) {
|
|
103
|
+
throw error;
|
|
104
|
+
}
|
|
105
|
+
// ← sessionProviderId 走到这里:真实错误被丢弃
|
|
106
|
+
return resolveImplicitProvider(sessionProviderId, env); // 降级去解析 providers[0]
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
// ...
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`AppContainer.tsx:1217` 的 `activateOpenAiProvider()` 调用顺序是:
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
config.setActiveOpenAiProvider(providerId); // 记为 session 选择
|
|
117
|
+
await config.refreshAuth(AuthType.USE_OPENAI); // 内部走 resolveActiveProvider({ sessionProviderId })
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
即传的是 **`sessionProviderId`**,不是 `requestedId`。于是:
|
|
121
|
+
|
|
122
|
+
1. `resolveProvider('linksub-008')` 抛 `LINKSUB_008_API_KEY 未设置`;
|
|
123
|
+
2. 该错误被 `catch` 吞掉(因为 `requestedId === undefined`);
|
|
124
|
+
3. 降级调用 `resolveImplicitProvider()` → `resolveProvider(undefined)` →
|
|
125
|
+
**`providers[0]` = `ytoken-01`**;
|
|
126
|
+
4. `ytoken-01` 的 key 同样缺失,再次抛出;
|
|
127
|
+
5. 这条**第二次**的错误冒泡到 `AppContainer.tsx:1273`,成为用户看到的文案。
|
|
128
|
+
|
|
129
|
+
用编译产物直接复现:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
$ cd ~/git/gemini-cli/packages/core
|
|
133
|
+
$ env -u YTOKEN_01_API_KEY -u LINKSUB_008_API_KEY node --input-type=module -e '
|
|
134
|
+
const m = await import("./dist/src/core/openai/integration.js");
|
|
135
|
+
try {
|
|
136
|
+
const p = m.resolveActiveProvider({ sessionProviderId: "linksub-008", allowImplicitProvider: true });
|
|
137
|
+
console.log("resolved:", p && p.id);
|
|
138
|
+
} catch (e) { console.log("THROWN:", e.message); }'
|
|
139
|
+
|
|
140
|
+
THROWN: Provider "ytoken-01" references the environment variable YTOKEN_01_API_KEY, which is not set.
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**更危险的变体:静默换端点。** 若 `ytoken-01`
|
|
144
|
+
的 key 恰好存在,降级就会**成功**,把一个并非用户选择的 provider 装进会话:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
$ env -u LINKSUB_008_API_KEY YTOKEN_01_API_KEY=sk-test node --input-type=module -e '
|
|
148
|
+
const m = await import("./dist/src/core/openai/integration.js");
|
|
149
|
+
const p = m.resolveActiveProvider({ sessionProviderId: "linksub-008", allowImplicitProvider: true });
|
|
150
|
+
console.log("asked for linksub-008 -> got:", p && p.id, "| baseUrl:", p && p.baseUrl);'
|
|
151
|
+
|
|
152
|
+
asked for linksub-008 -> got: ytoken-01 | baseUrl: https://api.ytoken.eu.cc/v1
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
此时唯一提示是一条 warning:
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
The selected OpenAI provider "linksub-008" is no longer configured,
|
|
159
|
+
so this session is using "ytoken-01" instead. Run /provider to choose another.
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
这条文案本身也是错的——`linksub-008` **并未**"no longer
|
|
163
|
+
configured",它是**存在但凭据缺失**。同一句 `catch`
|
|
164
|
+
把两种完全不同的事故(provider 被删除 / provider 的 key 没设)压成了同一种。
|
|
165
|
+
|
|
166
|
+
### 2.3 缺陷 3:认证门只认第 0 条
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
// packages/core/src/core/openai/integration.ts:246
|
|
170
|
+
export function hasResolvableOpenAiProvider(env, filePath) {
|
|
171
|
+
// ...
|
|
172
|
+
const requestedId = cleanEnv?.[OPENAI_PROVIDER_ENV]; // 只认 GEMINI_OPENAI_PROVIDER
|
|
173
|
+
const profile = resolveProvider(requestedId, filePath, cleanEnv);
|
|
174
|
+
return Boolean(profile?.baseUrl && profile?.modelId);
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
问题有二:
|
|
179
|
+
|
|
180
|
+
1. 它**不读** `settings.json` 里的
|
|
181
|
+
`security.auth.openAiProviderId`(用户已持久化的选择);
|
|
182
|
+
2. 无 `GEMINI_OPENAI_PROVIDER` 时永远只看 `providers[0]`。
|
|
183
|
+
|
|
184
|
+
当前 provider 文件的实际状况:
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
providers: 7 | without modelId: 2 | without apiKeyEnv: 0
|
|
188
|
+
entry0: ytoken-01 modelId: undefined ← 缺 modelId
|
|
189
|
+
selected linksub-008 modelId: deepseek-v4.1-flash
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`providers[0]` 没有 `modelId`,所以门恒为 false:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
$ node --input-type=module -e '...'
|
|
196
|
+
entry0: ytoken-01 modelId: undefined (needs a modelId for the gate)
|
|
197
|
+
hasResolvableOpenAiProvider: false # 即使所有 key 都齐
|
|
198
|
+
gate with provider env var: true # 只有显式指定 GEMINI_OPENAI_PROVIDER 才 true
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
门判 false ⇒ 走 `validateAuthMethod` 的兜底分支 ⇒ 用户看到与真正原因无关的:
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
When using an OpenAI-compatible API, you must specify the GEMINI_OPENAI_BASE_URL environment variable.
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
这正是 `cd ~` 下的无用报错,也是"配置明明都在,却反复要求 BASE_URL"的来源。
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## 3. 复现证据汇总
|
|
212
|
+
|
|
213
|
+
| 场景 | 命令/条件 | 结果 |
|
|
214
|
+
| -------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- |
|
|
215
|
+
| 基线(key 齐备) | `cd ~/git/test; gemini-leo -p ok` | ✅ `ok` |
|
|
216
|
+
| key 被剥离 | 同上 + `env -u YTOKEN_01_API_KEY -u LINKSUB_008_API_KEY ...` | ❌ 报 `ytoken-01 ... not set`(归因错误) |
|
|
217
|
+
| 换到无项目 `.env` 的目录 | `cd ~` + 同样剥离 | ✅ 读到了 `~/.gemini/.env`,正常启动 |
|
|
218
|
+
| 显式指定 provider + key 齐备 | `GEMINI_OPENAI_PROVIDER=linksub-008 gemini-leo -p ok` | ✅ `ok` |
|
|
219
|
+
| 只缺 `LINKSUB_008`,`YTOKEN` 存在 | `env -u LINKSUB_008_API_KEY YTOKEN_01_API_KEY=...` | ⚠️ 静默解析为 `ytoken-01` / `api.ytoken.eu.cc` |
|
|
220
|
+
| 直接调用 `resolveActiveProvider` | 见 2.2 | ❌ 抛出 `ytoken-01` 的错误 |
|
|
221
|
+
| 认证门(所有 key 齐备、未设 env 变量) | `hasResolvableOpenAiProvider({...})` | ❌ `false`(因 entry0 缺 modelId) |
|
|
222
|
+
|
|
223
|
+
关键对照实验——同一台机器、同一份配置,仅改变 cwd:
|
|
224
|
+
|
|
225
|
+
```
|
|
226
|
+
=== cwd=~/git/test(有项目 .env)===
|
|
227
|
+
Ignoring the OpenAI provider file at ~/.gemini/openai-providers.json:
|
|
228
|
+
Provider "ytoken-01" references the environment variable YTOKEN_01_API_KEY, which is not set.
|
|
229
|
+
When using an OpenAI-compatible API, you must specify the GEMINI_OPENAI_BASE_URL environment variable.
|
|
230
|
+
|
|
231
|
+
=== cwd=~(无项目 .env)===
|
|
232
|
+
- Review or refactor code
|
|
233
|
+
- Build a new feature
|
|
234
|
+
Just tell me the task and I'll dig in. ← 正常
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## 4. 临时规避方案
|
|
240
|
+
|
|
241
|
+
### 方案 A:让项目 `.env` 不再遮蔽(推荐,已验证)
|
|
242
|
+
|
|
243
|
+
在 `~/git/test/.gemini/settings.json` 写入:
|
|
244
|
+
|
|
245
|
+
```json
|
|
246
|
+
{
|
|
247
|
+
"advanced": {
|
|
248
|
+
"ignoreLocalEnv": true
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
`ignoreLocalEnv=true` 会跳过项目 `.env`,一路回落到 `~/.gemini/.env`。已验证:
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
# 剥离 key 后,仅靠 settings 即可恢复
|
|
257
|
+
$ cd ~/git/test && env -u YTOKEN_01_API_KEY -u LINKSUB_008_API_KEY -u OPENROUTER_API_KEY \
|
|
258
|
+
GEMINI_OPENAI_PROVIDER=linksub-008 gemini-leo -p ok
|
|
259
|
+
ok
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
> 注意:`--ignore-env`
|
|
263
|
+
> 这个 CLI 参数在当前版本**不被接受**(`Unknown arguments: ignore-env`),只能用 settings 或
|
|
264
|
+
> `advanced.ignoreLocalEnv`。
|
|
265
|
+
|
|
266
|
+
### 方案 B:合并 `.env` 文件(最彻底)
|
|
267
|
+
|
|
268
|
+
把 `~/git/test/.env` 的内容并进 `~/.gemini/.env`,然后删除项目级 `.env`:
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
cat ~/git/test/.env >> ~/.gemini/.env
|
|
272
|
+
rm ~/git/test/.env
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
这样 `findEnvFile()` 无论从哪里启动都会命中同一个文件,不存在遮蔽问题。
|
|
276
|
+
|
|
277
|
+
### 方案 C:启动时显式指定 provider
|
|
278
|
+
|
|
279
|
+
因 `providers[0]` 缺 `modelId`,认证门不会自动放行,需要显式指定:
|
|
280
|
+
|
|
281
|
+
```bash
|
|
282
|
+
GEMINI_OPENAI_PROVIDER=linksub-008 gemini-leo
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
可写进 `~/.bashrc` 或包一层 alias / 启动脚本。
|
|
286
|
+
|
|
287
|
+
### 方案 D:补全第 0 条 provider
|
|
288
|
+
|
|
289
|
+
给 `ytoken-01` 补一个
|
|
290
|
+
`modelId`,认证门即可通过(仍建议配合方案 A/B 解决 key 缺失):
|
|
291
|
+
|
|
292
|
+
```jsonc
|
|
293
|
+
{
|
|
294
|
+
"id": "ytoken-01",
|
|
295
|
+
"baseUrl": "https://api.ytoken.eu.cc/v1",
|
|
296
|
+
"apiKeyEnv": "YTOKEN_01_API_KEY",
|
|
297
|
+
"modelId": "deepseek-v4.1-flash", // ← 新增
|
|
298
|
+
}
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
---
|
|
302
|
+
|
|
303
|
+
## 5. 修复实现
|
|
304
|
+
|
|
305
|
+
三处缺陷都已修复,按风险从低到高实施。
|
|
306
|
+
|
|
307
|
+
### 5.1 缺陷 2:不再把错误归因到别的 provider
|
|
308
|
+
|
|
309
|
+
**改动:** `packages/core/src/core/openai/providers.ts`、`.../integration.ts`
|
|
310
|
+
|
|
311
|
+
`resolveProvider()` 原本对所有失败都抛同一种
|
|
312
|
+
`Error`,调用方无从区分"provider 不存在"和"provider 存在但凭据缺失",只能一概降级。现在前者抛出专用的
|
|
313
|
+
`UnknownProviderError`(携带 `requestedId` 与 `knownIds`):
|
|
314
|
+
|
|
315
|
+
```ts
|
|
316
|
+
export class UnknownProviderError extends Error {
|
|
317
|
+
constructor(
|
|
318
|
+
readonly requestedId: string,
|
|
319
|
+
readonly knownIds: readonly string[],
|
|
320
|
+
message: string,
|
|
321
|
+
) {
|
|
322
|
+
super(message);
|
|
323
|
+
this.name = 'UnknownProviderError';
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
`resolveActiveProvider()` 的 `catch` 随之收紧——**只有**"会话选择 +
|
|
329
|
+
provider 确实不存在"才降级:
|
|
330
|
+
|
|
331
|
+
```ts
|
|
332
|
+
if (requestedId !== undefined || !(error instanceof UnknownProviderError)) {
|
|
333
|
+
throw error;
|
|
334
|
+
}
|
|
335
|
+
return resolveImplicitProvider(sessionProviderId, env);
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
用类型而非匹配消息来判别,避免将来改文案时静默恢复成换端点。同时把
|
|
339
|
+
`resolveImplicitProvider()` 的 warning 从 "is no longer configured" 改为 "is not
|
|
340
|
+
configured in the provider file",因为它现在只会因条目确实缺失而触发。
|
|
341
|
+
|
|
342
|
+
**效果:** 选择 `linksub-008` 而后者的 key 未设置时,报出的是
|
|
343
|
+
|
|
344
|
+
```
|
|
345
|
+
Provider "linksub-008" references the environment variable LINKSUB_008_API_KEY, which is not set.
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
即使 `ytoken-01` 的 key 存在,也不会再静默把会话切到 `api.ytoken.eu.cc`。
|
|
349
|
+
|
|
350
|
+
### 5.2 缺陷 3:认证门尊重已持久化的选择
|
|
351
|
+
|
|
352
|
+
**改动:** `integration.ts`、`packages/cli/src/config/auth.ts`
|
|
353
|
+
|
|
354
|
+
`hasResolvableOpenAiProvider()` 增加第三个可选参数
|
|
355
|
+
`selectedProviderId`,判定优先级与 `resolveActiveProvider()`
|
|
356
|
+
严格一致:**持久化选择 > `GEMINI_OPENAI_PROVIDER` > 第一条**。两者共用一个
|
|
357
|
+
`pickRequestedId()`,避免再次漂移。
|
|
358
|
+
|
|
359
|
+
新增 `describeUnusableOpenAiProvider()`
|
|
360
|
+
作为"报告侧":门本身必须保持静默(它会被 React 渲染路径反复调用),而
|
|
361
|
+
`validateAuthMethod()` 只调用一次,拿到真实原因后直接返回:
|
|
362
|
+
|
|
363
|
+
```ts
|
|
364
|
+
const providerFailure = describeUnusableOpenAiProvider(
|
|
365
|
+
{ ...process.env },
|
|
366
|
+
undefined,
|
|
367
|
+
selected,
|
|
368
|
+
);
|
|
369
|
+
if (providerFailure) return providerFailure;
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
`auth.ts` 的两个调用点(`isOpenAiEndpointConfigured()` 与
|
|
373
|
+
`validateAuthMethod()`)都改为通过
|
|
374
|
+
`readPersistedProviderId(loadSettings().merged)` 传入该选择。
|
|
375
|
+
|
|
376
|
+
**效果:** `providers[0]` 缺 `modelId`
|
|
377
|
+
不再拖垮一个配置完好的选择;配置有误时看到的是具体原因,而不是无关的 "must
|
|
378
|
+
specify GEMINI_OPENAI_BASE_URL"。
|
|
379
|
+
|
|
380
|
+
### 5.3 缺陷 1:项目 `.env` 不再遮蔽用户级 `.env`
|
|
381
|
+
|
|
382
|
+
**改动:** `packages/cli/src/config/settings.ts`
|
|
383
|
+
|
|
384
|
+
采取的是最小侵入方案,而非把 `findEnvFile()` 改造成返回列表——那样会波及
|
|
385
|
+
`settings-env-isolation.test.ts` 中十余个锁定短路行为的断言。
|
|
386
|
+
|
|
387
|
+
`findEnvFile()` 的选择语义保持不变(项目 `.env` 仍是权威),但
|
|
388
|
+
`loadEnvironment()` 在加载完主文件后,追加读取被跳过的用户级文件:
|
|
389
|
+
|
|
390
|
+
```ts
|
|
391
|
+
if (envFilePath) {
|
|
392
|
+
loadEnvFileIntoProcess(envFilePath, settings, isTrusted);
|
|
393
|
+
}
|
|
394
|
+
for (const fallbackPath of findUserLevelEnvFiles(envFilePath)) {
|
|
395
|
+
loadEnvFileIntoProcess(fallbackPath, settings, isTrusted);
|
|
396
|
+
}
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
`findUserLevelEnvFiles()` 返回 `<home>/.gemini/.env` 与 `<home>/.env`
|
|
400
|
+
中尚未被选为主文件、且确实存在的那些。解析循环被提取为
|
|
401
|
+
`loadEnvFileIntoProcess()`,确保兜底文件走**完全相同**的检查——包括不可信工作区的白名单与值清洗,以及项目文件的
|
|
402
|
+
`excludedEnvVars` 过滤。由于既有规则是"仅在 `process.env`
|
|
403
|
+
尚无该键时写入",兜底天然只补空缺,优先级不变。
|
|
404
|
+
|
|
405
|
+
### 5.4 测试
|
|
406
|
+
|
|
407
|
+
新增/调整的用例:
|
|
408
|
+
|
|
409
|
+
| 文件 | 覆盖内容 |
|
|
410
|
+
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
411
|
+
| `hasResolvableProvider.test.ts` | 所选 provider 存在但 key 缺失 → 报**该** provider 名字与变量名;fallback 可用时也不换端点;provider 确实缺失时仍降级并 warn |
|
|
412
|
+
| 同上 | 认证门:所选条目可用而 `providers[0]` 缺 `modelId` → `true`;持久化选择优先于 `GEMINI_OPENAI_PROVIDER`;空白 id 视为未设置 |
|
|
413
|
+
| 同上 | `describeUnusableOpenAiProvider()` 的四种返回(报原因 / 可用 / stale / 未指定) |
|
|
414
|
+
| `settings-env-isolation.test.ts` | 项目 `.env` 只有一个无关变量时,用户级 key 仍可读到;同名键仍以项目为准;`ignoreLocalEnv` 下仍读家目录;主文件即家目录文件时不重复读取 |
|
|
415
|
+
|
|
416
|
+
其中两个用例刻意使用 `TEST_UNSET_*` 这种测试专用变量名:`readEnvValue()` 在
|
|
417
|
+
`configEnv` 缺键时会回落到
|
|
418
|
+
`process.env`,用真实变量名会让断言依赖运行机器的实际环境。
|
|
419
|
+
|
|
420
|
+
### 5.5 顺带修掉的测试缺陷
|
|
421
|
+
|
|
422
|
+
`auth.test.ts` 的 6 个用例在**改动前就已失败**(已用 `git stash`
|
|
423
|
+
对照基线确认),原因是认证门会读取开发者真实的
|
|
424
|
+
`~/.gemini/openai-providers.json`——配置了 provider 的机器上,"nothing
|
|
425
|
+
set" 自然会变成
|
|
426
|
+
`true`。这正是本次要修的 bug 在测试里的同构版本,所以一并处理:用一个模块级
|
|
427
|
+
`beforeEach` 把 `GEMINI_CLI_HOME` 指向临时目录(core 的 `homedir()`
|
|
428
|
+
每次调用都会读它),无需 mock 任何模块。
|
|
429
|
+
|
|
430
|
+
`settings.test.ts` 的 4 个缓存用例断言了 `fs.readFileSync`
|
|
431
|
+
的**固定调用次数**("每个 workspace
|
|
432
|
+
5 次")。兜底读取会多读 2 个文件,于是计数断言失败——但用例真正要验证的是缓存,不是文件数。已改为断言语义:命中缓存返回同一对象且不再读取;`saveSettings`
|
|
433
|
+
后返回新对象。
|
|
434
|
+
|
|
435
|
+
### 5.6 验证结果
|
|
436
|
+
|
|
437
|
+
```
|
|
438
|
+
core src/core/openai 302 passed (11 files)
|
|
439
|
+
cli src/config 981 passed | 1 skipped
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
剩余两项失败与本次改动无关,均已用基线对照确认:
|
|
443
|
+
|
|
444
|
+
- `extension-manager-scope.test.ts` —— Termux/Android 缺少
|
|
445
|
+
`@lydell/node-pty-android-arm64` 二进制,文件级加载失败;
|
|
446
|
+
- `extension-manager.test.ts` 的并发安装用例 ——
|
|
447
|
+
Android 文件系统下的时序问题,基线上同样失败。
|
|
448
|
+
|
|
449
|
+
端到端复现(编译产物 + 临时 HOME):
|
|
450
|
+
|
|
451
|
+
```
|
|
452
|
+
=== 所选 key 缺失、fallback key 存在 ===
|
|
453
|
+
THROWN: Provider "linksub-008" references the environment variable LINKSUB_008_API_KEY, which is not set.
|
|
454
|
+
=== provider 确实缺失 ===
|
|
455
|
+
degraded to: ytoken-01
|
|
456
|
+
=== 门:entry0 缺 modelId ===
|
|
457
|
+
default (entry0): false
|
|
458
|
+
with selection: true
|
|
459
|
+
=== 项目 .env 只有一个无关变量 ===
|
|
460
|
+
NGROK_AUTHTOKEN : abc123 (来自项目 .env)
|
|
461
|
+
YTOKEN_01_API_KEY : sk-a (来自 ~/.gemini/.env,修复前读不到)
|
|
462
|
+
LINKSUB_008_API_KEY: sk-b
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
---
|
|
466
|
+
|
|
467
|
+
## 6. 相关文件索引
|
|
468
|
+
|
|
469
|
+
| 文件 | 作用 |
|
|
470
|
+
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
471
|
+
| `packages/core/src/core/openai/providers.ts` | `UnknownProviderError`、`resolveProvider()`、`resolveApiKey()` 抛错 |
|
|
472
|
+
| `packages/core/src/core/openai/integration.ts` | `resolveActiveProvider()` 降级判定、`resolveImplicitProvider()` 文案、`hasResolvableOpenAiProvider()` 门、`describeUnusableOpenAiProvider()`、`pickRequestedId()` |
|
|
473
|
+
| `packages/cli/src/config/auth.ts` | `isOpenAiEndpointConfigured()`、`validateAuthMethod()` 的门调用与原因呈现 |
|
|
474
|
+
| `packages/cli/src/ui/openai/openAiProviderPreference.ts` | `readPersistedProviderId()`(`security.auth.openAiProviderId` 的读取) |
|
|
475
|
+
| `packages/cli/src/config/settings.ts` | `findEnvFile()`、`findUserLevelEnvFiles()`、`loadEnvFileIntoProcess()`、`loadEnvironment()` |
|
|
476
|
+
| `packages/core/src/core/openai/hasResolvableProvider.test.ts` | 门 / 降级 / 原因报告的全部用例 |
|
|
477
|
+
| `packages/cli/src/config/settings-env-isolation.test.ts` | `.env` 遮蔽与兜底的全部用例 |
|
|
478
|
+
|
|
479
|
+
---
|
|
480
|
+
|
|
481
|
+
## 7. 附:改动范围
|
|
482
|
+
|
|
483
|
+
诊断阶段产生的临时改动(`~/git/test/.gemini/settings.json`、`~/git/test/.env`、临时目录
|
|
484
|
+
`~/.gemini/tmp/envtest`、`~/.gemini/tmp/wtest`)当时已还原或删除。
|
|
485
|
+
|
|
486
|
+
修复阶段**修改了源码**,范围如下:
|
|
487
|
+
|
|
488
|
+
```bash
|
|
489
|
+
$ cd ~/git/gemini-cli && git status --short
|
|
490
|
+
M packages/cli/src/config/auth.ts
|
|
491
|
+
M packages/cli/src/config/auth.test.ts
|
|
492
|
+
M packages/cli/src/config/settings-env-isolation.test.ts
|
|
493
|
+
M packages/cli/src/config/settings.test.ts
|
|
494
|
+
M packages/cli/src/config/settings.ts
|
|
495
|
+
M packages/core/src/core/openai/hasResolvableProvider.test.ts
|
|
496
|
+
M packages/core/src/core/openai/integration.ts
|
|
497
|
+
M packages/core/src/core/openai/providers.ts
|
|
498
|
+
?? docs/openai-provider-env-shadowing.md
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
第 4 节的规避方案仍然有效,但已是冗余的——修复后不再需要 `ignoreLocalEnv`
|
|
502
|
+
或显式指定 `GEMINI_OPENAI_PROVIDER` 才能正常启动。
|
package/docs/sidebar.json
CHANGED
|
@@ -229,6 +229,10 @@
|
|
|
229
229
|
},
|
|
230
230
|
{ "label": "Local development", "slug": "docs/local-development" },
|
|
231
231
|
{ "label": "NPM package structure", "slug": "docs/npm" },
|
|
232
|
+
{
|
|
233
|
+
"label": "OpenAI provider env shadowing",
|
|
234
|
+
"slug": "docs/openai-provider-env-shadowing"
|
|
235
|
+
},
|
|
232
236
|
{
|
|
233
237
|
"label": "Single-file bundle",
|
|
234
238
|
"slug": "docs/single-file-bundle"
|