智能命令行工具的运行止损线

智能命令行工具的运行止损线

命令行里的 Agent 一旦接触文件、网络或外部服务，就不能只考虑“任务能否完成”。连续失败时，它可能反复读取同一批数据，也可能把同一条写命令执行多次。此时继续尝试通常不会带来新信息，反而会扩大影响。比提高成功率更紧迫的事，是让程序知道何时停下来。

我会先按副作用区分工具。查看状态、读取配置属于只读操作；修改文件、发送请求和触发部署则可能改变外部状态。两类工具不能共用一条宽松的重试规则。只读命令在错误明确且任务还有时间预算时可以有限重试，写操作则要先确认上一次是否已经成功，还要有幂等标识或人工确认。否则，超时只代表客户端没有收到结果，并不代表服务端没有执行。

次数上限只是最后一道闸

给工具调用设置上限很有必要，但上限不是随手填下的魔法数字。它应同时考虑任务类型、单次调用成本、剩余时间以及失败是否可能自行恢复。参数错误、权限拒绝和输出校验失败，原样重试通常没有意义；网络短暂中断或服务明确返回可重试状态，才值得在预算内再试。

下面的配置表达的是一种控制关系：达到调用上限后，把决定权交还给人，而不是让 Agent 自己修改目标、扩大搜索范围或继续派生任务。

max_tool_calls = 3
on_exceeded = "ask_human"

具体上限需要通过真实任务回放来定。更稳妥的实现还会给整项任务设置总时限和资源预算。即使调用次数没有耗尽，只要用户已经取消、上游上下文失效，或者任务进入无法判定的状态，也应立即停止。停止后要返回清楚的原因：卡在哪个工具、发生了哪类错误、哪些动作已经确认完成、哪些动作状态未知。单独一句“执行失败”会把最困难的判断留给用户。

写操作要防止重复落地

最危险的情况不是命令报错，而是命令实际成功、回执却在途中丢失。Agent 如果据此再次执行，可能重复创建资源、重复发送内容或覆盖新状态。解决办法不是盲目增加重试，而是在调用前生成任务标识，在调用后查询结果；无法确认时，进入待人工核对状态。

执行计划也应在真正写入前展示关键参数。路径要解析为明确目标，通配符和环境变量不能在最后一刻才展开。涉及删除、覆盖、发布等动作时，程序应把目标和影响范围交给用户确认。模型可以提出命令，但是否执行仍由确定的规则和权限层决定。

日志只留下排查需要的内容

失败事件可以记录工具名、错误类别、调用序号、耗时区间和时间窗口，但不应默认收集任务正文、完整命令参数或环境变量。很多命令行任务会接触仓库地址、文件内容和访问凭据，把这些原样写进日志，等于把一次运行故障变成新的信息泄露入口。

错误信息也要做分层。用户看到的是可操作提示，维护者拿到的是脱敏后的诊断字段。若确实需要采集样本，应先缩小到能够复现问题的最少内容，并说明保存位置和清理时间。这样既能排查，也不会让调试材料无限堆积。

恢复前先确认现场

解除止损不能只看工具重新可用。先检查此前的写操作有没有留下部分结果，再用同一组脱敏案例复跑只读路径、失败路径和取消路径。确认调用次数会收敛、取消后不再产生新命令、重复请求不会重复写入，才逐步恢复自动执行。

限流解决的是影响扩散，不是根因。恢复后仍要回看提示词是否让任务边界不断扩大，工具权限是否过宽，错误分类是否把不可重试问题判成了临时故障。一次止损记录至少应留下触发条件、已执行动作、未知状态和恢复依据。下次再遇到类似问题，团队才能从证据继续判断，而不是重新猜一遍。