Generated by Answer me with HTML 0.5.10 · 2026-11-19 16:15 · ★ Star on GitHub

看懂 TRAE 评测:IDE、CLI 与 cmd-forward

用一道题,拆开发问、执行结束与评分。

日期2026-11-19代码基线commercial cdab772be · runtime d7c712a5

IDE 和 CLI 共用平台、评分与回写。区别在于怎样给 TRAE 发题,以及怎样取回结果。

A

先认清三个角色

cmd-forward 的一句话定义

cmd-forward 是一个 VSIX 插件。VSIX 就是 IDE 的插件安装包。 它把“给 TRAE 聊天发消息”变成 HTTP 接口。 Runtime 通过这个接口发题,无需在聊天框里打字。

角色 用日常话理解 负责什么
Commercial 平台 组织评测的人 选题、选 Agent、安排资源、接收结果
Orchestrator 一道题的指挥员 控制轮次、安排评分、回写结果
Runner 工作区里的执行员 安装和驱动 TRAE、收集文件与轨迹

Orchestrator 和 Runner 都属于 Runtime 仓库。 TRAE 自身解题逻辑来自另行安装的 IDE 或 CLI 包。

B

IDE 和 CLI,到底差在哪里?

对比项 TRAE IDE TRAE CLI
被测对象 有桌面窗口的 TRAE 无需桌面的命令行进程
本页的运行形态 Mac VM + Linux 工作区 + Orchestrator 常规双沙箱:Agent 工作区 + Orchestrator
代码在哪里改 Linux 工作区 Linux 工作区
怎么发题 给 cmd-forward 发 HTTP 请求 启动进程,传入 prompt
怎么看一轮是否结束 查 TRAE 结果库 看进程结果与原生事件
怎么拿回答 从数据库提取 summary 读事件流或最后回答文件
是否使用 cmd-forward 是 否
后续如何评分 共用 Runtime 评分框架 共用 Runtime 评分框架

本页 IDE 指 agent_id=trae 的 Remote-SSH 路径。 其他桌面拓扑不在这个三资源示例中。 CLI 的三个具体适配器见 G。

Linux沙箱Mac虚拟机HTTP 调用 RunnerRemote-SSH 连接项目远程项目与终端能力OrchestratorLinux工作区Mac上的TRAE

Runner 在 Linux;Mac VM 承载桌面 IDE。 源码:平台准备三资源,入口 asyncExecuteRemoteSSHIDE,约 2746 行。

C

跟着一道题,看懂 casefile

casefile 是整道题的执行说明书

平台把题面、Agent 配置、跑法和机器连接信息合在一起。 Runtime 读取这个 JSON,才知道该怎样执行和回写。 它是平台编排后的输出,不是用户最初填写的表单。

平台整理题目与配置casefile执行说明书Orchestrator读取Runner安装与驱动TRAE评分并回写平台

教学题目:修复 sum_items([]) 报错,并运行测试。 下面采用 agent_id=trae 的 Remote-SSH IDE 形态。 编号是教学示例;域名和密钥都是占位值。 本例未填真实资源,不能直接运行。

查看完整 JSON

先看字段视图。 为了阅读,只把两段长脚本缩写成占位说明。 下载文件中包含完整脚本;它们也在下方展开。

TRAE IDE casefile · 字段视图,脚本已缩写json
{  "space_id": "10001",  "expt_id": "20001",  "expt_group_key": "20001",  "invoke_id": "30001",  "run_id": "30001",  "data_set_id": "40001",  "data_set_key": "sum-empty-demo",  "experiment_info": {"run_mode": 1, "max_turns": 1, "evaluator_trigger": "final_turn_only"},  "agent": {    "agent_id": "trae",    "agent_version": "<TRAE_BUILD_VERSION>",    "model_name": "<MODEL_VISIBLE_TO_TRAE_ACCOUNT>",    "trae_package_url": "https://assets.example.invalid/Trae_CN.dmg",    "trae_agent_mode": "agent",    "enable_plan_mode": "false"  },  "dataset_item": {    "item_key": "sum-empty-demo-001",    "query": "修复 sum_items([]) 报错的问题,并运行测试。",    "workspace_path": "/workspace/demo",    "image": "registry.example.invalid/eval/python-ssh:demo",    "setup_script": "<准备脚本,见下方>",    "evaluator_conf": {"total_score_type": "avg", "isolation": "host", "pass_threshold": 1, "evaluators": [{"evaluator_type": "script", "evaluator_key": "sum-empty-tests", "max_eval_minutes": 1, "script": "<评分脚本,见下方>"}]},    "artifacts_conf": {"collectors": [{"type": "git_diff"}]}  },  "runner_protocol": "http",  "sandbox_topology": "separate",  "runner_session_id": "<RUNNER_SANDBOX_SESSION>",  "orchestrator_session_id": "<ORCHESTRATOR_SANDBOX_SESSION>",  "runner_server_endpoint": "https://runner.example.invalid/",  "runner_auth_token": "<RUNNER_AUTH_TOKEN>",  "remote_topology": {    "mac_vm": {"aic_cluster": "<AIC_CLUSTER>", "emulator": "<LEASED_MAC_ID>", "aic_ak": "<AIC_AK>", "aic_sk": "<AIC_SK>"},    "ssh_target": {"host": "ssh.example.invalid", "port": "2222", "user": "root"}  }}

