mslxdff 0.1.203 → 0.1.208

package/src/anthropic/request-body.js

@@ -1,126 +1,183 @@
-// 请求侧翻译：Anthropic Messages 请求体 → OpenAI chat 请求体（/v1/messages 外壳，ADR-0047）。
-// 从 translate.js 拆出（ADR-0055）：translate.js 贴 20KB 体积硬门，且「入站请求形状」与
-// 「出站响应/usage 翻译」本就是两向关注点，拆后 translate.js 单向 import 本文件，不回环。
-// 对外接口不变：调用方与测试仍从 anthropic/translate.js import（那边 re-export）。
-//
-// 纪律（别改回去）：
-//  * 思考档位**原样透传**（thinking/effort/reasoning_effort/reasoningEffort/extra_body），语义归一交给
-//    各 provider 与 src/thinking-effort.js —— 旧版在此丢掉，下游被迫补默认值（workbuddy 恒 high，ADR-0053）；
-//  * 但**必须主动丢** output_config 原始对象 / context_management / 消息块内 thinking：Claude Code 对
-//    不认识的 model ID 照发全套字段，块内 thinking 无法签发 signature，回传必被上游拒（ADR-0047）。
-import { isServerTool } from "./web-search.js";
-import { newToolUseId } from "./shared.js";
-
-// system 允许字符串或 text 块数组；块间空行连接（缓存语义不保留，上游是 OpenAI）
-function systemTextOf(system) {
-  if (typeof system === "string") return system;
-  if (!Array.isArray(system)) return "";
-  return system.map((b) => (b && typeof b.text === "string" ? b.text : "")).filter(Boolean).join("\n\n");
-}
-
-function imagePartOf(block) {
-  const src = block?.source || {};
-  if (src.type === "base64" && src.data) {
-    return { type: "image_url", image_url: { url: `data:${src.media_type || "image/png"};base64,${src.data}` } };
-  }
-  if (src.type === "url" && src.url) return { type: "image_url", image_url: { url: String(src.url) } };
-  return null;
-}
-
-export function toolResultTextOf(content) {
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) {
-    return content
-      .map((p) => (typeof p === "string" ? p : p && typeof p.text === "string" ? p.text : ""))
-      .filter(Boolean)
-      .join("\n");
-  }
-  return content == null ? "" : String(content);
-}
-
-/** Anthropic Messages 请求体 → OpenAI chat 请求体（直接喂既有 ChatPipeline）。 */
-export function messagesToChatBody(req = {}) {
-  const model = String(req.model || "").trim();
-  if (!model) throw new Error("messages: 缺少 model");
-  const messages = [];
-  const sys = systemTextOf(req.system);
-  if (sys) messages.push({ role: "system", content: sys });
-
-  // 重复 tool_use_id 保首个、丢后续：客户端重试/重放历史会把同一工具结果存两份，
-  // 部分上游按 call_id 查重直接 400（同 responses/translate.js:57-59 的实测教训）。
-  const seenToolResult = new Set();
-
-  for (const m of Array.isArray(req.messages) ? req.messages : []) {
-    if (!m || typeof m !== "object") continue;
-    // role=system/developer 必须保留：Claude Code ≥2.1.286 的 mid-conversation system beta 就往 messages[] 里塞系统指令，
-    const role = m.role === "assistant" ? "assistant" : m.role === "system" || m.role === "developer" ? "system" : "user";
-    const blocks = typeof m.content === "string" ? [{ type: "text", text: m.content }] : Array.isArray(m.content) ? m.content : [];
-    let text = "";
-    const imgs = [];
-    const toolCalls = [];
-    for (const b of blocks) {
-      if (!b || typeof b !== "object") continue;
-      if (b.type === "text") text += typeof b.text === "string" ? b.text : "";
-      else if (b.type === "image") { const p = imagePartOf(b); if (p) imgs.push(p); }
-      else if (b.type === "tool_use") {
-        let args = "{}";
-        try { args = JSON.stringify(b.input ?? {}); } catch { args = "{}"; }
-        toolCalls.push({ id: String(b.id || newToolUseId()), type: "function", function: { name: String(b.name || ""), arguments: args } });
-      } else if (b.type === "tool_result") {
-        // tool 消息必须先于同轮 user 文本进数组：OpenAI 侧要求 role:tool 紧跟其 assistant
-        const key = String(b.tool_use_id || "");
-        if (key) { if (seenToolResult.has(key)) continue; seenToolResult.add(key); }
-        const body = toolResultTextOf(b.content);
-        messages.push({ role: "tool", tool_call_id: key, content: b.is_error ? `[tool_error] ${body}` : body });
-      }
-      // thinking / redacted_thinking 忽略：我们无法签发 signature，回传必被上游拒（ADR-0047）
-    }
-    if (!text && !imgs.length && !toolCalls.length) continue;
-    const msg = { role, content: imgs.length ? [...(text ? [{ type: "text", text }] : []), ...imgs] : text };
-    if (toolCalls.length) msg.tool_calls = toolCalls;
-    messages.push(msg);
-  }
-  // 空会话直接 400：绝不伪造一句 "hi" 打上游（那会把假提问写进用户上下文并白烧一发额度）
-  if (!messages.some((x) => x.role !== "system")) throw new Error("messages: 缺少用户消息");
-
-  const body = { model, messages, stream: Boolean(req.stream) };
-  // 流式必须让上游把 usage 放进收尾帧，否则 message_delta.usage 恒 0（OpenAI 规范字段）。
-  // 个别上游不认 stream_options 会 400 → `MSLXDFF_ANTHROPIC_STREAM_USAGE=0` 关掉。
-  if (body.stream && process.env.MSLXDFF_ANTHROPIC_STREAM_USAGE !== "0") body.stream_options = { include_usage: true };
-  // Anthropic 的 server tool（web_search_*/web_fetch_*/…）没有 input_schema，折成假 function 会
-  // 让上游收到「空参数空描述」的工具（严格端点直接 422），本网关不实现的发前一律剥除（ADR-0049）。
-  const fnTools = (Array.isArray(req.tools) ? req.tools : []).filter((t) => !isServerTool(t));
-  if (fnTools.length) {
-    body.tools = fnTools.map((t) => ({
-      type: "function",
-      function: { name: String(t?.name || ""), description: String(t?.description || ""), parameters: t?.input_schema || {} },
-    }));
-  }
-  const keptNames = new Set(fnTools.map((t) => String(t?.name || "")));
-  const tc = req.tool_choice;
-  if (tc === "auto" || (tc && typeof tc === "object" && tc.type === "auto")) body.tool_choice = "auto";
-  else if (tc && typeof tc === "object" && tc.type === "any") body.tool_choice = "required";
-  // 点名一个已被剥掉的工具时降为 auto：上游会按不存在的函数强制点名，那样一定拿不到有用回答
-  else if (tc && typeof tc === "object" && tc.type === "tool") body.tool_choice = keptNames.has(String(tc.name || "")) ? { type: "function", function: { name: String(tc.name || "") } } : "auto";
-  else if (tc && typeof tc === "object" && tc.type === "none") body.tool_choice = "none";
-  if (req.max_tokens != null && Number.isFinite(Number(req.max_tokens))) body.max_tokens = Number(req.max_tokens);
-  if (req.temperature != null) body.temperature = req.temperature;
-  if (req.top_p != null) body.top_p = req.top_p;
-  if (Array.isArray(req.stop_sequences) && req.stop_sequences.length) body.stop = req.stop_sequences;
-  // 思考档位原样透传（不解释语义，语义归一交给各 provider / src/thinking-effort.js）：
-  // 客户端显式声明必须一路带到上游，旧版在此丢掉 → 下游被迫补默认值（workbuddy 恒 high）。
-  if (req.thinking != null) body.thinking = req.thinking;
-  // 档位载体只收「非空 trimmed 字符串」：空串声明不算声明，不该发出去顶掉下游默认值。
-  for (const k of ["effort", "reasoning_effort", "reasoningEffort"]) {
-    const v = typeof req[k] === "string" ? req[k].trim() : "";
-    if (v) body[k] = v;
-  }
-  if (req.extra_body != null) body.extra_body = req.extra_body;
-  // output_config.effort 是 Claude Code 的另一档位载体（beta），原始对象上游不认故不外发，
-  // 但档位本身不能丢 → 归一到 reasoning_effort（客户端已显式声明时以声明为准）。
-  const ocEffort = req.output_config && typeof req.output_config === "object" ? req.output_config.effort : undefined;
-  if (ocEffort != null && body.reasoning_effort == null && body.reasoningEffort == null) {
-    body.reasoning_effort = ocEffort;
-  }
-  return body;
-}
+// 请求侧翻译：Anthropic Messages 请求体 → OpenAI chat 请求体（/v1/messages 外壳，ADR-0047）。
+// 从 translate.js 拆出（ADR-0055）：translate.js 贴 20KB 体积硬门，且「入站请求形状」与
+// 「出站响应/usage 翻译」本就是两向关注点，拆后 translate.js 单向 import 本文件，不回环。
+// 对外接口不变：调用方与测试仍从 anthropic/translate.js import（那边 re-export）。
+//
+// 形状对齐（1:1 照抄 cc-switch `src-tauri/src/proxy/providers/transform.rs:236-402`，只服务 /v1/messages）：
+//  * system 块间用 "\n" 拼成**一条**；逐块剥开头的 `x-anthropic-billing-header:` 行（#2350：
+//    该行带轮换 `cch=`，留在前缀位置会让上游前缀缓存每轮失效 → 每轮全量 prefill）；
+//  * `tool_use.arguments` 走 canonical JSON；出站体整体 canonicalize（键序恒定 = 字节前缀稳定）；
+//  * tool_result 里的媒体外移成一条 user 消息（改前是静默丢图）；
+//  * tools 过滤 `BatchTool`、description 缺省不写、`input_schema` 过 cleanToolSchema；
+//  * o 系列 `max_tokens` → `max_completion_tokens`；`stream_options` 改 merge 不覆盖。
+//
+// 纪律（别改回去）：
+//  * 思考档位**原样透传**（thinking/effort/reasoning_effort/reasoningEffort/extra_body），语义归一交给
+//    各 provider 与 src/thinking-effort.js —— 旧版在此丢掉，下游被迫补默认值（workbuddy 恒 high，ADR-0053）；
+//    此处刻意**不**照抄 cc-switch 的 thinking→reasoning_effort 本地映射表（transform.rs:100-190）；
+//  * 但**必须主动丢** output_config 原始对象 / context_management / 消息块内 thinking：Claude Code 对
+//    不认识的 model ID 照发全套字段，块内 thinking 无法签发 signature，回传必被上游拒（ADR-0047）；
+//  * 空会话抛错，绝不伪造一句 "hi" 打上游（会把假提问写进用户上下文并白烧一发额度）；
+//  * tool_result 重复 tool_use_id 保首个、丢后续（部分上游按 call_id 查重直接 400）；
+//    `is_error` 保留 `[tool_error]` 前缀（上游可见的错误信号，别照抄 cc-switch 丢掉）。
+import { isServerTool } from "./web-search.js";
+import { newToolUseId } from "./shared.js";
+import { canonicalJson, canonicalizeValue } from "./canonical-json.js";
+import { stripLeadingBillingHeader, cleanToolSchema, isOpenAiOSeries } from "./request-shape.js";
+import { imagePartOf, planToolResultMedia, queueToolMedia, flushToolMedia } from "./tool-media.js";
+
+// system 允许字符串或 text 块数组；块间用 "\n" 连接（照抄 cc-switch：跨轮字节稳定）。
+// 逐块剥开头的计费头：它每轮变一次，是前缀缓存失效的头号嫌疑人（cc-switch #2350）。
+function systemTextOf(system) {
+  const one = (t) => stripLeadingBillingHeader(typeof t === "string" ? t : "");
+  if (typeof system === "string") return one(system);
+  if (!Array.isArray(system)) return "";
+  return system
+    .map((b) => one(b && typeof b.text === "string" ? b.text : ""))
+    .filter(Boolean)
+    .join("\n");
+}
+
+/** tool_result 的 content → 纯文本（字符串原样；块数组取各 text；其余 String()）。 */
+export function toolResultTextOf(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((p) => (typeof p === "string" ? p : p && typeof p.text === "string" ? p.text : ""))
+      .filter(Boolean)
+      .join("\n");
+  }
+  return content == null ? "" : String(content);
+}
+
+/** Anthropic Messages 请求体 → OpenAI chat 请求体（直接喂既有 ChatPipeline）。 */
+export function messagesToChatBody(req = {}) {
+  const model = String(req.model || "").trim();
+  if (!model) throw new Error("messages: 缺少 model");
+  const messages = [];
+  const sys = systemTextOf(req.system);
+  if (sys) messages.push({ role: "system", content: sys });
+
+  // 重复 tool_use_id 保首个、丢后续：客户端重试/重放历史会把同一工具结果存两份，
+  // 部分上游按 call_id 查重直接 400（同 responses/translate.js:57-59 的实测教训）。
+  const seenToolResult = new Set();
+  // 工具结果里的媒体暂存：同轮普通消息之前冲成一条 user 消息（Chat 的 tool 消息不能带图分片）
+  const pendingMedia = [];
+
+  for (const m of Array.isArray(req.messages) ? req.messages : []) {
+    if (!m || typeof m !== "object") continue;
+    // role=system/developer 必须保留：Claude Code ≥2.1.286 的 mid-conversation system beta 就往 messages[] 里塞系统指令，
+    const role = m.role === "assistant" ? "assistant" : m.role === "system" || m.role === "developer" ? "system" : "user";
+    if (typeof m.content === "string") {
+      if (m.content) messages.push({ role, content: m.content });
+      continue;
+    }
+    const blocks = Array.isArray(m.content) ? m.content : null;
+    if (!blocks) {
+      if (m.content != null) messages.push({ role, content: m.content }); // 其它形状原样透传
+      continue;
+    }
+    const parts = []; // text / image 分片（照抄 cc-switch 的 content_parts）
+    const toolCalls = [];
+    for (const b of blocks) {
+      if (!b || typeof b !== "object") continue;
+      if (b.type === "text") {
+        if (typeof b.text === "string" && b.text) parts.push({ type: "text", text: b.text });
+      } else if (b.type === "image") {
+        const p = imagePartOf(b);
+        if (p) parts.push(p);
+      } else if (b.type === "tool_use") {
+        toolCalls.push({
+          id: String(b.id || newToolUseId()),
+          type: "function",
+          function: { name: String(b.name || ""), arguments: canonicalJson(b.input ?? {}) },
+        });
+      } else if (b.type === "tool_result") {
+        // tool 消息必须先于同轮 user 文本进数组：OpenAI 侧要求 role:tool 紧跟其 assistant
+        const key = String(b.tool_use_id || "");
+        if (key) { if (seenToolResult.has(key)) continue; seenToolResult.add(key); }
+        const plan = planToolResultMedia(b.content, canonicalJson);
+        let text;
+        if (plan) { queueToolMedia(pendingMedia, key, plan.media); text = plan.text; }
+        else text = toolResultTextOf(b.content);
+        messages.push({ role: "tool", tool_call_id: key, content: b.is_error ? `[tool_error] ${text}` : text });
+      }
+      // thinking / redacted_thinking 忽略：我们无法签发 signature，回传必被上游拒（ADR-0047）
+    }
+    // 媒体先给、再给同轮普通内容（照抄 cc-switch transform.rs:517 的顺序）
+    flushToolMedia(messages, pendingMedia);
+    if (!parts.length && !toolCalls.length) continue;
+    // 单 text 分片化简成纯字符串；无分片给 null（照抄 transform.rs:524-535）
+    const content = parts.length === 0 ? null
+      : parts.length === 1 && parts[0].type === "text" ? parts[0].text
+        : parts;
+    const msg = { role, content };
+    if (toolCalls.length) msg.tool_calls = toolCalls;
+    messages.push(msg);
+  }
+  flushToolMedia(messages, pendingMedia); // 尾部残余（末条就是工具轮时）
+  // 空会话直接 400：绝不伪造一句 "hi" 打上游（那会把假提问写进用户上下文并白烧一发额度）
+  if (!messages.some((x) => x.role !== "system")) throw new Error("messages: 缺少用户消息");
+
+  const body = { model, messages, stream: Boolean(req.stream) };
+  // o 系列必须用 max_completion_tokens（照抄 cc-switch transform.rs:278-286）
+  if (req.max_tokens != null && Number.isFinite(Number(req.max_tokens))) {
+    if (isOpenAiOSeries(model)) body.max_completion_tokens = Number(req.max_tokens);
+    else body.max_tokens = Number(req.max_tokens);
+  }
+  if (req.temperature != null) body.temperature = req.temperature;
+  if (req.top_p != null) body.top_p = req.top_p;
+  if (Array.isArray(req.stop_sequences) && req.stop_sequences.length) body.stop = req.stop_sequences;
+  // 思考档位原样透传（不解释语义，语义归一交给各 provider / src/thinking-effort.js）：
+  // 客户端显式声明必须一路带到上游，旧版在此丢掉 → 下游被迫补默认值（workbuddy 恒 high）。
+  if (req.thinking != null) body.thinking = req.thinking;
+  // 档位载体只收「非空 trimmed 字符串」：空串声明不算声明，不该发出去顶掉下游默认值。
+  for (const k of ["effort", "reasoning_effort", "reasoningEffort"]) {
+    const v = typeof req[k] === "string" ? req[k].trim() : "";
+    if (v) body[k] = v;
+  }
+  if (req.extra_body != null) body.extra_body = req.extra_body;
+  // output_config.effort 是 Claude Code 的另一档位载体（beta），原始对象上游不认故不外发，
+  // 但档位本身不能丢 → 归一到 reasoning_effort（客户端已显式声明时以声明为准）。
+  const ocEffort = req.output_config && typeof req.output_config === "object" ? req.output_config.effort : undefined;
+  if (ocEffort != null && body.reasoning_effort == null && body.reasoningEffort == null) {
+    body.reasoning_effort = ocEffort;
+  }
+  // 流式必须让上游把 usage 放进收尾帧，否则 message_delta.usage 恒 0（OpenAI 规范字段）。
+  // 照抄 cc-switch transform.rs:349-365：**merge** 客户端既有 stream_options，而不是整段覆盖。
+  // 个别上游不认 stream_options 会 400 → `MSLXDFF_ANTHROPIC_STREAM_USAGE=0` 关掉。
+  if (body.stream && process.env.MSLXDFF_ANTHROPIC_STREAM_USAGE !== "0") {
+    const opts = req.stream_options && typeof req.stream_options === "object" ? req.stream_options : {};
+    body.stream_options = { ...opts, include_usage: true };
+  }
+  // Anthropic 的 server tool（web_search_*/web_fetch_*/…）没有 input_schema，折成假 function 会
+  // 让上游收到「空参数空描述」的工具（严格端点直接 422），本网关不实现的发前一律剥除（ADR-0049）；
+  // 另外照抄 cc-switch 剥 `BatchTool`、description 缺省不写、schema 过 cleanToolSchema。
+  const fnTools = (Array.isArray(req.tools) ? req.tools : [])
+    .filter((t) => !isServerTool(t))
+    .filter((t) => String(t?.type || "") !== "BatchTool");
+  if (fnTools.length) {
+    body.tools = fnTools.map((t) => {
+      const fn = { name: String(t?.name || "") };
+      if (typeof t?.description === "string" && t.description) fn.description = t.description;
+      fn.parameters = cleanToolSchema(t?.input_schema ?? {});
+      return { type: "function", function: fn };
+    });
+  }
+  const keptNames = new Set(fnTools.map((t) => String(t?.name || "")));
+  const tc = req.tool_choice;
+  if (typeof tc === "string") {
+    // 字符串形态：Anthropic 的 "any" → OpenAI 的 "required"（照抄 transform.rs:381-386）
+    if (tc === "any") body.tool_choice = "required";
+    else if (tc) body.tool_choice = tc;
+  } else if (tc && typeof tc === "object") {
+    if (tc.type === "auto") body.tool_choice = "auto";
+    else if (tc.type === "any") body.tool_choice = "required";
+    // 点名一个已被剥掉的工具时降为 auto：上游会按不存在的函数强制点名，那样一定拿不到有用回答
+    else if (tc.type === "tool") body.tool_choice = keptNames.has(String(tc.name || "")) ? { type: "function", function: { name: String(tc.name || "") } } : "auto";
+    else if (tc.type === "none") body.tool_choice = "none";
+  }
+  // 出站体键序规范化：同一逻辑内容必然产出同一份字节 → 上游前缀缓存能稳定命中
+  // （照抄 cc-switch forwarder.rs prepare_upstream_request_body / json_canonical.rs）。
+  return canonicalizeValue(body);
+}

