RH
RouterHub AI API 中转站导航与平台推荐
博客

Deep Agents 命令超时后如何保住输出

0.7.40 把超时前的标准输出与错误输出带回结果,排障时还要区分取消清理、自定义 execute 和 Windows 子进程的边界。

muchacha 2026-11-19 02:22:05

正文

超时不该只剩一句错误提示

Deep Agents 0.7.40 修复了本地 shell 命令超时后诊断输出丢失的问题:LocalShellBackend 会把已经捕获的标准输出和错误输出放回超时结果,并清理命令进程。对正在构建编码代理的开发者,直接影响是能从最后一段日志判断命令卡在哪里,而不是看到超时就盲目加长等待时间或再启动一次。

这项变化来自 2026 年 11 月 18 日的官方发布说明,以及同一版本纳入的两个修复:保留超时输出和清理被取消的 shell 命令。下述实现细节按 0.7.40 的固定版本源码核对,来源获取日期为 2026 年 11 月 19 日。它不是模型推理能力更新,也不改变远程模型 API 的超时策略。

需要把两件事分开理解。超时结果保留日志,不代表命令成功;调用方取消了等待,也不代表所有子进程都已经结束。 返回字段、执行平台和是否覆写后端方法,决定了应用应该怎样处理下一步。

先确认超时发生在哪一层

假设代理运行测试命令,测试程序先打印“准备完成”,随后卡住。旧实现的超时响应只给出等待期限和重试提示;输出保留修复则在错误说明之后增加 Output before the timeout:,附上已经读到的命令输出。错误输出仍按行添加 [stderr] 前缀,超时结果的 exit_code 仍为 124。

这里的 124 是后端生成的超时标记,不是测试程序主动返回的业务状态。应用应先检查 exit_code,再用 output 辅助诊断,不能因为输出里有“完成”或某个成功词就把整次调用判为成功。如果 truncated 为真,模型和操作者都需要知道日志不是完整内容,不能把缺少某行记录当作程序没有执行到那里。

还要检查调用链。模型请求超时、HTTP 响应体空闲超时和本地 shell 执行期限,不是同一个计时器。Cline 本地模型超时的排查文章讨论的是网络响应读取;这里讨论的是代理通过本地后端执行操作系统命令。调整模型端点、关闭网络空闲计时,不能修复本地命令的进程清理或日志保留问题。

排障时可以先保存四项信息:已安装的 Deep Agents 版本、后端实际类型、调用的是 execute 还是 aexecute、是否传入命令级 timeout。再判断看到的是后端返回的超时结果,还是外层协程抛出的取消异常。不要只凭界面上的“请求超时”四个字选择修法。

输出为什么要在终止后再收集

官方修复不仅把异常里的文本拼回响应,还调整了 POSIX 输出读取流程。执行期间和终止后的收尾使用同一个读取器,因此正常运行时已经捕获的内容与终止后仍留在管道中的字节,可以汇集成同一份快照。最后再生成超时结果,避免取消检查过程反复复制累积输出。

这解释了一个容易忽略的边界:“保留输出”指后端确实捕获到的内容,不是保证恢复程序曾经想打印的所有内容。 程序自己的用户态缓冲区尚未刷新时,后端没有可读字节;进程被终止,也不能凭空补回这部分日志。制作验收命令时,应使用会立即刷新输出的程序,或显式刷新缓冲区,避免把程序缓冲误判为框架丢日志。

超时还可能切断一个多字节字符。0.7.40 的修复在处理不完整或无效输出时使用替换解码,避免一个解码错误掩盖真正的超时原因。这不是对原始字节的无损还原;如果需要保存二进制诊断数据,应让命令把它写入独立文件,而不是依赖工具响应中的文本。

标准输出和错误输出也不是完整的时间线。该后端分别捕获两个流,再把标准输出与带前缀的错误输出合并。[stderr] 能说明内容来自哪个流,不能证明两段内容的精确交错顺序。定位并发任务时,建议由程序在日志中自行写入阶段或任务标识。

输出大小限制仍然生效。超时前的输出经过与正常结果相同的合并与截断处理,truncated 会反映这一点。不要为了看到更多日志就无限放大输出上限:Python 的官方 subprocess 文档明确提醒,管道通信会把读取的数据缓冲在内存中,不适合无限输出。返回文本的截断上限,也不等于给子进程或整个执行过程设置了内存硬限制。

用不调用模型的命令验收

可以直接调用后端,先把模型、联网和工具选择排除在外。下面是根据官方回归测试整理的 POSIX 本地验收示例,只打印文本并等待,不修改项目文件。它是供读者复现的行为检查,不是供应商成功率或延迟评测。

在独立虚拟环境安装指定版本:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "deepagents==0.7.40"

保存为 check_shell_timeout.py,然后在这个虚拟环境运行:

import asyncio
import tempfile

from deepagents.backends import LocalShellBackend

command = 'printf "progress line\\n"; printf "error line\\n" >&2; sleep 10'


def check(result):
    assert result.exit_code == 124
    assert "timed out" in result.output
    assert "Output before the timeout:" in result.output
    assert "progress line" in result.output
    assert "[stderr] error line" in result.output
    assert result.truncated is False
    print(result.output)


