From 222485ca932b15c5259f690dddd39f7a1ff060d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=B5=B7?= <7836246@qq.com> Date: Tue, 17 Mar 2026 09:37:34 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E7=A7=BB=E9=99=A4=20config.yaml=20?= =?UTF-8?q?=E8=B7=9F=E8=B8=AA=20+=20=E6=9B=B4=E6=96=B0=20README=20?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - config.yaml 加入 .gitignore（含敏感 token，不再上传） - 新增 config.yaml.example 作为配置模板 - README 新增：日志查看器功能介绍、配置表格、环境变量参考 - README 更新：项目结构增加 public/ 目录说明 - .gitignore 清理重复条目 + 排除截图文件 --- .gitignore | 37 +++--------- README.md | 95 ++++++++++++++++++++++++++---- config.yaml => config.yaml.example | 3 +- 3 files changed, 93 insertions(+), 42 deletions(-) rename config.yaml => config.yaml.example (98%) diff --git a/.gitignore b/.gitignore index dc7349e..30335ad 100644 --- a/.gitignore +++ b/.gitignore @@ -26,35 +26,6 @@ Thumbs.db logs/ *.log -# Environment -# Binaries -*.exe -*.dll -*.so -*.dylib -cursor2api - -# Go -vendor/ -*.test - -# Node -node_modules/ - -# IDE -.idea/ -.vscode/ -*.swp -*.swo - -# OS -.DS_Store -Thumbs.db - -# Logs -logs/ -*.log - # Environment .env .env.local @@ -62,4 +33,10 @@ logs/ # Build dist/ build/ -*.traineddata \ No newline at end of file +*.traineddata + +# Config (contains sensitive tokens, use config.yaml.example as template) +config.yaml + +# Screenshots (dev artifacts) +*.png \ No newline at end of file diff --git a/README.md b/README.md index a2c016a..3aa9f55 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ - **Anthropic Messages API 完整兼容** - `/v1/messages` 流式/非流式，直接对接 Claude Code - **OpenAI Chat Completions API 兼容** - `/v1/chat/completions`，对接 ChatBox / LobeChat 等客户端 - **Cursor IDE Agent 模式适配** - `/v1/responses` 端点 + 扁平工具格式 + 增量流式工具调用 +- **🆕 全链路日志查看器** - Web UI 实时查看请求/响应/工具调用全流程，支持日/夜主题切换 - **🆕 API Token 鉴权** - 公网部署安全，支持 Bearer token / x-api-key 双模式，多 token 管理 - **🆕 Thinking 支持** - 客户端驱动，Anthropic `thinking` block + OpenAI `reasoning_content`，模型名含 `thinking` 或传 `reasoning_effort` 即启用 - **🆕 response_format 支持** - `json_object` / `json_schema` 格式输出，自动剥离 markdown 包装 @@ -57,20 +58,40 @@ npm install ### 2. 配置 -编辑 `config.yaml`： -- `auth_tokens` - API 鉴权 token 列表（公网部署推荐配置，不配则全部放行） -- `cursor_model` - 使用的模型（默认 `anthropic/claude-sonnet-4.6`） -- `compression.enabled` - 压缩开关（默认开启） -- `compression.level` - 压缩级别 1-3（1=轻度, 2=中等, 3=激进） -- `proxy` - 全局代理（可选，国内通常不需要） -- `vision.enabled` - 开启视觉拦截 -- `vision.mode` - 视觉模式：`ocr`（免 Key）或 `api`（外接视觉模型） -- `vision.proxy` - Vision 独立代理（不影响主请求速度） +复制示例配置文件并根据需要修改： + +```bash +cp config.yaml.example config.yaml +``` + +主要配置项： + +| 配置项 | 说明 | 默认值 | +|--------|------|--------| +| `port` | 服务端口 | `3010` | +| `auth_tokens` | API 鉴权 token 列表（公网部署推荐配置） | 不配置则全部放行 | +| `cursor_model` | 使用的模型 | `anthropic/claude-sonnet-4.6` | +| `thinking.enabled` | Thinking 开关（最高优先级） | `true` | +| `compression.enabled` | 压缩开关 | `true` | +| `compression.level` | 压缩级别 1-3 | `2` (中等) | +| `proxy` | 全局代理（可选） | 不配置 | +| `vision.enabled` | 开启视觉拦截 | `true` | +| `vision.mode` | 视觉模式：`ocr` / `api` | `ocr` | +| `vision.proxy` | Vision 独立代理 | 不配置 | +| `logging.file_enabled` | 日志文件持久化 | `false` | +| `logging.dir` | 日志存储目录 | `./logs` | +| `logging.max_days` | 日志保留天数 | `7` | + +> 💡 详细配置说明请参见 `config.yaml.example` 中的注释。 ### 3. 启动 ```bash +# 开发模式 npm run dev + +# 生产模式 +npm run build && npm start ``` ### 4. 配合 Claude Code 使用 @@ -80,6 +101,14 @@ export ANTHROPIC_BASE_URL=http://localhost:3010 claude ``` +如果配置了 `auth_tokens`，需要同时设置 API Key： + +```bash +export ANTHROPIC_BASE_URL=http://localhost:3010 +export ANTHROPIC_API_KEY=sk-your-secret-token-1 +claude +``` + ### 5. 配合 Cursor IDE 使用 在 Cursor IDE 的设置中配置： @@ -90,6 +119,29 @@ OPENAI_BASE_URL=http://localhost:3010/v1 > ⚠️ **注意**：Cursor IDE 请优先选用 Claude 模型名（通过 `/v1/models` 查看），避免使用 GPT 模型名以获得最佳兼容。 +## 🖥️ 日志查看器 + +启动服务后访问 `http://localhost:3010/logs` 即可打开全链路日志查看器。 + +### 功能特性 + +- **实时日志流** - SSE 推送，实时查看请求处理的每个阶段 +- **请求列表** - 左侧面板展示所有请求，以用户提问作为标题，方便快速识别 +- **全局搜索** - 关键字搜索 + 时间过滤（今天/两天/一周/一月） +- **状态过滤** - 按成功/失败/处理中/拦截状态筛选 +- **详情面板** - 点击请求查看完整的请求参数、提示词、响应内容 +- **阶段耗时** - 可视化时间线展示各阶段耗时（receive → convert → send → response → complete） +- **🌙 日/夜主题** - 一键切换明暗主题，自动记忆偏好 +- **日志持久化** - 配置 `logging.file_enabled: true` 后日志写入 JSONL 文件，重启自动加载 + +### 鉴权 + +如果配置了 `auth_tokens`，日志页面需要登录认证。也可以通过 URL 参数直接访问： + +``` +http://localhost:3010/logs?token=sk-your-secret-token-1 +``` + ## 项目结构 ``` @@ -107,6 +159,11 @@ cursor2api/ │ ├── logger.ts # 日志收集 + SSE 推送 │ ├── proxy-agent.ts # 代理支持（全局 + Vision 独立代理） │ └── tool-fixer.ts # 工具参数自动修复（字段映射 + 智能引号 + 模糊匹配） +├── public/ +│ ├── logs.html # 日志查看器主页面 +│ ├── logs.css # 日志查看器样式（含暗色主题） +│ ├── logs.js # 日志查看器前端逻辑 +│ └── login.html # 登录页面 ├── test/ │ ├── unit-tolerant-parse.mjs # tolerantParse / parseToolCalls 单元测试 │ ├── unit-tool-fixer.mjs # tool-fixer 单元测试 @@ -116,7 +173,7 @@ cursor2api/ │ ├── e2e-test.ts # 端到端 API 测试 │ ├── e2e-chat.mjs # 端到端对话测试 │ └── e2e-agentic.mjs # Claude Code Agentic 压测 -├── config.yaml # 配置文件 +├── config.yaml.example # 配置文件模板（复制为 config.yaml 使用） ├── package.json └── tsconfig.json ``` @@ -127,7 +184,7 @@ cursor2api/ > **核心设计理念：不对抗模型的严格文档助手身份，而是顺应它在 Cursor 内部被强制赋予的角色。** -Cursor 背后的 Claude 模型被后端强行锁定为 "Documentation Assistant" 身份，且工具被强行过滤为仅有 `read_file` 和 `read_dir`。一旦用户试图让其执行其他操作或直接调用其他工具，系统内置过滤器会立刻触发拒绝。传统试图告诉它“你在 IDE 里可以自动化操作”的方法随着官方后端的升级已不再稳定。 +Cursor 背后的 Claude 模型被后端强行锁定为 "Documentation Assistant" 身份，且工具被强行过滤为仅有 `read_file` 和 `read_dir`。一旦用户试图让其执行其他操作或直接调用其他工具，系统内置过滤器会立刻触发拒绝。传统试图告诉它"你在 IDE 里可以自动化操作"的方法随着官方后端的升级已不再稳定。 **本项目最新采用的策略是——告诉模型它正在编写 API 系统的开发文档，需要输出工具示例供我们复制：** @@ -170,6 +227,22 @@ AI 按此格式输出 → 我们解析并转换为标准的 Anthropic `tool_use` | **L3: 输出拦截** | `handler.ts` | 50+ 正则模式匹配拒绝文本（中英文），在流式/非流式响应中实时拦截并替换 | | **L4: 响应清洗** | `handler.ts` | `sanitizeResponse()` 对所有输出做后处理，将 Cursor 身份引用替换为 Claude | +## 环境变量 + +所有配置均可通过环境变量覆盖（优先级高于 `config.yaml`）： + +| 环境变量 | 说明 | +|----------|------| +| `PORT` | 服务端口 | +| `AUTH_TOKEN` | API 鉴权 token（逗号分隔多个） | +| `PROXY` | 全局代理地址 | +| `CURSOR_MODEL` | Cursor 使用的模型 | +| `THINKING_ENABLED` | Thinking 开关 (`true`/`false`) | +| `COMPRESSION_ENABLED` | 压缩开关 (`true`/`false`) | +| `COMPRESSION_LEVEL` | 压缩级别 (`1`/`2`/`3`) | +| `LOG_FILE_ENABLED` | 日志文件持久化 (`true`/`false`) | +| `LOG_DIR` | 日志文件目录 | + ## 免责声明 / Disclaimer **本项目仅供学习、研究和接口调试目的使用。** diff --git a/config.yaml b/config.yaml.example similarity index 98% rename from config.yaml rename to config.yaml.example index bc1d3ee..6a4fcd2 100644 --- a/config.yaml +++ b/config.yaml.example @@ -1,4 +1,5 @@ # Cursor2API v2 配置文件 +# 复制此文件为 config.yaml 并根据需要修改 # 服务端口 port: 3010 @@ -87,7 +88,7 @@ vision: # 环境变量: LOG_FILE_ENABLED=true|false, LOG_DIR=./logs logging: # 是否启用日志文件持久化（默认关闭） - file_enabled: true + file_enabled: false # 日志文件存储目录 dir: "./logs" # 日志保留天数（超过天数的日志文件会自动清理）