diff --git a/README.md b/README.md index d20a772..e6f0ccd 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ # cnb2api -**Your CNB free AI credits, served over a plain OpenAI-compatible API.** +**Turn CNB Cloud Workspace In-Network AI into a High-Availability Production Gateway** + +*Native OpenAI + Anthropic Dual Protocol · Zero-Config Claude Code Direct Connect · Zero Dependencies · v5.2 Self-Healing HA · Terminal Quota Dashboard* [![test](https://github.com/dengyie/cnb2api/actions/workflows/test.yml/badge.svg)](https://github.com/dengyie/cnb2api/actions/workflows/test.yml) ![node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen) @@ -13,25 +15,49 @@ English · [简体中文](README.zh-CN.md) -CNB gives every verified org a monthly pool of free AI credits — but they're -only reachable from **inside** a CNB cloud workspace (the endpoint needs a -pipeline `CNB_TOKEN` and CNB-internal networking). **cnb2api** runs a tiny -reverse proxy inside that workspace and turns it into a stable -`https://…/v1/chat/completions` URL that any OpenAI client can call from -anywhere. - -- 🔓 **Above-board.** It uses only the **official, documented** workspace AI - endpoint with the pipeline `CNB_TOKEN` CNB itself issues — no reverse-engineered - front-end endpoints, no anonymous session scraping, nothing that fights the - platform's rules. -- ♻️ **Survives daily recycling.** CNB reclaims workspaces overnight and the - subdomain changes on every restart. A keepalive loop heals that automatically, - so your clients keep one fixed URL and never notice — an always-on endpoint on - a throwaway machine. -- 🪶 **Zero dependencies.** Node 22+ built-ins only (`fetch` / `AbortSignal` / - streams); tests run on the built-in `node:test` runner. Nothing to `npm install`. -- 📊 **Quota in your terminal.** A one-command dashboard for your AI credits and - core-hours — the only such tool in the CNB ecosystem. +CNB (Cloud Native Builder) provides every verified organization with a generous, recurring monthly allowance: **500 ~ 1,166 AI Credits** (equivalent to up to **~200M tokens/month** with prompt caching) and **1,600 compute core-hours**. However, the official in-network AI completion endpoint is heavily locked down: + +1. 🔒 **Intranet Isolation & Pipeline Auth**: The endpoint is strictly isolated inside the CNB workspace network (public requests are blocked by network policy with HTTP 403 `Blocked by network policy`), and only accepts ephemeral pipeline `CNB_TOKEN` credentials (personal access tokens return HTTP 403 `OpenAPI only allowed in pipeline`). Local IDEs, Cursor, Claude Code, or third-party API aggregators cannot connect directly. +2. 🌊 **Enforced Streaming & Model Mappings**: The upstream API mandates `stream: true` (non-streaming requests throw error 11101), and model names (such as `deepseek-v4-flash`, `glm-5.3-flash`, etc.) undergo internal gateway routing, requiring a robust transformation and aggregation layer. +3. ⏳ **Ephemeral Cloud Workspace Lifecycle (Cattle, Not Pets)**: Workspaces automatically shut down after 10 minutes of inactivity, have an 18-hour session ceiling, and face mandatory overnight reclamation between 04:00 and 06:00 (UTC+8). On every restart, the generated port-proxy subdomain (`{subdomain}-9001.cnb.run`) drifts unpredictably. +4. ⚠️ **Fragility & Risks of Scraping Approaches**: Community alternatives often reverse-engineer anonymous web NPC chat endpoints using headless Chromium, session pools, or CSRF scraping. These lack native Tool Calling, violate platform terms, and break whenever the web interface changes. + +--- + +**cnb2api** is built to solve this: a **lightweight, zero-dependency, 100% compliant high-availability reverse proxy gateway** running directly inside your CNB workspace. It maps the internal AI endpoint to a permanent public URL, powered by an innovative **v5.2 zero-token & dual-watchdog self-healing architecture** that maintains 7×24 uptime on top of ephemeral cloud containers. + +### Key Highlights + +- 🔓 **100% Official & Compliant**: Strictly calls documented workspace AI endpoints using authentic platform pipeline tokens. No reverse-engineering, no web scraping, no anonymous session pools. Native Function / Tool Calling is fully supported. +- ⚡ **First-Class Dual Protocol (OpenAI + Anthropic)**: + - **OpenAI Compatible**: Standard `/v1/chat/completions` and `/v1/models` with SSE streaming and faithful non-streaming state machine aggregation (complete backfilling of `usage`, exact `credit` charges, incremental `tool_calls`, and `finish_reason`). + - **Anthropic Messages Protocol Native**: Native `/v1/messages` and `/v1/messages/count_tokens` enabling **direct connection with Claude Code CLI** (`ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` out of the box), with full streaming event sequence, thinking / reasoning blocks, and bidirectional tool call translation. + - 🛡️ **Built-in Upstream Neutralizer**: Transparently rewrites Claude Code internal billing headers and signature prompt phrases to equivalent expressions, completely bypassing upstream 11128 false-positive blocks without altering user intent. +- ♻️ **v5.2 Zero Long-Lived Credentials + Dual-Watchdog Self-Healing**: + - **Zero Token Leakage**: No static or long-lived platform tokens exist in the workspace. The self-healing cron pipeline uses ephemeral platform `CNB_TOKEN`s minted on the fly and destroyed upon task completion. + - **Automatic Dynamic Routing**: On boot, `start.sh` registers the new subdomain to your relay (`/ops/register`), which hot-reloads nginx upstream configurations. Client BaseURLs and API keys remain permanent. Full recovery drill takes **~2m 13s**. + - **v5.2 Silent Self-Healing Watchdog**: Circumvents CI platform cron dormancy (CNB pauses crons if no commits occur over multiple days). An external watchdog (`cnb-watchdog.sh`) detects stalled states and silently triggers fallback OpenAPI starts with a 30-minute cooldown lock—alerting only on true failures. +- 🪶 **True Zero Dependencies**: Implemented entirely with Node.js 22+ built-ins (`fetch`, `ReadableStream`, `crypto.timingSafeEqual`, `node:test`). Zero `npm install`, sub-millisecond cold starts, minimal memory footprint. +- 📊 **Terminal Quota Dashboard & Token Monitoring**: + - `cnb2api-quota` CLI: One-command ANSI progress bar dashboard displaying AI credits, dev core-hours, CI core-hours, and in-flight deductions directly from the official charge API. Supports `--json` and `--line` modes, runnable even when the proxy is offline. + - In-memory `GET /usage` accounting endpoint grouped by boot generation with UTC+8 daily rollups, ready for Komari or custom monitoring integrations. + +--- + +### Technical Approach Comparison + +| Dimension | cnb2api (This Project) | Community NPC Reverse Proxies | Direct External Calling | +|:---|:---|:---|:---| +| **Access Route** | **Official Workspace Intranet AI Endpoint** | Web frontend anonymous visitor NPC chat | Official AI Endpoint (Public) | +| **Compliance & Account** | **100% Compliant**, consumes your org's quota | Violates ToS, gray-market, ban risk | Cannot call (Network policy blocked) | +| **Network Reachability** | Workspace proxy + dynamic relay, **Public stable access** | Requires headless browser/proxy pools for CSRF | ❌ **403 Blocked by network policy** | +| **Auth Mechanism** | Ephemeral `CNB_TOKEN` via pipeline (Zero leakage) | Web cookies / session scraping | ❌ Personal tokens 403 (Pipeline only) | +| **Protocol Support** | **OpenAI + Anthropic Dual Protocol Stack** | Partial OpenAI text-only imitation | None | +| **Claude Code Direct** | **Native Direct Connect** (with 11128 workaround) | ❌ Unsupported (no tools / blocked) | None | +| **Tool / Function Calling** | **Native full support** (incremental streaming merge) | ❌ Unsupported (frontend has no tools) | None | +| **External Dependencies** | **Zero Dependencies** (Node.js 22+ built-in, instant boot) | Heavy dependencies (Chromium, Puppeteer) | None | +| **High Availability** | **v5.2 Dual-Watchdog Self-Healing** (Internal cron + watchdog) | Single point of failure on UI changes | None | +| **Quota Transparency** | **Built-in Terminal CLI Dashboard** + `/usage` metrics | Black-box, no usage tracking | Only visible deep in web console | ## How it works diff --git a/README.zh-CN.md b/README.zh-CN.md index 591eff4..4280133 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,7 +2,9 @@ # cnb2api -**把 CNB 免费 AI 额度,变成一个标准的 OpenAI 兼容 API。** +**将 CNB 云原生工作区内网 AI 转化为高可用生产级 API 网关** + +*原生支持 OpenAI + Anthropic 双协议栈 · Claude Code 零配置直连 · 0 依赖 · v5.2 双保险自愈高可用 · 终端额度看板* [![test](https://github.com/dengyie/cnb2api/actions/workflows/test.yml/badge.svg)](https://github.com/dengyie/cnb2api/actions/workflows/test.yml) ![node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen) @@ -13,20 +15,49 @@ -CNB 给每个实名组织每月一份免费 AI 额度——但它只能在 CNB 云工作区**内部** -调用(端点需要流水线 `CNB_TOKEN` 和 CNB 内网)。**cnb2api** 在工作区里跑一个 -极小的反向代理,把它变成一个稳定的 `https://…/v1/chat/completions` 地址, -任何 OpenAI 客户端都能从任何地方调用。 - -- 🔓 **生而合规。** 只走**官方文档化**的工作区 AI 端点,用 CNB 自己签发的 - 流水线 `CNB_TOKEN`——不逆向前端接口、不抓匿名会话、不跟平台规则对着干。 -- ♻️ **扛得住每天回收。** CNB 过夜回收工作区、子域名每次重启都变。一个保活 - 循环自动自愈,客户端始终用同一个固定 URL、完全无感——在易逝的机器上攒出 - 一个常年在线的端点。 -- 🪶 **零依赖。** 只用 Node 22+ 内置能力(`fetch` / `AbortSignal` / streams), - 测试跑内置的 `node:test`。没有任何 `npm install`。 -- 📊 **终端里看额度。** 一条命令展示 AI credits 与核时——CNB 生态里独一份的 - 额度工具。 +CNB（云原生构建平台）为每个实名认证组织每月免费提供丰厚的开发者资源：**500 ~ 1,166 AI Credits**（搭配 Prompt Cache 相当于最高 **~2 亿 tokens** 可用量）与 **1,600 核时** 算力。然而，官方内置的 AI 对话补全端点存在严格的网络与环境限制： + +1. 🔒 **内网物理隔离与流水线鉴权**：端点严格限定在 CNB 工作区内网（公网访问直接被网络策略拦截报 403 `Blocked by network policy`）；且鉴权必须使用流水线即时签发的临时 `CNB_TOKEN`（个人访问令牌报 403 `OpenAPI only allowed in pipeline`）。外部 IDE、Cursor、Claude Code 或三方 API 网关无法直连。 +2. 🌊 **强制流式输出与模型路由**：官方 API 强制要求 `stream: true`（非流式请求直接报错 11101），且所有模型（如 deepseek-v4-flash、glm-5.3-flash 等）在底层网关经历统一路由与映射，需要健壮的协议转换与状态聚合。 +3. ⏳ **易逝性云工作区生命周期（Cattle, not Pet）**：工作区无连接 10 分钟自动关机、单次运行最长 18 小时、凌晨 4-6 点强制「环境不过夜」回收；每次重新启动分配的端口代理子域名（`{subdomain}-9001.cnb.run`）均随机变化。 +4. ⚠️ **社区逆向方案的脆弱与合规风险**：社区同类项目多采用抓取前端匿名 NPC 聊天接口、无头 Chromium 会话池或逆向 CSRF 的方案。不仅缺乏原生 Tool Calling 支持，更易因平台改版/风控而彻底失效。 + +--- + +**cnb2api** 为此而生：它是一个专为 CNB 工作区打造的**极简、零依赖、100% 官方合规的高可用反向代理网关**。直接运行在工作区内网，不仅将官方内网 AI 端点无缝映射为标准稳定的公网接口，更独创 **v5.2 零长效凭据 + 双保险自愈架构**，在易逝的临时容器之上提供 7×24 小时高可用服务。 + +### 核心特性 + +- 🔓 **100% 官方合规正道**：只调用官方文档化的工作区 AI 端点，完全依靠平台原生流水线临时凭据。不逆向、不爬虫、不碰前端 NPC 会话池，原生支持 Function / Tool Calls。 +- ⚡ **OpenAI + Anthropic 双协议栈**： + - **OpenAI 兼容**：标准 `/v1/chat/completions` 与 `/v1/models`，支持流式 SSE 透传与忠实的非流式状态机聚合（完整回填 `usage`、真实 `credit` 扣费、`tool_calls` 与 `finish_reason`）。 + - **Anthropic 原生兼容**：原生 `/v1/messages` 与 `/v1/messages/count_tokens`，**Claude Code CLI 零中间件直连**（设置 `ANTHROPIC_BASE_URL` 与 `ANTHROPIC_AUTH_TOKEN` 即用），支持流式事件序列、thinking 思考链与双向工具调用映射。 + - 🛡️ **独家出站中性化规避（Upstream Neutralizer）**：自动等价重写 Claude Code 内部计费头与特征提示词短语，语义无损放行，彻底消除上游网关对 Claude Code 的 11128 误报拦截。 +- ♻️ **v5.2 零凭据泄露 + 双保险自愈高可用**： + - **凭据零保管**：工作区无任何长期静态 Token。定时自愈流水线每次使用平台现签现销的临时凭据，过期风险彻底归零。 + - **动态域名自动跟随**：工作区开机通过 `start.sh` 自动向中继注册新子域名（`/ops/register`），中继自动热重载 upstream，客户端固定域名与 Key 永久不变。实测完整自愈恢复仅需 **~2 分 13 秒**。 + - **v5.2 静默自愈双保险**：针对云平台连续多日无 commit 自动休眠 crontab 的平台机制，外部看门狗（`cnb-watchdog.sh`）在检测到异常时静默触发带 30 分钟冷却锁的 OpenAPI 应急拉起，23 秒恢复且真故障才告警，告警噪音降为零。 +- 🪶 **真正的零外部依赖（Zero Dependencies）**：100% 基于 Node.js 22+ 内置模块实现（原生 `fetch`、`ReadableStream`、`crypto.timingSafeEqual`、`node:test`），零 `npm install`，毫秒级冷启动，内存占用极低。 +- 📊 **全链路用量监控与独家额度看板**： + - 终端一键查额度 `cnb2api-quota`：红黄绿 ANSI 进度条可视化展示 AI credits、开发核时、CI 核时及在途冻结额度，支持 `--json` 与 `--line`，不启动反代也能查。 + - 内存级 `GET /usage` 统计端点，按 boot 换代隔离并支持 UTC+8 每日对账，完美对接自建看板与探针监控。 + +--- + +### 技术方案横向对比 + +| 维度 | cnb2api（本项目） | 社区逆向 NPC 接口方案 | 直接外部调用 | +|:---|:---|:---|:---| +| **调用途径** | **官方工作区内网 AI 端点** | 网页前端匿名游客 NPC 聊天接口 | 官方 AI 端点（公网） | +| **合规与账号** | **100% 官方合规**，消耗自己组织正规配额 | 灰产逆向、违反 ToS、易被平台风控 | 无法调用（网络策略拦截） | +| **网络可达性** | 工作区反代 + 动态中继，**公网稳定访问** | 需维护无头浏览器/代理池抓 CSRF | ❌ **403 Blocked by network policy** | +| **鉴权机制** | 流水线即时签发 `CNB_TOKEN`（零保管） | 抓取网页 cookie / session | ❌ 个人令牌 403（仅允许流水线） | +| **协议支持** | **OpenAI + Anthropic 双协议栈** | 仅部分模拟 OpenAI 基础文本 | 无 | +| **Claude Code 直连** | **原生直连**（内置 11128 误报规避） | ❌ 不支持（缺少 tool calling / 被拦截） | 无 | +| **Tool Calling / 函数调用** | **原生完整支持**（流式增量合并） | ❌ 不支持（前端接口无 tools 能力） | 无 | +| **外部运行依赖** | **0 依赖**（Node.js 22+ 内置，秒启） | 依赖 Chromium、Puppeteer 等重型依赖 | 无 | +| **高可用机制** | **v5.2 双保险自愈**（内网 cron + 外部看门狗） | 单点容易随前端改版报废 | 无 | +| **额度透明度** | **内置终端看板 CLI** + `/usage` 统计 | 黑盒无账单，不可视 | 只能进网页控制台深处查看 | ## 工作原理