with tempfile.TemporaryDirectory() as directory:
    backend = LocalShellBackend(
        root_dir=directory,
        env={"PATH": "/usr/bin:/bin"},
        max_output_bytes=100_000,
    )
    check(backend.execute(command, timeout=1))
    check(asyncio.run(backend.aexecute(command, timeout=1)))

这里检查的不是“运行用了几秒”,而是同步与异步命令级超时都能返回错误标记、进度文本和错误输出。官方回归测试还覆盖了输出截断、终止期间补读管道字节、换行归一化和不完整字符处理。需要升级团队封装时,可以把这些场景转成自己的回归用例。

如果断言失败,先确认实际安装版本以及是否使用内置 LocalShellBackend。然后检查封装层有没有重建结果、只保留错误说明、覆盖输出字段,或把外层取消异常误当成命令级超时。不要一开始就更换模型,后端直接调用已经足以区分这类问题是否与模型请求有关。

取消等待不等于得到超时结果

命令级 timeout 到期会产生 ExecuteResponse,其中有 exit_code、output 和 truncated。外部取消 aexecute 的任务则不同:内置执行路径会发出取消信号,尝试清理进程,随后继续向调用方抛出 asyncio.CancelledError。不能把这条路径当成必然返回 124 的普通工具结果。

0.7.40 针对尚未启动的内置任务也做了处理:如果取消先发生,排队中的命令不应再启动。已经运行的命令则走有界清理。应用应同时验收“尚未执行就取消”和“执行中取消”,因为只测试接口很快返回,无法证明后一种情况没有遗留进程。

另一个关键条件是方法身份。只有 type(self).execute is LocalShellBackend.execute 成立时,才使用新的内置异步取消清理路径。子类如果没有改写 execute,可以继续走这条路径;如果改写了,即使内部调用 super().execute,异步调用仍保留原先的线程委托方式,取消等待可能留下正在运行的命令。

这并不意味着覆写方法一定会丢掉超时日志。覆写后调用父类执行,仍可能拿到父类生成的超时响应;变化在于外部取消时,框架没有擅自替换自定义执行方法的行为。升级时不要为了触发身份判断而移除原有命令限制或审计逻辑,应为自定义后端单独设计取消契约。

对于有副作用的工具,取消后还要记录执行是否开始、是否确认结束、是否允许重试。可以参照Agent Framework 的 MCP 客户端生命周期理解“停止调用”和“释放所拥有资源”为什么必须分别检查,但具体 shell 进程规则仍应按 Deep Agents 的实现验收。

POSIX 与 Windows 的清理边界

在 POSIX 系统,内置后端会为命令创建新会话,超时、中断和内置异步取消会尝试终止该命令的进程组。终止、可选的输出补读和进程回收共享一秒的清理期限。这是源码中的清理预算,不是所有命令的性能承诺,也不保证外层应用恰好在命令期限到达时立即退出。

进程组也不是万能的后代追踪器。后代进程如果自行创建新会话或新进程组,就可能离开被清理的范围。不能据此声称“升级后所有后台进程都会被杀掉”。源码还明确区分了 nohup:它本身不会改变进程组,也不能抵御对该组发送的 SIGKILL。

Windows 的边界更窄。清理直接终止 shell 进程,并不保证结束它启动的所有后代;后代继承的输出句柄也可能让管道继续保持打开。超时响应因此会提醒,shell 已停止,但它启动的进程可能仍在运行。不要把 POSIX 回归测试通过,当作 Windows 进程树清理也已通过。

如果后端不能确认命令被停止,结果会出现可能仍在运行的警告,并提醒重新执行可能启动第二份命令。应用应将这类警告提升为人工检查条件,尤其不能自动重跑部署、数据迁移或写入外部系统的命令。只有确认前一次执行状态,并验证操作具有幂等性,才讨论重试策略。

日志修复不是安全沙箱

这次更新改善的是诊断与生命周期,不是隔离能力。官方后端文档明确指出,LocalShellBackend 允许命令以运行用户的权限直接操作宿主机;root_dir 决定工作目录,virtual_mode=True 对文件工具有路径语义,却不能限制 shell 访问系统中的其他路径。

因此,本地验收应放在专用开发环境,避免继承生产凭证;代理执行前仍需人工审批策略。面对不可信输入、共享服务或多租户代码执行,应选择有实际隔离能力的执行环境,而不是把“超时会清理”当作安全边界。

还要留意文档版本差异。获取时,综合后端文档的工作原理段落仍写着 subprocess.run(shell=True),而 0.7.40 的固定版本源码已经使用 subprocess.Popen 管理启动、输出读取和回收。综合文档适合确认后端职责与安全限制;讨论这次修复的细节,应以发布说明、修复记录及对应提交的源码为准。

最终验收标准可以归为三项:超时返回是否保留了实际捕获的日志,取消是否按真实后端类型传播并清理,以及未确认结束的命令是否被阻止盲目重试。把这三项分开,才能避免“日志回来了”掩盖进程仍在执行的问题。

参考来源