@jsonstudio/rcc 0.89.1205 → 0.89.1457

package/docs/VIRTUAL_ROUTER_PRIORITY_AND_HEALTH.md

@@ -0,0 +1,125 @@
+# Virtual Router: Priority + Health-Weighted Selection
+
+This document describes how RouteCodex/llmswitch-core selects a `providerKey` from a route pool, with emphasis on:
+
+- `mode: "priority"` pools (strict priority, failover only when needed)
+- `mode: "round-robin"` pools (health-weighted AWRR)
+- How quota/health signals affect selection order and weights
+
+## Terms
+
+- **providerKey**: `providerId.<keyAlias>.<modelId>` (example: `antigravity.gbplasu1.claude-sonnet-4-5-thinking`)
+- **pool**: A `RoutePoolTier` (`routing.<routeName>[]`), containing `targets` and a `mode`
+- **quotaView**: Host-injected view (`ProviderQuotaView`) that provides:
+  - `inPool`, `cooldownUntil`, `blacklistUntil`
+  - `priorityTier` (static)
+  - `selectionPenalty`, `lastErrorAtMs`, `consecutiveErrorCount` (soft health signals)
+
+## Priority Pools (`mode: "priority"`)
+
+Goal: always use the highest-priority candidate first, and only fall back when the current best becomes unavailable.
+
+### Base priority (config order)
+
+When targets do not carry explicit per-target priority metadata at runtime, the router derives a deterministic base score from the target list ordering:
+
+- Treat each contiguous `(providerId, modelId)` block in `tier.targets` as a **target group**
+  - This matches how `bootstrapVirtualRouterConfig()` expands a single routing entry into multiple auth aliases
+- Group base scores: `100, 90, 80, ...` (step `10`) by appearance order
+- Inside a group (different aliases for the same provider+model), alias scores: `100, 99, 98, ...` (step `1`)
+
+This makes it difficult for a single transient failure to instantly flip priority to the next target, while still allowing repeated errors to degrade a key.
+
+### Error priority penalty (soft)
+
+If `quotaView` provides `selectionPenalty` for a key, priority selection subtracts it from the derived base score:
+
+```
+effectivePriority = basePriority - selectionPenalty
+```
+
+`selectionPenalty` is produced by the host quota daemon:
+
+- `selectionPenalty = consecutiveErrorCount` when the last error is within `ROUTECODEX_QUOTA_ERROR_PRIORITY_WINDOW_MS` (default `10min`)
+- Resets to `0` on a successful response
+
+This is a *soft* preference signal (it does not exclude the key); exclusion is controlled by `inPool/cooldownUntil/blacklistUntil`.
+
+### What “exhausted” means
+
+In priority mode, a higher-priority key is considered exhausted only when it is **not selectable** due to:
+
+- health manager unavailable (tripped/cooldown)
+- quotaView exclusion (`inPool=false` / active `cooldownUntil` / active `blacklistUntil`)
+- routing instructions / user exclusions
+
+Only then will routing advance to the next candidate in priority order.
+
+## Round-Robin Pools (`mode: "round-robin"`) — Health-Weighted AWRR
+
+Goal: evenly distribute traffic across healthy keys, while reducing the hit rate of recently failing keys (without starving them).
+
+Implementation: deterministic smooth weighted round-robin (no randomness).
+
+### Health-weighted weights (AWRR)
+
+If enabled (`loadBalancing.healthWeighted.enabled=true`) and `quotaView` provides error metadata, the router computes:
+
+- `weight = baseWeight * multiplier`
+- `multiplier` decreases with `consecutiveErrorCount`
+- `multiplier` recovers over time using exponential decay (half-life)
+- `multiplier` is floored by `minMultiplier` (prevents starvation)
+
+Defaults live in:
+
+- `sharedmodule/llmswitch-core/src/router/virtual-router/health-weighted.ts`
+
+Key knobs (configurable under `loadBalancing.healthWeighted`):
+
+- `baseWeight` (default `100`)
+- `minMultiplier` (default `0.5`)
+- `beta` (default `0.1`) — one error reduces weight by ~10%
+- `halfLifeMs` (default `10min`)
+- `recoverToBestOnRetry` — on router retries, prefer the healthiest key first
+
+## Model-capacity 429 handling (host quota)
+
+Some upstreams report `HTTP 429` with capacity semantics (e.g. “No capacity available for model …”).
+This is not “quota depleted” locally; switching keys often does not help.
+
+RouteCodex treats this as a *model-series* cooldown:
+
+- On capacity-exhausted 429, host applies an immediate cooldown to the entire `${providerId}.${modelId}` series
+- Default cooldown: `60s`
+
+Implementation:
+
+- `src/manager/modules/quota/provider-quota-daemon.model-backoff.ts`
+
+## Context-weighted selection (preserve large windows)
+
+Some clients have a fixed maximum usable context (e.g. `200k`). When multiple candidates are all "safe" for the current
+request, we want to bias traffic toward smaller effective safe windows early, so that larger windows remain available
+later when context grows.
+
+This is implemented as an additional multiplier on top of existing weights (health-weighted / legacy), and is only
+applied inside the same pool bucket and only for candidates in `ContextAdvisor.safe`.
+
+Config (under `virtualrouter.loadBalancing.contextWeighted`):
+
+- `enabled` (default `false`)
+- `clientCapTokens` (default `200000`)
+- `gamma` (default `1`, proportional compensation)
+- `maxMultiplier` (default `2`)
+
+Effective safe window (`T_safeEff`) used for compensation:
+
+- `T_eff = min(modelMaxTokens, clientCapTokens)`
+- `reserve = ceil(T_eff * (1 - warnRatio))` (warnRatio comes from `virtualrouter.contextRouting.warnRatio`, default `0.9`)
+- `slack = max(0, modelMaxTokens - clientCapTokens)`
+- `reserveEff = max(0, reserve - slack)` (models with slack can "absorb" the reserve)
+- `T_safeEff = T_eff - reserveEff`
+
+Then, within the bucket:
+
+- `multiplier = min(maxMultiplier, (max(T_safeEff) / T_safeEff) ^ gamma)`