package/src/anthropic/request-shape.js

@@ -0,0 +1,60 @@
+/**
+ * /v1/messages 请求形状的「取稳与清洗」原语 —— 1:1 照抄 cc-switch。
+ *
+ * 三件套：
+ *  1. `stripLeadingBillingHeader` —— 剥 system 文本**开头**的 `x-anthropic-billing-header:` 行
+ *     （照抄 transform.rs:17-55，对应 cc-switch #2350）。Claude Code 会把含轮换 `cch=` 的
+ *     计费头塞在 system 最前面；它每轮变一次 → 整条前缀缓存失效 → 每轮全量 prefill。
+ *     只在开头剥，后文再出现同样的字符串一律保留（那是用户自己写的内容）。
+ *  2. `cleanToolSchema` —— 工具参数 schema 清洗（照抄 transform.rs:563-594）：根缺 `type` 时补
+ *     `"object"` 并顺带补 `properties: {}`，全树删 `format: "uri"`（严格上游会拒），嵌套递归。
+ *  3. `isOpenAiOSeries` —— o 系列（o1/o3/o4…）需 `max_completion_tokens` 而非 `max_tokens`
+ *     （照抄 transform.rs:57-63 的意图；本仓模型 id 带供应商前缀，故按末段判定）。
+ */
+
+const BILLING_HEADER_PREFIX = "x-anthropic-billing-header:";
+
+/**
+ * 剥 system 开头的计费头行（含紧随的一个空行）。
+ * 无换行（整段就是这一行）→ 返回空串，与 cc-switch 一致。
+ * @param {unknown} text
+ * @returns {string}
+ */
+export function stripLeadingBillingHeader(text) {
+  const s = typeof text === "string" ? text : "";
+  if (!s.startsWith(BILLING_HEADER_PREFIX)) return s;
+  const nl = s.search(/[\r\n]/);
+  if (nl < 0) return "";
+  let rest = s.slice(nl + 1);
+  if (s[nl] === "\r" && rest.startsWith("\n")) rest = rest.slice(1);
+  if (rest.startsWith("\r\n")) return rest.slice(2);
+  if (rest.startsWith("\n") || rest.startsWith("\r")) return rest.slice(1);
+  return rest;
+}
+
+/** 递归清洗一份 JSON schema（不修改入参：每层都产新对象）。 */
+export function cleanToolSchema(schema) {
+  return cleanSchemaInner(schema, true);
+}
+
+function cleanSchemaInner(schema, isRoot) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return schema;
+  const out = { ...schema };
+  const missingType = isRoot && !("type" in out);
+  if (missingType) out.type = "object";
+  if (missingType && !("properties" in out)) out.properties = {};
+  if (out.format === "uri") delete out.format;
+  if (out.properties && typeof out.properties === "object" && !Array.isArray(out.properties)) {
+    const props = {};
+    for (const k of Object.keys(out.properties)) props[k] = cleanSchemaInner(out.properties[k], false);
+    out.properties = props;
+  }
+  if (out.items !== undefined) out.items = cleanSchemaInner(out.items, false);
+  return out;
+}
+
+/** OpenAI o 系列（o1/o3/o4-mini…）：只看 id 末段，避免供应商前缀（如 `openai/o3`）干扰。 */
+export function isOpenAiOSeries(model) {
+  const id = String(model || "").split("/").pop() || "";
+  return /^o\d(?:$|[-.])/.test(id.toLowerCase());
+}

