Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 40 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,31 @@ base_url = "http://localhost:8787/bili/https://api.openai.com/v1"
upstream URL is configured, prepend `http://localhost:8787/bili/` to it.
Nothing else changes.

#### B. Login/subscription clients (MITM transparent proxy)
#### B. Codex Route (API key or ChatGPT subscription)

Codex can be connected without changing its active `model_provider` and
without trusting a MITM certificate. Start bili, open
[http://localhost:8787/__bili/](http://localhost:8787/__bili/), then enable
**Codex Route** on the Routing page. For scripted startup, enable it before
starting the owning server:

```bash
bili codex enable --port 8787
bili start --port 8787
```

billion-context resolves only the active Codex provider, records its real
`base_url`, and temporarily replaces that one field with
`http://127.0.0.1:8787/codex`. The provider id never changes, so existing Codex
history stays in the same bucket. Disabling the route or gracefully stopping
the owning bili process restores the original field; edits made by the user
while routing was active are preserved. A stale takeover is safely recovered
the next time bili starts.

The Routing page also offers a manual, backup-first repair for sessions created
by older bili test provider ids. Normal routing never migrates Codex history.

#### C. Other login/subscription clients (MITM transparent proxy)

Clients you sign **into an account** (ChatGPT Plus/Pro, Claude, ZCode coding
plan, …) authenticate via **OAuth and hardcode the endpoint** — you can't
Expand All @@ -126,7 +150,7 @@ Supported login clients:
| Client | Login | Endpoint hardcoded | Status |
|---|---|---|---|
| **ZCode** | bigmodel coding plan (OAuth) | `open.bigmodel.cn` (builtin provider) | ✅ tested |
| **Codex** | ChatGPT account (OAuth) | `chatgpt.com/backend-api` | ❓ untested (may not work — needs verification) |
| **Codex** | ChatGPT account (OAuth) | `chatgpt.com/backend-api` | ✅ use Codex Route above; MITM is fallback only |
| **Claude Code** | Claude subscription (OAuth) | `api.anthropic.com` | ❓ untested (may not work — needs verification) |

How MITM mode works: the client only offers an **HTTP proxy** setting, so it
Expand All @@ -153,8 +177,8 @@ non-model traffic.
- **HTTP Proxy**: `http://127.0.0.1:8787`
- **Proxy CA certificate path**: `~/.local/share/billion-context/ca/root-ca.pem`
- (optional) **No-proxy list**: `localhost,127.0.0.1`
- (For ZCode specifically: **Settings → Network**. For Codex/Claude Code:
set the `HTTPS_PROXY` env var and `NODE_EXTRA_CA_CERTS` to the CA path.)
- (For ZCode specifically: **Settings → Network**. For Claude Code, set the
`HTTPS_PROXY` env var and `NODE_EXTRA_CA_CERTS` to the CA path.)

3. Restart the client. Its model traffic now flows through billion-context
with compression injected. Send a message and check the proxy log
Expand Down Expand Up @@ -435,17 +459,23 @@ If the proxy's own outbound connections to a model provider are blocked
```

Rules:
- **Global `proxy`** (top level) applies to every provider's outbound.
- **Per-URL `proxy`** overrides the global for that host.
- **Per-URL `proxy`** has the highest priority for its matching provider URL.
- Remaining priority is `BILI_UPSTREAM_PROXY` → Web UI manual proxy → top-level
`proxy` → `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` → Windows system proxy
→ direct.
- Empty string `""` means **explicitly direct** (override-and-disable).
- Neither set = direct connect.
- Only HTTP proxies (`http://host:port`). SOCKS5 is not supported yet.
- Auto mode honors `NO_PROXY` and the Windows proxy bypass list for
environment/system fallbacks. A proxy pointing back to bili's own local port
is ignored or rejected to prevent a loop.
- HTTP and HTTPS proxy origins are supported. 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).
Env override: `BILI_UPSTREAM_PROXY=http://127.0.0.1:20172` (higher priority than
the config file). On Windows, common Clash/Mihomo static system proxies are
discovered automatically; the Web UI shows the effective source and any PAC
URL detected in Internet Settings.

**MITM vs `/bili/` — distinguishing the key scheme.** A login client
(ZCode via MITM) and an API-key client can both hit the same host
Expand Down
42 changes: 33 additions & 9 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,27 @@ base_url = "http://localhost:8787/bili/https://api.openai.com/v1"

**其他 API-key 客户端(Cursor / Aider / Continue ……)** —— 只要配置了上游 URL,前面加 `http://localhost:8787/bili/` 就行,其他都不用改。

#### B. 登录/订阅客户端(MITM 透明代理)
#### B. Codex 路由(API key 或 ChatGPT 订阅)

