cctra 0.3.0

package/src/server/upstream.ts

@@ -0,0 +1,251 @@
+// ============================================================================
+// 上游转发 orchestrator：把 Canonical 请求转成上游协议，注入 auth，fetch，解析响应
+// 同时支持 stream 和非 stream
+// ============================================================================
+import type { Source, Subscription, ApiFormat } from "../types";
+import type { CanonicalRequest, CanonicalResponse, CanonicalChunk } from "../canonical/types";
+import { canonicalToChatUpstream } from "../convert/upstream/canonical-to-chat";
+import { canonicalToAnthropicUpstream } from "../convert/upstream/canonical-to-anthropic";
+import { canonicalToResponses } from "../convert/upstream/canonical-to-responses";
+import { parseChatUpstreamResponse } from "./chat-parser";
+import { parseAnthropicUpstreamResponse } from "./anthropic-parser";
+import { parseResponsesResponse } from "./responses-parser";
+import { pickInboundStreamParser, type InboundStreamParser } from "../convert/streaming/inbound/pick";
+import { ChatStreamFormatter } from "../convert/streaming/outbound/format-chat";
+import { ResponsesStreamFormatter } from "../convert/streaming/outbound/format-responses";
+import { AnthropicStreamFormatter } from "../convert/streaming/outbound/format-anthropic";
+import { cancelableFetch } from "./cancelable-fetch";
+import { logger } from "../utils/logger";
+import type { CanonicalResponseError } from "../canonical/types";
+
+/**
+ * 流式路径专用 typed error：携带上游 HTTP status 给 handler 决定 HTTP 响应。
+ * HTTP 4xx/5xx 到达 `callUpstreamStream` 时直接 throw，handler 在 SSE 流内发 error event。
+ */
+export class UpstreamError extends Error {
+  constructor(
+    public readonly status: number | undefined,
+    public readonly body: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "UpstreamError";
+  }
+}
+
+export interface UpstreamCallOptions {
+  route: { source: Source; upstreamModelId: string; apiFormat: ApiFormat };
+  canonical: CanonicalRequest;
+  clientFormat: "openai-chat" | "openai-responses" | "anthropic-messages";
+  /** 客户端 req.signal；为 undefined 时只用上游 5min 硬超时 */
+  clientSignal?: AbortSignal;
+}
+
+/** 非流式上游调用 */
+export async function callUpstream(opts: UpstreamCallOptions): Promise<CanonicalResponse> {
+  const ready = await resolveUpstream(opts.route);
+  if (!ready) {
+    return makeError(opts.route.upstreamModelId, "plugin_returned_no_config", { type: "plugin_error" });
+  }
+
+  const upstreamBody = pickUpstreamSerializer(ready.apiFormat)(opts.canonical);
+
+  const url = joinUrl(ready.baseUrl, ready.path);
+  logger.info(`[upstream] ${opts.route.apiFormat} → POST ${url} (model=${opts.canonical.model})`);
+
+  let res: Response;
+  try {
+    res = await cancelableFetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...ready.authHeader,
+      },
+      body: JSON.stringify(upstreamBody),
+    }, opts.clientSignal);
+  } catch (e) {
+    return makeError(
+      opts.route.upstreamModelId,
+      `network_error: ${(e as Error).message}`,
+      { type: "network_error" },
+    );
+  }
+
+  if (!res.ok) {
+    const text = await res.text();
+    // 优先抽 body 的 error.message（OpenAI/Anthropic/Responses 标准 shape），
+    // 抽不到时回退到 raw text 截 500 字符
+    let message = text.slice(0, 500);
+    try {
+      const parsed = JSON.parse(text) as { error?: { message?: unknown } };
+      if (typeof parsed.error?.message === "string") {
+        message = parsed.error.message.slice(0, 500);
+      }
+    } catch { /* 非 JSON body，保持 raw text */ }
+    return makeError(
+      opts.route.upstreamModelId,
+      message,
+      { status: res.status, type: "upstream_error" },
+    );
+  }
+
+  const raw = await res.json();
+  return pickUpstreamParser(ready.apiFormat)(raw, opts.route.upstreamModelId);
+}
+
+/** 流式上游调用 */
+export interface UpstreamStream {
+  upstreamStream: ReadableStream<Uint8Array>;
+  /** 按 ready.apiFormat（真实上游协议）选 inbound 解析器 */
+  parser: InboundStreamParser;
+  /** 按 clientFormat 选输出格式化器；返回 0+ SSE 行（含 \n\n） */
+  format: (chunk: CanonicalChunk) => string[];
+}
+
+export async function callUpstreamStream(opts: UpstreamCallOptions): Promise<UpstreamStream> {
+  const ready = await resolveUpstream(opts.route);
+  if (!ready) throw new Error("plugin_returned_no_config");
+
+  const upstreamBody = pickUpstreamSerializer(ready.apiFormat)(opts.canonical);
+
+  const url = joinUrl(ready.baseUrl, ready.path);
+  logger.info(`[upstream:stream] ${opts.route.apiFormat} → POST ${url} (model=${opts.canonical.model})`);
+
+  const res = await cancelableFetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...ready.authHeader,
+    },
+    body: JSON.stringify(upstreamBody),
+  }, opts.clientSignal);
+
+  if (!res.ok || !res.body) {
+    const text = res.body ? await res.text() : `upstream_${res.status}`;
+    throw new UpstreamError(res.status, text.slice(0, 500), text.slice(0, 500));
+  }
+
+  // 关键：parser 用 ready.apiFormat（plugin 真实返回），不是 route.apiFormat（plugin 占位）
+  const parser = pickInboundStreamParser(ready.apiFormat);
+
+  const formatter = opts.clientFormat === "openai-chat" ? new ChatStreamFormatter()
+    : opts.clientFormat === "openai-responses" ? new ResponsesStreamFormatter()
+    : new AnthropicStreamFormatter();
+
+  return {
+    upstreamStream: res.body,
+    parser,
+    format: (chunk) => formatter.format(chunk),
+  };
+}
+
+// ============================================================================
+// 解析上游 ready config（subscription 直接用；plugin 调用 getConfig）
+// ============================================================================
+
+interface ReadyConfig {
+  baseUrl: string;
+  path: string;
+  apiFormat: ApiFormat;
+  authHeader: Record<string, string>;
+}
+
+async function resolveUpstream(route: UpstreamCallOptions["route"]): Promise<ReadyConfig | null> {
+  const source = route.source;
+  if (source.kind === "subscription") {
+    const sub = source as Subscription;
+    const path = pickUpstreamPath(sub);
+    return {
+      baseUrl: sub.endpoint,
+      path,
+      apiFormat: sub.apiFormat,
+      authHeader: { Authorization: `Bearer ${sub.token}`, ...sub.headers },
+    };
+  }
+  // plugin
+  if (source.kind !== "plugin") return null;
+  const pluginCfg = source as unknown as import("../types").PluginConfig;
+  const { loadPlugin } = await import("../plugin/loader");
+  const { makePluginContext } = await import("../plugin/host");
+  const { loadConfigFile } = await import("../core/config");
+  const config = loadConfigFile();
+  const plugin = await loadPlugin(pluginCfg, config);
+  if (!plugin?.getConfig) return null;
+  try {
+    const ctx = makePluginContext(pluginCfg.name, pluginCfg.config);
+    const result = await plugin.getConfig(ctx);
+    const ready = Array.isArray(result) ? result[0] : result;
+    if (!ready) return null;
+    return {
+      baseUrl: ready.baseUrl,
+      path: ready.path,
+      apiFormat: ready.apiFormat,
+      authHeader: ready.authHeader,
+    };
+  } catch (e) {
+    logger.error(`[plugin:${source.name}] getConfig failed: ${(e as Error).message}`);
+    return null;
+  }
+}
+
+function makeError(
+  model: string,
+  msg: string,
+  opts?: { status?: number; type?: CanonicalResponseError["type"] },
+): CanonicalResponse {
+  const base = {
+    id: `error-${Date.now()}`,
+    model,
+    content: [{ type: "text", text: msg }] as CanonicalResponse["content"],
+    stopReason: "error" as const,
+    usage: { inputTokens: 0, outputTokens: 0 },
+  };
+  if (opts?.status === undefined && !opts?.type) return base;
+  return {
+    ...base,
+    error: {
+      message: msg,
+      ...(opts.status !== undefined && { status: opts.status }),
+      ...(opts.type && { type: opts.type }),
+    },
+  };
+}
+
+function joinUrl(base: string, path: string): string {
+  const b = base.replace(/\/+$/, "");
+  const p = path.startsWith("/") ? path : `/${path}`;
+  if (b.endsWith("/v1") && p.startsWith("/v1/")) return `${b}${p.slice(3)}`;
+  if (b.endsWith("/v1beta") && p.startsWith("/v1beta/")) return `${b}${p.slice(7)}`;
+  return `${b}${p}`;
+}
+
+// ============================================================================
+// 工厂函数：按 apiFormat 选上游 serializer / parser / path
+// ============================================================================
+
+type UpstreamSerializer = (req: CanonicalRequest) => unknown;
+type UpstreamParser = (raw: unknown, model: string) => CanonicalResponse;
+
+function pickUpstreamSerializer(format: ApiFormat): UpstreamSerializer {
+  switch (format) {
+    case "openai-chat":        return canonicalToChatUpstream;
+    case "openai-responses":   return canonicalToResponses;
+    case "anthropic-messages": return canonicalToAnthropicUpstream;
+  }
+}
+
+function pickUpstreamParser(format: ApiFormat): UpstreamParser {
+  switch (format) {
+    case "openai-chat":        return parseChatUpstreamResponse;
+    case "openai-responses":   return parseResponsesResponse;
+    case "anthropic-messages": return parseAnthropicUpstreamResponse;
+  }
+}
+
+function pickUpstreamPath(sub: Subscription): string {
+  switch (sub.apiFormat) {
+    case "openai-chat":        return sub.chatCompletionsPath ?? "/v1/chat/completions";
+    case "openai-responses":   return sub.responsesPath ?? "/v1/responses";
+    case "anthropic-messages": return sub.messagesPath ?? "/v1/messages";
+  }
+}

