@chenpu17/cc-gw 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 chenpu17
+
+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,228 @@
+# cc-gw
+
+> **中文** | [English](#english)
+
+cc-gw 是一个面向 Claude Code 与同类客户端的本地多模型网关，负责：
+
+- 归一化 `/v1/messages` 请求并映射到不同 Provider / 模型
+- 复刻 Claude API 的流式与工具调用语义
+- 记录请求日志、Token（含缓存命中）、TTFT/TPOT 等运行指标
+- 提供可视化 Web 管理台与守护进程 CLI
+
+核心组件：
+
+| 模块 | 说明 |
+| ---- | ---- |
+| `@cc-gw/server` | Fastify 服务，实现协议转换、模型路由、Provider 适配与日志存储 |
+| `@cc-gw/web` | React + Vite Web UI，包含仪表盘、日志面板、模型管理、系统设置 |
+| `@cc-gw/cli` | CLI 守护工具，封装 start/stop/restart/status 并托管 PID/日志 |
+
+## 快速开始
+
+### 推荐方式：npm 全局安装
+
+```bash
+npm install -g @chenpu17/cc-gw
+cc-gw start --daemon --port 4100
+```
+
+首启会在 `~/.cc-gw/config.json` 生成配置模板，推荐直接通过 Web UI (`http://127.0.0.1:4100/ui`) 完成所有后续配置与调整。`cc-gw status`、`cc-gw stop`、`cc-gw restart` 可用于日常运维。
+
+### 从源码构建（开发者）
+
+前置：Node.js 18.18+（推荐 20 LTS）、pnpm 8+
+
+```bash
+pnpm install
+pnpm --filter @cc-gw/server build
+pnpm --filter @cc-gw/web build
+pnpm --filter @cc-gw/cli exec tsx index.ts start --daemon --port 4100
+```
+
+### 连接 Claude Code
+1. 启动 cc-gw 并确认配置中 `host` 为 `127.0.0.1`，`port` 与 CLI 启动一致。
+2. 在安装了 Claude Code 的终端设置环境变量：
+   ```bash
+   export ANTHROPIC_BASE_URL=http://127.0.0.1:4100
+   claude "help me review this file"
+   ```
+3. cc-gw 会根据 `modelRoutes`/默认策略将 Claude 请求路由到已配置的目标模型（如 Kimi、火山 DeepSeek、OpenAI 或自建模型）。
+
+## 配置说明
+
+配置文件位于 `~/.cc-gw/config.json`：
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 4100,
+  "providers": [
+    {
+      "id": "kimi",
+      "label": "Moonshot Kimi",
+      "type": "kimi",
+      "baseUrl": "https://api.moonshot.cn/v1",
+      "apiKey": "sk-...",
+      "models": [
+        { "id": "kimi-k2-0905-preview", "label": "Kimi K2" }
+      ]
+    },
+    {
+      "id": "anthropic",
+      "label": "Claude",
+      "type": "anthropic",
+      "baseUrl": "https://api.anthropic.com",
+      "apiKey": "sk-ant-...",
+      "models": [
+        { "id": "claude-3-5-sonnet-latest" }
+      ]
+    }
+  ],
+  "defaults": {
+    "completion": "kimi:kimi-k2-0905-preview",
+    "reasoning": "anthropic:claude-3-5-sonnet-latest",
+    "background": "kimi:kimi-k2-0905-preview",
+    "longContextThreshold": 60000
+  },
+  "modelRoutes": {
+    "claude-sonnet-4-20250514": "kimi:kimi-k2-0905-preview",
+    "claude-opus-4-1-20250805": "anthropic:claude-3-5-sonnet-latest"
+  },
+  "logRetentionDays": 30,
+  "storePayloads": true
+}
+```
+
+字段要点（建议仍以 Web UI “系统设置 / 模型管理” 进行操作，下列仅便于理解结构）：
+
+- `providers`：定义上游服务；`type` 支持 `openai | anthropic | kimi | deepseek | custom`。
+- 模型标识使用 `providerId:modelId` 形式供路由引用。
+- `modelRoutes`：将 Claude 发起的模型名映射到上游模型；未命中时使用 `defaults`。
+- `storePayloads`：是否在 SQLite 中压缩保存原始请求/响应（Brotli），关闭后仅保留元信息。
+- 推荐通过 Web UI 的“模型管理 / 系统设置”在线编辑并热加载，无需手工修改文件。
+
+### 环境变量
+
+| 变量 | 说明 |
+| ---- | ---- |
+| `PORT` | CLI 启动时临时覆盖监听端口 |
+| `CC_GW_UI_ROOT` | 指定 Web UI 静态目录（默认自动检测 `@cc-gw/web` build 结果） |
+| `CC_GW_DEBUG_ENDPOINTS` | 设为 `1` 可在日志中输出下游请求 URL |
+
+## Web 管理台
+
+访问 `http://<host>:<port>/ui`，主要页面：
+
+- **Dashboard**：展示请求量、Token 使用、缓存命中、各模型 TTFT（Time To First Token）/TPOT（Total Processing Time）、SQLite 数据库占用。
+- **请求日志**：多条件筛选（时间、Provider、模型、状态），查看压缩日志详情，支持分页导出与清理。
+- **模型管理**：维护 Provider 列表、预置模型、路由策略；一键测试连通性（发送诊断 PROMPT）。
+- **系统设置**：端口、日志保留策略、是否存储请求 payload、日志清理工具。
+
+UI 支持中英文、深色/浅色主题以及移动端响应式布局，提供键盘可达性（Skip Link、焦点管理）。
+
+## CLI 守护
+
+```bash
+pnpm --filter @cc-gw/cli exec tsx index.ts start [--daemon] [--port 4100]
+pnpm --filter @cc-gw/cli exec tsx index.ts stop
+pnpm --filter @cc-gw/cli exec tsx index.ts restart [--daemon] [--port 4100]
+pnpm --filter @cc-gw/cli exec tsx index.ts status
+```
+
+- 守护模式下 PID/日志存放于 `~/.cc-gw/cc-gw.pid` 与 `~/.cc-gw/logs/cc-gw.log`。
+- `status` 会回显配置与日志路径，便于排查。
+
+## 数据与日志
+
+- 数据库：`~/.cc-gw/data/gateway.db`（`better-sqlite3`）。
+  - `request_logs`：请求摘要、路由结果、耗时、TTFT/TPOT。
+  - `request_payloads`：压缩的请求/响应正文（Brotli）。
+  - `daily_metrics`：按日聚合的调用次数与 Token 统计。
+- 日志：`~/.cc-gw/logs/cc-gw.log`，包含请求生命周期、Provider 调用与 usage 摘要（`event: usage.metrics`）。
+
+## 常见问题
+
+- **Web UI 404**：请确认执行过 `pnpm --filter @cc-gw/web build`，并在 CLI 启动时自动或手动设置 `CC_GW_UI_ROOT`。
+- **usage 中无 `cached_tokens`**：部分 Provider（如火山 DeepSeek）需开启 `stream_options.include_usage` 或提供专有缓存参数；cc-gw 已在支持的适配器中自动注入，如仍为 `null` 需确认上游是否支持。
+- **日志数据库过大**：可在“系统设置”关闭 payload 保存或缩短保留天数；Web UI 亦提供手动清理工具。
+
+---
+
+## English
+
+cc-gw is a local gateway tailored for Claude Code and similar Anthropic-compatible clients. It normalizes `/v1/messages`, routes traffic across heterogeneous providers, mirrors Claude’s streaming & tool semantics, and records detailed metrics that surface in a bilingual Web console and CLI daemon.
+
+### Highlights
+
+| Feature | Details |
+| ------- | ------- |
+| Protocol adaptation | Converts Claude-style payloads into OpenAI-, Anthropic-, Kimi-, and DeepSeek-compatible requests while preserving tool calls and reasoning blocks. |
+| Model routing | Maps incoming model IDs to configured upstream providers with fallbacks for long-context and background tasks. |
+| Observability | Persists request logs, token usage (including cache hits), TTFT, TPOT, and daily aggregates in SQLite with Brotli-compressed payloads. |
+| Web console | React + Vite UI with dashboards, filters, provider CRUD, bilingual copy, and responsive layout. |
+| CLI daemon | `cc-gw` command wraps start/stop/restart/status, manages PID/log files, and scaffolds a default config on first launch. |
+
+### Quick Start
+
+```bash
+npm install -g @chenpu17/cc-gw
+cc-gw start --daemon --port 4100
+```
+
+The first launch writes `~/.cc-gw/config.json`. Manage everything through the Web UI at `http://127.0.0.1:4100/ui`. Use `cc-gw status`, `cc-gw stop`, and `cc-gw restart` to control the daemon.
+
+### From Source (contributors)
+
+```bash
+pnpm install
+pnpm --filter @cc-gw/server build
+pnpm --filter @cc-gw/web build
+pnpm --filter @cc-gw/cli exec tsx index.ts start --daemon --port 4100
+```
+
+Connect Claude Code by pointing `ANTHROPIC_BASE_URL` to your local gateway:
+
+```bash
+export ANTHROPIC_BASE_URL=http://127.0.0.1:4100
+claude "help me review this file"
+```
+
+### Configuration Snapshot
+
+- Providers include `type`, `baseUrl`, `apiKey`, and `models` descriptions.
+- Model routes use `providerId:modelId` syntax to remap Claude requests.
+- `storePayloads` toggles compressed body retention; disable to keep only metadata.
+- Web UI allows editing without restarting; CLI restart will pick up bundle changes after rebuilds.
+
+### Observability & Storage
+
+- SQLite file under `~/.cc-gw/data/gateway.db` tracks logs and aggregated metrics.
+- Dashboard surfaces per-model TTFT/TPOT, cache hits, and DB size.
+- Logs can be filtered/exported/cleaned directly from the UI.
+
+### CLI Reference
+
+| Command | Description |
+| ------- | ----------- |
+| `cc-gw start [--daemon] [--port]` | Launch the Fastify server, auto-creating config if missing. |
+| `cc-gw stop` | Send SIGTERM and remove stale PID files. |
+| `cc-gw restart` | Convenience wrapper for stop + start. |
+| `cc-gw status` | Show running status, PID, log directory, config path. |
+
+### Environment
+
+| Variable | Purpose |
+| -------- | ------- |
+| `PORT` | Override listening port at launch. |
+| `CC_GW_UI_ROOT` | Manually point to the built web assets. |
+| `CC_GW_DEBUG_ENDPOINTS=1` | Log upstream provider endpoints for debugging. |
+
+### Tips
+
+- Always rebuild `@cc-gw/server` and `@cc-gw/web` before restarts to ensure the daemon picks up new code.
+- If cache statistics remain zero, verify whether the upstream provider exposes `cached_tokens` or equivalent details.
+- Back up `~/.cc-gw/` (config, logs, SQLite DB) for migrations or disaster recovery.
+
+---
+
+欢迎通过 Issue / PR 反馈改进意见，也可以在 Web UI 的“关于”页查看贡献者信息与致谢。

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@chenpu17/cc-gw",
+  "version": "0.2.1",
+  "private": false,
+  "type": "module",
+  "scripts": {
+    "dev": "pnpm --filter server dev",
+    "build": "pnpm run build:server && pnpm run build:web",
+    "build:server": "pnpm --filter @cc-gw/server build",
+    "build:cli": "pnpm --filter @cc-gw/cli build",
+    "build:web": "pnpm --filter @cc-gw/web build",
+    "build:all": "pnpm run build:server && pnpm run build:cli && pnpm run build:web",
+    "release:bundle": "pnpm run build:all && node scripts/build-release.mjs",
+    "prepack": "pnpm run build:all",
+    "lint": "pnpm exec eslint .",
+    "format": "pnpm exec prettier --check .",
+    "format:write": "pnpm exec prettier --write .",
+    "typecheck": "pnpm -r exec tsc --noEmit",
+    "test": "pnpm exec vitest run"
+  },
+  "bin": {
+    "cc-gw": "src/cli/dist/index.js"
+  },
+  "files": [
+    "src/cli/dist",
+    "src/server/dist",
+    "src/web/dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "pnpm": {
+    "peerDependencyRules": {
+      "ignoreMissing": [
+        "react",
+        "react-dom"
+      ]
+    }
+  },
+  "packageManager": "pnpm@9.0.0",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "description": "Self-hosted Claude Code compatible gateway with web console and CLI daemon.",
+  "license": "MIT",
+  "keywords": [
+    "claude",
+    "gateway",
+    "ai",
+    "fastify"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chenpu17/cc-gw.git"
+  },
+  "dependencies": {
+    "@fastify/cors": "^9.0.1",
+    "@fastify/static": "^7.0.4",
+    "better-sqlite3": "^9.0.0",
+    "commander": "^12.0.0",
+    "colorette": "^2.0.20",
+    "fastify": "^4.26.2",
+    "open": "^10.1.0",
+    "tiktoken": "^1.0.21",
+    "undici": "^6.11.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.5.0",
+    "@types/node": "^20.12.7",
+    "eslint": "^8.57.0",
+    "globals": "^15.0.0",
+    "prettier": "^3.2.5",
+    "typescript": "^5.4.3",
+    "typescript-eslint": "^7.5.0",
+    "vitest": "^1.6.0"
+  }
+}

