@jsonstudio/rcc 0.89.1205 → 0.89.1457

package/docs/providers/gemini-provider.md

@@ -0,0 +1,62 @@
+# Gemini Provider (gemini-chat)
+
+本页介绍 Gemini HTTP Provider 的使用与测试方法（基于 Google Generative Language API）。
+
+## 基本信息
+- 基地址：`https://generativelanguage.googleapis.com/v1beta`
+- 端点：`/models/{model}:generateContent`
+- 认证：API Key（请求头 `x-goog-api-key: <KEY>`，或自动从 `Authorization: Bearer <KEY>` 转换）
+- 协议类型：`gemini`（providerProtocol=`gemini-chat`）
+
+## 配置示例
+
+```json
+{
+  "type": "gemini-http-provider",
+  "config": {
+    "providerType": "gemini",
+    "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
+    "model": "gemini-2.5-flash-lite",
+    "auth": {
+      "type": "apikey",
+      "headerName": "x-goog-api-key",
+      "apiKey": "<YOUR_GEMINI_API_KEY>"
+    }
+  }
+}
+```
+
+> 注意：若 `auth.headerName` 未设置，本 Provider 会在发送前将 `Authorization: Bearer <KEY>` 自动转换为 `x-goog-api-key: <KEY>`。
+
+## 协议映射（最小）
+- 入站（OpenAI Chat → Gemini contents）：Provider 在 `preprocessRequest` 做最小映射：
+  - `messages[].role=user|assistant` → `contents[].role=user|model`
+  - `messages[].content` → `parts[].text`
+  - `system` 合并为 `systemInstruction`
+  - 可选生成参数：`max_tokens` → `generationConfig.maxOutputTokens`，`temperature`、`top_p` 对应映射
+- 返回：保持上游 JSON 原样返回（包含 `candidates` / `content`）。Composite 响应侧已允许 `candidates` 通过形状守卫。
+
+## provider update（模型更新）
+
+`src/tools/provider-update` 已支持 Gemini 的 `/models` 结果（`{ models: [{ name: 'models/<id>'}, ...] }`）。示例：
+
+```bash
+node dist/tools/provider-update/index.js \
+  --config /Users/you/.routecodex/provider/gemini/config.json \
+  --write --probe-keys --verbose
+```
+
+要求：配置文件中 `auth.headerName` 为 `x-goog-api-key` 或者确保 `Authorization: Bearer <KEY>` 可用（工具也支持 headerName/prefix 覆盖）。
+
+## 快速联调（本地脚本）
+
+```bash
+GEMINI_API_KEY=**** npm run build
+GEMINI_API_KEY=**** node scripts/gemini-smoke.mjs
+```
+
+脚本默认使用 `gemini-2.5-flash-lite` 并发送简短提示；返回结果仅截断打印前 500 字符。
+
+## 测试建议
+- 单元：按 docs/providers/provider-composite-testing.md 中“协议守卫/形状漂移”用例增加 `gemini-chat` 断言；已允许 `candidates` 通过。
+- 集成：在 provider_golden_samples 中增加 `gemini-chat` 的 request/response 样例（可按真实 wire 形状扩展），并在蓝图回归中启用 gemini 路径。

package/docs/providers/lmstudio-v2-migration-report.md

