# Trae 上游协议（llm_utils_chat / SOLO）

## 关键教训：主机不是 api.trae.cn

api.trae.cn 只是账号/OAuth 主机，直接请求 /api/agent/v3/llm_utils_chat 会 404。
模型网关是：

| 地区 | 主机 |
|---|---|
| CN | https://trae-api-cn.mchost.guru |
| INTL | https://a0ai-api-sg.byteintlapi.com |

路径统一：POST /api/agent/v3/llm_utils_chat

## 请求头（CN SOLO）

参考 trae2api-cn 实现，完整头集合如下（缺头/老版本头会被网关拒绝，甚至伪装成 404）：

    Authorization: Cloud-IDE-JWT <jwt>
    X-Cloudide-Token: <jwt>
    x-ide-token: <jwt>
    x-uid: <user_id>
    x-app-id: 6eefa01c-1036-4c7e-9ca5-d891f63bfcd8
    x-device-id: <device_id>
    x-machine-id: <device_id>
    x-request-id: <uuid>
    x-ide-version: 0.1.52
    x-ide-version-code: 20260811
    x-ide-version-type: stable
    x-app-version: default
    x-app-version-code: 20260811
    x-version-code: 20260811
    x-device-cpu: AMD
    x-device-brand: 83DG
    x-device-type: windows
    x-device-platform: windows
    x-os-version: Windows 11 Pro
    x-system-type: Windows
    package-type: stable_cn
    x-lscbd-aid: 787976
    x-lscbd-platform: windows
    x-ss-dp: 787976
    x-plugin-channel: icube-ai
    app-version: 0.1.52
    x-bridge-transport: aha
    x-ahanet-timeout: 86400
    x-lgw-req-sdk-type: 3
    x-net-sdk-domain-dispatch: 1
    x-ttnet-bypass-decompression: 1
    x-ttnet-bypass-cookie: 0
    request-traffic-type: prod
    User-Agent: Trae/0.1.52
    Accept: text/event-stream

> 注意：Authorization 头里的 $jwt 是变量插值，不是字符串 jwt。
> 曾经因此修了一个“一直 404”的 bug。

## 请求体（SOLO）

    {
      "messages": [
        {
          "role": "user",
          "content": [
            {"type": "text", "text": "你好"}
          ]
        }
      ],
      "config_name": "glm-5.2",
      "model": "glm-5.2",
      "function": "solo_work_lite",
      "stream": true,
      "request_id": "<session_id>",
      "session_id": "<session_id>",
      "max_tokens": 4096
    }

### content 必须是数组

上游 Go 结构体：

    type LLMRawMessage struct {
        Role    string                  `json:"role"`
        Content []*LLMRawMessageContent `json:"content"`
    }

所以 OpenAI 风格字符串 "content": "你好" 会报：

    {"code":4001,"message":"bad request: json: cannot unmarshal string into Go struct field LLMRawMessage.messages.content of type []*idecopilot.LLMRawMessageContent"}

## 常见坑

| 现象 | 原因 |
|---|---|
| 404 | 发到 api.trae.cn；或缺 SOLO 路由头 |
| 400 4001 | content 是字符串不是块数组 |
| 401 | jwt 过期 / Authorization 头拼错 |
| 403 排队码 10605 | 免费模型繁忙，业务层面的排队状态 |