Corral Vibe 项目

项目简介

Corral 是一款专注于解决 AI 编程 Agent 和 CI 任务中"进程残留"问题的 Rust 工具。它的使用场景非常明确：当你在终端运行一条命令（包括 AI Agent 自行生成的命令）时，该命令的子进程常常在命令结束后继续存活——daemon 化进程、双 fork 场景、或忽略 SIGTERM 的顽固程序——导致端口占用、文件锁未释放、CPU 持续消耗，直接污染下一次运行环境。Corral 在命令执行完毕后强制确保整个进程树完全终止，然后再退出，从根本上杜绝了这种"幽灵进程"污染。

核心功能

• 完整进程树清理：不仅终止直接子进程，还通过 Linux pidfd 机制追踪并终止所有后代进程
• cgroup v2 强制模式：在内核层面通过 cgroup.kill 一次性杀死 cgroup 内所有进程，需要 Linux 5.14+
• Fallback 无特权模式：不支持 cgroup 的环境下，通过遍历 /proc 查找残留进程并发送信号
• 超时控制：--wall 参数设置命令执行时间上限，超时后先发 SIGTERM，优雅等待 2 秒后强制 SIGKILL
• 内存与进程数限制：enforced 模式支持 --mem 和 --pids 参数，防止失控进程撑爆系统资源
• 输出流量控制：--max-output 限制 stdout 和 stderr 的总字节数，防止日志炸弹
• JSON 审计记录：--json 参数将每次运行的完整生命周期写入审计文件，供后续分析使用
• 差异化退出码：120=残留进程未完全终止、124=超时、121=内存超限、122=输出超限，精准表达失败原因

技术实现

Corral 的实现完全基于 Rust 语言，核心使用了 Linux 5.11+ 引入的 pidfd API。在 enforced 模式下，命令运行在独立的 cgroup v2 组内，当需要终止时只需一次 write(cgroup.kill) 系统调用，内核即可强制杀死组内所有进程，无需逐个查找进程树。

在不支持 cgroup 的环境中，Corral 实现了一个"子进程再收养"（child subreaper）机制：将自己设置为子进程收割者，这样孤儿进程会变成 Corral 的子进程，然后通过遍历 /proc 目录找到所有进程并向残留进程发送信号。整个过程在 --verify-timeout（默认 2 秒）内完成，如果超时则退出码返回 120 并报告哪些进程未能停止。

Corral 不提供任何安全沙箱能力（不限制文件访问、网络访问或权限），它是纯粹的进程生命周期管理工具，职责单一而专注。

快速上手

• 下载预编译二进制（Linux x86_64）：

  curl -LO https://github.com/Cardinal44/corral/releases/latest/download/corral-linux-x86_64.tar.gz
  tar -xzf corral-linux-x86_64.tar.gz
  sudo cp corral-linux-x86_64/corral /usr/local/bin/

• 编译安装（需 Rust 工具链）：

  cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
  cmake --build build && ctest --test-dir build --output-on-failure

• 基本使用：corral --wall 30s -- ./build.sh
• 带资源限制：corral-enforced --wall 5m --mem 512M --pids 64 -- ./build.sh
• 生成审计记录：corral --wall 5m --max-output 1M --json run.json -- make test
• 配置为 CI 工具钩子：将 corral --wall 前缀加到任意构建命令前即可

适用人群

• 使用 AI 编程 Agent（Claude Code、Cursor、Codex 等）并遇到"进程幽灵"困扰的开发者
• CI/CD 管道工程师，需要确保每个 Job 结束后系统状态干净
• 安全研究人员，需要隔离执行不可信代码但不需要完整沙箱的场景
• 运维工程师，管理长期运行的多阶段构建脚本，需要防止进程泄露积累