hax 后台任务与子代理委派:如何并行驱动多个 AI 编程任务不卡死终端
hax 后台任务与子代理委派:如何并行驱动多个 AI 编程任务不卡死终端
hax 是一个用 C 编写的极简终端原生 AI 编程代理(coding agent)。它内置了「后台任务」与「子代理委派」两套并行机制:长命令会自动脱离为受管后台任务,模型还能再拉起多个 hax -p 子进程作为子代理(subagent),让测试、构建、代码审查等多条 AI 工作线并行推进,而终端始终可以输入、不被阻塞。
上图是 hax 在本地 llama.cpp 模型下的典型界面:流式 Markdown、工具调用与上下文用量一目了然。
为什么终端不会卡死:hax 的 3 层并行设计 ⚡
hax 的 bash 工具执行任何命令时,只要命令"跑超了",就不会杀掉它,而是把它接管为后台任务(task)。整个过程分三层:
- 脱离(detach):命令的整个进程树、输出管道、磁盘 spool 文件一并移交给任务注册表,工具调用立即返回,终端回到输入状态;
- 独立 drainer 线程:每个任务有一条专属后台线程持续把管道里的输出泵入 spool 文件,主循环完全不被占用(实现见 src/tools/task_registry.h、src/system/bg_job.h);
- 通知代替轮询:任务完成时,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 续聊」把子代理委派管得井井有条。对长构建、并行测试、多路审查这类场景,这套机制是终端派工作流的实用加速器。
