Generated by Answer me with HTML 0.5.10 · 2026-11-19 16:15 · ★ Star on GitHub
看懂 TRAE 评测:IDE、CLI 与 cmd-forward
用一道题,拆开发问、执行结束与评分。
IDE 和 CLI 共用平台、评分与回写。区别在于怎样给 TRAE 发题,以及怎样取回结果。
先认清三个角色
cmd-forward 是一个 VSIX 插件。VSIX 就是 IDE 的插件安装包。 它把“给 TRAE 聊天发消息”变成 HTTP 接口。 Runtime 通过这个接口发题,无需在聊天框里打字。
| 角色 | 用日常话理解 | 负责什么 |
|---|---|---|
| Commercial 平台 | 组织评测的人 | 选题、选 Agent、安排资源、接收结果 |
| Orchestrator | 一道题的指挥员 | 控制轮次、安排评分、回写结果 |
| Runner | 工作区里的执行员 | 安装和驱动 TRAE、收集文件与轨迹 |
Orchestrator 和 Runner 都属于 Runtime 仓库。 TRAE 自身解题逻辑来自另行安装的 IDE 或 CLI 包。
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。
Runner 在 Linux;Mac VM 承载桌面 IDE。
源码:平台准备三资源,入口 asyncExecuteRemoteSSHIDE,约 2746 行。
跟着一道题,看懂 casefile
平台把题面、Agent 配置、跑法和机器连接信息合在一起。 Runtime 读取这个 JSON,才知道该怎样执行和回写。 它是平台编排后的输出,不是用户最初填写的表单。
教学题目:修复 sum_items([]) 报错,并运行测试。
下面采用 agent_id=trae 的 Remote-SSH IDE 形态。
编号是教学示例;域名和密钥都是占位值。
本例未填真实资源,不能直接运行。
先看字段视图。 为了阅读,只把两段长脚本缩写成占位说明。 下载文件中包含完整脚本;它们也在下方展开。
{ "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 的函数。 它在空数组时会访问不存在的第一个元素。
#!/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 表示测试未通过或全部通过。
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 指定评分文件的写入位置。
只打印分数到终端,不能替代写入这个文件。
{"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 行。
放大看:cmd-forward 是什么?
把它想成给 IDE 发消息的“收件窗口”。 Runtime 用 HTTP 把题目交进去。
| 你可能想问 | 具体答案 |
|---|---|
| 它是什么? | 一个服务端 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 行。
发出去的 HTTP 请求长什么样?
这是首次发问的示意请求,未执行网络调用。 尖括号表示本次实验需要提供的值。
{ "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 读成:[题目数组, 配置对象]。
响应示意:
{ "code": 0, "data": { "sessionId": "sid-demo" }}它像一张取件单,用来找到后续结果。 它不是最终回答,也不是评分。 HTTP 响应有时较晚返回;Runtime 仍会查结果库。
源码:sendPayload 1178 行。
拿到聊天编号后,怎么知道做完了?
结果库可以理解为 TRAE 会话的“进度账本”。 Runner 按聊天编号和轮次查账,不随便拿最新一条记录。
Runner 在 Linux 读取加密的 SQLite 数据库。
读取前会一起快照 DB、WAL 和 SHM。
回答优先取 finish 工具的 params.summary。
之后 Orchestrator 收集产物,再按题目配置安排评分。
| 看到的信号 | 它能说明什么 | 还不能说明什么 |
|---|---|---|
code=0 且有 sessionId |
发问被接收,有聊天编号 | 题目已经做完 |
turn_status=completed |
TRAE 自己判定这轮完成 | 修改满足测试要求 |
RoundScore.Passed=true |
评分器判断达到题目标准 | 其他题目也会通过 |
进阶:普通 failed 也可能保留回答和产物去评分。
数据库读取错误或结构化网关错误走另一条错误路径。
同一道题,换成 CLI 怎么走?
CLI 不需要打开桌面,也不使用 cmd-forward。 Runner 启动进程,把同一题面交给命令行工具。 进程结束后,适配器整理出统一的回答和轨迹。
| 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 行。
卡住时,先从哪里查?
| 现象 | 先检查什么 | 源码位置 |
|---|---|---|
| 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 模型实现不在这两个仓库中。 本页未验证线上制品版本,也未发起真实评测。