trajectory-explorer / src /explain.ts
xxxxxxk's picture
Trajectory explorer: overview, training, comparison, episode view, HF sign-in
028a5cd verified
Raw History Blame Contribute Delete
5.92 kB
// Plain-language explanations: what an orchestrator tool, a run state or an error message means.
// Error texts are the ones grow_gym / grow.graph return to the orchestrator; the rules behind them are in grow/graph.py.
import type { Episode } from "./types";
export const opHelp: Record<string, string> = {
graph_state: "查看任务图:看一眼当前所有子任务的状态、哪些可以开始。不改变任何东西。",
expand: "拆分:把一个可开始的子任务拆成几个更小的子任务,可以写它们之间的依赖。被拆的任务变成汇总步骤,等子任务都完成后再执行。",
assign: "指派:给一个可开始的子任务配一个子 agent。只有指派过的子任务才会被执行。",
exec: "执行:让所有已指派、可开始的子任务的子 agent 动手,依次在同一个仓库里改代码。",
retry: "重试:把一个失败的子任务重新打开,可附一句提示。",
prune: "剪枝:删掉一个还没执行的子任务,以及由它拆出来的所有子任务。",
link: "连边:给两个子任务之间加一条依赖,后者要等前者完成。",
stop: "结束:交卷。仓库的最终状态就是结果,所以只能在根任务上结束。",
};
export const stateHelp: Record<string, string> = {
accepted: "保留:改了文件,验收检查通过,改动留在仓库里。",
rejected: "撤销:改动让原本通过的仓库测试挂了,验收检查把它撤销了,仓库回到改之前。",
nochange: "无改动:这次运行没有改任何文件(比如只是在读代码、摸清结构)。",
failed: "失败:运行没有正常结束,例如超时、上下文超长。",
done: "完成:跑完了,但这条记录没有验收日志,不知道改动是否被保留(训练轨迹和较早的测评都是这样)。",
running: "运行中:回放时,这个子 agent 正在执行。",
};
const deps = (ep: Episode, n: string) => ep.graph?.nodes.find((x) => x.id === n)?.depends_on ?? [];
// One sentence in Chinese for an error the environment returned to the orchestrator; null when we do not know it.
export function explainError(error: string | null | undefined, ep: Episode): string | null {
if (!error) return null;
let m: RegExpMatchArray | null;
if ((m = error.match(/^(\w+): (\S+) is not on the frontier/))) {
const d = deps(ep, m[2]);
return `${m[2]} 现在还不能${m[1] === "assign" ? "指派" : "拆分"}:` + (d.length
? `它要等 ${d.join("、")} 先完成。只有依赖都已完成的待办子任务("可开始")才能拆分或指派。`
: `它已经开始或做完了,不再处于"可开始"状态。`);
}
if ((m = error.match(/^expand: (\S+) is already expanded/))) return `${m[1]} 已经拆分过了,不能再拆一次。`;
if ((m = error.match(/^(?:expand|assign): unknown node (\S+)/))) return `没有叫 ${m[1]} 的子任务(名字写错了)。`;
if ((m = error.match(/^prune: (\S+) is (fail|done), must be open/)))
return `只能删掉还没执行的子任务;${m[1]} 已经${m[2] === "fail" ? "执行失败了(想重做应该用「重试」)" : "完成了"}。`;
if (/^prune: cannot prune the root/.test(error)) return "不能删掉根任务(它就是整道题)。";
if (/frozen history/.test(error) && error.startsWith("prune")) return "它拆出来的子任务里已经有执行过的,执行过的历史不能删。";
if ((m = error.match(/^stop: node (\S+) is open, must be done/))) return `只能在已完成的任务上结束;${m[1]} 还没做完。`;
if ((m = error.match(/stop only on the root (\S+); not finished yet: (.*)$/)))
return `仓库的最终状态就是交卷结果,所以只能在根任务 ${m[1].replace(/[;,]$/, "")} 上结束,而且要等它做完;还没完成的有:${m[2]}。`;
if ((m = error.match(/^retry: (\S+) is (open|done), must be fail/)))
return `只能重试执行失败的子任务;${m[1]} ${m[2] === "open" ? "还没执行过" : "已经完成了"}。`;
if ((m = error.match(/subgraph edge (\S+)->(\S+) references unknown node/)))
return `拆分时写的依赖 ${m[1]} → ${m[2]} 里有子任务名对不上(多半是写错名字),整次拆分没有生效。`;
if (/malformed subgraph/.test(error)) return "拆分的参数格式不对,整次拆分没有生效。";
if (/subgraph has no nodes/.test(error)) return "拆分时一个子任务也没给。";
if (/subgraph self-loop/.test(error)) return "拆分里有子任务依赖它自己。";
if (/^link: edge already exists/.test(error)) return "这条依赖已经有了。";
if (/^link: would create a cycle/.test(error)) return "加上这条依赖会绕成一个环。";
if (/^link: unknown endpoint/.test(error)) return "依赖的两端有不存在的子任务。";
if (/^link: target .* must be open/.test(error)) return "只能给还没执行的子任务加依赖。";
if (/^exec: no executable node/.test(error)) return "现在没有可以执行的子任务:可开始的子任务要先「指派」给子 agent。";
return null;
}
// The same for why a sub-agent run failed or was undone.
export function explainFailure(failure: string | null | undefined): string | null {
if (!failure) return null;
let m: RegExpMatchArray | null;
if ((m = failure.match(/broke tests that passed before \(passed\/failed (\d+)\/(\d+) became (\d+)\/(\d+)\)/)))
return `验收检查撤销了这次改动:仓库原有测试从 ${m[1]} 个通过变成 ${m[3]} 个通过,有原本通过的测试被改挂了。`;
if (/maximum context length/.test(failure)) return "子 agent 的上下文超出模型长度上限,接口报错,这次没跑完。";
if (/^out of time/.test(failure)) return "时间用完了,这次没跑完。";
if (/^no final message/.test(failure)) return "子 agent 没有给出最终回报。";
return null;
}