cctra 0.3.0

package/src/plugin/contract.ts

@@ -0,0 +1,51 @@
+// ============================================================================
+// 插件契约：给插件作者用的 .d.ts 类型
+// ============================================================================
+import type { ApiFormat } from "../types";
+import type { CanonicalRequest, CanonicalResponse, CanonicalChunk } from "../canonical/types";
+
+/** 插件作者导出的对象 */
+export interface UpstreamPlugin {
+  /** 全局唯一名 */
+  name: string;
+  displayName?: string;
+
+  /** 声明式模式：返回 ready config，让 cctra 帮你发请求 */
+  getConfig?(ctx: PluginContext): Promise<UpstreamReady | UpstreamReady[]>;
+
+  /** 函数式模式：直接接管请求（更灵活） */
+  fetch?(req: CanonicalRequest, ctx: PluginContext): Promise<CanonicalResponse>;
+  fetchStream?(req: CanonicalRequest, ctx: PluginContext): AsyncIterable<CanonicalChunk>;
+
+  /** 可选：返回插件能服务的模型列表 */
+  listModels?(ctx: PluginContext): Promise<PluginModel[]>;
+}
+
+/** 一次 getConfig 调用返回的"准备好"配置 */
+export interface UpstreamReady {
+  baseUrl: string;
+  path: string;
+  apiFormat: ApiFormat;
+  authHeader: Record<string, string>;
+  modelId: string;
+  modelMetadata?: PluginModel;
+}
+
+/** cctra 给插件的 API */
+export interface PluginContext {
+  /** 用户填的插件配置（JSON） */
+  config: Record<string, unknown>;
+  /** 写日志（带插件名前缀） */
+  logger: (msg: string) => void;
+  /** cctra 的 fetch 包装 */
+  fetch: typeof fetch;
+  /** 内存缓存 */
+  cacheGet: (key: string) => Promise<unknown | undefined>;
+  cacheSet: (key: string, value: unknown, ttlMs?: number) => Promise<void>;
+}
+
+export interface PluginModel {
+  id: string;
+  alias?: string;
+  metadata?: Record<string, unknown>;
+}

package/src/plugin/host.ts

@@ -0,0 +1,27 @@
+// ============================================================================
+// cctra 给插件的 host API 工厂
+// ============================================================================
+import type { PluginContext } from "./contract";
+import { logger } from "../utils/logger";
+
+const cache = new Map<string, { value: unknown; expiresAt: number }>();
+
+export function makePluginContext(pluginName: string, config: Record<string, unknown>): PluginContext {
+  return {
+    config,
+    logger: (msg: string) => logger.info(`[plugin:${pluginName}] ${msg}`),
+    fetch: fetch.bind(globalThis),
+    cacheGet: async (key: string) => {
+      const entry = cache.get(`${pluginName}:${key}`);
+      if (!entry) return undefined;
+      if (entry.expiresAt < Date.now()) {
+        cache.delete(`${pluginName}:${key}`);
+        return undefined;
+      }
+      return entry.value;
+    },
+    cacheSet: async (key: string, value: unknown, ttlMs = 60_000) => {
+      cache.set(`${pluginName}:${key}`, { value, expiresAt: Date.now() + ttlMs });
+    },
+  };
+}

package/src/plugin/loader.ts

@@ -0,0 +1,55 @@
+// ============================================================================
+// 插件加载器：动态 import() 用户的 .js 文件，缓存到内存
+// v1 是 trust 模型：插件 = 任意 JS，可执行任何代码
+// ============================================================================
+import { statSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { PluginConfig, Config } from "../types";
+import type { UpstreamPlugin } from "./contract";
+import { info, error as errorOut } from "../ui/format";
+
+const moduleCache = new Map<string, UpstreamPlugin>();
+
+/** 加载并缓存插件。CLI 一次性操作，输出走 format（stdout/stderr）给用户看。 */
+export async function loadPlugin(plugin: PluginConfig, _config: Config): Promise<UpstreamPlugin | null> {
+  if (moduleCache.has(plugin.path)) {
+    return moduleCache.get(plugin.path)!;
+  }
+
+  // 验证文件存在
+  try {
+    statSync(plugin.path);
+  } catch {
+    errorOut(`[plugin:${plugin.name}] file not found: ${plugin.path}`);
+    return null;
+  }
+
+  // 用 cache-busting query string 避免 stale cache
+  const url = pathToFileURL(resolvePath(plugin.path)).href;
+  const cacheBustUrl = `${url}?t=${Date.now()}`;
+
+  try {
+    const mod = await import(cacheBustUrl);
+    const instance: UpstreamPlugin = mod.default ?? mod;
+    if (!instance.name) {
+      instance.name = plugin.name;
+    }
+    moduleCache.set(plugin.path, instance);
+    info(`[plugin:${plugin.name}] loaded from ${plugin.path}`);
+    return instance;
+  } catch (e) {
+    errorOut(`[plugin:${plugin.name}] failed to import: ${(e as Error).message}`);
+    return null;
+  }
+}
+
+/** 清空缓存（用户在 CLI 里 disable 插件时调用） */
+export function unloadPlugin(path: string): void {
+  moduleCache.delete(path);
+}
+
+/** 清空所有缓存（daemon 重新加载配置时用） */
+export function clearPluginCache(): void {
+  moduleCache.clear();
+}

package/src/plugin/sandbox.ts

@@ -0,0 +1,3 @@
+// 占位：v1 不做沙箱隔离，插件 = 任意 JS
+// 未来如果需要 Worker 隔离，在这里实现
+export {};

package/src/providers/presets.ts

@@ -0,0 +1,167 @@
+// ============================================================================
+// Vendor 预设：从 cc-switch 三个 preset 文件人工筛选 + 翻译成 cctra 精简版
+// ============================================================================
+//
+// 数据来源（vendor 名称 & endpoint URL）：
+//   cc-switch (MIT, Copyright (c) 2025 Jason Young)
+//   https://github.com/farion1231/cc-switch
+//   - src/config/claudeProviderPresets.ts (Anthropic 格式)
+//   - src/config/codexProviderPresets.ts   (OpenAI Chat / Responses)
+//   - src/config/geminiProviderPresets.ts  (OpenAI Responses 兼容)
+//
+// cctra preset 设计：
+//   - 一个 vendor 可以有多个协议端点（如 Ark 同时支持 Anthropic + OpenAI Chat）
+//   - add wizard 选中 preset 后，下一步协议选择只显示该 preset 支持的协议
+//   - 「不使用供应商」才允许 3 种协议全选
+// ============================================================================
+
+import type { ApiFormat } from "../canonical/types";
+
+export type ProviderEndpoints = Partial<Record<ApiFormat, string>>;
+
+export interface ProviderPreset {
+  name: string;                   // 显示名
+  endpoints: ProviderEndpoints;   // 每个协议对应的 base URL
+  notes?: string;                 // 特殊处理备注
+}
+
+export const API_FORMAT_LABELS: Record<ApiFormat, string> = {
+  "openai-chat": "OpenAI Chat Completions",
+  "openai-responses": "OpenAI Responses",
+  "anthropic-messages": "Anthropic Messages",
+};
+
+// ============================================================================
+// Provider 预设（从 cc-switch 精确抄录，一个 vendor 可声明多个协议端点）
+// ============================================================================
+export const providerPresets: ProviderPreset[] = [
+  // ---- Anthropic + OpenAI Chat ----
+  { name: "Ark Agent Plan", endpoints: { "anthropic-messages": "https://ark.cn-beijing.volces.com/api/plan", "openai-chat": "https://ark.cn-beijing.volces.com/api/plan/v3" } },
+  { name: "Ark Coding Plan", endpoints: { "anthropic-messages": "https://ark.cn-beijing.volces.com/api/coding", "openai-chat": "https://ark.cn-beijing.volces.com/api/coding/v3" } },
+  { name: "Shengsuanyun", endpoints: { "anthropic-messages": "https://router.shengsuanyun.com/api", "openai-chat": "https://router.shengsuanyun.com/api/v1" } },
+  { name: "PatewayAI", endpoints: { "anthropic-messages": "https://api.pateway.ai", "openai-chat": "https://api.pateway.ai/v1" } },
+  { name: "BytePlus", endpoints: { "anthropic-messages": "https://ark.ap-southeast.bytepluses.com/api/coding", "openai-chat": "https://ark.ap-southeast.bytepluses.com/api/coding/v3" } },
+  { name: "DouBaoSeed", endpoints: { "anthropic-messages": "https://ark.cn-beijing.volces.com/api/compatible", "openai-chat": "https://ark.cn-beijing.volces.com/api/v3" } },
+  { name: "DeepSeek", endpoints: { "anthropic-messages": "https://api.deepseek.com/anthropic", "openai-chat": "https://api.deepseek.com" } },
+  { name: "Zhipu GLM", endpoints: { "anthropic-messages": "https://open.bigmodel.cn/api/anthropic", "openai-chat": "https://open.bigmodel.cn/api/coding/paas/v4" } },
+  { name: "Zhipu GLM en", endpoints: { "anthropic-messages": "https://api.z.ai/api/anthropic", "openai-chat": "https://api.z.ai/api/coding/paas/v4" } },
+  { name: "Baidu Qianfan Coding Plan", endpoints: { "anthropic-messages": "https://qianfan.baidubce.com/anthropic/coding", "openai-chat": "https://qianfan.baidubce.com/v2/coding" } },
+  { name: "Bailian", endpoints: { "anthropic-messages": "https://dashscope.aliyuncs.com/apps/anthropic", "openai-chat": "https://dashscope.aliyuncs.com/compatible-mode/v1" } },
+  { name: "Kimi", endpoints: { "anthropic-messages": "https://api.moonshot.cn/anthropic", "openai-chat": "https://api.moonshot.cn/v1" } },
+  { name: "StepFun", endpoints: { "anthropic-messages": "https://api.stepfun.com/step_plan", "openai-chat": "https://api.stepfun.com/step_plan/v1" } },
+  { name: "StepFun en", endpoints: { "anthropic-messages": "https://api.stepfun.ai/step_plan", "openai-chat": "https://api.stepfun.ai/step_plan/v1" } },
+  { name: "ModelScope", endpoints: { "anthropic-messages": "https://api-inference.modelscope.cn", "openai-chat": "https://api-inference.modelscope.cn/v1" } },
+  { name: "Longcat", endpoints: { "anthropic-messages": "https://api.longcat.chat/anthropic", "openai-chat": "https://api.longcat.chat/openai/v1" } },
+  { name: "MiniMax", endpoints: { "anthropic-messages": "https://api.minimaxi.com/anthropic", "openai-chat": "https://api.minimaxi.com/v1" } },
+  { name: "MiniMax en", endpoints: { "anthropic-messages": "https://api.minimax.io/anthropic", "openai-chat": "https://api.minimax.io/v1" } },
+  { name: "BaiLing", endpoints: { "anthropic-messages": "https://api.tbox.cn/api/anthropic", "openai-chat": "https://api.tbox.cn/api/llm/v1" } },
+  { name: "Xiaomi MiMo", endpoints: { "anthropic-messages": "https://api.xiaomimimo.com/anthropic", "openai-chat": "https://api.xiaomimimo.com/v1" } },
+  { name: "Xiaomi MiMo Token Plan (China)", endpoints: { "anthropic-messages": "https://token-plan-cn.xiaomimimo.com/anthropic", "openai-chat": "https://token-plan-cn.xiaomimimo.com/v1" } },
+  { name: "SiliconFlow", endpoints: { "anthropic-messages": "https://api.siliconflow.cn", "openai-chat": "https://api.siliconflow.cn/v1" } },
+  { name: "SiliconFlow en", endpoints: { "anthropic-messages": "https://api.siliconflow.com", "openai-chat": "https://api.siliconflow.com/v1" } },
+  { name: "Novita AI", endpoints: { "anthropic-messages": "https://api.novita.ai/anthropic", "openai-chat": "https://api.novita.ai/openai/v1" } },
+  { name: "Nvidia NIM", endpoints: { "anthropic-messages": "https://integrate.api.nvidia.com", "openai-chat": "https://integrate.api.nvidia.com/v1" } },
+  { name: "AiHubMix", endpoints: { "anthropic-messages": "https://aihubmix.com", "openai-chat": "https://aihubmix.com/v1" }, notes: "ANTHROPIC_API_KEY header（不是 ANTHROPIC_AUTH_TOKEN）" },
+  { name: "CherryIN", endpoints: { "anthropic-messages": "https://open.cherryin.net", "openai-chat": "https://open.cherryin.net/v1" } },
+  { name: "DMXAPI", endpoints: { "anthropic-messages": "https://www.dmxapi.cn", "openai-chat": "https://www.dmxapi.cn/v1" } },
+  { name: "PackyCode", endpoints: { "anthropic-messages": "https://www.packyapi.com", "openai-chat": "https://www.packyapi.com/v1" } },
+  { name: "AtlasCloud", endpoints: { "anthropic-messages": "https://api.atlascloud.ai", "openai-chat": "https://api.atlascloud.ai/v1" } },
+  { name: "ClaudeCN", endpoints: { "anthropic-messages": "https://claudecn.top", "openai-chat": "https://claudecn.top/v1" } },
+  { name: "RunAPI", endpoints: { "anthropic-messages": "https://runapi.co", "openai-chat": "https://runapi.co/v1" } },
+  { name: "RelaxyCode", endpoints: { "anthropic-messages": "https://www.relaxycode.com", "openai-chat": "https://www.relaxycode.com/v1" } },
+  { name: "Cubence", endpoints: { "anthropic-messages": "https://api.cubence.com", "openai-chat": "https://api.cubence.com/v1" } },
+  { name: "AIGoCode", endpoints: { "anthropic-messages": "https://api.aigocode.com", "openai-chat": "https://api.aigocode.com" } },
+  { name: "RightCode", endpoints: { "anthropic-messages": "https://www.right.codes/claude", "openai-chat": "https://right.codes/codex/v1" } },
+  { name: "AICodeMirror", endpoints: { "anthropic-messages": "https://api.aicodemirror.com/api/claudecode", "openai-chat": "https://api.aicodemirror.com/api/codex/backend-api/codex" } },
+  { name: "CrazyRouter", endpoints: { "anthropic-messages": "https://cn.crazyrouter.com", "openai-chat": "https://cn.crazyrouter.com/v1" } },
+  { name: "SSSAiCode", endpoints: { "anthropic-messages": "https://node-hk.sssaicode.com/api", "openai-chat": "https://node-hk.sssaicode.com/api/v1" } },
+  { name: "Compshare", endpoints: { "anthropic-messages": "https://api.modelverse.cn", "openai-chat": "https://api.modelverse.cn/v1" } },
+  { name: "Compshare Coding Plan", endpoints: { "anthropic-messages": "https://cp.compshare.cn", "openai-chat": "https://cp.compshare.cn/v1" } },
+  { name: "Micu", endpoints: { "anthropic-messages": "https://www.micuapi.ai", "openai-chat": "https://www.micuapi.ai/v1" } },
+  { name: "CTok.ai", endpoints: { "anthropic-messages": "https://api.ctok.ai", "openai-chat": "https://api.ctok.ai/v1" } },
+  { name: "LemonData", endpoints: { "anthropic-messages": "https://api.lemondata.cc", "openai-chat": "https://api.lemondata.cc/v1" } },
+  { name: "OpenRouter", endpoints: { "anthropic-messages": "https://openrouter.ai/api", "openai-chat": "https://openrouter.ai/api/v1" } },
+  { name: "TheRouter", endpoints: { "anthropic-messages": "https://api.therouter.ai", "openai-chat": "https://api.therouter.ai/v1" } },
+
+  // ---- Anthropic + OpenAI Responses ----
+  { name: "APIKEY.FUN", endpoints: { "anthropic-messages": "https://api.apikey.fun", "openai-responses": "https://api.apikey.fun/v1" } },
+  { name: "APINebula", endpoints: { "anthropic-messages": "https://apinebula.com", "openai-responses": "https://apinebula.com/v1" } },
+  { name: "SudoCode", endpoints: { "anthropic-messages": "https://sudocode.us", "openai-responses": "https://sudocode.us/v1" } },
+  { name: "E-FlowCode", endpoints: { "anthropic-messages": "https://e-flowcode.cc", "openai-responses": "https://e-flowcode.cc/v1" } },
+  { name: "PIPELLM", endpoints: { "anthropic-messages": "https://cc-api.pipellm.ai", "openai-responses": "https://cc-api.pipellm.ai/v1" } },
+
+  // ---- Anthropic 独有（claudeProviderPresets 有但 codex 没有同名项）----
+  { name: "Bailian For Coding", endpoints: { "anthropic-messages": "https://coding.dashscope.aliyuncs.com/apps/anthropic" } },
+  { name: "Kimi For Coding", endpoints: { "anthropic-messages": "https://api.kimi.com/coding" } },
+  { name: "ClaudeAPI", endpoints: { "anthropic-messages": "https://gw.claudeapi.com" } },
+
+  // ---- OpenAI Chat 独有（codex 有但 claude 没有同名项）----
+  { name: "OpenCode Go", endpoints: { "openai-chat": "https://opencode.ai/zen/go" } },
+  { name: "OpenAI Official", endpoints: { "openai-chat": "https://api.openai.com/v1" } },
+  { name: "GitHub Copilot", endpoints: { "openai-chat": "https://api.githubcopilot.com" }, notes: "需要 OAuth（暂不支持 API key 登录）" },
+
+  // ---- OpenAI Responses 独有 ----
+  { name: "Codex (ChatGPT Plus/Pro)", endpoints: { "openai-responses": "https://chatgpt.com/backend-api/codex" }, notes: "需要 ChatGPT Plus/Pro OAuth token" },
+  { name: "Gemini OpenAI-Compat", endpoints: { "openai-responses": "https://generativelanguage.googleapis.com/v1beta/openai" }, notes: "Google Gemini 官方 OpenAI 兼容端点" },
+  { name: "OpenAI Responses (Official)", endpoints: { "openai-responses": "https://api.openai.com" } },
+];
+
+/**
+ * 「不使用供应商」special entry（用于纯手输流程）
+ */
+export const NO_VENDOR: ProviderPreset = {
+  name: "(不使用供应商)",
+  endpoints: {},
+  notes: "",
+};
+
+/**
+ * 获取供应商列表，第一项是「不使用供应商」
+ */
+export function getVendorChoices(): ProviderPreset[] {
+  return [NO_VENDOR, ...providerPresets];
+}
+
+/**
+ * 获取 preset 支持的协议；自定义 preset 支持全部 3 种协议
+ */
+export function getSupportedApiFormats(preset: ProviderPreset): ApiFormat[] {
+  if (preset === NO_VENDOR || preset.name === NO_VENDOR.name) {
+    return ["openai-chat", "openai-responses", "anthropic-messages"];
+  }
+  return (["anthropic-messages", "openai-chat", "openai-responses"] as const)
+    .filter((format) => Boolean(preset.endpoints[format]));
+}
+
+/**
+ * 获取协议对应 endpoint
+ */
+export function getEndpointForFormat(preset: ProviderPreset, format: ApiFormat): string {
+  return preset.endpoints[format] ?? "";
+}
+
+/**
+ * 供应商选择列表 hint
+ */
+export function getPresetHint(preset: ProviderPreset): string | undefined {
+  const formats = getSupportedApiFormats(preset);
+  if (formats.length === 0) return undefined;
+  const formatLabels = formats.map((format) => API_FORMAT_LABELS[format]).join(" / ");
+  const firstEndpoint = preset.endpoints[formats[0]!];
+  return firstEndpoint ? `${formatLabels}: ${firstEndpoint}` : formatLabels;
+}
+
+/**
+ * 根据供应商名生成 kebab-case profile 名称
+ * 例：
+ *   "Ark Agent Plan"                 → "ark-agent-plan"
+ *   "APIKEY.FUN"                     → "apikey-fun"
+ *   "Xiaomi MiMo Token Plan (China)" → "xiaomi-mimo-token-plan-china"
+ */
+export function generateProfileName(vendorName: string): string {
+  return vendorName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")  // 非字母数字 → 连字符
+    .replace(/-+/g, "-")          // 合并连续连字符
+    .replace(/^-|-$/g, "");       // 去首尾连字符
+}

package/src/server/anthropic-parser.ts

@@ -0,0 +1,44 @@
+// ============================================================================
+// 上游响应解析：Anthropic Messages → CanonicalResponse
+// ============================================================================
+import type { CanonicalResponse, CanonicalContentBlock } from "../canonical/types";
+
+interface AnthropicUpstreamResponse {
+  id?: string;
+  model?: string;
+  content?: Array<
+    | { type: "text"; text: string }
+    | { type: "tool_use"; id: string; name: string; input: unknown }
+    | { type: "thinking"; thinking: string; signature?: string }
+  >;
+  stop_reason?: "end_turn" | "max_tokens" | "stop_sequence" | "tool_use";
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
+}
+
+export function parseAnthropicUpstreamResponse(raw: unknown, model: string): CanonicalResponse {
+  const r = raw as AnthropicUpstreamResponse;
+  const blocks: CanonicalContentBlock[] = [];
+  for (const b of r.content ?? []) {
+    if (b.type === "text") blocks.push({ type: "text", text: b.text });
+    else if (b.type === "tool_use") blocks.push({ type: "tool_use", id: b.id, name: b.name, input: b.input });
+    else if (b.type === "thinking") blocks.push({ type: "thinking", thinking: b.thinking, signature: b.signature });
+  }
+
+  return {
+    id: r.id ?? `msg-${Date.now()}`,
+    model: r.model ?? model,
+    content: blocks,
+    stopReason: r.stop_reason ?? "end_turn",
+    usage: {
+      inputTokens: r.usage?.input_tokens ?? 0,
+      outputTokens: r.usage?.output_tokens ?? 0,
+      cacheReadTokens: r.usage?.cache_read_input_tokens,
+      cacheWriteTokens: r.usage?.cache_creation_input_tokens,
+    },
+  };
+}

package/src/server/cancelable-fetch.ts

@@ -0,0 +1,21 @@
+// ============================================================================
+// cancelableFetch：合并客户端 abort signal + 上游硬超时
+// 客户端断网 / Ctrl+C → 立刻取消上游 fetch（不再浪费 token）
+// ============================================================================
+
+const DEFAULT_TIMEOUT_MS = 60_000 * 5; // 5 分钟（保持现有行为）
+
+/**
+ * 用 AbortSignal.any 合并 clientSignal + timeout signal，注入 fetch
+ */
+export function cancelableFetch(
+  url: string,
+  init: RequestInit,
+  clientSignal: AbortSignal | undefined,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): Promise<Response> {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const signals: AbortSignal[] = clientSignal ? [clientSignal, timeoutSignal] : [timeoutSignal];
+  const merged = signals.length === 1 ? signals[0]! : AbortSignal.any(signals);
+  return fetch(url, { ...init, signal: merged });
+}

package/src/server/chat-parser.ts

@@ -0,0 +1,81 @@
+// ============================================================================
+// 上游响应解析：OpenAI Chat Completions → CanonicalResponse
+// 跟 upstream.ts（orchestrator）配套使用
+// ============================================================================
+import type { CanonicalResponse, CanonicalContentBlock } from "../canonical/types";
+
+interface ChatUpstreamResponse {
+  id?: string;
+  model?: string;
+  choices?: Array<{
+    index?: number;
+    message: {
+      role: "assistant";
+      content?: string | null;
+      tool_calls?: Array<{ id: string; type: "function"; function: { name: string; arguments: string } }>;
+    };
+    finish_reason?: string;
+  }>;
+  usage?: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+  };
+}
+
+export function parseChatUpstreamResponse(raw: unknown, model: string): CanonicalResponse {
+  const r = raw as ChatUpstreamResponse;
+  const choice = r.choices?.[0];
+  if (!choice) {
+    return makeErrorResponse(model, "no_choices", { type: "parse_error" });
+  }
+
+  const blocks: CanonicalContentBlock[] = [];
+  if (choice.message.content) {
+    blocks.push({ type: "text", text: choice.message.content });
+  }
+  if (choice.message.tool_calls) {
+    for (const tc of choice.message.tool_calls) {
+      let input: unknown = {};
+      try { input = JSON.parse(tc.function.arguments); } catch { /* keep empty */ }
+      blocks.push({ type: "tool_use", id: tc.id, name: tc.function.name, input });
+    }
+  }
+
+  return {
+    id: r.id ?? `chatcmpl-${Date.now()}`,
+    model: r.model ?? model,
+    content: blocks,
+    stopReason: mapStopReason(choice.finish_reason),
+    usage: {
+      inputTokens: r.usage?.prompt_tokens ?? 0,
+      outputTokens: r.usage?.completion_tokens ?? 0,
+    },
+  };
+}
+
+function mapStopReason(r: string | undefined): CanonicalResponse["stopReason"] {
+  switch (r) {
+    case "stop": return "end_turn";
+    case "length": return "max_tokens";
+    case "tool_calls": return "tool_use";
+    case "content_filter": return "error";
+    default: return "end_turn";
+  }
+}
+
+function makeErrorResponse(
+  model: string,
+  reason: string,
+  opts?: { type?: "parse_error" },
+): CanonicalResponse {
+  const message = `Upstream returned no valid response: ${reason}`;
+  const base: CanonicalResponse = {
+    id: `error-${Date.now()}`,
+    model,
+    content: [{ type: "text", text: message }],
+    stopReason: "error",
+    usage: { inputTokens: 0, outputTokens: 0 },
+  };
+  if (!opts?.type) return base;
+  return { ...base, error: { message, type: opts.type } };
+}