@@ -0,0 +1,102 @@
+**Title**
+- LM Studio → Provider V2 Migration Analysis
+
+**Summary**
+- Decision: Reuse `openai-standard` provider with a thin `lmstudio-compatibility` module. This aligns with V2 principles (minimal compatibility, no tool logic in provider) and leverages existing OpenAI‑compatible behavior of LM Studio.
+- Scope: Chat Completions (`/v1/chat/completions`) supported out of the box; Responses (`/v1/responses`) can be enabled using the existing Responses profile + upstream SSE passthrough design, gated by configuration.
+
+**Why This Approach**
+- OpenAI compatibility: LM Studio implements OpenAI‑compatible endpoints and shapes (messages, tools, tool_calls, streaming), so OpenAI‑standard fits.
+- Existing service profile: A dedicated `lmstudio` service profile exists and targets localhost defaults and OpenAI‑style endpoints (src/providers/core/config/service-profiles.ts:92).
+- Minimal compatibility needs: Only small request/response shape adjustments are required (e.g., `tool_choice` normalization), which belong in Compatibility, not Provider.
+
+**Provider Choice**
+- Use `openai-standard` with `providerType: 'lmstudio'`.
+  - Mapping is already defined: `CONFIG_MAPPINGS['lmstudio-provider-simple'] = 'openai-standard'` (src/providers/core/api/provider-config.ts:103-112).
+  - LM Studio profile defaults:
+    - Base URL: `http://localhost:${DEFAULT_CONFIG.LM_STUDIO_PORT}`
+    - Endpoint: `/v1/chat/completions`
+    - Headers: `Content-Type: application/json`
+    - Location: src/providers/core/config/service-profiles.ts:92-103
+
+**Compatibility Responsibilities**
+- Keep compatibility minimal, provider‑agnostic, and confined to the Compatibility layer:
+  - Normalize `tool_choice` to LM Studio’s expected strings when an OpenAI object is provided, forcing `'required'` in that case（逻辑现由 `sharedmodule/llmswitch-core` 中的 compat profile 提供）。
+  - Preserve OpenAI tool shape (direct mapping of `tools` and `choices[].message.tool_calls`).
+  - Maintain `object` values like `chat.completion` and `chat.completion.chunk` in responses.
+- Do not duplicate llmswitch-core tool governance (canonicalization/harvest/repair) in Compatibility per AGENTS.md.
+
+**API Surface Alignment**
+- Chat Completions (`/v1/chat/completions`)
+  - Requests: `model`, `messages`, `tools`, `tool_choice`, `stream`, `max_tokens`, `temperature`, etc. Direct mapping per transformation tables (docs/transformation-tables/claude-code-router-openai-to-lmstudio.json).
+  - Responses: OpenAI‑shaped `choices[0].message.tool_calls` with `finish_reason: 'tool_calls'`. `object: 'chat.completion'` and streaming chunks `chat.completion.chunk` are preserved.
+- Responses API (`/v1/responses`)
+  - Supported via existing “Responses provider” design when needed. Upstream SSE passthrough can be enabled and paired with compatibility that does no destructive filtering of event streams. See docs/responses-passthrough-provider-design.md.
+
+**Streaming**
+- Chat Completions streaming uses standard OpenAI chunk format; `openai-standard` handles this consistently.
+- For Responses SSE passthrough, use the dedicated `responses` profile with required headers (e.g., `OpenAI-Beta`) and tee/pipe handling. See service profiles and passthrough design docs.
+
+**Error Handling**
+- LM Studio error shapes can be treated as OpenAI‑style error objects; transformation table marks them as direct mappings (docs/transformation-tables/claude-code-router-openai-to-lmstudio.json).
+- Follow Fail Fast: no hidden fallbacks in provider; only shape normalization in Compatibility.
+
+**Config Blueprint**
+- Provider V2 (OpenAI standard with LM Studio profile):
+```
+{
+  "type": "openai-standard",
+  "config": {
+    "providerType": "lmstudio",
+    "auth": { "type": "apikey", "apiKey": "local-dev" },
+    "overrides": {
+      "baseUrl": "http://localhost:1234",
+      "endpoint": "/v1/chat/completions"
+    }
+  }
+}
+```
+- Compatibility (minimal, auto‑inferred for providerType `lmstudio`):
+```
+{
+  "type": "lmstudio-compatibility",
+  "config": {
+    "toolsEnabled": true
+  }
+}
+```
+
+**Key Implementation Notes**
+- Provider
+  - Reuse `openai-standard` end‑to‑end; select `ServiceProfile('lmstudio')` for defaults. No tool logic here.
+  - For Responses passthrough, use the dedicated `responses` profile if routing `/v1/responses` to LM Studio’s OpenAI‑compatible Responses endpoint.
+- Compatibility
+  - Ensure LM Studio compat profile is available and registered（type 由 `compatibilityProfile` 指定）。It performs only light normalization/mapping; notably `tool_choice` normalization and direct mapping rules for tools/tool_calls（均驻留在 llmswitch-core compat 中）。
+  - Keep response `object` and tool call shapes intact (see same file, response rules section around id `tool-calls-response`).
+- llmswitch-core
+  - Tool canonicalization, harvesting from text, and argument repair remain centralized per AGENTS.md; do not reimplement in Compatibility/Provider.
+
+**Validation Plan**
+- Local dry‑runs and shape checks
+  - Use `npm run test:lmstudio-dryrun` to validate tool call flows and response shapes.
+  - Review prior LM Studio dry‑run docs for expected shapes (docs/lmstudio-dry-run-summary.md, docs/lmstudio-tool-calling.md).
+- Snapshots & SSE
+  - Enable upstream SSE passthrough when validating `/v1/responses`; verify event integrity and headers.
+- Compatibility integrity
+  - Confirm that `tool_choice` object inputs become `'required'` and result in `finish_reason: 'tool_calls'` when tools are selected.
+
+**Open Items / Risks**
+- Responses header/versioning: Confirm current `OpenAI-Beta` header value when targeting `/v1/responses` upstream.
+- Auth expectations: LM Studio local deployments often accept requests without Authorization; retaining an API key header is typically harmless, but confirm server configuration.
+- Compatibility registration: Ensure `lmstudio-compatibility` type is registered with `CompatibilityModuleFactory` if created via type string.
+
+**References**
+- `src/providers/core/api/provider-config.ts:103` — maps `lmstudio-provider-simple` to `openai-standard`.
+- `src/providers/core/config/service-profiles.ts:92` — LM Studio service profile defaults.
+- 历史实现：`src/providers/compat/lmstudio-compatibility.ts:76` — `tool_choice` normalization logic（已迁移至 sharedmodule/llmswitch-core compat profiles）。
+- `docs/lmstudio-tool-calling.md:1` — LM Studio tool calling shape and examples.
+- `docs/transformation-tables/claude-code-router-openai-to-lmstudio.json:1` — direct mappings for OpenAI↔LM Studio.
+- `docs/responses-passthrough-provider-design.md:3` — Responses SSE passthrough design.
+
+**Conclusion**
+- Answer to Q1: Yes — reuse `openai-standard` with `lmstudio-compatibility`. This yields minimal, standards‑aligned integration under Provider V2, keeps tool governance centralized in llmswitch‑core, and supports both Chat Completions and Responses with straightforward configuration.

