docs/DYNAMIC_HEADERS.md

动态 Header 改进说明

问题背景

之前的实现中，HTTP headers 是硬编码的：

• sec-ch-ua-platform 固定为 "macOS" 或 "Windows"
• sec-ch-ua 固定为特定的 Chrome 版本
• Referer 和 accept-language 固定不变

这种硬编码的方式容易被 Cursor API 识别为异常请求，导致 403 错误。

改进方案

1. 动态浏览器指纹生成器 (utils/headers.go)

创建了 HeaderGenerator 类，实现以下功能：

智能平台选择

• 根据当前操作系统自动选择合适的浏览器配置
• macOS: 支持 Intel (x86) 和 Apple Silicon (arm) 架构
• Windows: 支持多个版本 (10.0, 11.0, 15.0)
• Linux: 标准 x86_64 配置

随机化配置

• Chrome 版本: 从 120-130 随机选择
• 语言设置: 支持 en-US, zh-CN, en-GB, ja-JP
• Referer: 随机选择不同的 Cursor 页面
• User-Agent: 根据平台和版本动态生成

真实的浏览器指纹

生成的 headers 包含完整的浏览器指纹信息：

{
  "sec-ch-ua-platform": "macOS",
  "sec-ch-ua-platform-version": "14.0.0",
  "sec-ch-ua-arch": "arm",
  "sec-ch-ua-bitness": "64",
  "sec-ch-ua": "\"Google Chrome\";v=\"126\", \"Chromium\";v=\"126\", \"Not(A:Brand\";v=\"24\"",
  "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36..."
}

2. 自动刷新机制

当遇到 403 错误时：

1. 自动刷新浏览器指纹配置
2. 清除 x-is-human token 缓存
3. 使用新的配置重试请求

3. 代码改进

服务初始化

type CursorService struct {
    // ... 其他字段
    headerGenerator *utils.HeaderGenerator
}

func NewCursorService(cfg *config.Config) *CursorService {
    return &CursorService{
        // ... 其他初始化
        headerGenerator: utils.NewHeaderGenerator(),
    }
}

Headers 生成

// 之前：硬编码
func (s *CursorService) chatHeaders(xIsHuman string) map[string]string {
    return map[string]string{
        "sec-ch-ua-platform": `"macOS"`,  // 固定值
        "sec-ch-ua": `"Google Chrome";v="143"...`,  // 固定版本
        // ...
    }
}

// 现在：动态生成
func (s *CursorService) chatHeaders(xIsHuman string) map[string]string {
    return s.headerGenerator.GetChatHeaders(xIsHuman)
}

403 错误处理

if resp.StatusCode == http.StatusForbidden && attempt < maxRetries {
    logrus.Warn("Received 403, refreshing browser fingerprint...")
    
    // 刷新浏览器指纹
    s.headerGenerator.Refresh()
    
    // 清除 token 缓存
    s.scriptMutex.Lock()
    s.scriptCache = ""
    s.scriptCacheTime = time.Time{}
    s.scriptMutex.Unlock()
    
    // 重试
    continue
}

优势

1. 更难被检测

• 每次请求的指纹信息都可能不同
• 模拟真实用户的多样性
• 避免固定模式被识别

2. 自动适应

• 根据运行环境自动选择合适的配置
• macOS 上运行自动使用 macOS 配置
• Windows 上运行自动使用 Windows 配置

3. 更好的容错性

• 遇到 403 错误自动切换配置
• 增加请求成功率
• 减少人工干预

4. 易于维护

• 集中管理浏览器配置
• 易于添加新的平台或版本
• 代码更简洁清晰

测试结果

运行测试程序可以看到：

浏览器配置:
  平台: macOS
  平台版本: 14.0.0
  架构: arm
  位数: 64
  Chrome 版本: 126
  User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...

生成 5 个随机配置:
1. macOS | Chrome 130 | arm
2. macOS | Chrome 125 | arm
3. macOS | Chrome 130 | x86
4. macOS | Chrome 128 | arm
5. macOS | Chrome 122 | arm

每次生成的配置都不同，增加了多样性。

使用方法

无需任何配置，直接使用即可：

# 重新编译
go build -o cursor2api-go

# 运行服务
./cursor2api-go

服务会自动：

• 根据操作系统选择合适的浏览器配置
• 为每个请求生成动态 headers
• 遇到 403 错误时自动刷新配置并重试

日志示例

启用调试模式后可以看到：

DEBU Sending request to Cursor API attempt=1 model=claude-sonnet-4.6
WARN Received 403 Access Denied, refreshing browser fingerprint...
DEBU Refreshed browser fingerprint platform=macOS chrome_version=124
DEBU Sending request to Cursor API attempt=2 model=claude-sonnet-4.6

未来改进

可以考虑的进一步优化：

1. 添加更多浏览器类型 (Firefox, Safari)
2. 支持移动设备指纹
3. 根据成功率动态调整配置策略
4. 添加指纹轮换策略 (定期刷新)