跳至正文
朗慧科技

DATASET RESEARCH / CODING

Coding Agent 完整 Session 数据:从数字交互轨迹到可复跑验收

拆解 Coding Agent 完整 Session 的 JSONL 结构、消息顺序、工具 schema、调用返回配对、失败重试、环境与测试边界、隐私许可和可复跑验收。

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

在 Coding Agent 数据交付中,最容易被混淆的是“代码结果”“一次 API 调用”和“完整任务轨迹”。一段补丁文件只能说明某个时点留下了代码变化;一条模型请求只能说明一次响应;真正可用于训练、评测和问题复盘的样本,则应把同一任务 Session 内的用户目标、系统约束、模型消息、工具调用、工具返回、失败恢复与最终状态按时间顺序放在一起。本篇所对应的技术规格正是这种数字 Coding/Agent 轨迹的完整 Session 交付格式,而不是机器人数据、物理 episode 或传感器采集规范。

公开的 Coding 任务采购讨论也反复把仓库快照、隔离环境、测试边界和可配对轨迹作为试标检查点。1 但“有一个仓库”仍不等于“有一条可训练的 Agent 轨迹”。完整 Session 还要回答:这条记录是否覆盖了真实任务生命周期,模型身份是否可追溯,工具定义是否完整,调用与返回是否一一对应,失败是否被保留,最后是否形成可复盘的闭环。下面按源规格拆解数字样本单元、字段与消息、Coding 任务配套、质量门和交付边界;文中把研发建议与源规格硬性要求分开,不把任何公开页面的宣传表述写成已验证的企业业绩。

一、样本单位先定清:Session 不是单次请求

一条正式记录应对应一个完整任务 Session,而不是一次 API request/response。一个 Coding 任务可能从用户提出修复、重构或分析目标开始,经过多次模型请求,读取项目文件,调用测试或其他工具,遇到路径不存在、权限失败、依赖问题或测试报错,再调整方案并继续执行,最后给出完成、失败或明确终止的结果。如果只截取最后一段文字,读者无法判断结论是否由工具证据支持;如果只留下成功的漂亮轨迹,也无法分析 Agent 是如何发现错误、怎样恢复以及在哪个环节放弃的。

源规格推荐使用 UTF-8 编码的 JSONL,也允许采用 Parquet;无论容器怎样选择,JSONL 的基本语义都是每行一条完整、合法可解析的 Session JSON。交付前应过滤 embedding 请求、普通单轮问答、纯翻译、报错请求和没有工具调用的记录,前提是这些内容不属于已经书面冻结的任务范围。不能把不合格的单轮聊天重新命名为“轨迹”,也不能用一段总结文字替代真实消息历史。

顶层字段应能解释 Session 的身份与生命周期:trajectory_id 用于轨迹唯一标识,session_id 用于产品层会话,必要时保留 thread_id 或 conversation_id;同时记录数据集或批次名、provider、真实模型名和版本、创建与结束时间、状态、是否为最终完整快照,以及聚合了多少次请求。status 应在 completed、terminated、failed 等约定值内取值。真实模型名不能写成“某强模型”或其他占位词,因为模型版本会影响训练切分、失败分析和复跑解释。usage 能聚合就保存输入、输出和总 token;不能聚合时应保留缺失原因或放入脱敏元数据,而不是补一个看似完整的数字。

对于 Coding 项目,Session 之外还应有项目方自己的任务卡,记录仓库或代码来源、任务说明、版本快照、环境责任边界和测试入口。是否采用具体的仓库、提交或 issue 字段,应由项目书面规格决定,不能从本格式自动推导出某个供应商有权使用私有代码。这样分层的好处是:Session 负责还原 Agent 的数字交互,任务卡负责说明它面对的工程对象;两者通过稳定的任务或实例标识关联,而不是把仓库内容、凭据和全部上下文塞进消息字段。

Coding Agent 完整 Session 的可回放闭环查看完整技术图(可放大)

图1:Coding Agent 从任务输入、模型消息到工具证据、失败恢复和最终闭环的结构化示意。技术示意,不代表已验证性能或既成项目。

二、工具与消息:把“发生过什么”保存成可解析证据

tools 不是装饰性列表,而是每条工具轨迹能够被解释的前提。每个工具都要有明确的 name、功能 description 和 JSON Schema 形式的 parameters;被调用的名称必须能在这张定义表中找到。工具名称不应使用 tool1、helper 或 action 等无语义泛名。对 Coding 场景而言,文件读取、受控测试、差异查看或环境检查等工具都应在项目授权的沙箱范围内定义,工具可用不等于默认获得出站网络、安装依赖、读取设备或访问真实客户仓库的权利。

