billion-context 0.1.19 → 0.1.21

package/README.md

@@ -40,54 +40,222 @@ 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
+```
+
+**Or configure via the web UI** (easier): open `http://localhost:8787/__acp/` in
+a browser while the proxy is running — edit providers in a form, and get
+copy-ready config snippets for Pi / OpenCode / Codex. The startup banner prints
+this URL too:
 
-Flags override the config file and env vars. `bili --help` lists them all.
+```
+acp-proxy listening on http://localhost:8787 — web UI: http://localhost:8787/__acp/
+```
 
-### Point your agent at the proxy
+This is the recommended path for first-time setup. (Prefer editing the JSON
+file directly — e.g. for git-managed or scripted deployments? See
+[Manual config file](#manual-config-file) below.)
 
-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).
+### How routing works
 
-#### Claude Code (Anthropic)
+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:
 
-```bash
-export ANTHROPIC_BASE_URL=http://localhost:8787/anthropic
-export ANTHROPIC_API_KEY=sk-ant-...   # real key — passed through as-is
-claude
 ```
+client baseURL:  http://localhost:8787/zhipu/api/coding/paas/v4
+                  └──────────┬──────────┘└────────┬────────┘
+                      proxy host           remaining path
+                      + provider name      (forwarded as-is)
+```
+
+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 — Configure your providers
+
+Open the **web UI** at `http://localhost:8787/__acp/` and add your providers
+there (add provider → fill name + URL + per-model context → Save). This writes
+to `~/.config/billion-context/billion-context.json` directly. Then **restart
+`bili`** — the startup banner lists your routes:
+
+```
+acp-proxy listening on http://localhost:8787 — routes: anthropic=https://api.anthropic.com, zhipu=https://open.bigmodel.cn
+```
+
+That confirms the proxy picked up your config. (Prefer editing the JSON file by
+hand? See [Manual config file](#manual-config-file). 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` |
+
+> 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.
+
+### Web UI
 
-#### Codex / any OpenAI-compatible agent (zhipu / openai / deepseek)
+Open `http://localhost:8787/__acp/` in a browser while the proxy is running. You can:
+
+- **Edit providers** in a form (add/remove providers and per-model context windows) and save — this writes to `billion-context.json` directly.
+- **Generate client URLs** — pick a provider, get ready-to-copy config snippets for Pi / OpenCode / Codex (the `baseUrl`/`baseURL`/`base_url` line with the proxy origin + provider name filled in).
+- **View sessions** — live table of active sessions (requests, tokens saved, last seen), auto-refreshing.
+
+Changes to providers require a **restart** to take effect (the UI tells you this).
+
+### Manual config file
+
+Prefer editing JSON by hand — for git-managed configs, scripted deployments, or
+if you just don't want to use the browser? The web UI writes to the same file,
+so you can edit it directly with identical results.
+
+Open `~/.config/billion-context/billion-context.json` and edit the `providers`
+block. Each entry is a **name → URL** mapping; the name is what you 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`**. (Full schema — per-model context windows,
+optional fields — is in [Configuration](#configuration).)
+
+### 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 +276,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 +290,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 +420,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,170 @@ 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`。保持这个终端开着(或后台运行,见[运行代理](#运行代理))。
 
-### 快速覆盖(命令行参数)
+点击[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" />
 
-```bash
-bili --port 9000              # 改监听端口
-bili --host 0.0.0.0           # 监听所有网卡
-bili --debug                 # 详细日志(也可在配置里设 "debug": true)
-bili --passthrough           # 不压缩直接转发(冒烟测试模式)
-bili --config ~/my-bili.json # 用别的配置文件
+### 第 2 步 —— 编辑配置文件
+
+复制以下内容
+
+<img width="2931" height="1519" alt="image" src="https://github.com/user-attachments/assets/c02278be-bc7a-4f14-8f58-0f2d83784d54" />
+
+> 不想用网页?也可以直接手编 JSON 文件,见下文[手动配置文件](#手动配置文件)。
+
+### 第 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",
 ```
 
-参数优先级高于配置文件和环境变量。`bili --help` 列出全部。
+`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` |
 
-代理按 **URL 路径里的 provider 名**路由。把助手的 base URL 设为 `http://localhost:8787/<provider>/...`,代理就转发到该 provider(如何在配置里声明 provider 见[配置](#配置))。
+> 如果你装了 `billion-context-pi` 扩展,用隔离的 agent 目录跑 Pi
+> (`PI_CODING_AGENT_DIR=…`),免得客户端扩展和 proxy 双重压缩。
+> `bili-test-pi` 脚本帮你做好了这层隔离。
 
-#### Claude Code(Anthropic)
+#### OpenCode
 
-```bash
-export ANTHROPIC_BASE_URL=http://localhost:8787/anthropic
-export ANTHROPIC_API_KEY=sk-ant-...   # 真实 key —— 原样透传
-claude
+打开 `~/.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"
 ```
 
-#### Codex / 任意 OpenAI 兼容助手(智谱 / openai / deepseek)
+其他字段(`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,还用不了。
+
+### 手动配置文件
+
+上面用网页配置。如果你不想用网页、想把配置纳入 git 管理、或者用脚本
+自动化部署,也可以直接手编 JSON 文件,效果完全一样。
+
+打开 `~/.config/billion-context/billion-context.json`,编辑 `providers` 块。
+每个条目是一个**名字 → 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"
+  }
+}
+```
+
+- 删掉你不用的 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 窗口、可选字段 —— 见[配置](#配置)。)
+
+### 网页配置
+
+代理跑着的时候,在浏览器打开 `http://localhost:8787/__acp/`。你可以:
+
+- **编辑 providers** —— 用表单增删 provider 和按模型的 context 窗口,点 Save 直接写入 `billion-context.json`。
+- **生成客户端 URL** —— 选一个 provider,得到可直接复制的配置片段(Pi / OpenCode / Codex 的 `baseUrl`/`baseURL`/`base_url` 一行,已填好代理地址 + provider 名)。
+- **查看会话** —— 实时会话表(请求数、省的 token、最后活跃时间),自动刷新。
+
+改完 providers 需要**重启 bili** 才生效(UI 会提醒你)。
+
+### 验证
+
+代理跑着、配置保存了之后,确认它能应答,并且第一个真实请求在日志里显示压缩活动:
 
 ```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 / 其他
+```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        # 本次启动禁用自动更新
+```
 
-在助手设置里把 base URL 设为 `http://localhost:8787/<provider>`。
+参数优先级高于环境变量和配置文件。`bili --help` 列出全部。
 
 ### 调试
 
@@ -100,11 +217,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 +231,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 +343,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` —— 边缘场景,非正常流程。
 
 ## 会话机制