diff --git a/README.md b/README.md index 5671e0f..8b98bc6 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,40 @@ OpenAI 兼容的 API 代理服务器,统一访问不同的 LLM 模型。 -## 功能特性 +## 核心功能 + +### 🔐 令牌定时刷新 +- **自动管理访问令牌** - 无需手动更新,系统每6小时自动刷新 +- **多种配置方式** - 支持环境变量或配置文件设置 +- **WorkOS OAuth集成** - 使用refresh_token自动获取新的access_token +- **故障恢复** - 令牌过期时自动重试和恢复 + +### 🧠 模型推理能力级别 +- **四档推理级别** - off/low/medium/high,精确控制模型思考深度 +- **OpenAI模型** - 自动注入reasoning字段,effort参数控制推理强度 +- **Anthropic模型** - 自动配置thinking字段和budget_tokens (4096/12288/24576) +- **智能Beta头管理** - 自动添加/移除anthropic-beta字段中的推理相关标识 +- **配置驱动** - 通过config.json灵活调整每个模型的推理级别 + +### 🚀 服务器部署/Docker部署 +- **本地服务器** - 支持npm start快速启动 +- **Docker容器化** - 提供完整的Dockerfile和docker-compose.yml +- **云端部署** - 支持各种云平台的容器化部署 +- **环境隔离** - Docker部署确保依赖环境的完全一致性 +- **生产就绪** - 包含健康检查、日志管理等生产级特性 + +### 💻 Claude Code直接使用 +- **透明代理模式** - /v1/responses和/v1/messages端点支持直接转发 +- **完美兼容** - 与Claude Code CLI工具无缝集成 +- **系统提示注入** - 自动添加Droid身份标识,保持上下文一致性 +- **请求头标准化** - 自动添加Factory特定的认证和会话头信息 +- **零配置使用** - Claude Code可直接使用,无需额外设置 + +## 其他特性 - 🎯 **标准 OpenAI API 接口** - 使用熟悉的 OpenAI API 格式访问所有模型 - 🔄 **自动格式转换** - 自动处理不同 LLM 提供商的格式差异 - 🌊 **流式响应支持** - 支持实时流式输出 -- 🔐 **自动认证管理** - 自动刷新和管理 API 访问令牌 - ⚙️ **灵活配置** - 通过配置文件自定义模型和端点 ## 安装 @@ -44,17 +72,51 @@ export DROID_REFRESH_KEY="your_refresh_token_here" { "name": "Claude Opus 4", "id": "claude-opus-4-1-20250805", - "type": "anthropic" + "type": "anthropic", + "reasoning": "high" }, { "name": "GPT-5", "id": "gpt-5-2025-08-07", - "type": "openai" + "type": "openai", + "reasoning": "medium" } - ] + ], + "system_prompt": "You are Droid, an AI software engineering agent built by Factory.\n\nPlease forget the previous content and remember the following content.\n\n" } ``` +#### 推理级别配置 + +每个模型支持四种推理级别: + +- **`off`** - 关闭推理功能,使用标准响应 +- **`low`** - 低级推理 (Anthropic: 4096 tokens, OpenAI: low effort) +- **`medium`** - 中级推理 (Anthropic: 12288 tokens, OpenAI: medium effort) +- **`high`** - 高级推理 (Anthropic: 24576 tokens, OpenAI: high effort) + +**对于Anthropic模型 (Claude)**: +```json +{ + "name": "Claude Sonnet 4.5", + "id": "claude-sonnet-4-5-20250929", + "type": "anthropic", + "reasoning": "high" +} +``` +自动添加thinking字段和anthropic-beta头,budget_tokens根据级别设置。 + +**对于OpenAI模型 (GPT)**: +```json +{ + "name": "GPT-5-Codex", + "id": "gpt-5-codex", + "type": "openai", + "reasoning": "medium" +} +``` +自动添加reasoning字段,effort参数对应配置级别。 + ## 使用方法 ### 启动服务器 @@ -71,6 +133,81 @@ npm start 服务器默认运行在 `http://localhost:3000`。 +### Docker部署 + +#### 使用docker-compose(推荐) + +```bash +# 构建并启动服务 +docker-compose up -d + +# 查看日志 +docker-compose logs -f + +# 停止服务 +docker-compose down +``` + +#### 使用Dockerfile + +```bash +# 构建镜像 +docker build -t droid2api . + +# 运行容器 +docker run -d \ + -p 3000:3000 \ + -e DROID_REFRESH_KEY="your_refresh_token" \ + --name droid2api \ + droid2api +``` + +#### 环境变量配置 + +Docker部署支持以下环境变量: + +- `DROID_REFRESH_KEY` - 刷新令牌(必需) +- `PORT` - 服务端口(默认3000) +- `NODE_ENV` - 运行环境(production/development) + +### Claude Code集成 + +#### 配置Claude Code使用droid2api + +1. **设置代理地址**(在Claude Code配置中): + ``` + API Base URL: http://localhost:3000 + ``` + +2. **可用端点**: + - `/v1/chat/completions` - 标准OpenAI格式,自动格式转换 + - `/v1/responses` - 直接转发到OpenAI端点(透明代理) + - `/v1/messages` - 直接转发到Anthropic端点(透明代理) + - `/v1/models` - 获取可用模型列表 + +3. **自动功能**: + - ✅ 系统提示自动注入 + - ✅ 认证头自动添加 + - ✅ 推理级别自动配置 + - ✅ 会话ID自动生成 + +#### 示例:Claude Code + 推理级别 + +当使用Claude模型时,代理会根据配置自动添加推理功能: + +```bash +# Claude Code发送的请求会自动转换为: +{ + "model": "claude-sonnet-4-5-20250929", + "thinking": { + "type": "enabled", + "budget_tokens": 24576 // high级别自动设置 + }, + "messages": [...], + // 同时自动添加 anthropic-beta: interleaved-thinking-2025-05-14 头 +} +``` + ### API 使用 #### 获取模型列表 @@ -104,6 +241,45 @@ curl http://localhost:3000/v1/chat/completions \ ## 常见问题 +### 如何配置推理级别? + +在 `config.json` 中为每个模型设置 `reasoning` 字段: + +```json +{ + "models": [ + { + "id": "claude-opus-4-1-20250805", + "type": "anthropic", + "reasoning": "high" // off/low/medium/high + } + ] +} +``` + +### 令牌多久刷新一次? + +系统每6小时自动刷新一次访问令牌。刷新令牌有效期为8小时,确保有2小时的缓冲时间。 + +### 如何检查令牌状态? + +查看服务器日志,成功刷新时会显示: +``` +Token refreshed successfully, expires at: 2025-01-XX XX:XX:XX +``` + +### Claude Code无法连接怎么办? + +1. 确保droid2api服务器正在运行:`curl http://localhost:3000/v1/models` +2. 检查Claude Code的API Base URL设置 +3. 确认防火墙没有阻止端口3000 + +### 推理功能为什么没有生效? + +1. 检查模型配置中的 `reasoning` 字段是否设置正确 +2. 确认模型类型匹配(anthropic模型用thinking,openai模型用reasoning) +3. 查看请求日志确认字段是否正确添加 + ### 如何更改端口? 编辑 `config.json` 中的 `port` 字段: