# trae-enterprise-proxy

**Repository Path**: fleey/trae-enterprise-proxy

## Basic Information

- **Project Name**: trae-enterprise-proxy
- **Description**: trae企业版cli proxy。严禁前人砍树后人暴晒。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# trae2api

把本机的 **TraeCode CLI (`traecli`)** 反代成 **OpenAI 兼容接口 + Anthropic 兼容接口**，
让 Codex、Claude Code、Cherry Studio、NextChat、LangChain、官方 `openai` / `anthropic` SDK
等标准客户端直接用上 Trae 的模型。

- ✅ **三套协议**：OpenAI Chat Completions、OpenAI Responses、Anthropic Messages，同一个端口
- ✅ **真 function calling**：直连模式下客户端的 `tools` 原样透传，回来的是标准 OpenAI `tool_calls`
  / Anthropic `tool_use`
- ✅ **不需要工作目录**：直连模式下工具由客户端自己执行，不用配 workspace、不用挂 volume
- ✅ **流式 thinking**：推理内容逐 token 实时吐到 `reasoning_content` / `thinking_delta`
- ✅ **图片识别**：OpenAI `image_url` 的 `data:` URI、Anthropic `image.source.base64` 都透传
  （发给纯文本模型会被挡在本地并告诉你换哪个，见 `GET /v1/models` 的 `multimodal`）
- ✅ **完整 agent 能力**：agent 模式下可以真的改文件、跑命令
- ✅ **19 个模型**：Doubao / GLM / MiniMax / Qwen / Kimi / DeepSeek
- ✅ **Docker**：镜像内置官方 Linux 版 traecli

---

## 先选模式：`direct` 还是 `agent`

这是用这个项目**最重要的一个决定**，由 `TRAE2API_UPSTREAM` 控制。两种模式的能力边界完全不同。

| | `direct`（默认） | `agent` |
|---|---|---|
| 走什么 | 直连 Trae 后端 `/api/ide/v2/llm_raw_chat` | traecli app-server，跑完整 agent loop |
| 客户端 `tools` | ✅ **原样透传，返回真的 `function_call` / `tool_use`** | ❌ 只能忽略 |
| 谁执行工具 | **客户端自己**（在它自己的当前目录） | traecli（在服务端配置的 cwd 里） |
| 要不要配工作目录 | ❌ **完全不需要** | ✅ 必须配，否则 agent 在空目录里瞎编 |
| Docker 要不要挂项目 | ❌ 不用 | ✅ 要挂，还要配 `CWD_MAP` |
| `instructions` / `system` 提示 | ✅ 用客户端自己的 | 被 traecli 约 14700 字符的系统提示覆盖 |
| 输入开销 | ≈ 几百 token | 每轮 22k~27k token |
| 正文流式 | ✅ 逐 token | ❌ 上游整块下发 |
| 自主改文件 / 跑命令 | ❌ 由客户端驱动 | ✅ |
| 服务端文件系统访问 | **零** | 有（受 roots 白名单约束） |
| 稳定性 | ⚠️ 未公开内部端点，随时可能变 | ✅ 官方 CLI 接口 |

**怎么选：**

- **客户端自带 agent loop**（Codex、Claude Code、CC Switch、LangChain agent、任何要
  function calling 的东西）→ 用 `direct`。这是它们本来期望的协议，也是唯一能拿到
  `function_call` / `tool_use` 的路。
- **想让服务端自己动手改代码**（发一句话，让它把文件改了）→ 用 `agent`。
- **只是纯聊天** → 两个都行，`direct` 更省 token、正文还是流式的。

默认就是 `direct`，不用配。确认上游能通（只读探测，不写任何东西，不打印 token）：

```bash
python3 tools/verify_direct.py --tools
```

要服务端自己动手改文件，才需要显式切回：

```bash
TRAE2API_UPSTREAM=agent
```

`agent` 模式还得配工作目录，见下面「`agent` 模式专属」那节。

---

## ⚠️ 安全须知

安全边界**取决于上面选的模式**，差别很大：

**`direct` 模式（默认）**：服务端不碰文件系统，不起 traecli 的 agent loop。风险面就是一个普通的
模型 API + 你的 Trae 账号额度。下面那一整套 cwd 白名单机制在这个模式下不参与，因为没有东西需要它约束。

**`agent` 模式（需显式开启）**：**任何能访问这个端口的人，都能在这台机器上执行 shell 命令、读写文件。**
它不是一个普通的模型 API。内置的几道防线（都是默认生效的）：

| 防线 | 行为 |
|---|---|
| 强制鉴权 | 没配任何 key 就**拒绝启动**（除非显式 `TRAE2API_ALLOW_NO_AUTH=1`） |
| 只听回环 | 默认绑 `127.0.0.1`；绑非回环地址又没鉴权时拒绝启动 |
| 工作目录白名单 | 没给 key 配 roots 时，它**根本不能指定 cwd**，一律跑在 scratch 目录 |
| 路径归一 | `trae_cwd` 先 `realpath` 再校验，`../../etc` 这类会被 403 |
| 按 key 隔离 | 多 key 模式下，每个 key 只能碰自己的 roots，跨项目越权 403 |
| 沙箱 | 默认 `workspace-write` + `approvalPolicy=never`：越权动作直接拒，不会挂起等人 |
| 越权需双开关 | `danger-full-access` 要求服务端 `TRAE2API_ALLOW_FULL_ACCESS=1` **且**请求显式指定 |

鉴权在两种模式下都强制生效。但不管哪种模式，都不要把这个端口暴露到公网或不受信任的局域网。

---

## 快速开始

前提：本机已装好 `traecli` 并且 `traecli login` 登录过（`traecli login status` 可查）。

```bash
python3 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
cp .env.example .env
```

编辑 `.env`：**把 `TRAE2API_API_KEY` 改掉**。上游模式保持默认的 `direct` 即可。然后：

```bash
./run.sh
```

验证：

```bash
./.venv/bin/python tools/smoke_test.py --api-key "$TRAE2API_API_KEY"
```

`direct` 模式到这里就配完了 —— 没有工作目录、roots、volume 要操心。

### 接客户端

两套协议同一个端口、同一把 key（你设的 `TRAE2API_API_KEY`），区别只有 Base URL 带不带 `/v1`：

| 客户端 | Base URL | Key 怎么带 |
|---|---|---|
| OpenAI 系（Codex、Cherry Studio、NextChat、`openai` SDK…） | `http://localhost:8787/v1` | `Authorization: Bearer` |
| Anthropic 系（Claude Code、`anthropic` SDK…） | `http://localhost:8787`（**不带 `/v1`**，SDK 自己拼） | `x-api-key`，`Bearer` 也认 |

