Skip to content
Closed
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
8 changes: 4 additions & 4 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed
| `diagnostics.dump4xxMaxBytes` | number | 2097152 (floor 1024) | BILI_DUMP_4XX_MAX_BYTES | Size cap for a single 4xx dump file. |
| `diagnostics.maxTotalBytes` | number | unset (off) | BILI_DUMP_MAX_TOTAL_BYTES | Total-size cap for debug dump dirs (dumps/, raw/, SSE dump dir); oldest files deleted first when exceeded (floor 1 MiB). Dumps have no rotation by default and can grow tens of GB/day under active capture (#2412). |
| `diagnostics.maxAgeDays` | number | unset (off) | BILI_DUMP_MAX_AGE_DAYS | Age cap in days for debug dump dirs; files older than this are deleted (floor 1 h). Off by default. |
| `diagnostics.renderNone` | boolean | false | ACP_RENDER_NONE | Disable all ACP tag rendering (raw wire study mode). |
| `diagnostics.renderNone` | boolean | false (dsh sessions: true since #3198) | ACP_RENDER_NONE | Disable all ACP tag rendering (raw wire study mode). Host-aware default since #3198: dsh-stamped sessions render none by default because dsh re-serializes its own resent history non-byte-stably around injected tags, breaking the prefix cache; set an explicit `false` to keep tags on a dsh session. |
| `diagnostics.noInjectTool` | boolean | false | ACP_NO_INJECT_TOOL | Stop injecting the acp_compress tool definition into requests. |
| `diagnostics.noCompressPrompt` | boolean | false | ACP_NO_COMPRESS_PROMPT | Stop appending the compression doctrine to system prompts. |
| `diagnostics.countTokensPassthrough` | boolean | false | ACP_COUNT_TOKENS_PASSTHROUGH | Forward /v1/messages/count_tokens to the upstream instead of answering locally. |
Expand Down Expand Up @@ -882,7 +882,7 @@ Since #2030 every pure-behavior knob has a config-file key alongside its env var
- **Type:** `{ dumpBody?: boolean; dumpReq?: boolean; rawDumpDir?: string; dump4xx?: boolean; dump4xxMaxBytes?: number; maxTotalBytes?: number; maxAgeDays?: number; renderNone?: boolean; noInjectTool?: boolean; noCompressPrompt?: boolean; countTokensPassthrough?: boolean; compressProtocol?: "tools" | "text" }`
- **Default:** `{ dumpBody: false, dumpReq: true, rawDumpDir: <state dir>/raw, dump4xx: false, dump4xxMaxBytes: 2097152, maxTotalBytes: null, maxAgeDays: null, renderNone: false, noInjectTool: false, noCompressPrompt: false, countTokensPassthrough: false, compressProtocol: "tools" }`
- **Status:** ACTIVE
- **Description:** Debug/diagnostic toggles that used to be env-only (`ACP_DUMP_BODY`, `ACP_DUMP_REQ`, `ACP_RAW_DUMP_DIR`, `BILI_DUMP_4XX`, `BILI_DUMP_4XX_MAX_BYTES`, `ACP_RENDER_NONE`, `ACP_NO_INJECT_TOOL`, `ACP_NO_COMPRESS_PROMPT`, `ACP_COUNT_TOKENS_PASSTHROUGH`, `ACP_COMPRESS_PROTOCOL`). Mostly read live per request (no restart needed), except `compressProtocol` which resolves once at boot like the env var did. `renderNone` stops the `mNNNNN` render tags from being injected into outgoing history — disable only if your workflow doesn't need ref-based compression (#933). Retention bounds (#2412): dump dirs are write-only with no rotation by default — active body/SSE capture measured at ~63 GB/day can fill a disk in days. Set `maxTotalBytes` and/or `maxAgeDays` to bound them (oldest-first deletion, `err-*`/`summary-err-*` incident dumps protected, deletions logged at warn level); leave both unset for unbounded retention. Details in the [env table](#config-file-keys-for-environment-knobs-2030).
- **Description:** Debug/diagnostic toggles that used to be env-only (`ACP_DUMP_BODY`, `ACP_DUMP_REQ`, `ACP_RAW_DUMP_DIR`, `BILI_DUMP_4XX`, `BILI_DUMP_4XX_MAX_BYTES`, `ACP_RENDER_NONE`, `ACP_NO_INJECT_TOOL`, `ACP_NO_COMPRESS_PROMPT`, `ACP_COUNT_TOKENS_PASSTHROUGH`, `ACP_COMPRESS_PROTOCOL`). Mostly read live per request (no restart needed), except `compressProtocol` which resolves once at boot like the env var did. `renderNone` stops the `mNNNNN` render tags from being injected into outgoing history — disable only if your workflow doesn't need ref-based compression (#933). Since #3198 the resolution is env > file > **host default**: dsh-stamped sessions (the `x-bili-plugin: dsh` header) default to `true` because dsh re-serializes tag-shaped bytes in its own persisted history non-byte-stably, so every newly-tagged message breaks the upstream prefix cache on first resend (A/B: session hit rate 85.6% → 91.2%); every other host stays `false`, and an explicit file/env value always beats the host default. Refs stay assigned internally under `none`, so growth-gated folds keep working; the cost is losing per-message ref citation in the model's view. Retention bounds (#2412): dump dirs are write-only with no rotation by default — active body/SSE capture measured at ~63 GB/day can fill a disk in days. Set `maxTotalBytes` and/or `maxAgeDays` to bound them (oldest-first deletion, `err-*`/`summary-err-*` incident dumps protected, deletions logged at warn level); leave both unset for unbounded retention. Details in the [env table](#config-file-keys-for-environment-knobs-2030).

### `fakeCompletion`

Expand Down Expand Up @@ -1620,7 +1620,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes
| `ACP_PROMPT_CACHE_ROUTING` | `promptCache.routing` | auto |
| `ACP_PROVIDERS` | `providersPath` | unset |
| `ACP_RAW_DUMP_DIR` | `diagnostics.rawDumpDir` | <state dir>/raw |
| `ACP_RENDER_NONE` | `diagnostics.renderNone` | false |
| `ACP_RENDER_NONE` | `diagnostics.renderNone` | false (dsh sessions: true since #3198) |
| `ACP_SESSION_HEADER` | `sessionHeader` | x-acp-session |
| `ACP_UPDATE_TAG` | `updateTag` | latest |
| `ACP_UPSTREAM` | `upstream` | https://api.anthropic.com |
Expand Down Expand Up @@ -1755,7 +1755,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes
| `BILI_ALLOW_PRIVATE_HTTP_PROVIDERS` | Opt-in switch (#2984): set to `1`/`true` to let plain-HTTP provider baseUrls on private networks (RFC1918, 127/8, link-local, IPv6 ULA/link-local, `*.local`/`.lan`/`.internal`) pass the agent-registry intake and summary-endpoint guards, which otherwise trust loopback plaintext only. Public IPs/domains and CGNAT (100.64/10) stay refused regardless. Default off — behavior identical to pre-#2984. A set env value owns the knob over `network.allowPrivateHttpProviders`. |
| `ACP_SESSION_HEADER` | Conversation-id header name (default `x-acp-session`). |
| `ACP_REASONING_KEEP` | Responses API only: set `none` to drop all reasoning items. Default routes reasoning through the compression pipeline so it is hidden automatically once its turn is summarized (prevents the unbounded accumulation that broke Codex's prompt-cache prefix). |
| `ACP_RENDER_NONE` | Set to `1` to stop injecting per-message render tags (the `` `<acp>` `` markers carrying `mNNNNN` refs) into outgoing request history — applies to every wire format (OpenAI chat, Anthropic, Responses) and compact rebuilds (#933). Default is `text-only`: the model reads these refs to cite messages in `compress` calls, so only disable them once you've confirmed your workflow doesn't need ref-based compression (e.g. tag echoes leaking into client-visible output). Previously this variable was honored only on the Responses path and compact; #933 extended it to all paths. |
| `ACP_RENDER_NONE` | Set to `1` to stop injecting per-message render tags (the `` `` `` markers carrying `mNNNNN` refs) into outgoing request history — applies to every wire format (OpenAI chat, Anthropic, Responses) and compact rebuilds (#933). Default is `text-only`: the model reads these refs to cite messages in `compress` calls, so only disable them once you've confirmed your workflow doesn't need ref-based compression (e.g. tag echoes leaking into client-visible output). Previously this variable was honored only on the Responses path and compact; #933 extended it to all paths. Since #3198 the effective default is host-aware: a dsh-stamped session (`x-bili-plugin: dsh`) resolves to `none` with NO variable set at all, because dsh re-renders tag-shaped bytes in its own persisted history non-byte-stably and each newly-tagged message then breaks the upstream prefix cache on first resend (A/B: session hit rate 85.6% → 91.2%, seams gone). All other hosts are unchanged; setting this variable or `diagnostics.renderNone` explicitly (including `0`/`false`) overrides the host default. Refs stay assigned internally and growth-gated nudges still list compressible ranges, so folding keeps working; what you give up is citing individual messages by ref. Expect exactly ONE full replay when flipping the flag mid-session, or when this default first applies after an upgrade. |
| `ACP_LOG_FILE` | Log file path (default XDG state path; `off` disables the file, keeps stderr). Auto-rotates at 10 MB. |
| `ACP_DUMP_SSE` | Directory to dump raw SSE frames for debugging — including loop-originated upstream responses (compress re-requests and truncation retries, named `<ts>-<sid>-loop<N>-raw.sse`), which the outer forward tee cannot see (#1455). |
| `BILI_STREAM_ERROR_SHAPE` | Set `"completion"` to restore the legacy failure shape on the anthropic/openai wire (failure text inside a synthesized successful completion); default `"protocol"` = protocol-native error frames (#1455). Same knob as `compat.streamErrorShape`; this env var wins. |
Expand Down
8 changes: 4 additions & 4 deletions CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,7 @@
| `diagnostics.dump4xxMaxBytes` | number | 2097152 (floor 1024) | BILI_DUMP_4XX_MAX_BYTES | 单个 4xx 转储文件的大小上限。 |
| `diagnostics.maxTotalBytes` | number | unset (off) | BILI_DUMP_MAX_TOTAL_BYTES | 调试转储目录(dumps/、raw/、SSE dump 目录)的总大小上限;超限时按最旧优先删除(下限 1 MiB)。转储默认无任何轮转,持续捕获下每天可增长数十 GB(#2412)。 |
| `diagnostics.maxAgeDays` | number | unset (off) | BILI_DUMP_MAX_AGE_DAYS | 调试转储目录的保留天数上限;超过该天数的文件被删除(下限 1 小时)。默认关闭。 |
| `diagnostics.renderNone` | boolean | false | ACP_RENDER_NONE | 禁用所有 ACP 标签渲染(原始线路研究模式)。 |
| `diagnostics.renderNone` | boolean | false(dsh 会话:自 #3198 起为 true) | ACP_RENDER_NONE | 禁用所有 ACP 标签渲染(原始线路研究模式)。#3198 起默认值按宿主感知:dsh 会话默认不渲染标签——dsh 对自身持久化历史的再序列化对注入的标签非字节稳定,会打断前缀缓存;显式设 `false` 可让 dsh 会话保留标签。 |
| `diagnostics.noInjectTool` | boolean | false | ACP_NO_INJECT_TOOL | 停止向请求注入 acp_compress 工具定义。 |
| `diagnostics.noCompressPrompt` | boolean | false | ACP_NO_COMPRESS_PROMPT | 停止向系统提示词附加压缩教条文本。 |
| `diagnostics.countTokensPassthrough` | boolean | false | ACP_COUNT_TOKENS_PASSTHROUGH | 把 /v1/messages/count_tokens 转发给上游,而不是本地应答。 |
Expand Down Expand Up @@ -882,7 +882,7 @@
- **类型:** `{ dumpBody?: boolean; dumpReq?: boolean; rawDumpDir?: string; dump4xx?: boolean; dump4xxMaxBytes?: number; maxTotalBytes?: number; maxAgeDays?: number; renderNone?: boolean; noInjectTool?: boolean; noCompressPrompt?: boolean; countTokensPassthrough?: boolean; compressProtocol?: "tools" | "text" }`
- **默认:** `{ dumpBody: false, dumpReq: true, rawDumpDir: <state dir>/raw, dump4xx: false, dump4xxMaxBytes: 2097152, maxTotalBytes: null, maxAgeDays: null, renderNone: false, noInjectTool: false, noCompressPrompt: false, countTokensPassthrough: false, compressProtocol: "tools" }`
- **状态:** ACTIVE
- **说明:** 此前仅有环境变量形态的调试/诊断开关(`ACP_DUMP_BODY`、`ACP_DUMP_REQ`、`ACP_RAW_DUMP_DIR`、`BILI_DUMP_4XX`、`BILI_DUMP_4XX_MAX_BYTES`、`ACP_RENDER_NONE`、`ACP_NO_INJECT_TOOL`、`ACP_NO_COMPRESS_PROMPT`、`ACP_COUNT_TOKENS_PASSTHROUGH`、`ACP_COMPRESS_PROTOCOL`)。除 `compressProtocol` 在启动时一次性解析(同旧环境变量行为)外,其余均按请求实时读取,无需重启。`renderNone` 停止向外发历史注入 `mNNNNN` 渲染标签 —— 仅当你的工作流不需要基于 ref 的压缩时才关闭(#933)。保留期限约束(#2412):转储目录只写不删、默认无轮转 —— 实测持续开启 body/SSE 捕获约 63 GB/天,数天内即可写满磁盘。设置 `maxTotalBytes` 和/或 `maxAgeDays` 可为其设限(最旧优先删除,`err-*`/`summary-err-*` 事故证据文件受保护不删,删除动作以 warn 级别记录日志);两者都不设置则保持无限期保留。详见[环境变量表](#环境变量的配置键对照-2030)。
- **说明:** 此前仅有环境变量形态的调试/诊断开关(`ACP_DUMP_BODY`、`ACP_DUMP_REQ`、`ACP_RAW_DUMP_DIR`、`BILI_DUMP_4XX`、`BILI_DUMP_4XX_MAX_BYTES`、`ACP_RENDER_NONE`、`ACP_NO_INJECT_TOOL`、`ACP_NO_COMPRESS_PROMPT`、`ACP_COUNT_TOKENS_PASSTHROUGH`、`ACP_COMPRESS_PROTOCOL`)。除 `compressProtocol` 在启动时一次性解析(同旧环境变量行为)外,其余均按请求实时读取,无需重启。`renderNone` 停止向外发历史注入 `mNNNNN` 渲染标签 —— 仅当你的工作流不需要基于 ref 的压缩时才关闭(#933)。#3198 起解析顺序为 env > 文件 > **宿主默认**:dsh 会话(`x-bili-plugin: dsh` 头)默认为 `true`——dsh 对自身持久化历史中标签形字节的再序列化非字节稳定,每条新注入标签的消息首次重发即打断上游前缀缓存(A/B:会话命中率 85.6% → 91.2%);其他宿主保持 `false`,显式的文件/env 值始终优先于宿主默认。`none` 下 ref 仍在内部分配,增长门控折叠照常工作;代价是模型视图中失去逐消息 ref 引用。保留期限约束(#2412):转储目录只写不删、默认无轮转 —— 实测持续开启 body/SSE 捕获约 63 GB/天,数天内即可写满磁盘。设置 `maxTotalBytes` 和/或 `maxAgeDays` 可为其设限(最旧优先删除,`err-*`/`summary-err-*` 事故证据文件受保护不删,删除动作以 warn 级别记录日志);两者都不设置则保持无限期保留。详见[环境变量表](#环境变量的配置键对照-2030)。

### `fakeCompletion`

Expand Down Expand Up @@ -1619,7 +1619,7 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报
| `ACP_PROMPT_CACHE_ROUTING` | `promptCache.routing` | auto |
| `ACP_PROVIDERS` | `providersPath` | unset |
| `ACP_RAW_DUMP_DIR` | `diagnostics.rawDumpDir` | <state dir>/raw |
| `ACP_RENDER_NONE` | `diagnostics.renderNone` | false |
| `ACP_RENDER_NONE` | `diagnostics.renderNone` | false(dsh 会话:自 #3198 起为 true) |
| `ACP_SESSION_HEADER` | `sessionHeader` | x-acp-session |
| `ACP_UPDATE_TAG` | `updateTag` | latest |
| `ACP_UPSTREAM` | `upstream` | https://api.anthropic.com |
Expand Down Expand Up @@ -1751,7 +1751,7 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报
| `BILI_ALLOW_PRIVATE_HTTP_PROVIDERS` | 可选开关(#2984):设为 `1`/`true` 后,私网(RFC1918、127/8、link-local、IPv6 ULA/link-local、`*.local`/`.lan`/`.internal`)上的明文 HTTP provider baseUrl 可通过 agent-registry 接收与摘要端点守卫——这些守卫默认只信任回环明文。公网 IP/域名与 CGNAT(100.64/10)无论如何都拒。默认关闭——行为与 #2984 之前逐字一致。已设置的环境变量值优先于 `network.allowPrivateHttpProviders`。 |
| `ACP_SESSION_HEADER` | 会话 id 请求头名称(默认 `x-acp-session`)。 |
| `ACP_REASONING_KEEP` | 仅 Responses API:设 `none` 丢弃全部 reasoning 项。默认让 reasoning 走压缩管道,其轮次被摘要后自动隐藏(避免无限累积破坏 Codex 的 prompt-cache 前缀)。 |
| `ACP_RENDER_NONE` | 设为 `1` 停止向出站请求历史注入逐消息渲染标签(承载 `mNNNNN` ref 的 `` `` `` 标记)——适用于所有线格式(OpenAI chat、Anthropic、Responses)及 compact 重建(#933)。默认 `text-only`:模型靠这些 ref 在 `compress` 调用中引用消息,只有确认自己的工作流不需要基于 ref 的压缩(例如标签回声泄漏到客户端可见输出)后才应禁用。此前该变量仅在 Responses 路径与 compact 上生效;#933 扩展到了所有路径。 |
| `ACP_RENDER_NONE` | 设为 `1` 停止向出站请求历史注入逐消息渲染标签(承载 `mNNNNN` ref 的 `` `` `` 标记)——适用于所有线格式(OpenAI chat、Anthropic、Responses)及 compact 重建(#933)。默认 `text-only`:模型靠这些 ref 在 `compress` 调用中引用消息,只有确认自己的工作流不需要基于 ref 的压缩(例如标签回声泄漏到客户端可见输出)后才应禁用。此前该变量仅在 Responses 路径与 compact 上生效;#933 扩展到了所有路径。#3198 起有效默认值按宿主感知:dsh 会话(`x-bili-plugin: dsh`)**无需设置任何变量**即解析为 `none`——dsh 对自身持久化历史中标签形字节的重渲染非字节稳定,每条新注入标签的消息首次重发即打断上游前缀缓存(A/B 实测:会话命中率 85.6% → 91.2%,缝消失)。其他宿主不变;显式设置本变量或 `diagnostics.renderNone`(含 `0`/`false`)可覆盖宿主默认。refs 仍在内部分配、growth-gated nudge 仍列出可压缩区间,所以折叠照常工作;代价是无法再按 ref 引用单条消息。会话中途翻转该标志、或升级后此默认首次生效时,预期恰好一次完整重放。 |
| `ACP_LOG_FILE` | 日志文件路径(默认 XDG state 路径;`off` 关闭文件只保留 stderr)。10 MB 自动轮转。 |
| `ACP_DUMP_SSE` | 调试用:转储原始 SSE 帧的目录——含压缩重发/截断重试的循环内上游响应(命名 `<ts>-<sid>-loop<N>-raw.sse`),外层 tee 看不到(#1455)。 |
| `BILI_STREAM_ERROR_SHAPE` | 设为 `"completion"` 恢复 anthropic/openai 线上旧的失败形状(失败文本包在合成的成功完成里);默认 `"protocol"` = 协议原生错误帧(#1455)。与 `compat.streamErrorShape` 同一开关,此环境变量优先。 |
Expand Down
3 changes: 2 additions & 1 deletion src/cache-ledger.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1968,11 +1968,12 @@ function formatSeam(r: BiliCacheReport): string {
out.push(` stateful-upstream check (#2483): if your upstream keeps a live session per conversation and validates the echoed history against its own transcript (claude-code-based relays such as magpie), bili's render tags on assistant text trip that check even though bili's own list is unchanged — set diagnostics.renderNone=true until per-route render-tags control ships; expect exactly ONE replay when flipping the flag mid-session`);
}
if (r.seam.client.count > 0) {
out.push("✎ CLIENT MID-HISTORY REWRITE (host-side insert — NOT a bili seam)");
out.push("✎ CLIENT MID-HISTORY REWRITE (host-side insert/rewrite — NOT a bili seam)");
out.push(` ${r.seam.client.count} sample(s) · ${fmtTok(r.seam.client.missed)} tok — the client's own resent history broke mid-list, so bili's faithful rebuild carried the break to the wire (host plugin insert / paste hoisting / re-render). Client-owned re-bill, not a rebuild seam.`);
for (const e of r.seam.events) {
if (e.client) out.push(` #${e.seq} ${fmtTime(e.at)} hit ${e.hitPct.toFixed(1)}% · input ${fmtTok(e.input)} · inbound message[${e.client.idx}] ${e.client.role}/${e.client.cls} ${e.client.len}B JSON · outbound ${fmtTok(e.lcpBytes)}B @ message[${e.msgIndex ?? "?"}] of ${e.prevMsgs}→${e.curMsgs}`);
}
out.push(` render-tag check (#3198): if your host re-renders ACP render tags inside its own resent history (dsh), these breaks are the host re-rendering bili's injected tags — set diagnostics.renderNone=true (ACP_RENDER_NONE=1) to remove the injection; refs stay assigned internally so growth-gated folds keep working, at the cost of per-message ref citation; expect exactly ONE replay when flipping the flag mid-session`);
}
if (r.seam.abortCorrelated > 0) {
out.push("⏻ ABORT-CORRELATED");
Expand Down
Loading
Loading