pueue-job-orchestration

Pueue 任务编排

通用 CLI 遥测层和任务管理——通过 pueue 路由的每条命令都会获得精确的计时、退出代码捕获、完整的 stdout/stderr 日志、环境快照，以及完成时回调。

自我进化的技能：此技能会在使用过程中持续改进。如果指令有误、参数发生变化，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

概述

Pueue 是一个用于管理 Shell 命令队列的 Rust CLI 工具。它提供：

• 守护进程持久运行——SSH 断开连接、崩溃或重启后仍可继续运行
• 基于磁盘的队列——出现任何故障后都会自动恢复
• 基于组的并行处理——控制每个组中的并发任务数
• 轻松恢复失败任务——使用一条命令重启失败任务
• 完整遥测——记录每个任务的计时、退出代码、stdout/stderr 日志和环境快照

何时通过 Pueue 路由

操作	是否通过 Pueue 路由？	原因
任何运行时间超过 30 秒的命令	始终	遥测、持久运行、日志捕获
批量操作（超过 3 项）	始终	并行控制、故障隔离
构建/测试流水线	建议	--after DAG、组监控
数据处理	始终	检查点恢复、状态管理
快速的一次性命令（少于 5 秒）	可选	开销约为 100 毫秒，但可以获得日志
交互式命令（编辑器、REPL）	绝不	Pueue 无法处理 stdin 交互

何时使用此技能

当用户提到以下内容时使用此技能：

触发条件	示例
在 上运行任务	“在 上运行此任务”
长时间运行的数据处理	“为所有代码填充缓存”
批量/并行操作	“处理这 70 个任务”
SSH 远程执行	“今晚在 GPU 服务器上执行此操作”
填充缓存	“填充 ClickHouse 缓存”
Pueue 功能	“设置回调”“延迟此任务”

快速参考

检查状态

# Local
pueue status

# Remote (<gpu-host>)
ssh <gpu-host> "~/.local/bin/pueue status"

将任务加入队列

# Local (with working directory)
pueue add -w ~/project -- python long_running_script.py

# Local (simple)
pueue add -- python long_running_script.py

# Remote (<gpu-host>)
ssh <gpu-host> "~/.local/bin/pueue add -w ~/project -- uv run python script.py"

# With group (for parallelism control)
pueue add --group p1 --label "BTCUSDT@1000" -w ~/project -- python populate.py --symbol BTCUSDT

监控任务

pueue follow <id>         # Watch job output in real-time
pueue log <id>            # View completed job output
pueue log <id> --full     # Full output (not truncated)

管理任务

pueue restart <id>         # ⚠ Creates NEW task (see warning below)
pueue restart --in-place <id>  # Restarts task in-place (no new ID)
pueue restart --all-failed # ⚠ Restarts ALL failed across ALL groups
pueue kill <id>            # Kill running job
pueue clean                # Remove completed jobs from list
pueue reset                # Clear all jobs (use with caution)

严重警告——pueue restart 的语义：

pueue restart <id> 不会在原位置重启任务。它会创建一个 ID 全新的任务，并复制原任务的命令。原任务仍会保持 Done/Failed 状态。在循环或自主 Agent 中使用时，这会导致任务数量呈指数级增长。在 2026-03-04 的一次事故中，Agent 调用 pueue restart 重启失败任务，导致任务数从 60 个增至约 12,800 个。

• 确实需要重启时使用 --in-place：pueue restart --in-place <id>
• 重启前先验证：读取 pueue log <id>，检查故障是否持续存在（数据缺失、参数错误）——重试永远无法解决这类问题
• 不要在未使用 --group 筛选的情况下使用 --all-failed——这会重启所有组中的每个失败任务

主机配置

主机	位置	GPU	并行组
	~/.local/bin/pueue	RTX 4090	p1 (16), p2 (2), p3 (3), p4 (1)
gpu-host-2	~/.local/bin/pueue	RTX 2080 Ti	p1 (8), p2 (2)
本地（macOS）	/opt/homebrew/bin/pueue	不适用	default

核心工作流

1. 加入单个远程任务

# Step 1: Verify daemon is running
ssh <gpu-host> "~/.local/bin/pueue status"

# Step 2: Queue the job
ssh <gpu-host> "~/.local/bin/pueue add --label 'my-job' -- cd ~/project && uv run python script.py"

# Step 3: Monitor progress
ssh <gpu-host> "~/.local/bin/pueue follow <id>"

2. 批量提交作业（多个标的）

用于 rangebar 缓存填充或类似的批量操作：

# Use the pueue-populate.sh script
ssh <gpu-host> "cd ~/rangebar-py && ./scripts/pueue-populate.sh setup"   # One-time
ssh <gpu-host> "cd ~/rangebar-py && ./scripts/pueue-populate.sh phase1"  # Queue Phase 1
ssh <gpu-host> "cd ~/rangebar-py && ./scripts/pueue-populate.sh status"  # Check progress

