billion-context 0.1.26 → 0.1.27

package/README.md

@@ -167,6 +167,12 @@ non-model traffic.
 > so no other app is affected. Deleting the CA files and restarting the proxy
 > regenerates them.
 
+**Routing a login client through its own proxy (firewall/GFW).** A login
+client (ZCode) and an API-key client can both hit the same host
+(`open.bigmodel.cn`). To give the login client its OWN upstream proxy without
+affecting API-key clients, use the `mitm://` scheme key — see
+[Upstream proxy (MITM vs `/bili/`)](#upstream-proxy-firewall--gfw).
+
 ### Option B — Manual config file & context windows
 
 Open `~/.config/billion-context/billion-context.json` and edit the `providers`
@@ -344,6 +350,7 @@ The config file is a single JSON object. Example:
 | `passthrough` | `false` | Forward without compression (same as `ACP_PASSTHROUGH=1`) |
 | `providers` | *(none)* | Per-URL context overrides — see below |
 | `compress` | *(see defaults)* | `{ injectTool, injectNudge }` |
+| `proxy` | *(none)* | Upstream HTTP proxy for the proxy's OWN outbound connections to model providers (`http://host:port`). Per-URL `proxy` overrides this. See [Upstream proxy](#upstream-proxy-firewall--gfw). |
 
 > **Choosing a `host`** (IPv6 / containers): the default `127.0.0.1` is
 > IPv4-only and loopback-only. Use `--host ::` (or `"host": "::"`) to listen
@@ -401,6 +408,65 @@ registry, then the built-in prefix table.
 **API keys are never stored in the proxy** — whatever key the agent sends is
 passed through untouched to the upstream.
 
+### Upstream proxy (firewall / GFW)
+
+If the proxy's own outbound connections to a model provider are blocked
+(e.g. `api.openai.com` from inside the GFW), configure an **upstream proxy**
+(the local v2rayA / clash HTTP port) so the proxy reaches the provider:
+
+```jsonc
+{
+  // Global default: ALL providers route through this proxy
+  "proxy": "http://127.0.0.1:20172",
+  "providers": {
+    "https://api.openai.com/v1": {
+      // Per-URL overrides global (use a different proxy for this host)
+      "proxy": "http://127.0.0.1:20173",
+      "models": { "gpt-5": { "context": 400000 } }
+    },
+    "https://open.bigmodel.cn/api/anthropic": {
+      // Empty string = explicitly DIRECT, overriding the global proxy
+      "proxy": "",
+      "models": { "glm-5.2": { "context": 1000000 } }
+    }
+  }
+}
+```
+
+Rules:
+- **Global `proxy`** (top level) applies to every provider's outbound.
+- **Per-URL `proxy`** overrides the global for that host.
+- Empty string `""` means **explicitly direct** (override-and-disable).
+- Neither set = direct connect.
+- Only HTTP proxies (`http://host:port`). SOCKS5 is not supported yet.
+- Both outbound paths are covered: `/bili/` path-mode (fetch) AND MITM CONNECT
+  tunnels (the proxy's connection to the real upstream goes through the HTTP
+  CONNECT proxy).
+
+Env override: `BILI_UPSTREAM_PROXY=http://127.0.0.1:20172` (same as global
+`proxy`; config file wins over env if both set).
+
+**MITM vs `/bili/` — distinguishing the key scheme.** A login client
+(ZCode via MITM) and an API-key client can both hit the same host
+(`open.bigmodel.cn`). To let their config differ, MITM traffic uses a
+`mitm://` scheme in the lookup key while `/bili/` traffic uses the real
+`https://`:
+
+| Client | Lookup key example |
+|---|---|
+| ZCode (MITM, login) | `mitm://open.bigmodel.cn` |
+| API-key client (`/bili/`) | `https://open.bigmodel.cn/api/anthropic` |
+
+So you can give ZCode its own proxy without affecting API-key clients:
+```jsonc
+{
+  "providers": {
+    "mitm://open.bigmodel.cn":            { "proxy": "http://127.0.0.1:20173" },
+    "https://open.bigmodel.cn/api/anthropic": { "proxy": "http://127.0.0.1:20172" }
+  }
+}
+```
+
 ## How sessions work
 
 The proxy needs a stable per-conversation identifier to isolate compression

package/README.zh-CN.md

@@ -140,6 +140,8 @@ MITM 默认开启,且只对一份 **白名单**中的模型域名(`open.bigmodel
 > 客户端(通过 CA 路径设置,它会把该路径作为 `NODE_EXTRA_CA_CERTS` 喂给
 > Node)信任它,其他应用不受影响。删除 CA 文件并重启 proxy 会重新生成。
 
+**给登录客户端单独配代理(防火墙/GFW)。** 登录客户端(ZCode)和 API-key 客户端可能连同一个域名(`open.bigmodel.cn`)。要给登录客户端配**专属上游代理**而不影响 API-key 客户端,用 `mitm://` scheme 键 —— 见[上游代理(MITM 与 `/bili/`)](#上游代理防火墙gfw)。
+
 ### 方式 B 手动配置文件&设置上下文大小
 
 打开 `~/.config/billion-context/billion-context.json`,编辑 `providers` 块。
@@ -298,6 +300,7 @@ bili --no-auto-update        # 本次启动禁用自动更新
 | `passthrough` | `false` | 不压缩直接转发(等同 `ACP_PASSTHROUGH=1`) |
 | `providers` | *(无)* | 按 URL 的 context 覆盖 —— 见下文 |
 | `compress` | *(见默认值)* | `{ injectTool, injectNudge }` |
+| `proxy` | *(无)* | 代理自身访问模型提供商时走的上游 HTTP 代理(`http://host:port`)。按 URL 的 `proxy` 会覆盖它。见[上游代理](#上游代理防火墙gfw)。 |
 
 > **选择 `host`**(IPv6 / 容器):默认 `127.0.0.1` 只听 IPv4 且仅
 > loopback。用 `--host ::`(或 `"host": "::"`)可同时听 IPv4 和 IPv6
@@ -340,6 +343,56 @@ key 就是客户端写在 `/bili/` 后面的那个字符串:
 
 **API key 永远不存进代理** —— 助手发什么 key,原样透传给上游。
 
+### 上游代理(防火墙 / GFW)
+
+如果代理自身访问模型提供商的连接被墙(比如 GFW 内访问 `api.openai.com`),配置一个**上游代理**(本地 v2rayA / clash 的 HTTP 端口),让代理能连到提供商:
+
+```jsonc
+{
+  // 全局默认:所有提供商的出站都走这个代理
+  "proxy": "http://127.0.0.1:20172",
+  "providers": {
+    "https://api.openai.com/v1": {
+      // 按 URL 覆盖全局(给这个域名用另一个代理)
+      "proxy": "http://127.0.0.1:20173",
+      "models": { "gpt-5": { "context": 400000 } }
+    },
+    "https://open.bigmodel.cn/api/anthropic": {
+      // 空字符串 = 明确直连,覆盖全局代理
+      "proxy": "",
+      "models": { "glm-5.2": { "context": 1000000 } }
+    }
+  }
+}
+```
+
+规则:
+- **全局 `proxy`**(顶层)对所有提供商的出站生效。
+- **按 URL 的 `proxy`** 覆盖该域名的全局设置。
+- 空字符串 `""` 表示**明确直连**(覆盖并禁用)。
+- 都不配 = 直连。
+- 只支持 HTTP 代理(`http://host:port`)。SOCKS5 暂不支持。
+- 两条出站路径都覆盖:`/bili/` 路径模式(fetch)和 MITM CONNECT 隧道(代理连接真实上游的链路走 HTTP CONNECT 代理)。
+
+环境变量覆盖:`BILI_UPSTREAM_PROXY=http://127.0.0.1:20172`(等同全局 `proxy`;两者都设时配置文件优先)。
+
+**MITM 与 `/bili/` —— 用 scheme 区分。** 登录客户端(ZCode 走 MITM)和 API-key 客户端可能连同一个域名(`open.bigmodel.cn`)。为了让它们的配置能区分,MITM 流量在查找键里用 `mitm://` scheme,`/bili/` 流量用真实的 `https://`:
+
+| 客户端 | 查找键示例 |
+|---|---|
+| ZCode(MITM,登录态)| `mitm://open.bigmodel.cn` |
+| API-key 客户端(`/bili/`)| `https://open.bigmodel.cn/api/anthropic` |
+
+所以你可以给 ZCode 单独配代理,不影响 API-key 客户端:
+```jsonc
+{
+  "providers": {
+    "mitm://open.bigmodel.cn":            { "proxy": "http://127.0.0.1:20173" },
+    "https://open.bigmodel.cn/api/anthropic": { "proxy": "http://127.0.0.1:20172" }
+  }
+}
+```
+
 ## 会话机制
 
 代理需要一个稳定的、按会话标识的 ID,以便在多个用户/账号并发时隔离压缩状态。它从四个维度推导一个(见 `src/session-id.ts`):**协议 × 上游 origin × API key × 会话**。前三个防止跨账号 / 跨 provider 串数据;会话维度来自客户端发送的内容。