package/docs/providers/provider-composite-design.md

@@ -0,0 +1,142 @@
+# ProviderComposite 设计（兼容层内聚到 Provider）
+
+本设计将“Compatibility 兼容层”内聚为 Provider 节点的协议敏感子插件（compat-subnode），在出站/返回两侧做强类型守卫，统一使用 BasePipeline 注入的 runtime metadata（虚拟路由结果）作为唯一真理来源。
+
+## 目标与原则
+
+- 仅按协议类型划分 Provider：`openai-chat`、`openai-responses`、`anthropic-messages`（预留 `gemini-chat`）。
+- 兼容层内聚：ProviderComposite 在 Provider 内部调用 compat 子插件；Host 流水线不再显式编排 compatibility 节点。
+- 协议守卫（Fail Fast）：入/出两侧验证 `providerType → providerProtocol` 的映射；任何形状漂移立即报错。
+- 工具治理边界：工具解析/修复/收割仅在 llmswitch-core 的 process 链路，compat 子插件严格“最小字段修剪/映射/黑名单”。
+- SSE 边界：Provider 对上游可用 SSE，但对 Host 一律返回 JSON；客户端方向的 SSE 仅在 llmswitch-core 的 sse 节点族出现。
+
+## 背景：runtime metadata 统一输入
+
+- BasePipeline 在构建 request/response context 时，将虚拟路由回写的 `providerType`/`providerProtocol`/`providerKey`/`routeName`/`target` 等以不可枚举属性写入请求体。
+- 模块：`src/providers/core/runtime/provider-runtime-metadata.ts`
+- 读取：`extractProviderRuntimeMetadata()`（BaseProvider 已缓存最近一次 metadata，并在日志/错误中心附带字段）。
+
+## 新拓扑（出站与返回）
+
+```
+output/* → Provider.preprocessRequest(compat.request) → HTTP Provider → Provider.postprocessResponse(compat.response) → response/*
+```
+
+说明：
+- Host 侧流水线不变；compat 被 Provider 内部的 ProviderComposite 执行。
+- Responses 上游使用 SSE；Provider 解析为 JSON 再返回 Host。
+
+## 类与文件
+
+- 新增（Provider 内）：
+  - `src/providers/core/composite/provider-composite.ts`
+  - `src/providers/core/composite/compat/openai-compat-aggregator.ts`
+  - `src/providers/core/composite/compat/{responses,anthropic,gemin i}.ts`
+
+- 复用（保持原路径）：
+- 历史上曾存在 `src/providers/compat/*` 模块作为旧实现，现已下线；兼容行为统一迁移至 `sharedmodule/llmswitch-core/src/conversion/compat/*`（通过 `compatibilityProfile` 驱动 GLM / LM Studio / iFlow 等）。
+
+## 协议守卫与自动加载
+
+- 运行时映射（唯一来源：BasePipeline 注入）：
+  - `openai → openai-chat`
+  - `responses → openai-responses`
+  - `anthropic → anthropic-messages`
+  - `gemini → gemini-chat`
+- 验证点：
+  - 入站：`in.protocol` 与 `runtime.providerProtocol` 以及 `map(runtime.providerType)` 必须一致，否 则 `ERR_PROTOCOL_MISMATCH`。
+  - compat.request/response 不得改变协议形状，否则 `ERR_COMPAT_PROTOCOL_DRIFT`。
+
+## OpenAI 协议族家族聚合器
+
+- 基于 `providerId/providerKey` 选择最小家族差异：
+  - `glm` → 复用 `GLMCompatibility`（最小清理、1210/1214、末条 tool 回显清噪）。
+  - `lmstudio` → 复用 `LMStudioCompatibility`（最小字段映射）。
+  - `iflow` → 复用 `iFlowCompatibility`（OpenAI 形状，OAuth 于 Provider 层处理）。
+  - `qwen` → 默认走最小路径（保持 OpenAI 形状），不启用旧 `qwen-compat` 的“input/parameters”改形状逻辑。
+  - 其他 → passthrough/minimal。
+
+## 与 BaseProvider 的集成
+
+- Chat 协议 Provider（`ChatHttpProvider`，原 `OpenAIStandard`）在以下两处调用：
+  - `preprocessRequest` 末尾：`compat.request`
+  - `postprocessResponse` 封装前：`compat.response`
+- Responses/Anthropic Provider 可按需接入（初期保持 passthrough）。
+
+## 错误模型与快照
+
+- 错误：
+  - `ERR_PROTOCOL_MISMATCH`：协议守卫失败（含 `requestId/providerKey/providerType/providerProtocol/routeName`）。
+  - `ERR_COMPAT_PROTOCOL_DRIFT`：compat 改变协议形状。
+  - `ERR_UNSUPPORTED_PROVIDER_TYPE`：未注册协议族。
+  - `ERR_PROVIDER_HTTP`：HTTP 层错误（保留）。
+- 上报路径：Compat/Provider 每次捕获异常时必须调用 `emitProviderError()`（封装在 `provider-error-reporter.ts`），将错误统一转换为 `ProviderErrorEvent` 并提交给 sharedmodule/llmswitch-core 的 `providerErrorCenter`，同时调用 `errorHandlingCenter.handleError()`。虚拟路由器依赖这些事件执行熔断，禁止吞掉任何异常或在本地兜底。
+- 快照：
+  - `compat-pre/compat-post`（request/response）、`provider-request/provider-response/provider-error`；均脱敏，best-effort。
+
+## Provider 类型对齐（type-only）
+
+- Provider 仅按协议类型划分：`openai`、`responses`、`anthropic`、`gemini`。
+- Factory 按类型创建：
+  - `openai` → Chat 协议 Provider（当前类：ChatHttpProvider）；
+  - `responses` → ResponsesHttpProvider（上游 SSE→JSON 解析）；
+  - `anthropic` → AnthropicHttpProvider；
+  - `gemini` → 预留。
+- 旧配置兼容（规范化）：
+  - 若发现 `providerType` ∈ {`glm`,`qwen`,`iflow`,`lmstudio`}，运行时规范化为 `openai` 并记录告警；品牌保留在 `providerId`，OAuth 方案通过 `auth.type = "<provider>-oauth"` 显式声明。
+  - 不在 `llmswitch-core` 内判断品牌，品牌差异仅由 compat 聚合器处理（最小清理）。
+
+## 迁移与兼容
+
+- 配置：将旧 `providerType: 'qwen'|'glm'|'iflow'|'lmstudio'` 规范化为 `providerType: 'openai'`，并通过 `providerId` + `auth.type = '<provider>-oauth'` 表达家族；保留警告日志。
+- Qwen：默认走 OpenAI 兼容端点 `/v1/chat/completions`；如需 native wire，需新增协议 id 与 codec，不能在 `openai-chat` 协议下改形状。
+
+### 配置示例（OAuth 品牌）
+
+```json
+{
+  "type": "openai-standard",
+  "config": {
+    "providerType": "openai",
+    "baseUrl": "https://portal.qwen.ai/v1",
+    "auth": { "type": "qwen-oauth" },
+    "models": ["qwen3-coder-plus"]
+  }
+}
+```
+
+### 运行期元数据（runtime metadata）
+
+ProviderComposite 与 Hook/HTTP 层依赖 `BasePipeline` 回写的元数据：
+
+```ts
+{
+  requestId, pipelineId, routeName,
+  providerId, providerKey,
+  providerType, providerProtocol,
+  target: { model, providerType, providerKey, ... }
+}
+```
+
+上述字段作为请求体的不可枚举属性注入（attachProviderRuntimeMetadata），Provider/Composite 通过 extractProviderRuntimeMetadata 读取。
+
+## 测试计划
+
+- 协议守卫：错配触发 `ERR_PROTOCOL_MISMATCH`；家族聚合器若改形状触发 `ERR_COMPAT_PROTOCOL_DRIFT`。
+- GLM 回归：tools 严格字段清理、1210/1214、非流式响应黑名单。
+- LM Studio / iFlow：OpenAI 形状不变；OAuth 流程（iFlow）在 Provider 层。
+- Qwen：保持 OpenAI 形状直连。
+- Responses：上游 SSE → JSON，对内一律 JSON。
+
+### 建议的测试入口
+
+- 构建：`npm run build`
+- 蓝图回归：`npm test -- tests/pipeline/blueprint-regression.test.ts --runInBand`
+- 协议守卫单测：新增 `tests/provider/provider-composite-guards.test.ts`（建议，见测试文档）
+
+## 执行步骤（本次提交范围）
+
+1) 添加 ProviderComposite 与 openai 聚合器骨架文件；
+2) 在 Chat 协议 Provider（`chat-http-provider.ts`）植入 compat.request/compat.response 调用；
+3) Factory 由 `protocol-first` 选择 Provider（保持与旧配置兼容的规范化通道）；
+4) 回归：`npm test -- tests/pipeline/blueprint-regression.test.ts --runInBand`。

