无需 Dashboard:用 tmux 网格 + watch 实时监控 AI 长时任务运行状态的完整指南
无需 Dashboard:用 tmux 网格 + watch 实时监控 AI 长时任务运行状态的完整指南
让 AI 代理(Agent)连续工作几小时甚至一整天,是 cwc-long-running-agents 这个项目的核心场景:它为 Claude Code 提供了一套长时运行 Agent 的"质量循环"原语,包括 Default-FAIL 契约、独立评估器和自动交接。任务跑得越久,你越想知道它现在在干什么、有没有卡住、成果有没有存下来。好消息是:这个项目里 Agent 的每一步动作都会落盘成文件,所以完全无需 Dashboard,用 tmux 网格配合 watch 命令,就能在终端里搭出一块免费的实时状态监控面板。
为什么长时 Agent 任务需要实时监控?
传统开发中,代码是你自己敲的,你当然知道进度。但当你运行一个可以持续数小时的 AI 长时任务时,情况完全不同:
- Agent 会不断写文件、跑测试、提交代码,这些动作分散在多个文件里;
- 长会话中上下文会被压缩摘要,光看终端滚动输出容易遗漏关键信息;
- 一旦发现跑偏,你需要及时刹车或转向,而不是干等它跑完。
好在 cwc-long-running-agents 的设计哲学是"一切皆文件":Agent 的进度笔记、证据文件、Git 提交都落在磁盘上,终端工具随时可以读取。官方在 README.md 的 Watching it work 一节中给出了 4 条监控命令,我们只需要把它们装进 tmux 的四个窗格里即可。
先认识监控面板背后的 4 个数据源
在动手搭面板前,先搞清楚每个窗格在看什么。它们分别对应仓库里的不同原语:
| 监控窗格 | 数据来源 | 对应的原语/文件 |
|---|---|---|
| 进度笔记 | PROGRESS.md |
自动交接机制,约定见 CLAUDE.md |
| 提交记录 | git log |
commit-on-stop.sh 会话末兜底提交 |
| 截图证据 | screenshots/ 目录 |
证据文件,由 track-read.sh 记录 |
| 证据读取计数 | .claude/.evidence-reads |
Default-FAIL 契约,由 verify-gate.sh 消费 |
理解这 4 个文件,你就理解了整个"质量循环"的可观测性:Agent 不能谎报进度,因为每个 passes: true 都必须先有被读取过的证据文件。
一键搭好 tmux 监控网格
确认已安装 tmux 和 watch(大多数 Linux 发行版自带,macOS 可通过 Homebrew 安装 tmux),然后在包含 .claude/ 目录的项目根目录下执行下面这段命令。它会创建一个名为 agent-watch 的 tmux 会话,切分为 2×2 四个窗格,每个窗格跑一条 watch 命令:
tmux new -s agent-watch -c "$PWD"
tmux split-window -h
tmux split-window -v
tmux select-pane -t 0; tmux split-window -v
tmux select-pane -t 0
tmux send-keys "watch -n 2 'tail -20 PROGRESS.md'" C-m
tmux send-keys -t 1 "watch -n 5 'git log --oneline -8'" C-m
tmux send-keys -t 2 "watch -n 5 'find screenshots -name \"*.png\" | tail -5'" C-m
tmux send-keys -t 3 "watch -n 2 'wc -l < .claude/.evidence-reads 2>/dev/null'" C-m
参数说明,帮你按需调整:
-n 2/-n 5:刷新间隔秒数。进度和证据计数变化快,用 2 秒;git log和截图列表变化慢,5 秒足够;split-window -h水平切分(左右),-v垂直切分(上下);- 之后用
Ctrl+b 方向键在各窗格间切换,Ctrl+b z可全屏放大当前窗格细看,再按一次恢复网格; Ctrl+b d挂起会话,执行tmux attach -t agent-watch随时回来看一眼,面板不中断。
搭好之后的效果是:一个窗格滚着 Agent 自己写的进度笔记,一个窗格显示最新的提交记录,一个窗格列出最新截图,最后一个窗格的数字不断跳动——每个原语都有了活着的视图,这正是官方 README 推荐的做法。
4 个窗格分别看什么?读懂面板的 5 个要点
面板跑起来之后,新手最容易犯的错是"只盯着看、不知道在找什么"。下面是每个窗格的判读要点:
-
进度窗格(PROGRESS.md):Agent 会按约定维护
Done / In progress / Next / Notes四个小节。如果In progress长时间停在同一条,多半是在反复调试某个功能——这很正常,长时任务本来就是"构建 → 评估 → 重建"的循环。 -
提交窗格(git log):新提交出现说明工作被安全保存了。即使会话意外中断,下一轮也可以从 Git 记录干净地恢复。长时间无新提交时,结合进度窗格判断是在写代码还是卡住了。
-
截图窗格(screenshots):新增截图意味着 Agent 正在对运行中的应用做真实验证,而不是空谈"应该好了"。
-
证据计数窗格(.evidence-reads):数字在涨,说明 Agent 正在打开证据文件;这个数字在每次被门控放行后重置为 0,所以你会看到它反复归零又增长——这就是 Default-FAIL 契约在工作的直接证据。
-
交叉验证:当你看到某功能被标记通过时,问自己"截图窗格里有对应的新截图吗?"面板的价值正在于这种跨窗格的互相印证。
发现跑偏怎么办?两个无需重启的干预钩子
监控的意义在于及时干预。cwc-long-running-agents 自带两个"操作员控制"钩子,让你在任务运行中途就能刹车或转向,完全不需要杀掉会话:
| 操作 | 命令 | 背后的钩子 |
|---|---|---|
| 紧急刹车 | touch AGENT_STOP |
kill-switch.sh |
| 中途转向 | 把指令写进 STEER.md |
steer.sh |
- 紧急刹车:
touch AGENT_STOP在项目根目录创建该文件后,Agent 的每次工具调用都会被拦截并暂停;想恢复时删除该文件即可。这是最安全的"急停按钮"。 - 中途转向:往根目录的
STEER.md里写一句指令(例如"先修登录页的样式问题"),steer 钩子会把内容一次性展示给 Agent 然后自动清空文件,Agent 会在不打断当前会话的情况下调整方向。配合监控面板,你等于拥有了"边看边改"的完整闭环。
从手动循环到无人值守:进阶玩法
搭好监控面板后,如果还想让"构建 → 评估 → 重建"循环自己转起来,README 给了一个极简的 headless 循环脚本示意(节选自 README.md):
while grep -q '"passes": false' test-results.json; do
claude -p "Read PROGRESS.md and build the next unfinished feature per CLAUDE.md."
VERDICT=$(claude --agent evaluator -p "Review the most recent commit against its spec.")
[ "$(echo "$VERDICT" | head -1)" = "PASS" ] || echo "$VERDICT" > NEXT_FINDINGS.md
done
循环里有两个"安全阀"值得关注:test-results.json 中不再有 passes: false 时自动退出;运行期间执行 touch AGENT_STOP 可提前终止。更完整的无人值守模式(限制单会话时长、由外层脚本自动开启下一轮)以及规划器、冲刺契约等进阶模式,可以在 README 的 Going further 一节中继续了解。
常见问题 FAQ
Q1:为什么用 watch 而不是写一个 Dashboard?
因为数据源本来就是文件。watch 每 N 秒重跑一次命令并刷新画面,零依赖、零部署,退出 tmux 会话即走。对新手来说,这是理解"长时 Agent 可观测性"成本最低的方式。
Q2:执行 watch 命令后提示"目录中找不到 PROGRESS.md"?
请在包含 .claude/ 的项目根目录运行。官方明确提示:从子目录启动 claude 时钩子不会加载,监控同理——文件路径都是相对项目根目录的。
Q3:tmux 窗格太多,终端看不全怎么办?
按 Ctrl+b z 全屏当前窗格细看,Ctrl+b d 挂起会话;或者把 2×2 网格改成 4 列并排(tmux new-session 后连续 split-window -h),适合宽屏终端。
Q4:.evidence-reads 计数一直显示 0 或空?
该文件在每次通过门控写入后被清空重置,计数为 0 是正常状态;2>/dev/null 是官方写法,用于文件尚不存在时不报错。只要 Agent 开始读证据,数字就会出现。
总结
监控 AI 长时任务不一定要写 Dashboard。cwc-long-running-agents 把 Agent 的每一步动作都落成文件,你只需一条 tmux 命令、四条 watch,就能获得进度笔记、提交记录、截图证据、证据计数四路实时视图,再用 AGENT_STOP 和 STEER.md 两个钩子实现运行中的刹车与转向。建议先照本文搭好监控网格,实际跑一轮任务,感受一下"无需 Dashboard 的实时监控"——这也是理解整个长时 Agent 质量循环最直观的方式。