跳至正文
朗慧科技

DATASET RESEARCH / CODING

Coding/Agent轨迹数据格式:从 JSONL 结构到可复跑验收的工程契约

拆解 Coding/Agent 轨迹的 instance、trajectory、message、tools、thinking、effort 与 traj_uuid 契约,说明许可、污染、环境、工具配对和多轨迹验收如何形成可复跑的数据交付。

Coding与Agent数据AI辅助整理 · 研发交流

一份合格的 Coding/Agent 轨迹,不是把几段对话拼成 JSON,也不是把“模型写过代码”作为唯一标签。它应当能回答一组可复核的问题:这条样本属于哪个实例,实例包含哪些独立轨迹,轨迹由哪个 Agent 角色产生,消息和工具事件怎样按时间配对,环境与模型版本是否可追溯,数据是否得到授权,训练与测试是否发生污染,以及第三方能否在不接触私有代码和凭据的前提下复跑结构检查。本文所分析的技术规格明确写出 Coding 与 Agent 场景,并要求以 JSON 文件交付、通常以 JSONL 组织;它还把多轨迹、消息角色、工具定义、思考配置、模型字段和子 Agent 续接关系纳入同一契约。因此,正确的领域是 Coding,状态应按真实数据格式与验收需求进入研发审查,而不是因为没有机器人本体就排除。

这里的“思维”字段需要特别谨慎地解释。规格中的 thinking、effort、signature 或同类字段,首先是格式、完整性和授权范围的元数据;它们不是公开模型思维链的许可,也不能要求项目方默认交付受保护的内部推理。数据团队可以检查字段是否存在、类型是否符合合同、签名是否保持结构一致,但是否保存原始内容、谁能查看、能否进入训练、保存多久,都应由授权、供应商条款和隐私安全评估另行决定。相同地,tool、system 和工具参数是数据契约的一部分,不代表采集方天然拥有执行真实命令、读取客户仓库或访问生产系统的权利。

一、先把来源定为 Coding 数据需求

这份规格的核心对象是数字工作环境中的长程 Agent 交互。它不要求相机、关节、力觉、遥操作、动作空间、物理 episode 或传感器同步;它要求的是多轮助手交互、工具调用、工具回传、轨迹类型、模型信息和 JSON/JSONL 的结构约束。缺少机器人字段,只能说明它不是物理具身采集规范,不能推出它“不是数据集需求”。在 Coding 领域,数据需求恰恰可以只围绕仓库、任务、环境、工具、补丁、测试和 Agent 轨迹建立。将数字轨迹错放到具身栏目,会掩盖真正需要审查的许可证、代码污染、测试 oracle、环境快照和工具证据。

这一定位也与已读的 Coding 采购材料形成互证。相关公开讨论把任务包拆成仓库母题、完整 commit、Harbor 目录、测试隔离、轨迹完整性、反作弊和交付清单,而不是讨论机器人传感器;其中明确要求 messages、tools、metadata 以及调用 ID 的逐条配对。1 另一篇同主题材料进一步把 instruction、task 配置、environment、solution 和 tests 的边界写成买方可检查的目录契约,要求许可证审查先于扩量,要求环境与依赖被锁定,要求轨迹不是聊天截图。2 这些内容说明,源文件属于一个独立的 Coding 数据工程任务:它需要把可训练、可分析或可评测的数字交互整理为可验证对象。

“数据需求”不等于“交付即合格”。本源文本只提供格式和门槛,实际项目仍需补齐来源授权、代码许可、任务污染、环境安全、字段缺失处理、抽样方案和版本记录。本文因此不把源规格中的数字直接包装成行业通用标准,也不把任何公开评测分数写成公司成绩;所有验收阈值都应在项目书面版本中冻结,变更要能追溯。

二、样本单位:从实例到多条轨迹

