Wander — 远程异步完成（元协议）+ GitHub Actions 适配器

不要手动刷新，让 Wander 来守候。 设计哲学：当你触发一个远程且耗时的操作后，完成通知应主动找到你——而 Agent 仍必须验证最终结果，而非假设其成功。

元协议 vs 具体实现：本能力定义了一套适用于任意长期运行远程任务的可移植最佳实践。Wander（watch-workflow-*.sh）是当事实来源为GitHub Actions时的参考适配器。它并非唯一有效的监控方式。

心智模型（第一性原理）

每个远程异步任务都具有相同结构：

触发 → 在别处执行 → 终态（+ 产物）
(Agent)     （无法加速）     （用户与 Agent 均需此信息）

Agent 应当：

1. 触发后立即继续——勿在聊天界面中反复手动刷新 UI 消耗对话轮次。
2. 附加监控器——一种无需用户盯守浏览器标签页即可主动呈现完成状态及成功/失败结果的机制。
3. 闭环认知流程——当监控器触发时，Agent 读取真实结果并采取行动（推进下一步，或诊断问题）。

仅当 Agent 明确知晓终态时，该闭环才算完成（对于失败情形，还需具备足够日志/上下文以支持修复）。

1. 读取监控输出（终态日志、JSON 汇总、仪表盘链接 + 状态抓取——取决于后端所提供内容）。
2. 基于结果执行动作——在终态被确认前，不得视任务为“已完成”：
   • ✅ 成功 → 推进后续操作（例如合并 PR、部署、打标签）
   • ❌ 失败 / 已取消 → 向用户呈现失败信息、拉取日志、提出修复建议
3. 绝不假设成功——“监控已启动” ≠ “任务已成功”。

元协议 —— 在选择监控器前对任务进行分类

步骤 A —— 识别权威数据源（即真实状态所在系统？）

步骤 B —— 选择完成通知通道（在保障可审计性的前提下选择最低摩擦路径）

1. 以 CI 为门面——若团队已将质量门禁设于某 CI 运行之上，则即便繁重工作由 EAS/Railway 等执行，监控该 CI 运行通常仍是最佳选择（通过包装任务或 workflow_dispatch 触发）。
2. 厂商原生 CLI/API——例如，在无 CI 包装且厂商自身为权威数据源时，轮询构建 ID 直至返回 finished / errored 状态。
3. 仪表盘 + 显式交接——当自动化不可行时可接受；但仍需用户提供一个明确的状态名称，或单个经确认的 URL——而非凭主观感受判断。

步骤 C —— 后台运行监控器，除非用户明确要求阻塞当前会话。

步骤 D —— 完成后，从同一权威数据源获取失败详情（失败步骤日志、EAS 错误页、部署日志等）。

在步骤 A 中切勿默认采用 GitHub Actions。应默认采用：实际掌控该触发任务终态的平台。

参考适配器：通过 Wander 使用 GitHub Actions

当权威运行任务本身即为 GitHub Actions 工作流（如 push、workflow_run、workflow_dispatch 等），请使用 Wander 脚本作为监控器：

# Wander 后台进程退出后，检查结果：
gh run view  --json conclusion -q .conclusion
# → "success" | "failure" | "cancelled" | "timed_out"

# 若失败，获取日志供 Agent 诊断：
gh run view  --log-failed

任务分类——示例（GHA 列 = Wander 适配器可直接适用的情形）：

若 EAS 仅通过 CLI 触发且未接入 GHA：Wander 脚本不适用——请依据项目文档，使用 EAS/Expo 原生状态（eas build:list、构建 URL 或项目自动化机制）。

引擎说明：当前 wander 仓库实现了针对GitHub Actions的轮询与通知功能。其他后端应作为额外适配器（未来扩展）或遵循相同元协议的项目专属脚本纳入。

范围说明：v1 版本仅覆盖 GitHub Actions。

Agent 自动触发 —— 依据任务类别决策，而非“一律使用 GHA”

在触发一个长期运行的远程任务后，应为其附加匹配该任务权威数据源的监控器——除非用户明确拒绝或该任务极短（可忽略）。

若所触发的工作流明确属于GitHub Actions（或完全封装于 Agent 刚刚启动的 GHA 工作流中）：

1. 若存在 .workflows.yml → 从中选取工作流及触发时机。
2. 若不存在但 .github/workflows/ 存在 → 识别对应工作流（通过注册表扫描或向用户询问），随后启动监控。
3. 使用 watch-workflow-bg.sh —— 默认后台运行，除非用户要求阻塞。
4. 约 8 秒后，预览终端输出 / 运行 ID 并报告初始状态。
5. 告知用户：“正在 GitHub Actions 上监控 ；完成后我会通知你——你可以继续其他工作。”
6. 在终态明确前：持续检查监控输出或执行 gh run view --json conclusion。切勿过早宣告成功。
7. 收到结果后：成功 → 执行下一步；失败 → 执行 gh run view --log-failed（或等效命令）并提出修复建议。