package/docs/providers/provider-composite-testing.md

@@ -0,0 +1,98 @@
+# ProviderComposite 测试方法
+
+本文档给出 ProviderComposite（兼容层内聚）变更后的测试建议，用于统一回归与新增用例编写方式。
+
+## 1. 构建与基础回归
+
+- 构建：`npm run build`
+- 蓝图回归：`npm test -- tests/pipeline/blueprint-regression.test.ts --runInBand`
+  - 说明：该用例基于用户的 codex-samples 快照与用户配置动态生成蓝图，校验不同 providerProtocol 的节点签名。
+  - 若环境未配置样本/用户配置会自动跳过。
+
+## 2. 协议守卫与形状断言（新增建议）
+
+新增 `tests/provider/provider-composite-guards.test.ts`（建议：在后续 PR 中加入），覆盖：
+
+- `ERR_PROTOCOL_MISMATCH`：
+  - 构造请求体并注入 runtime metadata（providerType 与 providerProtocol 显式不匹配），
+  - 调用 `ProviderComposite.applyRequest` → 断言抛错；
+  - 同理 `applyResponse`。
+
+- `ERR_COMPAT_PROTOCOL_DRIFT`：
+  - 模拟 compat 插件输出非预期形状（如 openai-chat 协议下没有 `messages` 或 `choices`），
+  - 断言 `applyRequest/Response` 抛错。
+
+伪代码示例：
+
+```ts
+import { ProviderComposite } from '../../src/providers/core/composite/provider-composite.js';
+import { attachProviderRuntimeMetadata } from '../../src/providers/core/runtime/provider-runtime-metadata.js';
+
+test('protocol mismatch fails fast', async () => {
+  const body: any = { model: 'gpt-4o', messages: [] };
+  attachProviderRuntimeMetadata(body, {
+    requestId: 'req_x', providerType: 'anthropic', providerProtocol: 'openai-chat'
+  });
+  await expect(
+    ProviderComposite.applyRequest(body, { providerType: 'anthropic', dependencies: anyDeps })
+  ).rejects.toThrow(/ERR_PROTOCOL_MISMATCH/);
+});
+```
+
+## 3. 家族聚合回归（openai 协议族）
+
+针对 `glm/lmstudio/iflow`：
+
+- 入站：构造 openai-chat 形状请求 + 注入 runtime metadata（providerType='openai', providerId='glm' 等），
+  - 断言：最小清理生效（如 GLM 删除 tools[].function.strict/无 tools 时删除 tool_choice）。
+- 返回：构造上游 JSON 响应，调用 `applyResponse`，
+  - 断言：非流式响应黑名单仅在非 `/v1/responses` 入口时生效（依据 metadata.entryEndpoint）。
+
+针对 `qwen`：
+
+- 断言聚合器保持 OpenAI 形状，不走“input/parameters”改形状路径。
+
+## 4. SSE 路径验证（Responses）
+
+- 使用 ResponsesHttpProvider 发送请求（或模拟 sendRequestInternal 的 SSE 分支），
+- 断言：
+  - Provider 对 Host 返回 JSON（内部会将上游 SSE 解析为 JSON），
+  - 不透传 `__sse_stream`，Client 方向 SSE 由 llmswitch-core 管理。
+
+## 5. 验证脚本适配说明
+
+`npm run build:verify` 当前蓝图依赖独立 virtualRouter 节点；本次变更将虚拟路由器并入 llmswitch-core，
+因此需要更新验证脚本或切换到新的蓝图：
+
+- 方案 A：更新脚本以读取 BasePipeline 注入的 `providerProtocol` 元信息；
+- 方案 B：提供新的验证蓝图（不依赖独立 virtualRouter 节点），通过 `orchestrator.resolve(entry, { providerProtocol, processMode })` 选择。
+
+待测试蓝图更新后，本用例将纳入 CI。
+
+## 6. 全局 Dry-Run（路径 & 快照）
+
+为方便批量验证兼容层/虚拟路由/ProviderComposite 的执行路径，新增脚本
+`scripts/pipeline-dry-run.mjs`：
+
+```
+npm run build
+node scripts/pipeline-dry-run.mjs \
+  --config ~/.routecodex/config.json \
+  --samples ~/.routecodex/codex-samples \
+  --out demo-results/pipeline-dryrun
+```
+
+- 脚本会使用 `PipelineAssembler` + `VirtualRouterModule` 组装流水线，
+  并从 `codex-samples/openai-chat|openai-responses|anthropic-messages` 中读取
+  `*_http-request.json` 逐条重放（默认每类全部，可用 `--limit` 限制）。
+- Provider 阶段仍通过现有 ProviderComposite/HTTP provider 走完整链路，但因为使用
+  本地请求不会访问真实上游；所有快照写入 `--out/snapshots`（可通过
+  `ROUTECODEX_SNAPSHOT_BASE` 自定义）。
+- 每个请求都会生成 `summary.json` 结构，包含 `routeName`、`pipelineId`、
+  provider target、执行耗时以及 `pathSignature`（按节点顺序汇总）。
+- 快照沿用 `llmswitch-core` 的 `pipeline.aggregate`、`compat.pre/post`、
+  `provider.request/response`，可直接在现有界面或分析脚本中解析。
+
+通过该 dry-run 输出的路径数据，可以快速核对“虚拟路由 → chat-process →
+provider-composite → provider-http → response-process”的实际执行链，
+避免在没有真实上游的环境中手动重复验证。