package/src/anthropic/session-id.js

@@ -0,0 +1,58 @@
+/**
+ * Claude 系会话身份提取 —— 1:1 照抄 cc-switch `src-tauri/src/proxy/session.rs:107-231`（Claude 分支）。
+ *
+ * 为什么需要：会话 id 用来给上游做「缓存亲和 / 粘性路由」（`prompt_cache_key`、会话头）。
+ * cc-switch #8236 的教训是：拿不到真实会话身份就每轮生成一个新 id ⇒ 每轮换缓存 key ⇒
+ * 前缀缓存永不命中。Claude Code 走 `/v1/messages` 时把会话身份放在**请求体 metadata**里
+ * （不是 header），所以只读 header 的实现会一路漏。
+ *
+ * 优先级（与 cc-switch 一致）：
+ *  1. header `x-claude-code-session-id`，再 `claude-code-session-id`（非空即用：**不 trim、无长度门槛**）
+ *  2. `metadata.user_id`：trim 后以 `{` 开头 → 当 JSON 解析取 `session_id`（trim 后非空才认）；
+ *     否则找字面量 `_session_`，取其后的整段（旧格式）
+ *  3. `metadata.session_id`（字符串，trim 后非空）
+ *  4. 都没有 → 返回 null（由调用方走既有兜底，绝不在这里凭空生成：生成值会每轮变）
+ *
+ * 明确不用（cc-switch 同款判断）：Responses 的 `previous_response_id` 之类「每轮变化的响应游标」
+ * 不是稳定会话身份，当成缓存 key 会导致每轮换 key。
+ */
+
+const CLAUDE_SESSION_HEADERS = ["x-claude-code-session-id", "claude-code-session-id"];
+const LEGACY_MARKER = "_session_";
+
+/** `metadata.user_id` → 会话 id（JSON 里的 session_id，或旧 `_session_` 后缀）。 */
+function sessionFromUserId(userId) {
+  const t = typeof userId === "string" ? userId.trim() : "";
+  if (!t) return null;
+  if (t.startsWith("{")) {
+    try {
+      const j = JSON.parse(t);
+      const s = typeof j?.session_id === "string" ? j.session_id.trim() : "";
+      return s || null;
+    } catch {
+      return null; // 坏 JSON：不猜，交下一档
+    }
+  }
+  const i = t.indexOf(LEGACY_MARKER);
+  if (i < 0) return null;
+  return t.slice(i + LEGACY_MARKER.length) || null;
+}
+
+/**
+ * @param {Record<string, unknown>} headers 入站头（Node 已小写化）
+ * @param {any} body 原始 Anthropic 请求体
+ * @returns {{sessionId: string, source: string} | null}
+ */
+export function claudeSessionId(headers = {}, body = null) {
+  for (const name of CLAUDE_SESSION_HEADERS) {
+    const v = headers?.[name];
+    if (typeof v === "string" && v) return { sessionId: v, source: "header" };
+  }
+  const meta = body && typeof body === "object" && body.metadata && typeof body.metadata === "object" ? body.metadata : null;
+  if (!meta) return null;
+  const fromUser = sessionFromUserId(meta.user_id);
+  if (fromUser) return { sessionId: fromUser, source: "metadata.user_id" };
+  const sid = typeof meta.session_id === "string" ? meta.session_id.trim() : "";
+  if (sid) return { sessionId: sid, source: "metadata.session_id" };
+  return null;
+}

