cursor2api/config.yaml.example

# Cursor2API v2 配置文件
# 复制此文件为 config.yaml 并根据需要修改

# 服务端口
port: 3010

# 请求超时（秒）
timeout: 120

# ==================== API 鉴权（推荐公网部署时开启） ====================
# 配置后所有 POST 请求必须携带 Bearer token 才能访问
# 客户端使用方式：Authorization: Bearer <token> 或 x-api-key: <token>
# 支持多个 token（数组格式），不配置则全部放行
# 环境变量: AUTH_TOKEN=token1,token2 (逗号分隔)
# auth_tokens:
#   - "sk-your-secret-token-1"
#   - "sk-your-secret-token-2"

# ==================== 代理设置 ====================
# 全局代理（可选）
# ⚠️ Node.js fetch 不读取 HTTP_PROXY / HTTPS_PROXY 环境变量，
#    必须在此处或通过 PROXY 环境变量显式配置代理。
# 支持 http 代理，含认证格式: http://用户名:密码@代理地址:端口
# 💡 国内可直连 Cursor API，通常不需要配置全局代理
# proxy: "http://127.0.0.1:7890"

# Cursor 使用的模型
cursor_model: "anthropic/claude-sonnet-4.6"

# ==================== 自动续写配置 ====================
# 当模型输出被截断时，自动发起续写请求的最大次数
# 默认 0（禁用），由客户端（如 Claude Code）自行处理续写，体验更好
# 设为 1~3 可启用 proxy 内部续写（拼接更完整，但延迟更高）
# 环境变量: MAX_AUTO_CONTINUE=0
max_auto_continue: 0

# ==================== 历史消息条数硬限制 ====================
# 输入消息条数上限，超出时删除最早的消息（保留工具 few-shot 示例）
# 注意：按条数限制无法反映实际 token 体积，建议改用 max_history_tokens（更精准）
# 如需同时设置，两者独立生效，取更严格的结果
# 设为 -1 不限制消息条数
# 环境变量: MAX_HISTORY_MESSAGES=100
max_history_messages: -1

# ==================== 历史消息 Token 数硬限制（推荐） ====================
# 按 js-tiktoken (cl100k_base) 估算 token 数裁剪历史，比按条数更精准
# 能有效防止超出 Cursor API 200k 上下文上限，保障模型输出稳定
#
# ⚠️  注意：js-tiktoken 使用 OpenAI cl100k_base 词表估算，与 Claude 实际 tokenizer 有差异
#     实测低估约 10%~20%，中英混合/工具调用场景差异更大
#     建议开启后观察 UI 日志中的「↑ Cursor 输入 tokens」真实值，再据此调整
#
# 裁剪规则：
#   - 系统提示 + 工具定义的 token 优先扣除
#   - 剩余额度从最新消息往前累加，超出预算的最早消息整条删除
#   - 工具模式的 few-shot 示例（前 2 条）始终保留
#
# 参考值：120000～140000（考虑到估算误差，需预留足够安全余量）
# Cursor API 上下文上限约 200k tokens，实际可用历史额度受系统提示和工具定义影响
#
# 与 max_history_messages 的关系：
#   两者独立生效，若同时设置则取更严格的结果
#   推荐：只设置 max_history_tokens，不设置 max_history_messages
#
# 设为 -1 不限制
# 环境变量: MAX_HISTORY_TOKENS=130000
max_history_tokens: 130000

# ==================== Thinking 开关（最高优先级） ====================
# 控制是否向 Cursor 发送 thinking 请求，优先级高于客户端传入的 thinking 参数
# 设为 true: 强制启用 thinking（即使客户端没请求也注入）
# 设为 false: 强制关闭 thinking（即使客户端请求了 thinking 也不启用）
# 不配置此项时: 跟随客户端请求（Anthropic API 看 thinking 参数，OpenAI API 看模型名/reasoning_effort）
# 环境变量: THINKING_ENABLED=true|false
thinking:
  enabled: false

# ==================== 历史消息压缩配置 ====================
# 对话过长时自动压缩早期消息，释放输出空间，防止 Cursor 上下文溢出
# 压缩算法会智能识别消息类型，不会破坏工具调用的 JSON 结构
compression:
  # 是否启用压缩（true/false），关闭后所有消息原样保留
  # 环境变量: COMPRESSION_ENABLED=true|false
  enabled: false

  # 压缩级别: 1=轻度(默认), 2=中等, 3=激进
  # 环境变量: COMPRESSION_LEVEL=1|2|3
  # 级别说明:
  #   1（轻度）: 保留最近 10 条消息，早期消息保留 4000 字符，适合日常使用（默认）
  #   2（中等）: 保留最近 6 条消息，早期消息保留 2000 字符，适合中长对话
  #   3（激进）: 保留最近 4 条消息，早期消息保留 1000 字符，适合超长对话/大工具集
  level: 1

  # 以下为高级选项，设置后会覆盖 level 的预设值
  # 保留最近 N 条消息不压缩（数字越大保留越多上下文）
  # keep_recent: 10

  # 早期消息最大字符数（超过此长度的消息会被智能压缩）
  # early_msg_max_chars: 4000

