Long-Running Task Handler
适用场景
Hermes Agent 的 terminal 默认 timeout=180 秒,delegate_task 受父会话迭代限制。当用户下达以下类型任务时必须使用本 skill:
- 大型代码重构 / 编译 / 测试全量运行(>2分钟)
- 多步骤安装(brew install、pip install large packages)
- 批量文件处理(>50 个文件)
- 远程数据下载/API 批量请求
- 长时间代理任务(飞书群消息批量发送等)
核心模式:三步走
第一步:预估耗时
# 快速预检任务规模
import os, subprocess
lines = subprocess.run(['wc', '-l', 'target/file.py'], capture_output=True, text=True)
# 如果是大型任务,直接进"异步执行"模式
第二步:异步执行(不阻塞当前会话)
# 模式 A:terminal background + notify_on_complete
result = terminal(
command="hermes chat -q '你的任务描述'",
timeout=600, # 前台最大600
background=True,
notify_on_complete=True
)
# 模式 B:长命令直接 background
result = terminal(
command="python3 huge_script.py && echo DONE",
timeout=600,
background=True,
notify_on_complete=True
)
# 模式 C:设置 watch_patterns 实时看进度
result = terminal(
command="python3 build_script.py",
background=True,
watch_patterns=["Step", "Progress", "Complete"]
)
第三步:超时重试
# 如果 terminal timeout 了,用 subprocess 跑更长时间
import asyncio, subprocess
process = await asyncio.create_subprocess_shell(
command,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.PIPE,
)
try:
stdout, stderr = await asyncio.wait_for(
process.communicate(), timeout=900 # 15分钟
)
except asyncio.TimeoutError:
process.kill()
return {"error": "timeout", "partial_output": ...}
配置优化
当有长时间任务需求时,先检查并调优以下配置:
# 1. terminal timeout (默认180 → 调高到600)
hermes config set terminal.timeout 600
# 2. delegation max_iterations (默认50 → 调高)
hermes config set delegation.max_iterations 120
# 3. 如果常超时,加 Hermes 内置配置
hermes config set agent.max_tool_uses 999 # 已足够
hermes config set agent.max_messages 120 # 给更多轮次
进阶:Nohup 模式(真正独立进程)
Hermes 进程可能被杀,所以需要完全独立的进程:
nohup bash -c 'cd /path/to/proj && python3 script.py > /tmp/long_task.log 2>&1' &
echo "PID: $!"
然后定时轮询状态:
tail -5 /tmp/long_task.log
ps -p $PID -o pid,state,%cpu,%mem,etime
已知陷阱
- 不要盲目调高 timeout:600 秒是 foreground 上限,超过必须用 background
- background 模式必须设 notify_on_complete:否则任务静默跑完后你不知道
- delegate_task 超时:子 agent 默认 50 次迭代,如果任务太长它会自动停止——用
terminal background代替 - 不要在长时间任务中做复杂的上下文:任务描述越精确越好,子 agent 没你的上下文历史
- process(wait) 上限 300 秒,静默 clamp(2026-10-25 实测):
process(action='wait', timeout=N)的 N 会被截到 300s(请求 590 返回 "Requested wait of 590s was clamped to configured limit of 300s",不报错)。大于 5 分钟的任务不要指望一次 wait 等完——循环调wait(timeout=300)直到 status=exited,或干脆靠 notify_on_complete 回调。实测 112MB GitHub APK 下载 18 分钟:background curl + notify_on_complete 起任务,期间 3 次 wait(300) 看 curl 进度行百分比即可,最后 wait 返回 exited + 完整输出。 - 大文件下载三步验收:
curl -L --fail --retry 3 -o下载完成后,file验格式 +unzip -l验包结构(APK/jar/zip 看有没有 manifest/dex/classes)+shasum -a 256记指纹。只看 curl exit 0 不够——网络中间层可能给HTML错误页。 - 「下载完成」误报(2026-10-25 DSHBox APK 实痛):上一轮会话已报「下载完成 45MB」,本轮用户来要文件时实测该后台 curl 仍在下载(先后读到 69M/93.8M/96.9M 三个"完成值")。验收铁律:①
ps aux | grep curl确认无下载进程存活;② 间隔 ≥5s 两次 stat 大小一致;③ 与官方源核对字节数(GitHub:api.github.com/repos/<o>/<r>/releases/tags/<tag>→assets[].size)。历史会话说"完成"不算数——跨会话续接下载任务时一律重新验。
重启/中断后续接(Resume-after-restart,2026-09-04 验证)
华哥的 Mac 可能随时重启,长任务被腰斩后用户会说"继续刚才的任务"。标准续接流程:
- 重建任务上下文:
session_search(query=<上一条已发消息的特征词>, sort=newest)找到中断会话。锚点消息 + 周边工具调用记录能精确还原"做到哪一步"——不要凭记忆猜进度。 - 盘点磁盘产物:重启不丢文件。先
ls/读项目目录,已落盘的成品和半成品全部有效,不要重做。重点检查崩溃前正在写的那份文件是否完整(看结尾结构/时间戳)。 - 进程归零认知:重启后所有后台进程、codex exec、容器全部消失(
pgrep确认),不存在"接着跑"的后台任务——只有"重跑哪一步"的问题。 - 定位断点 → 只补缺口:对比"最后一条已交付消息承诺的下一步"与"磁盘上已有的产物",差什么补什么。从任务起点重做会浪费 token 且可能覆盖已有成果。
- 汇报结构:先给"重启损失盘点"表(什么完好/什么断了)→ 已续上的部分 → 剩下需要用户拍板的决策点。让用户一眼看到零损失或明确损失。