package/src/server/error-status.ts

@@ -0,0 +1,18 @@
+// ============================================================================
+// 错误响应 → HTTP status code 单一来源
+// 避免 cc-switch 那种 `IntoResponse` + `map_proxy_error_to_status` 双轨 footgun
+// ============================================================================
+import type { CanonicalResponse } from "../canonical/types";
+
+/**
+ * 从 CanonicalResponse 决定 HTTP status code。
+ * - 错误响应有 status 字段 → 透传上游
+ * - 错误响应无 status 字段（如 plugin/network/parse 错）→ 500
+ * - 非错误响应 → undefined（调用方用默认 200）
+ */
+export function errorResponseToHttpStatus(
+  response: CanonicalResponse,
+): number | undefined {
+  if (!response.error) return undefined;
+  return response.error.status ?? 500;
+}

package/src/server/error.ts

@@ -0,0 +1,16 @@
+// ============================================================================
+// 错误信封：按客户端协议分别包装
+// 上游错误 JSON 优先透传（status + body），代理本身失败才用代理信封
+// ============================================================================
+
+export function chatErrorBody(message: string, type = "cctra_error"): Record<string, unknown> {
+  return { error: { message, type } };
+}
+
+export function anthropicErrorBody(message: string, type = "cctra_error"): Record<string, unknown> {
+  return { type: "error", error: { type, message } };
+}
+
+export function responsesErrorBody(message: string, code = "cctra_error"): Record<string, unknown> {
+  return { error: { message, code } };
+}

