CommandCode Proxy v4

中文 | English

一个本地部署、完全兼容 OpenAI Chat Completions 与 Anthropic Messages 的 API 网关，为 Command Code AI（commandcode.ai）提供透明代理。任何 OpenAI 风格的客户端（Cursor、Continue、Aider、OpenWebUI、Hermes、你自己的代码）都能直接指向它，透明地使用 CommandCode 后端模型。

非官方社区工具。逆向自官方 CommandCode CLI wire 协议（/alpha/generate），与 CommandCode 无任何关联。

---

🖼 界面截图 · Screenshots

除命令行外，代理自带一个中文 Web 仪表盘（默认 http://127.0.0.1:9090），用于查看状态、管理账号与查看用量。以下为实际界面截图（均已脱敏）。 Beyond the CLI, the proxy ships a built-in Chinese web dashboard (default http://127.0.0.1:9090) for status, accounts and usage. Real screenshots below, all scrubbed.

控制台总览 · Console Overview

• 一屏掌握运行状态：引擎运行/停止、监听端口、运行时长、当前账号、绑定地址、API 鉴权开关、已注册账号数与可用模型数。
• 顶部可一键切换引擎、切换当前账号、调整额度轮换模式。

模型目录 · Model Catalog

• 官方模型定价目录（上下文 / 输入 / 输出 / 缓存读 / 缓存写 / 能力 / Deal），实时从 commandcode.ai 刷新，也可手动“获取最新模型”。
• 支持关键词搜索、标签筛选（GO / FREE / DEAL / 视觉 / 推理）与排序（输入价、输出价、缓存读、上下文等），令牌数以 K/M 友好显示。

账号与鉴权 · Accounts & Auth

• 支持浏览器登录（OAuth）或粘贴 Key 登录；多账号管理，5 小时额度轮换调度（≥90% 自动切换）。
• 密钥在界面上一律脱敏显示（如 sk-demo-...cccc），可设为当前账号或移除——保证敏感信息不落屏。

✨ 功能特性