3. 配置并行组

# Create groups with different parallelism limits
pueue group add fast      # Create 'fast' group
pueue parallel 4 --group fast  # Allow 4 parallel jobs

pueue group add slow
pueue parallel 1 --group slow  # Sequential execution

# Queue jobs to specific groups
pueue add --group fast -- echo "fast job"
pueue add --group slow -- echo "slow job"

4. 处理失败的作业

# Check what failed
pueue status | grep Failed

# View error output FIRST (distinguish transient vs persistent)
pueue log <id>

# Restart specific job IN-PLACE (no new task created)
pueue restart --in-place <id>

# ⚠ NEVER blindly restart all failed — classify failures first
# pueue restart --all-failed  # DANGEROUS: no group filter, creates duplicates

重启前的失败分类：退出代码 1（应用错误）可能是持久性问题（缺少数据、参数错误——永远不会成功）。退出代码 137（OOM）或 143（SIGTERM）可能是暂时性问题。重启前务必查看 pueue log。

故障排除

问题	原因	解决方案
pueue: command not found	不在 PATH 中	使用完整路径：~/.local/bin/pueue
Connection refused	守护进程未运行	使用 pueued -d 启动
作业卡在 Queued 状态	组已暂停或达到上限	检查 pueue status，然后运行 pueue start
SSH 断开导致作业终止	未使用 Pueue	通过 Pueue 排队，而不是直接使用 SSH
作业立即失败	工作目录错误	使用 pueue add -w /path 或 cd /path && pueue add

优先级调度（--priority）

优先级数字越高，队列有空位时越先运行：

# Urgent validation (runs before queued lower-priority jobs)
pueue add --priority 10 -- python validate_critical.py

# Normal compute (default priority is 0)
pueue add -- python train_model.py

# Low-priority background task
pueue add --priority -5 -- python cleanup_logs.py

优先级仅影响等待空位的排队中作业。运行中的作业不会被抢占。

按任务覆盖环境变量（pueue env）

为已暂存或排队中的任务注入或覆盖环境变量：

# Create a stashed job
JOB_ID=$(pueue add --stashed --print-task-id -- python train.py)

# Set environment variables (NOTE: separate args, NOT KEY=VALUE)
pueue env set "$JOB_ID" BATCH_SIZE 64
pueue env set "$JOB_ID" LEARNING_RATE 0.001

# Enqueue when ready
pueue enqueue "$JOB_ID"

语法：pueue env set <id> KEY VALUE ——键和值是两个独立的位置参数。

限制：仅适用于已暂存或排队中的任务。无法修改运行中任务的环境变量。

与项目 .env 的关系：.env（由 python-dotenv 加载）仍是默认环境变量的 SSoT。仅在需要临时覆盖（例如超参数扫描）且不想修改配置文件时，使用 pueue env set。

阻塞等待（pueue wait）

阻塞直至任务完成——用于脚本时，比轮询循环更简单：

# Wait for specific task
pueue wait 42

# Wait for all tasks in a group
pueue wait --group mygroup

# Wait for ALL tasks across all groups
pueue wait --all

# Wait quietly (no progress output)
pueue wait 42 --quiet

# Wait for tasks to reach a specific status
pueue wait --status queued

脚本集成模式

# Queue -> wait -> process results
TASK_ID=$(pueue add --print-task-id -- python etl_pipeline.py)
pueue wait "$TASK_ID" --quiet
EXIT_CODE=$(pueue status --json | jq -r ".tasks[\"$TASK_ID\"].status.Done.result" 2>/dev/null)
if [ "$EXIT_CODE" = "Success" ]; then
    echo "Pipeline succeeded"
    pueue log "$TASK_ID" --full
else
    echo "Pipeline failed"
    pueue log "$TASK_ID" --full >&2
fi

---

配套 CLI 工具（）

四款轻量级 CLI 工具可与 pueue 搭配使用，用于监控和发送通知。均已安装在 上：noti 和 mprocs 位于 /usr/local/bin/，ntfy 和 task-spooler 通过 apt 安装。

noti — 为任意命令包装 Telegram 通知

最适合一次性的“完成后通知我”工作流。原生支持 Telegram。

# Wrap any command — sends Telegram when it finishes
noti -g moon run kintsugi:catchup

# With execution time in message
noti -g -e python long_script.py

# Custom title/message
noti -g -t "Deploy done" -m "<gpu-host> updated" moon run deploy:<gpu-host>

配置：~/.config/noti/noti.yaml，以及 ~/.bashrc 中的环境变量 NOTI_TELEGRAM_TOKEN、NOTI_TELEGRAM_CHAT_ID、NOTI_DEFAULT=telegram。

ntfy — 从脚本或回调发送推送通知

最适合从脚本、pueue 回调或 curl 单行命令发送程序化通知。

# One-liner from any script
ntfy pub --title "Backfill done" odb-alerts "BTCUSDT@500 complete"

# With priority and tags
ntfy pub --priority high --tags "warning" odb-alerts "Job failed"

# curl variant (works anywhere, no binary needed)
curl -d "Backup finished" ntfy.sh/my-topic

# Subscribe to topic (poll mode)
ntfy sub --poll odb-alerts

Pueue 回调集成——添加到 ~/.config/pueue/pueue.yml：

callback: 'ntfy pub --title "pueue: {{label}}" --tags "{{status}}" odb-alerts "Task #{{id}} {{status}} ({{command}})"'

mprocs — 多进程 TUI

最适合在交互式 SSH 会话中并排监控多个进程。

# Watch multiple pueue jobs in split panes
mprocs "pueue follow 3" "pueue follow 7" "pueue follow 8"

# Monitor services
mprocs "journalctl -fu opendeviationbar-sidecar" "journalctl -fu opendeviationbar-kintsugi"

需要交互式 TTY（直接通过 SSH 连接，而不是通过脚本）。

task-spooler（tsp）— 最简单的作业队列

最适合快速运行临时的顺序或并行任务，无需设置 pueue 组。

# Queue tasks (default: 1 parallel)
tsp python train.py
tsp python validate.py

# Set parallel slots
tsp -S 3

# List queue
tsp -l

# View job output
tsp -c 0

# Combine with noti
tsp bash -c 'python train.py && noti -g -m "training done"'

工具选择指南

Need to...
├── Get notified when a command finishes? → noti -g <command>
├── Send notification from a script/callback? → ntfy pub topic "msg"
├── Watch multiple logs/processes live? → mprocs "cmd1" "cmd2"
├── Quick sequential queue (no groups needed)? → tsp <command>
└── Persistent queue with groups, priorities? → pueue add <command>

---

深入参考资料

主题	参考资料
安装（macOS、Linux、systemd、launchd）	安装指南
生产经验：--after 链式执行、取证审计、按年份并行处理、流水线监控	生产经验
防止状态膨胀、使用 xargs -P 批量提交、两层架构（300K+ 个任务）、崩溃恢复	状态管理与批量提交
ClickHouse 线程调优、并行度计算公式、实时调优	ClickHouse 调优
回调钩子、模板变量、延迟调度（--delay）	回调与调度
python-dotenv 密钥模式、rangebar-py 集成	环境与密钥
Claude Code 集成、同步封装、遥测查询	Claude Code 集成
所有 pueue.yml 设置（共享、客户端、守护进程、配置档）	Pueue 配置参考

---

Pueue 与 Temporal：何时使用哪一个

对于需要持久性和去重的结构化、可重复工作流，可考虑 Temporal（pip install temporalio、brew install temporal）：

维度	Pueue	Temporal
最适合	临时 shell 命令、SSH 远程任务	结构化、可重复的工作流
设置	单个二进制文件，无需基础设施	服务端 + 数据库（开发环境：temporal server start-dev）
去重	无 — restart 会创建新任务	工作流 ID 唯一性（内置）
重试策略	无 — 手动或由外部 Agent 处理	按活动设置：最大尝试次数、退避、不可重试错误
并行度	pueue parallel N --group G	worker 上的 max_concurrent_activities=N
可见性	pueue status（文本形式，扩展性较差）	带分页、搜索和事件历史记录的 Web UI

建议：临时任务继续使用 pueue。当去重和重试策略变得重要时，将结构化流水线迁移到 Temporal。请参阅 devops-tools:distributed-job-safety，了解适用于两者的不变条件。

---

相关内容

• 钩子：itp-hooks/posttooluse-reminder.ts — 检测到耗时较长的命令时，提醒使用 Pueue
• 参考：Pueue GitHub
• 配套工具：noti（命令包装器 → Telegram）、ntfy（发布-订阅通知）、mprocs（多进程 TUI）、task-spooler（轻量级作业队列）
• SOTA 替代方案：Temporal — 持久化工作流编排，内置去重、重试和可观测性
• 问题：rangebar-py#77 — 原始实现
• 问题：rangebar-py#88 — 生产部署经验

执行后反思

此技能执行完成后，关闭前请检查：

1. 命令是否成功？ — 如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请更新用法示例和参数表，使其保持一致。
3. 是否需要变通处理？ — 如果你需要临时变通（使用不同的标志、增加步骤），请更新此 SKILL.md，避免下次调用时再次需要相同的变通方法。

仅在问题确实存在且可复现时更新，不要基于猜测更新。