按组看字段:

① 这次执行归谁:顶层身份字段

字段 本例类型或值 含义
space_id string 结果回写到哪个平台空间。
expt_id string 这次实验的编号。
expt_group_key string 分析与 Trace 使用的实验组标识。
invoke_id string 本次目标调用编号,用于结果回调。
run_id string 本平台链路中与 invoke_id 相同。
data_set_id string 题集编号。
data_set_key string 题集的 key;不是版本号。

② 怎么跑:experiment_info

以下字段都在 experiment_info 对象内。

字段 本例类型或值 含义
run_mode 整数 1 1 表示单轮用户输入。
max_turns 整数 1 最多问 Agent 一轮。
evaluator_trigger final_turn_only 最后一轮完成后评分。

③ 用哪个 TRAE:agent

以下字段都在 agent 对象内。

字段 本例类型或值 含义
agent_id 字符串 trae 选择 TRAE IDE 适配器。
agent_version 字符串占位 平台记录的 Agent 版本。
model_name 字符串占位 TRAE 账号能使用的模型名。
trae_package_url URL 占位 Mac VM 要安装的 TRAE 包。
trae_agent_mode 字符串 agent 选择 TRAE 的 Agent 模式。
enable_plan_mode 字符串 false 关闭计划模式。

④ 题目与环境:dataset_item

以下字段都在 dataset_item 对象内。

字段 本例类型或值 含义
item_key string 这道题的稳定标识。
query string 真正发给 TRAE 的题面。
workspace_path Linux 路径 Agent 修改代码的工作目录。
image 镜像占位 平台用于准备 Linux 工作区的镜像。
setup_script 脚本文本 发题前准备文件与依赖。
evaluator_conf object 这道题的评分配置,见下一组。
artifacts_conf object 结束后收集什么产物。

⑤ 怎么判对错:dataset_item.evaluator_conf

下面解释评分配置及 evaluators 数组。

字段 本例类型或值 含义
total_score_type avg 多个评估器分数取平均。
isolation host 在 Agent 所在的 Linux 沙箱评分。
pass_threshold 数字 1 本例轮分达到 1 才算达标。
evaluators array 本题需要执行的评估器列表。
evaluators[].evaluator_type script 使用脚本评分。
evaluators[].evaluator_key sum-empty-tests 这个评估器的稳定名字。
evaluators[].max_eval_minutes 数字 1 这个评估器最多运行一分钟。
evaluators[].script 脚本文本 检查代码,并写出评分 JSON。

⑥ 收什么产物:dataset_item.artifacts_conf

下面是本例唯一的收集器。

字段 本例类型或值 含义
collectors array 产物收集器列表。
collectors[].type git_diff 保存 Agent 对代码的修改。

⑦ 指挥员怎么找执行员:顶层 Runner 字段

这些字段供 Orchestrator 连接 Linux Runner。

字段 本例类型或值 含义
runner_protocol http Orchestrator 与 Runner 使用 HTTP。
sandbox_topology separate Orchestrator 与 Runner 分箱。
runner_session_id 资源编号占位 Runner 所在 Linux 沙箱的会话。
orchestrator_session_id 资源编号占位 主调度沙箱的会话。
runner_server_endpoint URL 占位 Orchestrator 调用 Runner 的地址。
runner_auth_token 令牌占位 调用 Runner 时使用的 Bearer token。

⑧ IDE 怎样连上工作区:remote_topology

下面两组都是平台提供的连接信息。

字段 本例类型或值 含义
mac_vm object 定位 Mac VM,并提供控制凭据。
mac_vm.aic_cluster 字符串占位 Mac VM 所在的 AIC 集群。
mac_vm.emulator 字符串占位 租用的 Mac VM 编号。
mac_vm.aic_ak 凭据占位 AIC 控制凭据 AK。
mac_vm.aic_sk 凭据占位 AIC 控制凭据 SK。
ssh_target object Mac IDE 要连接的 Linux SSH 入口。
ssh_target.host 主机占位 平台暴露的 Linux SSH 地址。
ssh_target.port 字符串 2222 平台暴露的 SSH 端口。
ssh_target.user root SSH 登录用户。
四个容易填错的地方