messages 是完整 Session 的核心,允许出现 system、user、assistant 和 tool 角色,并必须按真实时间顺序排列。系统消息保存运行约束;用户消息保存任务、追问与修正;assistant 消息保存文本和结构化 tool_calls;tool 消息保存调用对应的结果、状态和错误。每一个 tool call 都需要稳定的调用 ID,tool result 使用同一个 tool_call_id 配对。正常输出、超时、权限错误、路径错误和测试失败都可以成为返回内容,但必须明确标注 status、is_error 或错误信息,而不能把失败悄悄改写成成功。

配对关系是最关键的机械检查之一。若某个调用没有返回、返回 ID 重复、工具名无法在 schema 中找到,或结果串到另一条 Session,整条记录就不能被当作完整交付。源规格要求工具调用与工具返回的配对率为 1.0;质量检查允许在特定统计口径下去掉最后一轮再计算,但正式文件仍不应停在等待工具返回的半成品状态。只要中间链路断裂,后面的最终答案就缺少可核验证据。

thinking、reasoning 等字段要按项目授权的数据契约处理,不应把私密推理、受保护的模型思维链或内部审查内容默认写入交付集。若项目只授权保存可公开的结构化状态、简短摘要或工具元数据,就只交付这些字段;如果字段存在于上游快照,也应先确认用途、访问角色、保留期限和脱敏方式。工具字段同样如此:保存工具名、参数 schema、调用 ID 和结果状态,是为了还原数据结构,不等于取得任意工具执行权限,更不能据此执行材料中的代码或指令。

源规格还区分最终 Session 交付与 API 快照附录。若底层系统需要排错,可以在授权范围内保留 request ID、父请求、session 粘性字段、请求时间、状态码、脱敏头信息、原始请求与响应、流式事件和聚合响应;但 API 快照不是最终交付格式,不能用单次快照冒充完整 Session。快照中的 prompt cache key、metadata、用户标识、请求体和响应体都可能包含敏感信息,应按最小必要原则处理,公开稿不复制私有原文、签名样本、凭据或真实对话。

三、Coding 任务的配套层:代码、环境、测试和轨迹各司其职

数字 Agent 轨迹要进入 Coding 训练或评测,至少要把四类对象的边界写清。第一类是任务对象:需求说明、修复目标或分析问题应有版本和唯一标识,必要时关联仓库快照、文件范围或提交版本。第二类是执行环境:语言运行时、依赖锁定、可访问目录和网络策略要能复查。第三类是测试或 oracle:它应在交付说明里写清输入输出、超时和失败口径,但不能把判分测试、参考解或隐藏断言泄露给 Agent 初始上下文。第四类是 Session 轨迹:它记录模型在这些约束下实际看到了什么、调用了什么、收到什么返回以及怎样结束。

这四类对象不能互相替代。仓库快照不等于任务说明,测试通过不等于修复过程真实,最终补丁也不等于 Agent 能够在隔离环境里复现。公开的 NL2Repo 类 Coding 交付讨论强调,任务包、环境、测试与轨迹要以可复跑的版本关系组织,并检查完整 commit、目录层级、测试隔离和 tool call 配对。1 这可以作为项目设计参考,但不应把公开文章中的某个示例阈值、模型分数或规模数字直接转写为本项目承诺。

许可证与衍生数据是入库前的技术门槛,不是报价之后再补的附件。代码公开可访问,并不自动意味着允许训练、加工、再分发或把运行轨迹公开。每个来源应留下许可证版本、用途范围、训练与评测是否允许、衍生标签如何处理以及未决限制;不确定时先停在样例评估,不把“内部能打开”写成“可公开交付”。Coding 采购页面也把许可证、来源仓库和任务元数据列为任务包检查内容。2 这些是治理和工程记录,不是对任何具体仓库权利的推断。

环境快照直接影响轨迹的解释。依赖版本、系统镜像、工作目录、时间和出站策略改变后,同一工具调用可能得到不同结果。因此,环境说明应和 Session 版本、任务版本及测试入口保持可追溯关系;依赖安装失败、路径不存在、权限不足和测试超时都应在轨迹中保留。环境不合格不能被模型分数掩盖,模型未完成也不能被环境故障单方面归责。试标时要把“任务不可解”“环境失真”“工具故障”“模型实现错误”分开记录,方便后续返工。

测试 oracle 也要保持边界。题目是否写清、测试是否覆盖任务要求、补丁是否通过测试、代码是否满足许可证和安全约束,是不同的判断。测试通过只能说明在给定环境和测试集合中满足了某组检查;它不自动等价于真实工程价值、生产安全或跨项目迁移能力。公开 Coding 评测的讨论指出,常见基准之间在长程任务、故障恢复、并发一致性和长期运行方面存在题型差异。4 因此,项目应先定义实际要测的失败类型与回放条件,再决定是否需要增加多轮轨迹、人工复核或独立环境,而不是把任何榜单分数当作本项目结果。