package/docs/anthropic-request-golden-samples.md

@@ -0,0 +1,50 @@
+### Anthropic Golden Request Samples
+
+我们把真实 `/v1/messages` 请求快照统一保存在 `~/.routecodex/golden_samples/anthropic_requests/`，每个目录
+包含：
+
+```
+<slug>/
+  request_payload.json  # 直接发送给 Anthropics API 的 json
+  meta.json             # 来源阶段、采样说明、endpoint 等元数据
+```
+
+> **提示**：仓库内 `samples/chat-blackbox/anthropic/request-basic.json` 为上述样本的版本化拷贝，可在代码评审时直接 diff。
+> 建议先用真实 provider 生成阶段快照，并把 `body` + `stageFile` 写入
+> `~/.routecodex/golden_samples/new/anthropic-messages/<providerId>/`。随后执行
+> `node scripts/tools/capture-provider-goldens.mjs --update-golden`，脚本会读取这些快照并同步
+> `provider_golden_samples/`，检测到字段差异时会提示是否覆盖。
+
+当前样本：
+
+| slug | 描述 | Source Stage |
+|------|------|--------------|
+| `glm46-toolcall-20251209T223550158-010` | 用户让助手列出仓库目录，prompt 中包含 Codex/CLAUDE 大段 system 规则，`stream=true`，用于验证工具治理路径 | `anthropic-messages/req_1765290950164_req_inbound_stage1_format_parse.json` |
+| `glm46-toolcall-20251209T223550463-011` | 用户只说“列出本地文件”，模型应拒绝直接读取本地盘，适合验证拒绝/告警逻辑 | `anthropic-messages/req_1765290950463_req_inbound_stage1_format_parse.json` |
+
+#### 如何回放
+
+1. 启动 RouteCodex，确保目标 provider（例如 `glm.key1.glm-4.6`）可用。
+2. 直接将样本作为请求体发送：
+
+```bash
+curl -s http://127.0.0.1:5555/v1/messages \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer test' \
+  --data @~/.routecodex/golden_samples/anthropic_requests/glm46-toolcall-20251209T223550158-010/request_payload.json
+```
+
+3. 如果需要切换 provider，只需修改 JSON 中的 `model` 字段或配合用户配置热更（无需 CLI 抓样本）。
+
+#### 验证快照
+
+- 设置 `ROUTECODEX_HUB_SNAPSHOTS=1` 后回放，`~/.routecodex/codex-samples/anthropic-messages/` 将刷新对应的
+  `req_*` 与 `resp_*` 阶段文件，可直接 diff。
+- `anthropic/glm46-toolcall-…` 目录内已有响应黄金样本，可与请求目录交叉比对，确认入站/出站一致性。
+
+#### 扩展样本
+
+1. 捕获目标请求期间的 `req_*_req_inbound_stage1_format_parse.json`
+2. 在 `anthropic_requests/` 下创建新子目录，复制 `body.payload` 为 `request_payload.json`
+3. 写入 `meta.json` 说明模型、来源阶段、场景描述
+4. 更新本文档表格即可

package/docs/antigravity-gemini-format-cleanup.md