package/src/anthropic/shared.js

@@ -1,18 +1,18 @@
-// /v1/messages 外壳的公共原语：消息/工具 id 与 Anthropic 协议错误体。
-// ADR-0055 把请求侧拆去 request-body.js 时独立成档，让 request-body.js 与 translate.js 单向依赖它，
-// 避免两文件互相 import 成环（函数提升虽能跑，顶层常量会 TDZ，属定时炸弹）。
-// 共用面：src/anthropic/request-body.js（newToolUseId）、src/anthropic/translate.js（newMessageId/
-// newToolUseId，并对外 re-export 三个符号，调用方与测试的 import 路径不变）。
-
-let seq = 0;
-export function newMessageId() {
-  return `msg_${Date.now().toString(36)}${(seq++).toString(36)}`;
-}
-export function newToolUseId() {
-  return `toolu_${Date.now().toString(36)}${(seq++).toString(36)}`;
-}
-
-/** Anthropic 协议错误体形状（非流式 JSON 与流式 in-band error 帧共用）。 */
-export function anthropicError(type, message) {
-  return { type: "error", error: { type: String(type || "api_error"), message: String(message || "error").slice(0, 500) } };
-}
+// /v1/messages 外壳的公共原语：消息/工具 id 与 Anthropic 协议错误体。
+// ADR-0055 把请求侧拆去 request-body.js 时独立成档，让 request-body.js 与 translate.js 单向依赖它，
+// 避免两文件互相 import 成环（函数提升虽能跑，顶层常量会 TDZ，属定时炸弹）。
+// 共用面：src/anthropic/request-body.js（newToolUseId）、src/anthropic/translate.js（newMessageId/
+// newToolUseId，并对外 re-export 三个符号，调用方与测试的 import 路径不变）。
+
+let seq = 0;
+export function newMessageId() {
+  return `msg_${Date.now().toString(36)}${(seq++).toString(36)}`;
+}
+export function newToolUseId() {
+  return `toolu_${Date.now().toString(36)}${(seq++).toString(36)}`;
+}
+
+/** Anthropic 协议错误体形状（非流式 JSON 与流式 in-band error 帧共用）。 */
+export function anthropicError(type, message) {
+  return { type: "error", error: { type: String(type || "api_error"), message: String(message || "error").slice(0, 500) } };
+}

