# Cursor2API Go 实现说明：OpenAI `chat/completions` 下的 thinking + tools

本文档只描述当前 Go 仓库已经实现或明确约束的行为，不再沿用旧的 Deno `/v1/messages` 迁移口径。

## 1. 当前范围

当前仓库只支持两个公开接口：

- `GET /v1/models`
- `POST /v1/chat/completions`

不实现 `/v1/messages`，也不承诺 Anthropic 原生 block/SSE 兼容。

## 2. 真实能力边界

### 2.1 公开模型目录

配置项 `MODELS` 只填写基础模型，例如：

```env
MODELS=claude-sonnet-4.6
```

服务会自动向外暴露两类模型：

- 基础模型：`claude-sonnet-4.6`
- thinking 派生模型：`claude-sonnet-4.6-thinking`

约定如下：

- 基础模型：保留现有模型名，启用 tool 能力。
- `-thinking` 模型：自动映射回基础模型出站，同时启用 thinking 和 tool 能力。
- 不允许继续派生 `-thinking-thinking`。

### 2.2 外部接口契约

当前实现的是 OpenAI `chat/completions` 兼容面：

- 请求支持 `messages`
- 请求支持 `tools`
- 请求支持 `tool_choice`
- assistant 历史消息支持 `tool_calls`
- tool 历史消息支持 `tool_call_id`
- 响应支持非流式 `message.tool_calls`
- 响应支持流式 `delta.tool_calls`

thinking 不作为 OpenAI 独立字段对外暴露。它只作为内部 prompt 协议与解析协议使用。

## 3. 请求侧链路

### 3.1 入口文件

- `handlers/handler.go`
- `services/cursor.go`
- `services/cursor_protocol.go`

### 3.2 处理步骤

1. `handlers.ChatCompletions` 绑定并校验 OpenAI 请求。
2. `CursorService.buildCursorRequest(...)` 解析模型能力：
   - `claude-sonnet-4.6` -> 基础模型
   - `claude-sonnet-4.6-thinking` -> 基础模型 + thinking 开启
3. `tool_choice` 被解析为三类模式：
   - `auto`
   - `none`
   - `required`
   - 或 `{"type":"function","function":{"name":"..."}}`
4. 工具定义被统一校验：
   - 仅支持 `type=function`
   - `function.name` 必填
   - 不允许重名
5. 构造单次请求专用 `TriggerSignal`，格式：

```text
<<CALL_xxxxxxxx>>
```

6. 构造发往 Cursor 的纯文本消息。

## 4. 内部 prompt 协议

上游 Cursor 仍然只收到文本消息，不使用原生 OpenAI tool calling。

### 4.1 tool 协议

当请求含有 `tools` 且 `tool_choice != "none"` 时，system message 会注入：

- 工具桥接说明
- tool 调用格式约束
- `<function_list>` 工具清单
- `required` / 指定 function 的额外约束

模型被要求按如下格式输出工具调用：

```text
<<CALL_xxxxxxxx>>
<invoke name="tool_name">{"arg":"value"}</invoke>
```

### 4.2 thinking 协议

当请求命中 `*-thinking` 模型时：

- system prompt 注入 thinking 规则
- 每条 user message 追加固定 thinking hint

hint 为：

```text
Use <thinking>...</thinking> for hidden reasoning when it helps. Keep your final visible answer outside the thinking tags.
```

### 4.3 历史消息回放

为了让多轮 tool loop 继续工作，OpenAI 历史消息会被回放成内部文本协议：

- assistant `tool_calls` -> `TriggerSignal + <invoke ...>`
- tool message -> `<tool_result id="...">...</tool_result>`

普通 `system/user/assistant` 文本则继续按 Cursor `parts[].text` 发送。

## 5. 响应解析链路

### 5.1 入口文件

- `services/cursor.go`
- `utils/cursor_protocol.go`
- `utils/utils.go`

### 5.2 解析步骤

1. `consumeSSE(...)` 读取 Cursor SSE。
2. 每个 `delta` 文本片段进入 `CursorProtocolParser`。
3. 解析器增量产出三类内部事件：
   - `text`
   - `thinking`
   - `tool_call`
4. `thinking` 只保留在内部事件层，不直接回写给客户端。

### 5.3 解析规则

- `<thinking>...</thinking>` 在 thinking 模型下会被消费为内部 thinking 事件。
- `TriggerSignal + <invoke ...>` 会被消费为工具调用事件。
- 不完整标签会在流结束时降级为普通文本，避免丢内容。
- 多个连续 `<invoke>` 会逐个产出，不再只保留第一个。

## 6. OpenAI 响应写回

### 6.1 非流式

非流式响应会在 `services.CursorService.ChatCompletionNonStream(...)` 中聚合内部事件：

- 只有文本时，返回普通 `message.content`
- 有工具调用时，返回 assistant `tool_calls`
- 若本轮出现工具调用，`finish_reason = "tool_calls"`
- 否则 `finish_reason = "stop"`

为提升与部分编排器（例如 Kilo Code）在“必须用工具”场景下的兼容性：

- 当请求含 `tools` 且被判定为“必须至少调用一次工具”（`tool_choice=required/指定函数`，或启用 `KILO_TOOL_STRICT`）时，
  如果第一轮没有产出任何 `tool_calls`，服务会自动重试 1 次（仅非流式）。

### 6.2 流式

`utils.StreamChatCompletion(...)` 会输出：

- 首个 role chunk：`assistant`
- 文本 chunk：`delta.content`
- 工具调用 chunk：`delta.tool_calls`
- 收尾 chunk：
  - 有工具调用 -> `finish_reason = "tool_calls"`
  - 无工具调用 -> `finish_reason = "stop"`

thinking 内容不会作为独立 OpenAI 字段透出。

## 7. 代码落点

本次能力集中在以下模块：

- `models/`
  - OpenAI request/response/tool 类型
  - thinking 模型派生规则
  - 基础模型到 Cursor 模型的映射
- `config/`
  - `MODELS` 基础模型配置
  - 自动扩展 `*-thinking` 公开模型目录
- `services/cursor_protocol.go`
  - `tool_choice` 解析
  - 工具定义校验
  - OpenAI 历史消息到 Cursor 文本协议的转换
- `utils/cursor_protocol.go`
  - Cursor 文本增量到 `text/thinking/tool_call` 事件的解析
- `utils/utils.go`
  - OpenAI 流式/非流式响应写回

## 8. 测试基线

当前测试覆盖以下关键路径：

- `MODELS` 自动扩展基础模型和 `-thinking` 模型
- thinking 模型回落到基础出站模型
- tool prompt 注入与 tool history 回放
- `<thinking>` / `<invoke>` 的增量解析
- 流式 `delta.tool_calls`
- 非流式 `message.tool_calls`
- 纯文本聊天回归不破坏

## 9. 非目标

当前不做以下内容：

- Anthropic `/v1/messages`
- MCP
- 原生 OpenAI tool execution
- 可见的 reasoning/thinking 对外字段
- 图像、文档、文件等多模态 block 协议