billion-context 0.1.18 → 0.1.20

package/README.md

@@ -40,54 +40,187 @@ npm install -g billion-context
 
 This installs the `bili` command (`bili-proxy` is kept as an alias).
 
-## Usage
+## Quickstart
 
-### Start the proxy
+Three steps: **start the proxy → edit the config file → point your client at it**.
+Compression is injected automatically — you only configure routing, never
+compression itself.
+
+### Step 1 — Start the proxy
 
 ```bash
 bili
 ```
 
-That's it. The proxy reads its config from `~/.config/billion-context/billion-context.json` (XDG) and listens on `127.0.0.1:8787`. If no config file exists yet, it uses sensible defaults and logs where it expects the file.
+It listens on `http://127.0.0.1:8787`. Keep this terminal open (or run in the
+background; see [Running the proxy](#running-the-proxy)).
 
-### Quick overrides (flags)
+On first run `bili` **auto-creates an empty config file** and tells you where:
+so you don't have to invent the schema from scratch:
 
-```bash
-bili --port 9000              # change listen port
-bili --host 0.0.0.0           # listen on all interfaces
-bili --debug                 # verbose logging (also: set "debug": true in config)
-bili --passthrough           # forward without compression (smoke-test mode)
-bili --config ~/my-bili.json # use a different config file
+```
+[acp-config] created empty config at ~/.config/billion-context/billion-context.json — add your providers (see README Quickstart), then restart
 ```
 
-Flags override the config file and env vars. `bili --help` lists them all.
+### How routing works
 
-### Point your agent at the proxy
+The proxy routes by a **provider name in the URL path** — the first path
+segment after the host. It strips the name and forwards the rest to that
+provider. Everything after the name is passed through untouched:
 
-The proxy routes by a **provider name in the URL path**. Set your agent's base URL to `http://localhost:8787/<provider>/...` and the proxy forwards to that provider (see [Configuration](#configuration) for how providers are declared).
+```
+client baseURL:  http://localhost:8787/zhipu/api/coding/paas/v4
+                  └──────────┬──────────┘└────────┬────────┘
+                      proxy host           remaining path
+                      + provider name      (forwarded as-is)
+```
 
-#### Claude Code (Anthropic)
+This is why Step 2 has you declare named providers, and Step 3 has you put that
+same name at the start of the client's base URL — it's how the proxy knows where
+to send each request. In the config below, `zhipu` corresponds to:
+```json
+    "zhipu": {
+      "url": "https://open.bigmodel.cn",
+      "models": {
+        "glm-5.2": { "context": 1000000, "output": 131072 }
+      }
+```
+
+### Step 2 — Edit the config file
+
+Open the file from Step 1 (`~/.config/billion-context/billion-context.json`)
+and edit the `providers` block to match what you pay for. Each entry is a
+**name → URL** mapping; the name is what you'll put in the client's base URL in
+Step 3.
+
+```json
+{
+  "providers": {
+    "zhipu": {
+      "url": "https://open.bigmodel.cn",
+      "models": {
+        "glm-5.2": { "context": 1000000, "output": 131072 }
+      }
+    },
+    "anthropic": "https://api.anthropic.com"
+  }
+}
+```
+
+- Delete providers you don't use.
+- Add others (e.g. `"deepseek": "https://api.deepseek.com"`).
+- The API key is **not** here — it lives in the client; the proxy passes it
+  through untouched.
+
+After saving, **restart `bili`**. The startup banner lists your routes:
 
-```bash
-export ANTHROPIC_BASE_URL=http://localhost:8787/anthropic
-export ANTHROPIC_API_KEY=sk-ant-...   # real key — passed through as-is
-claude
 ```
+acp-proxy listening on http://127.0.0.1:8787 — routes: anthropic=https://api.anthropic.com, zhipu=https://open.bigmodel.cn
+```
+
+That confirms the proxy picked up your config. (Full schema — per-model context
+windows, optional fields — is in [Configuration](#configuration).)
+
+### Step 3 — Point your client at the proxy
+
+Edit the client's own config file so it sends requests to
+`http://localhost:8787/<provider>/...` (the provider name from Step 2 as the
+first path segment). Put your **real** API key in the client's config too —
+the proxy passes it through untouched.
+
+#### Pi (billion-context-pi)
+
+Open `~/.pi/agent/models.json` and change your existing provider's **`baseUrl` line** to point at the proxy — leave every other field alone:
+
+```jsonc
+// before:
+"baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
+// after (swap the host for the proxy + the provider name you picked):
+"baseUrl": "http://localhost:8787/zhipu/api/coding/paas/v4",
+```
+
+`http://localhost:8787` is the proxy, `zhipu` is the name from Step 2, and the remaining path `/api/coding/paas/v4` is forwarded as-is to Zhipu. `apiKey`, `api`, and `models` stay unchanged.
+
+| `api` value | `baseUrl` should point at |
+|---|---|
+| `openai-completions` | an OpenAI-compatible endpoint (GLM/DeepSeek/OpenAI) → `…/zhipu/...` |
+| `anthropic-messages` | an Anthropic-compatible endpoint → `…/anthropic` |
 
-#### Codex / any OpenAI-compatible agent (zhipu / openai / deepseek)
+> If you use the `billion-context-pi` extension, run Pi in an isolated agent
+dir (`PI_CODING_AGENT_DIR=…`) so the client-side extension doesn't double-
+compress alongside the proxy. The `bili-test-pi` helper does this for you.
+
+#### OpenCode
+
+Open `~/.config/opencode/opencode.json` and change your existing provider's **`baseURL` line** to point at the proxy:
+
+```jsonc
+// before:
+"baseURL": "https://open.bigmodel.cn/api/coding/paas/v4"
+// after:
+"baseURL": "http://localhost:8787/zhipu/api/coding/paas/v4"
+```
+
+Everything else (`apiKey`, `models`) stays unchanged. For an Anthropic provider, change `baseURL` to `http://localhost:8787/anthropic`.
+
+#### Codex
+
+Open `~/.codex/config.toml` and change your existing provider's **`base_url` line** to point at the proxy:
+
+```toml
+# before:
+base_url = "https://open.bigmodel.cn/api/coding/paas/v4"
+# after:
+base_url = "http://localhost:8787/zhipu/api/coding/paas/v4"
+```
+
+Everything else (`name`, `wire_api`, `env_key`) stays unchanged.
+
+> Codex's Responses API needs an upstream that speaks the Responses protocol.
+> Most regional OpenAI-compatible endpoints only speak `/chat/completions`; if
+> yours 404s on `/responses`, use a relay that speaks Responses, or the
+> official OpenAI API.
+
+#### Other clients (Cursor / Aider / Continue …)
+
+Not yet supported. The proxy currently speaks the Anthropic, OpenAI
+chat-completions, and OpenAI Responses protocols — if your client uses a
+different protocol or a non-standard auth header, it won't work yet.
+
+### Verify
+
+With the proxy running and your config saved, check it answers and that your
+first real request shows compression activity in the log:
 
 ```bash
-export OPENAI_BASE_URL=http://localhost:8787/zhipu/api/coding/paas/v4
-export OPENAI_API_KEY=<your real glm key>   # passed through as-is
-codex
+# Health check (proxy up + where it forwards)
+curl -s http://localhost:8787/__acp/health
+# → {"ok":true,"upstream":"https://api.anthropic.com"}
+
+# Live session stats (after a real request)
+curl -s http://localhost:8787/__acp/stats
 ```
 
-The `/zhipu/...` prefix tells the proxy to route to the `zhipu` provider; the
-remaining path is preserved.
+Then send one message from your client and watch the log
+(`~/.local/state/billion-context/bili.log`, also printed to stderr). You
+should see a `processTurn` line per request, and once the conversation grows,
+`[acp-usage] round N input=X cached=Y (cache hit Z%)` + a `compress` event.
 
-#### Cursor / Aider / others
+## Running the proxy
 
-Set the base URL to `http://localhost:8787/<provider>` in the agent's settings.
+### Flags
+
+```bash
+bili --port 9000              # change listen port
+bili --host 0.0.0.0           # listen on all interfaces (see host note below)
+bili --debug                 # verbose logging (also: set "debug": true in config)
+bili --passthrough           # forward without compression (smoke-test mode)
+bili --config ~/my-bili.json # use a different config file
+bili update                  # check & install a newer version now (bypasses throttle)
+bili --no-auto-update        # disable self-update for this run
+```
+
+Flags override env vars and the config file. `bili --help` lists them all.
 
 ### Debugging
 
@@ -108,8 +241,6 @@ All logs are **tee'd to a file by default**: `~/.local/state/billion-context/bil
 shows them in the terminal.
 
 ```bash
-bili start                # logs → ~/.local/state/billion-context/bili.log + terminal
-bili update               # (see below)
 # Config:  "logFile": "/custom/path.log"
 # Env:     ACP_LOG_FILE=/custom/path.log   (or ACP_LOG_FILE=off to disable the file)
 ```
@@ -124,11 +255,6 @@ The proxy checks npm for a newer version on startup and every 3 minutes. When a
 newer version is found it installs it globally (`npm install -g`) and logs a
 notice — **restart `bili` to pick up the new version**.
 
-```bash
-bili update          # check & install now (manual, bypasses 3min throttle)
-bili --no-auto-update   # disable self-update for this run
-```
-
 Disable permanently via config (`"autoUpdate": false`) or env
 (`ACP_AUTO_UPDATE=0`).
 
@@ -259,43 +385,15 @@ built-in model table, then to `modelContextLimit`.
 **API keys are never stored in the proxy** — whatever key the agent sends is
 passed through untouched to the upstream.
 
-### Routing
-
-Point any agent at the proxy using a provider name as a path segment. The
-proxy strips the name and forwards to that provider's root URL.
-
-```
-agent baseURL:  http://localhost:8787/zhipu/api/coding/paas/v4
-                 └──────────┬──────────┘└────────┬────────┘
-                     proxy host           remaining path
-                     + provider name      (forwarded as-is)
-```
-
-#### Claude Code (Anthropic)
-
-```bash
-export ANTHROPIC_BASE_URL=http://localhost:8787/anthropic
-export ANTHROPIC_API_KEY=sk-ant-...   # real key — passed through as-is
-claude
-```
-
-#### Codex / any OpenAI-compatible agent (zhipu / openai / deepseek)
-
-```bash
-export OPENAI_BASE_URL=http://localhost:8787/zhipu/api/coding/paas/v4
-export OPENAI_API_KEY=<your real glm key>   # passed through as-is
-codex
-```
-
-The `/zhipu/...` prefix tells the proxy to route to the `zhipu` provider; the
-remaining `/api/coding/paas/v4/...` path is preserved.
-
-### Notes on provider names
+### Provider name rules
 
 - Must start with a letter, contain only letters/digits/`-`/`_`.
 - Reserved words (`v1`, `chat`, `completions`, `messages`, `models`, `api`)
   are rejected to avoid colliding with real API path segments.
 - The provider name can appear anywhere in the path; the longest match wins.
+- With **no providers** declared (e.g. you emptied the `providers` block),
+  every request is forwarded to the default `upstream` with its full path —
+  an edge case, not the normal flow.
 
 ## How sessions work
 

package/README.zh-CN.md

@@ -40,53 +40,176 @@ npm install -g billion-context
 
 这会安装 `bili` 命令(`bili-proxy` 保留为别名)。
 
-## 用法
+## 快速上手
 
-### 启动代理
+三步:**启动代理 → 编辑配置文件 → 把客户端指向它**。
+压缩是自动注入的 —— 你只需配置路由,无需配置压缩本身。
+
+### 第 1 步 —— 启动代理
 
 ```bash
 bili
 ```
 
-就这么简单。代理从 `~/.config/billion-context/billion-context.json`(XDG)读取配置,监听 `127.0.0.1:8787`。如果配置文件还不存在,会用合理默认值,并打印期望的文件位置。
+它监听 `http://127.0.0.1:8787`。保持这个终端开着(或后台运行,见[运行代理](#运行代理))。
 
-### 快速覆盖(命令行参数)
+首次运行 `bili` 会**自动创建一份空的配置文件**,并告诉你路径:
 
-```bash
-bili --port 9000              # 改监听端口
-bili --host 0.0.0.0           # 监听所有网卡
-bili --debug                 # 详细日志(也可在配置里设 "debug": true)
-bili --passthrough           # 不压缩直接转发(冒烟测试模式)
-bili --config ~/my-bili.json # 用别的配置文件
+```
+[acp-config] created empty config at ~/.config/billion-context/billion-context.json — add your providers (see README Quickstart), then restart
 ```
 
-参数优先级高于配置文件和环境变量。`bili --help` 列出全部。
+### 路由怎么工作
 
-### 把你的助手指向代理
+代理按 **URL 路径里的 provider 名**路由 —— host 后面的第一段路径。它会
+剥离该名字,把剩余部分转发给那个 provider。名字之后的整段路径原样透传:
 
-代理按 **URL 路径里的 provider 名**路由。把助手的 base URL 设为 `http://localhost:8787/<provider>/...`,代理就转发到该 provider(如何在配置里声明 provider 见[配置](#配置))。
+```
+客户端 baseURL: http://localhost:8787/zhipu/api/coding/paas/v4
+                 └──────────┬──────────┘└────────┬────────┘
+                     代理 host            剩余路径
+                     + provider 名        (原样转发)
+```
 
-#### Claude Code(Anthropic)
+这就是为什么第 2 步让你声明带名字的 provider、第 3 步又让你把同样的名字
+放在客户端 base URL 的开头 —— 代理凭这个知道每条请求发到哪。
+稍后在配置文件中,`zhipu` 对应的是:
+```json
+    "zhipu": {
+      "url": "https://open.bigmodel.cn",
+      "models": {
+        "glm-5.2": { "context": 1000000, "output": 131072 }
+      }
+```
 
-```bash
-export ANTHROPIC_BASE_URL=http://localhost:8787/anthropic
-export ANTHROPIC_API_KEY=sk-ant-...   # 真实 key —— 原样透传
-claude
+
+### 第 2 步 —— 编辑配置文件
+
+打开第 1 步创建的文件(`~/.config/billion-context/billion-context.json`),
+编辑 `providers` 块,填入你付费使用的 provider。每个条目是一个
+**名字 → URL** 映射;这个名字就是你在第 3 步里写进客户端 base URL 的东西。
+
+```json
+{
+  "providers": {
+    "zhipu": {
+      "url": "https://open.bigmodel.cn",
+      "models": {
+        "glm-5.2": { "context": 1000000, "output": 131072 }
+      }
+    },
+    "anthropic": "https://api.anthropic.com",
+  }
+}
 ```
 
-#### Codex / 任意 OpenAI 兼容助手(智谱 / openai / deepseek)
+- 删掉你不用的 provider。
+- 添加其他的(例如 `"deepseek": "https://api.deepseek.com"`)。
+- 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 窗口、可选字段 —— 见[配置](#配置)。)
+
+### 第 3 步 —— 把客户端指向代理
+
+编辑客户端自己的配置文件,让它把请求发到
+`http://localhost:8787/<provider>/...`(第 2 步声明的 provider 名作为路径
+第一段)。把你的**真实** API key 也填进客户端配置 —— 代理原样透传。
+
+#### Pi(billion-context-pi)
+
+打开 `~/.pi/agent/models.json`,把你现有 provider 的 **`baseUrl` 这一行**改成指向代理,其他字段都不用动:
+
+```jsonc
+// 改之前:
+"baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
+// 改之后(把 host 换成代理 + 你起的 provider 名):
+"baseUrl": "http://localhost:8787/zhipu/api/coding/paas/v4",
+```
+
+`http://localhost:8787` 是代理,`zhipu` 是第 2 步起的名字,剩余路径 `/api/coding/paas/v4` 原样转发到智谱。`apiKey`、`api`、`models` 都不用改。
+
+| `api` 值 | `baseUrl` 应指向 |
+|---|---|
+| `openai-completions` | OpenAI 兼容端点(GLM/DeepSeek/OpenAI)→ `…/zhipu/...` |
+| `anthropic-messages` | Anthropic 兼容端点 → `…/anthropic` |
+
+> 如果你装了 `billion-context-pi` 扩展,用隔离的 agent 目录跑 Pi
+> (`PI_CODING_AGENT_DIR=…`),免得客户端扩展和 proxy 双重压缩。
+> `bili-test-pi` 脚本帮你做好了这层隔离。
+
+#### OpenCode
+
+打开 `~/.config/opencode/opencode.json`,把你现有 provider 的 **`baseURL` 这一行**改成指向代理:
+
+```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
+
+打开 `~/.codex/config.toml`,把现有 provider 的 **`base_url` 这一行**改成指向代理:
+
+```toml
+# 改之前:
+base_url = "https://open.bigmodel.cn/api/coding/paas/v4"
+# 改之后:
+base_url = "http://localhost:8787/zhipu/api/coding/paas/v4"
+```
+
+其他字段(`name`、`wire_api`、`env_key`)都不用改。
+
+> Codex 的 Responses API 需要上游说 Responses 协议。多数区域性 OpenAI
+> 兼容端点只说 `/chat/completions`;如果你的端点在 `/responses` 上 404,
+> 用一个说 Responses 的中转,或用官方 OpenAI API。
+
+#### 其他客户端(Cursor / Aider / Continue …)
+
+暂不支持。代理目前说 Anthropic、OpenAI chat-completions、OpenAI Responses
+三种协议 —— 如果你的客户端用别的协议或非标准 auth header,还用不了。
+
+### 验证
+
+代理跑着、配置保存了之后,确认它能应答,并且第一个真实请求在日志里显示压缩活动:
 
 ```bash
-export OPENAI_BASE_URL=http://localhost:8787/zhipu/api/coding/paas/v4
-export OPENAI_API_KEY=<你的真实智谱 key>   # 原样透传
-codex
+# 健康检查(代理是否在跑 + 转发到哪)
+curl -s http://localhost:8787/__acp/health
+# → {"ok":true,"upstream":"https://api.anthropic.com"}
+
+# 实时会话统计(发过真实请求后)
+curl -s http://localhost:8787/__acp/stats
 ```
 
-`/zhipu/...` 前缀告诉代理路由到 `zhipu` provider;剩余路径保留不变。
+然后从助手发一条消息,观察日志(`~/.local/state/billion-context/bili.log`,
+同时也打到 stderr)。每个请求应该看到一行 `processTurn`,等对话变长后
+会出现 `[acp-usage] round N input=X cached=Y (cache hit Z%)` + `compress` 事件。
 
-#### Cursor / Aider / 其他
+## 运行代理
 
-在助手设置里把 base URL 设为 `http://localhost:8787/<provider>`。
+### 命令行参数
+
+```bash
+bili --port 9000              # 改监听端口
+bili --host 0.0.0.0           # 监听所有网卡(见下面的 host 说明)
+bili --debug                 # 详细日志(也可在配置里设 "debug": true)
+bili --passthrough           # 不压缩直接转发(冒烟测试模式)
+bili --config ~/my-bili.json # 用别的配置文件
+bili update                  # 立即检查并安装新版本(跳过节流)
+bili --no-auto-update        # 本次启动禁用自动更新
+```
+
+参数优先级高于环境变量和配置文件。`bili --help` 列出全部。
 
 ### 调试
 
@@ -100,11 +223,10 @@ codex
 
 ### 日志文件
 
-所有日志**默认同时写入文件**:`~/.local/state/billion-context/bili.log`(XDG state 目录)。同时仍打印到 stderr,所以前台运行 `bili start` 时终端也能看到。
+所有日志**默认同时写入文件**:`~/.local/state/billion-context/bili.log`
+(XDG state 目录)。同时仍打印到 stderr,所以前台运行 `bili start` 时终端也能看到。
 
 ```bash
-bili start                # 日志 → ~/.local/state/billion-context/bili.log + 终端
-bili update               # (见下文)
 # 配置: "logFile": "/custom/path.log"
 # 环境变量: ACP_LOG_FILE=/custom/path.log   (或 ACP_LOG_FILE=off 关闭文件,只保留 stderr)
 ```
@@ -115,11 +237,6 @@ bili update               # (见下文)
 
 代理启动时和每 3 分钟检查 npm 是否有新版本。发现新版本就全局安装(`npm install -g`)并打印通知 —— **重启 `bili` 才能生效**。
 
-```bash
-bili update          # 立即检查并安装(手动,跳过 3 分钟节流)
-bili --no-auto-update   # 本次启动禁用自动更新
-```
-
 永久禁用:配置(`"autoUpdate": false`)或环境变量(`ACP_AUTO_UPDATE=0`)。
 
 ## 配置
@@ -232,40 +349,13 @@ bili --no-auto-update   # 本次启动禁用自动更新
 
 **API key 永远不存进代理** —— 助手发什么 key,原样透传给上游。
 
-### 路由
-
-用 provider 名作为路径段把任意助手指向代理。代理剥离该名字并转发到该 provider 的根 URL。
-
-```
-助手 baseURL:   http://localhost:8787/zhipu/api/coding/paas/v4
-                 └──────────┬──────────┘└────────┬────────┘
-                     代理 host            剩余路径
-                     + provider 名        (原样转发)
-```
-
-#### Claude Code(Anthropic)
-
-```bash
-export ANTHROPIC_BASE_URL=http://localhost:8787/anthropic
-export ANTHROPIC_API_KEY=sk-ant-...   # 真实 key —— 原样透传
-claude
-```
-
-#### Codex / 任意 OpenAI 兼容助手(智谱 / openai / deepseek)
-
-```bash
-export OPENAI_BASE_URL=http://localhost:8787/zhipu/api/coding/paas/v4
-export OPENAI_API_KEY=<你的真实智谱 key>   # 原样透传
-codex
-```
-
-`/zhipu/...` 前缀告诉代理路由到 `zhipu` provider;剩余 `/api/coding/paas/v4/...` 路径保留不变。
-
-### Provider 名注意事项
+### Provider 名规则
 
 - 必须以字母开头,只含字母/数字/`-`/`_`。
 - 保留字(`v1`、`chat`、`completions`、`messages`、`models`、`api`)被拒绝,以免与真实 API 路径段冲突。
 - provider 名可出现在路径任意位置;最长匹配优先。
+- **未声明任何 providers**(比如你清空了 `providers` 块)时,每个请求按完整
+  原始路径转发到默认 `upstream` —— 边缘场景,非正常流程。
 
 ## 会话机制