billion-context 0.1.23 → 0.1.25

package/README.zh-CN.md

@@ -42,134 +42,130 @@ npm install -g billion-context
 
 ## 快速上手
 
-三步:**启动代理 → 编辑配置文件 → 把客户端指向它**。
+两种方式 —— 任选其一:
+
+- **零配置(最简单):** 在客户端 baseURL 前面加上代理地址 + `/bili/`。无需配置文件 —— context 窗口自动从 [models.dev](https://models.dev) registry 查询。`/bili/` 前缀还是个自检测信号:billion-context 的客户端扩展(billion-context-pi / opencode-acp)能在自己的 baseUrl 里认出它并自禁用,避免双层压缩。
+- **显式 context 窗口覆盖:** 在配置文件(或网页)里按 URL 声明 context 窗口,用于 registry 不认识的端点,或想钉死一个精确值的场景。两种方式路由都是同一个 `/bili/` 前缀 —— 配置只改变代理用哪个 context 窗口。
+
 压缩是自动注入的 —— 你只需配置路由,无需配置压缩本身。
 
-### 第 1 步 —— 启动代理
+### 方式 A —— 零配置(`/bili/` 前缀)
+
+启动代理:
 
 ```bash
 bili
 ```
 
-它监听 `http://127.0.0.1:8787`。保持这个终端开着(或后台运行,见[运行代理](#运行代理))。
-
-点击[http://localhost:8787/__acp/](http://localhost:8787/__acp/) 添加你的模型
-<img width="2908" height="1787" alt="image" src="https://github.com/user-attachments/assets/cacf4b64-e5c6-41f2-b270-fd2be02eab0c" />
-
-### 第 2 步 —— 编辑配置文件
+然后把客户端现有的 baseURL 前面加上 `http://localhost:8787/bili/` 就行。完整上游 URL 嵌在路径里,proxy 无需任何配置就知道转发到哪:
 
-在网页上添加你的 provider,复制以下内容到配置:
-<img width="2931" height="1519" alt="image" src="https://github.com/user-attachments/assets/c02278be-bc7a-4f14-8f58-0f2d83784d54" />
-
-> 不想用网页?也可以直接手编 JSON 文件,见下文[手动配置文件](#手动配置文件)。
-
-### 第 3 步 —— 把客户端指向代理
+```
+客户端 baseURL 之前:  https://api.openai.com/v1
+客户端 baseURL 之后:  http://localhost:8787/bili/https://api.openai.com/v1
+```
 
-编辑客户端自己的配置文件,让它把请求发到
-`http://localhost:8787/<provider>/...`(第 2 步声明的 provider 名作为路径
-第一段)。把你的**真实** API key 也填进客户端配置 —— 代理原样透传。
+就这样 —— 真实 API key 照常填在客户端配置里(proxy 原样透传)。context 窗口(gpt-5.1-codex=400K、glm-5.2=1M、claude-opus-4=200K ……)自动从 models.dev 查询。
 
-#### Pi(billion-context-pi)
+#### A. API-key 客户端(`/bili/` 前缀)
 
-打开 `~/.pi/agent/models.json`,把你现有 provider 的 **`baseUrl` 这一行**改成指向代理,其他字段都不用动:
+用 **API key** 配置(不是登录账号)的客户端允许你改上游 URL。只需在前面加 `http://localhost:8787/bili/`,其他都不用改。
 
+**OpenCode** —— 编辑 `~/.config/opencode/opencode.json`,改 provider 的 `baseURL`:
 ```jsonc
-// 改之前:
-"baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
-// 改之后(把 host 换成代理 + 你起的 provider 名):
-"baseUrl": "http://localhost:8787/zhipu/api/coding/paas/v4",
+// 之前:
+"baseURL": "https://open.bigmodel.cn/api/coding/paas/v4"
+// 之后(前面加上代理地址 + /bili/):
+"baseURL": "http://localhost:8787/bili/https://open.bigmodel.cn/api/coding/paas/v4"
 ```
 
-`http://localhost:8787` 是代理,`zhipu` 是第 2 步起的名字,剩余路径 `/api/coding/paas/v4` 原样转发到智谱。`apiKey`、`api`、`models` 都不用改。
+**Codex(API key 模式)** —— 编辑 `~/.codex/config.toml`,改 provider 的 `base_url`:
+```toml
+# 之前:
+base_url = "https://api.openai.com/v1"
+# 之后:
+base_url = "http://localhost:8787/bili/https://api.openai.com/v1"
+```
 
-| `api` 值 | `baseUrl` 应指向 |
-|---|---|
-| `openai-completions` | OpenAI 兼容端点(GLM/DeepSeek/OpenAI)→ `…/zhipu/...` |
-| `anthropic-messages` | Anthropic 兼容端点 → `…/anthropic` |
+**Pi** —— 编辑 `~/.pi/agent/models.json`,改 provider 的 `baseUrl`:
+```jsonc
+// 之前:
+"baseUrl": "https://api.anthropic.com"
+// 之后:
+"baseUrl": "http://localhost:8787/bili/https://api.anthropic.com"
+```
 
-> 如果你装了 `billion-context-pi` 扩展,用隔离的 agent 目录跑 Pi
-> (`PI_CODING_AGENT_DIR=…`),免得客户端扩展和 proxy 双重压缩。
-> `bili-test-pi` 脚本帮你做好了这层隔离。
+**其他 API-key 客户端(Cursor / Aider / Continue ……)** —— 只要配置了上游 URL,前面加 `http://localhost:8787/bili/` 就行,其他都不用改。
 
-#### OpenCode
+#### B. 登录/订阅客户端(MITM 透明代理)
 
-打开 `~/.config/opencode/opencode.json`,把你现有 provider 的 **`baseURL` 这一行**改成指向代理:
+需要 **登录账号**的客户端(ChatGPT Plus/Pro、Claude、ZCode coding plan
+……)通过 **OAuth 认证,且硬编码了端点**——你改不了 baseURL,所以 `/bili/`
+前缀方式对它们无效。这类客户端要用 **MITM 透明代理模式**。
 
-```jsonc
-// 改之前:
-"baseURL": "https://open.bigmodel.cn/api/coding/paas/v4"
-// 改之后:
-"baseURL": "http://localhost:8787/zhipu/api/coding/paas/v4"
-```
+支持的登录客户端:
 
-其他字段(`apiKey`、`models`)都不用改。如果要走 Anthropic provider,把 `baseURL` 改为 `http://localhost:8787/anthropic`。
-
-#### Codex
+| 客户端 | 登录方式 | 硬编码端点 | 状态 |
+|---|---|---|---|
+| **ZCode** | 智谱 coding plan(OAuth) | `open.bigmodel.cn`(内置 provider) | ✅ 已测试 |
+| **Codex** | ChatGPT 账号(OAuth) | `chatgpt.com/backend-api` | ❓ 未测试(可能不支持,需验证) |
+| **Claude Code** | Claude 订阅(OAuth) | `api.anthropic.com` | ❓ 未测试(可能不支持,需验证) |
 
-打开 `~/.codex/config.toml`,把现有 provider 的 **`base_url` 这一行**改成指向代理:
+MITM 模式原理:这类客户端只提供 **HTTP 代理**设置,所以它发送
+`CONNECT <域名>:443`;billion-context 在本地用自生成的根 CA 终止 TLS,在明文里注入压缩,再重新加密转发。OAuth token 随客户端的
+`Authorization` 头原样转发(我们不动它)——订阅折扣保留。
 
-```toml
-# 改之前:
-base_url = "https://open.bigmodel.cn/api/coding/paas/v4"
-# 改之后:
-base_url = "http://localhost:8787/zhipu/api/coding/paas/v4"
-```
+MITM 默认开启,且只对一份 **白名单**中的模型域名(`open.bigmodel.cn`、
+`api.anthropic.com`、`api.openai.com`、`chatgpt.com`)生效。所有其他 HTTPS
+域名都是盲隧道(billion-context 从不解密非模型流量)。
 
-其他字段(`name`、`wire_api`、`env_key`)都不用改。
+**一次性设置(在客户端里信任根 CA):**
 
-> Codex 的 Responses API 需要上游说 Responses 协议。多数区域性 OpenAI
-> 兼容端点只说 `/chat/completions`;如果你的端点在 `/responses` 上 404,
-> 用一个说 Responses 的中转,或用官方 OpenAI API。
+1. 启动一次 proxy 以生成根 CA:
+   ```bash
+   bili start
+   ls ~/.local/share/billion-context/ca/root-ca.pem   # 现在存在了
+   ```
 
-#### 其他客户端(Cursor / Aider / Continue …)
+2. 在客户端的 **设置 → 网络/代理** 里填:
+   - **HTTP 代理**:`http://127.0.0.1:8787`
+   - **代理 CA 证书路径**:`~/.local/share/billion-context/ca/root-ca.pem`
+   - (可选)**不走代理列表**:`localhost,127.0.0.1`
+   - (ZCode 具体位置:**设置 → 网络**。Codex/Claude Code:设 `HTTPS_PROXY`
+     环境变量 + `NODE_EXTRA_CA_CERTS` 指向 CA 路径。)
 
-暂不支持。代理目前说 Anthropic、OpenAI chat-completions、OpenAI Responses
-三种协议 —— 如果你的客户端用别的协议或非标准 auth header,还用不了。
+3. 重启客户端。它的模型流量现在会经过 billion-context 并注入压缩。发一条消息,看 proxy 日志(`~/.local/state/billion-context/bili.log`)应出现
+   `mitm <域名>:443 tunnel established`。
 
-### 手动配置文件
+> 根 CA 是本地生成的、只存在本机,**不是**系统级安装。只有你配置的那个
+> 客户端(通过 CA 路径设置,它会把该路径作为 `NODE_EXTRA_CA_CERTS` 喂给
+> Node)信任它,其他应用不受影响。删除 CA 文件并重启 proxy 会重新生成。
 
-上面用网页配置。如果你不想用网页、想把配置纳入 git 管理、或者用脚本
-自动化部署,也可以直接手编 JSON 文件,效果完全一样。
+### 方式 B 手动配置文件&设置上下文大小
 
 打开 `~/.config/billion-context/billion-context.json`,编辑 `providers` 块。
-每个条目是一个**名字 → URL** 映射;这个名字就是你在第 3 步里写进客户端
-base URL 的东西。
+**key 就是上游 URL** —— 客户端写在 `/bili/` 后面的那个字符串。value 为该
+URL 声明按模型的 context 窗口:
 
 ```json
 {
   "providers": {
-    "zhipu": {
-      "url": "https://open.bigmodel.cn",
-      "models": {
-        "glm-5.2": { "context": 1000000, "output": 131072 }
-      }
+    "https://open.bigmodel.cn/api/coding/paas/v4": {
+      "models": { "glm-5.2": { "context": 1000000 } }
     },
-    "anthropic": "https://api.anthropic.com"
+    "https://api.anthropic.com": {}
   }
 }
 ```
 
-- 删掉你不用的 provider。
-- 添加其他的(例如 `"deepseek": "https://api.deepseek.com"`)。
+- 一个 key 在客户端嵌入的 URL 等于它或以它开头时匹配(最长 key 优先)。纯 host key 覆盖该 host 上的所有路径。
+- 空 value `{}` 表示"这个 URL 存在,无覆盖"(context 窗口来自 models.dev / 前缀表)。
+- 删掉你不用的条目;添加其他的(按需)。
 - API key **不**写在这里 —— key 在客户端那边,代理原样透传。
 
-保存后**重启 `bili`**。启动行列出你的路由:
-
-```
-acp-proxy listening on http://127.0.0.1:8787 — routes: anthropic=https://api.anthropic.com, zhipu=https://open.bigmodel.cn
-```
-
-这证明代理读到了你的配置。(完整 schema —— 按模型的 context 窗口、可选字段 —— 见[配置](#配置)。)
-
-### 网页配置
-
-代理跑着的时候,在浏览器打开 `http://localhost:8787/__acp/`。你可以:
 
-- **编辑 providers** —— 用表单增删 provider 和按模型的 context 窗口,点 Save 直接写入 `billion-context.json`。
-- **生成客户端 URL** —— 选一个 provider,得到可直接复制的配置片段(Pi / OpenCode / Codex 的 `baseUrl`/`baseURL`/`base_url` 一行,已填好代理地址 + provider 名)。
-- **查看会话** —— 实时会话表(请求数、省的 token、最后活跃时间),自动刷新。
+### 方式C 网页配置&设置上下文大小
 
-改完 providers 需要**重启 bili** 才生效(UI 会提醒你)。
+打开 [http://localhost:8787/__bili/](http://localhost:8787/__bili/) 进行配置。
 
 ### 验证
 
@@ -177,11 +173,11 @@ acp-proxy listening on http://127.0.0.1:8787 — routes: anthropic=https://api.a
 
 ```bash
 # 健康检查(代理是否在跑 + 转发到哪)
-curl -s http://localhost:8787/__acp/health
+curl -s http://localhost:8787/__bili/health
 # → {"ok":true,"upstream":"https://api.anthropic.com"}
 
 # 实时会话统计(发过真实请求后)
-curl -s http://localhost:8787/__acp/stats
+curl -s http://localhost:8787/__bili/stats
 ```
 
 然后从助手发一条消息,观察日志(`~/.local/state/billion-context/bili.log`,
@@ -279,15 +275,13 @@ bili --no-auto-update        # 本次启动禁用自动更新
   "port": 8787,
   "host": "127.0.0.1",
   "providers": {
-    "zhipu": {
-      "url": "https://open.bigmodel.cn",
+    "https://open.bigmodel.cn/api/coding/paas/v4": {
       "models": {
-        "glm-5.2": { "context": 1000000, "output": 131072 },
-        "glm-5.1": { "context": 200000, "output": 131072 }
+        "glm-5.2": { "context": 1000000 },
+        "glm-5.1": { "context": 200000 }
       }
     },
-    "anthropic": "https://api.anthropic.com",
-    "deepseek": "https://api.deepseek.com"
+    "https://api.deepseek.com": {}
   }
 }
 ```
@@ -298,12 +292,11 @@ bili --no-auto-update        # 本次启动禁用自动更新
 |------|---------|-------------|
 | `port` | `8787` | 代理监听端口 |
 | `host` | `127.0.0.1` | 代理监听地址 |
-| `upstream` | `https://api.anthropic.com` | 无路由匹配时的默认上游 |
 | `sessionHeader` | `x-acp-session` | 客户端可发来标识会话的 header 名 |
 | `log` | `true` | 启用请求日志 |
 | `debug` | `false` | 详细日志(等同 `ACP_DEBUG=1`) |
 | `passthrough` | `false` | 不压缩直接转发(等同 `ACP_PASSTHROUGH=1`) |
-| `providers` | *(无)* | Provider 路由 —— 见下文 |
+| `providers` | *(无)* | 按 URL 的 context 覆盖 —— 见下文 |
 | `compress` | *(见默认值)* | `{ injectTool, injectNudge }` |
 
 > **选择 `host`**(IPv6 / 容器):默认 `127.0.0.1` 只听 IPv4 且仅
@@ -314,41 +307,38 @@ bili --no-auto-update        # 本次启动禁用自动更新
 > `--host 0.0.0.0`。⚠️ `0.0.0.0` / `::` 会把代理暴露到**所有**网卡;
 > 确保你在可信网络或防火墙后面。
 
-### Providers(URL 路由 + 按模型 context)
+### Providers(按 URL 的 context 覆盖)
 
-`providers` 把路由名映射到一个纯 URL 字符串(简单)或一个带 `url` + 可选按模型 context 窗口的对象(推荐)。
+路由始终是 `/bili/` 前缀(见[方式 A](#方式-a-零配置bili-前缀))。
+`providers` 块只声明**按 URL 的 context 窗口覆盖**,以上游 URL 为 key。
+key 就是客户端写在 `/bili/` 后面的那个字符串:
 
-**简单形式** —— provider 名 → URL:
-```json
-{ "deepseek": "https://api.deepseek.com" }
-```
-
-**完整形式** —— provider 名 → `{ url, models }`:
 ```json
 {
-  "zhipu": {
-    "url": "https://open.bigmodel.cn",
-    "models": {
-      "glm-5.2": { "context": 1000000, "output": 131072 },
-      "glm-5.1": { "context": 200000 }
-    }
+  "providers": {
+    "https://open.bigmodel.cn/api/coding/paas/v4": {
+      "models": {
+        "glm-5.2": { "context": 1000000 },
+        "glm-5.1": { "context": 200000 }
+      }
+    },
+    "https://api.deepseek.com": {}
   }
 }
 ```
 
-同一个模型在不同 provider 后面可以有不同 context 窗口(例如 relay 把模型包成更大窗口)。`context` 是**输入 context 上限**(压缩器用它判断何时 nudge);`output` 是最大输出 token。两者都可选;缺失值回退到内置模型表,再回退到 `modelContextLimit`。
+同一个模型在不同上游后面可以有不同 context 窗口(例如 relay 把模型包成更大窗口)。`context` 是**输入 context 上限**(压缩器用它判断何时 nudge)。可选;缺失值回退到 [models.dev](https://models.dev) registry,再回退到内置前缀表。
 
-> **为什么要声明 context?** LLM 的 `/models` API **不返回** context 窗口(已跨 OpenAI、Anthropic、智谱、comfly 验证)。它们是文档级信息。值错了(例如把 GLM-5.2 猜成 128K 而非 1M)会导致频繁误触发压缩。按 provider + 模型声明能让代理匹配客户端自己用的注册表。
+> **为什么要声明 context?** LLM 的 `/models` API **不返回** context 窗口(已跨 OpenAI、Anthropic、智谱、comfly 验证)。它们是文档级信息。值错了(例如把 GLM-5.2 猜成 128K 而非 1M)会导致频繁误触发压缩。按 URL + 模型声明能让代理匹配客户端自己用的注册表。
 
-**API key 永远不存进代理** —— 助手发什么 key,原样透传给上游。
+### URL key 匹配规则
 
-### Provider 名规则
+- 一个请求在客户端嵌入的 URL **等于 key 或以 key 开头**时匹配(最长 key 优先)。
+- 浅 key 如 `https://open.bigmodel.cn` 覆盖该 host 上的每条路径;深 key 如 `https://open.bigmodel.cn/api/anthropic` 只覆盖那一个端点。
+- key 永不跨 host(边界检查要求 key 后面是 `/` 或字符串结尾),所以 `https://x.com` 不会匹配 `https://x.com.evil`。
+- 未被任何匹配 key 覆盖的模型回退到 models.dev,再回退到前缀表,最后回退到 `modelContextLimit`。
 
-- 必须以字母开头,只含字母/数字/`-`/`_`。
-- 保留字(`v1`、`chat`、`completions`、`messages`、`models`、`api`)被拒绝,以免与真实 API 路径段冲突。
-- provider 名可出现在路径任意位置;最长匹配优先。
-- **未声明任何 providers**(比如你清空了 `providers` 块)时,每个请求按完整
-  原始路径转发到默认 `upstream` —— 边缘场景,非正常流程。
+**API key 永远不存进代理** —— 助手发什么 key,原样透传给上游。
 
 ## 会话机制
 
@@ -370,7 +360,7 @@ bili --no-auto-update        # 本次启动禁用自动更新
 
 ## 状态
 
-早期。协议处理和压缩已通过 mock 测试(141 项通过)。真实模型集成测试是下一里程碑。预期会有粗糙的地方。
+早期。协议处理和压缩已通过 mock 测试(146 项通过)。真实模型集成测试是下一里程碑。预期会有粗糙的地方。
 
 pi 扩展模式(进程内、更紧密集成、参考实现)见 [billion-context-pi](https://github.com/ranxianglei/billion-context-pi)。