cctra 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cha133
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# cctra
+
+> Local LLM subscription protocol converter + plugin host
+
+`cctra` runs a daemon on `127.0.0.1:3133` that translates between **OpenAI Chat Completions / OpenAI Responses / Anthropic Messages**, with a **tier-based model aliasing** system and **local-path plugin** support for non-standard upstream auth (OAuth, mTLS, etc.).
+
+## Quick start
+
+```bash
+# install (once)
+bun add -g cctra
+# or npm i -g cctra
+
+# add a subscription (interactive)
+cctra add
+
+# start the daemon (foreground)
+cctra serve
+
+# or install as system startup item (Windows / macOS / Linux)
+cctra daemon install
+cctra daemon start
+```
+
+## Endpoints
+
+cctra exposes exactly **3 protocol endpoints** on `127.0.0.1:3133`:
+
+| Protocol | Path |
+|---|---|
+| Anthropic Messages | `POST /anthropic/v1/messages` |
+| OpenAI Chat Completions | `POST /v1/chat/completions` |
+| OpenAI Responses | `POST /v1/responses` |
+| OpenAI Models | `GET /v1/models` |
+| Health | `GET /healthz` |
+
+### Client configuration
+
+⚠️ **baseURL must include the protocol namespace prefix**:
+
+| Client | baseURL |
+|---|---|
+| Claude Code | `http://127.0.0.1:3133/anthropic` |
+| OpenAI SDK / Codex / Cursor | `http://127.0.0.1:3133/v1` |
+
+## Tier aliases
+
+cctra ships 4 built-in semantic tier names that you map to concrete `(subscription, model)` pairs:
+
+| Tier | Purpose |
+|---|---|
+| `cctra` | Default (medium quality, cheap) |
+| `cctra-pro` | Deep reasoning (slow but strong) |
+| `cctra-flash` | High speed (small & fast) |
+| `cctra-vision` | Multimodal |
+
+```bash
+# map cctra-pro to your actual deepseek model
+cctra tier set cctra-pro ark-agent-plan/deepseek-v4-pro
+
+# now configure Claude Code to use it (won't change when you switch models)
+# ANTHROPIC_MODEL=cctra-pro
+```
+
+## Plugin system
+
+Add custom JS plugins for non-standard upstream auth:
+
+```bash
+cctra plugin add my-internal /path/to/my-internal.js
+cctra plugin ls
+cctra plugin enable my-internal
+cctra plugin disable my-internal
+cctra plugin rm my-internal
+```
+
+A plugin exports:
+
+```js
+export default {
+  name: "my-internal-llm",
+  displayName: "My Company LLM",
+  async getConfig(ctx) {
+    // OAuth / mTLS / custom header logic
+    return { baseUrl: "...", path: "/v1/chat/completions", apiFormat: "openai-chat", authHeader: { /* ... */ }, modelId: "..." };
+  },
+  async listModels(ctx) { return [{ id: "..." }, { id: "..." }]; },
+};
+```
+
+See `examples/plugins/` for working examples.
+
+## CLI
+
+```
+cctra add                    # interactive subscription wizard
+cctra ls                     # list all sources
+cctra show <name>            # show details
+cctra rm <name>              # remove
+cctra rename <old> <new>     # rename
+cctra model add <sub>        # add model to a subscription
+cctra model ls <sub>         # list models
+cctra model rm <sub> <m>     # remove model
+cctra model rename <sub> <m> <alias>
+cctra plugin add <name> <path>
+cctra plugin ls / show / enable / disable / rm
+cctra tier set <name> <target>
+cctra tier ls / show / rm
+cctra daemon install / uninstall / start / stop / status
+cctra serve [--port N]       # foreground HTTP server
+```
+
+## Configuration
+
+Persisted at `~/.cctra/config.toml` (TOML format, edited via CLI).
+
+Plugin configs go in `~/.cctra/plugins/<name>/config.json`.
+
+## Architecture
+
+- `src/canonical/` — protocol-agnostic internal types
+- `src/convert/` — bidirectional protocol conversions
+- `src/server/` — Bun.serve() routes, upstream forwarding
+- `src/plugin/` — local-path plugin loader + author contract
+- `src/tier/` — 4 builtin tier system
+- `src/daemon/` — cross-platform install (Windows registry / macOS LaunchAgent / Linux systemd)
+- `launcher/` — tiny Rust .exe for Windows startup (hides console, registers in Task Manager)
+
+## Credits
+
+The vendor preset list (`src/providers/presets.ts`) — provider names and endpoint URLs — is derived from [cc-switch](https://github.com/farion1231/cc-switch) (MIT, Copyright (c) 2025 Jason Young). Thanks to Jason and the cc-switch contributors for maintaining this comprehensive registry.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/cctra

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import("../src/index.ts");

package/bin/cctra.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import("../src/index.ts");

package/examples/plugins/oauth-internal.js

@@ -0,0 +1,46 @@
+// ============================================================================
+// 示例插件：内部公司服务，OAuth 鉴权
+// 演示 token 缓存、refresh、ctx.fetch 用法
+// ============================================================================
+
+export default {
+  name: "oauth-internal",
+  displayName: "Internal OAuth Service",
+
+  async getConfig(ctx) {
+    const { clientId, clientSecret, baseUrl, modelIds, workspaceId } = ctx.config;
+
+    // 缓存 token（避免每次请求都重新拿）
+    let tokenData = await ctx.cacheGet("oauth-token");
+    if (!tokenData) {
+      tokenData = await refreshToken(clientId, clientSecret);
+      // token 提前 60s 过期，留缓冲
+      await ctx.cacheSet("oauth-token", tokenData, (tokenData.expires_in - 60) * 1000);
+      ctx.logger(`refreshed OAuth token, expires in ${tokenData.expires_in}s`);
+    }
+
+    return modelIds.map((id) => ({
+      baseUrl: baseUrl.replace(/\/+$/, ""),
+      path: "/v1/chat/completions",
+      apiFormat: "openai-chat",
+      authHeader: {
+        Authorization: `Bearer ${tokenData.access_token}`,
+        "X-Workspace-Id": workspaceId,
+      },
+      modelId: id,
+    }));
+  },
+
+  async listModels(ctx) {
+    return ctx.config.modelIds.map((id) => ({ id }));
+  },
+};
+
+async function refreshToken(_clientId, _clientSecret) {
+  // v1 示例：实际应调用 OAuth 端点
+  // 这里模拟一个 token
+  return {
+    access_token: "simulated-token-" + Date.now(),
+    expires_in: 3600,
+  };
+}

package/examples/plugins/openai-compatible.js

@@ -0,0 +1,27 @@
+// ============================================================================
+// 示例插件：标准 OpenAI 兼容端点（无鉴权）
+// 复制到 ~/.cctra/plugins/openai-compatible.js 后用 `cctra plugin add` 注册
+// ============================================================================
+
+export default {
+  name: "openai-compatible",
+  displayName: "OpenAI-Compatible Endpoint",
+
+  async getConfig(ctx) {
+    // 用户填的 config（来自 cctra plugin add 时输入）
+    const { baseUrl, token, modelIds } = ctx.config;
+
+    return modelIds.map((id) => ({
+      baseUrl: baseUrl.replace(/\/+$/, ""),
+      path: "/v1/chat/completions",
+      apiFormat: "openai-chat",
+      authHeader: token ? { Authorization: `Bearer ${token}` } : {},
+      modelId: id,
+    }));
+  },
+
+  async listModels(ctx) {
+    const { modelIds } = ctx.config;
+    return modelIds.map((id) => ({ id, alias: id }));
+  },
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "cctra",
+  "version": "0.3.0",
+  "description": "Local LLM subscription protocol converter + plugin host. Run a daemon on 127.0.0.1:3133 that translates between OpenAI Chat / OpenAI Responses / Anthropic Messages, with a tier-based model aliasing system and local-path plugin support.",
+  "type": "module",
+  "bin": {
+    "cctra": "bin/cctra.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "serve": "bun run src/index.ts serve",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "verify": "bunx tsc --noEmit && bun test",
+    "publish": "pwsh -ExecutionPolicy Bypass -File scripts/publish.ps1"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "keywords": [
+    "llm",
+    "proxy",
+    "openai",
+    "anthropic",
+    "claude-code",
+    "codex",
+    "translation",
+    "plugin"
+  ],
+  "license": "MIT",
+  "author": "cha133",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cha133/cctra.git"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.0",
+    "commander": "^15.0.0",
+    "confbox": "^0.2.4",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/src/canonical/types.ts

@@ -0,0 +1,132 @@
+// ============================================================================
+// Canonical 内部表示：与具体协议解耦的统一数据结构
+// shape 接近 Anthropic Messages（因为它表达能力最丰富）
+// ============================================================================
+
+export type ApiFormat = "openai-chat" | "openai-responses" | "anthropic-messages";
+
+export type StopReason = "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | "error";
+
+// ---------- Per-protocol extras（透传未识别字段） ----------
+
+/**
+ * 按协议分类的「未识别字段」桶。
+ * - inbound 时把协议原请求中未识别的字段塞进对应协议桶
+ * - outbound 时按目标协议把对应桶 spread 进结果对象
+ * 例：anthropic → canonical → anthropic 链路里 cache_control 字段不会丢失
+ */
+export interface ProtocolExtras {
+  anthropic?: Record<string, unknown>;
+  openaiChat?: Record<string, unknown>;
+  openaiResponses?: Record<string, unknown>;
+}
+
+// ---------- Request ----------
+
+export interface CanonicalRequest {
+  model: string;
+  messages: CanonicalMessage[];
+  system?: string | CanonicalContentBlock[];
+  tools?: CanonicalTool[];
+  maxTokens?: number;
+  temperature?: number;
+  topP?: number;
+  stopSequences?: string[];
+  stream: boolean;
+  metadata?: Record<string, unknown>;
+  // OpenAI Responses 多轮链路 ID（cctra 仅做透传，不维护链路状态）
+  previousResponseId?: string;
+  // 思考强度（OpenAI Responses `reasoning.effort` / Anthropic `thinking.budget_tokens` 的统一抽象）
+  reasoning?: { effort?: "low" | "medium" | "high" };
+  // 透传未识别字段（按协议分类）
+  extras?: ProtocolExtras;
+}
+
+export interface CanonicalMessage {
+  role: "user" | "assistant";
+  content: CanonicalContentBlock[];
+  extras?: ProtocolExtras;
+}
+
+export type CanonicalContentBlock = (
+  | { type: "text"; text: string }
+  | { type: "image"; source: ImageSource }
+  | { type: "document"; source: DocumentSource }
+  | { type: "tool_use"; id: string; name: string; input: unknown }
+  | { type: "tool_result"; toolUseId: string; content: string | CanonicalContentBlock[]; isError?: boolean }
+  | { type: "thinking"; thinking: string; signature?: string }
+  | { type: "refusal"; refusal: string }
+) & { extras?: ProtocolExtras };
+
+export interface ImageSource {
+  kind: "url" | "base64";
+  mediaType: string;            // e.g. "image/png"
+  data: string;                 // URL string or base64-encoded data
+}
+
+export interface DocumentSource {
+  kind: "url" | "base64";
+  mediaType: string;
+  data: string;
+}
+
+export interface CanonicalTool {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+}
+
+// ---------- Response ----------
+
+/**
+ * 错误响应的结构化字段。
+ * - `message`：人类可读错误消息
+ * - `status`：上游 HTTP status code（4xx/5xx 透传用；plugin/network/parse 错无此字段）
+ * - `type`：错误分类标签
+ */
+export interface CanonicalResponseError {
+  message: string;
+  status?: number;
+  type?: "upstream_error" | "network_error" | "plugin_error" | "parse_error";
+}
+
+export interface CanonicalResponse {
+  id: string;
+  model: string;
+  content: CanonicalContentBlock[];
+  stopReason: StopReason;
+  usage: CanonicalUsage;
+  /** 错误响应的结构化字段（替代过去用 `content[0].text` + `stopReason: "error"` 表达错误） */
+  error?: CanonicalResponseError;
+}
+
+export interface CanonicalUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+// ---------- Streaming Chunks ----------
+// 字段跟 Anthropic SSE 几乎一致，方便直接复用 streaming 状态机
+
+export type CanonicalChunk =
+  | { type: "message_start"; message: CanonicalResponse }
+  | { type: "content_block_start"; index: number; content_block: CanonicalContentBlock }
+  | { type: "content_block_delta"; index: number; delta: ContentBlockDelta }
+  | { type: "content_block_stop"; index: number }
+  | { type: "message_delta"; delta: MessageDelta; usage?: Partial<CanonicalUsage> }
+  | { type: "message_stop" }
+  | { type: "ping" }
+  | { type: "error"; error: string };
+
+export type ContentBlockDelta =
+  | { type: "text_delta"; text: string }
+  | { type: "input_json_delta"; partial_json: string }
+  | { type: "thinking_delta"; thinking: string }
+  | { type: "signature_delta"; signature: string };
+
+export interface MessageDelta {
+  stop_reason?: StopReason;
+  stop_sequence?: string;
+}

package/src/commands/add.ts

@@ -0,0 +1,159 @@
+// ============================================================================
+// cctra add：交互式添加订阅
+// ============================================================================
+import * as p from "@clack/prompts";
+import { Command } from "commander";
+import { checkCancel } from "../ui/prompts";
+import { success, error as errorOut, info } from "../ui/format";
+import { withConfig } from "./shared";
+import { addSubscription } from "../core/config";
+import { fetchUpstreamModels } from "../core/model-fetch";
+import {
+  API_FORMAT_LABELS,
+  getEndpointForFormat,
+  getPresetHint,
+  getSupportedApiFormats,
+  getVendorChoices,
+  generateProfileName,
+  NO_VENDOR,
+  type ProviderPreset,
+} from "../providers/presets";
+import type { Subscription, ApiFormat } from "../types";
+
+export function registerAdd(program: Command): void {
+  program
+    .command("add")
+    .description("Interactively add a subscription")
+    .action(async () => {
+      try {
+        const sub = await promptNewSubscription();
+        withConfig((config) => addSubscription(config, sub));
+        success(`Added subscription "${sub.name}" with ${sub.models.length} model(s).`);
+        info(`Run \`cctra serve\` to start the daemon.`);
+      } catch (e) {
+        if ((e as Error).message.includes("cancelled")) return;
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+}
+
+async function promptNewSubscription(): Promise<Subscription> {
+  // 1. Vendor（可跳过 → 走纯手输）
+  const vendor = checkCancel(
+    await p.autocomplete<ProviderPreset>({
+      message: "Select a vendor (type to search, or pick '(不使用供应商)' for custom):",
+      options: getVendorChoices().map((v) => ({
+        value: v,
+        label: v.name,
+        hint: getPresetHint(v),
+      })),
+      placeholder: "Type to filter vendors...",
+    }),
+  );
+  const isCustom = vendor.name === NO_VENDOR.name;
+
+  // 2. 名称（vendor 选中时自动从 vendor.name 生成）
+  const defaultName = isCustom ? "" : generateProfileName(vendor.name);
+  const name = checkCancel(
+    await p.text({
+      message: "Subscription name:",
+      initialValue: defaultName,
+      placeholder: "e.g. ark-agent-plan, deepseek",
+      validate: (v) => {
+        if (!v?.trim()) return "Name is required.";
+        const n = v.trim().toLowerCase();
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(n)) return 'Use kebab-case: lowercase letters, digits, hyphens.';
+        return undefined;
+      },
+    }),
+  );
+
+  // 3. 协议（vendor 选中时只显示该 preset 支持的协议）
+  const supportedFormats = getSupportedApiFormats(vendor);
+  const apiFormat = checkCancel(
+    await p.select<ApiFormat>({
+      message: "Upstream API format:",
+      initialValue: supportedFormats[0],
+      options: supportedFormats.map((format) => ({
+        value: format,
+        label: API_FORMAT_LABELS[format],
+      })),
+    }),
+  );
+
+  // 4. Endpoint（vendor 选中时按协议预填）
+  const endpoint = checkCancel(
+    await p.text({
+      message: "Endpoint URL (root, no /v1 suffix):",
+      initialValue: getEndpointForFormat(vendor, apiFormat),
+      placeholder: "e.g. https://ark.cn-beijing.volces.com/api/plan",
+      validate: (v) => (!v?.trim() ? "Endpoint is required." : undefined),
+    }),
+  );
+
+  // 4.5 提示 vendor 备注（如有）
+  if (vendor.notes && !isCustom) {
+    info(`Note: ${vendor.notes}`);
+  }
+
+  // 5. Token
+  const token = checkCancel(
+    await p.password({
+      message: "API key / token:",
+      validate: (v) => (!v?.trim() ? "Token is required." : undefined),
+    }),
+  );
+
+  // 6. 拉模型列表
+  const s = p.spinner();
+  s.start("Fetching model list from upstream...");
+  let modelNames: string[] = [];
+  try {
+    modelNames = await fetchUpstreamModels({
+      endpoint: endpoint.trim(),
+      token: token.trim(),
+      apiFormat,
+    });
+    s.stop(`Found ${modelNames.length} model(s).`);
+  } catch {
+    s.stop("Failed to fetch models, will add manually.");
+  }
+
+  // 7. 选模型
+  let selected: string[] = [];
+  if (modelNames.length > 0) {
+    const result = checkCancel(
+      await p.multiselect({
+        message: "Select models to add:",
+        options: modelNames.map((m) => ({ value: m, label: m })),
+        required: false,
+      }),
+    );
+    selected = result as string[];
+  }
+
+  if (selected.length === 0) {
+    // 手动输入
+    const manual = checkCancel(
+      await p.text({
+        message: "Enter model IDs (comma-separated):",
+        placeholder: "e.g. deepseek-v4-pro, claude-sonnet-4-6",
+      }),
+    );
+    selected = manual.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+
+  return {
+    kind: "subscription",
+    vendor: isCustom ? undefined : vendor.name,
+    name: name.trim().toLowerCase(),
+    endpoint: endpoint.trim(),
+    token: token.trim(),
+    apiFormat,
+    ...(apiFormat === "openai-responses" ? { responsesPath: "/v1/responses" } : {}),
+    models: selected.map((id) => ({ id })),
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+}

package/src/commands/daemon.ts

@@ -0,0 +1,102 @@
+// ============================================================================
+// cctra daemon <subcommand>：守护进程管理
+// install / uninstall / start / stop / status
+// ============================================================================
+import { Command } from "commander";
+import { install, uninstall, isInstalled } from "../daemon/install";
+import { checkDaemonStatus } from "../daemon/status";
+import { startDaemon } from "../daemon/start";
+import { stopDaemon } from "../daemon/stop";
+import { success, error as errorOut, info, dim, green, red } from "../ui/format";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DAEMON_ENTRYPOINT = join(__dirname, "..", "index.ts");
+
+export function registerDaemon(program: Command): void {
+  const daemon = program.command("daemon").description("Manage the cctra daemon");
+
+  // cctra daemon install
+  daemon
+    .command("install")
+    .description("Install daemon as a system startup item")
+    .action(() => {
+      try {
+        const bundledLauncher = process.platform === "win32"
+          ? join(__dirname, "..", "..", "bin", "cctra-daemon.exe")
+          : undefined;
+        if (process.platform === "win32" && (!bundledLauncher || !existsSync(bundledLauncher))) {
+          errorOut(`Bundled launcher not found: ${bundledLauncher}`);
+          errorOut("Build it first with scripts/build-launcher.ps1");
+          return;
+        }
+        install({ bundledLauncherPath: bundledLauncher, daemonEntrypoint: DAEMON_ENTRYPOINT });
+        success(`Installed cctra daemon for ${process.platform}.`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // cctra daemon uninstall
+  daemon
+    .command("uninstall")
+    .description("Remove daemon from system startup")
+    .action(() => {
+      try {
+        uninstall();
+        success(`Uninstalled cctra daemon.`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // cctra daemon start
+  daemon
+    .command("start")
+    .description("Start the daemon (background)")
+    .action(async () => {
+      try {
+        await startDaemon();
+        success(`Started.`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // cctra daemon stop
+  daemon
+    .command("stop")
+    .description("Stop the daemon")
+    .action(async () => {
+      try {
+        await stopDaemon();
+        success(`Stopped.`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // cctra daemon status
+  daemon
+    .command("status")
+    .description("Check daemon status")
+    .action(async () => {
+      const status = await checkDaemonStatus();
+      const installed = isInstalled();
+      const runningIcon = status.running ? green("✓ running") : red("✗ not running");
+      const installedIcon = installed ? green("✓ installed") : red("✗ not installed");
+      console.log(`Daemon:    ${runningIcon}`);
+      console.log(`Startup:   ${installedIcon}`);
+      console.log(`Port:      ${status.port}`);
+      console.log(dim(`Health:    http://127.0.0.1:${status.port}/healthz`));
+      if (!status.running && !installed) {
+        info(`Run \`cctra daemon install\` to register as a startup item, or \`cctra serve\` to run in foreground.`);
+      }
+    });
+}