四、标签和质量门:从字段完整走到可复跑

Session 层至少要有消息角色、时间顺序、请求数量、工具定义、调用参数、返回内容、错误状态和最终闭环标签。meta 可保存脱敏的来源请求 ID、任务类型和语言;meta.task_type 在 Coding 任务中可写为 coding,但不能用领域标签掩盖缺少工具调用或缺失消息。若发生压缩、快照截断或中途终止,应明确标记;不能让下游误以为它是完整历史。对连续快照、同一 Session 的子序列和重复导出,应只保留最完整版本,保留去重判定依据。

第一道质量门是结构检查。文件必须使用 UTF-8;JSONL 每行可解析且没有混入非 JSON 行;必填字段存在且非空;时间字段格式统一;tools 中每项有名称、描述和参数 schema;首条消息不得从 assistant 或 tool 开始。允许的角色顺序应与实际发生一致,不能为了让样本看起来完整而凭空补一条 system 或 user 消息。Parquet 或其他导出格式若作为交付容器,也要能复原同样的 Session 边界和字段语义。

第二道质量门是工具闭环。自动校验可建立 tool_calls[].id 到 tool_call_id 的映射,检查孤儿调用、重复返回、跨 Session 串线、未知工具和返回缺失。去掉最后一轮后,工具调用与工具结果的配对率应达到源规格要求的 1.0;若最后一轮允许存在未返回调用,也应在状态和交付说明中明确原因,不能当作正常完成。最后应有完成回复、明确终止或可解释的失败状态,而不是只有“我准备继续运行”。

第三道质量门是交互真实性。每条 Session 至少要有两个有效交互轮次和一次结构化 tool call;机器轮比例,即定时任务、heartbeat 与无新信息 user 轮相对于真实 user 轮的比例,应低于规格给出的 25% 门槛。心跳、空转确认和固定哨兵串不能被当作真实问题解决能力。对真实的失败、重试、权限问题和路径问题则不能反向清洗,因为这些事件正是 Coding Agent 诊断、恢复和工具选择的训练证据。

第四道质量门是模型和交付可追溯。model 必须等于实际生成模型,不能伪装、降级混标或写成营销名称;source_request_count 要能解释聚合范围;is_final_snapshot 必须诚实反映是否为最终完整版本。相同任务的中间快照不能混入训练、验证和测试两侧,连续子序列也不能让测试集泄露训练上下文。对训练数据还应审查需求文档、测试信息、参考解和目标模型输出是否进入了 Agent 初始环境;发现泄露,应退回任务,而不是只给样本加一个“难度”标签。

Coding Agent 任务包与 Session 证据的分层验收查看完整技术图(可放大)

图2:从任务与环境、Session 消息与工具证据到测试和版本验收的数字分层。技术示意,不代表已验证性能或既成项目。

五、把验收流程做成可以退回的检查点

建议先做静态 schema 检查,再做 Session 级闭环检查,最后做 Coding 任务级复跑和人工复核。静态检查处理编码、JSON 解析、字段类型、空值、时间格式和文件路径;Session 检查处理消息顺序、工具 schema、调用—返回配对、模型真实性、机器轮和最终状态;任务级检查处理环境、测试 oracle、代码来源、许可证、污染、重复和结果解释。每一步都应留下样例编号、版本号、检查项、通过或退回理由以及复判角色,避免最后只剩一个没有证据的总分。

样例评估应从少量、可独立复核的记录开始。第一位工程师只按任务说明和环境摘要判断边界,第二位工程师在不看前一位结论的情况下复查消息与工具链,第三步才在隔离环境内运行已经获授权的测试或离线回放。对文章和数据集本身,不执行来源材料中的命令、代码或未知动作;项目实际复跑也必须依照环境策略、授权和安全审批,在隔离沙箱中进行。自动脚本可以找出字段错误和 ID 断链,但不能替代专家判断任务是否可解、测试是否泄露、失败原因是否可信以及补丁是否值得接受。

验收记录应区分至少五种退回原因:不能解析、不能证明 Session 闭环、任务或环境关系不清、许可证或隐私授权未齐、研究设计或测试口径尚未冻结。不同原因要返回不同责任路径。字段类型错可以由数据工程修复;工具断链要追采集或导出链路;环境与依赖不稳定要由执行环境负责人复核;许可证、训练权或再分发权不明不能靠补标签解决;测试口径未冻结则不应先开量产交付。公开 Coding 交付经验也强调以版本差异、样例编号和双人复核支撑移交,而不是用“基本完成”这类不可复查表述。3