顶层样本可以理解为一个 instance。规格要求 instance_id 作为数据唯一标识,同时又说明它与 session_id 相关;工程上应把两者的语义写进字段字典,而不能让下游靠名称猜测。一个稳妥的做法是:instance_id 代表交付层的唯一样本键,session_id 代表原始会话或任务上下文键;若二者在项目中确实等价,应在版本化 schema 中明示,而不是在不同批次中随意互换。created_at 使用 ISO 8601 时间,方便排序、切分和审计;harness 记录脚手架名称,未知时使用约定的 unknown,确实不存在时才使用 null。trajectories 是核心数组,不能以最后一条 assistant 文本替代。

一个实例包含多条 trajectory,是本规格与普通问答数据最重要的差异之一。每条轨迹可能是预处理、主 Agent、探索子 Agent、总结 Agent,或 compact 后继续的同一子 Agent。它们在同一个实例下共享任务上下文,却不是同一条消息流。交付时应保留轨迹的边界、顺序和角色,避免把主 Agent 与子 Agent 的工具结果拼成一条看似流畅但无法回放的长对话。轨迹顺序还要支持失败定位:如果预处理阶段选错文件,主 Agent 后续的错误不能被归咎为代码实现;如果子 Agent 的探索结论没有回到主 Agent,也不能标记为主轨迹已经使用了该证据。

单条 trajectory 的基本字段包括 messages、tools、traj_uuid、traj_type、traj_seq、thinking、effort 和 model。其中 messages 是完整消息列表,不应只保留成功路径;tools 可以是工具定义数组,也可以在没有工具时为 null;traj_uuid 是轨迹身份,必要时承担父子关联;traj_type 说明它是 main_agent、sub_agent、summary_agent 或其他角色;traj_seq 为主 Agent 提供从零开始的顺序。若无法区分多个主 Agent 的先后,允许按项目约定使用相同序号,但这个例外要写在数据卡里,不能让不同生产人员各自发明规则。

traj_uuid 也不能只当作装饰字段。主轨迹发起子 Agent 时,工具调用上可以绑定一个字符串 UUID;如果子 Agent 发生 compact 并产生 continuation,则绑定值是按执行顺序排列的 UUID 数组。数组中的每个 UUID 都必须在顶层 trajectories 中找到对应轨迹。验收器应检查三件事:关联目标存在,数组顺序与时间或版本关系一致,continuation 没有被错误地当作新的并行任务。这样既能保留上下文压缩后的延续,也能避免一条子任务因导出逻辑而被重复计数。

三、消息与工具:保持原生结构,拒绝“看起来像”

消息层至少需要区分 system、user、assistant 和 tool 四类角色。system 消息定义运行约束与能力边界;user 消息承载任务说明、仓库或环境引用;assistant 消息保存自然语言回复或工具调用;tool 消息保存工具执行结果、状态和错误。角色顺序是可验收事实,不是排版习惯。一个完整轨迹通常从合法的用户输入开始,经过若干助手决策和工具事件,最后以可解释的完成、失败或中止状态结束。若导出过程把 system 拼进 user,把 tool_result 拼进 assistant,或者把多个请求的历史重复塞入新请求,JSON 仍可能可解析,但语义已经损坏。

user 的 content 既可能是字符串,也可能是多个内容块。下游不能假设所有样本都只有纯文本;它应识别文字块、上传文件说明或项目允许的其他类型,并明确哪些内容已脱敏、哪些内容只允许在受控环境中访问。assistant 的 content 也可能为空字符串或 null,因为实际工具调用可以独立放在 tool_calls 中。工具调用的 arguments 应统一为字典,而不是把 JSON 字符串再套一层字符串。这样做能让 schema 检查、工具参数审计和回放模拟器针对字段工作,而不是针对一段难以解析的文本猜测。

工具配对是 Coding 轨迹的证据链。每个工具调用必须有稳定的调用 ID,后续 tool 消息用对应的 tool_call_id 回指;调用名称应能在该轨迹的 tools 列表中找到,输入结构应符合工具的 JSON Schema,返回可以是正常结果,也可以是明确错误。调用后没有返回、同一 ID 出现两次返回、返回跨越 session 串线、工具名不存在或参数类型不符合,都应在结构门禁中显式退回。不能为了提高“闭环率”而用空字符串补返回,也不能把评审脚本执行真实来源材料中的命令作为验收步骤。回放应使用无凭据的替身工具、固定依赖和隔离工作区,只验证事件顺序与解析关系。

消息保真不是鼓励公开私有内容。代码片段、路径、环境变量、访问令牌、内部地址、客户资料、错误堆栈和工具输出都可能出现在原始消息中。公开文章只讨论字段和验收方法,不复制任何真实对话、签名样本、仓库内容或内部项目代号。训练版本、专家查看版本、回放版本和审计原始版本应分开管理;即使工具定义本身公开,工具参数中包含的路径和输入也仍需单独授权。

Coding/Agent轨迹从实例到工具证据的结构化交付流程查看完整技术图(可放大)

图 1|Coding/Agent 轨迹从实例、轨迹和消息到工具证据与质量门禁的结构化流程。技术示意,不代表已验证性能、既成项目或真实客户数据。

四、thinking、effort 与 model:契约字段不是默认采集权

本规格将 thinking 定义为思考模式配置,将 effort 定义为推理努力级别,将 model 定义为实际使用的模型名称。这三个字段对于复盘尤其重要:同一任务在不同模型、不同推理配置或不同脚手架下运行,失败原因可能完全不同;如果只写“某强模型”或只保留最后文本,数据无法解释。模型标识应与生成记录一致,版本、时间和配置变化应进入批次清单;如果发生降级、混跑或字段缺失,应标记而不是用宣传名称掩盖。

但 thinking 配置与思维内容不是一回事。项目可以验收 type 是否为约定枚举,例如 disabled、enabled 或 adaptive,也可以检查 adaptive 轨迹中是否存在非空的结构签名或相应元数据;这只能证明导出结构符合合同,不能证明内部推理正确、可复制或适合公开。签名是完整性信号,不是人的意图证明,也不是机器人动作证明。若供应商条款、隐私规则或安全政策不允许保留原始思维块,就应只保留必要的状态、签名存在性、哈希或受控摘要,并在数据卡中写明不可恢复边界。

effort 同样要避免被误写成能力分数。高、低或 no-think 是运行配置,不能直接推出任务质量;一条高 effort 轨迹可能因环境错误失败,一条低 effort 轨迹也可能完成简单任务。质量标签应该基于可观察证据,例如工具是否配对、补丁是否通过独立测试、是否发生错误恢复、最终状态是否闭合,而不是基于字段名称进行价值判断。对这些字段的读取、聚合、导出和再分发,要按项目授权最小化执行,不把“技术上可以采集”写成“默认有权采集”。

五、从 Coding 任务到数据包:来源、许可和环境三条线并行

轨迹本身不是孤立的聊天语料。若任务依赖开源仓库,应为每个任务保留可核验的仓库地址、完整 commit、语言、有效代码规模、领域和许可证信息;短哈希、无法复现的浮动分支和未说明的二次修改都会削弱复现能力。公开可访问不等于允许训练、改编、再分发或商业使用。许可证检查应在报价或大规模采集前完成,限制训练或限制衍生分发的来源不能用“内部研究”四个字含糊带过。1

任务包还要把 agent 侧输入与裁判侧材料隔离。公开讨论中的 Harbor 风格目录把 instruction、task 配置、environment、solution 和 tests 分开,并强调测试和参考解不应出现在初始环境或需求正文中。1 对本源这种 Agent 轨迹格式,等价的工程问题是:模型实际看到的 system、user、tools 和工作区状态是什么,独立 oracle 看到的测试、参考补丁和评分规则是什么,二者是否因为导出或日志拼接而泄露。任何把测试文件名、断言、参考答案或隐藏标签塞回训练输入的做法,都会把“完成任务”变成查答案。

环境快照必须与轨迹一起版本化。至少记录运行时、依赖锁定、工具 schema 版本、工作区初始状态、出站策略和结果校验规则。轨迹中出现 Read、Edit、Agent 或其他工具名,只能作为交互事件记录;文章和验收人员不应据此执行来源文本中的代码、安装目标包或访问真实客户仓库。对需要回放的任务,建议提供无网络、无凭据、无生产副作用的沙箱,并让工具返回可控的模拟结果。环境失败、依赖缺失和模型判断错误要分开标注,否则通过率没有解释力。

六、五道质量门:从能解析到能复跑

第一道是 schema 门。逐行解析 JSONL,检查编码、对象类型、必填字段、枚举值、ID 唯一性、时间格式和数组层级。顶层应能定位 instance,实例应能定位 trajectory,轨迹应能定位 message 和 tool 定义。traj_seq 的类型、tools 的 null 语义、arguments 的字典语义和 content 的字符串/数组语义都应写进机器可执行的 schema,而不只存在于自然语言说明里。

第二道是消息与工具门。检查角色值、消息顺序、assistant 工具调用、工具定义名称、参数 schema、调用 ID 与返回 ID 的配对,以及停止原因是否存在。对孤儿调用、重复返回、空工具名、跨轨迹引用和截断的最后一轮进行硬退回。轨迹完整性不是“消息数量够多”;长轨迹如果在关键工具调用处断掉,反而比短但完整的样本更难使用。对失败和重试应保留原因与发生顺序,不要为了展示漂亮成功样本而删除诊断证据。

第三道是角色与拓扑门。检查 main_agent 是否有序号,子 Agent 是否能通过 traj_uuid 追溯,continuation 数组是否完整,summary Agent 是否被误计为主决策,多个轨迹是否共享了不应共享的上下文。对同一实例的轨迹要做图结构校验:节点是 trajectory,边是启动关系或 continuation 关系,边上可附调用 ID、时间或版本。图中不能出现悬空节点、循环续接或同一 UUID 被两个不相干实例复用。这个门能把“格式正确但拓扑错误”的批次拦在训练之前。

第四道是真实性与任务门。规格要求 assistant 轮次至少达到约定下限,并以单 session 与批次平均分别统计;这类数字是本源项目的验收锚点,不是所有 Coding 数据集都应照抄的行业标准。验收时应报告每条轨迹的实际轮数、空转或心跳轮、工具错误、成功终止、失败终止和中止原因。对于环境任务,还要核对初始状态、依赖版本、测试隔离和独立 oracle;不能把批次平均轮数当作长程能力,也不能把测试通过率直接当成工程价值。公开材料建议将失败、诊断和恢复纳入交付,正是因为只保留成功路径无法解释 Agent 怎样处理真实反馈。3

第五道是污染、去重与复现门。按规范化 JSON 指纹识别完全重复,按 instance 与 trajectory 边界识别前缀快照,按任务、仓库 commit、工作区和连续 session 检查近重复。去重不能误删合理的失败/恢复变体,也不能把同一任务稍改路径后当成独立样本。训练、验证和测试至少按任务族、来源版本、项目或 session 做隔离;相邻消息不能随机拆开跨分区。公开基准的任务设置与真实工程题存在差异,不能把某个榜单数字或外部通过率换算成此项目交付质量;更应该检查题目是否涵盖失败恢复、并发、长期运行和分阶段验收等真实难点。5

多轨迹 Agent 图与五道质量门的验收关系查看完整技术图(可放大)

图 2|主 Agent、子 Agent 与 continuation 组成的轨迹图,以及结构、配对、拓扑、真实性和污染五道质量门。技术示意,不代表已验证性能或任何模型成绩。

七、标签、专家与偏差:把“完成”拆成可解释证据

标注不应只有一个“好/坏”或“成功/失败”。建议至少保留任务类型、来源版本、模型与脚手架、assistant 轮数、是否使用工具、工具调用错误、首次失败位置、恢复是否发生、最终终止类型、测试或 oracle 状态、隐私处理级别和人工复核状态。对主 Agent 与子 Agent 分开统计,对预处理、探索、实现、验证和总结阶段分开统计。这样可以判断问题来自仓库理解、工具选择、环境故障、代码修改、测试解释还是最终闭环,而不是把所有失败归为模型不行。

专家复核的职责也应拆开。软件工程专家判断任务边界、代码与文档来源、补丁是否符合需求和测试是否有解释力;数据工程人员判断 schema、序列化、哈希、配对、去重和切分;隐私与安全人员判断路径、密钥、内部地址、人员信息和工具权限。专家不要把受保护思维链改写成“标准答案”,也不要为了填充标签而复制客户对话。对于 thinking、签名或 effort,只能在授权范围内做结构化核验,不能声称读懂了模型内部推理,更不能以隐藏字段推断用户意图。

抽样必须覆盖边界样本:短轨迹与长轨迹、主 Agent 与多子 Agent、工具无返回、错误后恢复、compact continuation、模型版本变化、不同任务族、不同许可证、依赖构建失败和含敏感字段的记录。两名独立复核者对同一条样本意见不一致时,应保存分歧和裁决理由;不应取平均分把 schema 断链掩盖掉。退回原因要指向字段或门禁,例如“tool_call_id 无匹配返回”“来源许可证未核实”“初始环境泄露测试”“continuation UUID 不存在”,让返工能落到采集、导出、标注或环境团队。

偏差控制也不能靠增加轮数解决。若同一仓库、同一任务模板或同一脚手架占比过高,模型可能学到表面路径而不是工程能力;若所有样本都来自成功执行,失败恢复能力会被高估;若训练和测试共享连续 session,评测可能只是记忆。应按任务领域、仓库规模、语言、文档风格、工具组合、环境故障和失败类型做分层统计,并在数据卡中报告缺失和未知,而不是用一个总量掩盖分布。

八、算法路线与不能从规格推出的结论

对结构化 Coding 轨迹,第一步通常不是直接训练,而是构建可查询的 block 级质量集。解析器可以把消息角色、工具调用、工具返回、错误状态和轨迹拓扑转换成事件图,再把原始载荷与安全摘要分层保存。监督微调可以使用有授权的用户目标、环境反馈、工具事件和最终产物;格式校验可以惩罚不存在的工具、无效参数、悬空调用和不合法终止。若项目要研究过程奖励,可把定位、假设、修改、测试、恢复和 closure 分开打标,但不能把未经授权的原始 thinking 作为默认训练标签。

评测时应把题目正确性、测试通过、补丁可接受性、轨迹完整性和真实工程价值区分开。一个补丁通过公开测试,不代表它覆盖了未见边界;一条轨迹结构完整,不代表模型推理可靠;一组长轨迹轮数较高,也不代表任务更难。可执行环境和独立 verifier 有助于检查状态变化,但 verifier 自己也要经过稳定性、反作弊和污染审计。公开材料把环境、机制变体、多轨迹和独立验证器视为可执行专家环境的重要组成,4 这为 Coding 数据设计提供了方法参考,却不是对任何项目效果的保证。

同样不能从这份规格推出公司业绩、模型排行榜、客户覆盖或跨模型泛化。模型名称字段只说明某条样本的运行配置;它不构成厂商背书。来源网页中的行业观察、评测成绩和趋势判断,应归属于其原文场景;它们不能替代本项目的冻结样本、独立复跑、许可证证明和质量记录。交付文件可以记录“在约定环境下完成了哪些门禁”,但不要把门禁通过率写成基础模型能力,更不要把论文或公开榜单的指标改写成商业承诺。

九、交付形态:让数据工程和业务验收说同一种语言