package/docs/providers/provider-type-only-migration.md

@@ -0,0 +1,111 @@
+# Provider 按协议类型划分（Type-only）迁移指南
+
+本文档描述从“按品牌/家族（glm/qwen/iflow/lmstudio）”到“按协议类型（openai/responses/anthropic/gemini）”的迁移要求与示例。
+
+## 目标
+
+- Provider 仅以协议类型作为 `providerType`：
+  - `openai`（OpenAI Chat wire）
+  - `responses`（OpenAI Responses wire）
+  - `anthropic`（Anthropic Messages wire）
+  - `gemini`（预留）
+- 品牌/家族名仅通过 `providerId` 标识；OAuth 方案使用 `auth.type = "<provider>-oauth"` 显式声明。
+- `providerProtocol` 由 BasePipeline 路由阶段注入，Provider/Composite 只做守卫，不自行推断。
+
+## 迁移规则
+
+1. 配置层
+   - 将原 `providerType: 'glm'|'qwen'|'iflow'|'lmstudio'` 替换为 `providerType: 'openai'`。
+   - 将家族名写入：
+     - `providerId`（路由家族）；
+     - `auth.type = "<provider>-oauth"`（OAuth 场景）。
+   - Responses/Anthropic 按照协议类型分别设置 `providerType: 'responses' | 'anthropic'`。
+
+2. 代码层
+   - Factory 改为 protocol-first 选择 Provider；对旧配置自动规范化并打印告警。
+   - 兼容逻辑内聚到 ProviderComposite，品牌差异由 openai-compat-aggregator 内部处理（最小清理）。
+
+## 配置示例
+
+### Qwen（OAuth）
+
+```json
+{
+  "type": "openai-standard",
+  "config": {
+    "providerType": "openai",
+    "baseUrl": "https://portal.qwen.ai/v1",
+    "auth": { "type": "qwen-oauth" },
+    "models": ["qwen3-coder-plus"]
+  }
+}
+```
+
+### GLM（API Key）
+
+```json
+{
+  "type": "openai-standard",
+  "config": {
+    "providerType": "openai",
+    "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
+    "auth": { "type": "apikey", "apiKeyEnv": "GLM_API_KEY" },
+    "models": ["glm-4"]
+  }
+}
+```
+
+### iFlow（OAuth）
+
+```json
+{
+  "type": "openai-standard",
+  "config": {
+    "providerType": "openai",
+    "baseUrl": "https://api.iflow.com/v1",
+    "auth": { "type": "iflow-oauth" },
+    "models": ["iflow-gpt4-1106"]
+  }
+}
+```
+
+### Responses（真实 /v1/responses wire）
+
+```json
+{
+  "type": "responses-http-provider",
+  "config": {
+    "providerType": "responses",
+    "baseUrl": "https://api.openai.com/v1",
+    "auth": { "type": "apikey", "apiKeyEnv": "OPENAI_API_KEY" }
+  }
+}
+```
+
+### Anthropic Messages
+
+```json
+{
+  "type": "anthropic-http-provider",
+  "config": {
+    "providerType": "anthropic",
+    "baseUrl": "https://api.anthropic.com/v1",
+    "auth": { "type": "apikey", "apiKeyEnv": "ANTHROPIC_API_KEY" }
+  }
+}
+```
+
+## 运行期元数据（供调试校验）
+
+`attachProviderRuntimeMetadata(payload, meta)` 注入字段：
+
+```ts
+{
+  requestId, pipelineId, routeName,
+  providerId, providerKey,
+  providerType, providerProtocol,
+  target: { model, providerType, providerKey }
+}
+```
+
+ProviderComposite 在出/入站两侧校验 `providerType → providerProtocol`，并对协议形状做最小断言，快速暴露错配。