若该工作流并非 GHA（纯 EAS CLI、仅平台侧部署等）：

• 切勿强行套用 watch-workflow-bg.sh。
• 改用厂商 CLI/API 轮询、项目定制脚本，或与用户约定仪表盘 URL —— 仍尽可能后台运行，并在事后验证终态。

若 .github/workflows/ 不存在：不得自动启动 Wander；请依据上述步骤 A–B 选择其他监控器。

何时使用本技能

• 任何远程异步任务预计耗时> ~30 秒
• 用户希望在“构建 / CI / 部署 / 发布”完成后收到通知
• 用户即将手动刷新某个仪表盘——此时应提供一个结构化的监控方案替代之
• 多步骤流程中，下一步依赖于当前步骤的成败结果

不应使用的情形

• 任务在< ~10 秒内完成（可内联等待）
• 纯本地命令，且能立即返回退出码
• 用户明确要求在聊天中进行同步阻塞式输出
• 无法抵达客观终态（触发逻辑未定义 / 平台未知）——需先澄清

前置条件（GitHub Actions 适配器路径）

• gh CLI 已安装并完成身份认证
• jq 已安装
• Wander 已下载至本地：WANDER_HOME（默认为 ~/code/wander）
• macOS 支持通知中心；Linux/无头环境：仅输出模式仍可正常工作

安装（Wander / GHA 适配器）

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

添加至 shell 初始化文件（如 ~/.bashrc 或 ~/.zshrc）：

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'

选择合适的运行模式（GHA 适配器）

经验法则：优先选用后台模式。若预计运行时间> ~5 分钟且终端可能关闭，请改用分离模式。

工作流注册表（.workflows.yml，GHA）

各工作流执行时长不同。该注册表用于告知 GHA 适配器预期行为：

workflows:
  - name: "ci.yml"
    description: "Lint + 单元测试"
    check_window: 180      # 若监控启动前工作流已结束，允许向前追溯的时间窗口（秒）
    expected_duration: 45  # 典型运行时长（秒）
    category: "smoke"

  - name: "build.yml"
    description: "Docker 构建 + 推送"
    check_window: 600
    expected_duration: 180
    category: "build"

  - name: "deploy.yml"
    description: "Railway 部署"
    check_window: 900
    expected_duration: 300
    category: "deploy"

check_window = 若工作流在监控启动前已完成，该参数定义了我们仍将其视为“本次触发”的最大回溯时间。通常约为 6× expected_duration。

为仓库自动生成注册表：

cd /path/to/repo
"$WANDER_HOME/scripts-registry.sh" scan-workflows --auto-scope

未配置时的默认 check_window 值为 300 秒。

标准使用模式（GHA）

Git push 后（CI 运行于 GitHub Actions）

git push origin main && "$WANDER_HOME/watch-workflow-bg.sh" ci.yml

项目级封装（推荐团队采用）

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

随后执行：git push && ./scripts/watch-ci.sh

EAS 且受 GHA 门禁控制

若 EAS 由 GHA 工作流触发（例如 eas-build.yml）：

git push origin feat/my-branch && "$WANDER_HOME/watch-workflow-bg.sh" eas-build.yml

若 EAS 仅通过 CLI 触发：请使用 EAS/Expo 原生信号进行监控；团队可选模式仍是添加一层轻量 GHA workflow_dispatch 封装，以实现统一监控。

手动触发工作流

gh workflow run deploy.yml --ref main
"$WANDER_HOME/watch-workflow-bg.sh" deploy.yml main

边界情况（GHA 适配器）

任务失败时的处理（GHA）

gh run view  --log-failed
gh run rerun  --failed

对于非 GHA 类型任务，请遵守相同元规则：拉取对应平台的首要失败信息源（构建日志、部署日志等）。

WANDER_HOME 解析顺序

1. $WANDER_HOME 环境变量
2. 当前仓库同级目录：$(dirname "$REPO_ROOT")/wander
3. 默认值：~/code/wander

演进方向：超越 GitHub Actions 的适配器

元协议保持稳定。适配器可替换：

• 当前：Wander = GHA 轮询 + 桌面通知。
• 未来：EAS CLI 监控器、部署 Webhook → 通知桥接器等。

在专用适配器尚未就绪前，优先采用以 CI 为门面或厂商原生轮询——切勿静默假设成功。

参考资料

• Wander README
• EDGE_CASES.md
• COFFEE_BREAK.md