@@ -0,0 +1,102 @@
+---
+title: Antigravity Gemini 格式清理要求
+date: 2026-01-25
+tags:
+  - routecodex
+  - antigravity
+  - gemini
+  - claude
+status: active
+---
+
+# Antigravity Gemini 格式清理要求（gcli2api 对齐）
+
+> [!summary]
+> 本文汇总当前 **antigravity** 走 Gemini 协议时的格式清理要求，覆盖 **Gemini 系列** 与 **Claude 系列** 的关键输出/请求规范、UA/Headers 规范、工具历史一致性要求等。
+> 本次改动已生效：历史 `functionCall` 强制补 `thoughtSignature: "skip_thought_signature_validator"`。
+
+## 1) 适用范围
+- **Gemini 系列**：`gemini-3-pro-low / gemini-3-pro-high` 等 Gemini 协议模型。
+- **Claude 系列**：`claude-*` 走 antigravity/兼容层的 Gemini 路由时的兼容字段统一。
+
+---
+
+## 2) UA 与 Headers（gcli2api 对齐）
+- **User-Agent**：固定为 `gcloud-cli/1.11.3`（对齐 gcli2api 行为）。
+- **Headers 关键项**：
+  - `x-goog-api-client`: `gl-go/1.0.0 gccl/1.11.3`
+  - `x-goog-user-project`: 使用 `project`（保持与 gcli2api 一致）
+  - `x-goog-request-params`: `model=...`
+  - `x-client-request-id` + `x-goog-request-id`（使用 requestId/requestType 组合）
+- **Body 结构**：
+  - 仅保留 gcli2api 需要的最小字段集合
+  - **不带 sessionId**
+  - 保持 `contents / systemInstruction / safetySettings / generationConfig / tools` 的一致性顺序与结构
+
+---
+
+## 3) 工具与历史一致性（核心要求）
+
+> [!important]
+> **历史中出现的工具调用必须与当前请求 tools 对齐**。历史中不得出现当前 tools 列表中不存在的工具调用。
+
+- **历史工具清理**：
+  - 对 **history 中出现但当前 tools 不存在** 的 `functionCall`/`functionResponse` 做 **移除或降级为纯文本**。
+  - 保持 **tools 列表与历史工具调用**的 **一一对应**。
+- **工具名合法性**：
+  - Gemini 对函数名字符集/形状严格校验；不合法名称需 **清理或过滤**。
+- **工具 schema 对齐**：
+  - 历史 `functionCall.args` 必须与当前工具 schema 对齐。
+  - 对 `args` 做 **结构修正**：Gemini 期望 `functionCall.args` 为对象（Struct），非对象需包 `value`。
+
+---
+
+## 4) Gemini 协议的格式清理要点
+
+### 4.1 functionCall 历史补签名
+- **新增要求（已生效）**：
+  - 历史 `functionCall` **必须包含**：
+    - `thoughtSignature: "skip_thought_signature_validator"`
+  - 这是 gcli2api 的行为：即使没有真实签名，也需要该字段以通过 Cloud Code 严格校验。
+
+### 4.2 工具 schema 输出
+- **始终输出工具 schema**（Gemini 需要工具声明来校验 `functionCall`/`functionResponse`）。
+- `toolConfig.functionCallingConfig`：
+  - `NONE / ANY / ALLOWED` 按 `tool_choice` 映射。
+
+### 4.3 Content 清理
+- 统一 `contents` 结构，确保每条 entry 的 parts 合法。
+- 对无效 part 做降级或过滤，避免 Gemini 侧 malformed。
+
+---
+
+## 5) Claude 系列在 Antigravity 中的兼容统一
+
+- Claude-thinking / 非 thinking 输出在 antigravity 侧 **统一形态**：
+  - 保证与 Gemini/OpenAI 响应结构一致的 **content 形状**。
+- 保持 **history/tool 行为与 Gemini 同步**（同样遵循历史工具一致性要求）。
+
+---
+
+## 6) 当前已生效的关键修复
+
+- ✅ **历史 functionCall 强制补 `thoughtSignature`**（gcli2api 行为一致）。
+- ✅ **history/tool 对齐清理**：历史工具调用不再允许与当前 tools 不一致。
+- ✅ **args 结构修正**：非对象 args 包装到 `{ value }`。
+- ✅ **UA/Headers 与 gcli2api 对齐**（最小 body、requestId/requestType headers）。
+
+---
+
+## 7) 验证方式（建议）
+
+- 对比两条请求（首条无历史、次条带历史）：
+  - `provider-request.json` 中 **`functionCall` 必须带 `thoughtSignature`**。
+  - `tools` 与历史 functionCall **必须一一对齐**。
+  - `args` 必须为对象（Struct）。
+
+---
+
+## 8) 备注
+
+> [!note]
+> 本次修改已验证生效。若后续仍出现 429 或 Cloud Code 严格校验失败，优先检查 **history 中工具清理是否遗漏** 或 **functionCall/Response 的结构化字段是否存在差异**。

package/docs/antigravity-routing-contract.md

