billion-context 0.1.165 → 0.1.166
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +112 -983
- package/README.zh-CN.md +67 -304
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.zh-CN.md
CHANGED
|
@@ -42,6 +42,8 @@
|
|
|
42
42
|
|
|
43
43
|
---
|
|
44
44
|
|
|
45
|
+
> **缓存健康速览：**健康会话的前缀缓存命中率在 **95–97%** 左右——压缩本身代价 ≤2%。持续低于这个数，用 `/acp` 或 `/acp-cache` 查归因（见[常见问题](#常见问题)）；常见原因依次：上游缓存 TTL 到期 · 切换模型 · bili 的 bug（欢迎提报）· 其他/未知。
|
|
46
|
+
|
|
45
47
|
## 社区
|
|
46
48
|
|
|
47
49
|
QQ群:
|
|
@@ -86,19 +88,16 @@ QQ群:
|
|
|
86
88
|
真实模型 API (Anthropic / OpenAI / 兼容厂商)
|
|
87
89
|
```
|
|
88
90
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
可选的第五个工具 `absorb`(`compress.absorb.enabled: true` —— 见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md))对**各个工具结果即时压缩**:大结果(构建、日志、grep)被附带强制吸收指令,模型将各自蒸馏为紧凑摘要,原配对从下一轮起从线上隐藏 —— 使折叠轮之间的中间会话压力更低(#605)。
|
|
92
|
-
|
|
93
|
-
第六个工具 `acp_rule`(默认关闭;设 `compress.rules: true` 显式开启 —— 见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)。开启后模型对会话规则有全权、可未经提示自主调用,#1399)记录**持久化的原则级提醒**:模型记录的简短规则(用户强调的教训、要求记住的行为、撞到的大坑)受硬性保护不被压缩——调用及结果在每次折叠中都保留在上下文中——省略参数则列出已记录规则;传入 `delete`(规则 id,如 `"rule3"`)删除单条规则,传入 `clear: true` 清空全部规则([ranxianglei/billion-context-pi#433](https://github.com/ranxianglei/billion-context-pi/issues/433))。
|
|
91
|
+
### 上下文管理工具
|
|
94
92
|
|
|
95
|
-
|
|
93
|
+
代理向对话注入四个上下文管理工具;模型在上下文增长时自行调用,代理在服务端执行 `compress`,折叠后的范围在历史中保持摘要形态、直到被恢复:
|
|
96
94
|
|
|
97
|
-
|
|
95
|
+
- **`compress`** —— 把一段消息范围折叠成详细摘要。
|
|
96
|
+
- **`decompress`** —— 需要精确细节时恢复某个已压缩范围。
|
|
97
|
+
- **`search_context`** —— 在压缩摘要与可见消息中做关键词检索。
|
|
98
|
+
- **`acp_status`** —— 上下文用量概览 + 哪些区间仍可压缩。
|
|
98
99
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
**如何确认压缩真的生效了。** 代理执行 `compress` 后会以普通 assistant 文本发出确认标记(`📦 [ACP] Compressed …`)—— 但曾观察到模型在持续上下文压力下*自行书写该标记格式*而从未调用工具(#717):约 2 小时内 17 次假"压缩",真实用量一路爬到 89%。因此对话中看到的标记行本身不是持久化完成的证据 —— 请先用 `acp_status` 复核(块数 +1、可压缩区间起点前移)再采信。作为兜底,代理会剥离模型自发的标记形文本并记录 `[marker-echo]` 警告;注入的 nudge 与系统提示词也明确声明标记只由代理发出。
|
|
100
|
+
模型会自主使用以上工具自主管控上下文，无需人工干预。
|
|
102
101
|
|
|
103
102
|
## 该选哪个?
|
|
104
103
|
|
|
@@ -107,25 +106,25 @@ QQ群:
|
|
|
107
106
|
| 客户端 | 用这个 |
|
|
108
107
|
|---|---|
|
|
109
108
|
| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi)(进程内扩展) |
|
|
110
|
-
| **opencode**(1.x / 2.x) | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili opencode`(启动器)或 `bili plugin install opencode`(
|
|
109
|
+
| **opencode**(1.x / 2.x) | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili opencode`(启动器)或 `bili plugin install opencode`(原生);独立 [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) 在 1.x 上仍可用 —— 完整指南:[OpenCode](CLIENTS.zh-CN.md#opencode) |
|
|
111
110
|
| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context)，`bili omp`（内置插件）或 `bili plugin install omp`（自拉起原生插件，免启动器） |
|
|
112
|
-
| **dsh** | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili dsh
|
|
113
|
-
| **kimi** | `bili plugin install kimi
|
|
114
|
-
| **hermes** | `bili plugin install hermes
|
|
115
|
-
| **zcode
|
|
111
|
+
| **dsh** | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili dsh`(启动器,经 `--patch` 注入完整原生插件)或 `bili plugin install dsh` ≡ `dsh plugin --profile <name> add billion-context`(统一泳道)—— 细节见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md) |
|
|
112
|
+
| **kimi** | `bili plugin install kimi`(自拉起原生,需 Kimi Code ≥ 2.0.0)或 `bili kimi`(证书 MITM)或 `/bili/` 前缀 —— 细节见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md) |
|
|
113
|
+
| **hermes** | `bili plugin install hermes`(自拉起原生,Python 插件 #958)或 `bili hermes`(证书 MITM) |
|
|
114
|
+
| **zcode**(Z.ai / bigmodel coding plan) | `bili plugin install zcode`(自拉起原生,#1145)或 GUI「设置 → 网络」证书 MITM 或 `/bili/` 前缀 —— 细节见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md) |
|
|
116
115
|
| **claude** | `bili claude`(启动器)或 `bili plugin install claude`(原生姿态,#964 —— 受管 settings 块 + 会话自管代理;见下方"注意") |
|
|
117
|
-
| **jcode** | [`billion-context`](https://github.com/ranxianglei/billion-context)
|
|
118
|
-
| **gemini
|
|
116
|
+
| **jcode** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili jcode`(cert-MITM)或 `/bili/` 前缀 —— 无原生模式(编译型 Rust 二进制、无插件接缝,[#962](https://github.com/ranxianglei/billion-context/issues/962)) |
|
|
117
|
+
| **gemini**(Gemini CLI) | `bili gemini`(启动器,`GOOGLE_GEMINI_BASE_URL` `/bili/` 改写)或 `/bili/` 前缀 —— 仅启动器(无环内工具注入接缝,#1043) |
|
|
119
118
|
| **iflow**（iFlow CLI） | `bili iflow`（启动器，`IFLOW_BASE_URL` `/bili/` 改写）或 `/bili/` 前缀 |
|
|
120
119
|
| **qwen**（Qwen Code） | `bili qwen`（启动器，cert-MITM）或 `/bili/` 前缀 |
|
|
121
|
-
| **mcode
|
|
122
|
-
| **aider** | [`billion-context`](https://github.com/ranxianglei/billion-context)
|
|
123
|
-
| **copilot
|
|
124
|
-
| **amp
|
|
125
|
-
| **goose
|
|
120
|
+
| **mcode**(MiniMax Code) | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili mcode`(cert-MITM)或 `/bili/` 前缀 —— 无原生模式(纯声明式事件钩子,无模型请求接缝,[#1050](https://github.com/ranxianglei/billion-context/issues/1050)) |
|
|
121
|
+
| **aider** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili aider`(cert-MITM)或 `/bili/` 前缀 —— 无原生模式(仅 shell 命令钩子,无工具注入接缝,[#1048](https://github.com/ranxianglei/billion-context/issues/1048)) |
|
|
122
|
+
| **copilot**(GitHub Copilot CLI) | `bili copilot`(启动器,cert-MITM)—— 闭源 Go 二进制、无插件接缝(#1049) |
|
|
123
|
+
| **amp**(Amp CLI) | `bili amp`(启动器,cert-MITM)—— 闭源 Go 二进制、无插件接缝(#1049) |
|
|
124
|
+
| **goose**(Goose CLI) | `bili goose`(启动器)—— rustls 不信任任何 CA 文件,无法 cert-MITM:openai/anthropic 腿经 `OPENAI_HOST`/`ANTHROPIC_HOST`,自定义 provider 经重新生成的 `GOOSE_PATH_ROOT` overlay(#1049) |
|
|
126
125
|
| **其余所有**（没有上下文 hook） | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili <client>`（启动器，优先）或 `/bili/` 前缀 |
|
|
127
126
|
|
|
128
|
-
**原生模式 vs 独立扩展。** 宿主原生插件(`bili plugin install
|
|
127
|
+
**原生模式 vs 独立扩展。** 宿主原生插件(`bili plugin install …`)与独立进程内扩展(`billion-context-pi`、`opencode-acp`)**互斥** —— 两者同时生效意味着双重压缩。安装器负责切换:替换旧条目(裸名、`npm:` 别名、带版本号、路径形式都认,数组/对象两种形态都处理),原配置快照到 `.bili-bak`;**项目级**安装不会被碰 —— 需手动移除。作为手动安装的运行期安全网,原生入口在加载时同步设置 `BILLION_CONTEXT_NATIVE=<host>`,让独立扩展在动作时自动退出。pi 一侧该标记需要 `billion-context-pi` **0.1.72+**。
|
|
129
128
|
|
|
130
129
|
|
|
131
130
|
## 安装
|
|
@@ -140,9 +139,9 @@ npm install -g billion-context
|
|
|
140
139
|
|
|
141
140
|
3种方式 —— 任选其一:
|
|
142
141
|
|
|
143
|
-
- **原生插件(
|
|
144
|
-
- **启动器(
|
|
145
|
-
- **改url(
|
|
142
|
+
- **原生插件(最原生):** `bili plugin install <client>` —— bili 成为客户端内的插件,照常启动客户端即可.
|
|
143
|
+
- **启动器(免安装):** `bili <client>` 一条命令拉起代理 + 客户端,不碰任何真实配置文件.
|
|
144
|
+
- **改url(最通用):** 在客户端 baseURL 前面加上代理地址 + `/bili/`。
|
|
146
145
|
|
|
147
146
|
三种方式背后的机制细节(插件生命周期、runtime-info 协议、注入优先级)见 [TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。
|
|
148
147
|
|
|
@@ -170,25 +169,17 @@ bili plugin remove <client> # 卸载(dsh 经同一通道移除;配置快照
|
|
|
170
169
|
|
|
171
170
|
pi / omp / kimi / claude 没有客户端侧通道 —— 它们的配置条目由 `bili plugin install <client>` 代写(kimi 的声明式 `kimi.plugin.json` + 注册记录、claude 的受管 settings 块等)。
|
|
172
171
|
|
|
173
|
-
插件加载时**自拉起自己的代理**(已有健康实例且通过附着门禁则直接复用;父进程 pid 看门狗在客户端退出时收掉它),把模型流量改写到 `<proxy>/bili/<上游URL>`,注册 `compress` / `decompress` / `acp_status` 为客户端原生工具(plugin 模式),并把客户端**自己的模型配置**上报给代理让压缩预算用真实窗口而不是注册表猜测。退出开关:`BILI_NATIVE_PI=0`、`BILI_NATIVE_OMP=0`、`BILI_NATIVE_OPENCODE=0`、`BILI_NATIVE_DSH=0`、`BILI_NATIVE_KIMI=0`、`BILI_NATIVE_HERMES=0`、`BILI_NATIVE_ZCODE=0`。完整机制:[TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。
|
|
174
|
-
|
|
175
|
-
**附着门禁(#1335)。** 原生 hook 会附着到端口上任何应答者,因此三类监听者区别对待:自己会话拉起的代理(出生即 armed)✅ 附着;其他会话的 armed 共享代理(watcher 集,#1186)✅ 附着——共享本就是设计;手工 `bili start` 常驻守护进程 ❌ **默认不附着**——它没有生命周期属主(拒绝 watcher 注册、不随会话退出、常是旧版本代码,正是 #1322 的成因)。hook 附着前先探测候选者 `/__bili/health` 里的 `watchdog.armed`:armed → 附着并注册 watcher(现状不变);unarmed、或 pre-#1330 构建根本不报 `watchdog` 字段(不可验证,按 unarmed 处理)→ **不附着**,本会话自拉起一个临时代理(临时端口、出生即 armed、随最后一个会话消亡,#1186 watcher 语义)。顺带修掉版本偏斜:每个会话跑的都是**当前安装的** bili,而不是陈旧守护进程携带的旧代码。代价:无 armed 代理时每会话多一个短命代理进程(会话状态在磁盘上共享,压缩连续性不受影响);多实例告警(#394)相应变多。**逃生舱:** 刻意用常驻守护进程承载原生 hook → 配置文件设 `"native": { "attachExternal": true }` 或 `BILI_NATIVE_ATTACH_EXTERNAL=1`,恢复对任何 code/lane 兼容监听者的附着(守护进程的寿命与版本由你自己负责)。kimi/dsh 的显式用户指定附着(`BILLION_CONTEXT_ATTACH` / 预置 `BILLION_CONTEXT_PROXY`)完全不经过发现路径,构造上豁免。
|
|
176
|
-
|
|
177
|
-
**Runtime-info 协议(#955)。** 原生插件读取客户端自己将要使用的模型配置并推给代理(逐请求头 + 自举上报);代理解析上下文窗口时优先采用这份真相,而不是 models.dev 注册表/内置表。协议细节、解析顺序与现有实现:[TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。
|
|
178
|
-
|
|
179
172
|
注意:
|
|
180
173
|
|
|
181
|
-
- 原生模式与独立进程内扩展(`billion-context-pi`、`opencode-acp`)**互斥** —— 安装器负责换条目并把原配置快照(`.bili-bak`)
|
|
182
|
-
- OpenCode
|
|
183
|
-
- `kimi` 仅在自举时上报 runtime-info(
|
|
184
|
-
- `hermes` 的原生插件是 Python
|
|
185
|
-
- `claude` 有**原生姿态**(#964)
|
|
186
|
-
- `zcode` 有**原生姿态**(#1145)
|
|
187
|
-
- `codex` / `omp` 也有配套安装(MCP shell 与轻量扩展)
|
|
188
|
-
- `jcode`
|
|
189
|
-
- `
|
|
190
|
-
|
|
191
|
-
- `copilot`、`amp`、`goose` 仅启动器模式(#1049):三者均无工具注入接缝,故没有原生模式(amp/goose 理论上可做 codex 式 MCP shell 伴生安装,本版本未提供)。Goose 另外无法 cert-MITM —— 其发布构建走 rustls/webpki、不信任任何 CA 文件 —— 因此改走纯 HTTP base-URL 重定向而非代理环境变量。
|
|
174
|
+
- 原生模式与独立进程内扩展(`billion-context-pi`、`opencode-acp`)**互斥** —— 安装器负责换条目并把原配置快照(`.bili-bak`)。
|
|
175
|
+
- OpenCode 旧会话、V1/V2 插件形态与全部注意事项:[OpenCode](CLIENTS.zh-CN.md#opencode)。
|
|
176
|
+
- `kimi` 仅在自举时上报 runtime-info(静态头无法承载逐请求窗口/模型值),子代理会话按每次调用的 `conversation_id` 绑定。
|
|
177
|
+
- `hermes` 的原生插件是 Python:健康检查通过后用环境变量把 hermes 的 httpx 栈指向代理,并经 `llm_request` 中间件打逐请求头。
|
|
178
|
+
- `claude` 有**原生姿态**(#964):受管 settings 块 + `SessionStart` hook + 稳定端口的 MCP shell;`BILI_NATIVE_CLAUDE=0` 退出(passthrough)。机制:[TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。
|
|
179
|
+
- `zcode` 有**原生姿态**(#1145):受管 `~/.zcode/cli/config.json` 块 + 每会话 provider `baseURL` 改写。完整机制:[CLIENTS.zh-CN.md](CLIENTS.zh-CN.md)。
|
|
180
|
+
- `codex` / `omp` 也有配套安装(MCP shell 与轻量扩展),但需要一个在跑的代理 —— 不属于原生模式。
|
|
181
|
+
- `jcode`、`aider` 无原生模式(无插件/MCP/工具注入接缝:#962、#1048)—— 用 `bili jcode` / `bili aider`。
|
|
182
|
+
- `copilot`、`amp`、`goose` 仅启动器模式(#1049);goose 无法 cert-MITM(rustls 不信任任何 CA 文件),改走纯 HTTP base-URL 重定向。
|
|
192
183
|
|
|
193
184
|
### 方式 2 —— 启动器(`bili pi` / `bili codex` / `bili claude` / `bili omp` / `bili opencode` / `bili hermes` / `bili dsh` / `bili codebuddy` / `bili qoder` / `bili trae` / `bili jcode` / `bili kimi` / `bili gemini` / `bili iflow` / `bili qwen` / `bili mcode` / `bili aider` / `bili copilot` / `bili amp` / `bili goose`)
|
|
194
185
|
|
|
@@ -199,22 +190,22 @@ bili pi # 拉起 pi,走代理 —— file-free(#53
|
|
|
199
190
|
bili codex # 拉起 codex
|
|
200
191
|
bili claude # 拉起 claude
|
|
201
192
|
bili omp # pi 同款,file-free(#535):环境变量 + 扩展 registerProvider + 压缩取消,真实 ~/.omp 不动
|
|
202
|
-
bili opencode # OpenCode(1.x 与 2.x):完整指南见下文 [OpenCode](#opencode) 一节
|
|
193
|
+
bili opencode # OpenCode(1.x 与 2.x):完整指南见下文 [OpenCode](CLIENTS.zh-CN.md#opencode) 一节
|
|
203
194
|
bili hermes # file-free(#535):hermes 代理环境变量(HTTPS_PROXY + SSL_CERT_FILE 组合 CA bundle)—— https 走 CONNECT MITM,http 走绝对形式转发;真实 ~/.hermes 不动
|
|
204
|
-
bili dsh # deepseek-harness:经 --patch 注入完整原生插件(#941) ——
|
|
195
|
+
bili dsh # deepseek-harness:经 --patch 注入完整原生插件(#941) —— 真实 dsh 工具、会话绑定 /acp(plugin 模式);非回环上游走代理 env,回环保留 overlay DSH_HOME 改写(#535);dsh 自动压缩关
|
|
205
196
|
bili codebuddy # Tencent CodeBuddy Code CLI:CODEBUDDY_BASE_URL /bili/ 重写(OpenAI chat completions wire),预算对齐走 CODEBUDDY_AUTO_COMPACT_WINDOW;真实 ~/.codebuddy 不动
|
|
206
197
|
bili qoder # qoder:模型端点硬编码 https(无法 /bili/ 改写)—— 证书 MITM(HTTPS_PROXY + NODE_EXTRA_CA_CERTS),默认模型主机已加白名单(#653)
|
|
207
198
|
bili trae # Trae CLI(字节跳动,闭源 Go 二进制,无 base-URL 覆盖)—— 证书 MITM(HTTPS_PROXY + SSL_CERT_FILE),模型主机取 TRAE_CLI_API_HOST 或默认企业网关(#655)
|
|
208
199
|
bili jcode # jcode(Rust 终端编码 agent)—— 环境变量式证书 MITM 启动:HTTPS_PROXY + SSL_CERT_FILE,模型主机 api.z.ai 默认加白,本地回环 provider 走 NO_PROXY 直连
|
|
209
|
-
bili kimi # Kimi Code CLI(Moonshot)
|
|
200
|
+
bili kimi # Kimi Code CLI(Moonshot):除无条件回环绕过外遵循标准代理环境变量 —— https 证书 MITM、http 绝对形式转发;回环端点编目并附手动 /bili/ 提示(#757)
|
|
210
201
|
bili gemini # Gemini CLI(Google):GOOGLE_GEMINI_BASE_URL /bili/ 改写到 generativelanguage.googleapis.com(Google 原生 wire),真实 ~/.gemini 零改动
|
|
211
202
|
bili iflow # iFlow CLI:IFLOW_BASE_URL /bili/ 改写到 apis.iflow.cn/v1(OpenAI chat-completions wire),真实 ~/.iflow 零改动
|
|
212
203
|
bili qwen # Qwen Code(多协议 gemini-cli fork,无 base-URL 钩子):HTTPS_PROXY + NODE_EXTRA_CA_CERTS 证书 MITM,默认 DashScope/Qwen 模型主机加白,自建中转用 --mitm-domain 追加
|
|
213
|
-
bili mcode # MiniMax Code CLI
|
|
214
|
-
bili aider # Aider(Python pair programmer):HTTPS_PROXY + SSL_CERT_FILE/REQUESTS_CA_BUNDLE 证书 MITM
|
|
204
|
+
bili mcode # MiniMax Code CLI:与 kimi 同构(代理环境变量、无条件回环绕过、证书 MITM/绝对形式);会话经 X-Mavis-Session-Id 绑定(#1050)
|
|
205
|
+
bili aider # Aider(Python pair programmer):HTTPS_PROXY + SSL_CERT_FILE/REQUESTS_CA_BUNDLE 证书 MITM;端点取自 OPENAI_API_BASE / ANTHROPIC_BASE_URL / --openai-api-base / .aider.conf.yml(#1048)
|
|
215
206
|
bili copilot # Copilot CLI(GitHub,闭源 Go 二进制)—— 证书 MITM(HTTPS_PROXY + SSL_CERT_FILE),api.githubcopilot.com + 各套餐子域加白(#1049)
|
|
216
207
|
bili amp # Amp CLI(Sourcegraph,闭源 Go 二进制)—— 证书 MITM(HTTPS_PROXY + SSL_CERT_FILE),ampcode.com 加白(#1049)
|
|
217
|
-
bili goose # Goose(Block,Rust/reqwest):rustls 发布构建不信任任何 CA 文件 ——
|
|
208
|
+
bili goose # Goose(Block,Rust/reqwest):rustls 发布构建不信任任何 CA 文件 —— openai/anthropic 腿经 OPENAI_HOST/ANTHROPIC_HOST,自定义 provider 经重新生成的 GOOSE_PATH_ROOT overlay(/bili/ 改写,真实配置不动)(#1049)
|
|
218
209
|
bili pi --mitm-domain api.foo.com # 向 MITM 白名单追加域名
|
|
219
210
|
```
|
|
220
211
|
|
|
@@ -249,159 +240,26 @@ curl -s http://localhost:8787/__bili/stats
|
|
|
249
240
|
|
|
250
241
|
然后从助手发一条消息,观察日志(`~/.local/state/billion-context/bili.log`,同时也打到 stderr)。每个请求应该看到一行 `processTurn`,等对话变长后会出现 `[acp-usage] round N input=X cached=Y (cache hit Z%)` + `compress` 事件。
|
|
251
242
|
|
|
252
|
-
###
|
|
253
|
-
|
|
254
|
-
两条通道，同一个插件(#941):
|
|
255
|
-
|
|
256
|
-
- **启动器:** `bili dsh` 经 `--patch` overlay(`~/.dsh-bili/.bili-acp.patch.yml`)注入完整原生插件 —— 每个 profile 启动即注册 bili 工具，模型请求盖 `x-bili-plugin` + dsh 会话 id(plugin 模式)，`/acp` 会话绑定。同一份 patch 同时禁用 dsh 原生自动压缩(`compaction-basic` → `auto: false`);手动 `/compact` 仍可用。
|
|
257
|
-
- **Profile 安装(免启动器)——统一泳道(#966):** `bili plugin install dsh` 对每个已存在的 profile 执行 `dsh plugin --profile <name> add billion-context` —— pnpm 把包装进各 profile 自己的 `node_modules`,dsh 自动挂载包内 patch 层(`dsh.bundle.patch.yml`)。装哪个源取决于 bili 自身的安装形态(#925):npm 安装传注册表名,checkout/dev 构建传绝对路径(`link:` 依赖,本地改动实时生效)。旧版受管块(`# bili begin` / `# bili end`,#966 之前的安装所写)在安装与卸载时都会被剥离 —— 用户条目与注释保留,清空的文件还原占位 `[]`。先在每个 profile 里跑过一次 dsh 让目录存在。插件加载时自拉起代理(已有健康实例则附看，不重复拉;父进程 pid 看门狗)，经全局 fetch 补丁把模型流量改写为 `<proxy>/bili/<上游URL>`，原样注册清单工具，并按工具就绪门控 plugin 模式头(第一轮走 wire 模式)。退出开关:`BILI_NATIVE_DSH=0`。卸载:`bili plugin remove dsh` 或 `dsh plugin --profile <name> remove billion-context` —— 两者走同一通道。经注册表安装要求 npm 上已发布含 `dsh.bundle.patch.yml` 的版本。若 add 后 dsh 启动即报 `billion-context/dsh` 的 `ERR_MODULE_NOT_FOUND`,说明 profile 从陈旧的包元数据缓存里解析到了不含 bundle 子路径导出的旧版本(#953)——固定版本重装:`dsh plugin --profile <name> add billion-context@latest`。
|
|
258
|
-
- **自动更新保持各 profile 同步:** 刷新有两个触发器 —— 全局自更新完成后,以及**profile 自己的代理**在周期检查里发现注册表有新版本时(全局 bili 从不运行也一样刷新,#1196 —— 插件市场安装的用户往往根本没有全局安装)。两种触发器都扫描 `~/.dsh/profiles/*/package.json`,把注册表钉住的 `billion-context` 依赖刷新到目标版本(全局触发器刷到新全局版本,自触发刷到注册表最新),统一经 dsh 自己的 `plugin add` 通道,绝不在位覆盖 —— 加载的插件与代理从此不再漂移(#953);钉在本地源的 profile 不动。刷新是尽力而为,失败下个周期重试,绝不会让代理或更新本身失败。
|
|
259
|
-
- **已报告:Profile 安装下部分传输零代理流量(#1158,调查中):** dsh `llm-pi-ai` 层的部分传输服务会话**从未有任何模型请求到达代理**(日志无 `processTurn`,调用 bili 工具返回 404 "no model request has arrived"),而同宿主的其他 provider 正常。根因仍在用运行时证据定性 —— 候选:传输层 fetch 形态(SDK 注入 fetch / 非全局 dispatcher)或宿主侧归属缺口导致流量未被 takeover gate 认领。检测:此类情况会打一次性 `[plugin] NO MODEL REQUESTS seen for conversation …` 告警,dsh 插件还会把归属 gate 放行的每个端点各记一条日志(每进程一次)。期间可靠规避:改用 `bili dsh` 启动 —— 启动器的 settings overlay 会把那些 provider 的 `baseURL` 重写为 `/bili/` URL,无论传输层使用哪种 fetch、归属状态如何,流量都必然过代理。
|
|
260
|
-
|
|
261
|
-
`bili dsh` 启动下插件**附看**(attach)启动器的代理(不二次拉起)。裸上游 URL 与 spawn 模式一样重写为 `<proxy>/bili/<url>`(回环代理目标永不被代理 env 拦截，等于直接绕开 MITM)；已经路由的 `/bili/` 前缀请求原样放行、只盖章。已知局限:手动 `/compact` 没有 dsh 侧事件钩子，其边界交给内核的自然 ingest diff(自动压缩已关，影响罕见)。
|
|
262
|
-
|
|
263
|
-
### Kimi Code(Moonshot)
|
|
264
|
-
|
|
265
|
-
三种对齐模式:`bili kimi`(启动器,证书 MITM —— 方式 2)、`/bili/` URL 前缀,以及原生插件模式(`bili plugin install kimi`,#963)。Kimi Code v2 的插件体系是纯声明式的(`kimi.plugin.json`:MCP server、hooks、skills —— 没有进程内 JS 执行),所以 bili 无法像 pi/opencode/dsh 那样补丁客户端的 fetch 栈。取而代之,插件带两个小型 node 脚本,在客户端外围完成工作:
|
|
266
|
-
|
|
267
|
-
- **安装:** `bili plugin install kimi` 写 `$KIMI_CODE_HOME/plugins/managed/billion-context/kimi.plugin.json`,声明一个 stdio MCP server(`node <root>/dist/kimi/native-mcp.js`)加一个 `SessionStart` hook(`node <root>/dist/kimi/bootstrap-hook.js`,超时 30 s),并在 `$KIMI_CODE_HOME/plugins/installed.json` 注册该插件。安装器要求 `kimi --version` ≥ 2.0.0,低于此版本拒绝安装(启动器模式不受影响)。卸载:`bili plugin remove kimi`(managed 目录 + 注册表记录 + 配置还原)。
|
|
268
|
-
- **每会话自举:** kimi 为每个会话把 MCP server 作为直接子进程拉起;启动时它先附上健康的现有代理(`BILLION_CONTEXT_PROXY`),否则在临时端口自拉起一个,然后用幂等的逐行受管块改写 `~/.kimi-code/config.toml` 的路由:自有 provider `[providers.bili]`(`base_url = http://127.0.0.1:<port>/bili/<上游>`,原样克隆当前 provider 的 `oauth` / `api_key` 引用)、`[models.bili-kimi]` 别名、顶层 `default_model` 重定向(原值记录在块内)。原文件一次性快照到 `config.toml.bili-bak`;每次写入都在 mkdir 锁文件下进行,块外的用户内容绝不被触碰。Kimi 的配置热重载会把变更应用到存活会话。`SessionStart` hook 机会性地跑同样的自举(仅 attach —— 永不拉起代理);它的非阻塞竞态在设计上被容忍:第一轮可能走直连/wire 模式,不变量是绝不把 `base_url` 指向死端口。
|
|
269
|
-
- **Plugin 模式盖章:** 只有当 ACP 工具清单已在存活代理上验证通过后,块里才会写入 `custom_headers = { x-bili-plugin = "kimi" }` —— 此前流量走 wire 模式。由于 `custom_headers` 按 provider 静态生效,无法承载逐请求的窗口/模型头(会在模型切换后过期),所以 runtime-info 上报只在自举时发生(客户端配置里有模型 + 上下文窗口 + 最大输出就一并上报)。
|
|
270
|
-
- **看门狗与生命周期:** MCP 子进程每 30 s 探测一次代理。attach 模式下永远等待(绝不碰用户自己的代理);spawn 模式下代理死亡则重新拉起并把路由改写到新 origin。恢复失败时移除受管块,让流量退回直连上游而不是打到死端口。会话结束时 kimi 杀掉 MCP 子进程,父进程 pid 看门狗随之收掉拉起的代理。多个并发 TUI 共享第一个拉起的代理;它消失后其余会话自动重新拉起并改路。
|
|
271
|
-
- **已知局限:** 子代理会话各自得到独立的派生代理会话(kimi 不暴露稳定的会话 id;工具调用经每次调用的 `conversation_id` 参数绑定);kimi 的原生自动压缩**没有**被推后 —— ACP 压缩只是先触发,与启动器模式一致。退出开关:`BILI_NATIVE_KIMI=0`。
|
|
272
|
-
|
|
273
|
-
### Gemini 系(Gemini CLI / iFlow CLI / Qwen Code)
|
|
274
|
-
|
|
275
|
-
面向 gemini-cli 架构家族的三个启动器(#1043 第一梯队)。三者中两个有 base-URL 环境变量钩子,一个没有:
|
|
276
|
-
|
|
277
|
-
- **`bili gemini`** —— Gemini CLI(`@google/gemini-cli`)。设置
|
|
278
|
-
`GOOGLE_GEMINI_BASE_URL=<proxy>/bili/<upstream>`(默认上游
|
|
279
|
-
`https://generativelanguage.googleapis.com`;如果你自己导出了
|
|
280
|
-
`GOOGLE_GEMINI_BASE_URL`,该值会被中继经过代理)。客户端切换到
|
|
281
|
-
`gateway` 认证模式,把 Google 原生 wire 请求直接发给回环代理 —— 无 MITM、
|
|
282
|
-
无需装 CA,`~/.gemini` 零改动。代理本身原生支持这条 wire(模型名在 URL
|
|
283
|
-
path 里)。局限:headless `-p` 运行需要已保存的认证选择(例如 settings 里
|
|
284
|
-
`security.auth.selectedType = "gemini-api-key"` + `GEMINI_API_KEY`),因为
|
|
285
|
-
gemini-cli 在非交互模式下拒绝纯环境变量推导的 gateway 认证;使用 OAuth
|
|
286
|
-
个人登录(CodeAssist)的用户完全不走这条路 —— 该路径无视 base-URL 钩子。
|
|
287
|
-
- **`bili iflow`** —— iFlow CLI(`@iflow-ai/iflow-cli`)。同样的模式,走
|
|
288
|
-
`IFLOW_BASE_URL`(默认 `https://apis.iflow.cn/v1`,你设置过则中继);
|
|
289
|
-
OpenAI chat-completions wire。
|
|
290
|
-
- **`bili qwen`** —— Qwen Code(`QwenLM/qwen-code`)。这个 fork 移除了
|
|
291
|
-
base-URL 钩子(`DASHSCOPE_PROXY_BASE_URL` 只是头部调优旋钮,不是路由),
|
|
292
|
-
但它遵循标准代理环境变量,所以启动器走证书 MITM:`HTTPS_PROXY=<proxy>` +
|
|
293
|
-
`NODE_EXTRA_CA_CERTS=<bili CA>`,并把默认模型主机(DashScope / Qwen 网关 /
|
|
294
|
-
常见第三方端点)静态加白。自建中转主机用 `--mitm-domain <host>` 追加。
|
|
295
|
-
尽力而为的路由 —— 日志里出现 `BLIND TUNNEL WARNING` 说明有主机没进白名单。
|
|
296
|
-
|
|
297
|
-
三者都没有 native 模式:均无环内工具注入接缝(gemini-cli 扩展只到自定义命令,
|
|
298
|
-
fork 继承同一面)。按设计保持 launcher-only。
|
|
299
|
-
### Hermes（Nous Research）
|
|
300
|
-
|
|
301
|
-
三种对齐模式:`bili hermes`(启动器,证书 MITM —— 方式 2)、`/bili/` URL 前缀、原生插件模式(`bili plugin install hermes`,#958)。hermes CLI agent 的插件 API 只有 Python(`desktop/plugin.js` SDK 属于另一个 Desktop app),所以原生插件是随 npm 包分发的一个纯标准库 Python 模块:
|
|
302
|
-
|
|
303
|
-
- **安装:** `bili plugin install hermes` 把 `plugin.yaml` + `__init__.py` 拷进 `~/.hermes/plugins/billion-context/`,写一个机器自管的 `bili.json` sidecar(指向全局 bili 安装的 `dist/index.js` + node 路径),并经 hermes 自己的通道启用插件(`hermes plugins enable billion-context` —— CLI 不在 PATH 上时改为打印同一条命令)。新开一个 hermes 会话生效。卸载:`bili plugin remove hermes`;全局更新后刷新:`bili plugin update hermes`。
|
|
304
|
-
- **生命周期:** 加载时插件先附着到健康的运行中代理,否则在临时端口自拉起(父进程 pid 看门狗在 hermes 退出时收掉它;并发启动走与启动器相同的 starting-marker 仲裁协议)。只有代理确认健康后,才用 `HTTPS_PROXY` / `https_proxy` + `SSL_CERT_FILE`(bili 组合 CA bundle —— 当前 hermes 经此解析环境信任;`HERMES_CA_BUNDLE` 保留给旧版本)把 hermes 的 httpx 栈指向它 —— **从不改动** `~/.hermes/config.yaml`。provider 的 https 域名从 hermes 配置读出并加入 MITM 白名单;其余域名与启动器模式一样盲隧道。拉不出健康代理时插件静默退场,流量直连(不压缩、无死端口)。
|
|
305
|
-
- **Plugin 模式盖章:** `llm_request` 中间件打 `x-bili-plugin: hermes` + 会话 id(= hermes session id,gateway 多会话安全)+ 模型,已知后再加 `x-bili-plugin-max-output` —— 且只在 ACP 工具已对着存活代理清单注册完之后;第一轮走 wire 模式。`pre_api_request` hook 捕获生效的 `max_tokens`,把 runtime-info(模型 + 最大输出)推给代理。`compress` / `decompress` / `acp_status` 注册为真正的 hermes 工具,由代理既有的插件端点提供。
|
|
306
|
-
- **已知局限:** 走 hermes Codex-wire 传输发出的请求可能丢掉逐请求头面,这类配置在该传输暴露头之前停留在 wire 模式。`BILLION_CONTEXT_PROXY` 已设置(启动器管着代理)或定义了 `BILI_PROVIDER_REWRITES` 时插件整体退场。退出开关:`BILI_NATIVE_HERMES=0`。
|
|
307
|
-
|
|
308
|
-
### ZCode（Z.ai / bigmodel coding plan）
|
|
309
|
-
|
|
310
|
-
三种对齐模式:`/bili/` URL 前缀、GUI「设置 → 网络」证书 MITM(HTTP 代理 + 根 CA 路径)、原生插件模式(`bili plugin install zcode`,#1145)。ZCode 的扩展面是 Claude-Code 形状但纯声明式:`~/.zcode/cli/config.json` 里的用户级 hooks 与 stdio MCP server,没有进程内 JS 接缝。所以原生通道随包带两个小 node 脚本,在客户端外围干活:
|
|
311
|
-
|
|
312
|
-
- **安装:** `bili plugin install zcode` 写 `~/.zcode/cli/config.json`:置 `hooks.enabled = true`、追加一条 `SessionStart` process hook(`node <root>/dist/zcode/bootstrap-hook.js`)、注册 stdio MCP server `mcp.servers.bili`(`node <root>/dist/zcode/mcp-entry.js`)。已存在的用户自有 `mcp.servers.bili` 条目**绝不覆盖** —— 安装器会响亮地拒绝。安装时不冻结任何 URL;路由按会话发生。卸载:`bili plugin remove zcode`(只剥离 bili 自己的条目、由 bili 启用的 `hooks.enabled` 予以还原、provider store 从快照恢复)。
|
|
313
|
-
- **每会话自举:** 每个 ZCode 会话把 MCP 子进程作为直接子进程拉起;启动时附着到健康代理(`BILLION_CONTEXT_PROXY`)或在临时端口自拉起,然后在 mkdir 锁文件下对生效的 provider store 做幂等 JSON 手术:bigmodel coding-plan provider 条目的 `baseURL` 变为 `http://127.0.0.1:<port>/bili/<上游>`(内置默认上游是 `https://open.bigmodel.cn/api/anthropic`;你自己设的自定义 baseURL 原样保留在包装之内)。两代 store 都处理:legacy `~/.zcode/v2/config.json`(`provider.<id>.options.baseURL`)与 v3.14+ personal store `~/.zcode/v2/provider_config.json`(`config.providerConfigRules.providerRules[].config.api.baseUrl`)—— 两者并存时以新 store 为准。原始文件按每次用户编辑快照到 `<file>.bili-bak`(快照永远反映你最后一次真实状态,绝不记录 bili 自己的写入);其余所有键逐字节保留。旧世代客户端在启动时加载 provider 配置 —— 安装后重启一次 ZCode;新版构建可在会话中途感知路由变化(约 1 s 轮询)。`SessionStart` hook 机会性地跑同一套自举(仅附着 —— 绝不 spawn);它的非阻塞竞态被设计为可容忍:第一轮可以走 wire 模式,不变量是 `baseURL` 永不指向死端口。
|
|
314
|
-
- **Plugin 模式盖章:** MCP 子进程对着存活代理清单核验 ACP 工具列表之后,才给路由条目加 `headers["x-bili-plugin"] = "zcode"` —— 此前流量走 wire 模式。工具调用经每次调用的 `conversation_id` 参数绑定(#760)。
|
|
315
|
-
- **看门狗与生命周期:** MCP 子进程每 30 s 探测一次代理。attach 模式下永远等待(绝不碰用户自己的代理);spawn 模式下代理死亡则重新拉起并把路由改写到新 origin。恢复失败时移除受管改写,让流量退回直连上游而不是打到死端口。会话结束时 ZCode 杀掉 MCP 子进程,父进程 pid 看门狗随之收掉拉起的代理。多个并发会话共享第一个拉起的代理;它消失后其余会话自动重新拉起并改路。
|
|
316
|
-
- **已知局限:** ZCode 的反欺诈指纹(#661)作用于 `zcode.z.ai` 登录流量的 MITM 重建 body —— 原生模式不碰那个面(模型流量走 provider store,不走 GUI 代理);若你同时使用 GUI 代理/MITM 配置,请保留 `"mitm://zcode.z.ai": { "passthrough": true }` 路由。`BILLION_CONTEXT_PROXY` 已设置(attach 模式管着代理)或定义了 `BILI_PROVIDER_REWRITES` 时插件整体退场。退出开关:`BILI_NATIVE_ZCODE=0`。
|
|
317
|
-
|
|
318
|
-
### 客户端用 `http.proxy`(CONNECT)接入但从不压缩
|
|
319
|
-
|
|
320
|
-
部分客户端(VS Code 系 IDE:CodeBuddy、Cursor、Windsurf……)只提供一个 HTTP **代理**设置(`http.proxy`、`codingcopilot.httpProxyURL` 等),没有可改写的模型 base-URL。这类客户端不走普通的 `/bili/…` 请求,而是把 `CONNECT <模型域名>:443` 发给代理。只有当模型域名在 bili 的 **MITM 白名单**里时这条路径才会被解密;否则 bili 只做盲隧道(不透明转发),永远看不到——也就无法压缩——模型请求(#897)。
|
|
321
|
-
|
|
322
|
-
该失效模式现在不再静默:
|
|
323
|
-
|
|
324
|
-
- 日志里对每个目标域名打一次 `BLIND TUNNEL WARNING`,附修复步骤;
|
|
325
|
-
- `curl -s http://localhost:8787/__bili/health` 与 `/__bili/stats` 输出 `blindTunnels`(计数 + 精确目标域名,仅 loopback);
|
|
326
|
-
- 存在此类隧道时,`acp_status` 输出会多一节 `UNDECRYPTED TRAFFIC (instance-level)`。
|
|
327
|
-
|
|
328
|
-
要真正压缩这类客户端:把它的模型域名加进 `billion-context.json` 的 `"mitm".domains`(如 `"mitm": { "domains": ["copilot.tencent.com"] }`)或环境变量 `BILI_MITM_DOMAINS`,重启 bili,并让客户端信任 bili 的根 CA(Node 系客户端用 `NODE_EXTRA_CA_CERTS=~/.local/share/billion-context/ca/root-ca.pem`,有 CA 路径设置的用其设置)。`/bili/` 前缀方案在这里不适用——没有 URL 可改。详见 [CONFIGURATION.zh-CN.md → MITM](CONFIGURATION.zh-CN.md#mitm-透明代理登录客户端)。
|
|
329
|
-
|
|
330
|
-
### 未识别的端点直连、什么都不压缩(#1290)
|
|
331
|
-
|
|
332
|
-
bili 只压缩路径匹配已知 wire 协议(`/chat/completions`、`/llm_raw_chat`、`/v1/messages`、`/responses`……)的请求。发往其它路径的请求——例如第三方插件的**自定义 wire**(Command Code 的 Go 套餐发 `POST /alpha/generate`)——会逐字节中继,**永不压缩**。目前没有任何配置口可以声明一种任意新 wire;那是一项独立功能,不是一个能打开的开关。
|
|
333
|
-
|
|
334
|
-
这个结果现在不再静默(#1290):
|
|
335
|
-
|
|
336
|
-
- 客户端侧 fetch 钩子对每个不同的未路由端点每进程记一次日志(`…is not a recognized model endpoint, so bili did not route it through the proxy…`);
|
|
337
|
-
- `curl -s http://localhost:8787/__bili/stats` 输出 `unrecognizedPaths`(按路径计数,仅 loopback);
|
|
338
|
-
- 存在此类请求时,`acp_status` 输出会多一节 `UNRECOGNIZED PATHS (instance-level)`。
|
|
339
|
-
|
|
340
|
-
如果你期望这类端点被压缩,改用 provider 的标准协议端点(Command Code 的 Provider 套餐发 `/provider/v1/chat/completions`,bili 能正常压缩);真正的自定义 wire 需要单独的支持。
|
|
341
|
-
|
|
342
|
-
## OpenCode
|
|
243
|
+
### 客户端深入
|
|
343
244
|
|
|
344
|
-
|
|
245
|
+
一行带不过来的细节 —— 各模式(启动器 / `/bili/` URL 前缀 / 原生插件)如何把流量接进代理、往哪儿写了什么、已知局限有哪些 —— 都在 **[CLIENTS.zh-CN.md](CLIENTS.zh-CN.md)**:dsh · Kimi Code · Hermes · ZCode · Gemini 系(Gemini CLI / iFlow CLI / Qwen Code)· CONNECT 盲隧道接入但从不压缩的客户端(#897)· 未识别端点直连(#1290)· OpenCode(启动器 / 原生 / 纯代理、`/acp` 状态与规则、旧 opencode-acp 会话 #920)。
|
|
345
246
|
|
|
346
|
-
|
|
347
|
-
|---|---|---|
|
|
348
|
-
| 启动器(最省事) | `bili opencode` | 一条命令拉起代理 + 客户端;不碰真实配置 |
|
|
349
|
-
| 原生(免启动器) | `bili plugin install opencode` | 自拉起插件写进真实配置;照常启动 `opencode` |
|
|
350
|
-
| 纯代理(兜底) | baseURL 加 `/bili/` 前缀 | 无插件 —— wire 级工具注入 |
|
|
351
|
-
|
|
352
|
-
### 启动器 —— `bili opencode`
|
|
353
|
-
|
|
354
|
-
HTTPS 走证书 MITM,HTTP 走临时 `opencode.json` 副本(`/bili/` 改写;JSONC 注释照单接受,合并方式与 opencode 自身一致;相对本地插件路径在副本里重新锚定为绝对路径 —— opencode 按声明所在配置文件目录解析,#826)。宿主代次用 `--version` 探测(探测失败默认按 1.x):**2.x** 宿主注入内置 V2 插件(`dist/agent/opencode.js`),以临时包装目录形式给出(目录入口 `index.js` 再 re-export 插件文件 —— 2.x 拒绝配置 `plugin` 数组里的裸文件路径);**1.x** 宿主直接给裸文件路径。
|
|
355
|
-
|
|
356
|
-
插件在两代宿主上做的事相同:在宿主内原生注册 bili 工具 —— compress / decompress / search_context / acp_status(另加 absorb)—— 并在每个 provider 请求上盖章代理头,含从宿主自身模型目录(`ctx.catalog.model.list()`,每 60s 刷新)读取的 context-window / max-output,并以 runtime-info 上报给代理(#955)—— 压缩走插件模式,**不做** wire 级工具注入;原生 auto-compaction 自动关闭(`compaction.auto: false`)。所有注册都是防御式的(可选链):任一 2.x build 上接缝缺失或未触发时,插件保持惰性,会话透明回退纯代理模式而不是报错 —— 在相邻的 `dev` build 上观察到过 API 面互不相同(#754 评审探针)。
|
|
357
|
-
|
|
358
|
-
1.x 细节(1.14.46 + 1.18.31 验证):V1 `.server()` 钩子在进程内把每个 provider 的 `options.baseURL` 改写为 `<proxy>/bili/…` 并设 `compaction.auto: false`;`chat.headers` 每次请求盖章插件头;`tool` 用真实 zod 形状注册 bili 工具(zod 是运行时依赖 —— 解析不到时降级为只改写)。没有显式 `baseURL` 的 provider(SDK 默认值,如裸 `@ai-sdk/openai` → api.openai.com)由全局 `fetch` 补丁兜住(日志:`v1: fetch patch installed`)—— 幂等,`/bili/` 包装过的 URL 原样直通;含 OpenAI Responses 端点端到端验证。
|
|
247
|
+
## 常见问题
|
|
359
248
|
|
|
360
|
-
|
|
249
|
+
**怎么查缓存命中率？** 不用翻日志——`/acp-cache` 直接在客户端里打一份**文字总结报告**，顶部带一个可点击的 **Web UI 链接**，点进去是网页版会话页（**折线图 + 逐断点归因**）：
|
|
361
250
|
|
|
362
|
-
|
|
251
|
+
|
|
252
|
+
报告四块，一眼定位：**GRAND LEDGER**（总账：总输入/总命中/hit%，直接给出 `HEALTHY` 或异常判定；miss 拆解为 new content 新增内容 / compress re-pay 压缩重付 / upstream-ttl-or-client-rewrite 上游 TTL 或客户端重写）· **FOLD ECONOMICS**（每次折叠的经济账：净省多少、是否回本）· **LINE ITEMS**（只列异常行：hit<85% 或 miss≥5000）。经验值：**压缩本身只吃掉 ≤2%**，健康会话稳在 **95–97%**；低于这个值时，归因按概率排序：①上游缓存 TTL 到期（报告里表现为 stable-prefix miss，top spikes 会点出闲置时长）②切换了模型 ③bili 的 bug（带报告页提 issue）④其他/未知。`/acp-cache [full]` 列每一折每一行；HTTP 同款：`GET /__bili/cache-report`；每个请求的 `[acp-usage]` 行仍会落日志，供深挖。
|
|
363
253
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
### 纯代理(无插件)
|
|
367
|
-
|
|
368
|
-
与其它客户端一样,把 provider baseURL 指向代理:
|
|
369
|
-
|
|
370
|
-
```json
|
|
371
|
-
{
|
|
372
|
-
"provider": {
|
|
373
|
-
"myprovider": {
|
|
374
|
-
"npm": "@ai-sdk/openai-compatible",
|
|
375
|
-
"options": {
|
|
376
|
-
"baseURL": "http://localhost:8787/bili/http://upstream.example/v1",
|
|
377
|
-
"apiKey": "sk-any"
|
|
378
|
-
}
|
|
379
|
-
}
|
|
380
|
-
}
|
|
381
|
-
}
|
|
382
|
-
```
|
|
254
|
+
**`/acp` 显示什么?** 带原生插件的客户端(opencode、dsh)里,`/acp` 直接从代理取当前会话的 ACP 状态面板(会话、块、可压缩区间、用量);首个模型请求到来前显示空闲提示。`/acp-cache [full]` 打印上面的缓存报告。
|
|
383
255
|
|
|
384
|
-
|
|
256
|
+
**能用网页查会话和配置吗?** 能 —— 打开 [http://localhost:8787](http://localhost:8787):总览仪表盘、会话列表(含逐会话详情)、实时日志、配置编辑器、上游连通性测试。全部功能同样以纯 JSON 提供(`/__bili/stats`、`/__bili/sessions`、`/__bili/config`、…),方便脚本化。
|
|
385
257
|
|
|
386
|
-
|
|
258
|
+
**压缩什么时候发生?** 由模型驱动:注入的上下文工具由模型在上下文增长时自行调用,温和的增长 nudge(按设计固定约 50K token 步长,可用 `compress.nudgeGrowthTokens` 调整)沿途提醒它,仅输入就超窗时预检作为硬兜底触发(#470)。用 `/acp` 或网页界面实时观察。
|
|
387
259
|
|
|
388
|
-
|
|
260
|
+
**bili 是透明的吗?怎么关掉?** 未识别端点原样转发([CLIENTS.zh-CN.md](CLIENTS.zh-CN.md)),且每种模式都能干净退出:原生安装用 `bili plugin remove <client>`,另两种模式停掉启动器命令 / 环境变量 / `/bili/` 前缀即可 —— 流量立刻恢复直连。
|
|
389
261
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
### 旧 opencode-acp 会话(#920)
|
|
393
|
-
|
|
394
|
-
在 1.x 宿主上,迁移前的 [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) 旧会话在两条泳道下都继续可用:启动器从临时配置副本中移除 `opencode-acp` 条目(宿主永远不会以激活状态加载它),各泳道把已安装的包作为库吸收(直接从 `node_modules` 导入 —— `.opencode/node_modules`、项目 `node_modules`、全局 npm root、opencode 配置级 modules,先到先得)。会话属于 legacy ⟺ opencode-acp 的持久化状态文件存在(`<XDG_DATA_HOME>/opencode/storage/plugin/acp/<sessionID>.json`,或 `acp.jsonc` 中 `storagePath` 指定的目录):
|
|
395
|
-
|
|
396
|
-
- **旧会话** —— 压缩由被吸收的 opencode-acp 执行(它自己的引用号与块存储照常工作:`compress` / `decompress` / `search_context` / `acp_status` / `acp_context_recap` 全部在它里面执行)。其模型请求带 `x-bili-plugin-bypass: 1`,代理原样转发 —— 不注入 wire 工具、不注 nudge、不绑定会话。
|
|
397
|
-
- **新会话** —— bili 接管:工具调用转发到代理的 plugin 端点(plugin 模式)。执行器按会话分泳道:新会话的 `compress` 发到代理,旧会话的发给 opencode-acp。`acp_context_recap` 没有代理端对应 —— 新会话调用会收到代理的 unknown-tool 消息。
|
|
398
|
-
|
|
399
|
-
`/acp` 与 `/dcp` 同样路由。新会话被 opencode-acp 注册表收编的可能被其 transform 门控(system / messages / text.complete 都过 legacy 谓词)阻断。退化路径:包缺失、导入失败或不是 v1 时,bili 单独运行,旧会话退化为只读存档(旧标签照常渲染、`decompress` 返回 `[Block … not found]`、新引用号从 m00001 重新开始)。
|
|
400
|
-
|
|
401
|
-
### 注意事项
|
|
402
|
-
|
|
403
|
-
- 2.x 系列以 npm 包 `@opencode/cli` 发布,且插件 API 面在不同 build 间仍在变动(相邻 `dev` 通道构建暴露不同 `ctx` 形状)—— 上文钩子/工具细节是针对具体版本的观察,不是稳定契约。
|
|
404
|
-
- 设计说明:V2 插件是薄协议客户端(不含 acp-kernel)—— 代理始终是唯一的压缩权威,消除 agent 与代理间的内核版本漂移;它不依赖插件 API 无法改上下文这一事实(该能力随 2.x build 变化)。
|
|
262
|
+
**日志和会话数据存在哪?** 日志:`~/.local/state/billion-context/bili.log`(同时镜像到 stderr);会话状态:`~/.local/share/billion-context/`(XDG 可覆盖;Windows 杀软排除 #362、可选清理 #1082)—— 完整路径见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)。
|
|
405
263
|
|
|
406
264
|
## 运行代理
|
|
407
265
|
|
|
@@ -421,114 +279,38 @@ bili --no-auto-update # 本次启动禁用自动更新
|
|
|
421
279
|
|
|
422
280
|
### 远程 agent（`--host`）
|
|
423
281
|
|
|
424
|
-
默认绑定 `127.0.0.1
|
|
425
|
-
|
|
426
|
-
```bash
|
|
427
|
-
bili --host 0.0.0.0 # 所有网卡(或直接用局域网 IP)
|
|
428
|
-
```
|
|
282
|
+
默认绑定 `127.0.0.1`,只接受本机连接。要给其他机器上的 agent 用:`bili --host 0.0.0.0`(或局域网 IP);远程 agent 把模型 `baseURL` 指向 `http://<本机>:<端口>/bili/…`。
|
|
429
283
|
|
|
430
|
-
-
|
|
431
|
-
-
|
|
432
|
-
|
|
433
|
-
- **没有任何鉴权**: 只应在可信局域网或防火墙内使用。`/__bili/` 管理
|
|
434
|
-
端点仍仅限本机访问。
|
|
435
|
-
- 启动时的 `[security]` 警告会提醒上述事项。
|
|
284
|
+
- MITM 模式的 `CONNECT` 也会接受远程客户端 —— 但仅限**白名单内的模型域名**;到任意主机的盲隧道仍仅限本机,代理不会沦为开放中继。
|
|
285
|
+
- `/bili/<绝对URL>` 目的地准入(#409):代理自身与 link-local/metadata 地址一律拒绝;loopback/私网目的地对本地客户端放行(自托管上游)、对远程客户端拒绝,除非列入 `BILI_TUNNEL_ALLOWED_HOSTS`(`host` 或 `host:port`,逗号分隔)。一个例外(#1073):**本地**客户端经**loopback IP 字面量**目的地转发管理路径(`/__bili/*`、`/__acp/*`)时不带标记放行;远程 peer 与主机名目的地无条件保留内部隧道标记,管理路径即使经 NAT hairpin 也无法穿过隧道。指向本实例自身管理端点的绝对形式请求会在本地直接应答、而不是经隧道转发(正向代理式健康探测能拿到真实响应)。
|
|
286
|
+
- **没有任何鉴权**:只应在可信局域网或防火墙内使用。`/__bili/` 管理端点仍仅限本机访问。启动时的 `[security]` 警告会提醒上述事项。
|
|
436
287
|
|
|
437
288
|
|
|
438
289
|
### 调试
|
|
439
290
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
1. **命令行参数**(最快):`bili --debug`
|
|
443
|
-
2. **环境变量**:`ACP_DEBUG=1 bili`
|
|
444
|
-
3. **配置文件**:在 `billion-context.json` 里设 `"debug": true`
|
|
445
|
-
|
|
446
|
-
详细模式会打印每次 `processTurn`(标签计数、token 用量)、nudge 决策(growth/usage/pendingT1/shouldInject)、客户端 headers 和 SSE 重写。
|
|
291
|
+
`bili --debug`(或环境变量 `ACP_DEBUG=1`,或配置里 `"debug": true` —— 优先级:参数 > 环境变量 > 配置)会打印每次 `processTurn`(标签计数、token 用量)、nudge 决策(growth/usage/pendingT1/shouldInject)、客户端 headers 和 SSE 重写。
|
|
447
292
|
|
|
448
293
|
### 日志文件
|
|
449
294
|
|
|
450
|
-
所有日志**默认同时写入文件**:`~/.local/state/billion-context/bili.log`
|
|
451
|
-
(XDG state 目录)。同时仍打印到 stderr,所以前台运行 `bili start` 时终端也能看到。
|
|
452
|
-
|
|
453
|
-
```bash
|
|
454
|
-
# 配置: "logFile": "/custom/path.log"
|
|
455
|
-
# 环境变量: ACP_LOG_FILE=/custom/path.log (或 ACP_LOG_FILE=off 关闭文件,只保留 stderr)
|
|
456
|
-
```
|
|
457
|
-
|
|
458
|
-
文件超过 10 MB 自动轮转(重命名为 `bili.log.old`)。每个请求的缓存命中统计会以 `[acp-usage] round N input=X cached=Y (cache hit Z%)` 打印,可直接从日志衡量前缀缓存健康度。
|
|
295
|
+
所有日志**默认同时写入文件**:`~/.local/state/billion-context/bili.log`(XDG state 目录),同时仍打印到 stderr。覆盖用配置的 `"logFile"` 或 `ACP_LOG_FILE`(`off` 关闭文件)。超过 10 MB 自动轮转(`bili.log.old`)。每个请求的缓存命中统计以 `[acp-usage] round N input=X cached=Y (cache hit Z%)` 打印,可直接从日志衡量前缀缓存健康度。
|
|
459
296
|
|
|
460
297
|
### 自动更新
|
|
461
298
|
|
|
462
|
-
代理启动时和每 3 分钟检查 npm
|
|
463
|
-
|
|
464
|
-
永久禁用:配置(`"autoUpdate": false`)或环境变量(`ACP_AUTO_UPDATE=0`)。
|
|
299
|
+
代理启动时和每 3 分钟检查 npm 是否有新版本。发现新版本就原位安装并打印通知 —— **重启 `bili` 才能生效**,除非启用可选自重启(`--auto-restart-on-update` 参数 / `ACP_AUTO_RESTART_ON_UPDATE=1` 环境变量 / 配置 `"autoRestartOnUpdate": true`,默认关闭):零在途请求时校验新安装、停止接收连接、排空、在同一端口拉起替代进程并在其开始接受连接后退出(客户端自动重连;会话状态在磁盘上保留)。安全门:排空窗口全程零在途、re-exec 前安装完整性检查、10 分钟冷却标记防止版本抖动循环重启;任何失败恢复原监听器并回落到普通提醒。运行进程落后于磁盘安装("stale")时,Web UI 显示横幅,`GET /__bili/status` 返回 `{version, diskVersion, stale, autoRestartOnUpdate, inFlight}` 供脚本使用。永久禁用:配置(`"autoUpdate": false`)或环境变量(`ACP_AUTO_UPDATE=0`)。
|
|
465
300
|
|
|
466
301
|
## 配置
|
|
467
302
|
|
|
468
303
|
完整的配置参考 —— 配置文件位置、顶层键、providers、压缩调参、环境变量 ——
|
|
469
304
|
见 **[CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)**。
|
|
470
305
|
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
如果代理自身访问模型提供商的连接被墙(比如 GFW 内访问 `api.openai.com`),配置一个**上游代理**(本地 v2rayA / clash 的 HTTP 端口),让代理能连到提供商:
|
|
474
|
-
|
|
475
|
-
```jsonc
|
|
476
|
-
{
|
|
477
|
-
// 全局默认:所有提供商的出站都走这个代理
|
|
478
|
-
"proxy": "http://127.0.0.1:20172",
|
|
479
|
-
"providers": {
|
|
480
|
-
"https://api.openai.com/v1": {
|
|
481
|
-
// 按 URL 覆盖全局(给这个域名用另一个代理)
|
|
482
|
-
"proxy": "http://127.0.0.1:20173",
|
|
483
|
-
"models": { "gpt-5": { "context": 400000 } }
|
|
484
|
-
},
|
|
485
|
-
"https://open.bigmodel.cn/api/anthropic": {
|
|
486
|
-
// 空字符串 = 明确直连,覆盖全局代理
|
|
487
|
-
"proxy": "",
|
|
488
|
-
"models": { "glm-5.2": { "context": 1000000 } }
|
|
489
|
-
}
|
|
490
|
-
}
|
|
491
|
-
}
|
|
492
|
-
```
|
|
306
|
+
两个最常找的开关:
|
|
493
307
|
|
|
494
|
-
|
|
495
|
-
-
|
|
496
|
-
- 其余优先级为:`BILI_UPSTREAM_PROXY` → Web UI 手动代理 → 顶层 `proxy` →
|
|
497
|
-
`HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` → Windows 系统代理 → 直连。
|
|
498
|
-
- 空字符串 `""` 表示**明确直连**(覆盖并禁用)。
|
|
499
|
-
- 自动模式会让环境/系统 fallback 遵守 `NO_PROXY` 与 Windows 绕过列表。
|
|
500
|
-
指回 bili 自己本地端口的代理会被跳过或拒绝,防止自环。
|
|
501
|
-
- 支持 HTTP 和 HTTPS 代理 origin。SOCKS5（`socks5`/`socks5h`）暂不支持：显式
|
|
502
|
-
的 `BILI_UPSTREAM_PROXY` / 配置 `proxy` 使用此类 scheme 会在启动时报出可操作
|
|
503
|
-
的错误；环境变量/系统代理（`HTTPS_PROXY` 等）使用此类 scheme 时会被忽略并打
|
|
504
|
-
一次警告日志（流量随后回退为直连）。Clash/mihomo 用户请改用同一 mixed 端口
|
|
505
|
-
的 HTTP 形式（如 `http://127.0.0.1:7890`）。
|
|
506
|
-
- 两条出站路径都覆盖:`/bili/` 路径模式(fetch)和 MITM CONNECT 隧道(代理连接真实上游的链路走 HTTP CONNECT 代理)。
|
|
507
|
-
|
|
508
|
-
环境变量覆盖:`BILI_UPSTREAM_PROXY=http://127.0.0.1:20172`(优先于配置文件)。
|
|
509
|
-
Windows 下会自动发现常见 Clash/Mihomo 静态系统代理;Web UI 会显示实际来源,
|
|
510
|
-
以及 Internet Settings 中检测到的 PAC URL。
|
|
511
|
-
|
|
512
|
-
**MITM 与 `/bili/` —— 用 scheme 区分。** 登录客户端(ZCode 走 MITM)和 API-key 客户端可能连同一个域名(`open.bigmodel.cn`)。为了让它们的配置能区分,MITM 流量在查找键里用 `mitm://` scheme,`/bili/` 流量用真实的 `https://`:
|
|
513
|
-
|
|
514
|
-
| 客户端 | 查找键示例 |
|
|
515
|
-
|---|---|
|
|
516
|
-
| ZCode(MITM,登录态)| `mitm://open.bigmodel.cn` |
|
|
517
|
-
| API-key 客户端(`/bili/`)| `https://open.bigmodel.cn/api/anthropic` |
|
|
518
|
-
|
|
519
|
-
所以你可以给 ZCode 单独配代理,不影响 API-key 客户端:
|
|
520
|
-
```jsonc
|
|
521
|
-
{
|
|
522
|
-
"providers": {
|
|
523
|
-
"mitm://open.bigmodel.cn": { "proxy": "http://127.0.0.1:20173" },
|
|
524
|
-
"https://open.bigmodel.cn/api/anthropic": { "proxy": "http://127.0.0.1:20172" }
|
|
525
|
-
}
|
|
526
|
-
}
|
|
527
|
-
```
|
|
308
|
+
- **上游代理(防火墙/GFW)**—— 让代理自身出站流量走 v2rayA/clash:完整解析顺序、空字符串 = 显式直连、SOCKS5 拒绝、两条出站路径都覆盖,以及 `mitm://` vs `https://` 键 scheme 区分,都在 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)(服务端设置 → `proxy`;Providers → key schemes)。
|
|
309
|
+
- **线上兼容角色改写(`compat.roles`)**—— 上游拒绝 `developer` 角色?[CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)(服务端设置 → `compat`)已覆盖 —— 包括零配置即用的失败自学习修复。
|
|
528
310
|
|
|
529
311
|
## 会话机制
|
|
530
312
|
|
|
531
|
-
|
|
313
|
+
代理以**客户端自己提供的会话值(原样照搬)**为键隔离压缩状态(`src/session-id.ts`)—— 不哈希、不含协议/上游/API key 维度(它们会在会话中途变化,拿它们做 key 恰好在用户继续对话时把状态弄丢,#280/#286)。该 id 只在代理内部使用(状态存储、持久化、UI 标签),绝不上送。
|
|
532
314
|
|
|
533
315
|
取值来源(按顺序取第一个命中的):插件的 `x-bili-plugin-conversation`(仅当同时带 `x-bili-plugin` 标记 header)、客户端专属 header(`x-claude-code-session-id`、`x-grok-session-id`/`x-grok-conv-id`、`x-mavis-session-id`)、通用 header(`x-session-affinity`、`x-acp-session`、`x-session-id`、`x-opencode-session`、`session-id`/`session_id`)、或 body 字段:Responses wire 的 `session_id`/`metadata.session_id`,以及 Responses/OpenAI/Anthropic wire 上提升替代内容指纹回退的 `prompt_cache_key`。
|
|
534
316
|
|
|
@@ -540,44 +322,25 @@ Windows 下会自动发现常见 Clash/Mihomo 静态系统代理;Web UI 会显
|
|
|
540
322
|
| **omp**(经插件)| ✅ 发 | `prompt_cache_key` 提升为稳定身份(#268)|
|
|
541
323
|
| **pi**(裸跑)| ❌ 不发 | 无 → 见下方匿名前缀亲和 |
|
|
542
324
|
|
|
543
|
-
**无 header 客户端(pi 类):匿名前缀亲和。** 当客户端完全不发任何会话信号时,代理从重放的历史本身解析会话(`src/prefix-affinity.ts`,#309):只有当请求历史从第 0 条开始逐字节复现某已存会话的消息链时,才重新挂回该会话;否则获得一个确定性的新 `pfa-…`
|
|
544
|
-
|
|
545
|
-
- **恢复(resume)** 的对话会重新挂回自己的会话 —— 包括代理重启之后(#499)。
|
|
546
|
-
- **开头相同的新任务不会继承**另一个会话的 block 或受保护区:它拿到全新会话,历史一旦分叉就彻底独立(分叉血缘会被记录以便调试)。
|
|
547
|
-
- 完全没有任何可用信号时,请求会被显式 400 拒绝,而不是静默与他人状态碰撞。
|
|
325
|
+
**无 header 客户端(pi 类):匿名前缀亲和。** 当客户端完全不发任何会话信号时,代理从重放的历史本身解析会话(`src/prefix-affinity.ts`,#309):只有当请求历史从第 0 条开始逐字节复现某已存会话的消息链时,才重新挂回该会话;否则获得一个确定性的新 `pfa-…` 会话。后果(#1262):**恢复(resume)** 的对话重新挂回自己的会话(包括代理重启后,#499);**开头相同的新任务不会继承**另一个会话的 block —— 它拿到全新会话,历史一旦分叉就彻底独立;完全没有任何可用信号时,请求会被显式 400 拒绝,而不是静默与他人状态碰撞。
|
|
548
326
|
|
|
549
327
|
设计记录与威胁模型:[SESSION-IDENTITY.md](SESSION-IDENTITY.md)。消息粒度的对偶文档(为什么身份由内容派生、而非指派 id)是 [MESSAGE-IDENTITY.zh-CN.md](MESSAGE-IDENTITY.zh-CN.md)。
|
|
550
328
|
|
|
551
329
|
上游粘性路由方面,代理只转发客户端本来就提供的身份值(例如 body 里的 `session_id` 会以 `x-session-id` 上送),绝不自行合成一个。
|
|
552
330
|
|
|
553
|
-
**建议:** 发显式 id
|
|
331
|
+
**建议:** 发显式 id 的客户端可以安全并发。无 header 的多 agent 场景,优先装客户端插件(为每个会话盖稳定 id)或每会话传显式 `x-acp-session` header —— 两者都没有时,前缀亲和也能把不同任务分开(分叉的代价只是一次原始重发加压缩阶梯重启)。
|
|
554
332
|
|
|
555
333
|
### 派生(子)会话继承父会话的压缩上下文(#1333、#1362)
|
|
556
334
|
|
|
557
|
-
当 agent 派生子会话
|
|
558
|
-
|
|
559
|
-
- 子会话自己从未见过的内容,`decompress` / `search_context` 会沿父链回退(驻留或磁盘上的父会话,带环检测、深度上限 8);
|
|
560
|
-
- 任何东西都不会被复制进子会话状态,父会话也绝不被修改 —— 回退命中一律只读,子会话不可能覆盖父会话仍持有的内容;
|
|
561
|
-
- 若记录链接时代理不认识该父会话,子会话就按全新会话起步。
|
|
562
|
-
|
|
563
|
-
| Lane | 父会话信号 |
|
|
564
|
-
|---|---|
|
|
565
|
-
| **pi** RLM inline spawn | 会话 header 里的 `parentSession`(父会话文件路径 → 解析为其会话 id) |
|
|
566
|
-
| **omp** fork / newSession | 会话 header 里的 `parentSession`(裸会话 id 或文件路径,两种都接受) |
|
|
567
|
-
| **OpenCode V1**(原生插件) | SDK 会话信息的 `parentID`(按会话解析一次并缓存) |
|
|
568
|
-
| **OpenCode V2**(原生插件) | `session.created` 事件的 `data.parentID` |
|
|
569
|
-
|
|
570
|
-
claude/codex/dsh 不需要这个机制:它们要么子 agent 共享同一个会话 id,要么根本没有子会话概念。
|
|
335
|
+
当 agent 派生子会话(subagent 或 fork,从空历史起步、不重发父会话内容)时,它会在出生时上报这条血缘:身份注册携带父会话 id(`parentConversationId`),代理在子会话上记录一条只读链接(`derivedFrom`)。此后 `decompress` / `search_context` 对子会话自己从未见过的内容沿父链回退(带环检测、深度上限 8);任何东西都不复制进子会话,父会话也绝不被修改;父会话未知时子会话就按全新起步。各 lane 的父信号(pi/omp `parentSession` header、OpenCode V1/V2 `parentID`):[SESSION-IDENTITY.zh-CN.md](SESSION-IDENTITY.zh-CN.md#派生子会话出生时携带血统1333-1362)。claude/codex/dsh 在这里不需要任何信号:它们的子 agent 共享同一个会话 id,或根本没有子会话概念。
|
|
571
336
|
|
|
572
337
|
### Windows：把会话目录加入杀软排除项（#362）
|
|
573
338
|
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
当同一会话连续 N 次写失败（默认 `5`）时，代理会打一条一次性、可操作的告警，明确指出要排除的目录。要从根上修复：把 `%USERPROFILE%\.local\share\billion-context\` 加入杀软**排除项**（Windows Defender：设置 → 病毒和威胁防护 → 管理设置 → 排除项 → 添加排除 → 文件夹），并确认没有同步工具（OneDrive / Dropbox / …）在同步该路径。完整步骤见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md) 的「Windows：把会话目录加入杀软排除项」章节。
|
|
339
|
+
代理把每个会话的压缩状态持久化到会话目录(默认 `%USERPROFILE%\.local\share\billion-context\`),长会话每一轮都会重写该文件。在 Windows 上,实时杀毒(Defender)、搜索索引器或同步工具(OneDrive)可能在写入中途锁住该目录,导致 rename 以 `EPERM` 失败。同一会话连续 N 次写失败(默认 `5`)时,代理打一条一次性可操作告警,指明要排除的目录。根上修复:把 `%USERPROFILE%\.local\share\billion-context\` 加入杀软**排除项**,并确认没有同步工具在同步该路径 —— 完整步骤见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md) 的「Windows：把会话目录加入杀软排除项」章节。
|
|
577
340
|
|
|
578
341
|
### 会话文件清理（#1082）
|
|
579
342
|
|
|
580
|
-
|
|
343
|
+
短命会话会留下永远不会再被恢复的小状态文件。清理是**可选开启(opt-in)**的:设 `BILI_SESSION_GC=1` 才启用(默认关闭 —— 会话文件属于用户数据,不应有静默删除策略)。启用且持久化开启时,bili 在启动时和每小时扫描会话目录,只有**两个条件同时满足**才删除一个文件:年龄超过 `BILI_SESSION_GC_MAX_AGE_DAYS`(默认 7 天),并且该会话**从未被压缩过**(没有折叠块)、最近一次请求体 ≤ `BILI_SESSION_GC_MAX_TOKENS` token(默认 1M)—— 删除只丢字节不丢内容。CCR 内容存储遵循其会话文件的生命周期;被压缩过的会话永不删除;每次删除都写审计日志。详见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)。
|
|
581
344
|
|
|
582
345
|
## 状态
|
|
583
346
|
|