# ==================== 工具处理配置 ====================
# 控制工具定义如何传递给模型，影响上下文体积和工具调用准确性
tools:
  # Schema 呈现模式
  #   'compact': TypeScript 风格的紧凑签名，体积最小（~15K chars/90工具）
  #              示例: {file_path!: string, encoding?: utf-8|base64}
  #   'full':    [默认] 完整 JSON Schema，工具调用最精确
  #              适合工具少（<20个）或需要最高准确率的场景
  #   'names_only': 只输出工具名和描述，不输出参数Schema
  #              极致省 token，适合模型已经"学过"这些工具的场景（如 Claude Code 内置工具）
  schema_mode: 'full'

  # 工具描述截断长度
  #   0:  [默认] 不截断，保留完整描述，工具理解最准确
  #   50: 截断到 50 个字符，节省上下文（适合工具多的场景）
  #   200: 中等截断，保留大部分有用信息
  description_max_length: 0

  # 工具白名单 — 只保留指定名称的工具（不配则保留所有工具）
  # 💡 适合只用核心工具、排除大量不需要的 MCP 工具等场景
  # include_only:
  #   - "Read"
  #   - "Write"
  #   - "Bash"
  #   - "Glob"
  #   - "Grep"
  #   - "Edit"

  # 工具黑名单 — 排除指定名称的工具
  # 💡 比白名单更灵活，可以只去掉几个不常用的工具
  # exclude:
  #   - "some_mcp_tool"

  # ★ 透传模式（推荐 Roo Code / Cline 等非 Claude Code 客户端开启）
  #   true:  跳过 few-shot 注入和工具格式改写，直接将工具定义以原始 JSON 嵌入系统提示词
  #          减少与 Cursor 内建身份的提示词冲突，解决「只有 read_file/read_dir」的错误
  #          工具调用仍使用 ```json action``` 格式，响应解析不受影响
  #   false: [默认] 使用标准模式（buildToolInstructions + 多类别 few-shot 注入）
  #          Claude Code 推荐此模式，兼容性和工具调用覆盖率更好
  # 环境变量: TOOLS_PASSTHROUGH=true|false
  # passthrough: true

  # ★ 禁用模式（极致省上下文）
  #   true:  完全不注入工具定义和 few-shot 示例，节省大量上下文空间
  #          模型凭自身训练记忆处理工具调用（适合已内化工具格式的场景）
  #          响应中的 ```json action``` 块仍会被正常解析
  #   false: [默认] 正常注入工具定义
  # 环境变量: TOOLS_DISABLED=true|false
  # disabled: true

# ==================== 响应内容清洗（可选，默认关闭） ====================
# 开启后，会将响应中 Cursor 相关的身份引用替换为 Claude
# 例如 "I am Cursor's support assistant" → "I am Claude, an AI assistant by Anthropic"
# 同时清洗工具可用性声明、提示注入指控等敏感内容
# 💡 如果你不需要伪装身份，建议保持关闭以获得最佳性能
# 💡 开启后，所有响应都会经过正则替换处理，有轻微性能开销
# sanitize_response: true

# ==================== 自定义拒绝检测规则（可选） ====================
# 追加到内置拒绝检测列表之后（不替换内置规则），匹配到则触发重试逻辑
# 每条规则作为正则表达式解析（不区分大小写），无效正则会自动退化为字面量匹配
# 💡 适用场景：特定语言的拒绝措辞、项目特有的拒绝响应、新的 Cursor 拒绝模式
# 支持热重载：修改后下一次请求即生效
# refusal_patterns:
#   - "我无法协助"
#   - "this violates our"
#   - "I must decline"
#   - "无法为您提供"
#   - "this request is outside"

# 浏览器指纹配置
fingerprint:
  user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36"

# ==================== 视觉处理降级配置（可选） ====================
# 如果开启，可以拦截您发给大模型的图片进行降级处理（因为目前免费 Cursor 不支持视觉）。
vision:
  enabled: true
  # mode 选项: 'ocr' 或 'api'
  # 'ocr': [默认模式] 彻底免 Key，零配置，完全依赖本机的 CPU 识图，提取文本、报错日志、代码段后发给大模型。
  # 'api': 需要配置下方的 baseUrl 和 apiKey，把图发给外部视觉模型（如 Gemini、OpenRouter），能"看到"画面内容和色彩。
  mode: 'ocr'
  
  # ---------- 以下选项仅在 mode: 'api' 时才生效 ----------
  # base_url: "https://openrouter.ai/api/v1/chat/completions"
  # api_key: "sk-or-v1-..."
  # model: "meta-llama/llama-3.2-11b-vision-instruct:free"
  
  # Vision 独立代理（可选）
  # 💡 Cursor API 国内可直连无需代理，但图片分析 API（OpenAI/OpenRouter）可能需要
  #    配置此项后只有图片 API 走代理，不影响主请求的响应速度
  #    如果不配，会回退到上面的全局 proxy（如果有的话）
  # proxy: "http://127.0.0.1:7890"

# ==================== 日志持久化配置（可选） ====================
# 开启后日志会写入文件，重启后自动加载历史记录
# 环境变量: LOG_FILE_ENABLED=true|false, LOG_DIR=./logs, LOG_PERSIST_MODE=compact|full|summary
logging:
  # 是否启用日志文件持久化（默认关闭）
  file_enabled: false
  # 日志文件存储目录
  dir: "./logs"
  # 日志保留天数（超过天数的日志文件会自动清理）
  max_days: 7
  # 落盘模式:
  #   compact = 精简调试信息（保留更多排障细节）
  #   full    = 完整持久化
  #   summary = 仅保留“用户问了什么 / 模型答了什么”与少量元数据（默认）
  persist_mode: summary