@@ -0,0 +1,31 @@
+# Antigravity 429 + sticky-queue contract (standard behavior)
+
+This document defines the *default* behavior for Antigravity routing under transient 429s. It is a hard requirement
+for the "standard" execution path; any alternative behavior is considered legacy compatibility.
+
+## Contract (3 rules)
+
+1) **Success sticks**  
+   Once an alias is selected for a `(providerId=antigravity, modelId)` group, routing keeps selecting that alias
+   until the alias becomes unavailable (error / cooldown / blacklist).
+
+2) **429 cools down + rotates to tail**  
+   For capacity-style 429s (e.g. upstream "model capacity exhausted"), routing:
+   - immediately applies a short cooldown to the failing `providerKey` (alias-level for Antigravity), and
+   - on retry, rotates the failing alias to the tail of the sticky-queue, so the next attempt prefers a different alias.
+
+3) **Fallback only when exhausted**  
+   Retrying stays within Antigravity for the same model as long as any usable alias remains.
+   Only when all aliases are excluded/cooling/blacklisted does routing fall back to other providers/routes.
+
+## Where this is implemented
+
+- **Retry hint plumbing (excludedProviderKeys)**: `src/server/runtime/http-server/request-executor.ts`
+- **Sticky-queue selection + alias rotation**:
+  - `sharedmodule/llmswitch-core/src/router/virtual-router/engine-selection/alias-selection.ts`
+  - `sharedmodule/llmswitch-core/src/router/virtual-router/engine-selection/tier-selection.ts`
+  - `sharedmodule/llmswitch-core/src/router/virtual-router/engine-selection/tier-selection-select.ts`
+- **Capacity-style 429 cooldown (alias-level for Antigravity)**:
+  - `src/manager/modules/quota/provider-quota-daemon.model-backoff.ts`
+  - `src/manager/modules/quota/provider-quota-daemon.events.ts`
+

package/docs/ccr-alignment-enhancetool.md

