diff --git a/API.en.md b/API.en.md index 967c258..eccefc6 100644 --- a/API.en.md +++ b/API.en.md @@ -31,6 +31,13 @@ This document describes the actual behavior of the current Go codebase. | Health probes | `GET /healthz`, `GET /readyz` | | CORS | Enabled (`Access-Control-Allow-Origin: *`, allows `Content-Type`, `Authorization`, `X-API-Key`, `X-Ds2-Target-Account`, `X-Vercel-Protection-Bypass`) | +### 3.0 Adapter-Layer Notes + +- OpenAI / Claude / Gemini protocols are now mounted on one shared `chi` router tree assembled in `internal/server/router.go`. +- Adapter responsibilities are streamlined to: **request normalization → DeepSeek invocation → protocol-shaped rendering**, reducing legacy split-logic paths. +- Tool-calling semantics are aligned between Go and Node runtime: structured parsing first (JSON/XML/invoke/markup), plus stream-time anti-leak filtering. +- `Admin API` separates static config from runtime policy: `/admin/config*` for configuration state, `/admin/settings*` for runtime behavior. + --- ## Configuration Best Practice @@ -931,15 +938,15 @@ Checks the current build version and the latest GitHub Release: ```json { "success": true, - "current_version": "2.3.5", - "current_tag": "v2.3.5", + "current_version": "3.0.0", + "current_tag": "v3.0.0", "source": "file:VERSION", "checked_at": "2026-03-29T00:00:00Z", - "latest_tag": "v2.3.6", - "latest_version": "2.3.6", - "release_url": "https://github.com/CJackHwang/ds2api/releases/tag/v2.3.6", + "latest_tag": "v3.0.0", + "latest_version": "3.0.0", + "release_url": "https://github.com/CJackHwang/ds2api/releases/tag/v3.0.0", "published_at": "2026-03-28T12:00:00Z", - "has_update": true + "has_update": false } ``` diff --git a/API.md b/API.md index aac0e3b..a42a0fc 100644 --- a/API.md +++ b/API.md @@ -31,6 +31,13 @@ | 健康检查 | `GET /healthz`、`GET /readyz` | | CORS | 已启用（`Access-Control-Allow-Origin: *`，允许 `Content-Type`, `Authorization`, `X-API-Key`, `X-Ds2-Target-Account`, `X-Vercel-Protection-Bypass`） | +### 3.0 接口适配层说明 + +- OpenAI / Claude / Gemini 三套协议已统一挂在同一 `chi` 路由树上，由 `internal/server/router.go` 负责装配。 +- 适配器层职责收敛为：**请求归一化 → DeepSeek 调用 → 协议形态渲染**，减少历史版本中“同能力多处实现”的分叉。 +- Tool Calling 的解析策略在 Go 与 Node Runtime 间保持一致：优先结构化解析（JSON/XML/invoke/markup），并在流式场景执行防泄漏筛分。 +- `Admin API` 将配置与运行时策略分开：`/admin/config*` 管静态配置，`/admin/settings*` 管运行时行为。 + --- ## 配置最佳实践 @@ -937,15 +944,15 @@ data: {"type":"message_stop"} ```json { "success": true, - "current_version": "2.3.5", - "current_tag": "v2.3.5", + "current_version": "3.0.0", + "current_tag": "v3.0.0", "source": "file:VERSION", "checked_at": "2026-03-29T00:00:00Z", - "latest_tag": "v2.3.6", - "latest_version": "2.3.6", - "release_url": "https://github.com/CJackHwang/ds2api/releases/tag/v2.3.6", + "latest_tag": "v3.0.0", + "latest_version": "3.0.0", + "release_url": "https://github.com/CJackHwang/ds2api/releases/tag/v3.0.0", "published_at": "2026-03-28T12:00:00Z", - "has_update": true + "has_update": false } ``` diff --git a/README.MD b/README.MD index 1c20ee6..864336d 100644 --- a/README.MD +++ b/README.MD @@ -44,6 +44,8 @@ flowchart LR subgraph Support["支撑模块"] Pool["📦 账号池 / 并发队列"] PoW["⚙️ PoW WASM\n(wazero)"] + Stream["🌊 统一流式引擎\nstream + sse"] + Sieve["🧰 Tool Sieve\nGo + Node 对齐"] end Admin["🛠️ Admin API\n/admin/*"] @@ -58,6 +60,8 @@ flowchart LR Auth --> Admin OA & CA & GA -. "轮询选账号" .-> Pool OA & CA & GA -. "计算 PoW" .-> PoW + OA & CA & GA -. "流式解析" .-> Stream + OA & CA & GA -. "工具调用防泄漏" .-> Sieve DS -- "响应" --> Client ``` @@ -65,6 +69,15 @@ flowchart LR - **前端**：React 管理台（`webui/`），运行时托管静态构建产物 - **部署**：本地运行、Docker、Vercel Serverless、Linux systemd +### 3.0 底层架构调整（相较旧版本） + +- **统一路由内核**：所有协议入口统一汇聚到 `internal/server/router.go`，并在同一路由树中注册 OpenAI / Claude / Gemini / Admin / WebUI 路由，避免多入口行为漂移。 +- **适配器分层更清晰**：`internal/adapter/{openai,claude,gemini}` 只负责协议形态、错误格式和流式事件语义，DeepSeek 侧调用统一收敛到共享调用层。 +- **Tool Calling 双运行时对齐**：Go 侧（`internal/util`）与 Vercel Node 侧（`internal/js/helpers/stream-tool-sieve`）保持一致的解析/防泄漏语义，覆盖 JSON / XML / invoke / text-kv 多风格输入。 +- **配置与运行时设置解耦**：静态配置（`config`）与运行时策略（`settings`）通过 Admin API 分离管理，支持热更新和密码轮换失效旧 JWT。 +- **流式能力升级**：`/v1/responses` 与 `/v1/chat/completions` 共享更一致的工具调用增量输出策略，降低不同 SDK 下的行为差异。 +- **可观测与可运维增强**：`/healthz`、`/readyz`、`/admin/version`、`/admin/dev/captures` 形成排障闭环，便于发布后验证。 + ## 核心能力 | 能力 | 说明 | @@ -144,7 +157,7 @@ cp config.example.json config.json ### 方式一：本地运行 -**前置要求**：Go 1.24+，Node.js 20+（仅在需要构建 WebUI 时） +**前置要求**：Go 1.26+，Node.js 20+（仅在需要构建 WebUI 时） ```bash # 1. 克隆仓库 @@ -415,6 +428,7 @@ ds2api/ ├── cmd/ │ ├── ds2api/ # 本地 / 容器启动入口 │ └── ds2api-tests/ # 端到端测试集入口 +├── app/ # 统一 HTTP Handler 组装层（供本地与 Serverless 复用） ├── api/ │ ├── index.go # Vercel Serverless Go 入口 │ ├── chat-stream.js # Vercel Node.js 流式转发 @@ -438,7 +452,10 @@ ds2api/ │ ├── server/ # HTTP 路由与中间件（chi router） │ ├── sse/ # SSE 解析工具 │ ├── stream/ # 统一流式消费引擎 +│ ├── testsuite/ # 端到端测试框架与用例编排 +│ ├── translatorcliproxy/ # CLIProxy 桥接与流写入组件 │ ├── util/ # 通用工具函数 +│ ├── version/ # 版本解析 / 比较与 tag 规范化 │ └── webui/ # WebUI 静态文件托管与自动构建 ├── webui/ # React WebUI 源码（Vite + Tailwind） │ └── src/ diff --git a/README.en.md b/README.en.md index 34bc615..3b2eeca 100644 --- a/README.en.md +++ b/README.en.md @@ -44,6 +44,8 @@ flowchart LR subgraph Support["Support Modules"] Pool["📦 Account Pool / Queue"] PoW["⚙️ PoW WASM\n(wazero)"] + Stream["🌊 Unified Streaming\nstream + sse"] + Sieve["🧰 Tool Sieve\nGo + Node parity"] end Admin["🛠️ Admin API\n/admin/*"] @@ -58,6 +60,8 @@ flowchart LR Auth --> Admin OA & CA & GA -. "Rotate accounts" .-> Pool OA & CA & GA -. "Compute PoW" .-> PoW + OA & CA & GA -. "Parse streams" .-> Stream + OA & CA & GA -. "Tool anti-leak" .-> Sieve DS -- "Response" --> Client ``` @@ -65,6 +69,15 @@ flowchart LR - **Frontend**: React admin panel (`webui/`), served as static build at runtime - **Deployment**: local run, Docker, Vercel serverless, Linux systemd +### 3.0 Architecture Changes (vs older releases) + +- **Unified routing core**: all protocol entries are now centralized through `internal/server/router.go`, with OpenAI / Claude / Gemini / Admin / WebUI routes registered in one tree to avoid multi-entry drift. +- **Cleaner adapter boundaries**: `internal/adapter/{openai,claude,gemini}` focuses on protocol shapes, error contracts, and streaming semantics, while upstream DeepSeek invocation stays shared. +- **Tool-calling parity across runtimes**: Go (`internal/util`) and Vercel Node (`internal/js/helpers/stream-tool-sieve`) follow aligned parsing/anti-leak semantics across JSON / XML / invoke / text-kv inputs. +- **Config/runtime separation**: static config (`config`) and runtime policy (`settings`) are managed independently via Admin APIs, enabling hot updates and password rotation with JWT invalidation. +- **Streaming behavior upgrade**: `/v1/responses` and `/v1/chat/completions` now share a more consistent incremental tool-call emission strategy across SDK ecosystems. +- **Improved operability**: `/healthz`, `/readyz`, `/admin/version`, and `/admin/dev/captures` form a tighter post-deploy diagnostics loop. + ## Key Capabilities | Capability | Details | @@ -144,7 +157,7 @@ Recommended per deployment mode: ### Option 1: Local Run -**Prerequisites**: Go 1.24+, Node.js 20+ (only if building WebUI locally) +**Prerequisites**: Go 1.26+, Node.js 20+ (only if building WebUI locally) ```bash # 1. Clone @@ -409,6 +422,7 @@ ds2api/ ├── cmd/ │ ├── ds2api/ # Local / container entrypoint │ └── ds2api-tests/ # End-to-end testsuite entrypoint +├── app/ # Unified HTTP handler assembly (shared by local + serverless) ├── api/ │ ├── index.go # Vercel Serverless Go entry │ ├── chat-stream.js # Vercel Node.js stream relay @@ -432,7 +446,10 @@ ds2api/ │ ├── server/ # HTTP routing and middleware (chi router) │ ├── sse/ # SSE parsing utilities │ ├── stream/ # Unified stream consumption engine +│ ├── testsuite/ # End-to-end testsuite framework and case orchestration +│ ├── translatorcliproxy/ # CLIProxy bridge and stream writer components │ ├── util/ # Common utilities +│ ├── version/ # Version parsing/comparison and tag normalization │ └── webui/ # WebUI static file serving and auto-build ├── webui/ # React WebUI source (Vite + Tailwind) │ └── src/ diff --git a/VERSION b/VERSION index 4fd0fe3..4a36342 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.5.1 \ No newline at end of file +3.0.0 diff --git a/docs/CONTRIBUTING.en.md b/docs/CONTRIBUTING.en.md index 6f8257b..e748d2b 100644 --- a/docs/CONTRIBUTING.en.md +++ b/docs/CONTRIBUTING.en.md @@ -8,7 +8,7 @@ Thanks for your interest in contributing to DS2API! ### Prerequisites -- Go 1.24+ +- Go 1.26+ - Node.js 20+ (for WebUI development) - npm (bundled with Node.js) @@ -97,6 +97,7 @@ ds2api/ ├── cmd/ │ ├── ds2api/ # Local/container entrypoint │ └── ds2api-tests/ # End-to-end testsuite entrypoint +├── app/ # Shared handler assembly (local + serverless) ├── api/ │ ├── index.go # Vercel Serverless Go entry │ ├── chat-stream.js # Vercel Node.js stream relay @@ -110,7 +111,6 @@ ds2api/ │ ├── admin/ # Admin API handlers │ ├── auth/ # Auth and JWT │ ├── claudeconv/ # Claude message conversion -│ ├── compat/ # Compatibility helpers │ ├── config/ # Config loading and hot-reload │ ├── deepseek/ # DeepSeek client, PoW WASM │ ├── js/ # Node runtime stream/compat logic @@ -120,8 +120,10 @@ ds2api/ │ ├── server/ # HTTP routing (chi router) │ ├── sse/ # SSE parsing utilities │ ├── stream/ # Unified stream consumption engine -│ ├── testsuite/ # Testsuite core logic +│ ├── testsuite/ # Testsuite framework and scenario orchestration +│ ├── translatorcliproxy/ # CLIProxy bridge and stream writer │ ├── util/ # Common utilities +│ ├── version/ # Version parsing and comparison │ └── webui/ # WebUI static hosting ├── webui/ # React WebUI source │ └── src/ diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index f956fad..a32b8b6 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -8,7 +8,7 @@ ### 前置要求 -- Go 1.24+ +- Go 1.26+ - Node.js 20+（WebUI 开发时） - npm（随 Node.js 提供） @@ -97,6 +97,7 @@ ds2api/ ├── cmd/ │ ├── ds2api/ # 本地/容器启动入口 │ └── ds2api-tests/ # 端到端测试集入口 +├── app/ # 统一 Handler 装配（本地 + Serverless） ├── api/ │ ├── index.go # Vercel Serverless Go 入口 │ ├── chat-stream.js # Vercel Node.js 流式转发 @@ -110,7 +111,6 @@ ds2api/ │ ├── admin/ # Admin API handlers │ ├── auth/ # 鉴权与 JWT │ ├── claudeconv/ # Claude 消息格式转换 -│ ├── compat/ # 兼容性辅助 │ ├── config/ # 配置加载与热更新 │ ├── deepseek/ # DeepSeek 客户端、PoW WASM │ ├── js/ # Node 运行时流式/兼容逻辑 @@ -120,8 +120,10 @@ ds2api/ │ ├── server/ # HTTP 路由（chi router） │ ├── sse/ # SSE 解析工具 │ ├── stream/ # 统一流式消费引擎 -│ ├── testsuite/ # 测试集核心逻辑 +│ ├── testsuite/ # 测试集框架与场景编排 +│ ├── translatorcliproxy/ # CLIProxy 桥接与流式写入 │ ├── util/ # 通用工具 +│ ├── version/ # 版本解析与比较 │ └── webui/ # WebUI 静态托管 ├── webui/ # React WebUI 源码 │ └── src/ diff --git a/docs/DEPLOY.en.md b/docs/DEPLOY.en.md index 855af36..2ac7b7b 100644 --- a/docs/DEPLOY.en.md +++ b/docs/DEPLOY.en.md @@ -24,7 +24,7 @@ This guide covers all deployment methods for the current Go-based codebase. | Dependency | Minimum Version | Notes | | --- | --- | --- | -| Go | 1.24+ | Build backend | +| Go | 1.26+ | Build backend | | Node.js | 20+ | Only needed to build WebUI locally | | npm | Bundled with Node.js | Install WebUI dependencies | @@ -401,7 +401,7 @@ cp config.example.json config.json docker pull ghcr.io/cjackhwang/ds2api:latest # specific version (example) -docker pull ghcr.io/cjackhwang/ds2api:v2.1.2 +docker pull ghcr.io/cjackhwang/ds2api:v3.0.0 ``` --- diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 3082da7..4df1194 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -24,7 +24,7 @@ | 依赖 | 最低版本 | 说明 | | --- | --- | --- | -| Go | 1.24+ | 编译后端 | +| Go | 1.26+ | 编译后端 | | Node.js | 20+ | 仅在需要本地构建 WebUI 时 | | npm | 随 Node.js 提供 | 安装 WebUI 依赖 | @@ -401,7 +401,7 @@ cp config.example.json config.json docker pull ghcr.io/cjackhwang/ds2api:latest # 指定版本（示例） -docker pull ghcr.io/cjackhwang/ds2api:v2.1.2 +docker pull ghcr.io/cjackhwang/ds2api:v3.0.0 ``` ---