agentic-process-monitor

Agentic Process Monitor

用于监控 Claude Code 后台进程的模式——检测成功、失败、超时和挂起的进程，然后将结果返回主上下文，以驱动下一步操作。

配套技能：devops-tools:pueue-job-orchestration（远程／排队工作）| devops-tools:distributed-job-safety（并发）

---

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

架构：哨兵 + 心跳 + Agent

Main Context                          Monitor Agent (subagent)
─────────────                         ──────────────────────
1. Start work (Bash run_in_background)
   └─ work wrapper writes sentinel files
2. Launch Agent (poll every 15s) ────► poll loop:
3. Continue other work                  .status exists? → return result
                                        .heartbeat stale? → kill, return error
                                        elapsed > max? → kill, return timeout
4. Agent returns ◄──────────────────── detected outcome
5. Act on result (next step / retry / abort)

为何采用此架构：主上下文保持精简（不会消耗轮询令牌）。子 Agent 负责所有等待工作。如果子 Agent 本身发生故障，主上下文可以直接检查哨兵文件并恢复。

---

哨兵协议

工作进程会在已知目录（例如 /tmp/<project>-monitor/）中写入 4 个文件：

文件	写入时机	用途
<step>.pid	启动时	用于超时终止的 PID
<step>.heartbeat	工作期间每隔 N 秒	修改时间新鲜度 = 存活证明
<step>.status	退出时（SUCCESS / FAILED）	完成哨兵
<step>.result	成功时	结构化输出（JSON）

工作包装器模板

#!/usr/bin/env bash
set -uo pipefail
STEP="${1:?step name required}"
MONITOR_DIR="${2:-/tmp/monitor}"
mkdir -p "$MONITOR_DIR"

echo $$ > "${MONITOR_DIR}/${STEP}.pid"

# Heartbeat: touch file every 10s in background
(while true; do touch "${MONITOR_DIR}/${STEP}.heartbeat"; sleep 10; done) &
HB_PID=$!
trap "kill $HB_PID 2>/dev/null" EXIT

# === YOUR WORK HERE ===
if your_command --args 2>"${MONITOR_DIR}/${STEP}.log"; then
    echo "SUCCESS" > "${MONITOR_DIR}/${STEP}.status"
    echo '{"key": "value"}' > "${MONITOR_DIR}/${STEP}.result"
else
    echo "FAILED" > "${MONITOR_DIR}/${STEP}.status"
fi

---

监控决策树

轮询 Agent 每隔 POLL_INTERVAL 秒检查一次（默认：15s）：

every POLL_INTERVAL:
  .status exists?
    → read status + result, return to main context
  .heartbeat exists AND mtime stale (> STALE_THRESHOLD)?
    → process hung — kill PID, return "hung" error
  elapsed > MAX_TIMEOUT?
    → timeout — kill PID, return "timeout" error
  otherwise
    → sleep POLL_INTERVAL, continue

推荐默认值

参数	默认值	原因
POLL_INTERVAL	15s	平衡延迟与令牌成本
HEARTBEAT_INTERVAL	10s	必须小于 STALE_THRESHOLD / 2
STALE_THRESHOLD	60s	心跳间隔的 6 倍，留有充足余量
MAX_TIMEOUT	1800s（30min）	捕获基础设施故障

---

熔断器

防止重复失败浪费计算资源。连续发生 3 次崩溃或失败后，停止并报告。任意一次成功后重置计数器。

consecutive_failures = 0
MAX_CONSECUTIVE = 3

on failure:
  consecutive_failures += 1
  if consecutive_failures >= MAX_CONSECUTIVE:
    STOP — likely infrastructure, not the work itself

on success:
  consecutive_failures = 0

---

Agent 自我修复

如果监控子 Agent 失败（上下文溢出、超时、崩溃），主上下文会恢复：

1. 直接检查 .status 文件——Agent 停止运行期间，工作可能已经完成
2. 如果 .status 存在 → 读取结果并正常继续
3. 如果没有 .status，但 .heartbeat 是最新的 → 启动替代监控 Agent
4. 如果没有 .status，且 .heartbeat 已过期 → 进程已挂起，终止 PID 并记录错误

这可以确保主上下文永远不会永久卡住。

---

反模式

反模式	失败原因	改用此方法
tail -f | grep -m1	在 macOS 上会出问题——管道缓冲会阻止 grep 退出并终止 tail，导致永久挂起	在循环中使用 grep 轮询日志文件，查找标记
仅使用 run_in_background	任务 ID 可能过期或无法检索；存在卡在运行状态的错误；没有中间进度	哨兵文件 + Agent 轮询
在主上下文中轮询	每次轮询都会将输出注入上下文窗口，每次检查会消耗约 50K 个 token	将轮询委派给子 Agent
硬编码 sleep 超时	快速完成时浪费时间，耗时较长时则等待时间不足	轮询间隔 + 最大超时时间
仅检查 PID 是否存活	无法区分挂起的进程（PID 存活，但没有进度）和正在运行的进程	检查心跳文件的修改时间——进程挂起后就会停止触碰该文件
uv run 掩盖过期的 venv	uv run 有自己的解析机制，会绕过损坏的 venv 状态；仓库重命名后，控制台脚本（pytest、ruff）的 shebang 会过期	仓库重命名或移动后，运行 uv sync --python 3.14 --extra dev

---

环境预检

进入任何自主循环前运行。如果任一检查失败，请先修复再继续。

# 1. Python package importable?
uv run --python 3.14 python -c "import your_package" \
  || uv sync --python 3.14 --extra dev

# 2. Console scripts have valid shebangs? (catches post-rename breakage)
uv run --python 3.14 pytest --co -q tests/ 2>/dev/null \
  || uv sync --python 3.14 --extra dev

# 3. External service reachable?
curl -sf "http://localhost:PORT/?query=SELECT+1" \
  || echo "FAIL: start service or SSH tunnel"

常见 uv/venv 故障

症状	根本原因	修复方法
出现 ModuleNotFoundError，但 uv run python -c "import ..." 可运行	venv 过期——控制台脚本的 shebang 指向旧仓库路径	uv sync --python 3.14 --extra dev
bad interpreter: ...old-path/.venv/bin/python3	同上——.venv/bin/pytest 的 shebang 硬编码了重命名前的目录	uv sync --python 3.14 --extra dev
pip show 显示未找到，但 uv run 显示已安装	uv run 的解析机制绕过了 venv 的 pip 元数据	uv sync 会协调二者

规则：仓库重命名、目录移动或 Python 版本变更后，运行任何命令前都要先运行 uv sync --python 3.14 --extra dev。

执行后反思

此技能完成后，在结束前检查：

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

仅当问题确实存在且可复现时才更新——不要基于推测更新。