package/src/tier/builtin.ts

@@ -0,0 +1,9 @@
+// 预留：4 个预定义 tier 的元数据（description / 用途说明）
+import type { Tier } from "../types";
+
+export const BUILTIN_TIERS: Record<string, Tier> = {
+  cctra: { name: "cctra", target: "", description: "默认（中等质量、便宜）" },
+  "cctra-pro": { name: "cctra-pro", target: "", description: "深度思考（慢但强）" },
+  "cctra-flash": { name: "cctra-flash", target: "", description: "高速（小快灵）" },
+  "cctra-vision": { name: "cctra-vision", target: "", description: "多模态" },
+};

package/src/tier/resolve.ts

@@ -0,0 +1,33 @@
+import type { Config, Source } from "../types";
+import { getSource } from "../core/source";
+
+/**
+ * 把 tier 名字解析成 (Source, upstreamModelId)
+ * tier 的 target 是 "sub/model" 或 "plugin/model" 格式
+ * 找不到映射或映射到的 source/model 不存在时返回 null
+ */
+export function resolveTier(
+  name: string,
+  config: Config,
+): { source: Source; modelId: string } | null {
+  const tier = config.tiers[name];
+  if (!tier || !tier.target) return null;
+
+  // 递归解析（支持 tier → tier）
+  if (config.tiers[tier.target]) {
+    return resolveTier(tier.target, config);
+  }
+
+  // 解析 "sub/model" 格式
+  if (!tier.target.includes("/")) return null;
+  const [sourceName, modelPart] = tier.target.split("/", 2);
+  if (!sourceName || !modelPart) return null;
+  const source = getSource(config, sourceName);
+  if (!source) return null;
+  const model = source.models.find((m) => m.id === modelPart || m.alias === modelPart);
+  if (!model) return null;
+  return { source, modelId: model.id };
+}
+
+/** 列出所有 4 个预定义 tier 名字（用于 CLI 提示等） */
+export const BUILTIN_TIER_NAMES = ["cctra", "cctra-pro", "cctra-flash", "cctra-vision"] as const;

