Wander — CI 工作流监控器

无需守候，只需漫游（Wander）。 一款用于监控 GitHub Actions 的命令行工具。不依赖轮询；可选在工作流运行完成时向 macOS 通知中心发送通知。

代理自动触发（强制启用）

每次执行 git push 并触发 GitHub Actions 后，均应在后台模式下自动启动 Wander，除非用户明确选择禁用该行为。

1. 若仓库根目录存在 .workflows.yml：优先使用项目级封装脚本（如 scripts/watch-*.sh），若其存在则调用之。
2. 否则：执行 "$WANDER_HOME/watch-workflow-bg.sh" （或传入项目实际使用的 workflow 文件）。
3. 以后台方式运行，确保终端会话保持响应性。
4. 约 8 秒后检查终端输出，并报告初始状态。

若仓库中不存在 .workflows.yml，但存在 .github/workflows/ 目录，则可提供监控功能，但**不会未经确认自动启动**。

适用场景

• 用户希望在 git push 后监控某工作流
• 用户要求在 CI 完成时收到通知
• 用户希望避免手动刷新 Actions 页面
• 运行时间较长的端到端（E2E）或发布（publish）流水线（耗时数分钟）
• 项目已集成 CI 监控能力（例如 ClawHub publish）

前提条件

• 已安装并完成身份验证的 gh CLI
• jq（脚本依赖）
• 本地已克隆 Wander 仓库；通过环境变量 WANDER_HOME 指定路径，或默认使用 ~/code/wander
• macOS 系统（用于通知中心集成）

安装（工具）

git clone https://github.com/ERerGB/wander.git ~/code/wander
cd ~/code/wander
chmod +x *.sh

将以下内容添加至 ~/.zshrc 或 ~/.bashrc：

export WANDER_HOME="${WANDER_HOME:-$HOME/code/wander}"
export PATH="$WANDER_HOME:$PATH"
alias wf='watch-workflow.sh'
alias wfbg='watch-workflow-bg.sh'
alias wfdt='watch-workflow-detached.sh'

或直接在 Wander 仓库中运行 ./scripts/install-personal.sh（详见主 README）。

使用模式

智能推送（适用于 Wander 仓库或类似结构）

cd /path/to/wander
./smart-push.sh

根据变更文件自动建议 smoke / e2e / skip 等操作，随后执行推送并启动监控。

手动控制（任意仓库）

git push
cd /path/to/target-repo
"$WANDER_HOME/watch-workflow-bg.sh" publish.yml

运行模式

项目级封装脚本（推荐）

#!/bin/bash
# scripts/watch-publish.sh
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
WANDER_DIR="${WANDER_DIR:-$(dirname "$REPO_ROOT")/wander}"
cd "$REPO_ROOT"
exec "$WANDER_DIR/watch-workflow-bg.sh" publish.yml "$@"

然后执行：git push && ./scripts/watch-publish.sh

其他示例：项目 openclaw-uninstall 在存在时即使用 ./scripts/watch-publish.sh 和 watch-publish-detached.sh。

工作流注册表

为支持 check_window / expected_duration 配置，请在项目根目录添加 .workflows.yml，或设置环境变量 WORKFLOW_REGISTRY_FILE：

workflows:
  - name: "publish.yml"
    description: "Publish to ClawHub"
    check_window: 120
    expected_duration: 30
    category: "publish"

若某工作流未在注册表中显式声明，则默认 check_window 值为 300 秒。

边界情况

当 CI 失败时

1. 从终端输出或通知中记录运行 ID（RUN_ID）。
2. 查看失败日志：gh run view --log-failed
3. 修复问题后重新 git push，或直接重跑失败作业：gh run rerun --failed

WANDER_HOME 解析顺序

• 优先使用环境变量 WANDER_HOME（若已设置）
• 其次尝试同级路径：$(dirname "$REPO_ROOT")/wander（常见于封装脚本中）
• 最后回退至默认路径：~/code/wander

参考文档

• Wander README
• EDGE_CASES.md
• COFFEE_BREAK.md