Update README.md

README.md

@@ -5,6 +5,403 @@ colorFrom: green
 colorTo: blue
 sdk: docker
 pinned: false
+app_port: 8002
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Cursor2API
+
+[English](README_EN.md) | 简体中文
+
+一个将 Cursor Web 转换为 OpenAI `chat/completions` 兼容 API 的 Go 服务。
+
+[![Go Version](https://img.shields.io/badge/Go-1.24+-blue.svg)](https://golang.org)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-orange.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+## ✨ 特性
+
+- 🔄 **API 兼容**: 兼容 OpenAI `chat/completions` 接口
+- ⚡ **高性能**: 低延迟响应
+- 🔐 **安全认证**: 支持 API Key 认证
+- 🌐 **模型派生**: 自动暴露 `*-thinking` 模型
+- 🧰 **工具调用**: 支持 `tools` / `tool_choice` / `tool_calls`
+- 🛡️ **错误处理**: 完善的错误处理机制
+- 📊 **健康检查**: 内置健康检查接口
+
+## 🖼️ 效果图
+
+![首页预览](docs/images/home.png)
+![调用效果预览 1](docs/images/play1.png)
+![调用效果预览 2](docs/images/play2.png)
+
+## 🤖 支持的模型
+
+- **Anthropic Claude**: `claude-sonnet-4.6`
+- **自动派生 thinking 模型**: `claude-sonnet-4.6-thinking`
+
+## 🚀 快速开始
+
+### 环境要求
+
+- Go 1.24+
+- Node.js 18+ (用于 JavaScript 执行)
+
+### 本地运行方式
+
+#### 方法一：直接运行（推荐用于开发）
+
+**Linux/macOS**:
+```bash
+git clone https://github.com/libaxuan/cursor2api-go.git
+cd cursor2api-go
+chmod +x start.sh
+./start.sh
+```
+
+**Windows**:
+```batch
+# 双击运行或在 cmd 中执行
+start-go.bat
+
+# 或在 Git Bash / Windows Terminal 中
+./start-go-utf8.bat
+```
+
+#### 方法二：手动编译运行
+
+```bash
+# 克隆项目
+git clone https://github.com/libaxuan/cursor2api-go.git
+cd cursor2api-go
+
+# 下载依赖
+go mod tidy
+
+# 编译
+go build -o cursor2api-go
+
+# 运行
+./cursor2api-go
+```
+
+#### 方法三：使用 go run
+
+```bash
+git clone https://github.com/libaxuan/cursor2api-go.git
+cd cursor2api-go
+go run main.go
+```
+
+服务将在 `http://localhost:8002` 启动
+
+## 🚀 服务器部署方式
+
+### Docker 部署
+
+1. **构建镜像**:
+```bash
+# 构建镜像
+docker build -t cursor2api-go .
+```
+
+2. **运行容器**:
+```bash
+# 运行容器（推荐）
+docker run -d \
+  --name cursor2api-go \
+  --restart unless-stopped \
+  -p 8002:8002 \
+  -e API_KEY=your-secret-key \
+  -e DEBUG=false \
+  cursor2api-go
+
+# 或者使用默认配置运行
+docker run -d --name cursor2api-go --restart unless-stopped -p 8002:8002 cursor2api-go
+```
+
+### Docker Compose 部署（推荐用于生产环境）
+
+1. **使用 docker-compose.yml**:
+```bash
+# 启动服务
+docker-compose up -d
+
+# 停止服务
+docker-compose down
+
+# 查看日志
+docker-compose logs -f
+```
+
+2. **自定义配置**:
+修改 `docker-compose.yml` 文件中的环境变量以满足您的需求：
+- 修改 `API_KEY` 为安全的密钥
+- 根据需要调整 `MODELS`、`TIMEOUT` 等配置
+- 更改暴露的端口
+
+### 系统服务部署（Linux）
+
+1. **编译并移动二进制文件**:
+```bash
+go build -o cursor2api-go
+sudo mv cursor2api-go /usr/local/bin/
+sudo chmod +x /usr/local/bin/cursor2api-go
+```
+
+2. **创建系统服务文件** `/etc/systemd/system/cursor2api-go.service`:
+```ini
+[Unit]
+Description=Cursor2API Service
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+WorkingDirectory=/home/your-user/cursor2api-go
+ExecStart=/usr/local/bin/cursor2api-go
+Restart=always
+Environment=API_KEY=your-secret-key
+Environment=PORT=8002
+
+[Install]
+WantedBy=multi-user.target
+```
+
+3. **启动服务**:
+```bash
+# 重载 systemd 配置
+sudo systemctl daemon-reload
+
+# 启用开机自启
+sudo systemctl enable cursor2api-go
+
+# 启动服务
+sudo systemctl start cursor2api-go
+
+# 查看状态
+sudo systemctl status cursor2api-go
+```
+
+## 📡 API 使用
+
+### 获取模型列表
+
+```bash
+curl -H "Authorization: Bearer 0000" http://localhost:8002/v1/models
+```
+
+### 非流式聊天
+
+```bash
+curl -X POST http://localhost:8002/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer 0000" \
+  -d '{
+    "model": "claude-sonnet-4.6",
+    "messages": [{"role": "user", "content": "Hello!"}],
+    "stream": false
+  }'
+```
+
+### 流式聊天
+
+```bash
+curl -X POST http://localhost:8002/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer 0000" \
+  -d '{
+    "model": "claude-sonnet-4.6",
+    "messages": [{"role": "user", "content": "Hello!"}],
+    "stream": true
+  }'
+```
+
+### 带工具的请求
+
+```bash
+curl -X POST http://localhost:8002/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer 0000" \
+  -d '{
+    "model": "claude-sonnet-4.6",
+    "messages": [{"role": "user", "content": "帮我查询北京天气"}],
+    "tools": [
+      {
+        "type": "function",
+        "function": {
+          "name": "get_weather",
+          "description": "获取实时天气",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "city": {"type": "string"}
+            },
+            "required": ["city"]
+          }
+        }
+      }
+    ]
+  }'
+```
+
+### `-thinking` 模型
+
+```bash
+curl -X POST http://localhost:8002/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer 0000" \
+  -d '{
+    "model": "claude-sonnet-4.6-thinking",
+    "messages": [{"role": "user", "content": "先思考再决定要不要用工具"}],
+    "tools": [
+      {
+        "type": "function",
+        "function": {
+          "name": "lookup",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "q": {"type": "string"}
+            },
+            "required": ["q"]
+          }
+        }
+      }
+    ],
+    "stream": true
+  }'
+```
+
+### 在第三方应用中使用
+
+在任何支持自定义 OpenAI API 的应用中（如 ChatGPT Next Web、Lobe Chat 等）：
+
+1. **API 地址**: `http://localhost:8002`
+2. **API 密钥**: `0000`（或自定义）
+3. **模型**: 选择支持的模型之一；基础模型会自动有对应的 `-thinking` 版本
+
+## ⚙️ 配置说明
+
+### 环境变量
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `PORT` | `8002` | 服务器端口 |
+| `DEBUG` | `false` | 调试模式（启用后显示详细日志和路由信息） |
+| `API_KEY` | `0000` | API 认证密钥 |
+| `MODELS` | `claude-sonnet-4.6` | 基础模型列表（逗号分隔），服务会自动追加对应的 `-thinking` 公开模型 |
+| `TIMEOUT` | `60` | 请求超时时间（秒） |
+| `KILO_TOOL_STRICT` | `false` | Kilo Code 兼容开关：当请求提供 `tools` 且 `tool_choice=auto` 时，将其提升为“必须至少调用一次工具” |
+
+### 调试模式
+
+默认情况下，服务以简洁模式运行。如需启用详细日志：
+
+**方式 1**: 修改 `.env` 文件
+```bash
+DEBUG=true
+```
+
+**方式 2**: 使用环境变量
+```bash
+DEBUG=true ./cursor2api-go
+```
+
+调试模式会显示：
+- 详细的 GIN 路由信息
+- 每个请求的详细日志
+- x-is-human token 信息
+- 浏览器指纹配置
+
+### 故障排除
+
+遇到问题？查看 **[故障排除指南](TROUBLESHOOTING.md)** 了解常见问题的解决方案，包括：
+- 403 Access Denied 错误
+- Token 获取失败
+- 连接超时
+- Cloudflare 拦截
+
+## 🧩 与 Kilo Code / Agent 编排器的兼容性
+
+部分编排器会在“提供了 tools”时强制模型必须产出工具调用，否则报类似 `MODEL_NO_TOOLS_USED` 的错误。为改善这一类兼容问题：
+
+- **建议**：在 `.env` 中启用 `KILO_TOOL_STRICT=true`
+- **非流式补救**：当请求提供 `tools` 且被判定为“必须用工具”（`tool_choice=required/指定函数`，或启用 `KILO_TOOL_STRICT`）时，如果本轮没有产出 `tool_calls`，服务会自动 **重试 1 次**（仅非流式；流式不重试）
+
+
+### Windows 启动脚本说明
+
+项目提供两个 Windows 启动脚本：
+
+- **`start-go.bat`** (推荐): GBK 编码，完美兼容 Windows cmd.exe
+- **`start-go-utf8.bat`**: UTF-8 编码，适用于 Git Bash、PowerShell、Windows Terminal
+
+两个脚本功能完全相同，仅显示样式不同。如遇乱码请使用 `start-go.bat`。
+
+## 🧪 开发
+
+### 运行测试
+
+```bash
+# 运行现有测试
+go test ./...
+```
+
+### 构建项目
+
+```bash
+# 构建可执行文件
+go build -o cursor2api-go
+
+# 交叉编译 (例如 Linux)
+GOOS=linux GOARCH=amd64 go build -o cursor2api-go-linux
+```
+
+## 📁 项目结构
+
+```
+cursor2api-go/
+├── main.go              # 主程序入口 (Go 版本)
+├── config/              # 配置管理 (Go 版本)
+├── handlers/            # HTTP 处理器 (Go 版本)
+├── services/            # 业务服务层 (Go 版本)
+├── models/              # 数据模型 (Go 版本)
+├── utils/               # 工具函数 (Go 版本)
+├── middleware/          # 中间件 (Go 版本)
+├── jscode/              # JavaScript 代码 (Go 版本)
+├── static/              # 静态文件 (Go 版本)
+├── start.sh             # Linux/macOS 启动脚本
+├── start-go.bat         # Windows 启动脚本 (GBK)
+├── start-go-utf8.bat    # Windows 启动脚本 (UTF-8)
+
+└── README.md            # 项目说明
+```
+
+## 🤝 贡献指南
+
+欢迎贡献代码！请遵循以下步骤：
+
+1. Fork 本仓库
+2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+### 代码规范
+
+- 遵循 [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
+- 使用 `gofmt` 格式化代码
+- 使用 `go vet` 检查代码
+- 提交信息遵循 [Conventional Commits](https://conventionalcommits.org/) 规范
+
+## 📄 许可证
+
+本项目采用 [PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) 许可证。
+禁止商业用途。查看 [LICENSE](LICENSE) 文件了解详情。
+
+## ⚠️ 免责声明
+
+使用本项目时请遵守相关服务的使用条款。
+
+---
+
+⭐ 如果这个项目对您有帮助，请给我们一个 Star！