package/src/server/handlers/chat-completions.ts

@@ -0,0 +1,94 @@
+// ============================================================================
+// POST /v1/chat/completions 处理器
+// ============================================================================
+import type { Config } from "../../types";
+import { chatToCanonical } from "../../convert/inbound/chat-to-canonical";
+import { callUpstream, callUpstreamStream, UpstreamError } from "../upstream";
+import { canonicalToChatResponse } from "../../convert/outbound/canonical-to-chat";
+import { chatErrorBody } from "../error";
+import { errorResponseToHttpStatus } from "../error-status";
+import { resolveRoute } from "../../core/routing";
+import { wrapWithKeepalive } from "../keepalive";
+import { loadConfigFile } from "../../core/config";
+import { logger } from "../../utils/logger";
+
+export async function handleChatCompletions(req: Request): Promise<Response> {
+  const config = loadConfigFile();
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return Response.json(chatErrorBody("Invalid JSON body"), { status: 400 });
+  }
+  const b = body as { model?: string };
+  if (!b.model) {
+    return Response.json(chatErrorBody("Missing 'model' field"), { status: 400 });
+  }
+
+  let route;
+  try {
+    route = resolveRoute(b.model, config);
+  } catch (e) {
+    return Response.json(chatErrorBody((e as Error).message), { status: 400 });
+  }
+
+  const canonical = chatToCanonical(body as Parameters<typeof chatToCanonical>[0]);
+  // 用 route 的 upstreamModelId 覆盖（避免客户端用 alias 时传错）
+  canonical.model = route.upstreamModelId;
+
+  if (canonical.stream) {
+    try {
+      const { upstreamStream, parser, format } = await callUpstreamStream({
+        route,
+        canonical,
+        clientFormat: "openai-chat",
+        clientSignal: req.signal,
+      });
+      const cstream = parser(upstreamStream);
+      const encoder = new TextEncoder();
+      const inner = new ReadableStream<Uint8Array>({
+        async start(controller) {
+          try {
+            for await (const chunk of cstream) {
+              for (const s of format(chunk)) controller.enqueue(encoder.encode(s));
+            }
+          } catch (e) {
+            logger.error(`[chat-completions:stream] error: ${(e as Error).message}`);
+            if (e instanceof UpstreamError) {
+              // OpenAI Chat 错误 SSE 事件：data: {"error": {...}}
+              // 注意：发完 error 后**不再发 [DONE]**（cc-switch 二元化约束）
+              const errEvent = `data: ${JSON.stringify({
+                error: { message: e.message, type: "upstream_error", code: e.status },
+              })}\n\n`;
+              controller.enqueue(encoder.encode(errEvent));
+            }
+          } finally {
+            controller.close();
+          }
+        },
+      });
+      return new Response(wrapWithKeepalive(inner), {
+        headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
+      });
+    } catch (e) {
+      return Response.json(chatErrorBody((e as Error).message), { status: 500 });
+    }
+  }
+
+  // 非流式
+  try {
+    const upstreamRes = await callUpstream({
+      route, canonical, clientFormat: "openai-chat", clientSignal: req.signal,
+    });
+    const body = canonicalToChatResponse(upstreamRes);
+    const httpStatus = errorResponseToHttpStatus(upstreamRes);
+    return httpStatus !== undefined
+      ? Response.json(body, { status: httpStatus })
+      : Response.json(body);
+  } catch (e) {
+    return Response.json(chatErrorBody((e as Error).message), { status: 500 });
+  }
+}
+
+// 抑制未用导入警告（config 未来会用）
+void (null as unknown as Config);