package/src/tier/store.ts

@@ -0,0 +1,3 @@
+// 预留：tier 持久化逻辑（当前直接复用 src/core/config.ts 的 setTier/removeTier）
+// 这个文件是占位，后续如果需要 tier 独立的校验/迁移可以扩展
+export {};

package/src/types.ts

@@ -0,0 +1,94 @@
+// ============================================================================
+// Source 抽象：所有提供模型的服务（静态订阅 + 动态插件）的统一接口
+// ============================================================================
+
+import type { ApiFormat } from "./canonical/types";
+
+export type SourceKind = "subscription" | "plugin";
+
+export interface Source {
+  kind: SourceKind;
+  name: string;
+  displayName?: string;
+  models: Model[];
+}
+
+// ============================================================================
+// Model：模型元数据
+// ============================================================================
+
+export interface Model {
+  id: string;
+  alias?: string;
+  contextWindow?: number;
+  supportsTools?: boolean;
+  supportsVision?: boolean;
+}
+
+// ============================================================================
+// Subscription：静态订阅（endpoint + token + 协议类型）
+// ============================================================================
+
+export type { ApiFormat } from "./canonical/types";
+
+export interface Subscription extends Source {
+  kind: "subscription";
+  vendor?: string;                // 来源 vendor 名（仅显示用，不影响路由）
+  endpoint: string;
+  token: string;
+  apiFormat: ApiFormat;
+  chatCompletionsPath?: string;        // 默认 "/v1/chat/completions"（仅 openai-chat）
+  messagesPath?: string;               // 默认 "/v1/messages"（仅 anthropic）
+  responsesPath?: string;              // 默认 "/v1/responses"（仅 openai-responses）
+  modelsPath?: string;                 // 默认 "/v1/models"
+  headers?: Record<string, string>;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ============================================================================
+// Plugin：本地路径插件配置
+// ============================================================================
+
+export interface PluginConfig extends Source {
+  kind: "plugin";
+  path: string;
+  config: Record<string, unknown>;
+  enabled: boolean;
+}
+
+// ============================================================================
+// Tier：层级模型别名（用户固定写 cctra-pro，cctra 动态路由到具体模型）
+// ============================================================================
+
+export interface Tier {
+  name: string;
+  target: string;                       // "subscription/model" 或 "plugin/model"
+  description?: string;
+}
+
+export const BUILTIN_TIERS = ["cctra", "cctra-pro", "cctra-flash", "cctra-vision"] as const;
+export type BuiltinTier = typeof BUILTIN_TIERS[number];
+
+// ============================================================================
+// 总配置（~/.cctra/config.toml 的 schema）
+// ============================================================================
+
+export interface Config {
+  port: number;
+  subscriptions: Record<string, Subscription>;
+  plugins: Record<string, PluginConfig>;
+  tiers: Record<string, Tier>;
+}
+
+export const DEFAULT_CONFIG: Config = {
+  port: 3133,
+  subscriptions: {},
+  plugins: {},
+  tiers: {
+    cctra: { name: "cctra", target: "", description: "默认（中等质量、便宜）" },
+    "cctra-pro": { name: "cctra-pro", target: "", description: "深度思考（慢但强）" },
+    "cctra-flash": { name: "cctra-flash", target: "", description: "高速（小快灵）" },
+    "cctra-vision": { name: "cctra-vision", target: "", description: "多模态" },
+  },
+};

package/src/ui/format.ts

@@ -0,0 +1,44 @@
+import pc from "picocolors";
+
+// Windows Terminal 对 Unicode 字符宽度渲染不一致，需要额外空格
+const GAP = process.platform === "win32" ? "  " : " ";
+
+export function success(msg: string): void {
+  console.log(`${pc.green("✔")}${GAP}${msg}`);
+}
+
+export function error(msg: string): void {
+  console.error(`${pc.red("✖")}${GAP}${msg}`);
+}
+
+export function info(msg: string): void {
+  console.log(`${pc.cyan("ℹ")}${GAP}${msg}`);
+}
+
+export function warn(msg: string): void {
+  console.log(`${pc.yellow("⚠")}${GAP}${msg}`);
+}
+
+export function dim(s: string): string {
+  return pc.dim(s);
+}
+
+export function bold(s: string): string {
+  return pc.bold(s);
+}
+
+export function green(s: string): string {
+  return pc.green(s);
+}
+
+export function red(s: string): string {
+  return pc.red(s);
+}
+
+export function yellow(s: string): string {
+  return pc.yellow(s);
+}
+
+export function cyan(s: string): string {
+  return pc.cyan(s);
+}

package/src/ui/prompts.ts

@@ -0,0 +1,34 @@
+import * as p from "@clack/prompts";
+
+/**
+ * 检查是否取消操作
+ */
+export function checkCancel<T>(value: T | symbol): T {
+  if (p.isCancel(value)) {
+    p.cancel("Operation cancelled.");
+    process.exit(0);
+  }
+  return value as T;
+}
+
+/**
+ * 掩码 token（前 4 + 后 4 可见，中间显示实际位数的 *）
+ */
+export function maskToken(token: string): string {
+  if (!token) return "";
+  if (token.length <= 8) return "*".repeat(token.length);
+  const midLen = token.length - 8;
+  return `${token.slice(0, 4)}${"•".repeat(midLen)}${token.slice(-4)}`;
+}
+
+/**
+ * 通用确认 prompt
+ */
+export async function confirm(message: string, initial = false): Promise<boolean> {
+  return checkCancel(
+    await p.confirm({
+      message,
+      initialValue: initial,
+    }),
+  );
+}

package/src/utils/fuzzy.ts

@@ -0,0 +1,48 @@
+/**
+ * 模糊匹配：大小写不敏感的子串匹配 + token 打分
+ * 返回匹配得分，0 表示不匹配
+ */
+export function fuzzyScore(query: string, target: string): number {
+  const q = query.toLowerCase().trim();
+  const t = target.toLowerCase().trim();
+
+  if (!q) return 1;
+  if (!t) return 0;
+
+  // 完全匹配得分最高
+  if (t === q) return 100;
+
+  // 前缀匹配
+  if (t.startsWith(q)) return 90;
+
+  // 子串匹配
+  if (t.includes(q)) return 70;
+
+  // token 级匹配：query 按空格分词，每个词都要在 target 中出现
+  const tokens = q.split(/\s+/);
+  if (tokens.length > 1 && tokens.every((token) => t.includes(token))) {
+    return 50 + tokens.length * 5;
+  }
+
+  // 单 token 子串匹配
+  if (tokens.some((token) => token.length >= 2 && t.includes(token))) {
+    return 30;
+  }
+
+  return 0;
+}
+
+/**
+ * 在列表中模糊搜索，返回按得分排序的结果
+ */
+export function fuzzySearch<T>(
+  query: string,
+  items: T[],
+  getText: (item: T) => string,
+): T[] {
+  return items
+    .map((item) => ({ item, score: fuzzyScore(query, getText(item)) }))
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .map((r) => r.item);
+}

package/src/utils/logger.ts

@@ -0,0 +1,32 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { daemonLogPath } from "./paths";
+
+/** 简单 logger：写到 ~/.cctra/daemon.log，带时间戳 */
+export const logger = {
+  info(msg: string): void {
+    log("INFO", msg);
+  },
+  warn(msg: string): void {
+    log("WARN", msg);
+  },
+  error(msg: string): void {
+    log("ERROR", msg);
+  },
+  debug(msg: string): void {
+    if (process.env.CCTRA_DEBUG) log("DEBUG", msg);
+  },
+};
+
+function log(level: string, msg: string): void {
+  const line = `[${new Date().toISOString()}] [${level}] ${msg}\n`;
+  const path = daemonLogPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, line, "utf-8");
+  } catch {
+    // 写日志失败不能影响主流程
+  }
+  // 同时输出到 stderr（daemon 模式下 stdout 被吞，stderr 总是可见）
+  process.stderr.write(line);
+}

