hax 后台任务与子代理委派:如何并行驱动多个 AI 编程任务不卡死终端

原创2026-10-23 17:47:072,130 阅读

hax 后台任务与子代理委派:如何并行驱动多个 AI 编程任务不卡死终端

hax 是一个用 C 编写的极简终端原生 AI 编程代理(coding agent)。它内置了「后台任务」与「子代理委派」两套并行机制:长命令会自动脱离为受管后台任务,模型还能再拉起多个 hax -p 子进程作为子代理(subagent),让测试、构建、代码审查等多条 AI 工作线并行推进,而终端始终可以输入、不被阻塞。

hax 终端 AI 编程代理并行后台任务与流式 Markdown 输出界面

上图是 hax 在本地 llama.cpp 模型下的典型界面:流式 Markdown、工具调用与上下文用量一目了然。

为什么终端不会卡死:hax 的 3 层并行设计 ⚡

hax 的 bash 工具执行任何命令时,只要命令"跑超了",就不会杀掉它,而是把它接管为后台任务(task)。整个过程分三层:

  1. 脱离(detach):命令的整个进程树、输出管道、磁盘 spool 文件一并移交给任务注册表,工具调用立即返回,终端回到输入状态;
  2. 独立 drainer 线程:每个任务有一条专属后台线程持续把管道里的输出泵入 spool 文件,主循环完全不被占用(实现见 src/tools/task_registry.h、src/system/bg_job.h);
  3. 通知代替轮询:任务完成时,hax 会在下一轮模型请求前注入一行状态通知(completion note),模型"听到"即可完成,无需 sleep 或轮询(见 src/agent_loop.c 与 src/agent_env.c)。

这套设计的直接效果是:终端 UI 保持响应,模型上下文保持干净,多个耗时任务互不干扰。

后台任务:3 种创建方式

hax 的 bash 工具(src/tools/bash.c)提供 3 种进入后台任务的途径:

方式 触发条件 说明
超时自动脱离 前台命令超过 bash.timeout(默认 2 分钟) 不杀进程,附注 [detached as task tN after 2m timeout]
显式后台 模型传 background: true 等待 bash.background_yield(默认 5 秒)初始输出窗口后脱离
快速命令短路 显式后台但 5 秒内就结束 直接同步返回,不产生任务

两个实用细节:

  • 命名任务:可传 name 参数(字母/数字/-/_,最长 32 字符,如 tests),得到可读的任务 id 而非 t1、t2;
  • 并发上限:task.max_running 默认 32(最高 64),超限会拒绝并要求先 wait 或 kill,防止失控。

若设置 no_tasks 为开,则回到传统行为:超时直接杀掉命令。

任务管理:查看、收集、停止

查看:在 REPL 输入 /tasks,列出所有任务的 id、状态(running / exit N / signal N)、已运行时长与命令摘要(渲染逻辑见 src/commands/tasks.c)。

收集:模型侧使用 task_wait 工具(src/tools/task_wait.c):

  • id:要等待的任务(如 t1);
  • timeout_seconds:等待上限,默认取 task.wait_timeout(10 分钟);
  • kill:置为真时发送 SIGTERM → 宽限期 → SIGKILL,并返回其最终输出。

task_wait 还有两个贴心的行为:对已完成的任务立即返回(顺带收集剩余输出);别的任务先完成时会提前结束等待,让模型马上响应那条完成通知。

停止:用户侧直接 /tasks kill t1 或 /tasks kill all。

生命周期:任务不脱离 hax 进程独立存活——离开当前会话或退出时,剩余进程树全部被清理(src/tools/task_registry.h);one-shot(-p)模式下,最终答案产生后没人等待的任务也会被停止。每个任务的完整输出始终有磁盘 spool 文件兜底,超限丢弃的内容也能从那里找回。

子代理委派:让 hax 再拉起一个 hax 🚀

当用户明确要求"用子代理"时,hax 会通过 bash 工具执行 hax -p "<任务>":在干净上下文中启动一个全新 hax 实例,最终答案打印到 stdout(委派指引见 src/agent_env.c)。要点如下:

  • 继承配置:子进程默认继承父会话的 provider、model、effort,零额外配置;
  • 并行委派:以 background: true 同时启动多个子代理,各自作为后台任务运行,最后统一 task_wait 收集答案——这是"多路并行 AI 编程"的核心用法;
  • 预设即角色:config.json 中带 description 的 preset 会被广告给模型,成为具名委派角色。例如定义一个 review 角色(provider 换成 codex、高 effort、追加审查指令),模型就只知道"review:彻底代码审查"这一个角色名;仅收藏用途的 preset 不会暴露给模型(docs/configuration.md);
  • 防递归:通过 HAX_SUBAGENT_DEPTH 环境变量传递层级,最多 3 层(src/tools/bash_env.h、src/cli.c),触顶即要求直接干活;
  • 可续聊:子进程启动时把 session id 打到 stderr,之后可用 hax --resume=<id> -p "<追问>" 对已结束的子代理继续发问。

官方文档的建议很克制:委派只留给彼此独立、受益于并行上下文的工作(见 docs/usage.md)——普通小任务在单会话里做更快更省。

关键配置速查 📌

完整说明见 docs/configuration.md:

配置项 默认值 作用
bash.timeout 2m 前台命令默认超时,超时后脱离为任务
bash.background_yield 5s 显式后台脱离前的初始输出窗口
bash.timeout_grace 2s SIGTERM 到 SIGKILL 的宽限期
task.wait_timeout 10m task_wait 默认等待上限
task.max_running 32 并发后台任务上限(最高 64)
no_tasks off 关闭后台任务,超时改为杀命令
no_subagents off 从系统提示中移除委派指引

动手体验:官方后台任务演示脚本 🎬

仓库自带一个 mock 演示脚本 scripts/mock/tasks.txt,完整走一遍任务生命周期:并行启动 tests 与 lint 两个流式任务、等待其中一个时另一个完成并打断等待、超时脱离、kill 收集、以及"你发消息后才到达的完成通知"。运行方式(仓库根目录):

HAX_PROVIDER=mock HAX_MOCK_SCRIPT=scripts/mock/tasks.txt build/hax

配合 HAX_BASH_BACKGROUND_YIELD=500ms 可让演示节奏更快。

常见问题 FAQ

Q1:关掉 hax 后,后台任务还活着吗? 不会。子 shell 在独立会话中运行并注册了父进程死亡信号,hax 退出(包括被 SIGKILL/OOM)时,命令的整个进程树随之终止,不会留下孤儿进程。

Q2:这和 shell 里的 & 后台执行有什么区别? & 只是让 shell 先返回,输出、进程组、上限、模型感知都要自己管。hax 接管了进程树、spool 文件、并发上限与完成通知,任务对模型是一等公民:可等待、可 kill、可列出(/tasks),且绝不轮询。

Q3:本地模型能用吗? 可以。截图即来自 llama.cpp provider 的 Qwen3 本地模型会话;后台任务与子代理机制在 provider 层之下,与选择哪个模型无关。

小结

hax 用「超时自动脱离 + 每任务 drainer 线程 + 完成通知」三件套,让终端在多个 AI 编程任务并行时依然流畅;再用「预设角色 + 深度上限 + --resume 续聊」把子代理委派管得井井有条。对长构建、并行测试、多路审查这类场景,这套机制是终端派工作流的实用加速器。

登录后查看全文
hax