@@ -0,0 +1,105 @@
+# CCR enhancetool 行为与对齐方案（形状/语法修复，非语义重写）
+
+本文档总结了 claude-code-router（下称 CCR）中内置 transformer “enhancetool”的关键行为，并给出在 llmswitch-core 中实现等价对齐的方案。对齐范围严格限定为“整体形状/语法/JSON(JSON5) 层”，不解析或重写具体命令语义（如 grep 正则、管道策略等）。
+
+## 1. CCR enhancetool 行为摘要
+
+- 非流 JSON（application/json）
+  - 对 `choices[0].message.tool_calls[].function.arguments` 执行三段式容错修复：
+    1) 尝试 `JSON.parse` 成功 → 使用原字符串。
+    2) 失败则 `JSON5.parse` 成功 → `JSON.stringify` 输出合法 JSON 字符串。
+    3) 再失败则进行“安全修复”（典型策略：去除围栏标记、去掉尾随逗号、单引号转双引号、补齐引号/括号等），成功后 `JSON.stringify`。
+    4) 全部失败 → 回退为字符串 "{}"（空对象）。
+  - 若存在 `tool_calls`：标准化 `content=null`；无 `finish_reason` 时补齐为 `tool_calls`。
+
+- 流式（text/event-stream）
+  - 吞掉“工具参数增量”片段，不向下游透出 arguments 的碎片增量。
+  - 聚合策略：
+    - 记录工具调用开始（OpenAI Chat: `delta.tool_calls`；Anthropic Messages: `content_block_start` 等），保存 `index/name/id`。
+    - 聚合 `partial_json` / `function.arguments` 的增量数据到缓冲；不在增量阶段向下游发送 arguments 内容。
+    - 在工具完成时（OpenAI: `finish_reason=tool_calls`；Anthropic: `content_block_stop`）一次性下发：
+      - 将聚合后的 arguments 走上述“三段式容错修复”，最终保证为“单个 JSON 字符串”。
+      - 构造新的 delta（含完整 `name` 与 `arguments`），并删除任何同时出现的 `delta.content`。
+  - 思考文本（reasoning）在 CCR 中被专门转为 `thinking` 域；本轮对齐聚焦工具通路，不改变我们已存在的 reasoning 处理策略。
+
+- 不做的事
+  - 不解析或重写具体命令语义（不拆分正则、多 -e 重写、命令管道改写等）。
+  - 不注入系统提示词；仅允许在 tools schema 描述中加入“形状/用法提示”（非 system）。
+
+## 2. 我们的对齐原则（三端一致）
+
+1) 形状优先：仅保障 `function.arguments` 在所有输出路径上都是“单个 JSON 字符串”，并保持 `content=null`、`finish_reason=tool_calls` 等不变式。
+2) 三端统一：Chat（OpenAI）、Responses（OpenAI）、Messages（Anthropic）在非流与流式两条通路都执行一致策略。
+3) 不解析命令语义：不对 grep/正则/管道等进行语义重写，避免引入不可预测副作用。
+
+## 3. 对齐实施方案
+
+### 3.1 非流（一次性 JSON）
+
+- 入口：`llmswitch-core v2` 的响应治理（response 相位）。
+- 动作：
+  - 若 `function.arguments` 是对象 → 仅 `JSON.stringify`（保持语义原样）。
+  - 若是字符串 → 走 `repairArguments`（JSON→JSON5→安全修复→失败回退 "{}"）。
+  - 补齐 `finish_reason=tool_calls`（若缺），以及 `content=null`（当存在 `tool_calls`）。
+
+### 3.2 流式（SSE 聚合）
+
+- Chat（OpenAI /v1/chat/completions）：新增“Chat SSE 工具参数聚合器”。
+  - 吞掉增量 arguments，不向下游透出；工具完成时合并缓冲并 `repairArguments`，一次性发送完整字符串。
+
+- Messages（Anthropic /v1/messages）：新增“Messages SSE 工具参数聚合器”。
+  - 聚合 `input_json_delta.partial_json`；`content_block_stop` 时进行 `repairArguments` 并一次性下发。
+
+- Responses（OpenAI /v1/responses）：改造现有 `ResponsesSSETransformer` 为同策略。
+  - 工具参数不再逐片外发，仅在工具结束时一次性输出完整字符串。
+
+### 3.3 repairArguments（对齐 CCR，形状/语法修复）
+
+- 实现在 `shared/v2/conversion/shared/jsonish.ts`：
+  - `repairArguments(arg: unknown): string`：输入任意字符串/对象，输出“单个 JSON 字符串”。
+  - 顺序：`JSON.parse` → `JSON5.parse` → 安全修复（去围栏/尾逗号/单引号等）→ 失败返回 "{}"。
+  - 不触碰命令语义（值中的命令原封不动）。
+
+### 3.4 tools schema 描述增强（非 system 提示）
+
+- 在 `augmentOpenAITools` 的 `shell` 描述中追加“稳健用法提示”（仅描述层）：
+  - 长 OR 模式建议使用多个 `-e` 或 `-f`（从 stdin 读模式列表）。
+  - 可优先使用 `rg`（ripgrep）以减少引号/括号陷阱。
+  - 避免将解释性文字混入 `arguments`；说明性文字放在普通对话文本中。
+
+## 4. 开关与默认
+
+- `RCC_TOOL_ENHANCE=1`（默认开）：启用 `repairArguments` 三段式修复（失败回退 "{}"）。
+- `RCC_SSE_TOOL_AGGREGATE=1`（默认开）：吞掉参数增量，完结一次性下发完整 arguments。
+
+## 5. 快照与验收
+
+- 预期在 `*_provider-request.json`：
+  - `assistant.tool_calls[].function.arguments` 均为合法 JSON 字符串；
+  - 当有 `tool_calls` 时，`content=null`，`finish_reason='tool_calls'`；
+  - 无 arguments 增量碎片。
+
+- SSE：不再透出 arguments 增量；仅在工具完成时出现一次完整 arguments。
+
+- 失败回退：当 JSON/JSON5/修复全部失败时，arguments 应为 "{}"。
+
+## 6. 边界与不做项
+
+- 不解析或重写具体命令语义（例如：不拆分大正则为多 `-e`，不重排管道）。
+- 不在服务器端点或兼容层重复实现工具转换/聚合；统一入口仅在 `llmswitch-core`。
+
+## 7. 实施清单（按顺序）
+
+1) 文档到位（本文件 + AGENTS.md 对齐段落）。
+2) 新增 `repairArguments`（JSON→JSON5→安全修复→"{}"）。
+3) 改造响应相位（非流）调用 `repairArguments` 并保证 finish_reason/content 不变式。
+4) 新增 Chat/Anthropic 两个 SSE 聚合器；改造 Responses SSE 统一策略。
+5) 更新 tools schema 描述（仅描述增强）。
+6) 严格按“先编译共享模块、再构建根包并全局安装”的顺序验证。
+
+---
+
+附：CCR 代码阅读锚点（仅供对照，不在代码注释中引用）
+- （更新）移除 `@musistudio/llms` 依赖描述；增强工具路径由 llmswitch-core 统一实现（透明代理 + 二轮请求）。
+- 流式路径中 `content_block_start/stop` 与 `partial_json` 聚合逻辑；
+- 非流路径中 arguments 三段式修复与回退策略。

package/docs/chat-glm-500-analysis.md

