Skip to content

docs: overhaul project introduction and feature comparison across READMEs #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dengyie merged 1 commit into from
Sep 13, 2026
Merged

docs: overhaul project introduction and feature comparison across READMEs #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 46 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -13,25 +15,49 @@ English · [简体中文](README.zh-CN.md)

</div>

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

Expand Down
61 changes: 46 additions & 15 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -13,20 +15,49 @@

</div>

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` 统计 | 黑盒无账单，不可视 | 只能进网页控制台深处查看 |

## 工作原理

Expand Down
Loading