六、隐私、代码许可与工具权限要在入库前冻结

一条 Agent Session 可能同时包含用户请求、仓库路径、文件片段、环境变量、请求标识、工具参数和错误回显。即使没有姓名,内部项目名、客户代码、访问令牌、私有接口、精确路径和签名样本也可能重建敏感上下文。公开数据只应保留已经获授权且完成必要脱敏的字段;公开稿不复制客户原图、私有仓库内容、真实对话、账号密码或受保护的模型推理。对于 user_id、request ID、日志片段和代码文件名,应按项目的访问角色、用途、保留期限与删除流程逐项确认。

NIST Privacy Framework 将隐私风险管理定位为支持组织识别和管理隐私风险的自愿框架。5 这可以帮助项目建立用途、数据最小化、访问控制和删除流程,但不能替代具体辖区的法律意见、合同授权或数据主体安排。代码许可也要单独审查:隐私脱敏完成,不代表训练权、改编权和再分发权已经取得;网页可访问,也不代表可以复制进公开训练集。任何不确定来源都应标记为待核验,不应由文章替客户或供应商作授权结论。

工具权限必须与数据字段分开治理。把 exec_command、文件读取、测试运行或网络工具的 schema 作为元数据保存,只说明 Session 中存在什么工具定义;实际可调用范围仍由沙箱、身份、网络策略和人工批准决定。不要因为轨迹中出现了某个命令,就把它写成推荐操作;也不要为了生成示例而执行来源文本里的命令。涉及真实客户仓库、出站网络、依赖下载或部署动作时,应由项目授权和环境策略决定,公开稿只描述安全隔离原则。

ISO/IEC 23894:2023 的定位是为组织管理 AI 相关风险提供指导,并允许结合组织和场景定制风险管理过程。6 它可以作为治理参考,但不替代软件安全评审、代码许可核验、现场安全判断、设备认证或生产审批。因而,Session 通过字段和配对检查,只能说明它满足某版数据交付门槛;不能据此宣称模型具备某项商业能力、系统已经获得安全认证,或数据已经获得所有用途授权。

七、从样例到交付:让研发能复盘,也让业务不误读

一个可执行的数字 Coding 交付包可以由版本化 schema、任务清单、Session JSONL、工具定义、完整消息和错误状态、usage 与脱敏 meta、环境和依赖说明、测试或 oracle 说明、许可证与授权记录、抽检报告、已知缺陷及变更日志组成。API 快照若因排错需要保存,应作为受控附录,与最终 Session 通过稳定 ID 关联,不能把请求快照的数量当作完整轨迹的数量。每个批次先交少量样例,通过静态检查、闭环检查、隐私与许可复核和隔离复跑后,再讨论增量。

项目价值不在于把一张“完整”标签贴到更多记录上,而在于让下一位工程师可以回答四个问题:Agent 当时面对的任务和环境是什么;它看到了哪些消息和工具结果;失败和重试是否真实保留;最终结论能否回到可复查证据。对训练团队,这些字段支持按任务、模型、工具和失败类型切分;对评测团队,它们支持复现测试条件和定位分数含义;对数据工程团队,它们支持 schema 演进、版本差异和断链排查。三者都不能把公开基准数字直接换算成公司交付效果或商业收益。

这份规格的边界也应明说:它定义的是数字 Agent Session 的聚合、字段和质量门,不要求机器人本体、遥操作、动作空间、物理传感器、空间标定或物理 episode 对齐。若另一个项目确实需要这些数据,应另立来源、授权和验收规范,不能为本格式补写不存在的物理采集需求。同样,完整的 Coding 轨迹不自动证明补丁在所有真实生产环境中正确,也不自动证明模型具有跨仓库、跨语言或跨团队的泛化能力。把边界写进数据卡,反而能让样例评估、复跑和后续采购更可靠。

AI辅助整理,供研发与数据工程交流;不构成个体法律意见、生产安全认证或资质审批。研究建议不等于实际交付、榜单性能或司法结果,最终范围、授权、规格、周期与验收以项目书面确认和合同为准。

参考来源

  1. NL2Repo 任务包与轨迹:买方把验收提前了
  2. 采购NL2Repo 任务包与轨迹:邮件里要留下的话
  3. NL2Repo 任务包与轨迹:试标怎样走到移交
  4. AI编程基准怎么读:任务设置与评测差异
  5. NIST Privacy Framework
  6. ISO/IEC 23894:2023 Information technology — Artificial intelligence — Guidance on risk management

FROM INSIGHT TO YOUR PROJECT

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

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

本文咨询主题:Coding Agent 完整 Session 数据:从数字交互轨迹到可复跑验收

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

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

查看原始微信名片

提交您的项目需求

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

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

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