@@ -0,0 +1,79 @@
+# Chat GLM 500 调查与处置记录（精准定位）
+
+## 背景
+- 现象：Chat 通路上游 GLM 返回 500（Operation failed）。
+- 最新失败样本目录：`~/.routecodex/codex-samples/openai-chat`
+  - 例：`req_1761955101841_2d71u9w6x_provider-request.json`
+
+## 症状与证据
+- 请求载荷体积异常：多轮 `role:"tool"` 消息携带巨大 JSON/文本结果；两条超长 system 提示叠加。
+- codec/compat 阶段的快照显示：`assistant.tool_calls` 的 `content` 已规范为 `null`；但 `provider-request.json` 依然包含大量工具结果文本（历史轮未最小化）。
+- SSE 侧报错：`Error: GLM API error: 500 Internal Server Error - Operation failed`。
+
+## 根因（Root Cause）
+- 历史工具结果在多轮会话中持续累积为长文本，叠加双 system 文本，导致上游 GLM 对载荷体量/结构敏感触发 500。
+- 并非“工具引导未生效”。工具引导与工具增强均在 llmswitch-core 正常注入（`[Codex Tool Guidance v1]` + 严格 schema）。
+
+## CCR（Claude Code Router）的相关做法（预算来源）
+- CCR 以“总上下文预算（token count）”为核心，计算消息 + system + tools 的 token 数，并基于阈值选用长上下文模型：
+  - 位置：`../../claude-code-router/src/utils/router.ts`
+  - 关键点：
+    - 使用 `tiktoken` 计算 token（消息文本、tool_use/input、tool_result/content、system 文本、工具 schema 都计入）。
+    - 与配置阈值比较（`virtualrouter.classifier.longContextThresholdTokens`，默认 180,000 tokens）。
+    - 超阈值或结合上一轮 usage 过大则切换到 `config.Router.longContext` 模型。
+- CCR 并不把大段工具结果回灌到 assistant 文本；工作流结束时通过 ExitTool 返回最终文本，移除 `tool_calls`。
+
+## 我们的对齐策略（直击根因）
+- 唯一入口：仅在 `sharedmodule/llmswitch-core` 做统一处理；Provider/兼容层不做逻辑修改。
+- 两类措施：
+  1) 工具结果“主动最小化 + 分层预算”
+     - 所有 `role:'tool'` 消息统一“文本化+裁剪”。
+     - rcc.tool.v1 成功 → 提取 stdout/简明输出；失败 → `执行失败：前三行`；无输出 → `执行成功（无输出）`。
+     - 为避免累计膨胀，引入分层预算：
+       - 总载荷预算（token/字节，按 CCR 思路来自配置/环境）。
+       - 每条工具消息预算（HEAD/TAIL、类型化提要），最近 N 条额度更大，其余更严格。
+       - 保留结构与 `tool_call_id`，不改角色、不清历史（记忆靠历史）。
+  2) 去噪
+     - 删除“无 `tool_calls` 且内容为空/仅空白”的 `assistant` 回合，减少空 turn.
+
+## 已落地（当前版本）
+- 实施位置：`sharedmodule/llmswitch-core/src/conversion/shared/openai-message-normalize.ts`
+  - 统一对所有 `role:'tool'` 消息做“文本化+截断”，并在文本前加截断提示（例如：`[输出已截断至 2048 字符]`）。
+  - 默认阈值：`RCC_TOOL_TEXT_LIMIT`（默认 2048，可调）。
+  - `assistant` 含 `tool_calls` 时，将空字符串 `content` 规范为 `null`（保留混合内容）。
+  - 删除空文本 `assistant`（无工具调用）。
+
+## curl 复现与验证
+1. 启动本地服务（示例端口 5520）
+   ```bash
+   rcc start  # 或 routecodex start
+   ```
+2. 使用失败样本 `*_raw-request.json` 复现
+   ```bash
+   jq -r '.body' ~/.routecodex/codex-samples/openai-chat/<失败样本>_raw-request.json > /tmp/rc_req_body.json
+   curl -s -o /tmp/rc_resp.json -w "%{http_code}" \
+     -H 'Content-Type: application/json' \
+     --data @/tmp/rc_req_body.json \
+     http://127.0.0.1:5520/v1/chat/completions
+   ```
+3. 成功标准
+   - `provider-request.json` 中：
+     - `role:'tool'` 文本出现截断提示；历史轮不再巨量。
+     - 不再出现空的 `assistant` turn。
+   - SSE/JSON 不再出现上游 500。
+
+## 后续工作（对齐 CCR 的“预算来源”）
+- 预算来源与策略：
+  - 总上下文预算：
+    - 从配置载入（建议：`virtualrouter.classifier.longContextThresholdTokens`，或在用户配置中覆盖）。
+    - 用 `tiktoken` 计算请求 token 数，参照 CCR 的 `router.ts` 逻辑。
+  - 分层预算落到工具结果：
+    - 最近 N 条工具消息额度更大，其余更严格（HEAD/TAIL/摘要）。
+    - 类型化提要（stderr/失败仅前几行，stdout/JSON 取关键信息）。
+  - 超预算策略：
+    - 优先压缩工具结果文本，不修改历史结构与角色；必要时切换长上下文模型（CCR 同源策略）。
+
+## 结论
+- 500 原因是“累积工具结果文本 + 超长 system 导致载荷过大”，而非“工具引导缺失”。
+- 处置方案定位在唯一入口（llmswitch-core），以“主动最小化 + 预算控制”预防问题发生。
+- 下一步将把“分层预算 + 类型化提要 + 全局上下文预算（CCR 同源）”落地为可配置策略，并继续用 curl 真样本回放验证。

package/docs/chat-request-golden-samples.md