package/src/cli/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/src/cli/dist/index.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+// index.ts
+import { Command } from "commander";
+import { spawn } from "child_process";
+import fs from "fs";
+import { promises as fsp } from "fs";
+import os from "os";
+import path from "path";
+import process from "process";
+import { fileURLToPath } from "url";
+import { green, yellow } from "colorette";
+var program = new Command();
+var DEFAULT_PORT = 3456;
+var HOME_DIR = path.join(os.homedir(), ".cc-gw");
+var PID_FILE = path.join(HOME_DIR, "cc-gw.pid");
+var LOG_DIR = path.join(HOME_DIR, "logs");
+var LOG_FILE = path.join(LOG_DIR, "cc-gw.log");
+var CONFIG_FILE = path.join(HOME_DIR, "config.json");
+function resolveServerEntry() {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  const candidates = [
+    path.resolve(__dirname, "../../server/dist/index.js"),
+    path.resolve(__dirname, "../server/dist/index.js"),
+    path.resolve(__dirname, "../../../src/server/dist/index.js")
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error("Server bundle not found. \u8BF7\u5148\u6784\u5EFA @cc-gw/server (pnpm --filter @cc-gw/server build)");
+}
+function resolveWebDist() {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  const candidates = [
+    path.resolve(__dirname, "../web/dist"),
+    path.resolve(__dirname, "../../web/dist"),
+    path.resolve(__dirname, "../../../src/web/dist"),
+    path.resolve(process.cwd(), "src/web/dist")
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+async function ensureHomeDir() {
+  await fsp.mkdir(LOG_DIR, { recursive: true });
+}
+async function ensureConfigTemplate(port) {
+  try {
+    await fsp.access(CONFIG_FILE);
+    return false;
+  } catch {
+    const selectedPort = port ? Number.parseInt(port, 10) || DEFAULT_PORT : DEFAULT_PORT;
+    const template = {
+      host: "127.0.0.1",
+      port: selectedPort,
+      providers: [],
+      defaults: {
+        completion: null,
+        reasoning: null,
+        background: null,
+        longContextThreshold: 6e4
+      },
+      logRetentionDays: 30,
+      modelRoutes: {},
+      storePayloads: true
+    };
+    await fsp.mkdir(path.dirname(CONFIG_FILE), { recursive: true });
+    await fsp.writeFile(CONFIG_FILE, JSON.stringify(template, null, 2), "utf-8");
+    return true;
+  }
+}
+async function readPid() {
+  try {
+    const raw = await fsp.readFile(PID_FILE, "utf-8");
+    const pid = Number.parseInt(raw.trim(), 10);
+    return Number.isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+async function writePid(pid) {
+  if (pid == null)
+    return;
+  await fsp.writeFile(PID_FILE, String(pid), "utf-8");
+}
+async function removePid() {
+  try {
+    await fsp.unlink(PID_FILE);
+  } catch {
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isServiceRunning() {
+  const pid = await readPid();
+  if (!pid)
+    return { running: false };
+  if (isProcessAlive(pid)) {
+    return { running: true, pid };
+  }
+  await removePid();
+  return { running: false };
+}
+async function handleStart(options) {
+  await ensureHomeDir();
+  const { running, pid } = await isServiceRunning();
+  if (running && pid) {
+    console.log(yellow(`cc-gw \u5DF2\u5728\u8FD0\u884C (pid: ${pid})`));
+    return;
+  }
+  const configCreated = await ensureConfigTemplate(options.port);
+  const serverEntry = resolveServerEntry();
+  const env = { ...process.env };
+  if (options.port) {
+    env.PORT = options.port;
+  }
+  if (!env.CC_GW_UI_ROOT) {
+    const uiRoot = resolveWebDist();
+    if (uiRoot) {
+      env.CC_GW_UI_ROOT = uiRoot;
+    }
+  }
+  const spawnOptions = {
+    env,
+    detached: Boolean(options.daemon),
+    stdio: options.daemon ? [
+      "ignore",
+      fs.openSync(LOG_FILE, "a"),
+      fs.openSync(LOG_FILE, "a")
+    ] : "inherit"
+  };
+  const child = spawn(process.execPath, [serverEntry], spawnOptions);
+  child.on("error", (err) => {
+    console.error("\u542F\u52A8 cc-gw \u5931\u8D25:", err);
+  });
+  await writePid(child.pid);
+  if (options.daemon) {
+    child.unref();
+    console.log(green(`cc-gw \u5DF2\u4EE5\u5B88\u62A4\u8FDB\u7A0B\u65B9\u5F0F\u542F\u52A8 (pid: ${child.pid})`));
+  }
+  const effectivePort = options.port ? Number.parseInt(options.port, 10) || DEFAULT_PORT : DEFAULT_PORT;
+  if (configCreated) {
+    console.log(green(`\u5DF2\u5728 ${CONFIG_FILE} \u751F\u6210\u9ED8\u8BA4\u914D\u7F6E`));
+    console.log(yellow(`\u9996\u6B21\u542F\u52A8\uFF1A\u5F85\u670D\u52A1\u5C31\u7EEA\u540E\uFF0C\u8BF7\u5728\u6D4F\u89C8\u5668\u8BBF\u95EE http://127.0.0.1:${effectivePort}/ui \u8FDB\u884C\u914D\u7F6E\u3002`));
+  }
+}
+async function handleStop() {
+  const pid = await readPid();
+  if (!pid) {
+    console.log(yellow("cc-gw \u672A\u5728\u8FD0\u884C\u3002"));
+    return;
+  }
+  if (!isProcessAlive(pid)) {
+    console.log(yellow("\u68C0\u6D4B\u5230\u9648\u65E7\u7684 PID \u6587\u4EF6\uFF0C\u5DF2\u6E05\u7406\u3002"));
+    await removePid();
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+    console.log(green(`\u5DF2\u5411\u8FDB\u7A0B ${pid} \u53D1\u9001 SIGTERM`));
+  } catch (err) {
+    console.error(`\u505C\u6B62 cc-gw \u5931\u8D25: ${err.message}`);
+  } finally {
+    await removePid();
+  }
+}
+async function handleStatus() {
+  const { running, pid } = await isServiceRunning();
+  if (running && pid) {
+    console.log(green(`cc-gw \u6B63\u5728\u8FD0\u884C (pid: ${pid})`));
+  } else {
+    console.log(yellow("cc-gw \u672A\u5728\u8FD0\u884C\u3002"));
+  }
+  console.log(`PID \u6587\u4EF6: ${PID_FILE}`);
+  console.log(`\u65E5\u5FD7\u76EE\u5F55: ${LOG_DIR}`);
+  console.log(`\u914D\u7F6E\u6587\u4EF6: ${CONFIG_FILE}`);
+}
+program.name("cc-gw").description("Claude Code Gateway CLI").version("0.1.0");
+program.command("start").description("\u542F\u52A8 cc-gw \u670D\u52A1").option("--daemon", "\u4EE5\u5B88\u62A4\u8FDB\u7A0B\u65B9\u5F0F\u8FD0\u884C").option("--port <port>", "\u6307\u5B9A\u670D\u52A1\u76D1\u542C\u7AEF\u53E3").action(async (options) => {
+  try {
+    await handleStart(options);
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+  }
+});
+program.command("stop").description("\u505C\u6B62 cc-gw \u670D\u52A1").action(async () => {
+  await handleStop();
+});
+program.command("restart").description("\u91CD\u542F cc-gw \u670D\u52A1").option("--daemon", "\u4EE5\u5B88\u62A4\u8FDB\u7A0B\u65B9\u5F0F\u8FD0\u884C").option("--port <port>", "\u6307\u5B9A\u670D\u52A1\u76D1\u542C\u7AEF\u53E3").action(async (options) => {
+  await handleStop();
+  await handleStart(options);
+});
+program.command("status").description("\u67E5\u770B cc-gw \u8FD0\u884C\u72B6\u6001").action(async () => {
+  await handleStatus();
+});
+program.parseAsync(process.argv);