agent 是字符串字典,要写 "false"。 run_mode 则是整数,要写 1。 SSH 的 port 在当前类型中也是字符串。 sandbox_topology 写 separate,不写 mac_vm_plus_ssh。

一轮指向 Agent 发问一次。 这个轮数不限制 Agent 内部调用模型与工具的次数。 agent_version 不会自动推导安装包地址。 实际安装哪个构建,由 trae_package_url 决定。

run_id 在本平台路径中等于 invoke_id。 它不是平台的 ExptRunID,也不是 TRAE 聊天编号。 聊天编号要等 cmd-forward 发问后才会产生。

平台会注入资源地址和控制凭据。 真实回写还需要空间身份;归档另有凭据配置。 本例没有展示全部生产字段。

两段脚本具体干什么?

准备脚本先放入一个有 Bug 的函数。 它在空数组时会访问不存在的第一个元素。

trae-casefile-setup.sh:1-7bash
#!/usr/bin/env bashset -euo pipefailmkdir -p /workspace/democat > /workspace/demo/math_utils.py <<'EXAMPLE_SOLUTION'def sum_items(items):    return items[0] + sum(items[1:])EXAMPLE_SOLUTION

评分脚本检查空数组、正常求和与负数。 然后把 score 和 reason 写到 Runtime 指定的位置。 本例用 0 与 1 表示测试未通过或全部通过。

trae-casefile-evaluator.py:1-20python
import importlib.utilimport jsonimport osfrom pathlib import Pathcontext = json.loads(Path(os.environ['FORNAX_EVAL_CONTEXT_FILE']).read_text())score, reason = 0, 'checks have not passed'try:    spec = importlib.util.spec_from_file_location('submission', 'math_utils.py')    submission = importlib.util.module_from_spec(spec)    spec.loader.exec_module(submission)    assert submission.sum_items([]) == 0, 'empty list must return zero'    assert submission.sum_items([1, 2, 3]) == 6, 'normal sum changed'    assert submission.sum_items([-2, 2]) == 0, 'negative values failed'    score, reason = 1, 'all three checks passed'except Exception as error:    reason = f'{type(error).__name__}: {error}'output = Path(context['output_json'])output.parent.mkdir(parents=True, exist_ok=True)output.write_text(json.dumps({'score': score, 'reason': reason}))

评分脚本从 FORNAX_EVAL_CONTEXT_FILE 读取上下文。 其中的 output_json 指定评分文件的写入位置。 只打印分数到终端,不能替代写入这个文件。

全部断言通过时的评分结果json
{"score": 1, "reason": "all three checks passed"}

casefile 怎样变成 cmd-forward 请求?

casefile 中的配置 运行时变成什么
dataset_item.query E 节请求的 args[0][0]
agent.model_name 发问配置里的 modelName
agent.trae_agent_mode 映射成 agentName,如 Agent
agent.enable_plan_mode 转成布尔值 enablePlanMode
dataset_item.workspace_path 生成 IDE 项目 alias,再放进 workspaceFolder
runner_server_endpoint Orchestrator 找 Runner 的地址

两个地址承担不同工作。 runner_server_endpoint 连接 Orchestrator 与 Runner。 cmd-forward 的 127.0.0.1:16259 则由 Linux Runner 调用。 后者是适配器内置的地址,不是前者的替代值。

源码:casefile 定义与解析 38、443 行;题目与评分字段 119、199 行;Mac/SSH 字段类型 142 行。 平台身份赋值见 buildCaseFile 659 行。

D

放大看:cmd-forward 是什么?

把它想成给 IDE 发消息的“收件窗口”。 Runtime 用 HTTP 把题目交进去。

Linux工作区沙箱本机 HTTP 请求请求发送题目Runner执行员cmd-forward插件TRAE聊天命令
你可能想问 具体答案
它是什么? 一个服务端 VSIX 插件,提供 HTTP 入口
装在哪? Linux 的 TRAE Remote-SSH server 扩展目录
谁请求它? 同在 Linux 工作区里的 Runtime 适配器
请求哪个地址? http://127.0.0.1:16259/vscode/commands/executeCommand
它收到什么? 项目路径、内部命令名、prompt 和会话选项
这里的 command 是什么? 本次调用的是 IDE 的聊天发送命令
为什么还要打开 Mac IDE? IDE 连接项目后,服务端扩展才能激活

executeCommand 的命令来自 IDE 命令系统。 本链路用它把题面送入聊天。 TRAE 随后自行选择工具、修改代码并运行终端命令。

127.0.0.1 指调用方所在的机器。 这里是远端 Linux,不是你手边的 Mac。 SSH 负责连接工作区;cmd-forward 负责程序化发聊天消息。

源码:插件安装说明 3 行;HTTP 地址与命令名 98 行。

E

发出去的 HTTP 请求长什么样?

这是首次发问的示意请求,未执行网络调用。 尖括号表示本次实验需要提供的值。