@@ -0,0 +1,42 @@
+### OpenAI Chat Golden Request Samples
+
+存放位置：`~/.routecodex/golden_samples/openai_requests/<slug>/`
+
+> **提示**：
+> - 自 0.87.21 起，chat 入口的 provider 专属样本统一存放在
+>   `~/.routecodex/golden_samples/new/<entryType>/<providerId>/`（例如 `new/openai-chat/glm`）。
+>   目录内包含 `request.sample.json`（直接从阶段快照复制的 `body`）以及 `meta.json`
+>   （指向原始 `*_stage2_format_build.json` 路径）。`scripts/tools/capture-provider-goldens.mjs`
+>   会优先读取这些“真实快照”，无需再回放 `samples/chat-blackbox/**/request-basic.json`。
+> - 仍需保留仓库内 `samples/chat-blackbox/*/request-basic.json`，用于快速审查/比较；当新增场景时，
+>   先运行真实请求生成阶段快照，再在 `new/<entryType>/<providerId>/` 放置 `request.sample` 与 `meta`，
+>   最后执行 `node scripts/tools/capture-provider-goldens.mjs --update-golden`，脚本会把同一份请求复制到
+>   `provider_golden_samples/`，供 mock/provider 单元测试使用。
+
+```
+<slug>/
+  request_payload.json  # 直接发送到 /v1/chat/completions 的 JSON
+  meta.json             # 包含来源阶段、endpoint、描述等元数据
+```
+
+| slug | 描述 | Source Stage |
+|------|------|--------------|
+| `chat-toolcall-20251209T225016004-002` | Codex CLI 会话（用户 repeatedly “列出本地文件”，`stream=true`，含完整 system/环境上下文与工具 schema），用于验证 chat 入口 → glm.provider 的骨架路径 | `openai-chat/req_1765291814052_req_inbound_stage1_format_parse.json` |
+
+#### 回放方式
+
+```bash
+curl -s http://127.0.0.1:5555/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer test' \
+  --data @~/.routecodex/golden_samples/openai_requests/chat-toolcall-20251209T225016004-002/request_payload.json
+```
+
+该样本会沿 V2 骨架走 chat 入口 → hub → glm provider，可直接用来对比 legacy/chat-provider 行为。
+
+#### 如何扩展
+
+1. 在 `~/.routecodex/golden_samples/openai-chat/req_*_req_inbound_stage1_format_parse.json` 中找到需要的请求负载。
+2. 将 `body.payload` 拷贝为新的 `request_payload.json`；注明 slug、描述后写入 `meta.json`。
+3. 更新本文件表格，描述该样本的用途、对应阶段文件。若需要刷新所有 provider 的黄金请求，可运行
+   `node scripts/tools/capture-provider-goldens.mjs --update-golden`，脚本将自动覆盖 `provider_golden_samples/` 下对应入口的请求副本。

package/docs/chat-semantic-expansion-plan.md