Claude Code 直接用环境变量起：

```bash
ANTHROPIC_BASE_URL=http://localhost:8787 ANTHROPIC_AUTH_TOKEN=你的key claude
```

Anthropic 侧的字段对应关系和流式事件见 [`POST /v1/messages`](#post-v1messages)。

下面是 OpenAI 侧的例子。function calling：

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8787/v1", api_key="你的key")

resp = client.chat.completions.create(
    model="Doubao-Seed-Evolving",
    messages=[{"role": "user", "content": "北京天气怎么样？"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询某个城市的天气",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
)
print(resp.choices[0].message.tool_calls)
# [ChatCompletionMessageToolCall(id='call_...', function=Function(
#     arguments='{"city": "Beijing"}', name='get_weather'), type='function')]
```

流式 + thinking：

```python
resp = client.chat.completions.create(
    model="DeepSeek-V4-Flash 正式版",
    messages=[{"role": "user", "content": "一步步推理：17*23 等于多少？"}],
    stream=True,
)
for ev in resp:
    if not ev.choices:
        continue
    delta = ev.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="", flush=True)   # 思考过程
    if delta.content:
        print(delta.content, end="", flush=True)             # 正文
```

> 官方 SDK 的 typed model 不认识 `reasoning_content`，非流式下要从
> `resp.choices[0].message.model_extra["reasoning_content"]` 取；流式的 `delta` 可以直接
> `getattr(delta, "reasoning_content", None)`。

---

## API

### `GET /health`

不需要鉴权，给编排系统探活用。

```json
{"status":"ok","upstream":"direct","traecli":"0.201.4-tob","app_server":"disabled","active_turns":0,"version":"0.1.0"}
```

`direct` 模式下 `app_server` 恒为 `disabled` —— 那个子进程根本不会起。

`agent` 模式下 `app_server` 有 `running` / `restarting` / `failed` / `stopped`。app-server 子进程
挂了会自动按指数退避重启，重启窗口内请求返回 503。

### `GET /v1/models` / `GET /v1/models/{id}`

返回 19 个模型，`id` 用的是 `traecli models` 里那种展示名（`GLM-5.3`、`DeepSeek-V4-Flash 正式版`）。
每个模型还带顶层整数 `context_window`（直接取自 traecli 模型元数据），Codex Desktop
可以据此自动设置上下文窗口，无需手填。

```json
{"id":"GLM-5.3","object":"model","owned_by":"trae","context_window":200000}
```

OpenAI 和 Anthropic 都在 `/v1/models` 做模型发现，但返回结构不兼容。**带
`anthropic-version` 头的请求**（Anthropic SDK 一定会带）会拿到 Anthropic 那套：

```json
{"data":[{"type":"model","id":"GLM-5.3","display_name":"GLM-5.3","created_at":"..."}],
 "has_more":false,"first_id":"GLM-5.3","last_id":"..."}
```

**别名**：内部 id 也认。`glm-5.3`、`GLM-5.3`、`DeepSeek-V4-Flash-Official` 都能解析到同一个模型，
大小写不敏感。带空格和中文的模型名在某些客户端里不好填，用别名即可。

### `POST /v1/chat/completions`

生效的标准参数：`model`、`messages`、`stream`、`stream_options.include_usage`，以及
`direct` 模式下的 `tools`、`max_tokens` / `max_completion_tokens`（由代理自己截断，见
[输出兜底](#输出兜底截断与重复塌缩)）。`tool_choice` 收下但**不生效**——私有端点忽略它，
实测 `tool_choice:"none"` 照样返回工具调用。

`direct` 模式下的工具调用（`finish_reason` 为 `tool_calls`）：

```bash
curl -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  localhost:8787/v1/chat/completions \
  -d '{"model":"Doubao-Seed-Evolving",
       "messages":[{"role":"user","content":"北京天气？调用工具。"}],
       "tools":[{"type":"function","function":{"name":"get_weather",
                 "parameters":{"type":"object","properties":{"city":{"type":"string"}}}}}]}'
```

把工具结果喂回去继续下一轮，就是标准 OpenAI 流程：追加一条带 `tool_calls` 的 assistant 消息，
再追加 `{"role":"tool","tool_call_id":"…","content":"…"}`。本代理是无状态的，每轮把完整对话发过来即可。

**扩展参数**（仅 `agent` 模式生效；body 字段优先于 header，header 优先于环境默认）：

| body | header | 作用 |
|---|---|---|
| `trae_cwd` | `X-Trae-Cwd` | agent 的工作目录，必须落在该 key 的 roots 内 |
| `trae_sandbox` | `X-Trae-Sandbox` | `read-only` / `workspace-write` / `danger-full-access` |
| `trae_approval_policy` | — | `untrusted` / `on-failure` / `on-request` / `never` |
| `trae_effort` | `X-Trae-Effort` | `none`…`ultra` 推理强度 |
| `trae_reasoning_summary` | — | `auto` / `concise` / `detailed` / `none` |
| `trae_timeout` | — | 本次超时秒数，仍受 `TRAE2API_TIMEOUT` 封顶 |

`direct` 模式会**静默忽略**这一整组参数（包括 `model@cwd` 后缀里的路径），因为那边压根没有服务端
工作目录这回事。

### `POST /v1/responses`

OpenAI **Responses API**。Codex 系客户端用的是这套，而不是 chat/completions —— 两者协议不同，
所以都实现了。

- `input` 支持字符串、`{"role","content"}` 简写、以及完整的 `{"type":"message","content":[{"type":"input_text"...}]}` 项
- `instructions` 映射成 system 消息（`direct` 模式下原样送达模型）
- `input_image` 同样支持 `data:` URI
- 推理走 `response.reasoning_summary_text.delta` 事件流（**逐 token**）
- `direct` 模式下 `tools` 支持扁平写法 `{"type":"function","name":…,"parameters":…}`，
  返回标准 `function_call` 输出项；把 `function_call` + `function_call_output` 放回 `input` 就能接着下一轮
- `agent` 模式下 `reasoning.effort` 映射到 traecli 的 effort

流式事件序列（实测）：

```
response.created → response.in_progress
→ output_item.added(reasoning) → reasoning_summary_part.added
→ reasoning_summary_text.delta × N        ← 逐 token 的思考过程
→ reasoning_summary_text.done → reasoning_summary_part.done → output_item.done
→ output_item.added(message) → content_part.added
→ output_text.delta × N → output_text.done → content_part.done → output_item.done
→ response.completed
```

工具调用时把 message 那一段换成
`output_item.added(function_call)` → `function_call_arguments.delta × N` →
`function_call_arguments.done` → `output_item.done`。

不支持：`previous_response_id`（400，本代理无状态，请把完整对话放进 `input`）。

### `POST /v1/messages`

**Anthropic Messages API**。Claude Code、官方 `anthropic` SDK、Cherry Studio 的 Claude
供应商走的是这套。鉴权用 `x-api-key`（`Authorization: Bearer` 也认，是同一把 key）。

```python
from anthropic import Anthropic

client = Anthropic(base_url="http://localhost:8787", api_key="你的key")

msg = client.messages.create(
    model="Doubao-Seed-Evolving",
    max_tokens=1024,
    system="你是一个简洁的助手。",
    messages=[{"role": "user", "content": "北京天气？调用工具。"}],
    tools=[{
        "name": "get_weather",
        "description": "查询某个城市的天气",
        "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    }],
)
print(msg.stop_reason, msg.content)
# tool_use [ToolUseBlock(id='call_...', name='get_weather', input={'city': 'Beijing'})]
```

对应关系：

| Anthropic | 这里怎么处理 |
|---|---|
| `system`（字符串或 text block 数组） | 变成 system 消息，`direct` 模式下原样送达模型 |
| `messages[].content` 的 `text` / `image` | 透传；`image.source.base64` 转成 `data:` URI |
| 用户消息里的 `tool_result` block | 拆成独立的 tool 消息（Anthropic 塞在 user 轮里，上游要分开） |
| `tool_result.is_error` | 内容前面加 `[tool error]`，否则模型看不出工具失败了 |
| assistant 消息里的 `tool_use` block | 还原成上游要的 `tool_calls` |
| 历史里的 `thinking` block | 丢弃（不带指令价值，且签名不是我们签的） |
| `tools[].input_schema` | 映射成 `function.parameters` |
| `max_tokens` | **必填**，`direct` 模式下由代理自己数着截断 |
| `stop_sequences` | **由代理实现**：匹配上就切流，`stop_reason` 报 `stop_sequence` |
| `thinking: {"type":"enabled"}` | 开了才回 `thinking` block；没开就把推理丢掉 |
| `temperature` / `top_p` / `top_k` / `tool_choice` | 收下但不生效，上游没这些旋钮 |

流式事件序列：

```
message_start → ping
→ content_block_start(thinking) → content_block_delta(thinking_delta) × N → content_block_stop
→ content_block_start(text) → content_block_delta(text_delta) × N → content_block_stop
→ message_delta(stop_reason, usage) → message_stop
```

工具调用那一段是
`content_block_start(tool_use)` → `content_block_delta(input_json_delta) × N` →
`content_block_stop`，`stop_reason` 为 `tool_use`。

`stop_reason` 映射：正常结束 `end_turn`；有工具调用 `tool_use`；被
[输出兜底](#输出兜底截断与重复塌缩) 截断 `max_tokens`；命中 `stop_sequences` 则是
`stop_sequence`，同时 `stop_sequence` 字段给出命中的那一条。

`agent` 模式下这个端点也能用，但和另外两个协议一样：`tools` 被忽略、永远拿不到
`tool_use`、`max_tokens` 不生效。

报错走 Anthropic 自己的信封，不是 OpenAI 那套：

```json
{"type":"error","error":{"type":"invalid_request_error","message":"max_tokens is required."}}
```

### `POST /v1/messages/count_tokens`

返回 `{"input_tokens": N}`。两边上游都没有 tokenizer，也没有计数端点，所以这是个**估算下界**
（和截断时用的是同一套估算：CJK 按 1 token/字，其余按 4 字符/token，不含上游自己加的脚手架）。
够用来做预算，不要拿它对账。

---

## `agent` 模式专属：工作目录、多项目、磁盘

**用 `direct` 模式的话，这一整节都可以跳过。**

### tools 冲突：为什么 agent 模式给不了 function call

Codex / CC Switch 这类客户端**每个请求都带自己的工具定义**，期望模型返回 `function_call`
让客户端自己执行。但 **traecli 是自带 agent loop 的** —— 它会自己跑命令、自己改文件，然后返回文本。

两者不能同时成立：traecli 已经执行过的动作再回传成 `function_call`，客户端会**重复执行一遍**。

所以 `agent` 模式的默认行为是**接受并忽略** `tools`（`TRAE2API_IGNORE_CLIENT_TOOLS=1`）。后果：

- ✅ 活会被干完，文件真的会被改
- ❌ 客户端的工具循环、审批 UI、沙箱**完全不参与** —— 干活的是 traecli，用的是 traecli 的沙箱
- ❌ 客户端永远收不到 `function_call`，只会收到一段文本

想要严格拒绝而不是静默忽略：`TRAE2API_IGNORE_CLIENT_TOOLS=0`（返回 400）。

**想要真的 function call，就是切 `TRAE2API_UPSTREAM=direct`** —— 这个架构冲突在那边不存在。

### 工作目录

这类客户端不会发 `trae_cwd`，所以 `agent` 模式必须设 `TRAE2API_DEFAULT_CWD` 指向你的项目目录，
否则 agent 会在空的 scratch 目录里干活，然后对着一个它看不见的仓库瞎编。

```bash
TRAE2API_DEFAULT_CWD=/workspace
TRAE2API_ALLOWED_ROOTS=/workspace
```

也可以让它从 prompt 里自动认（`TRAE2API_CWD_FROM_REQUEST=1`，默认开）：Codex 会在
`<environment_context>` 里发 `<cwd>`，代理把它抠出来、按 `TRAE2API_CWD_MAP` 映射成容器内路径，
再校验是否落在该 key 的 roots 内。

**`model@cwd` 语法**：给那些只能填模型名的客户端用，受同一套校验，不能用它绕过。

```
"model": "GLM-5.3@/Users/you/projects/demo"
```

示例：

```bash
curl -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  localhost:8787/v1/chat/completions \
  -d '{"model":"GLM-5.3","trae_cwd":"/Users/you/projects/demo",
       "messages":[{"role":"user","content":"创建 hello.py 打印 hello"}]}'
```

### 多项目 / 多租户

一个 key 通吃所有项目是不行的。用 `TRAE2API_KEYS_FILE` 给每个项目发独立 key，各自绑定自己的目录：

```json
{
  "sk-projA-…": {"label": "projA", "roots": ["/srv/projA"]},
  "sk-projB-…": {"label": "projB", "roots": ["/srv/projB"]},
  "sk-chat-…":  {"label": "chatonly"}
}
```

```bash
TRAE2API_KEYS_FILE=/etc/trae2api/keys.json ./run.sh
```

- `roots` 省略 → 该 key **永远不能**设 `trae_cwd`，只能纯聊天。
- `roots: "*"` → 继承 `TRAE2API_ALLOWED_ROOTS`。
- 越权返回 403，且**不会**告诉调用方允许的目录是什么（避免泄漏其他项目的路径布局）。
- 也支持内联 `TRAE2API_KEYS='{...}'`，但 key 会进环境变量，生产建议用文件。

日志里每个 turn 都带 `key=<label>`，方便按项目排查。

已知短板：

| 项 | 现状 |
|---|---|
| **并发是全局的** | `MAX_CONCURRENCY` 所有项目共用一个池子，没有按项目配额。一个项目挂满长任务会让别人排队直到 429 |
| **爆炸半径** | 单个 app-server 进程。它挂了所有项目在途请求同时 503（自动重启，约 1.5 秒） |
| **上游配额** | 所有 key 共用同一个 Trae 账号，限流和 token 预算共享，**无法按项目归账** |
| **memories** | 存储全局不分项目。实测库为空且我们用 ephemeral thread，风险低但非零 |

### 磁盘卫生

traecli 会给**每一个**它见过的工作目录在 `~/.trae/traecli.toml` 里写一条永久
`[projects."…"] trust_level = "trusted"`。

所以本项目**不用**每请求一个临时目录 —— 那会让这个文件无限膨胀（实测跑一轮测试就攒了 28 条死条目）。
没指定 cwd 的请求走**固定 scratch 池**：`TRAE2API_SCRATCH_DIR` 下 `slot-00..slot-NN`，
数量等于并发上限，用完即清空复用。条目数因此被永久钉死在 N 条。

清理历史遗留（指向已不存在目录的条目）：

```bash
python3 tools/prune_trust_entries.py            # 先看要删什么
```

```bash
python3 tools/prune_trust_entries.py --apply    # 写入，自动备份
```

跑之前先停掉 trae2api 和交互式 traecli —— traecli 是整文件覆盖写，并发会把结果冲掉。

---

## Docker

镜像会从 Trae 官方 CDN 下载**官方 Linux 版 traecli**（`traex-linux-x86_64` / `traex-linux-aarch64`，
带 sha256 校验），所以容器是自包含的。但**登录态不会被打进镜像**，必须在运行时提供。

```bash
cp .env.example .env   # 至少改掉 TRAE2API_API_KEY
docker compose up --build
```

### `direct` 模式的 Docker 配置（默认）

没有额外配置。`docker-compose.yml` 里那些
`TRAE2API_WORKSPACE` / `TRAE2API_CWD_MAP` / `TRAE2API_DEFAULT_CWD` **全部不生效**，
`/workspace` 挂载也用不上 —— 容器不进客户端的项目目录，工具都在客户端那边执行。
项目目录因此可以随请求动态变化，换项目不用改任何 Docker 配置。

（compose 里仍然保留了 `/workspace` 挂载，这样切到 `agent` 模式时不用再改 compose 文件。
用不到的时候它就是个空挂载，没有副作用。）

### `agent` 模式的 Docker 配置

设 `TRAE2API_UPSTREAM=agent`，并把项目挂进去。如果客户端在 prompt 的 `<cwd>` 里发送宿主机绝对路径，
挂载和映射必须指向同一个项目：

```bash
TRAE2API_WORKSPACE=/Users/you/projects/demo
TRAE2API_CWD_MAP=/Users/you/projects/demo=/workspace
```

检测到的 cwd 没有挂载或无法映射时，请求会返回 `cwd_unavailable`，不会静默回退到
另一个默认目录执行 agent。

### 容器怎么拿到登录态

两种模式都需要。二选一：

**A. 挂载宿主机的 `~/.trae`**（最省事）

`docker-compose.yml` 里把 `trae-home:/data/.trae` 换成：

```yaml
      - ${HOME}/.trae:/data/.trae
```

注意必须可写 —— traecli 会就地刷新 token。

**B. 用 Personal Access Token**（更适合服务器）

在 `.env` 里：

```
TRAECLI_PERSONAL_ACCESS_TOKEN=<你的 PAT>
TRAECLI_LOGIN_BASE_URL=https://console.enterprise.trae.cn
```

容器 entrypoint 会在首次启动时执行 `traecli login --with-trae-pat`。

两者都没有时容器会带着明确的错误信息退出，不会静默起一个用不了的服务。

### 沙箱说明（仅 `agent` 模式）

Linux 上 `workspace-write` 沙箱靠 **bubblewrap**，而 bwrap 需要非特权 user namespace，
Docker 默认 seccomp 策略会挡住它。实测三种配置：

| 配置 | 结果 |
|---|---|
| 默认 | ❌ `No permissions to create new namespace` |
| `--security-opt seccomp=unconfined` | ✅ 可用 |
| `--cap-add SYS_ADMIN`（仅此） | ❌ `pivot_root: Operation not permitted` |

所以 compose 只加 `seccomp:unconfined`，**不加** `SYS_ADMIN` —— 它既不够用也不必要，
白给一大块特权没有意义。

如果你的环境连 seccomp 都不让放开，更合理的做法是**把容器本身当成沙箱**：
设 `TRAE2API_SANDBOX=danger-full-access` + `TRAE2API_ALLOW_FULL_ACCESS=1`，
同时把 roots 收紧到 `/workspace`，并且**不要**挂载宿主机的敏感目录。

（`direct` 模式不起 traecli 的 agent loop，也就没有沙箱这回事，seccomp 可以保持默认。）

### 实测结论

在 Apple Silicon（Docker 29.6.2, linux/arm64）上完整验证过：

- 镜像自动拉对应架构的官方构建并校验 sha256，ELF 确认为 AArch64 原生（非 Rosetta 模拟）
- PAT 登录路径可用：`Successfully logged in with TraeCode CLI ToB PAT`
- 冒烟 13/13 通过（含流式 thinking、data URI 图片识别、403/401/404 边界）
- bwrap 沙箱在 `seccomp=unconfined` 下可用
- agent 写文件穿过 volume 真实落到宿主机
- 镜像约 629 MB（traecli 二进制本身就 329 MB）

镜像内可以直接跑调试命令，entrypoint 只在启动服务时才要求凭据：

```bash
docker run --rm trae2api:latest traecli --version
```

### 端口

compose 默认只映射到回环：`127.0.0.1:8787:8787`。改成 `8787:8787` 等于把服务暴露给整个局域网
—— `agent` 模式下那是一个能执行命令的 agent，想清楚再改。

---

## `direct` 模式：逆向记录

用 [`tools/capture_upstream.py`](tools/capture_upstream.py) 把 traecli 自己的 provider
base_url 指向本地服务，录到真实请求，逐字段复现。端点 `/api/ide/v2/llm_raw_chat`，请求/响应
都是 Trae 私有格式（不是 OpenAI）：

- 认证：`Authorization: Cloud-IDE-JWT <access_token>`（**不是** Bearer）+ 一组身份头
  （`x-app-id` / `x-ide-function` / `x-ide-version` / `x-ide-version-code` / `version`）
- body：`config_name`（展示名）、`model_name`（内部 id，取自
  `business_metadata.variants.standard_key`）、`messages`（content 是 `[{type,text}]` 列表）、
  `tools`、`session_id`、`access_type`
- 响应：私有 SSE —— `metadata` / `output`（带 `response`/`reasoning_content`/`tool_calls`）/
  `token_usage` / `done`，本项目翻译回 OpenAI Chat / Responses
- `session_id` 标识**整段会话**（不是单轮）。优先取客户端自己的会话 id：请求头
  `session_id` / `x-session-id` / `conversation_id` / `x-conversation-id`（按此优先级，
  大小写不敏感），这样 Codex 侧的 session 和 Trae 侧就是同一个；非 UUID 的值会被哈希成
  UUID 再上送（上游该字段要求 UUID）。没有这些头时，回落到用「开头的 system/developer
  消息 + 第一条 user 消息」派生的稳定 uuid5
- token 直接读 traecli 维护的 `auth.json`，续期由 traecli 负责，不用自己实现 OAuth
- `direct` 只复用逆向得到的模型协议与 traecli 登录态，不运行 traecli 的 agent loop

踩过的坑（都在代码里处理了）：

- `Bearer` → `ErrNoAuth`；`x-ide-token` → `entitlement check failed`；少任何身份头 → 同样失败
- tool 的 `parameters` 传对象 → 后端 500，必须序列化成 **JSON 字符串**
- 上游 `tool_calls` 用 `function_call`、分片增量，需重组成标准 OpenAI `tool_calls`
- **回传历史里的 assistant `tool_calls` 也必须写成 `function_call`**：写 OpenAI 的 `function`
  会被上游当成「这条消息没有工具调用」，紧跟其后的 `role: "tool"` 就成了孤儿 —— 详见下面的空轮第 3 条
- Responses 的扁平 `{"type":"function","name":…}` 工具写法要先转成 Chat 的嵌套 `function` 形状

实测对比（同一个带一个工具定义的短请求）：

| | agent | direct |
|---|---|---|
| prompt_tokens | 22600 | **478** |
| 正文流式 | 整块 | 逐 token |
| 工具调用 | 无 | 标准 OpenAI `tool_calls` |

一键确认能连通 + 工具透传：

```bash
python3 tools/verify_direct.py --tools
```

**风险说明**：这是未公开的内部 API，后端一改直连就断。它是默认值，因为它是唯一能给出 function call
的路 —— 但 `TRAE2API_UPSTREAM=agent` 永远可以切回官方 CLI 通道。合规自行判断。

---

## 输出兜底：截断与重复塌缩

私有端点**一个采样旋钮都不认**，实测（DeepSeek-V4-Pro-Official）：

| 传进去的字段 | 上游行为 |
|---|---|
| `max_tokens=8` / `max_completion_tokens=8` | 照样吐 74~77 个 completion token |
| `temperature=0`，同一 prompt 连发三次 | 三次输出各不相同 |
| `frequency_penalty` / `presence_penalty` | 无任何可观察影响 |
| `tool_choice="none"` | 照样返回工具调用 |

也没有 stop sequence 可传。后果是：模型一旦掉进重复塌缩（`发。发。发。` 刷屏），**没有任何东西
会让它停**，它会一路刷到后端自己的天花板，而这些 token 全算你的。多轮 + 长 reasoning +
客户端工具集和上游内置的 agent 脚手架对不上时，尤其容易触发。

所以 `direct` 模式的这两道闸是**代理自己**做的：读到条件满足就主动掐断上游 SSE。

- **长度预算**：把 `max_tokens` / `max_completion_tokens`（Responses 是 `max_output_tokens`）
  和 `TRAE2API_DIRECT_MAX_OUTPUT_TOKENS` 取小值，边转发边计数，超了就断。
- **重复塌缩探测**：输出末尾出现同一个短片段（≤32 字符）连续重复、累计超过
  `TRAE2API_DIRECT_LOOP_GUARD_CHARS` 个字符（默认 600，且至少重复 10 次）就断。
  普通散文、表格、markdown 分隔线都够不着这个阈值。

被截断的那一轮：Chat Completions 的 `finish_reason` 是 `length`；Responses 走
`response.incomplete` 事件、`status:"incomplete"`、`incomplete_details.reason:"max_output_tokens"`。
日志里有一行 `direct turn cut short (max_tokens|repetition) ...`。

两个注意事项：

- **token 数是估算的**：这边没有模型的 tokenizer，上游的 `token_usage` 又只在整轮结束时才下发。
  按「CJK 约 1 字 1 token、其他约 4 字符 1 token」估。它是预算，不是账单。
- **reasoning 也算进预算**，因为上游就是把它算在 `completion_tokens` 里的。于是给思考型模型
  发一个很小的 `max_tokens`，会得到「`finish_reason: length` + 正文为空」——和 OpenAI 的推理
  模型一个行为。不想要就 `TRAE2API_DIRECT_ENFORCE_MAX_TOKENS=0`，硬顶和塌缩探测仍然生效。
- 被截断的轮次给的是**估算 `usage`**，并带一个非标准的 `"estimated": true` 标记：上游的
  `token_usage` 事件在整轮末尾，掐断了就收不到。`completion_tokens` 是代理自己数的转发量，
  `prompt_tokens` 是**下限**（只算了我们发出去的正文，看不见上游自己包的脚手架——裸的一句话
  请求实际会记 96 个 prompt token）。别拿它对账。

---

## 空轮：一句话都没生成，回答就结束了

多轮聊到一半，客户端显示这一轮**正常结束**、但里面一个字都没有。这不是客户端的问题，是上游
返回了 HTTP 200 + 一个 `output` 事件都没有的流。实测出来两种成因：

**1. 有一条 message 既没有内容、也没有工具调用。**
上游直接整个请求判非法，`biz error ... ErrParamInvalid ... invalid message`（code 4001），
一个 token 都不返回：

```bash
python3 tools/probe_tool_history.py          # 跑全部用例
python3 tools/probe_tool_history.py --case empty_tool_result
```

```
  [ok   ] function_call                    7 output events  41 chars
  [EMPTY] empty_tool_result                0 output events  {"code": 4001, ... invalid message
  [EMPTY] empty_user_content               0 output events  {"code": 4001, ... invalid message
```

空 `content` 只有在**同时挂着 `tool_calls`** 时才被接受。所以一个没有输出的工具结果
（grep 没匹配、命令没 stdout），或者客户端发的 `content: null`，就足以让整轮变哑。
代理现在给这种 message 补一个空文本 part（`[{"type":"text","text":""}]`，实测上游接受），
消息本身保留，不删。

**2. 上游偶发地就是不给 output。** 要么一个错误事件都没有、流开了就关，要么回一个
`code 3003 / all models failed`——里面可能是 `model QPM/TPM rate limited`，也可能是
`model service is unavailable`。这两类都会重试（`TRAE2API_DIRECT_EMPTY_RETRIES`，默认 1 次，
退避 1 秒）。`4001`（请求本身非法）不重试。第一个 `output` 事件之前的框架事件会先攒着，
所以重试不会让客户端看到半个作废的回答。

**3. 工具历史的配对不合上游的规矩**，报 `code 4027 / tool call failed`：

```
Code 4027: tool call failed: Messages with role 'tool' must be a response to a
preceding message with 'tool_calls'
Code 4027: tool call failed: insufficient tool messages following tool_calls message
```

严格的后端（实测 DeepSeek 全系；Doubao / GLM 这类宽松后端照样能答，所以这个坑藏得很深）要求：
每条 `role: "tool"` 前面必须紧跟着声明了它的 assistant 消息，且那条 assistant 消息**声明几个
调用就要跟几条结果**。实测（`python3 tools/probe_tool_history.py --model DeepSeek-V4-Flash-Official`）
四种破法，全部已修：

| 破法 | 上游反应 | 现在怎么做 |
|---|---|---|
| `tool_calls[].function`（OpenAI 写法） | 整条 assistant 被当成没有工具调用 → 后面的 tool 变孤儿 → 4027 | 改写成上游自己的 `function_call` 写法 |
| 并行调用被拆成多条 assistant 消息（Responses 的 `input` 里每个 `function_call` 一项） | `insufficient tool messages` → 4027 | 相邻的调用项合并回**一条** assistant 消息 |
| 工具结果的调用已经不在上下文里（压缩过、续的旧会话） | 4027 | 降级成一条 user 消息（`[result of an earlier … call]`），内容不丢 |
| 声明了调用但没有结果（客户端打断） | `insufficient tool messages` → 4027 | 该调用折叠成 assistant 正文里的 `[called tool …]`，其余调用照常 |

Codex 的 shell / apply_patch 调用未必写成 `function_call`：也可能是 `local_shell_call` 或
`custom_tool_call`。这些以前被整项丢掉，而它们的结果（`function_call_output` /
`custom_tool_call_output`）留着 —— 又是一个孤儿。现在三种调用项都会翻译。

**顺带一个实测坑**：上游要求图片**每边至少 14 像素**，更小的直接整轮 `3003` 失败
（`Image dimensions are too small. Minimum allowed dimension: 14 pixels`）。而且图片一旦进了
历史，之后每一轮都会再发一遍——所以一张不合规的小图能让整段对话从此全空。正常截图不受影响，
实测 64×64 的 PNG 在 Doubao / GLM-5V / Kimi 上都正常。

**并不是每个模型都能收图。** `GET /v1/models` 的 `multimodal` 字段现在说的是实话：GLM-5.3、
GLM-5.2/5.1、DeepSeek 全系、MiniMax-M2.7 是纯文本的，发图片过去上游会拒。带图片的请求打到
这些模型上，代理直接回 `400 unsupported_content` 并列出能收图的模型，不再浪费两次重试。
`multimodal` 的唯一可信来源是 IDE 缓存的那张表——`traecli debug models` 给**每个**模型都报
`input_modalities: ["text","image"]`，那是 Codex fork 里的一个常量，不是能力。

**上游错误按标准状态码返回。** Trae 自己那个 `{"code": 3003, ...}` 客户端看不懂，现在映射成
每个 OpenAI / Anthropic 客户端都认的东西，而且是**真的 HTTP 状态码**：第一个 token 之前的
拒绝会在 SSE 开始前抛出来，不再是 200 里塞一个 error 帧。

| 上游 | HTTP | OpenAI `error.type` / `code` | Anthropic `error.type` |
|---|---|---|---|
| 原因里带 `status code: 4xx`（供应商读了请求并拒绝） | `400` | `invalid_request_error` / `upstream_rejected_request` | `invalid_request_error` |
| 原因里带 `status code: 429` | `429` | `rate_limit_error` / `rate_limit_exceeded` | `rate_limit_error` |
| 原因里带 `status code: 5xx` | `503` | `server_error` / `service_unavailable` | `overloaded_error` |
| `3003` + `rate limited` / `quota exceeded` | `429` | `rate_limit_error` / `rate_limit_exceeded` | `rate_limit_error` |
| `3003` 其他（`model service is unavailable`、`all models failed`） | `503` | `server_error` / `service_unavailable` | `overloaded_error` |
| `4001`（请求本身非法） | `400` | `invalid_request_error` / `upstream_rejected_request` | `invalid_request_error` |
| 空轮（重试完仍无 output） | `503` | `server_error` / `empty_turn` | `overloaded_error` |
| 其他 | `502` | `server_error` / `upstream_error` | `api_error` |

判定只看**人类可读的那段原因**（`message` / `error` / `model_call_chain[].error`），不看整个
JSON——上游有 `quota_type`、十六进制 request id 这类字段，整包做子串匹配会把「模型不可用」
误判成 429。

**供应商自己报的状态码优先于 Trae 的措辞。** Trae 会在每条 `model_call_chain[].error` 前面
统一贴一句 `model QPM/TPM rate limited`，哪怕真实原因完全不是限流——比如把图片发给纯文本
模型，回来的是
`model QPM/TPM rate limited\nerror, status code: 400, message: 1210:messages.content.type 参数非法，取值范围 ['text']`。
只按措辞判就是个假 429，还会被当成可重试的错误白等两轮。所以只要原因里能抠出
`status code: NNN`，就以那个码为准，4xx（429 除外）也不再重试。

重试完还是空，就**按上游错误报**（不再伪装成一个空的成功回答），日志里能看到：

```
direct turn produced no output and no error after 2 attempt(s) (model=... session=...)
direct turn ended empty (model=... session=... finish_reason=stop)
```

另外，卡住不动而不是空轮的情况，多半是上游 POST 完就不出声了。以前的读超时是 `None`
（永远等），现在默认 300 秒静默判死（`TRAE2API_DIRECT_READ_TIMEOUT`，收到任何字节就重置）。

---

## 文本形式的工具调用：还原成 `tool_calls`

`direct` 模式下客户端的 `tools` 是真透传的，大多数时候上游也确实回标准 `tool_calls`。
但**不是每次**——模型有时候会掉回它训练时学的 XML 语法，把工具调用当**正文**吐出来：

```xml
<tool_calls>
<invoke name="shell">
<parameter name="command">find . -maxdepth 3 -type f | sort</parameter>
</invoke>
</tool_calls>
```

客户端收到的是一段文字，不会去执行，也就不会有 tool result 回来，模型于是继续写——
这正是[输出兜底](#输出兜底截断与重复塌缩)那一节要拦的塌缩路径的入口。

所以代理在流里嗅探这个语法（[`text_tool_calls.py`](trae2api/text_tool_calls.py)）：

- 每个 `<invoke>` 块一闭合就转成标准 OpenAI `tool_calls` 发出去，**不破坏逐 token 流式**；
  `<tool_calls>` 外壳直接丢掉，这段 XML 不会出现在正文里
- 参数按**客户端自己的 JSON schema** 转类型：`<parameter name="timeout">30</parameter>` +
  schema 里 `integer` → `30` 而不是 `"30"`；`boolean` / `array` / `object` 同理，其余按字符串
- 标记跨 delta 被切开也认（`<invo` + `ke name=...`），块没闭合就当普通文本原样放出，不吞内容
- `finish_reason` 相应变成 `tool_calls`；Responses 那边出的是标准 `function_call` 输出项
- 默认只还原**客户端真正声明过的工具名**（`known`）。模型自己编的名字（实测它会编
  `list_files`、`execute_command`）保持原样当文本 —— 给客户端一个它没定义过的工具调用是另一种坏。
  想全都转：`TRAE2API_DIRECT_TEXT_TOOL_CALLS=all`；想关掉：`off`
- 原生 `tool_calls` 和还原出来的调用共存时，index 不会撞车（上游 index 会重映射到本地槽位）

实测（同一句话强制模型把调用写进正文）：

```
finish_reason: tool_calls
content:       "\n\n"
tool_calls:    [{"id":"call_c65e…","type":"function","function":
                {"name":"shell","arguments":"{\"command\": \"ls -la /tmp\", \"timeout\": 30}"}}]
```

日志里对应一行 `recovered N tool call(s) written as text`。要是看到它频繁出现，说明这个模型
在你的工具集下经常降级，值得把提示词或工具描述调一调。

---

## 关于「流式」的实话

`agent` 模式走的是 traecli 的 app-server 通道：

| | `traecli exec --json` | `traecli app-server`（本项目 agent 模式） |
|---|---|---|
| 思考过程 | ❌ 整块一次性给 | ✅ **逐 token 流式** |
| 正文 | ❌ 整块 | ⚠️ 见下 |
| 冷启动 | 每请求 1~3 秒 | 常驻进程，无冷启动 |

**实测结论**：走 app-server 时，Trae 后端把 **reasoning 逐 token 推**，但**最终答案是一整块下发的**
（一篇 400 字散文 = 1 个 delta）。这是上游行为，不是本代理在缓冲 —— 用裸 JSON-RPC 直连
app-server 得到同样结果。

所以 `agent` 模式下：
- **思考过程是真流式**，客户端能看到它一个字一个字出来；
- **正文默认一次到位**。想要打字机效果，设 `TRAE2API_CHUNK_CHARS=24`（配合
  `TRAE2API_CHUNK_DELAY_MS=15`）把已经拿到的文本重新切片。这是**纯视觉效果**，
  不会让上游真的变成流式。

`direct` 模式没有这个问题，正文本身就是逐 token 下发的。

---

## 配置

全部见 [`.env.example`](.env.example)。最常用的几个：

| 变量 | 默认 | 说明 |
|---|---|---|
| `TRAE2API_UPSTREAM` | `direct` | `direct` / `agent`，见开头那张表 |
| `TRAE2API_API_KEY` | 无 | 单 key 模式。与下面二选一，否则拒绝启动 |
| `TRAE2API_KEYS_FILE` | 无 | 多 key JSON 文件，**多项目推荐** |
| `TRAE2API_KEYS` | 无 | 多 key 内联 JSON |
| `TRAE2API_HOST` / `TRAE2API_PORT` | `127.0.0.1` / `8787` | 监听地址 |
| `TRAE2API_DEFAULT_MODEL` | `DeepSeek-V4-Flash 正式版` | 请求没带 `model` 时用它 |
| `TRAE2API_MAX_CONCURRENCY` | `4` | 并发上限 |
| `TRAE2API_REASONING_SOURCE` | `text` | `text` / `summary` / `both` |
| `TRAE2API_LOG_PROMPTS` | `0` | 日志里带一小段 prompt 提示，用于区分子任务 |

仅 `agent` 模式生效：

| 变量 | 默认 | 说明 |
|---|---|---|
| `TRAE2API_ALLOWED_ROOTS` | 空 | cwd 白名单，冒号分隔；空 = 禁止调用方指定 cwd |
| `TRAE2API_DEFAULT_CWD` | 空 | 客户端没传 cwd 时的默认工作目录 |
| `TRAE2API_CWD_FROM_REQUEST` | `1` | 从 prompt 的 `<cwd>` 自动识别工作目录 |
| `TRAE2API_CWD_MAP` | 空 | 宿主机路径→容器路径，`/host=/container` 逗号分隔 |
| `TRAE2API_SCRATCH_DIR` | `~/.cache/trae2api/scratch` | 无 cwd 请求用的固定 scratch 池 |
| `TRAE2API_SANDBOX` | `workspace-write` | 沙箱模式 |
| `TRAE2API_ALLOW_FULL_ACCESS` | `0` | 允许 `danger-full-access` |
| `TRAE2API_IGNORE_CLIENT_TOOLS` | `1` | 接受并忽略客户端的 `tools` |
| `TRAE2API_ALLOW_REMOTE_IMAGES` | `0` | 允许 `image_url` 传 http(s) 链接 |
| `TRAE2API_CHUNK_CHARS` | `0` | >0 时把正文切片做打字机效果 |
| `TRAE2API_TIMEOUT` | `600` | 单请求超时秒数 |
| `TRAE2API_EXPOSE_TOOL_EVENTS` | `0` | 把命令执行/文件改动作为 `trae_item` 扩展字段吐出来 |

仅 `direct` 模式生效：

| 变量 | 默认 | 说明 |
|---|---|---|
| `TRAE2API_DIRECT_URL` | 从 `auth.json` 推导 | 覆盖上游端点 |
| `TRAE2API_DIRECT_HEADERS` | 空 | 追加身份头，`Name: value` 逗号分隔 |
| `TRAE2API_DIRECT_ORIGINATOR` | `codex_exec` | `originator` 请求头 |
| `TRAE2API_DIRECT_USER_AGENT` | 按 CLI 版本生成 | `User-Agent` 请求头 |
| `TRAE2API_DIRECT_MAX_OUTPUT_TOKENS` | `0` | 每轮输出 token 硬顶，`0` 不限；见下节 |
| `TRAE2API_DIRECT_LOOP_GUARD_CHARS` | `600` | 重复塌缩截断阈值，`0` 关闭 |
| `TRAE2API_DIRECT_ENFORCE_MAX_TOKENS` | `1` | 是否执行客户端传来的 `max_tokens` |
| `TRAE2API_DIRECT_TEXT_TOOL_CALLS` | `known` | 把写成文本的 XML 工具调用还原成 `tool_calls`；`known`/`all`/`off` |
| `TRAE2API_DIRECT_EMPTY_RETRIES` | `1` | 上游返回空轮（一个 output 事件都没有）时重发几次，`0` 不重发 |
| `TRAE2API_DIRECT_READ_TIMEOUT` | `300` | 上游流静默多少秒判死；不是整轮超时，收到任何字节就重置，`0` 关闭 |

---

## 不支持 / 已知限制

**两种模式都有：**

- **`response_format` / 结构化输出**：`agent` 模式下 app-server 的 `turn/start` 没有 output-schema
  字段（`traecli exec` 有 `--output-schema`，但那条路没有流式 thinking）；`direct` 模式下该字段被静默忽略。
- **采样参数**：`temperature`、`top_p`、`stop`、`seed`、`logprobs` 等一律**静默忽略**
  —— traecli 和私有端点都不暴露这些旋钮。唯一例外是 `direct` 模式的 `max_tokens` /
  `max_output_tokens`：上游同样不认，但代理会自己数着截断，见
  [输出兜底](#输出兜底截断与重复塌缩)。
- **多轮是无状态的**：每次请求把整个对话拍平重发，不存服务端会话。`previous_response_id` 返回 400。
- **`/v1/completions`、`/v1/embeddings`**：不实现。
- **Anthropic 的 prompt caching**（`cache_control`）：字段被忽略。`usage` 里
  `cache_read_input_tokens` 是上游真实的缓存命中数，`cache_creation_input_tokens` 恒为 0
  —— 我们不往 Trae 的缓存里写。
- **Anthropic 的服务端工具**（`web_search`、`computer` 等没有 `input_schema` 的）：
  丢弃并打 warning，因为这边执行不了；给客户端一个跑不动的工具只会让它一直等结果。
- **Anthropic 的 `thinking` block 没有 `signature`**：本代理不签名，签名字段是空串。
  回填到本代理没问题（历史里的 thinking 一律丢弃），但别拿去喂真的 Anthropic API。

**仅 `agent` 模式：**

- **OpenAI function calling**：默认接受并忽略，客户端永远收不到 `function_call`。
  要真的 function call 就切 `direct`。
- **`n > 1`**：400。
- **远程图片 URL**：默认不透传，因为那会让 traecli 去抓调用方给的任意 URL。
  `data:` URI 永远可用；开 `TRAE2API_ALLOW_REMOTE_IMAGES=1` 才放行 http(s)。
- 每轮约 22k~27k 输入 token 的系统提示，但绝大部分命中缓存（`cached_tokens`）。

**仅 `direct` 模式：**

- **`n > 1`、`response_format`、`tool_choice` 不会报错**，只是被忽略 —— 这条路不做请求校验，
  参数直接透传给私有端点，而它只认 `tools` 本身。
- **`TRAE2API_TIMEOUT` 不生效**：上游是长连 SSE，读超时不设限。截断只由
  [输出兜底](#输出兜底截断与重复塌缩) 那两道闸负责。
- **并发满了会排队而不是 429**：`agent` 模式等 5 秒就返回 429，`direct` 模式一直等。
- **图片 URL 原样透传**，`TRAE2API_ALLOW_REMOTE_IMAGES` 在这条路上不参与。
- **端点未公开**，后端改协议就会断。

---

## 结构

```
trae2api/
  app.py            FastAPI 路由、鉴权、SSE、请求参数解析
  config.py         环境变量 → Settings、Principal(多 key)、启动期安全校验
  schemas.py        OpenAI 请求/响应的 pydantic 模型 + trae_* 扩展字段
  models_api.py     模型目录(model/list → models_cache.json → traecli debug models)
                    同时产出 direct 模式要的 (config_name, model_name) 映射
  translate.py      messages ↔ UserInput[]、通知 ↔ OpenAI chunk、usage 换算
  responses_api.py  /v1/responses 请求解析 + SSE 事件序列(两种模式共用)
  anthropic_api.py  /v1/messages 请求翻译 + SSE 事件序列 + stop_sequences(两种模式共用)

  # agent 模式
  rpc.py            app-server 子进程 + JSON-RPC 多路复用、审批兜底、崩溃重启
  session.py        单请求 thread/turn 生命周期、按 key 的 cwd 校验、并发闸门
  scratch.py        固定 scratch 目录池(防 traecli.toml 无限膨胀)
  cwd_detect.py     从 prompt 提取 <cwd> + 宿主机→容器路径映射

  # direct 模式
  direct.py         私有端点的认证、SSE 解码、tool_calls 重组、长度/重复塌缩兜底
  direct_routes.py  三套协议 ↔ 私有格式的请求/响应翻译
  text_tool_calls.py 把写成正文的 XML 工具调用还原成标准 tool_calls
docker/
  install-traecli.sh   从官方 CDN 装 Linux 版 traecli(校验 sha256 + ELF 架构)
  entrypoint.sh        凭据引导(挂载 or PAT 登录)
tools/
  smoke_test.py            端到端冒烟测试
  verify_direct.py         验证直连模式能否连通上游 + 工具透传
  capture_upstream.py      录制 traecli 发给后端的真实请求
  prune_trust_entries.py   清理 traecli.toml 里的死条目
  probe_appserver.py       app-server 协议调试脚本
```

跑测试：

```bash
./.venv/bin/python -m unittest discover -s tests -t .
```

调试用：导出 app-server 完整协议 schema

```bash
traecli app-server generate-json-schema --out /tmp/trae-schema
```