proxy-playbook/docs/TRAE_PROTOCOL.md

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	免费模型繁忙，业务层面的排队状态