package/src/anthropic/sse-aggregate.js

@@ -1,56 +1,56 @@
-// 上游只会流式、客户端要非流式时的 SSE 聚合（ADR-0055）。
-// 从 `src/routes/messages-route.js` 抽出：该文件贴着 20KB 体积硬门（20306/20480），本单要加的
-// usage 兜底接线必须先进一段，故沿用 ADR-0053 把 count_tokens 估算器拆成独立文件的同类先例。
-// 共用面：唯一调用方 `src/routes/messages-route.js`（体积门驱动的等价搬移，非新抽象）。
-//
-// 逐行吃 `data:` 帧聚成 chat.completion JSON（与 qoder/aggregate.js、zcode 非流式聚合同构），
-// 出口复用 `chatJsonToAnthropic`；一帧都没有或夹带 in-band 错误帧时返回 null，落回原有 502 + errorText
-// 路径 —— 错误绝不聚合成正文。
-
-/**
- * @param text collector 收到的原始响应体（SSE 帧序列）
- * @param model 回显给客户端的模型名
- * @returns chat.completion 形状对象，或 null（无有效帧 / 夹带错误帧）
- */
-export function sseToChatJson(text, model) {
-  let content = "";
-  let finish = "";
-  let usage = null;
-  let sawChunk = false;
-  const toolSlots = new Map();
-  for (const raw of String(text || "").split("\n")) {
-    const line = raw.trim();
-    if (!line.startsWith("data:")) continue; // 注释帧/keepalive/事件名行全跳过
-    const payload = line.slice(5).trim();
-    if (!payload || payload === "[DONE]") continue;
-    let chunk;
-    try { chunk = JSON.parse(payload); } catch { continue; }
-    if (chunk?.error) return null;
-    sawChunk = true;
-    const choice = chunk.choices?.[0] || {};
-    const delta = choice.delta || {};
-    if (choice.finish_reason) finish = choice.finish_reason;
-    if (chunk.usage) usage = chunk.usage;
-    if (typeof delta.content === "string" && delta.content) content += delta.content;
-    for (const tc of delta.tool_calls || []) {
-      const slot = Number(tc?.index ?? 0);
-      let t = toolSlots.get(slot);
-      if (!t) { t = { id: "", name: "", args: "" }; toolSlots.set(slot, t); }
-      if (tc?.id) t.id = String(tc.id);
-      if (tc?.function?.name) t.name += String(tc.function.name);
-      if (tc?.function?.arguments) t.args += String(tc.function.arguments);
-    }
-  }
-  if (!sawChunk) return null;
-  const toolCalls = [...toolSlots.values()].map((t, i) => ({ id: t.id || `call_${i}`, type: "function", function: { name: t.name, arguments: t.args || "{}" } }));
-  const message = { role: "assistant", content: content || (toolCalls.length ? null : "") };
-  if (toolCalls.length) message.tool_calls = toolCalls;
-  const out = {
-    id: "", object: "chat.completion", created: Math.floor(Date.now() / 1000), model,
-    choices: [{ index: 0, message, finish_reason: finish || (toolCalls.length ? "tool_calls" : "stop") }],
-  };
-  // 上游真报过 usage 才带这个字段：旧版合成 `{prompt_tokens:0,…}` 会把「未报」伪装成「报了 0」，
-  // 让翻译层的兜底判据永远看不到真实形状（ADR-0055 决策 3）。
-  if (usage) out.usage = usage;
-  return out;
-}
+// 上游只会流式、客户端要非流式时的 SSE 聚合（ADR-0055）。
+// 从 `src/routes/messages-route.js` 抽出：该文件贴着 20KB 体积硬门（20306/20480），本单要加的
+// usage 兜底接线必须先进一段，故沿用 ADR-0053 把 count_tokens 估算器拆成独立文件的同类先例。
+// 共用面：唯一调用方 `src/routes/messages-route.js`（体积门驱动的等价搬移，非新抽象）。
+//
+// 逐行吃 `data:` 帧聚成 chat.completion JSON（与 qoder/aggregate.js、zcode 非流式聚合同构），
+// 出口复用 `chatJsonToAnthropic`；一帧都没有或夹带 in-band 错误帧时返回 null，落回原有 502 + errorText
+// 路径 —— 错误绝不聚合成正文。
+
+/**
+ * @param text collector 收到的原始响应体（SSE 帧序列）
+ * @param model 回显给客户端的模型名
+ * @returns chat.completion 形状对象，或 null（无有效帧 / 夹带错误帧）
+ */
+export function sseToChatJson(text, model) {
+  let content = "";
+  let finish = "";
+  let usage = null;
+  let sawChunk = false;
+  const toolSlots = new Map();
+  for (const raw of String(text || "").split("\n")) {
+    const line = raw.trim();
+    if (!line.startsWith("data:")) continue; // 注释帧/keepalive/事件名行全跳过
+    const payload = line.slice(5).trim();
+    if (!payload || payload === "[DONE]") continue;
+    let chunk;
+    try { chunk = JSON.parse(payload); } catch { continue; }
+    if (chunk?.error) return null;
+    sawChunk = true;
+    const choice = chunk.choices?.[0] || {};
+    const delta = choice.delta || {};
+    if (choice.finish_reason) finish = choice.finish_reason;
+    if (chunk.usage) usage = chunk.usage;
+    if (typeof delta.content === "string" && delta.content) content += delta.content;
+    for (const tc of delta.tool_calls || []) {
+      const slot = Number(tc?.index ?? 0);
+      let t = toolSlots.get(slot);
+      if (!t) { t = { id: "", name: "", args: "" }; toolSlots.set(slot, t); }
+      if (tc?.id) t.id = String(tc.id);
+      if (tc?.function?.name) t.name += String(tc.function.name);
+      if (tc?.function?.arguments) t.args += String(tc.function.arguments);
+    }
+  }
+  if (!sawChunk) return null;
+  const toolCalls = [...toolSlots.values()].map((t, i) => ({ id: t.id || `call_${i}`, type: "function", function: { name: t.name, arguments: t.args || "{}" } }));
+  const message = { role: "assistant", content: content || (toolCalls.length ? null : "") };
+  if (toolCalls.length) message.tool_calls = toolCalls;
+  const out = {
+    id: "", object: "chat.completion", created: Math.floor(Date.now() / 1000), model,
+    choices: [{ index: 0, message, finish_reason: finish || (toolCalls.length ? "tool_calls" : "stop") }],
+  };
+  // 上游真报过 usage 才带这个字段：旧版合成 `{prompt_tokens:0,…}` 会把「未报」伪装成「报了 0」，
+  // 让翻译层的兜底判据永远看不到真实形状（ADR-0055 决策 3）。
+  if (usage) out.usage = usage;
+  return out;
+}