首次发问 · 示意请求json
{  "workspaceFolder": "<IDE当前打开的项目路径>",  "command": "workbench.action.chat.icube.send.internal",  "args": [    ["修复 sum_items([]) 报错的问题,并运行测试。"],    {      "newSession": true,      "agentName": "Agent",      "enablePlanMode": false,      "modelName": "<已注册模型名>",      "sessionId": null    }  ]}
字段 把它读成一句话
workspaceFolder 请在这个已打开的项目中工作
command 请调用 TRAE 内部的聊天发送命令
args[0] 这是要发给 Agent 的题目
args[1] 这是本次发问的配置
newSession 第一轮开新聊天;后续轮次继续旧聊天
agentName / modelName 选择 Agent 模式和模型
sessionId 指定继续哪段聊天;第一轮为 null

两层数组只是一种参数格式,不代表发问两次。 可以把 args 读成:[题目数组, 配置对象]。

响应示意:

接收响应 · 示意值json
{  "code": 0,  "data": {    "sessionId": "sid-demo"  }}
sid-demo 是聊天编号

它像一张取件单,用来找到后续结果。 它不是最终回答,也不是评分。 HTTP 响应有时较晚返回;Runtime 仍会查结果库。

源码:sendPayload 1178 行。

F

拿到聊天编号后,怎么知道做完了?

结果库可以理解为 TRAE 会话的“进度账本”。 Runner 按聊天编号和轮次查账,不随便拿最新一条记录。

Runnercmd-forwardTRAE会话结果库发题POST 题目和配置1请求执行聊天命令2code=0,sessionId=sid-demo3等待本轮记录执行状态与消息4查询 sid-demo 的第1轮5尚未结束,继续等待6写入终态、回答与工具记录7再查同一聊天、同一轮8本轮状态、summary 与轨迹9

Runner 在 Linux 读取加密的 SQLite 数据库。 读取前会一起快照 DB、WAL 和 SHM。 回答优先取 finish 工具的 params.summary。 之后 Orchestrator 收集产物,再按题目配置安排评分。

看到的信号 它能说明什么 还不能说明什么
code=0 且有 sessionId 发问被接收,有聊天编号 题目已经做完
turn_status=completed TRAE 自己判定这轮完成 修改满足测试要求
RoundScore.Passed=true 评分器判断达到题目标准 其他题目也会通过

进阶:普通 failed 也可能保留回答和产物去评分。 数据库读取错误或结构化网关错误走另一条错误路径。

源码:结果库读取 287 行;终态处理 1056 行。

G

同一道题,换成 CLI 怎么走?

CLI 不需要打开桌面,也不使用 cmd-forward。 Runner 启动进程,把同一题面交给命令行工具。 进程结束后,适配器整理出统一的回答和轨迹。

prompt 参数或标准输入修改代码与运行命令事件流、回答文件或 rollout统一 AgentOutput按题目配置评分Runner命令行进程题目工作区Orchestrator评分器
Runtime 注册 ID 核心命令形式,参数已省略 续聊与回答
traecli-custom trae-agent --prompt … --resume 续聊;读取 stream-json
trae-harness-cli harness-cli --session-id … run … 保持稳定 session ID;读取 trae-eval 事件
traex traex exec … exec resume 续聊;读取最后回答文件与 rollout

CLI 适配器还会检查原生结果事件。 因此不能只用进程退出码推断评分是否通过。 模型名相同,也要核对安装包、鉴权和路由配置。

源码:旧 CLI 449 行;Harness CLI 382 行;TraeCode CLI 161 行。

H

卡住时,先从哪里查?

现象 先检查什么 源码位置
IDE 没连上代码 三资源连接信息、Remote-SSH、sshd target_source_sandbox_agent_impl.go:2746
16259 连不上 插件是否安装,IDE 是否已连接并激活扩展 trae_vsix_install.sh:3;trae.go:524
发了题但没拿到编号 发问 HTTP 响应与请求参数 trae.go:792;trae.go:1178
有编号但一直等结果 session、轮次、数据库路径与终态 trae_chat_result.py:287
有回答却没分数 题目评估器和评分触发方式 orchestration.go:724
已出分但平台仍运行 invokeID 回调和异步上下文 reporter.go:336;eval_openapi_app.go:1335
任务卡在数据回流 应用 analysis 能力、空间开关、回流事件 eval_analysis_progress.go:156
编号 表示什么
invokeID 一次评测调用,用于回调平台
cmd-forward 的 sessionId TRAE 聊天编号,用于查本轮结果
沙箱资源的 session ID 运行环境编号,另有命名空间

本页说明调用方能确认的接口行为。 VSIX 内部 handler 和 TRAE 模型实现不在这两个仓库中。 本页未验证线上制品版本,也未发起真实评测。