@jsonstudio/rcc 0.89.1205 → 0.89.1348

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/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,82 @@
+## Chat 语义扩展与接线计划
+
+> 目标：让 llmswitch-core 中的 Chat Process / Standardized 桥承接四种协议的语义，不再依赖 metadata 透传 “raw payload”，并按顺序分阶段完成。
+
+### 阶段 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 的逻辑都应视为架构违规；新文档明确强调这一点，保持与工具链路治理的统一思路。

package/docs/cli-command-inventory.md

@@ -0,0 +1,76 @@
+# CLI Command Inventory & Contracts
+
+Source of truth: `src/cli.ts` (wiring) + command implementations in `src/cli/commands/*` and `src/commands/*`.
+
+## Inventory (from `src/cli.ts`)
+
+| Command | Where registered | Implementation | Side effects (non-exhaustive) | Exit behavior |
+|---|---|---|---|---|
+| `env` | `src/cli/register/basic-commands.ts` | `src/cli/commands/env.ts` | Reads config file (optional) | `ctx.exit(1)` on parse/config errors; otherwise returns |
+| `clean` | `src/cli/register/basic-commands.ts` | `src/cli/commands/clean.ts` | Deletes captures/logs via `fs.rmSync(recursive)` | Returns on success; on failure uses spinner/logger (no direct `ctx.exit` in this file) |
+| `examples` | `src/cli/register/basic-commands.ts` | `src/cli/commands/examples.ts` | Prints examples | Returns |
+| `port` | `src/cli/register/basic-commands.ts` | `src/cli/commands/port.ts` | Reads port listeners; may kill PIDs (`--kill`) | `ctx.exit(2)` on invalid port; `ctx.exit(1)` on failures |
+| `config` | `src/cli/register/status-config-commands.ts` | `src/cli/commands/config.ts` | Writes config file; reads existing config | Returns (no direct `ctx.exit` in this file) |
+| `status` | `src/cli/register/status-config-commands.ts` | `src/cli/commands/status.ts` | Network `fetch` to server status endpoint | Returns (no direct `ctx.exit` in this file) |
+| `start` | `src/cli/register/start-command.ts` | `src/cli/commands/start.ts` | Reads config; may write temp config + pid file; may `fetch` shutdown; may kill PIDs; spawns server (`node dist/index.js`) | Uses `ctx.exit(...)` for success/error paths |
+| `stop` | `src/cli/register/stop-command.ts` | `src/cli/commands/stop.ts` | Reads config (release); kill PIDs; optional token-daemon stop | `ctx.exit(1)` on config/stop failures; otherwise returns |
+| `restart` | `src/cli/register/restart-command.ts` | `src/cli/commands/restart.ts` | Reads config; kill PIDs; may `fetch` shutdown; spawns server; writes pid file | Uses `ctx.exit(...)` for success/error paths |
+| `code` | `src/cli/register/code-command.ts` | `src/cli/commands/code.ts` | Reads config for `apikey`; may `fetch /ready`; may spawn server; spawns `claude` | Uses `ctx.exit(...)` for success/error paths |
+| `provider-update` *(optional)* | `src/cli.ts` dynamic import | `src/commands/provider-update.ts` | Reads/writes provider config and lists; may call RouteCodex HTTP endpoint for probing | Uses `process.exit(1)` in multiple branches |
+| `camoufox-fp` *(optional)* | `src/cli.ts` dynamic import | `src/commands/camoufox-fp.ts` | Reads fingerprint JSON on disk | Sets `process.exitCode` on errors |
+| `camoufox-backfill` *(optional)* | `src/cli.ts` dynamic import | `src/commands/camoufox-backfill.ts` | Backfills fingerprints (disk IO) | Uses `process.exitCode` on errors (by pattern) |
+| `token-daemon` *(optional)* | `src/cli.ts` dynamic import | `src/commands/token-daemon.ts` | Spawns background daemon; reads/writes snapshots | Uses `process.exit(...)` / `process.exitCode` in command handlers |
+| `quota-status` *(optional)* | `src/cli.ts` dynamic import | `src/commands/quota-status.ts` | Reads quota snapshot file | Returns; throws on missing file |
+| `quota-daemon` *(optional)* | `src/cli.ts` dynamic import | `src/commands/quota-daemon.ts` | Reads replay NDJSON; writes `provider-quota.json` unless `--dry-run` | Returns; on failure throws/sets exit |
+| `oauth` *(optional)* | `src/cli.ts` dynamic import | `src/commands/oauth.ts` | Triggers OAuth flows (Camoufox/browser automation) | Returns; may set exit codes on failures (subcommands) |
+| `validate` *(optional)* | `src/cli.ts` dynamic import | `src/commands/validate.ts` | `fetch` health + API; may spawn `rcc start`; reads payload file | Calls `process.exit(1)` on failures |
+
+## Contracts (inputs/outputs) — extracted from `.option(...)`
+
+### `env` (`src/cli/commands/env.ts`)
+- Inputs: `--port`, `--host`, `--config`, `--json`; reads config file if present.
+- Output: prints shell exports (default) or JSON (`--json`).
+- Exit: `1` on invalid/missing config-derived port.
+
+### `clean` (`src/cli/commands/clean.ts`)
+- Inputs: `--yes`, `--what <targets>` (default `all`).
+- Output: spinner/log messages about deleted targets.
+- Exit: no explicit `ctx.exit` in this file (errors are handled inside action).
+
+### `port` (`src/cli/commands/port.ts`)
+- Inputs: `--port <port>` (default `5555`), `--kill`.
+- Output: diagnostics; when `--kill`, attempts to kill listeners.
+- Exit: `2` on invalid port; `1` on kill failure or unexpected errors.
+
+### `config` (`src/cli/commands/config.ts`)
+- Inputs: `--config <config>`, `--template <template>`, `--force`.
+- Output: writes/prints config info via logger/spinner.
+- Exit: no explicit `ctx.exit` in this file.
+
+### `status` (`src/cli/commands/status.ts`)
+- Inputs: `--json`.
+- Output: human-readable status or JSON.
+- Exit: no explicit `ctx.exit` in this file.
+
+### `start` (`src/cli/commands/start.ts`)
+- Inputs: `--config`, `--port`, `--quota-routing on|off`, `--log-level`, `--codex/--claude`, `--ua`, `--snap/--snap-off`, `--verbose-errors/--quiet-errors`, `--restart`, `--exclusive`.
+- Output: spinner/log lines; server process inherits stdio.
+- Exit: `0` on normal termination; `1` on validation/start/shutdown errors.
+
+### `stop` (`src/cli/commands/stop.ts`)
+- Inputs: none; release mode reads config file for port; dev mode uses default/env port.
+- Output: spinner/log lines about stop result.
+- Exit: `1` on configuration/stop errors.
+
+### `restart` (`src/cli/commands/restart.ts`)
+- Inputs: `--config`, `--log-level`, `--codex/--claude`.
+- Output: spinner/log lines; server process inherits stdio.
+- Exit: `0` on normal termination; `1` on validation/restart errors.
+
+### `code` (`src/cli/commands/code.ts`)
+- Inputs: `--port`, `--host` (default `0.0.0.0`), `--url`, `--config`, `--apikey`, `--claude-path`, `--cwd`, `--model`, `--profile`, `--ensure-server`.
+- Output: launches Claude Code (subprocess inherits stdio).
+- Exit: `0` when Claude exits cleanly; `1` on connection/start failures.
+
+### Optional command groups (`src/commands/*`)
+These are wired via `program.addCommand(...)` and still use `process.exit(...)`/`process.exitCode` in places. They are not yet migrated into the `ctx.exit`/testable registration pattern.