package/docs/rccx-wasm-migration.md

@@ -0,0 +1,74 @@
+# rccx wasm 接入说明（Host 视角）
+
+## 三条 CLI 路线的角色划分
+
+- `routecodex`（dev CLI）
+  - 面向本地开发与调试，始终使用仓库下的 `sharedmodule/llmswitch-core` 源码。
+  - 通过 `npm run llmswitch:link` / `npm run config:use-local` 把本地 llmswitch-core 链接到 `node_modules/@jsonstudio/llms`。
+- `rcc`（release CLI）
+  - 发布到 npm 的正式包：`@jsonstudio/rcc`。
+  - 由 `npm run publish:rcc` 生成 tarball 并 `npm publish`，构建时依赖 npm 上的 `@jsonstudio/llms`（TS 实现）。
+- `rccx`（wasm CLI，实验/内部使用）
+  - 使用 `@jsonstudio/llms-wasm`（wasm 引擎）作为 llms 核心实现。
+  - 通过 npm alias 保持 Host import 形状不变：源码仍然 `import ... from '@jsonstudio/llms'`，但在 rccx 包内该依赖会被重写为 `@jsonstudio/llms-wasm`。
+
+> 约束：按照 `AGENTS.md`，正式发布渠道仍然只使用 `@jsonstudio/rcc`；`routecodex` 和 `rccx` 保持在本地/内部使用范围内。
+
+## 依赖与打包策略
+
+- 根 `package.json` 继续声明：
+  - `@jsonstudio/llms`: `^0.6.x`（供 routecodex / rcc 构建使用）。
+- `scripts/pack-mode.mjs` 在打包 rccx 时（`--name @jsonstudio/rccx --bin rccx`）会：
+  - 将 `package.json.name` 设置为 `@jsonstudio/rccx`，`bin` 设置为 `{ "rccx": "dist/cli.js" }`。
+  - 清空 `bundledDependencies` / `bundleDependencies`，改为普通 `dependencies`。
+  - 在 `dependencies` 中应用 alias：
+    - 移除原有的 `@jsonstudio/llms` 直连依赖；
+    - 增加：
+      - `"@jsonstudio/llms": "npm:@jsonstudio/llms-wasm@^0.1.0"`
+      - `"@jsonstudio/llms-wasm": "^0.1.0"`
+  - 这样，安装 `@jsonstudio/rccx` 时，`require('@jsonstudio/llms')` 实际会加载 wasm 版本实现。
+
+> 注意：`pack-mode.mjs` 只在打包阶段临时修改 `package.json`，打包完成后会恢复原始文件。
+
+## 构建 rccx（本地）
+
+1. 确保本机已经有可用的 `@jsonstudio/llms-wasm`：
+   - 要么从 `sharedmodule/llms-wasm` 构建并发布到私有 npm；
+   - 要么通过本地 tarball 安装到全局/工程级 npm registry（版本号需满足 `^0.1.0`）。
+2. 在 routecodex 仓库根目录执行：
+   ```bash
+   npm run build:rccx
+   ```
+   - 这会先执行 `npm run build:min`（使用当前 BUILD_MODE 构建 dist）；
+   - 然后调用：
+     ```bash
+     node scripts/pack-mode.mjs --name @jsonstudio/rccx --bin rccx
+     ```
+   - 完成后仓库根目录会出现一个 `jsonstudio-rccx-<version>.tgz`。
+3. 在目标环境中安装 rccx：
+   ```bash
+   npm install -g ./jsonstudio-rccx-<version>.tgz
+   ```
+
+## 运行与行为确认
+
+- `rccx` CLI 行为与 `routecodex` / `rcc` 相同：
+  - `rccx start` 启动同一套 HTTP server，端口仍由 RouteCodex 配置决定（默认 5555）。
+  - `rccx code` / `rccx config` 等子命令全部复用现有 CLI 逻辑。
+- 不同点只在于 llms 实现：
+  - `rcc` 使用 npm 上的 `@jsonstudio/llms`（TS 实现）；
+  - `rccx` 使用 npm 上的 `@jsonstudio/llms-wasm`（wasm 引擎，通过 alias 暴露为 `@jsonstudio/llms`）。
+
+## 黑盒对比建议（可选）
+
+为确保 wasm 版本行为与 TS 版本一致，建议在同一份 RouteCodex 配置下做一轮回放对比：
+
+- 启动两个实例：
+  - `routecodex`（或 `rcc`）使用 TS 版 llms；
+  - `rccx` 使用 wasm 版 llms。
+- 对同一组请求（尤其是 sticky / health / 429 / series cooldown / Gemini compat 等场景）：
+  - 比较日志中的 `virtual-router-hit` / `providerKey` / sticky 选择与健康状态；
+  - 确认两侧路由决策与工具调用行为一致。
+
+后续每次升级 `@jsonstudio/llms` / `@jsonstudio/llms-wasm` 时，可以复用这一套回放作为回归校验。
+