• OpenAI /v1/chat/completions — 流式 SSE + 非流式，工具调用（并行工具、流式 tool_calls 增量），视觉（image_url base64/data-URL），reasoning_effort 映射，max_completion_tokens，透传上游 totalUsage 用量
• Anthropic /v1/messages — 流式块生命周期（message_start → content_block_start/delta/stop → signature_delta → message_delta → message_stop），tool_use / tool_result 往返，带签名兼容的 thinking 块，system 块数组
• 忠实还原 wire 翻译 — 经官方 CLI 源码逐行核对：原始 base64 图片块带 mediaType、tool_search→search_tools 别名、按模型细分推理档位 snap、终止性错误不重试列表（model_not_in_plan、premium_credits_exhausted、insufficient credits）
• 可靠性 — 429/5xx/网络错误指数退避重试，空闲流看门狗（不会无限挂起），客户端断开即取消，保证流干净收尾
• 多账号 — 仪表盘 OAuth 浏览器登录 + 手动输入 Key，5 小时额度轮换调度器（≥90% 自动切换）
• 安全默认 — 仅绑定 127.0.0.1（可用 HOST 显式开放局域网），可选 PROXY_API_KEY 共享密钥鉴权，XSS 加固仪表盘，CORS 仅对公共 API 表面开放；所有服务端上游请求经 assertSafeUpstreamUrl 校验（拒绝非 http(s) 协议、内嵌凭据、非 commandcode.ai 的任意 host，且默认拒绝环回/私有/保留地址——除非显式加入允许清单；非回环强制 https），打开浏览器改为无 shell 的 spawn 参数调用（杜绝命令注入）
• 打包 — TypeScript 构建、esbuild 打包、pkg 生成单文件 Windows exe
• 中文仪表盘 — 内置界面为中文，含官方模型定价目录（上下文/输入/输出/缓存读/缓存写/能力/Deal），实时从 commandcode.ai 刷新；模型目录支持搜索、GO/FREE/DEAL/视觉/推理标签筛选与排序，令牌数大数（K/M）友好显示
• 会话明细用量 — 面板的"用量与额度"标签页内置会话明细：逐会话记录 input/output token、耗时、成本、模型、状态，并给出按天趋势折线、模型分布饼图、今日/本周/本月成本卡片；持久化到本地 ~/.commandcode/usage-history.jsonl，重启不丢
• 官方用量总览 — 对齐官方 usage 页面（commandcode.ai/:login/settings/usage）的数据源：Total Tokens（含输入/输出拆分）、Total Runs（成功/失败/成功率）、月度限额进度条来自上游 /alpha/usage/summary 与 /alpha/billing/credits（与页面 /internal/* 接口字段一致，但接受 CLI API Key）；仪表盘新增 GET /api/usage/overview 聚合接口

🚀 快速开始

npm install
npm run dev          # http://127.0.0.1:9090

或生产模式：

npm run build && npm start

或独立二进制：

npm run build:win    # dist/commandcode-proxy-v4.exe —— 零依赖运行

首次启动仪表盘会自动打开。可通过 浏览器登录（OAuth） 或粘贴 API Key 登录。密钥也会自动从 ~/.commandcode/auth.json 或 COMMANDCODE_API_KEY 加载。

🧪 用法

# OpenAI 风格（示例用免费模型，任何套餐可直接跑通）
curl http://127.0.0.1:9090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"meituan/LongCat-2.0:free","messages":[{"role":"user","content":"hi"}]}'

# Anthropic 风格
curl http://127.0.0.1:9090/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model":"meituan/LongCat-2.0:free","max_tokens":1024,"messages":[{"role":"user","content":"hi"}]}'

模型名请以仪表盘"模型"页或 GET /v1/models 返回的实时目录为准；免费/折扣模型标有 FREE / DEAL 标签。

客户端配置：OpenAI 风格设 base URL 为 http://127.0.0.1:9090/v1，Anthropic 风格设为 http://127.0.0.1:9090，密钥随意（若设置了 PROXY_API_KEY 则须一致）。

⚙️ 配置

环境变量	默认值	作用
PORT	9090	监听端口
HOST	127.0.0.1	绑定地址（0.0.0.0 暴露到局域网）
PROXY_API_KEY	未设置	要求 /v1/* 携带该密钥（Bearer 或 x-api-key）
COMMANDCODE_API_KEY	取自 auth.json	上游密钥兜底
COMMANDCODE_API_BASE	https://api.commandcode.ai	上游服务地址
COMMANDCODE_UPSTREAM_ALLOWED_HOSTS	未设置	追加允许的上游 host（逗号分隔，供自建网关/镜像）；环回/私有/保留地址默认拒绝，仅在此显式加入才放行
COMMANDCODE_VERSION	1.27.1	CLI 版本标识头
ROTATION_MODE	manual	auto-quota 启用 30 分钟额度检查
NO_OPEN_BROWSER	未设置	设为 1 跳过仪表盘自动打开
MAX_BODY_MB	64	入站 JSON 请求体上限（MB）；视觉/多图 base64 负载超默认 1MB 会触发 413（FST_ERR_CTP_BODY_TOO_LARGE），范围 1..1024

持久化配置存于可执行文件旁的 config.json。

🛠 开发

npm run typecheck    # tsc --noEmit
npm test             # vitest —— 单元 + 集成（mock 上游）
npm run build:exe    # esbuild 打包
npm run build:win    # Windows exe

测试会拉起一个 mock CommandCode 上游，端到端跑通真实 HTTP 面：流式 chunk 形状、工具调用往返、推理档位 snap、Anthropic 块生命周期。

详见 HERMES_TEST_PROMPT.md 了解 agent 驱动的自测方案（让 LLM agent 穿过代理跑真实行为验证）。

🏗 架构

src/
├── index.ts                      # 启动引导、额度轮换调度、可选鉴权钩子
├── types/index.ts                # OpenAI / Anthropic / CC-wire 契约
├── adapters/commandcode/
│   ├── adapter.ts                # 翻译引擎（两种协议 ↔ CC wire，含中文注释）
│   └── upstream.ts               # HTTP 客户端：重试、空闲看门狗、中止
├── routes/
│   ├── chat.ts                   # POST /v1/chat/completions
│   ├── messages.ts               # POST /v1/messages
│   ├── models.ts                 # GET /v1/models、refresh
│   └── dashboard.ts              # 中文 SPA + 管理 API
└── utils/
    ├── config.ts                 # 账号、OAuth 流程、额度轮换
    ├── models.ts                 # 目录同步 + 模糊模型名解析
    ├── usage-store.ts            # 会话明细持久化 + 聚合统计
    └── logger.ts                 # 净化环形缓冲日志

🔒 安全校验 · Upstream URL safety

代理对所有服务端上游请求做白名单校验，采用 fail-closed（不满足即拒绝），而非降级放行：

校验顺序为：仅允许 http(s) → 拒绝内嵌凭据 → 拒绝环回/私有/保留地址（除非显式允许）→ host 属于 commandcode.ai 及子域或显式允许清单 → 非回环强制 https，全满足才放行。

• 默认只允许 commandcode.ai 及其子域；环回（localhost、127.x、::1）、私有（10.x、172.16-31.x、192.168.x）、保留/链路本地（169.254.x、IPv6 ULA/链路本地）及任意公网地址默认一律拒绝，除非运维显式加入允许清单。
• 环回/私有受控例外：本地 mock 上游、自建网关/镜像与开发测试需通过 COMMANDCODE_UPSTREAM_ALLOWED_HOSTS 显式加入允许清单才放行。这是运维显式配置的受控例外，而非默认放行或客户端可控路径——上游地址只由 COMMANDCODE_API_BASE 等运维环境变量决定，不随客户端请求参数变化，因此不存在把客户端输入导向内网的 SSRF 路径。
• 配套校验：拒绝非 http(s) 协议（防 file:、gopher: 协议混淆）、拒绝内嵌凭据（user:pass@host）、非回环 host 强制 https（防降级明文；回环且显式放行时允许 http，供本地 mock）。

📄 免责声明与许可证

本项目通过观察官方 CLI 的网络行为来与私有 API 互通。上游协议变动时可能失效，使用可能受 CommandCode 服务条款约束。请用自己的账号与凭据使用。

本项目使用 MIT 许可证 发布，详见 LICENSE。

---

English

A local, fully-compatible OpenAI Chat Completions and Anthropic Messages API gateway for CommandCode AI. Point any OpenAI-style client (Cursor, Continue, Aider, OpenWebUI, Hermes, your own code) at it and use CommandCode backend models transparently.

Unofficial, community tool. Reverse-engineered from the official CommandCode CLI wire protocol (/alpha/generate). Not affiliated with CommandCode.

The bilingual Screenshots section above shows the real dashboard UI (console overview, model catalog, accounts), all scrubbed.

Features

• OpenAI /v1/chat/completions — streaming SSE + non-streaming, tool calling (parallel tools, streamed tool_calls deltas), vision (image_url base64/data-URL), reasoning_effort mapping, max_completion_tokens, usage passthrough from upstream totalUsage
• Anthropic /v1/messages — streaming block lifecycle (message_start → content_block_start/delta/stop → signature_delta → message_delta → message_stop), tool_use / tool_result round-trip, thinking blocks with signature compatibility, system block arrays
• Faithful wire translation verified against the original CLI source: raw-base64 image parts with mediaType, tool_search→search_tools aliasing, per-model effort tier snapping, terminal-error no-retry list (model_not_in_plan, premium_credits_exhausted, insufficient credits)
• Reliability — exponential-backoff retries on 429/5xx/network errors, idle-stream watchdog (no infinite hangs), client-disconnect cancellation, clean stream termination guaranteed
• Multi-account — dashboard OAuth browser login + manual key entry, 5-hour quota rotation scheduler (auto-switch ≥90%)
• Secure defaults — binds 127.0.0.1 only (opt-in LAN via HOST), optional PROXY_API_KEY shared-secret auth, XSS-hardened dashboard, CORS limited to the public API surface; all server-side upstream requests are validated by assertSafeUpstreamUrl (rejects non-http(s) schemes, embedded credentials, and any host that is neither commandcode.ai nor explicitly allowlisted, and rejects loopback/private/reserved addresses by default; enforces https for non-loopback), and browser opening uses argument-array spawn (no shell injection)
• Packaging — TypeScript build, esbuild bundle, single-file Windows exe via pkg
• Chinese dashboard — built-in Chinese UI with official model pricing catalog (context/input/output/cache read/cache write/caps/deals) refreshed live from commandcode.ai
• Per-session usage history — the dashboard's Usage tab includes a session detail view: records input/output tokens, latency, cost, model, and status per request, visualized with a daily trend line, model-distribution doughnut, and today/week/month cost cards; persisted to ~/.commandcode/usage-history.jsonl, survives restarts
• Official usage overview — mirrors the data sources of the official usage page (commandcode.ai/:login/settings/usage): Total Tokens (with input/output breakdown), Total Runs (completed/failed/success rate) and a monthly limit progress bar fetched from upstream /alpha/usage/summary and /alpha/billing/credits (same fields as the page's /internal/* endpoints, but accepting CLI API keys); exposed via the new GET /api/usage/overview dashboard endpoint

Quick Start

npm install
npm run dev          # http://127.0.0.1:9090

or production:

npm run build && npm start

or the standalone binary:

npm run build:win    # dist/commandcode-proxy-v4.exe — runs with zero dependencies

On first launch the dashboard opens automatically. Log in via Browser (OAuth) or paste an API key. Keys are also auto-loaded from ~/.commandcode/auth.json or COMMANDCODE_API_KEY.

Configuration

Env var	Default	Purpose
PORT	9090	Listen port
HOST	127.0.0.1	Bind address (0.0.0.0 exposes to LAN)
PROXY_API_KEY	unset	Require this key on /v1/* (Bearer or x-api-key)
COMMANDCODE_API_KEY	from auth.json	Upstream key fallback
COMMANDCODE_API_BASE	https://api.commandcode.ai	Upstream base
COMMANDCODE_UPSTREAM_ALLOWED_HOSTS	unset	Extra allowed upstream hosts (comma-separated, for self-hosted gateways/mirrors); loopback/private/reserved are rejected by default unless added here
COMMANDCODE_VERSION	1.27.1	CLI version header
ROTATION_MODE	manual	auto-quota enables 30-min quota checks
NO_OPEN_BROWSER	unset	Set 1 to skip dashboard auto-open
MAX_BODY_MB	64	Max inbound JSON body size (MB); vision/multi-image base64 payloads exceed the 1MB default (413, FST_ERR_CTP_BODY_TOO_LARGE). Range 1..1024

Persistent config lives in config.json next to the executable.

Development

npm run typecheck    # tsc --noEmit
npm test             # vitest — unit + integration (mock upstream)
npm run build:exe    # esbuild bundle
npm run build:win    # Windows exe

Security

Described in the bilingual Upstream URL safety section above.

All server-side upstream requests pass an allowlist check and fail closed (reject, never degrade):

• By default only commandcode.ai and its subdomains are allowed; loopback (localhost, 127.x, ::1), private (10.x, 172.16-31.x, 192.168.x), reserved/link-local (169.254.x, IPv6 ULA/link-local), and arbitrary public hosts are rejected unless an operator adds them to the allowlist.
• Controlled loopback/private exception: a local mock upstream, self-hosted gateway/mirror, and dev/testing must be explicitly added to COMMANDCODE_UPSTREAM_ALLOWED_HOSTS to be reachable. This is an operator-configured exception, not a default-allowed or client-controlled path — the upstream URL is determined only by operator env vars such as COMMANDCODE_API_BASE, never by client request parameters, so there is no SSRF vector that steers client input to an internal network.
• Additional checks: reject non-http(s) schemes (protocol smuggling like file:, gopher:), reject embedded credentials (user:pass@host), and enforce https for non-loopback hosts (no plaintext downgrade; loopback with explicit allowlist may use http for a local mock).

Disclaimer

This project interoperates with a private API by observing the official CLI's network behavior. It may break when the upstream protocol changes, and usage may be subject to CommandCode's terms of service. Use with your own account and credentials.