package/docs/codex-samples-replay.md

@@ -0,0 +1,50 @@
+# Codex Samples 回放
+
+`scripts/replay-codex-sample.mjs` 允许我们将 `~/.routecodex/codex-samples/**/*_client-request.json` 等样本重新发送到本地 RouteCodex，确保工具调用、SSE chunk 和最终 JSON 都被完整记录。
+
+## 使用步骤
+
+1. 启动 RouteCodex 主包（默认 `http://127.0.0.1:5555`）。
+2. 准备好想要回放的样本文件，例如：
+   `~/.routecodex/codex-samples/openai-responses/req_req-v2-1764415000213-z1sxtbhuo_client-request.json`
+3. 执行：
+
+```bash
+npm run replay:codex-sample -- \
+  --sample ~/.routecodex/codex-samples/openai-responses/req_req-v2-1764415000213-z1sxtbhuo_client-request.json \
+  --label first-run
+```
+
+可选参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--label` | 为本次运行命名（默认使用时间戳）。 |
+| `--base`  | RouteCodex 基地址，默认 `http://127.0.0.1:5555`。 |
+| `--key`   | API Key / Bearer Token，默认 `routecodex-test`。 |
+
+## 产出内容
+
+脚本会在样本所在目录下生成 `runs/<requestId>/<label>/`，包括：
+
+- `request.json`：发送给 RouteCodex 的 endpoint 与 body；
+- `response.meta.json`：状态码、响应头以及是否流式；
+- 若为流式：
+  - `response.sse.log`：完整的 SSE 文本（`event:`/`data:`）；
+  - `response.sse.ndjson`：逐帧 NDJSON，方便与黄金样本 diff；
+- 若为 JSON：
+  - `response.json`：RouteCodex 返回的 JSON payload；
+- 若发生错误，额外写入 `response.error.txt`。
+
+## 配合 proxy replay
+
+对于 responses SSE，可使用 `scripts/responses-sse-proxy.mjs --replay <capture>/response.sse.log` 将黄金样本作为上游输出，再结合本脚本回放客户端 payload，实现“同一份请求 + 同一份 SSE 流”在 RouteCodex 中的完整闭环。
+
+## 常见场景
+
+- **工具调用链路**：先回放 `/v1/responses` 样本捕获 `required_action`，再回放对应的 `/v1/responses.submit_tool_outputs` 样本；
+- **对比黄金样本**：和 `npm run verify:sse-loop -- --skip-chat --skip-anthropic --use-proxy-capture` 搭配，先复现请求，再检查 SSE 是否与黄金帧一致；
+- **调试快照**：`runs/` 输出可以直接归档到版本库/CI 工件，作为后续 Regression 的输入。
+
+通过上述流程，可以确保 codex samples 中的工具请求、工具返回以及最终响应数据均可被精准复现，并在磁盘上形成完备的 JSON/SSE 证据链。
+