工具监督微调把 Agent 的交互过程转成条件语言建模样本。它教模型在给定任务、历史动作和环境观察时生成下一段可执行输出。这里的标签不只是一句自然语言答案，还包括是否调用工具、选择哪个工具、参数如何填写、何时读取新观察、遇到错误怎样恢复以及何时停止。数据表示若丢失这些边界，模型即使学会表面格式，也难以在真实 Runtime 中稳定执行。
1. 轨迹与学习目标
1.1. 决策序列
一条轨迹可写为 。 是任务与初始环境， 是模型产生的动作， 是环境返回的观察， 是最终回答或终止状态。训练只对策略产生的 token 计算损失，用户文本、系统约束、工具观察和 Runtime 注入的状态使用 loss mask 排除。
动作有三类：自然语言回复、结构化工具调用和控制动作。控制动作包括请求审批、等待、取消、提交结果与声明无法继续。若数据只保留工具 JSON 和最终回答，模型不会学到权限不足时应请求授权，也不会学到外部提交状态未知时应查询而非重试。
轨迹前缀决定标签含义。同一个 search 调用在尚无资料时可能正确，在已有充分证据后则是冗余动作。样本要保留当前决策依赖的任务、工具契约、关键观察、预算与能力状态，不能把动作从上下文中抽出做孤立分类。
1.2. 工具选择与停止
工具选择目标同时覆盖“调用哪个”和“是否调用”。训练集若全部来自必须使用工具的任务，模型会把调用本身当成成功信号，在可直接回答的问题上也制造无意义步骤。数据需要包含无需工具、工具不可用、已有观察足够、预算已耗尽等停止样本。
相近工具构成困难负例。数据库查询与全文检索、文件读取与网页抓取、预览与提交的名称可能相似，但权限、时效和副作用不同。样本中的选择理由不必暴露长篇私密推理，却应让输入状态包含足以区分它们的契约字段，使监督信号落在可观察条件上。
停止也有真假之分。模型可以在完成谓词满足时正常结束，在缺少权限或信息时说明阻塞，在安全策略拒绝后提出缩小范围。过早结束、未验证就宣告成功和无限搜索都是错误策略，需要在验证后的终局标签与反例中显式区分。
1.3. 参数与观察
参数生成受 JSON Schema、业务约束和环境版本共同约束。字段类型正确不代表语义正确：日期范围可能反转，文件路径可能越界，更新请求可能缺少资源版本。数据生成器保存工具版本、schema 哈希、规范化参数和校验结果，避免同名工具的旧新签名混成冲突标签。
观察属于环境输出，不能参与策略 token 的交叉熵。模型要学习的是基于观察采取后继动作。截取轨迹片段时，当前动作之后的观察必须删除，否则会发生未来信息泄漏；过长观察可以摘要或检索，但派生摘要要保留来源、截断标记和关键错误字段。
错误观察是训练恢复能力的关键材料。超时、权限拒绝、参数校验失败、空结果、部分成功和未知提交对应不同后继动作。若统一改写为“工具失败”，模型只能学会盲目重试。真实错误码、是否可重试、动作 ID 与已提交证据应该进入结构化观察。
2. 数据来源与规范化
2.1. 真实轨迹
真实轨迹贴近部署分布，包含用户表达、工具延迟、历史遗留数据和人工介入。采集时记录生成策略、模型版本、采样参数、工具与环境版本、权限集合、任务结果和成本。缺少这些元数据，后续无法判断某个动作来自模型能力、旧接口限制还是操作者修正。
线上成功不能直接当正样本。任务可能被人工完成，模型步骤可能包含碰巧无害的越权尝试，最终答案也可能通过缓存或数据泄漏得到。轨迹需在隔离环境重放，使用完成谓词验证终局，并逐步检查动作合法性、参数有效性、观察对应关系和不可逆效果。
隐私处理发生在入库前。凭据、个人数据和客户内容使用删除、占位符或受控引用，且占位保持类型与作用域一致。简单把所有值替换成同一 <SECRET> 会让模型学不到不同凭据槽与目标服务的对应关系，也可能破坏参数结构。
2.2. 合成与搜索轨迹
合成数据可以覆盖罕见工具组合、故障恢复和新接口。任务生成器从工具能力与环境状态反向构造可验证目标，教师模型产生候选轨迹，执行器在沙箱中运行，只有通过终局验证的轨迹进入候选池。教师文字自称成功没有资格替代环境证据。
单一教师容易复制固定路径和措辞。可以通过不同模型、采样温度、工具顺序约束和环境扰动生成多条候选，再按成功、成本与多样性筛选。搜索算法可在动作级扩展分支，用 verifier 评估局部状态；但被选中的轨迹要重新完整执行，防止拼接来自不一致环境快照的节点。
合成任务必须控制可解性。若工具集合无法满足目标，正确标签应是识别阻塞，不应让教师虚构 observation。若环境中存在不希望模型利用的捷径，例如答案文件或测试夹具，应在生成时移除，否则数据会强化部署时不存在的策略。
2.3. 统一轨迹格式
统一格式区分 system、user、assistant、tool_call、tool_result 和 runtime_event。每个调用有稳定 call ID，观察引用对应调用；并行调用还记录父节点与汇合关系。纯文本中用特殊标记模拟这些角色，容易在转义、截断和模板升级时破坏边界。
样本记录动作的可训练区间。工具名和参数由模型生成，通常计入损失；工具返回、审批结果和状态通知来自环境，全部 mask。最终回答是否训练取决于任务目标。若只研究调用规划，可降低自然语言部分权重，防止长答案淹没稀少的动作 token。
格式转换器必须双向测试：训练记录渲染成模型输入后再解析，应恢复相同角色、调用参数和 mask。部署 Harness 使用相同 chat template、工具 schema 和停止 token。训练与服务各自维护一套模板，会造成模型在离线损失下降、上线却无法闭合调用。
3. 过滤、修复与加权
3.1. 终局与逐步验证
过滤从终局开始：测试是否通过、目标文件是否产生、数据库状态是否满足、外部模拟器是否记录预期交易。仅比较最终文本会保留大量幻觉成功。终局正确后再检查过程，因为同一正确结果可能由危险捷径、重复副作用或人工补救得到。
逐步验证器检查 schema、权限、资源版本、动作前置条件和观察完整性。每个动作标记 valid、invalid、unknown，未知不会自动当作正例。对有副作用的轨迹，幂等键、审批摘要和提交证据缺失会降低质量等级，即使任务偶然完成。
过滤阈值要按用途调整。基础工具格式数据可容忍较弱的业务 verifier，安全恢复数据则要求完整事件证据。保留失败原因比只保留通过集合更有价值，它能暴露数据生成器、环境和教师模型的系统偏差。
3.2. 去重与污染
文本去重无法识别同一轨迹的模板改写。更可靠的指纹包含规范化任务、工具序列、参数结构、资源终局和关键观察。对于同一决策骨架的大量样本，按任务难度与环境差异采样，避免高频模板控制梯度。
训练集与评测集按任务来源、仓库、网站、模板族和时间切分。只按最终问题文本随机切分，会让同一项目的相邻 Issue 或同一生成模板进入两侧。工具任务还需检查环境污染：测试答案、参考补丁、隐藏验证脚本和教师缓存不应暴露给策略。
近重复检测不能误删重要反事实。两个样本只有一个参数越过权限边界，动作文本几乎相同，却提供了关键判别信号。去重键要保留风险等级、能力状态和资源版本等决定性字段。
3.3. 轨迹修复与权重
真实失败轨迹可以转为训练数据，但不能直接删除错误步骤后把剩余片段称作成功轨迹。删除会改变后续观察和状态。修复应从错误前的环境快照重新执行替代动作，得到一致的新轨迹；原失败前缀则可用于训练错误识别或偏好比较。
长轨迹中的大量格式 token 会压低关键动作权重。训练可按动作类型设置权重，或把轨迹切成保持因果上下文的决策样本。切片必须包含该动作依赖的观察，且不出现未来结果。不同长度样本打包时，loss 按有效策略 token 归一，避免短轨迹因样本平均获得过高影响。
质量分数结合终局、逐步合法性、成本、人工修正和验证置信度。高分不等于全部复制，数据混合还要控制工具、错误类型、任务难度和语言覆盖。权重策略通过消融验证，不能仅凭教师自评分决定。
4. 训练分布与泛化
4.1. 行为克隆的偏移
监督学习在示范状态分布 上优化 ，部署却访问当前策略诱导的 。早期一次参数错误会产生示范中没有的观察，后续预测进入分布外状态，错误逐步累积。这是行为克隆的核心限制。
加入恢复示范可以扩大覆盖：让候选策略在沙箱中运行，收集偏离状态，由专家或验证器给出正确后继动作，再合并训练。数据聚合要保留生成轮次与策略版本，避免新模型只学习旧模型最容易犯、后来已经消失的错误。
离线日志还受选择偏差影响。线上系统可能只保存成功、用户未取消或低风险任务，导致训练集缺少困难状态。比较来源覆盖率、失败保留率和状态特征分布，能够发现“数据很多但有效支持很窄”的情况。
4.2. 未见工具与接口变化
未见工具泛化依赖契约可组合性。评测替换工具名称、调整描述措辞、重排 schema 字段和引入同类新工具，可以区分语义理解与 token 记忆。若模型只见过固定工具列表，换名后性能骤降并不意外。
工具描述应说明前置条件、副作用、参数约束、错误语义和返回结构。过度冗长的描述增加上下文负担，过短描述又把必要知识藏在训练频率中。对跨工具共享的概念建立稳定字段，例如资源版本、幂等键和分页游标，比让每个工具发明不同名称更利于迁移。
接口升级时运行数据迁移与回放。旧轨迹按旧 schema 保留并标版本，转换器只能做语义明确的映射；无法转换的样本退出当前训练集。把新旧参数混在同一无版本名字下会制造不可解的监督冲突。
4.3. 离线分布与部署Harness
模型、工具和 Harness 组成联合策略。工具超时、最大输出、观察截断、上下文压缩和重试规则都会改变状态分布。训练时工具总是立即成功，部署时频繁分页和审批，模型就会在真正困难的位置失去监督支持。
离线评测使用固定环境快照，可以比较模型版本；在线影子评测再测真实延迟、失败和数据新鲜度。两者差距本身是指标。若只报告静态工具调用准确率，无法预测多步完成率与副作用风险。
回放旧轨迹评估新策略时，只能衡量日志中已采取动作的似然，不能知道新动作会得到什么观察。重要性加权在行为策略概率已知且支持重叠时才有意义，长序列的权重乘积还会产生巨大方差。涉及新工具或新状态时，需要模拟器、在线沙箱或保守的覆盖判断。
5. 评测与数据闭环
5.1. 分层指标
单步指标包括工具选择、参数字段准确率、schema 合法率、停止判断和错误分类。轨迹指标包括任务成功率、首错位置、恢复率、动作数、重复调用、成本和耗时。安全指标单列越权尝试、审批正确率、敏感数据流向与不可逆副作用。
参数完全匹配常常过严，语义等价的查询可以不同；只看执行成功又可能过松，危险参数恰好未造成损失。评测器应结合规范化参数、环境效果和策略约束，并保存无法自动判定的样本供人工抽查。
首错分析把错误归到选择、参数、观察理解、恢复、验证或停止。终局失败率相同的两个模型，首错分布可能完全不同，对应的数据改进方向也不同。
5.2. 反例与消融
“增加更多成功轨迹一定更好”是常见反例。若新增数据都来自同一教师和简单模板，训练损失下降，未见工具和故障状态却可能退化。消融应分别移除恢复轨迹、无需工具样本、困难负例、版本字段和逐步验证，观察单步与终局指标变化。
另一个反例是把失败调用全部过滤。数据变得干净后，模型只见过顺利环境，一旦上线遇到 429、空结果或权限拒绝就重复调用。保留错误观察及其正确后继动作，通常比保留错误动作本身更重要。
数据规模实验要控制 token、任务族和教师质量。比较一百万近重复轨迹与十万高覆盖轨迹时，同时报告有效动作类型、状态覆盖和验证通过率，避免把计算投入误写成数据方法收益。
5.3. 持续更新
部署日志经脱敏、归因和验证后进入候选池，不能自动回灌。模型错误、工具故障、用户目标变化和策略拒绝先分类；只有能够给出正确替代动作并重放验证的案例，才成为监督样本。
每次数据发布固定清单、生成代码、工具 schema、过滤器版本和评测结果。训练模型可以追溯到具体轨迹版本，发现污染或错误标签时能够删除来源并重训。数据集变更同代码变更一样接受审查。
闭环的终点是部署指标改善。若离线选择准确率提高而多步成功率不变，应检查状态分布、Harness 与验证器，不应继续盲目扩充相同样本。工具 SFT 提供可靠起点，环境交互与强化学习负责覆盖策略自己产生的新状态，两者边界由实测误差决定。
训练管线本身也需要一致性测试。随机抽取样本，把渲染后的 token、角色边界、attention mask 和 loss mask 可视化，确认损失只落在预期动作上。工具 JSON 被 tokenizer 拆成多少 token并不重要，关键是工具名、参数与结束标记完整参与监督，观察和系统文本没有误入标签。截断若切掉调用尾部，整条决策样本应重新切片或丢弃，不能留下永远无法解析的半个动作。
packing 把多条短轨迹放进同一序列时，要阻断样本间 attention，并分别保留位置、loss 与文档边界。后一任务若能看到前一任务的答案或工具结果，会形成隐蔽泄漏。多轮长轨迹通常不宜在任意 token 处截断；按决策边界切片并补入必要状态摘要，可以维持调用与观察的一一对应。
数据混合比例应在 token、轨迹和动作三个尺度报告。一个包含五万 token 日志的长轨迹，在逐 token 采样下可能压过数百条短任务；只按轨迹计数又会隐藏这一点。按来源设 token 上限，再按稀有动作和错误类型做分层采样，能维持覆盖。损失权重与采样权重不能同时无记录地放大同一类别。
优化指标也要按角色拆分。整体交叉熵主要由自然语言解释贡献时，工具参数已经退化却不易察觉。分别统计工具选择 token、参数键、参数值、控制动作和最终回答的 loss，并用环境执行率验证。结构 token loss 很低可能只说明括号与固定字段容易预测，不能证明资源和数值参数正确。
标签冲突通过状态指纹发现：相同规范化前缀若对应多个互斥动作，检查它们是否缺少能力、资源版本或隐藏观察。确有多种合理策略时，可以保留多标签而不强行选唯一答案；评测也采用环境效果和合法集合。若冲突来自过期接口或错误教师，按来源批量修复，不用模型容量吸收数据管线矛盾。
上线前做小规模记忆测试与反事实测试。模型应能拟合一小批无冲突轨迹，拟合不了往往暴露 mask、模板或解析错误；把工具名、危险路径、审批状态和观察结果替换后，动作应随语义变化。只会复现原始字符串而不能响应反事实，说明数据多样性或状态表示仍然不足。
训练完成后还应回放一组固定轨迹，逐 token 对比升级前后的工具概率、参数熵和停止倾向。该回归集不用于选择最佳 checkpoint，只负责发现模板、分词器或数据混合改动造成的意外漂移。结合真实环境评测，才能区分模型能力变化和序列化接口变化。 工具 SFT 的训练目标可以按 token、动作和轨迹分层。基础交叉熵作用于模型生成 token，动作权重提高工具名、关键参数和控制决定的贡献，轨迹采样保证困难任务不会被大量短格式样本淹没。三层权重都要记录，否则无法解释某类能力为何退化。
逐 token 平均让长轨迹贡献更多，逐样本平均让每条决策权重相同。若长轨迹包含大量自然语言，前者可能稀释稀少的工具 token；若短样本多为简单格式，后者又可能过度强化模板。通常先按任务和动作类型采样，再在批内按有效策略 token 归一，并用消融确认。
loss mask 是最容易静默出错的环节。用户、系统、工具 observation、Runtime 事件和 padding 不应作为策略目标；工具调用的名称、参数和结束标记需要完整训练。可视化随机样本的角色、token 与 mask，并做小数据过拟合，能快速发现模板边界与截断错误。
packing 多条短轨迹时，样本间 attention 必须隔离，位置与 loss 边界独立。后一任务若看到前一任务答案，训练损失会异常好，却在单独推理时失效。长轨迹按动作边界切片，不能切出半个 JSON 或缺少其依赖 observation 的后继动作。
工具 schema 既出现在输入，也影响输出 token。字段重排、描述改写和版本变化可能造成词形偏差。训练集包含等价序列化变体，部署模板与训练模板做往返测试。结构约束解码可以减少语法错，但不能替代参数语义数据。
多工具样本的配比按真实流量与风险校正。高频搜索自然占多数，低频付款、删除与审批却具有更高安全价值。完全按线上频率采样会让模型几乎见不到关键拒绝路径；完全均匀又偏离部署。混合权重和目标覆盖写入数据卡。
无需工具样本是重要负空间。问题已有答案、权限不够、工具成本高于收益和用户只要解释时，正确动作可能直接回复或说明阻塞。没有这些数据，模型会把工具调用当成展示能力的固定仪式。
困难负例要与正确动作只差一个决定性条件。例如同一路径在工作区内可读、在密钥目录不可读；同一邮件草稿可以生成，但发送需要批准。随机错误参数容易被模型识别，却不能训练真实边界。
恢复监督从错误状态开始。样本包含动作 ID、错误分类、已提交证据和剩余预算，标签是修参数、换工具、查询、请求授权或停止。直接展示失败前的正确完整轨迹，会让模型没有机会学习部署时真实出现的偏离状态。
未知提交是特别重要的恢复类。工具超时后，训练标签应查询外部状态，而非原样重试。若数据生成环境总能立即返回成败，模型永远学不到第三种状态。模拟器需要在提交后丢响应并提供幂等查询。
人工修正日志要重建因果。用户在 Agent 失败后手动改文件，最终测试通过，不能把整条轨迹标为模型成功。数据处理识别人工动作，从错误前快照重新执行可学习的修复，或把原轨迹保留为“需要人工”案例。
合成教师可能泄漏 verifier。教师看到隐藏测试、答案文件或最终数据库状态后生成轨迹，学生会学到部署不可用的信息模式。数据生成严格限制教师观察面，与被训练策略一致；任务构造与解答角色分离。
轨迹搜索选出高回报路径时，会产生幸存者偏差。偶然一次成功的脆弱动作可能被大量复制。候选要在环境扰动和不同种子下重放，比较稳定性、成本与安全；只有终局一次通过不够。
去重可用动作图指纹，但应保留关键反事实。相同工具序列、不同权限状态对应相反标签，不能因文本相似被合并。指纹包含任务族、能力、资源版本、错误类型与终局，聚类后按差异轴采样。
数据污染不仅是评测答案进入训练。旧工具 schema、过期政策和错误记忆也会造成冲突。每个数据源有生效时间和工具版本，发布前扫描不再支持的动作。无法迁移的旧轨迹退出当前训练集，而不是靠模型学习两套互斥接口。
离线行为克隆无法观察新动作产生的结果。对旧日志计算当前策略似然，可以发现分布漂移，却不能证明高似然动作会成功。重要性加权要求行为概率和支持重叠，长轨迹权重高方差。新工具或新状态最终需要交互环境。
DAgger 式数据聚合让当前策略运行，在偏离状态上请求专家动作。Agent 场景的专家可以是人工、强模型加 verifier 或确定性规则。聚合轮次记录生成策略，避免旧错误样本无限占比；每轮在固定回归集确认没有遗忘基础格式。
课程学习从可获得成功信号的任务开始。先训练单工具与明确错误，再增加工具组合、环境随机性和长程恢复。如果初始策略几乎从不成功，后续 RL 也难以得到信号。课程升级依据能力门槛，而非固定训练步数。
训练监控按工具选择、参数键、参数值、控制动作和最终回答拆 loss。整体 loss 下降可能只是自然语言更流畅，资源 ID 与数值参数却退化。环境执行率、schema 合法率和终局成功提供外部校验。
checkpoint 选择使用独立可交互环境，不按训练损失最低决定。比较模型时固定 Harness、工具版本、预算和解码；模型可能通过更长轨迹提高成功，因此同时报告动作、token 与时延。
数据错误修复需要可追溯 lineage。样本指向原始运行、转换器、过滤规则和人工裁决。发现一类错误后按来源批量失效并重建，不能手工改几条 JSON 后失去历史。模型 checkpoint 也记录精确数据清单。
隐私处理保持语义。账户、路径和密钥使用类型化占位符，跨轮引用保持一致；所有秘密替换成相同 token 会制造错误实体绑定。脱敏后重新解析并执行 schema 检查，防止处理过程破坏轨迹。
高质量数据发布报告来源比例、任务与工具覆盖、长度、错误类型、验证通过、去重、污染扫描和已知缺口。数据规模只是其中一项。十万条覆盖多种真实状态的轨迹，可能比百万条同一教师模板更有效。
最终验收看部署闭环：模型在未见任务能否选择工具、生成参数、利用 observation、从错误恢复并正确停止。任何离线指标若不能预测这些行为，都只是数据管线诊断，不应代替 Agent 能力结论。
监督微调还会出现灾难性遗忘。集中加入新工具轨迹后，模型可能降低普通对话、旧工具和拒绝能力。数据混合保留代表性基础样本，按能力套件做回归；只在新工具 benchmark 提升不足以发布。遗忘集中在哪些层，可通过冻结骨干、低秩适配与全参训练的消融定位。
工具 token 的新增方式影响迁移。把工具名作为普通文本无需修改词表，但相似名称可能混淆；新增特殊 token 能形成清晰边界，却要求初始化和服务模板一致。无论选择哪种，都用未见名称与别名测试语义泛化。
多语言任务要求 schema 字段稳定，描述可以本地化。参数值中的日期、数字、地址和专有名词经过区域规范化，执行器返回规范值与用户显示值。训练数据若混用两者，模型可能生成视觉正确但工具无法解释的参数。
工具可用性必须真实。展示工具却因权限永远拒绝，会产生矛盾监督；完全隐藏可申请工具，又学不会审批路径。发现阶段展示“可申请”能力时，标签应生成授权请求，而非直接调用。
教师蒸馏要保留不确定性。强模型在缺证据时给出确定动作，学生会把猜测当标准答案。候选由环境 verifier 筛选，无法判定的状态保留多种合法动作或阻塞标签。交叉熵不要求每个前缀只有唯一自然语言序列。
高损失样本不必然错误。罕见而正确的工具、长资源 ID 和多语言值都会提高 loss。审查结合 verifier、冲突前缀和来源质量，不能为降低曲线删除真正困难样本。
部署日志回流遵循最小收集。保存动作结构、错误分类和环境证据，敏感正文用受控引用；未授权内容不进入训练池。数据保留、删除和训练批次建立 lineage，后续删除请求可以定位受影响数据。
上线采用影子与低风险能力。新模型先在相同 observation 上给出候选而不执行，随后只开放只读和测试环境，再逐步增加写能力。真实执行的权限边界始终由 Runtime 控制，不随离线分数自动扩大。
工具 SFT 的成熟标志是模型能遵循契约并适应反馈。接口变化、错误状态和未见组合会暴露策略是否学到条件关系。数据工程围绕这些变化构造证据，模型才能成为闭环系统中的可靠候选生成器。
发布前对训练模板和服务模板做字节级样例对照，确认角色、转义、工具结束符和并行调用表示一致。许多“模型不会调用工具”的问题实际来自服务端序列化差异。该检查成本低，却能避免把接口 bug 误归因于训练。
最终数据版本冻结后再运行完整评测，不能边看测试结果边增删样本。开发阶段发现的问题进入下一数据版本，封闭测试只用于一次选择。这样才能估计未见任务能力，而非衡量团队对固定题目的调参程度。