一个可围绕项目约定的 Coding 轨迹交付包,至少应包含版本化 schema、字段字典、JSONL 样例、轨迹拓扑说明、工具定义、环境与依赖清单、任务来源和许可证记录、训练/验证/测试切分、去重与污染报告、抽检记录、失败清单、变更日志和数据卡。对于含受限字段的样本,还要提供访问角色、用途、保留期限、删除流程和脱敏状态。样例评估通过,只表示该版本满足书面门槛,不自动等于量产放行、模型收益或商业授权完成。

试标应从少量可独立复核的样本开始。第一轮确认来源、许可证、schema 和隐私;第二轮确认任务说明、环境快照、测试隔离和 oracle;第三轮跑结构校验、工具配对、轨迹图和去重;第四轮由不参与采集的人进行盲审,并保留通过或退回理由。公开的 Coding 交付方法也强调,试标要把样例编号、冻结版本、抽检表和返工理由放在同一版本语境下,而不是用“基本完成”替代证据。3 如果环境无法复现、工具链无法配对或许可证无法证明,应停在样例评估,不应为了满足数量而扩量。

业务价值来自可追溯,而不是来自夸大的规模。对模型研发团队,这类数据可帮助分析长程任务中的工具使用、错误恢复和多 Agent 协作;对数据工程团队,它提供稳定的 schema、版本和验收接口;对采购与交付团队,它使仓库锁定、许可审查、环境责任和拒收条件可以写进同一份工作说明。具体范围、授权、周期、样本量和指标仍应以书面项目文件与合同为准,不能从一篇技术文章推断现货、固定库存或长期效果。

十、边界结论:数字轨迹可以很复杂,但仍是 Coding 轨迹

最终应把这份源文件归入 Coding,而不是用“没有机器人数据”否定它。它定义的是数字 Agent 的 JSON/JSONL 轨迹:实例包含多条轨迹,轨迹包含消息和工具,消息保留角色与内容结构,工具调用与结果按 ID 配对,traj_type、traj_seq、thinking、effort、model 和 traj_uuid 支撑拓扑、运行配置与完整性审计。这已经足以构成独立的 Coding 数据格式与验收需求。

同时,本文不把它改写成物理数据。它没有要求本体、动作、传感器、时空标定、接触、遥操或物理 episode 对齐;后续若要进入机器人项目,必须另行建立物理采集契约,不能从软件 tool call 推导电机动作,也不能从 thinking signature 推导人的意图。保持这条边界,反而能让数字轨迹的数据价值更清晰:它服务于仓库级工程任务、Agent 交互分析和可复跑的软件环境,而不是冒充未被源文件要求的机器人训练数据。

AI 辅助整理,供研发与数据工程交流;不构成个体法律意见、生产安全认证或模型性能承诺。

参考来源

  1. NL2Repo 任务包与轨迹:采购时的检查点
  2. NL2Repo 任务包与轨迹:买方把验收提前了
  3. NL2Repo 任务包与轨迹:试标怎样走到移交
  4. 从对话记录到可执行环境:训练数据如何变化
  5. AI编程基准怎么读:任务设置与评测差异

FROM INSIGHT TO YOUR PROJECT

让专业洞察,成为您的数据方案

围绕本文的技术路径与应用场景,和朗慧聊聊您的数据需求。

本文咨询主题:Coding/Agent轨迹数据格式:从 JSONL 结构到可复跑验收的工程契约

业务电话137-5502-0164业务邮箱lk@langhuiai.com
朗慧业务联系人微信二维码,扫码添加联系人
微信沟通

扫码添加业务联系人
或点击二维码查看原图

查看原始微信名片

提交您的项目需求

业务团队将在工作时间内与您沟通。带 * 的为必填项。

* 联系电话或邮箱至少填写一项。

请勿填写个人病历、身份证号、合同原件内容或其他敏感信息。本文标题与链接将随需求提交,便于业务团队理解咨询背景。