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
26 changes: 25 additions & 1 deletion CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -284,6 +284,8 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed
| `imageTokenCap` | number | unset (uncapped) | — | Per-image token cost cap for this route. |
| `resign` | scheme → { enabled?, passthrough?, credentialRef? } | {} (global map applies) | — | Per-route overrides of the global resign map (level 2, deepest wins). |
| `bind` | string (named entries only) | unset | — | Deep-merge a named (non-URL) entry onto the bound URL lane as an alias; without bind a named entry stays routing-inert. |
| `apiKeyEnv` | string (env var name) | unset | — | Lane credential override (#2336): replace the client's credential with this env variable's value for this lane. Exactly one of apiKeyEnv/credentialRef; see [Lane credentials](#lane-credentials-apikeyenv--credentialref). |
| `credentialRef` | string (store name) | unset | — | Lane credential override via the private summary-credential store (secret:NAME semantics). |
| `compactionOptIn` | boolean | false | BILI_NON_HTTP_PROVIDERS | Named entries only: opt a non-http(s)-baseUrl provider into compaction ownership (pi/omp lanes); unions with env BILI_NON_HTTP_PROVIDERS. |

**Environment-only variables**
Expand Down Expand Up @@ -866,7 +868,7 @@ Three more #2030 keys extend existing blocks: [`mitm.handshakeTimeoutMs`](#clien

## Providers

The `providers` block maps **upstream URLs** to per-provider configuration. Each key is a URL prefix; each value can declare model context windows, a per-provider proxy, a compression protocol, a wire-protocol declaration, compression overrides, an image billing mode, a per-route passthrough, and a client-side direct exemption. Non-URL **named** keys are also allowed: they are routing-inert on their own, and become real lanes via [`bind`](#named-provider-entries-bind).
The `providers` block maps **upstream URLs** to per-provider configuration. Each key is a URL prefix; each value can declare model context windows, a per-provider proxy, a compression protocol, a wire-protocol declaration, compression overrides, an image billing mode, a per-route passthrough, a client-side direct exemption, and a lane credential override ([`apiKeyEnv`](#lane-credentials-apikeyenv--credentialref)). Non-URL **named** keys are also allowed: they are routing-inert on their own, and become real lanes via [`bind`](#named-provider-entries-bind).
```jsonc
{
"providers": {
Expand Down Expand Up @@ -934,6 +936,24 @@ A key that is not a URL (e.g. `"claude-bridge"`) is a **named** entry. On its ow
}
```

### Lane credentials (`apiKeyEnv` / `credentialRef`)

A URL-keyed lane (or a named entry with `bind`) can send **its own** credential upstream instead of the client's — the lane owner's key replaces whatever the agent client put on the wire (#2336). Typical case: a shared machine proxy where the owner's `deepseek` lane authenticates with the owner's key no matter which client (and whose personal key) is talking through it.

```jsonc
{
"providers": {
"https://api.deepseek.com": { "apiKeyEnv": "DEEPSEEK_LANE_KEY" }
}
}
```

- **Type:** `string` — `apiKeyEnv` is an environment-variable NAME (`env:VAR` semantics), `credentialRef` is a NAME in the private [summary-credential store](#shared-external-summary-service) (`secret:NAME` semantics). Exactly one of the two per entry; invalid values reject the config (#1909 discipline — startup failure / web-UI 400).
- **Replacement rules:** `x-api-key` and `x-goog-api-key` are replaced outright. `authorization` is replaced **only** when the client's value is a Bearer token — any other scheme (SDK-HMAC signatures, mTLS fingerprints…) is signature-owned and left untouched, with a warning. A request carrying none of the three gains `authorization: Bearer <key>`.
- **#1884 interplay:** skipped whenever the CodeArts re-sign arm is active on the request — the re-signer owns `Authorization` there.
- **Failure posture:** if the env var is unset or the secret is absent, bili keeps the client's own headers and warns once per lane+reference (visible, never silently degrading to a guaranteed 401). The warning re-arms after a successful resolution.
- Applied once to the shared forward-header set, so every egress of the request — initial send, role-ladder retry, overflow refold, compress-loop rounds, continuation refetch — carries the lane credential.

### `models`

- **Type:** `Record<string, { context?: number; output?: number; compress?: CompressSettings; benefit?: boolean }>`
Expand Down Expand Up @@ -1089,6 +1109,10 @@ A recipe carries: `baseUrl` (HTTPS; loopback HTTP allowed for local development;

Up to 16 targets per chain are supported. Saving an enabled chain through the Web API validates that every reference resolves (unknown provider or model → HTTP 400). At runtime an unresolvable reference is logged once and disables the chain until fixed — it never falls back to summarizing with the main model. `secret:` values are stored separately from the main JSON configuration in the private `billion-context.json.summary-credentials.json` file and are never returned by the configuration API. On Windows, protect this file and its parent directory with an administrator-only ACL; stale `.lock` files require manual removal after confirming no proxy process is writing the store. The total budget is shared across all targets and compression entry points, and cancellation or session-state changes discard generated results without folding.

#### Agent-reported providers (fallback layer)

An ACP-native agent (currently the `pi` extension) reports its own configured providers to the proxy once per process (`POST /__bili/agent-providers`): provider name, base URL, wire protocol, resolved API key, and model list. These recipes form a **fallback layer** — a chain may reference `"zhipu/glm-5"` without the dial fields being duplicated in the file, so a provider configured once in the agent's own config is directly usable as a summary target. Merge order is **file wins**: a file recipe with the same name shadows the agent's contribution for that provider entirely (including its models). The agent layer never persists to disk: keys live only in proxy process memory, are never returned by the configuration API, and never appear in logs. Skip rules on the reporting side: OAuth-authenticated providers, `auth.json` ("stored") credentials, providers whose endpoint points back at the proxy itself, and wire protocols without a summary dial (`bedrock`, `vertex`, `mistral`, `pi-messages`) are not reported. The Web UI marks agent-reported models with an `(agent)` badge in the target dropdown.

The three levels, from broadest to most specific:

1. **Global** — a top-level `"compress": { … }` key. Applies to every request. This is the only level where the `injectTool` / `injectNudge` toggles are honoured.
Expand Down
26 changes: 25 additions & 1 deletion CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -284,6 +284,8 @@
| `imageTokenCap` | number | unset (uncapped) | — | 本路由单张图片 token 成本上限。 |
| `resign` | scheme → { enabled?, passthrough?, credentialRef? } | {} (global map applies) | — | 按路由覆盖全局 resign 映射(第 2 级,最深层胜出)。 |
| `bind` | string (named entries only) | unset | — | 把具名(非 URL)条目深合并到所绑定的 URL 通道作为别名;无 bind 的具名条目不参与路由。 |
| `apiKeyEnv` | string (env var name) | unset | — | 通道凭据覆盖(#2336):用该环境变量的值替换客户端凭据。与 credentialRef 二选一;见[通道凭据](#lane-credentials-apikeyenv--credentialref)。 |
| `credentialRef` | string (store name) | unset | — | 经私有摘要凭据存储的通道凭据覆盖(secret:NAME 语义)。 |
| `compactionOptIn` | boolean | false | BILI_NON_HTTP_PROVIDERS | 仅命名条目:把非 http(s) baseUrl 供应商纳入压缩所有权(pi/omp 车道);与 env BILI_NON_HTTP_PROVIDERS 取并集。 |

**仅环境变量(无配置文件键)**
Expand Down Expand Up @@ -866,7 +868,7 @@

## Providers

`providers` 块将**上游 URL** 映射到按 provider 的配置。每个键是一个 URL 前缀;每个值可以声明模型上下文窗口、按 provider 的代理、压缩协议、wire 协议声明、压缩覆盖项、图片计费模式、按路由的透传开关,以及客户端侧直连豁免。 也允许**命名**的非 URL 键:它们本身对路由惰性无效,可通过 [`bind`](#named-provider-entries-bind) 成为真实 lane。
`providers` 块将**上游 URL** 映射到按 provider 的配置。每个键是一个 URL 前缀;每个值可以声明模型上下文窗口、按 provider 的代理、压缩协议、wire 协议声明、压缩覆盖项、图片计费模式、按路由的透传开关,客户端侧直连豁免,以及通道凭据覆盖([`apiKeyEnv`](#lane-credentials-apikeyenv--credentialref))。 也允许**命名**的非 URL 键:它们本身对路由惰性无效,可通过 [`bind`](#named-provider-entries-bind) 成为真实 lane。
```jsonc
{
"providers": {
Expand Down Expand Up @@ -934,6 +936,24 @@
}
```

### 通道凭据(`apiKeyEnv` / `credentialRef`)

URL 键通道(或带 `bind` 的命名条目)可以向上游发送**自己的**凭据而非客户端的 —— lane 主人的 key 替换 agent 客户端放在 wire 上的任何凭据(#2336)。典型场景:共享机器代理中,主人的 `deepseek` lane 无论哪个客户端(带谁的私人 key)接入,都用主人的 key 认证。

```jsonc
{
"providers": {
"https://api.deepseek.com": { "apiKeyEnv": "DEEPSEEK_LANE_KEY" }
}
}
```

- **类型:** `string` —— `apiKeyEnv` 是环境变量名(`env:VAR` 语义);`credentialRef` 是私有[摘要凭据存储](#共享外部摘要服务)中的名称(`secret:NAME` 语义)。每个条目二选一;非法值拒绝整个配置(#1909 纪律 —— 启动失败 / Web UI 400)。
- **替换规则:** `x-api-key` 与 `x-goog-api-key` 直接替换。`authorization` **仅当**客户端值是 Bearer token 时才替换 —— 其它方案(SDK-HMAC 签名、mTLS 指纹…)属签名所有,原样保留并告警。三者皆无的请求会注入 `authorization: Bearer <key>`。
- **#1884 交互:** 请求上 CodeArts 重签名臂活跃时跳过 —— 那里重签名器拥有 `Authorization`。
- **失败姿态:** env 未设或 secret 缺失时,bili 保留客户端自己的头,并按通道+引用告警一次(可见,绝不静默退化成必 401)。解析成功后告警槽重新武装。
- 在共享的转发头集合上一次性生效,请求的每次出站(初次发送、角色阶梯重试、溢出重折、压缩循环、续读重取)都携带通道凭据。

### `models`

- **类型:** `Record<string, { context?: number; output?: number; compress?: CompressSettings; benefit?: boolean }>`
Expand Down Expand Up @@ -1092,6 +1112,10 @@

每条链最多 16 个目标。通过 Web API 保存启用的链时会校验每个引用可解析(未知 provider 或 model → HTTP 400)。运行时遇到不可解析的引用会记录一次警告并禁用整条链直至修复 —— 绝不会回退用主模型写摘要。`secret:` 值单独存储在私有的 `billion-context.json.summary-credentials.json` 文件中,不随主 JSON 配置下发,配置 API 也不会返回。Windows 上请用仅管理员的 ACL 保护该文件及其父目录;确认没有代理进程在写存储后,残留的 `.lock` 文件需手工删除。总预算由全部目标与压缩入口共享;取消或会话状态变化会丢弃已生成但未落盘的结果。

#### Agent 上报的 providers(兜底层)

ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报自己已配置的 providers(`POST /__bili/agent-providers`):provider 名、base URL、线上协议、已解析的 API key 与模型清单。这些 recipes 构成一个**兜底层** —— 链可以直接引用 `"zhipu/glm-5"`,无需在文件里重复拨号字段;在 agent 自身配置过的 provider 可直接用作摘要目标。合并序为**文件优先**:同名 file recipe 会完全遮蔽 agent 对该 provider 的贡献(含模型清单)。agent 层永不落盘:key 只存在于代理进程内存,配置 API 不返回,也不进日志。上报侧的跳过规则:OAuth 认证的 provider、`auth.json`(“stored”)凭据、端点指回代理自身的 provider、以及没有摘要拨号协议的 provider(`bedrock`、`vertex`、`mistral`、`pi-messages`)都不会上报。Web 面板的目标下拉里 agent 上报的模型带 `(agent)` 标记。

三个层级,从最宽泛到最具体:

1. **全局(Global)** —— 顶层 `"compress": { … }` 键。应用于每个请求。这是唯一会生效 `injectTool` / `injectNudge` 开关的层级。
Expand Down
2 changes: 1 addition & 1 deletion reference/external-summary.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Design discussion: [#2163](https://github.com/ranxianglei/billion-context/issues

The implementation in PR #2167 wires the isolated executor in `src/external-summary.ts` into the host's compression paths through `src/external-summary-runtime.ts` and `src/external-summary-compress.ts`. `compress.externalSummary` settings are opt-in and disabled by default; the chain is three-level like every other `compress` field (whole-chain replace at provider/model level, no sub-merge) and rides the request Config rail (`ctx.config` / `effectiveConfig`, #833) — there is no side configuration file. This is a review-branch implementation, not a published release or production deployment; repository-owner approval of the configuration surface remains outstanding.

The chain is expressed as **references** (`"glm/glm-4.9-flash"`) into named provider *recipes* in the `providers` table (non-URL entries carrying `baseUrl`/`api`/credential/`models`, see `CONFIGURATION.md`). Parsing is split: `src/external-summary-settings.ts` does syntax-level chain parsing at config load (`parseExternalSummaryChain`) and reference expansion at request-apply time (`expandExternalSummaryChain` / `expandExternalSummaryChainTolerant` in `src/compress-settings.ts`), producing the expanded `ExternalSummarySettings` the executor rail consumes. An unresolvable reference in an enabled chain logs one warning and disables the chain — never a fallback to the main model. The Web API saves reject unresolvable enabled chains with HTTP 400; recipes are collected from the about-to-be-saved `providers` section (`collectNamedProviders` in `src/config.ts`).
The chain is expressed as **references** (`"glm/glm-4.9-flash"`) into named provider *recipes* in the `providers` table (non-URL entries carrying `baseUrl`/`api`/credential/`models`, see `CONFIGURATION.md`). Parsing is split: `src/external-summary-settings.ts` does syntax-level chain parsing at config load (`parseExternalSummaryChain`) and reference expansion at request-apply time (`expandExternalSummaryChain` / `expandExternalSummaryChainTolerant` in `src/compress-settings.ts`), producing the expanded `ExternalSummarySettings` the executor rail consumes. An unresolvable reference in an enabled chain logs one warning and disables the chain — never a fallback to the main model. The Web API saves reject unresolvable enabled chains with HTTP 400; recipes are collected from the about-to-be-saved `providers` section (`collectNamedProviders` in `src/config.ts`). #2336 adds an in-memory **agent-registry fallback layer** (`src/agent-providers.ts`): ACP-native agents POST their configured providers (`POST /__bili/agent-providers`, sanitized + validated by `parseAgentProviderReport`), and those recipes merge UNDER the file recipes at request-apply time (`{ ...agentProviderRecipes(), ...opts.namedProviders }`) — file wins on name collision. Agent recipes carry the resolved key inline (`apiKey` on the rail target, `XOR` with `credentialRef`; the file world still rejects plaintext keys — `parseExternalSummarySettings(value, { inlineKeys: true })` is the rail-only switch).

The executor accepts immutable task text, instructions and optional read-only reference text; an ordered list of injected asynchronous candidates; and explicit internal budgets. Wire protocols, authentication and range selection remain caller responsibilities. No provider request or fold occurs without a caller.

Expand Down
2 changes: 1 addition & 1 deletion reference/external-summary.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

PR #2167 已通过 `src/external-summary-runtime.ts` 和 `src/external-summary-compress.ts`,将 `src/external-summary.ts` 独立执行器接入宿主压缩路径。`compress.externalSummary` 默认关闭,须显式启用;该链与其余 `compress` 字段一样存在全部三个层级(provider/model 层整链替换,无子字段合并),且沿请求 Config 轨道(`ctx.config` / `effectiveConfig`,#833)流动,不再有旁路配置文件。当前是评审分支中的实现,不是已发布版本,也未部署生产;配置面仍待仓库 owner 明确确认。

链以**引用**形式表达(`"glm/glm-4.9-flash"`),指向 `providers` 表中的具名拨号配方(带 `baseUrl`/`api`/凭据/`models` 的非 URL 条目,详见 `CONFIGURATION.zh-CN.md`)。解析分两层:`src/external-summary-settings.ts` 在配置加载时做语法层链解析(`parseExternalSummaryChain`),在请求应用时做引用展开(`expandExternalSummaryChain` / `src/compress-settings.ts` 的 tolerant 变体),产出执行器轨道消费的展开型 `ExternalSummarySettings`。启用链中的不可解析引用会记录一次警告并禁用整条链 —— 绝不回退主模型。Web API 保存时对不可解析的启用链返回 HTTP 400;配方从即将保存的 `providers` 段收集(`src/config.ts` 的 `collectNamedProviders`)。
链以**引用**形式表达(`"glm/glm-4.9-flash"`),指向 `providers` 表中的具名拨号配方(带 `baseUrl`/`api`/凭据/`models` 的非 URL 条目,详见 `CONFIGURATION.zh-CN.md`)。解析分两层:`src/external-summary-settings.ts` 在配置加载时做语法层链解析(`parseExternalSummaryChain`),在请求应用时做引用展开(`expandExternalSummaryChain` / `src/compress-settings.ts` 的 tolerant 变体),产出执行器轨道消费的展开型 `ExternalSummarySettings`。启用链中的不可解析引用会记录一次警告并禁用整条链 —— 绝不回退主模型。Web API 保存时对不可解析的启用链返回 HTTP 400;配方从即将保存的 `providers` 段收集(`src/config.ts` 的 `collectNamedProviders`)。#2336 新增内存中的 **agent 注册表兜底层**(`src/agent-providers.ts`):ACP 原生 agent POST 自己已配置的 providers(`POST /__bili/agent-providers`,`parseAgentProviderReport` 消毒+校验),这些 recipes 在请求应用时合并在文件 recipes 之下(`{ ...agentProviderRecipes(), ...opts.namedProviders }`)——同名时文件胜出。agent recipes 携带已解析的 inline key(轨道 target 上的 `apiKey`,与 `credentialRef` 互斥;文件世界仍拒绝明文 key——`parseExternalSummarySettings(value, { inlineKeys: true })` 是轨道专用开关)。

执行器接收不可变的任务文本、指令、可选只读参考,有序的异步候选调用及明确的内部预算。协议、鉴权和范围选择由调用方负责;没有调用方就不会请求供应商或折叠历史。

Expand Down
Loading
Loading