package/src/utils/paths.ts

@@ -0,0 +1,48 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { mkdirSync } from "node:fs";
+
+/** ~/.cctra 目录路径 */
+export function cctraDir(): string {
+  return join(homedir(), ".cctra");
+}
+
+/** ~/.cctra/config.toml 路径 */
+export function configTomlPath(): string {
+  return join(cctraDir(), "config.toml");
+}
+
+/** ~/.cctra/daemon.log 路径 */
+export function daemonLogPath(): string {
+  return join(cctraDir(), "daemon.log");
+}
+
+/** ~/.cctra/models-cache.json 路径 */
+export function modelsCachePath(): string {
+  return join(cctraDir(), "models-cache.json");
+}
+
+/** ~/.cctra/plugins/<name>/ 目录 */
+export function pluginDir(name: string): string {
+  return join(cctraDir(), "plugins", name);
+}
+
+/** ~/.cctra/plugins/<name>/config.json 路径 */
+export function pluginConfigPath(name: string): string {
+  return join(pluginDir(name), "config.json");
+}
+
+/** Windows: %USERPROFILE%/.cctra/bin/cctra-daemon.exe */
+export function windowsLauncherPath(): string {
+  return join(cctraDir(), "bin", "cctra-daemon.exe");
+}
+
+/** 确保目录存在 */
+export function ensureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+/** 确保 cctra 目录存在 */
+export function ensureCctraDir(): void {
+  ensureDir(cctraDir());
+}