Codex 不需要改 `model_provider`,也不需要信任 MITM 证书。启动 bili,打开
[http://localhost:8787/__bili/](http://localhost:8787/__bili/),在“路由”页启用
**Codex 路由**。脚本化启动时,先启用路由,再启动拥有它的服务:

```bash
bili codex enable --port 8787
bili start --port 8787
```

billion-context 只解析当前激活的 Codex provider,记录它的真实 `base_url`,
并临时只把这个字段替换成 `http://127.0.0.1:8787/codex`。provider id 始终
不变,所以现有 Codex 历史仍在同一个分桶。关闭路由或正常停止拥有该路由的
bili 进程时会恢复原字段;路由期间用户自己做的新修改会被保留。异常退出留下
的接管状态会在下次启动 bili 时安全恢复。

“路由”页还提供旧版 bili 测试 provider 会话的手动修复:先预览、先备份、再
修复。正常路由绝不会自动迁移 Codex 历史。

#### C. 其他登录/订阅客户端(MITM 透明代理)

需要 **登录账号**的客户端(ChatGPT Plus/Pro、Claude、ZCode coding plan
……)通过 **OAuth 认证,且硬编码了端点**——你改不了 baseURL,所以 `/bili/`
Expand All @@ -107,7 +127,7 @@ base_url = "http://localhost:8787/bili/https://api.openai.com/v1"
| 客户端 | 登录方式 | 硬编码端点 | 状态 |
|---|---|---|---|
| **ZCode** | 智谱 coding plan(OAuth) | `open.bigmodel.cn`(内置 provider) | ✅ 已测试 |
| **Codex** | ChatGPT 账号(OAuth) | `chatgpt.com/backend-api` | ❓ 未测试(可能不支持,需验证) |
| **Codex** | ChatGPT 账号(OAuth) | `chatgpt.com/backend-api` | ✅ 优先使用上面的 Codex 路由;MITM 仅作 fallback |
| **Claude Code** | Claude 订阅(OAuth) | `api.anthropic.com` | ❓ 未测试(可能不支持,需验证) |

MITM 模式原理:这类客户端只提供 **HTTP 代理**设置,所以它发送
Expand All @@ -130,8 +150,8 @@ MITM 默认开启,且只对一份 **白名单**中的模型域名(`open.bigmodel
- **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 路径。)
- (ZCode 具体位置:**设置 → 网络**。Claude Code:设 `HTTPS_PROXY` 环境变量
+ `NODE_EXTRA_CA_CERTS` 指向 CA 路径。)

3. 重启客户端。它的模型流量现在会经过 billion-context 并注入压缩。发一条消息,看 proxy 日志(`~/.local/state/billion-context/bili.log`)应出现
`mitm <域名>:443 tunnel established`。
Expand Down Expand Up @@ -368,14 +388,18 @@ key 就是客户端写在 `/bili/` 后面的那个字符串:
```

规则:
- **全局 `proxy`**(顶层)对所有提供商的出站生效。
- **按 URL 的 `proxy`** 覆盖该域名的全局设置。
- **按 URL 的 `proxy`** 对匹配的 provider URL 优先级最高。
- 其余优先级为:`BILI_UPSTREAM_PROXY` → Web UI 手动代理 → 顶层 `proxy` →
`HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` → Windows 系统代理 → 直连。
- 空字符串 `""` 表示**明确直连**(覆盖并禁用)。
- 都不配 = 直连。
- 只支持 HTTP 代理(`http://host:port`)。SOCKS5 暂不支持。
- 自动模式会让环境/系统 fallback 遵守 `NO_PROXY` 与 Windows 绕过列表。
指回 bili 自己本地端口的代理会被跳过或拒绝,防止自环。
- 支持 HTTP 和 HTTPS 代理 origin。SOCKS5 暂不支持。
- 两条出站路径都覆盖:`/bili/` 路径模式(fetch)和 MITM CONNECT 隧道(代理连接真实上游的链路走 HTTP CONNECT 代理)。

环境变量覆盖:`BILI_UPSTREAM_PROXY=http://127.0.0.1:20172`(等同全局 `proxy`;两者都设时配置文件优先)。
环境变量覆盖:`BILI_UPSTREAM_PROXY=http://127.0.0.1:20172`(优先于配置文件)。
Windows 下会自动发现常见 Clash/Mihomo 静态系统代理;Web UI 会显示实际来源,
以及 Internet Settings 中检测到的 PAC URL。

**MITM 与 `/bili/` —— 用 scheme 区分。** 登录客户端(ZCode 走 MITM)和 API-key 客户端可能连同一个域名(`open.bigmodel.cn`)。为了让它们的配置能区分,MITM 流量在查找键里用 `mitm://` scheme,`/bili/` 流量用真实的 `https://`:

Expand Down
8 changes: 8 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
"@types/node": "^22.0.0",
"@types/node-forge": "^1.3.14",
"acp-kernel": "0.0.17",
"fzstd": "0.1.1",
"node-forge": "^1.4.0",
"tar": "^7.5.22",
"tsup": "^8.0.0",
Expand Down
61 changes: 55 additions & 6 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,13 @@ import { checkForUpdate, startAutoUpdate } from "./update.js";
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import path from "node:path";
import {
claimCodexTakeover,
disableCodexTakeover,
enableCodexTakeover,
getCodexTakeoverStatus,
recoverStaleCodexTakeover,
} from "./codex-takeover.js";

const VERSION = (() => {
try {
Expand Down Expand Up @@ -51,6 +58,9 @@ const HELP = `bili ${VERSION} — billion-context proxy

Usage:
bili [start] [options] start the proxy (default: reads ${defaultConfigFile()})
bili codex enable [--port N] route Codex Desktop through the local proxy
bili codex disable restore the active Codex provider endpoint
bili codex status show Codex Desktop local-route status
bili update check for & install a newer version now
bili --version print version
bili --help show this help
Expand All @@ -72,7 +82,8 @@ Docs: https://github.com/ranxianglei/billion-context
`;

type Parsed = {
command: "start" | "update" | "help" | "version";
command: "start" | "update" | "codex" | "help" | "version";
codexAction?: "enable" | "disable" | "status";
overrides: Record<string, string | undefined>;
};

Expand Down Expand Up @@ -133,25 +144,42 @@ function parseArgs(argv: string[]): Parsed {
}
}

// First positional (if any) is the command. "start" | "update" are recognized;
// First positional (if any) is the command. "start" | "update" | "codex" are recognized;
// an unknown command is an error.
if (positional.length > 0) {
const cmd = positional[0]!;
if (cmd === "start") {
command = command === "help" || command === "version" ? command : "start";
} else if (cmd === "update") {
command = "update";
} else if (cmd === "codex") {
command = "codex";
} else {
console.error(`bili: unknown command "${cmd}" (try "bili --help")`);
process.exit(2);
}
}

return { command, overrides };
let codexAction: Parsed["codexAction"];
if (positional[0] === "codex") {
command = "codex";
const action = positional[1];
if (action !== "enable" && action !== "disable" && action !== "status") {
console.error('bili: "codex" requires enable, disable, or status');
process.exit(2);
}
if (positional.length > 2) {
console.error(`bili: unexpected argument "${positional[2]}"`);
process.exit(2);
}
codexAction = action;
}

return { command, codexAction, overrides };
}

export async function main(): Promise<void> {
const { command, overrides } = parseArgs(process.argv.slice(2));
const { command, codexAction, overrides } = parseArgs(process.argv.slice(2));
if (command === "help") {
process.stdout.write(HELP);
return;
Expand All @@ -166,15 +194,36 @@ export async function main(): Promise<void> {
return;
}

// CLI flags override env (which overrides the config file inside
// loadOptions). Merge into process.env so loadOptions picks them up.
for (const [k, v] of Object.entries(overrides)) {
if (v !== undefined) process.env[k] = v;
}
if (command === "codex") {
if (codexAction === "enable") recoverStaleCodexTakeover();
const status = codexAction === "enable"
? enableCodexTakeover(loadOptions().port)
: codexAction === "disable"
? disableCodexTakeover()
: getCodexTakeoverStatus();
if (status.state === "enabled") {
process.stdout.write(`Codex route enabled for ${status.providerId}: ${status.baseUrl} → ${status.originalBaseUrl}\n`);
} else if (status.state === "disabled") {
const provider = status.provider ? ` (provider ${status.provider.id})` : "";
process.stdout.write(`Codex route disabled${provider}: ${status.configPath}${status.detail ? `\n${status.detail}` : ""}\n`);
} else {
process.stdout.write(`Codex Desktop local route conflict: ${status.detail ?? status.configPath}\n`);
process.exitCode = 1;
}
return;
}

// CLI flags override env (which overrides the config file inside
// loadOptions). Merge into process.env so loadOptions picks them up.
// First run: seed a template config so the user has a file to edit rather
// than a bare error. No-op if it already exists.
recoverStaleCodexTakeover();
ensureConfigTemplate();
const opts = loadOptions();
claimCodexTakeover(process.pid);
await startServer(opts);

// Start background auto-update after the server is listening so a slow
Expand Down
Loading
Loading