@@ -0,0 +1,84 @@
+## Chat 语义扩展与接线计划
+
+> 目标：让 llmswitch-core 中的 Chat Process / Standardized 桥承接四种协议的语义，不再依赖 metadata 透传 “raw payload”，并按顺序分阶段完成。
+
+> 术语约定：本文中的 “chat process” 指代码层面的 `chat_process` 阶段（工具治理/路由/协议重建的必经处理段）。
+
+### 阶段 0：现状确认
+
+1. **协议扫描**  
+   - `chat-mapper.ts`：系统提示、工具空数组、未知字段依赖 `metadata.systemInstructions/extraFields/toolsFieldPresent`。  
+   - `responses-mapper.ts`：resume/include/store 等通过 `metadata.responsesContext/responseFormat` 储存。  
+   - `anthropic-mapper.ts`：system blocks、tool alias、内容 shape 等塞进 `metadata.extraFields`。  
+   - `gemini-mapper.ts`：systemInstruction、safetySettings、generationConfig、toolConfig 均在 metadata/parameters。
+2. **chat process / standardized 桥**  
+   - 只理解 `messages/tools/toolOutputs/parameters`，其余通通进 `metadata.capturedContext`。
+
+### 阶段 1：扩展 Chat Process + Standardized 桥
+
+1. **类型扩展**  
+   - 在 `ChatEnvelope`、`StandardizedRequest` 新增 `semantics`，并明确区分：  
+     - **通用横向字段**：如 `semantics.session.previousResponseId`、`semantics.system.textBlocks`，用于跨协议共享。  
+     - **协议专属命名空间**：`semantics.responses` / `semantics.anthropic` / `semantics.gemini`。每个命名空间内定义稳定 contract，禁止随意往里塞 provider extras。  
+     - **providerExtras** 仅用于临时透传，默认禁止业务逻辑读取，后续接线完成后应趋近于空。
+   - `chatEnvelopeToStandardized` / `standardizedToChatEnvelope` 深拷贝 `semantics`。
+2. **chat process 适配**  
+   - `runHubChatProcess`、工具治理、路由决策只读 `request.semantics`；除 mapper/bridge 外，任何模块不得写入 `semantics`。  
+   - Metadata 退回诊断角色：仅保留 `missingFields/providerMetadata` 等调试字段，`capturedContext` 禁止再夹带业务语义。
+3. **模块测试**  
+   - 新增 spec：构造 `ChatEnvelope` (含 system/responses/anthropic/gemini)，执行标准化→还原→chat process，断言 `semantics` 原样保留。
+
+> 完成该阶段后，chat process 成为“语义承接层”，为后续接线提供可靠落点。
+
+### 阶段 2：协议语义接线（分批）
+
+1. **OpenAI Chat**  
+   - 将 `metadata.systemInstructions`/`extraFields`/`toolsFieldPresent` 迁移到 `semantics.system` / `semantics.tools`，只允许在 `semantics.providerExtras` 做临时镜像。  
+   - 迁移期间保持“语义双写”：写入 semantics 后，兼容代码仍可读旧 metadata，但新逻辑必须只读 semantics。  
+   - 更新现有 chat mapper 测试，确认 round-trip 不丢数据。
+2. **Responses**  
+   - `captureResponsesContext` 输出的 include/store/responseFormat/resume 等写入 `semantics.responses`，必要时临时镜像到旧 metadata。  
+   - SubmitToolOutputs、resume、responses-roundtrip 仅依赖 `semantics.responses`；现有逻辑若仍读 metadata，需先迁移。  
+   - 针对 responses 的 mock sample 回放，验证 `semantics.responses` 中包含 `previousResponseId`、`resumeToolOutputs` 等。
+3. **Anthropic**  
+   - system blocks、alias map、passthrough metadata、anthropicMirror -> `semantics.anthropic`。  
+   - outbound mapper 从 `semantics` 还原 payload，metadata.extraFields 仅做兼容写；新读路径统一指向 semantics。  
+   - 更新 `tests/sharedmodule/gemini/anthropic` 相关断言。
+4. **Gemini**  
+   - systemInstruction、safetySettings、toolConfig、generationConfig、`__rcc_stream` → `semantics.gemini`，仅在兼容期间写 metadata 镜像。  
+   - generationConfig / toolConfig 通过 `semantics` 显式传递，metadata 不得再承载业务语义。  
+   - 确认 `buildGeminiRequestFromChat` 仅依赖 `chat.semantics.gemini`。
+
+每完成一个协议接线：  
+- 编写/更新对应 spec。  
+- 运行协议相关现有测试（tool-loop、responses-submit、anthropic roundtrip、gemini mapper）。  
+- 确认黑盒模块测试（阶段 1）依然通过。
+
+### 阶段 3：清理与回归
+
+1. **移除遗留 metadata 键**  
+   - 删除 `metadata.systemInstructions/extraFields.responsesContext` 等已迁移字段，保留 `missingFields/providerMetadata`。  
+   - 更新文档与类型约束。
+2. **回归测试矩阵**  
+   - `npm run test:sharedmodule`  
+   - `npm run verify:e2e-toolcall`（覆盖 responses tool loop）  
+   - `scripts/tests/apply-patch-loop.mjs` / `responses-submit` 样本回放  
+   - Anthropic / Gemini 专属 dry-run（若有）。
+3. **文档更新**  
+   - `docs/responses-...`, `docs/pipeline/...` 添加新语义字段说明。  
+   - 记录“metadata 仅用于诊断，业务语义全部进入 `semantics`”的新约束。
+
+### 注意事项
+
+- **严格顺序**：阶段 1 完成并通过黑盒测试后，才能启动阶段 2 的任何接线工作。  
+- **只读语义**：除 Semantic Mapper / Bridge 外，任何模块不得写 `semantics`； chat process 之后的所有节点禁止从 metadata/raw 读取业务语义。  
+- **最小增量**：每个协议接线尽量独立 PR/commit，便于回滚。  
+- **兼容期双写**：阶段 2 中需维护 semantics & metadata 双写（写 semantics → 同步旧字段）；读路径优先 semantics，metadata 仅保底兼容，直到阶段 3 清理完成。  
+- **验证方式**：所有语义字段必须能在 `StandardizedRequest.semantics` 中观测到，且 chat process/路由/工具治理仅依赖该结构。
+
+### 审查建议
+
+- **横纵拆分**：在 `semantics` 结构中明确跨协议共享字段（例如 `semantics.session.previousResponseId`、`semantics.system.textBlocks`），避免每个协议重复定义同义字段；协议专属字段需在命名空间内列出 contract，并写测试覆盖。  
+- **提交策略**：阶段 2~3 的每个协议迁移都需更新 spec + 运行现有样本（responses submit、anthropic/gemini roundtrip 等），并用黑盒模块测试确认 semantics 不丢失。  
+- **metadata 清理**：阶段 3 清理前做 StandardizedRequest/ChatEnvelope 快照测试，确保 metadata 只剩诊断信息；用 codex samples 回放检查 semantics 是否完整覆盖我们关心的语义。  
+- **与“禁止 raw 打洞”对齐**：任何绕开 semantics、试图回读 raw/metatada 的逻辑都应视为架构违规；新文档明确强调这一点，保持与工具链路治理的统一思路。