diff --git a/docs/configuration.ja.md b/docs/configuration.ja.md index 215a6ffc3e..0a5798c8b3 100644 --- a/docs/configuration.ja.md +++ b/docs/configuration.ja.md @@ -120,6 +120,7 @@ | `compat.roles` | record role → role | {} | — | メッセージロールを上流が受け入れる名前にマッピングします(例:developer→system);完全一致ロールのみ、プロバイダーごとのエントリがキーごとに優先されます。 | | `compat.dropFields` | string[] (dot paths) | [] | — | 未知のフィールドで 400 を返す厳格スキーマゲートウェイ向けに、転送されるすべてのボディからドットパスフィールドを削除します;グローバル + プロバイダーごとのリストは加算的に統合されます。 | | `compat.streamErrorShape` | "protocol" \| "completion" | protocol | BILI_STREAM_ERROR_SHAPE | 200 がコミットされた後、上流ストリーム失敗がどのように提示されるか:プロトコルネイティブのエラーフレーム(デフォルト)またはレガシーの合成完了形状。 | +| `compat.degenerateTurn` | "error" \| "passthrough" | error | BILI_DEGENERATE_TURN | プラグインチャットパイプで退化ターンのリトライ後も利用可能な出力がゼロだった場合の終了処理(#4913):インバンドストリームエラー(デフォルト、#870)または空ターンを通常の完了として通過させる(#870 以前)。 | | `compat.noCacheControl` | boolean | false | BILI_NO_CACHE_CONTROL | Anthropic レーンの cache_control ブレークポイントを完全にスタンプしないようにします(独自のブレークポイントポリシーを持つ上流/リレー用のエスケープハッチ)。 | | `compat.keepResponseId` | boolean | false | ACP_KEEP_RESPONSE_ID | カーネル再構築された Responses リクエストで previous_response_id を保持します(デフォルトでは削除するため、再構築されたボディは上流が発行したことのない ID を参照しません)。 | | `dsh` | object | {} | BILI_ALLOW_DSH_COMPACTION | セクションは認識されるが、従来のエスケープハッチは削除された(#3666、#2028 を代替):`allowDshCompaction` キーおよび `BILI_ALLOW_DSH_COMPACTION` 環境変数はもはや存在しない — dsh ネイティブコンパクションは、すべてのレーンにおいてワイヤガードによって無条件に拒否される。残存する `dsh.allowDshCompaction` の値は、一度限りの非推奨警告とともに無視される;代わりにホスト側の抑制を適用すること(#3354/#2474)。ライブキー — `dsh.authoredCompaction`、`dsh.contextTab`、`dsh.contextTabLabel` — は以下のエントリに文書化されている。 | @@ -536,13 +537,14 @@ ``` ### `compat` -- **Type:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; noCacheControl?: boolean; keepResponseId?: boolean }` +- **Type:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; degenerateTurn?: "error" | "passthrough"; noCacheControl?: boolean; keepResponseId?: boolean }` - **Default:** `{}` (無効) - **Status:** ACTIVE - **Description:** グローバルなワイヤー互換ロールマップ。`roles` はメッセージのロールを、アップストリームが受け入れるロール名にマッピングします。例: `{"compat":{"roles":{"developer":"system"}}}` は、`developer` ロールを拒否するアップストリーム(#552、新しい codex クライアント)に対して、最終転送ボディ内で `developer` → `system` に書き換えます。`openai` の chat-completions と `responses` リクエストに適用されます。完全一致するロールのみ対象であり、ボディ内の他の部分は変更されません。再送信される compress-retry ボディにも同じ書き換えが適用されます。プロバイダーごとの `compat.roles` エントリ([Providers](#providers) 参照)はキーごとに優先されます。デフォルトの `{}` では、ボディはバイト単位で変更なしに転送されます。 - **Learn-on-failure:** compat が設定されていない場合、アップストリームからの `400 Invalid role: …` は自動修正されます — bili は問題のあるロールを `system` に書き換え、1回リトライし、そのマッピングを**セッションスコープ**(セッション内のメモリ上;設定ファイルには書き込まれない)で記憶します。そのセッション内の後続のリクエストでは、400 の往復がスキップされます。修正が発火した際に出力される情報ログには、恒久的なプロバイダーごとのスニペットが含まれます。 - **dropFields:** 最終転送ボディから削除するフィールドのドットパスリスト — クライアントが常に送信するがアップストリームが受け付けないフィールドを拒否する厳格スキーマのアップストリーム向け(#1757)。パスはプレーンオブジェクトのセグメントのみ使用可能(`reasoning.summary`);ワイルドカードと配列インデックスはサポートされていません;存在しないパスや非オブジェクトの中間要素はサイレントにスキップされます;文字列値は決して検査・変更されません — 構造キーのみ対象であり、ツール引数やメッセージコンテンツはバイト単位で正確に保たれます。`roles` と異なり、すべてのワイヤープロトコル(任意の JSON リクエストボディ)に適用されます。グローバルとプロバイダーごとのリストは**加算的に**(和集合)マージされます — プロバイダーエントリはパスを追加できますが、グローバルのものを撤回することはできません。最終送信ボディのロールマッピング / 出力ステアリングの後(プロンプトキャッシュスタンプの前)に適用され、compress-retry ループが再送信するすべてのボディおよび逐語パススルー転送にも適用されます。一致するフィールドのないボディはバイト単位で変更なしに転送されます;1つ以上のフィールドが実際に削除された場合、削除されたパスを記録する情報行がログ出力されます。オプトインのみ — v1 では learn-on-failure はありません: `"compat":{"dropFields":["reasoning.summary"]}`。 - **streamErrorShape:** アップストリームストリーム失敗が、200 レスポンスがすでにコミットされた後に anthropic/openai ワイヤー上でどのように提示されるか(`"protocol"`(デフォルト)または `"completion"`)。`protocol` はプロトコルネイティブの失敗チャネルに乗ります — anthropic/responses は `event: error` フレームを受け取り、openai はトップレベルの `error` フレームに続けて `[DONE]` を受け取ります — これによりクライアントは「このターンが失敗した」と「このターンが完了した」を区別し、独自のリトライロジックを維持できます(#1455: 従来の合成された `end_turn`/`finish_reason` は、死んだターンを通常の完了として装い、クライアントのリトライ予算をサイレントに消費していました)。`completion` は、インバンドエラーイベントを表面化できない SDK を持つホストのために、そのレガシー形状(合成された正常な完了内の失敗テキスト)を復元します。設定ファイル: `"compat":{"streamErrorShape":"completion"}`;環境変数 `BILI_STREAM_ERROR_SHAPE` が優先されます。google ワイヤーのみ影響を受けません(すでにネイティブエラーフレームを使用);responses ワイヤーでは、このノブはサーバーサイドの終了を合成されたアイテムライフサイクル完了から `event: error` フレームに変更します(ループ内での終了はすでに `response.failed` 経由でネイティブでした)。 +- **degenerateTurn:** プラグインチャットパイプで、退化ターミナルターン(#2756 ゲート)がその一度の継続リトライ再発行(#732/#821)後も依然として利用可能な出力がゼロだった場合(=リトライも空で終了した場合)の終了処理(`"error"`(デフォルト)または `"passthrough"`)。`error` は #870 のインバンドストリームエラーを送出する:空ターンはそれ以外では「モデルが何も生成しなかった」と区別がつかず、セッションは死んでいるのにアイドルと読み取られ、ホストがそれを自発的に表には出さない — 提示形状は `streamErrorShape` に従う。`passthrough` は #870 以前の終了に戻すオプトイン:空ターンを通常の完了として通過させる — プロキシレーンと responses ワイヤーがこの条件に対してすでに取っている同じ終了(両者に致命的な分岐は元々ない)。設定ファイル:`"compat":{"degenerateTurn":"passthrough"}`;環境変数 `BILI_DEGENERATE_TURN` が優先。影響するのはプラグインチャットレーンのみ;不明な値は `"error"` にフォールバック。(#4913:致命的な終了には以前は出口がなかった — thinking のみで応答するローカルモデルに固定されたホストはパススルーの復元を必要としていた。) - **noCacheControl:** (`#2030`) `true` にすると、bili の Anthropic レーンでの `cache_control` ブレークポイントスタンプが無効になります — フィールドを拒否するアップストリームや、独自のブレークポイントポリシーを持つリレーのためのエスケープハッチです。環境変数 `BILI_NO_CACHE_CONTROL` が優先されます;完全なメカニクスはその[環境変数エントリ](#environment-variables)を参照してください。 - **keepResponseId:** (`#2030`) `true` にすると、カーネル再構築された Responses リクエストで `previous_response_id` を保持し、ストリップしません(デフォルトではストリップするため、再構築されたボディは、書き換えられた入力に対してアップストリームが発行しなかったレスポンス ID を参照することはありません)。環境変数 `ACP_KEEP_RESPONSE_ID=1` が優先されます。 @@ -1956,6 +1958,7 @@ ACP ネイティブエージェント(現在は `pi` 拡張機能)は、プ | `BILI_CODEX_COMPACT` | `codexCompact` | "intercept" | | `BILI_DECODED_BODY_BYTES` | `network.decodedBodyBytes` | 10737418240 | | `BILI_DECOMPRESS_TMP_CAP` | `decompressTmpCap` | 50 | +| `BILI_DEGENERATE_TURN` | `compat.degenerateTurn` | error | | `BILI_DSH_AUTHORED_COMPACTION` | `dsh.authoredCompaction` | true (on, #3901 flip) | | `BILI_DSH_CONTEXT_TAB` | `dsh.contextTab` | true | | `BILI_DUMP_4XX` | `diagnostics.dump4xx` | false | diff --git a/docs/configuration.md b/docs/configuration.md index d2bddf9df9..4f374d8448 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -123,6 +123,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed | `compat.roles` | record role → role | {} | — | Map message roles to the names your upstream accepts (e.g. developer→system); exact-match roles only, per-provider entries win per key. | | `compat.dropFields` | string[] (dot paths) | [] | — | Dot-path fields stripped from every forwarded body for strict-schema gateways that 400 on unknown fields; global + per-provider lists union additively. | | `compat.streamErrorShape` | "protocol" \| "completion" | protocol | BILI_STREAM_ERROR_SHAPE | How upstream stream failures are presented after the 200 is committed: protocol-native error frames (default) or the legacy synthesized-completion shape. | +| `compat.degenerateTurn` | "error" \| "passthrough" | error | BILI_DEGENERATE_TURN | Terminal for the plugin chat pipe when the degenerate-turn retry ALSO ends with no usable output (#4913): in-band stream error (default, #870) or the empty turn passed through as a normal completion (pre-#870). | | `compat.noCacheControl` | boolean | false | BILI_NO_CACHE_CONTROL | Stop stamping Anthropic-lane cache_control breakpoints entirely (escape hatch for upstreams/relays with their own breakpoint policy). | | `compat.keepResponseId` | boolean | false | ACP_KEEP_RESPONSE_ID | Preserve previous_response_id on kernel-rebuilt Responses requests (default strips it so rebuilt bodies never reference ids the upstream never issued). | | `dsh` | object | {} | BILI_ALLOW_DSH_COMPACTION | Section recognized but its former escape hatch is gone (#3666, superseding #2028): the allowDshCompaction key and the BILI_ALLOW_DSH_COMPACTION env var no longer exist — dsh native compaction is refused unconditionally by the wire guard on every lane. Leftover dsh.allowDshCompaction values are ignored with a one-time deprecation warning; apply host-side suppression instead (#3354/#2474). The live keys — dsh.authoredCompaction, dsh.contextTab, dsh.contextTabLabel — are documented in the following entries. | @@ -540,13 +541,14 @@ Top-level keys that control how the proxy listens and behaves globally. ### `compat` -- **Type:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; noCacheControl?: boolean; keepResponseId?: boolean }` +- **Type:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; degenerateTurn?: "error" | "passthrough"; noCacheControl?: boolean; keepResponseId?: boolean }` - **Default:** `{}` (disabled) - **Status:** ACTIVE - **Description:** Global wire-compat role map. `roles` maps message roles to the role name your upstream accepts, e.g. `{"compat":{"roles":{"developer":"system"}}}` rewrites `developer` → `system` on the final forwarded body for upstreams that reject the `developer` role (#552, newer codex clients). Applies to `openai` chat-completions and `responses` requests; exact-match roles only, everything else in the body is untouched; re-sent compress-retry bodies carry the same rewrite. Per-provider `compat.roles` entries (see [Providers](#providers)) win per key. Default `{}` forwards bodies byte-for-byte unchanged. - **Learn-on-failure:** with no compat configured, an upstream `400 Invalid role: …` is auto-fixed — bili rewrites the offending role to `system`, retries once, and remembers the mapping **session-scoped** (in-memory on the session; never written to config). Later requests in that session skip the 400 round-trip. The info log emitted when the fix fires carries the permanent per-provider snippet. - **dropFields:** dot-path list of fields to delete from the final forwarded body — for strict-schema upstreams that reject a field the *client* always sends but the upstream does not accept (#1757). Paths use plain-object segments only (`reasoning.summary`); wildcards and array indices are not supported; nonexistent paths and non-object intermediates are skipped silently; string values are never inspected or altered — structural keys only, so tool arguments and message content stay byte-exact. Unlike `roles`, it applies on every wire protocol (any JSON request body). Global and per-provider lists merge **additively** (union) — a provider entry can add paths but never retract a global one. Applied after role mapping / output steering on the final outbound body (before the prompt-cache stamp), to every body the compress-retry loops re-send, and to verbatim pass-through forwards alike. A body with no matching field is forwarded byte-for-byte unchanged; when ≥1 field is actually dropped an info line logs the dropped paths. Opt-in only — no learn-on-failure in v1: `"compat":{"dropFields":["reasoning.summary"]}`. - **streamErrorShape:** how an upstream stream failure is presented on the anthropic/openai wire once the 200 response is already committed (`"protocol"`, default, or `"completion"`). `protocol` rides the protocol-native failure channel — anthropic/responses get an `event: error` frame, openai a top-level `error` frame followed by `[DONE]` — so clients can distinguish "this turn failed" from "this turn finished" and keep their own retry logic armed (#1455: the old synthesized `end_turn`/`finish_reason` dressed a dead turn as a normal completion and silently consumed client retry budgets). `completion` restores that legacy shape (failure text inside a synthesized successful completion) for hosts whose SDK cannot surface in-band error events. Config file: `"compat":{"streamErrorShape":"completion"}`; env `BILI_STREAM_ERROR_SHAPE` wins. Only the google wire is unaffected (already native error frames); on the responses wire this knob changes the server-side exit from the synthesized item-lifecycle completion to the `event: error` frame (its in-loop exit was already native via `response.failed`). +- **degenerateTurn:** terminal handling for the plugin chat-completions pipe when a degenerate terminal turn (#2756 gate) survives its one continuation-retry re-issue (#732/#821) — i.e. the retry ALSO ended with no usable output (`"error"`, default, or `"passthrough"`). `error` emits the #870 in-band stream error: the empty turn is otherwise indistinguishable from a model that produced nothing, the session would read as idle while dead, and the host never surfaces that on its own — its presentation shape follows `streamErrorShape`. `passthrough` opts back into the pre-#870 terminal: the empty turn passes through as a normal completion — the same terminal the proxy lane and the responses wire already take for this condition (they never had the fatal branch). Config file: `"compat":{"degenerateTurn":"passthrough"}`; env `BILI_DEGENERATE_TURN` wins. Only the plugin chat lane is affected; unknown values fall back to `"error"`. (#4913: the fatal terminal previously had no exit — hosts pinned to local models that answer thinking-only needed the pass-through back.) - **noCacheControl:** (`#2030`) `true` disables bili's Anthropic-lane `cache_control` breakpoint stamping — the escape hatch for upstreams that reject the field or relays with their own breakpoint policy. Env twin `BILI_NO_CACHE_CONTROL` wins; full mechanics in its [env entry](#environment-variables). - **keepResponseId:** (`#2030`) `true` keeps `previous_response_id` on kernel-rebuilt Responses requests instead of stripping it (default strips it, so a rebuilt body never references a response id the upstream never issued for the rewritten input). Env twin `ACP_KEEP_RESPONSE_ID=1` wins. @@ -1970,6 +1972,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes | `BILI_CODEX_COMPACT` | `codexCompact` | "intercept" | | `BILI_DECODED_BODY_BYTES` | `network.decodedBodyBytes` | 10737418240 | | `BILI_DECOMPRESS_TMP_CAP` | `decompressTmpCap` | 50 | +| `BILI_DEGENERATE_TURN` | `compat.degenerateTurn` | error | | `BILI_DSH_AUTHORED_COMPACTION` | `dsh.authoredCompaction` | true (on, #3901 flip) | | `BILI_DSH_CONTEXT_TAB` | `dsh.contextTab` | true | | `BILI_DUMP_4XX` | `diagnostics.dump4xx` | false | diff --git a/docs/configuration.zh-CN.md b/docs/configuration.zh-CN.md index 3ad7b20267..f563a9feb3 100644 --- a/docs/configuration.zh-CN.md +++ b/docs/configuration.zh-CN.md @@ -123,6 +123,7 @@ | `compat.roles` | record role → role | {} | — | 把消息角色映射为上游接受的名字(如 developer→system);仅精确匹配角色,逐 provider 条目按键级胜出。 | | `compat.dropFields` | string[] (dot paths) | [] | — | 从每个转发请求体中剔除的点路径字段,面向对未知字段返回 400 的严格 schema 网关;全局与逐 provider 列表加法并集。 | | `compat.streamErrorShape` | "protocol" \| "completion" | protocol | BILI_STREAM_ERROR_SHAPE | 200 已提交后上游流失败的呈现方式:协议原生错误帧(默认)或旧版合成完成形态。 | +| `compat.degenerateTurn` | "error" \| "passthrough" | error | BILI_DEGENERATE_TURN | plugin chat 管道的退化回合重试后仍无可用输出时的终局(#4913):带内流错误(默认,#870)或把空回合作为正常完成放行(pre-#870)。 | | `compat.noCacheControl` | boolean | false | BILI_NO_CACHE_CONTROL | 完全停止 Anthropic 通道的 cache_control 断点打标(面向拒收该字段或有自有断点策略的上游/中继的逃生门)。 | | `compat.keepResponseId` | boolean | false | ACP_KEEP_RESPONSE_ID | 在内核重建的 Responses 请求上保留 previous_response_id(默认剔除,使重建请求体永不引用上游从未签发过的响应 id)。 | | `dsh` | object | {} | BILI_ALLOW_DSH_COMPACTION | 段仍被识别,但其原逃生门已移除(#3666,取代 #2028):allowDshCompaction 键与 BILI_ALLOW_DSH_COMPACTION 环境变量已不存在——dsh 原生压缩现在在所有线路上被无条件拒绝。遗留的 dsh.allowDshCompaction 取值会被忽略(一次性弃用警告);请改用宿主侧抑制(#3354/#2474)。存活的键——dsh.authoredCompaction、dsh.contextTab、dsh.contextTabLabel——见接下来的条目。 | @@ -540,13 +541,14 @@ ### `compat` -- **类型:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; noCacheControl?: boolean; keepResponseId?: boolean }` +- **类型:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; degenerateTurn?: "error" | "passthrough"; noCacheControl?: boolean; keepResponseId?: boolean }` - **默认值:** `{}`(禁用) - **状态:** ACTIVE - **说明:** 全局线上兼容角色映射。`roles` 把消息角色映射为上游接受的角色名,例如 `{"compat":{"roles":{"developer":"system"}}}` 把 `developer` → `system`,用于拒绝 `developer` 角色的上游(#552,新版 codex 客户端会发送)。作用于 `openai` chat-completions 与 `responses` 请求;仅精确匹配角色,体内其它内容不动;压缩重试重发的请求体同样携带。按 provider 的 `compat.roles`(见 [Providers](#providers))按键优先。默认 `{}` 逐字节透明转发。 - **失败自学习:** 未配置 compat 时,上游返回 `400 Invalid role: …` 会被自动修复 —— bili 把被拒角色改写为 `system`,重试一次,并把学到的映射记在**会话上**(仅内存,绝不写入配置)。该会话后续请求免 400 往返。修复生效时打印的 info 日志附带可永久化的 per-provider 片段。 - **dropFields:** 最终转发体中要删除的字段点分路径列表 —— 用于严格 schema 上游拒绝*客户端*固定发送但上游不认的字段(#1757)。路径仅限纯对象段(如 `reasoning.summary`),不支持通配符与数组下标;不存在的路径与非对象中间节点静默跳过;字符串值永不检查或改写 —— 只删结构键,工具参数与消息内容逐字节不变。与 `roles` 不同,适用于所有 wire 协议(任意 JSON 请求体)。全局与 per-provider 列表**相加**合并(并集)—— provider 条目只能追加、不能撤销全局路径。应用于角色映射/输出转向之后的最终出站体(prompt-cache stamp 之前)、压缩重试重发的每个请求体,以及逐字节直通转发。无命中时逐字节不变;实际删除 ≥1 个字段时打一条 info 日志列出被删路径。纯 opt-in,v1 不做失败自学习:`"compat":{"dropFields":["reasoning.summary"]}`。 - **streamErrorShape:** 200 响应已提交后,上游流式失败在 anthropic/openai 线上如何呈现给客户端(默认 `"protocol"`,或 `"completion"`)。`protocol` 走协议原生失败通道——anthropic/responses 收 `event: error` 帧,openai 收顶层 `error` 帧后跟 `[DONE]`——客户端能区分「这一轮失败了」和「这一轮完成了」,自身重试逻辑保持可用(#1455:旧版合成的 `end_turn`/`finish_reason` 让死掉的回合看起来像正常完成,静默吃掉了客户端的重试预算)。`completion` 恢复该旧形状(失败文本包在合成的成功完成里),供无法呈现带内错误事件的宿主使用。配置文件:`"compat":{"streamErrorShape":"completion"}`;环境变量 `BILI_STREAM_ERROR_SHAPE` 优先。仅 google 线不受影响(本来就是原生错误帧);responses 线上该开关改变的是服务端出口:从合成的 item 生命周期完成帧改为 `event: error` 帧(其循环内出口本就走 `response.failed` 原生通道)。 +- **degenerateTurn:** plugin chat-completions 管道的退化回合(#2756 门)在重发其唯一一次续写重试(#732/#821)后仍无任何可用输出——即重试也空手而归时——的终局处理(`"error"` 默认,或 `"passthrough"`)。`error` 发 #870 带内流错误:空回合否则与“模型什么都没产出”无法区分,会话看起来空闲实则已死,宿主自己永远不会暴露它——其呈现形态随 `streamErrorShape`。`passthrough` 恢复 pre-#870 终局:空回合作为正常完成放行——这正是 proxy 车道与 responses wire 对该情形已在用的同一终局(它们从未有过致命分支)。配置文件:`"compat":{"degenerateTurn":"passthrough"}`;环境变量 `BILI_DEGENERATE_TURN` 优先。只影响 plugin chat 车道;未知值回落 `"error"`。(#4913:致命终局此前没有出口——只能 thinking 应答的本地模型宿主需要放行回来。) - **noCacheControl:**(#2030)`true` 关闭 bili 在 Anthropic 通道上的 `cache_control` 断点标注 —— 用于拒绝该字段的上游或有自己断点策略的中继。环境变量对应项 `BILI_NO_CACHE_CONTROL` 优先;完整机制见其[环境变量条目](#环境变量)。 - **keepResponseId:**(#2030)`true` 保留 kernel 重建的 Responses 请求上的 `previous_response_id`,不再剥离(默认剥离:重建后的 body 引用的是上游从未为改写后输入签发过的 response id,没有意义)。环境变量对应项 `ACP_KEEP_RESPONSE_ID=1` 优先。 @@ -1947,6 +1949,7 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报 | `BILI_CODEX_COMPACT` | `codexCompact` | "intercept" | | `BILI_DECODED_BODY_BYTES` | `network.decodedBodyBytes` | 10737418240 | | `BILI_DECOMPRESS_TMP_CAP` | `decompressTmpCap` | 50 | +| `BILI_DEGENERATE_TURN` | `compat.degenerateTurn` | error | | `BILI_DSH_AUTHORED_COMPACTION` | `dsh.authoredCompaction` | true (on, #3901 flip) | | `BILI_DSH_CONTEXT_TAB` | `dsh.contextTab` | true | | `BILI_DUMP_4XX` | `diagnostics.dump4xx` | false | diff --git a/docs/lifecycle.md b/docs/lifecycle.md index 97c4400148..9fa26955a6 100644 --- a/docs/lifecycle.md +++ b/docs/lifecycle.md @@ -39,6 +39,7 @@ | `BILI_FAKE_COMPLETION_RETRIES` | fake-completion fallback | 假完成重试(opt-in,默认 0 = 禁用) | fallback 机制定型后转 §2 | opt-in | | `BILI_NO_CACHE_CONTROL` | compat | 历史 no-cache-control 怪癖保留(knobs.ts:458 明言 "Historical quirk preserved in the env") | 兼容窗口结束后退役 | 默认 off | | `BILI_STREAM_ERROR_SHAPE` | compat | 给无法带内上报错误的 SDK 的流错误形状兼容 | 兼容保留(长期) | 常设兼容旋钮 | +| `BILI_DEGENERATE_TURN` | #4913 compat | plugin chat 车道退化回合重试耗尽后的终局:`error` 默认(#870 带内报错)/ `passthrough`(pre-#870 放行空回合为正常完成) | 确认无人用 passthrough 后退役(与 BILI_STREAM_ERROR_SHAPE 同类) | 默认 error | | `BILI_SUBAGENT_SPLIT` | #970 | subagent 拆分(默认 on) | 成为既定行为后移 §2 | 默认 ON(`=0` 退出) | | `BILI_PERSONA_SPLIT` | Responses personaSplit | Responses 线路 instructions 指纹分叉(默认 on;`=0` / `personaSplit: false` 关闭,剥 `instructionsFingerprintKeyed`、保留 identity) | 成为既定行为后移 §2 | 默认 ON(`=0` 退出) | | `BILI_RESUME_INHERITANCE` | resume inheritance | resume 继承行为(默认 on) | 同上 | 默认 ON(`=0` 退出) | diff --git a/reference/architecture.md b/reference/architecture.md index f02e4afefa..477af01d9e 100644 --- a/reference/architecture.md +++ b/reference/architecture.md @@ -304,6 +304,7 @@ billion-context/ │ ├── remote-notices.ts # Remote announcement feed watcher: fail-open polling, last-known-good snapshot (#5548) │ ├── request-membership.ts # Settle-side membership probe: is this usage report ours (#4805) │ ├── resolver-wedge.ts # Persistent local DNS resolver wedge detector + alarm (#5221) +│ ├── responses-system-sections.ts # Single source of truth for the Responses-wire developer-section join: steady prepare + round-2 rebuild share one separator (#6922) │ ├── responses-tool-output.ts # Responses tool-output image parts: projection + patch helpers │ ├── rollout.ts # Feature rollout: per-install uuid, basis-point buckets, nested cohorts (#3062) │ ├── runaway-guard.ts # Intrinsic stream terminator for runaway tag/codepoint enumeration (#2346) diff --git a/src/config.ts b/src/config.ts index ef473e7a98..c102341c93 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1012,6 +1012,15 @@ export type ProxyOptions = { * whose SDK cannot surface in-band errors. Env BILI_STREAM_ERROR_SHAPE * wins over the file's compat.streamErrorShape. */ streamErrorShape?: "protocol" | "completion"; + /** #4913: how the plugin chat pipe terminates an EXHAUSTED degenerate-turn + * retry — the second attempt after the continuation nudge (#732/#821) + * also ended with no usable output (thinking/echo only, clean stop). "error" + * (default) emits the #870 in-band stream error; "passthrough" passes the + * empty turn through as a normal completion (pre-#870). Only the chat + * pipe has this fatal branch — the proxy lane and the responses wire + * already pass this condition through, so the knob is a no-op for them. + * Env BILI_DEGENERATE_TURN wins over the file's compat.degenerateTurn. */ + degenerateTurn?: "error" | "passthrough"; /** Global-level image billing mode (#767); per-provider route entries * override it, env BILI_IMAGE_BILLING overrides both. undefined = auto * (= pixels for every host since #1843). */ @@ -1793,6 +1802,7 @@ export function loadOptions(env: NodeJS.ProcessEnv = process.env): ProxyOptions }, compat: { roles: parseCompatRoles(fileConfig.compat?.roles) ?? {}, dropFields: parseCompatDropFields(fileConfig.compat?.dropFields) ?? [] }, streamErrorShape: parseStreamErrorShape(env.BILI_STREAM_ERROR_SHAPE ?? fileConfig.compat?.streamErrorShape), + degenerateTurn: parseDegenerateTurn(env.BILI_DEGENERATE_TURN ?? fileConfig.compat?.degenerateTurn), imageBilling: parseImageBilling(fileConfig.imageBilling), imageTokenCap: parseImageTokenCap(fileConfig.imageTokenCap), sessionHeader: env.ACP_SESSION_HEADER ?? fileConfig.sessionHeader ?? "x-acp-session", @@ -2128,7 +2138,7 @@ type FileConfig = { * cache_control marks entirely (env BILI_NO_CACHE_CONTROL wins). * `keepResponseId` (#2030): set `true` to preserve previous_response_id * on rebuilt Responses requests (env ACP_KEEP_RESPONSE_ID=1 wins). */ - compat?: { roles?: Record; streamErrorShape?: string; dropFields?: string[]; noCacheControl?: boolean; keepResponseId?: boolean }; + compat?: { roles?: Record; streamErrorShape?: string; degenerateTurn?: string; dropFields?: string[]; noCacheControl?: boolean; keepResponseId?: boolean }; /** Global image billing mode (#767): "auto" | "pixels" | "bytes". * Per-provider `imageBilling` overrides it; env BILI_IMAGE_BILLING wins * over both. See ProviderRoute.imageBilling. */ @@ -3235,6 +3245,10 @@ function parseStreamErrorShape(value: unknown): "protocol" | "completion" { return value === "completion" ? "completion" : "protocol"; } +function parseDegenerateTurn(value: unknown): "error" | "passthrough" { + return value === "passthrough" ? "passthrough" : "error"; +} + export function parsePromptCacheRouting(value: string | undefined): PromptCacheRouting { // #5079: absent/unknown falls back to "disabled" (was "auto") — self-stamping is opt-in now; // explicit "auto" keeps its pre-#5079 meaning so existing configs migrate unchanged. diff --git a/src/plugin.ts b/src/plugin.ts index d58d0ffa8b..7c3156a025 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -2814,6 +2814,13 @@ export async function pipePluginChatWithStrip( // #5951: the requesting host already classifies this cut and retries on its // own budget — the proxy must not spend a second one. hostOwnsTruncationRecovery = false, + // #4913: how an EXHAUSTED degenerate-turn retry (the second attempt also + // ended with no usable output) is terminated — "passthrough" passes the + // empty turn through as a normal completion (pre-#870, the shape the + // proxy lane and the responses wire already take); "error" (default, + // = omitted) emits the #870 in-band stream error. Threaded from + // ProxyOptions.degenerateTurn (compat.degenerateTurn / BILI_DEGENERATE_TURN). + degenerateTurn?: "error" | "passthrough", ): Promise { let reader = stream.getReader(); let decoder = new TextDecoder("utf-8"); @@ -3027,11 +3034,45 @@ export async function pipePluginChatWithStrip( return false; } if (res.destroyed || res.writableEnded) return false; + // A turn the model left genuinely bare — no thought, no stripped echo, + // no released markup — is the upstream's own empty answer, not a stall: + // re-issuing it double-bills an empty completion (#732/#821 keep the + // same boundary in the compress loop). A draft-tail turn is NOT bare: + // it delivered a full handoff draft, which is precisely the stall signal. + // #4913: this gate must run BEFORE the exhausted-retry branch below — + // it was written under it, where a spent retry budget made it + // unreachable, so a retry attempt the model left genuinely bare died + // as a fatal in-band error instead of taking the pass-through #2756 + // documents for the same shape on the first pass. On the retry pass + // the per-attempt accumulators were reset when the retry took over + // (below), so this measures THIS attempt, not signals inherited from + // the first. + if (!sawThinking && !sawStrippedEcho && releasedMarkupChars === 0 && !stalledTail) { + log?.(degenerateRetried + ? `[plugin] degenerate terminal turn not retried (bare on the retry pass: no thinking, no stripped echo, no released markup): visibleTextChars=${visibleTextChars}, releasedMarkupChars=${releasedMarkupChars} (#2756/#4913) — passing the empty turn through` + : `[plugin] degenerate terminal turn not retried (bare: no thinking, no stripped echo, no released markup): visibleTextChars=${visibleTextChars}, releasedMarkupChars=${releasedMarkupChars} (#2756)`); + return false; + } if (degenerateRetried) { - // The retry degenerated too. An empty turn is indistinguishable from a - // model that produced nothing and the session reads as idle while it is - // dead, so the client gets an error the host would never surface (#870). - log?.("[plugin] degenerate terminal turn again after the retry; emitting an in-band error (#870)"); + // The retry degenerated too, and it was NOT bare (the gate above): + // this attempt really did produce thinking or stripped output and + // still ended with nothing the host can act on. Default terminal: + // an in-band error the host would never surface on its own — an + // empty turn is indistinguishable from a model that produced + // nothing and the session reads as idle while it is dead (#870). + // #4913: compat.degenerateTurn="passthrough" (env BILI_DEGENERATE_TURN + // wins) opts a host back into the pre-#870 shape — the empty turn + // passes through as a normal completion, the same terminal the + // proxy lane and the responses wire already take for this + // condition (they never had this fatal branch). + if (degenerateTurn === "passthrough") { + log?.(`[plugin] degenerate terminal turn again after the retry: passing the empty turn through (compat.degenerateTurn="passthrough", #4913): sawThinking=${sawThinking}, sawStrippedEcho=${sawStrippedEcho}, releasedMarkupChars=${releasedMarkupChars}, stalledTail=${stalledTail}, visibleTextChars=${visibleTextChars}, answerChars=${answerChars}, finishReason=${reason}`); + return false; + } + // #4913: name the signal that qualified the attempt. The + // accumulators now measure this attempt only (reset below when the + // retry takes over), so "again" is measured, not inherited. + log?.(`[plugin] degenerate terminal turn again after the retry; emitting an in-band error (#870): sawThinking=${sawThinking}, sawStrippedEcho=${sawStrippedEcho}, releasedMarkupChars=${releasedMarkupChars}, stalledTail=${stalledTail}, visibleTextChars=${visibleTextChars}, answerChars=${answerChars}, finishReason=${reason}`); // #5958: the terminal shape follows the configured streamErrorShape // (default protocol → a native error frame the host records as a // failure) instead of the old hard-wired completed-turn shape, which @@ -3044,15 +3085,6 @@ export async function pipePluginChatWithStrip( emitStreamError(res, protocol, "the turn degenerated again after the continuation nudge", undefined, streamErrorShape, { blockIndex: blocksForwarded, messageStarted: sawMessageStart }); return true; } - // A turn the model left genuinely bare — no thought, no stripped echo, - // no released markup — is the upstream's own empty answer, not a stall: - // re-issuing it double-bills an empty completion (#732/#821 keep the - // same boundary in the compress loop). A draft-tail turn is NOT bare: - // it delivered a full handoff draft, which is precisely the stall signal. - if (!sawThinking && !sawStrippedEcho && releasedMarkupChars === 0 && !stalledTail) { - log?.(`[plugin] degenerate terminal turn not retried (bare: no thinking, no stripped echo, no released markup): visibleTextChars=${visibleTextChars}, releasedMarkupChars=${releasedMarkupChars} (#2756)`); - return false; - } degenerateRetried = true; log?.(announceTail ? "[plugin] terminal turn is a bare announcement (ends mid-promise, no tool call); retrying once with a continuation nudge (#3905)" @@ -3076,6 +3108,21 @@ export async function pipePluginChatWithStrip( // lastChunkMeta.finishReason by design, so a mid-retry flush would // otherwise hand the client a chunk carrying the stale reason. delete lastChunkMeta["finishReason"]; + // #4913: per-attempt observability accumulators belong to the attempt + // they were set on. Without this reset the retry pass inherits the + // first attempt's signals (its thinking, its stripped echo, its + // released markup), so "degenerated again" reports the FIRST + // attempt's activity and the bare gate above false-qualifies a retry + // the model left bare. proseAcc deliberately keeps all attempts: the + // #361 tool-call-XML warn and the #3456 phantom-attachment scan are + // per-request by design; diag*/blocksForwarded/seenToolCalls are + // stream-level and stay untouched. + sawThinking = false; + sawStrippedEcho = false; + sawToolUse = false; + visibleTextChars = 0; + answerProse = ""; + releasedMarkupChars = 0; retryIndexOffset = blocksForwarded; inRetry = true; // The first attempt's held filter state belongs to text the client never diff --git a/src/server/relay.ts b/src/server/relay.ts index 0bc270a470..cadff3e5c1 100644 --- a/src/server/relay.ts +++ b/src/server/relay.ts @@ -2412,6 +2412,7 @@ const reply = prepared && !prepared.sidePassthrough ? createHandoffReply(prepare reply, opts.streamErrorShape, hostOwnsTruncationRecovery, + opts.degenerateTurn, ); } } else { @@ -2637,6 +2638,7 @@ const reply = prepared && !prepared.sidePassthrough ? createHandoffReply(prepare reply, opts.streamErrorShape, hostOwnsTruncationRecovery, + opts.degenerateTurn, ); } } else if ( diff --git a/tests/issue2929-codex-fold-double-miss.test.ts b/tests/issue2929-codex-fold-double-miss.test.ts index 81b61ca727..7419629dc1 100644 --- a/tests/issue2929-codex-fold-double-miss.test.ts +++ b/tests/issue2929-codex-fold-double-miss.test.ts @@ -34,16 +34,17 @@ type Item = Record; const SUMMARY_MARKER = "[Compressed conversation section]"; const NUDGE_MARKER = "Compressible ranges ("; -// Indices verified against the kernel's nudge gate with nudgeGrowthTokens=2000 -// and ~9KiB filler turns. Pre-#4521 (master) the injections landed on -// requests {7,8,9}; since #4521 the armed-but-silent status line rides an -// ephemeral carrier on the gated turns and its shown-marker feeds the nudge -// gate back, so the schedule shifts to {4,6,8,9} — the fold/proxy-tool-round -// mechanics under test are unchanged, only this probe's anchor re-calibrates -// to the next nudge-carrying request pair (6 → tool round, 7 → fold round). -const PROXY_TOOL_AT = 6; // upstream request index whose response = acp_status call (round 1) -const FOLD_AT = 7; // upstream request index whose response = compress call (round 2) -// FOLD_AT+1 = post-fold refreshed re-request (round 3); FOLD_AT+2 = next steady client turn. +// The fold turn is materialized SCHEDULE-INDEPENDENTLY: the fake upstream +// arms on the first request carrying the ephemeral nudge (with >=11 tagged +// refs to fold) and folds on the re-request that follows the acp_status +// round. A hardcoded request-index anchor broke every time the nudge gate's +// token schedule shifted — #4521's status-line feedback ({7,8,9} → {4,6,8,9}), +// #6928's status-line removal, and #4313's timestamp-rendering default flip +// (the suite preload pin BILI_MESSAGE_TIMESTAMPS="0" changes the wire shape +// and hence the schedule: OFF {4,13} vs ON {3,5,11,14} — direct local runs +// without the preload diverge from CI). The probe also pins +// compress.messageTimestamps:false so its wire shape is hermetic regardless +// of how the suite is launched. const TOTAL_TURNS = 13; const FILLER = (seed: number, kb: number): string => { @@ -120,6 +121,13 @@ test("#2929: nudge + proxy-tool-round fold keeps re-request/next-turn byte-stabl try { const captured: Array<{ url: string; body: string }> = []; + // Object (not bare lets) so the outer-scope reads aren't narrowed to + // the initial "idle" — the mutations happen inside the request callback. + const fold = { + state: "idle" as "idle" | "armed" | "folded", + armIdx: -1, // upstream request index that carried the nudge (acp_status round) + foldIdx: -1, // upstream request index that carried the compress call + }; upstream = http.createServer((req, res) => { const chunks: Buffer[] = []; req.on("data", (c: Buffer) => chunks.push(c)); @@ -127,15 +135,21 @@ test("#2929: nudge + proxy-tool-round fold keeps re-request/next-turn byte-stabl const idx = captured.length; const body = Buffer.concat(chunks).toString("utf8"); captured.push({ url: req.url ?? "", body }); - if (idx === PROXY_TOOL_AT) { - // Round 1 of the fold turn: model asks for proxy status — the - // loop executes it locally and re-requests (round 2). + const input = (JSON.parse(body) as { input?: Item[] }).input ?? []; + if (fold.state === "idle" && hasNudge(input) && refsOf(input).length >= 11) { + // Round 1 of the fold turn: the first nudge-carrying request + // with enough refs — model asks for proxy status, the loop + // executes it locally and re-requests (round 2). + fold.state = "armed"; + fold.armIdx = idx; functionCallSse(res, `resp_${idx}`, "acp_status", "{}", `call_st_${idx}`); return; } - if (idx === FOLD_AT) { - const prev = (JSON.parse(captured[idx - 1]!.body) as { input?: Item[] }).input ?? []; - const uniq = refsOf(prev); + if (fold.state === "armed") { + // Round 2: the re-request after the acp_status round — fold. + fold.state = "folded"; + fold.foldIdx = idx; + const uniq = refsOf(input); assert.ok(uniq.length >= 11, `fold round: expected >=11 tagged refs, saw ${uniq.length}`); const args = JSON.stringify({ content: [ { startId: uniq[3]!, endId: uniq[5]!, topic: "F1A", summary: `F1A summary: ${FILLER(1, 1)}` }, @@ -144,10 +158,9 @@ test("#2929: nudge + proxy-tool-round fold keeps re-request/next-turn byte-stabl functionCallSse(res, `resp_${idx}`, "compress", args, `call_cmp_${idx}`); return; } - const parsed = JSON.parse(body) as { input?: Item[] }; let label = "0"; - for (let i = (parsed.input ?? []).length - 1; i >= 0; i--) { - const it = parsed.input![i]!; + for (let i = input.length - 1; i >= 0; i--) { + const it = input[i]!; if (it.type === "message" && it.role === "user" && typeof it.content === "string") { const m = (it.content as string).match(/Turn (\d+):/); if (m) { label = m[1]!; break; } @@ -169,7 +182,7 @@ test("#2929: nudge + proxy-tool-round fold keeps re-request/next-turn byte-stabl routes: { [`http://127.0.0.1:${upstreamPort}`]: { models: { "gpt-test": { context: 200_000 } } } }, modelContextLimit: 200_000, kernelConfig: defaultConfig(200_000), - compress: { injectTool: true, injectNudge: true, nudgeGrowthTokens: 2000 }, + compress: { injectTool: true, injectNudge: true, nudgeGrowthTokens: 2000, messageTimestamps: false }, promptCache: { routing: "auto" }, sessionHeader: "x-acp-session", log: true, @@ -223,17 +236,18 @@ test("#2929: nudge + proxy-tool-round fold keeps re-request/next-turn byte-stabl } const inputs = captured.map((c) => (JSON.parse(c.body) as { input?: Item[] }).input ?? []); - assert.ok(inputs.length >= FOLD_AT + 3, `expected >= ${FOLD_AT + 3} upstream requests, got ${inputs.length}`); + assert.ok(fold.state === "folded", `scenario miss: the nudge never fired on a request with >=11 refs — probe cannot materialize the #2929 trigger; adjust nudgeGrowthTokens/filler`); + assert.ok(inputs.length >= fold.foldIdx + 3, `expected >= ${fold.foldIdx + 3} upstream requests, got ${inputs.length}`); // (0) Scenario materialization: the nudge must have been injected into - // the PRE-FOLD original request (production shape: nudge armed -> model + // the arming (pre-fold) request (production shape: nudge armed -> model // calls proxy tool -> compress). Without it this probe does not cover // the #2929 trigger. - assert.ok(hasNudge(inputs[PROXY_TOOL_AT]!), `scenario miss: no ephemeral nudge in the pre-fold request (inputs[${PROXY_TOOL_AT}]) — probe does not cover the production trigger; adjust nudgeGrowthTokens/filler`); - console.log(`probe: nudge confirmed in pre-fold request; total upstream requests=${inputs.length}`); + assert.ok(hasNudge(inputs[fold.armIdx]!), `scenario miss: no ephemeral nudge in the arming request (inputs[${fold.armIdx}]) — probe does not cover the production trigger`); + console.log(`probe: nudge at inputs[${fold.armIdx}], fold at inputs[${fold.foldIdx}]; total upstream requests=${inputs.length}`); // (1) The post-fold re-request carries the in-place summary(s). - const rPost = inputs[FOLD_AT + 1]!; + const rPost = inputs[fold.foldIdx + 1]!; const postSums = summaryIndices(rPost); assert.ok(postSums.length >= 1, "post-fold re-request must carry the in-place summary"); @@ -241,7 +255,7 @@ test("#2929: nudge + proxy-tool-round fold keeps re-request/next-turn byte-stabl // the post-fold re-request up to and including the summary anchor. In // production this is where the chain breaks (next turn hits only the // instructions baseline). - const next = inputs[FOLD_AT + 2]!; + const next = inputs[fold.foldIdx + 2]!; const nextSums = summaryIndices(next); assert.ok(nextSums.length >= 1, `next steady turn lost the summary entirely (summaries: ${nextSums.length}) — fold did not survive to the client turn`); assert.equal(nextSums[0], postSums[0], `summary anchor drifted: re-request item[${postSums[0]}] vs next turn item[${nextSums[0]}]`); diff --git a/tests/plugin-empty-turn-retry.test.ts b/tests/plugin-empty-turn-retry.test.ts index cf3625956a..353bd74abe 100644 --- a/tests/plugin-empty-turn-retry.test.ts +++ b/tests/plugin-empty-turn-retry.test.ts @@ -1,9 +1,13 @@ import { test } from "node:test"; import assert from "node:assert/strict"; import { pipePluginChatWithStrip, pipePluginResponsesWithStrip } from "../src/plugin.ts"; +import { loadOptions } from "../src/config.ts"; import { setLogCapture } from "../src/logger.ts"; import { DEGENERATE_RETRY_NUDGE, injectContinuationNudge } from "../src/degenerate-retry.ts"; import type { Session } from "../src/session.ts"; +import { mkdtempSync, writeFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; // The plugin pipe is what serves plugin-mode agents (this machine's omp // sessions among them). A turn whose ONLY text is an echoed render tag is @@ -464,10 +468,30 @@ test("plugin chat retries a turn whose only visible output was an unclosed rende ); }); +/** The #4913 production shape (issue dataset: 13/13 double-degenerates were + * thinking-only): the model emits only reasoning, then ends cleanly — no + * answer prose, no tool call, no stripped echo. */ +function thinkingOnlyTurn(text = "The retry still only thought."): string[] { + return [chatChunk({ role: "assistant" }), chatChunk({ reasoning_content: text }), chatStop(), DONE]; +} + test("plugin chat emits an in-band error when the retry degenerates too", async () => { const out: string[] = []; - const refetch = () => Promise.resolve(streamOf([chatChunk({ role: "assistant" }), chatStop(), DONE])); - await pipePluginChatWithStrip(streamOf(unclosedEchoTurn()), makeRes(out), "openai", makeSession(), undefined, refetch); + const logs: string[] = []; + setLogCapture((_level, msg) => { + logs.push(msg); + }); + // #4913 re-pin: the old pin used a truly BARE second attempt, which is + // exactly the shape #2756 documents as pass-through — the fix below now + // gives it that, so the fatal branch is pinned with the production shape + // instead (issue dataset: every double-degenerate second attempt carried + // thinking). + const refetch = () => Promise.resolve(streamOf(thinkingOnlyTurn())); + try { + await pipePluginChatWithStrip(streamOf(unclosedEchoTurn()), makeRes(out), "openai", makeSession(), (msg) => logs.push(msg), refetch); + } finally { + setLogCapture(null); + } const text = out.join(""); // #5958: an exhausted retry is a FAILURE, not a completed turn. The default // streamErrorShape is "protocol", so the client gets the wire-native error @@ -479,11 +503,93 @@ test("plugin chat emits an in-band error when the retry degenerates too", async // The error's own terminal plus the retry stream's trailing terminator both // close the turn; the client stops at the error either way. assert.equal((text.match(/\[DONE\]/g) ?? []).length, 2, "the error's terminal, then the retry's trailing terminator"); + // #4913 item 3: the fatal log names the signal that qualified the attempt, + // measured on the RETRY pass (accumulators are reset when the retry takes + // over), not inherited from the first attempt. + const fatal = logs.find((l) => l.includes("again after the retry")); + assert.ok(fatal, `the fatal retry log is present, got: ${JSON.stringify(logs)}`); + assert.ok(fatal.includes("sawThinking=true"), `the qualifying signal is named, got: ${fatal}`); + assert.ok(fatal.includes("releasedMarkupChars=0"), "the first attempt's released markup is not inherited into the retry's verdict"); +}); + +test("plugin chat: a retry attempt the model left genuinely bare passes through instead of dying (#4913)", async () => { + const out: string[] = []; + const logs: string[] = []; + setLogCapture((_level, msg) => { + logs.push(msg); + }); + let calls = 0; + const refetch = () => { + calls += 1; + return Promise.resolve(streamOf([chatChunk({ role: "assistant" }), chatStop(), DONE])); + }; + try { + await pipePluginChatWithStrip(streamOf(unclosedEchoTurn()), makeRes(out), "openai", makeSession(), (msg) => logs.push(msg), refetch); + } finally { + setLogCapture(null); + } + const text = out.join(""); + assert.equal(calls, 1, "the first attempt is still retried once"); + // Before the fix this shape died as a fatal in-band error: the #2756 bare + // exemption sat under the exhausted-retry branch and was unreachable on + // the second pass. It now takes the same pass-through as the same shape + // on the first pass — the upstream's own empty answer, not a proxy-invented + // failure. + assert.ok(!text.includes("stream_error"), "no protocol error frame for a bare second attempt"); + assert.ok(!text.includes("[ACP] stream error"), "no completed-turn error frame for a bare second attempt"); + assert.ok(text.includes('"finish_reason":"stop"'), "the turn completes as an (empty) answer"); + assert.equal((text.match(/\[DONE\]/g) ?? []).length, 1, "a single terminal closes the turn"); + const bare = logs.find((l) => l.includes("bare on the retry pass")); + assert.ok(bare, `the bare-on-retry log is present, got: ${JSON.stringify(logs)}`); + assert.ok(!logs.some((l) => l.includes("again after the retry")), "no fatal verdict for a bare second attempt"); +}); + +test("plugin chat (chat wire): a thinking-only second attempt dies with the qualifying signal logged (#4913)", async () => { + const out: string[] = []; + const logs: string[] = []; + setLogCapture((_level, msg) => { + logs.push(msg); + }); + let calls = 0; + const refetch = () => { + calls += 1; + return Promise.resolve(streamOf(thinkingOnlyTurn("second attempt thought again"))); + }; + try { + await pipePluginChatWithStrip(streamOf(thinkingOnlyTurn("first attempt thought")), makeRes(out), "openai", makeSession(), (msg) => logs.push(msg), refetch); + } finally { + setLogCapture(null); + } + const text = out.join(""); + assert.equal(calls, 1, "one retry, then the fatal verdict"); + assert.ok(text.includes('"code":"stream_error"'), "the #870 in-band failure is emitted"); + const fatal = logs.find((l) => l.includes("again after the retry")); + assert.ok(fatal, `the fatal retry log is present, got: ${JSON.stringify(logs)}`); + assert.ok(fatal.includes("sawThinking=true"), `the retry's own thinking qualifies the verdict, got: ${fatal}`); + assert.ok(!fatal.includes("first attempt thought"), "the verdict is measured, not inherited from the first attempt's bytes"); + assert.ok(fatal.includes("visibleTextChars=0") && fatal.includes("answerChars=0"), `the verdict carries the empty-shape counters, got: ${fatal}`); +}); + +test("plugin chat: a healthy second attempt after a degenerate first completes cleanly", async () => { + const out: string[] = []; + let calls = 0; + const refetch = () => { + calls += 1; + return Promise.resolve(streamOf(proseTurn("the answer arrives on the retry"))); + }; + await pipePluginChatWithStrip(streamOf(thinkingOnlyTurn()), makeRes(out), "openai", makeSession(), undefined, refetch); + const text = out.join(""); + assert.equal(calls, 1, "the degenerate first attempt is retried"); + assert.ok(!text.includes("stream_error"), "a recovered turn carries no error"); + assert.ok(textDeltas(text, "openai").endsWith("the answer arrives on the retry"), "the retry's answer reaches the client"); + assert.ok(text.includes('"finish_reason":"stop"'), "the recovered turn completes normally"); }); test("plugin chat keeps the legacy completed-turn shape when streamErrorShape is \"completion\"", async () => { const out: string[] = []; - const refetch = () => Promise.resolve(streamOf([chatChunk({ role: "assistant" }), chatStop(), DONE])); + // #4913 re-pin: a bare second attempt now passes through, so the legacy + // error shape is pinned with the thinking-only (production) second attempt. + const refetch = () => Promise.resolve(streamOf(thinkingOnlyTurn())); await pipePluginChatWithStrip( streamOf(unclosedEchoTurn()), makeRes(out), "openai", makeSession(), undefined, refetch, undefined, undefined, undefined, undefined, undefined, "completion", @@ -573,3 +679,98 @@ test("plugin chat (anthropic) defaults to a native error event, not a synthetic assert.ok(text.includes('"code":"stream_error"'), "the error carries the stream_error code"); assert.ok(!text.includes("[ACP] stream error"), "no synthetic completed-turn error block by default"); }); + +// #4913: compat.degenerateTurn="passthrough" (env BILI_DEGENERATE_TURN wins) +// opts the chat lane back into the pre-#870 terminal for an EXHAUSTED +// degenerate-turn retry — the empty turn passes through as a normal completion +// instead of the fatal in-band error. Only the chat pipe has the fatal branch; +// the proxy lane and responses wire already pass this condition through. +test("plugin chat: an exhausted degenerate retry passes through when degenerateTurn=passthrough (#4913)", async () => { + const out: string[] = []; + const logs: string[] = []; + let calls = 0; + const refetch = () => { + calls += 1; + return Promise.resolve(streamOf(thinkingOnlyTurn("second attempt thought again"))); + }; + await pipePluginChatWithStrip( + streamOf(thinkingOnlyTurn("first attempt thought")), + makeRes(out), + "openai", + makeSession(), + (msg) => logs.push(msg), + refetch, + undefined, + undefined, + undefined, + undefined, + undefined, + undefined, + false, + "passthrough", + ); + const text = out.join(""); + assert.equal(calls, 1, "the degenerate first attempt is retried once"); + assert.ok(!text.includes("stream_error"), "passthrough mode carries no in-band error"); + assert.ok(text.includes('"finish_reason":"stop"'), "the empty turn passes through as a normal completion"); + const passthrough = logs.find((l) => l.includes('compat.degenerateTurn="passthrough"')); + assert.ok(passthrough, `the passthrough verdict is logged with the counters, got: ${JSON.stringify(logs)}`); + assert.ok(passthrough.includes("sawThinking=true"), `the logged signal is the retry's own thinking, got: ${passthrough}`); + assert.ok(!logs.some((l) => l.includes("emitting an in-band error")), "no fatal branch ran"); +}); + +test("plugin chat: an exhausted degenerate retry still dies when degenerateTurn=error is explicit (#4913)", async () => { + const out: string[] = []; + let calls = 0; + const refetch = () => { + calls += 1; + return Promise.resolve(streamOf(thinkingOnlyTurn("second attempt thought again"))); + }; + await pipePluginChatWithStrip( + streamOf(thinkingOnlyTurn("first attempt thought")), + makeRes(out), + "openai", + makeSession(), + undefined, + refetch, + undefined, + undefined, + undefined, + undefined, + undefined, + undefined, + false, + "error", + ); + assert.equal(calls, 1); + assert.ok(out.join("").includes('"code":"stream_error"'), "the explicit error value keeps the #870 in-band failure"); +}); + +// #4913 config wiring: file compat.degenerateTurn + env BILI_DEGENERATE_TURN, +// env > file > default("error"), unknown values fall back to the default. +test("config: compat.degenerateTurn resolves env > file > default (#4913)", () => { + const dir = mkdtempSync(path.join(tmpdir(), "bili-4913-")); + const cfg = path.join(dir, "config.json"); + try { + const prevFile = process.env["BILI_CONFIG_FILE"]; + const prevEnv = process.env["BILI_DEGENERATE_TURN"]; + try { + process.env["BILI_CONFIG_FILE"] = cfg; + writeFileSync(cfg, JSON.stringify({ compat: { degenerateTurn: "passthrough" } })); + assert.equal(loadOptions({}).degenerateTurn, "passthrough", "the file value applies"); + writeFileSync(cfg, JSON.stringify({ compat: { degenerateTurn: "error" } })); + assert.equal(loadOptions({}).degenerateTurn, "error", "error value parses"); + assert.equal(loadOptions({ BILI_DEGENERATE_TURN: "passthrough" }).degenerateTurn, "passthrough", "env wins over the file"); + assert.equal(loadOptions({ BILI_DEGENERATE_TURN: "error" }).degenerateTurn, "error", "env error wins"); + writeFileSync(cfg, JSON.stringify({ compat: { degenerateTurn: "bogus" } })); + assert.equal(loadOptions({}).degenerateTurn, "error", "unknown file values fall back to the default"); + writeFileSync(cfg, JSON.stringify({})); + assert.equal(loadOptions({}).degenerateTurn, "error", "absent value defaults to error (status quo)"); + } finally { + if (prevFile === undefined) delete process.env["BILI_CONFIG_FILE"]; else process.env["BILI_CONFIG_FILE"] = prevFile; + if (prevEnv === undefined) delete process.env["BILI_DEGENERATE_TURN"]; else process.env["BILI_DEGENERATE_TURN"] = prevEnv; + } + } finally { + rmSync(dir, { recursive: true, force: true }); + } +}); diff --git a/website/config-reference/server.yaml b/website/config-reference/server.yaml index d05c9e7e50..35a200ffaf 100644 --- a/website/config-reference/server.yaml +++ b/website/config-reference/server.yaml @@ -407,6 +407,14 @@ entries: desc_en: "How upstream stream failures are presented after the 200 is committed: protocol-native error frames (default) or the legacy synthesized-completion shape." desc_zh: "200 已提交后上游流失败的呈现方式:协议原生错误帧(默认)或旧版合成完成形态。" desc_ja: "200 がコミットされた後、上流ストリーム失敗がどのように提示されるか:プロトコルネイティブのエラーフレーム(デフォルト)またはレガシーの合成完了形状。" + - key: compat.degenerateTurn + type: "\"error\" | \"passthrough\"" + default: "error" + env: BILI_DEGENERATE_TURN + group: behavior + desc_en: "Terminal for the plugin chat pipe when the degenerate-turn retry ALSO ends with no usable output (#4913): in-band stream error (default, #870) or the empty turn passed through as a normal completion (pre-#870)." + desc_zh: "plugin chat 管道的退化回合重试后仍无可用输出时的终局(#4913):带内流错误(默认,#870)或把空回合作为正常完成放行(pre-#870)。" + desc_ja: "プラグインチャットパイプで退化ターンのリトライ後も利用可能な出力がゼロだった場合の終了処理(#4913):インバンドストリームエラー(デフォルト、#870)または空ターンを通常の完了として通過させる(#870 以前)。" - key: compat.noCacheControl type: boolean default: "false"