Tap triggers

tap-triggers —— 位于 plan 之上的触发层

这是什么（一句话为什么）

Plan 回答做什么并编码验证；它刻意不回答何时。云端 "routines" 把三者打包，但每次触发都要付一个 agent 会话。Tap 的 "编译一次、免费重放" 非对称要求相反：触发层也必须零 token。操作系统自带世界级触发引擎（launchd）；本技能只拥有从可版本化声明到 launchd 产物的确定性编译。

声明格式

~/.tap/triggers/<site>/<name>[.<slot>].trigger.json——一个文件一个触发。slot（可选的文件名第三段）让一个 plan 有多个独立触发（visibility-recheck.am.trigger.json、…pm.trigger.json）。

{
  "ref": "xhs/visibility-recheck",        // 或 tap://xhs/visibility-recheck
  "args": { "note_url": "…", "note_id": "…" },   // 可选，原样 → tap --args
  "when": {                                // 下列 EXACTLY ONE：
    "calendar": { "Hour": 10, "Minute": 30 }     // launchd StartCalendarInterval
    // "calendar": [ {…}, {…} ]                  // 多个触发时刻
    // "interval_seconds": 3600                  // StartInterval（>= 60）
    // "watch_path": "~/Downloads"               // WatchPaths（变动时触发）
  },
  "sink": {                                 // 可选，结果落点
    "path": "~/.tap/ledger/{name}-{date}.json",  // {date}{site}{name}{run_id}
    "select": "return"                      // return | envelope | return.<field>…
  },
  "on": {                                   // 可选，统一订阅
    "ok":     [ { "write": "...", "select": "..." } ],
    "failed": [ { "notify_os": "🛑 扫描失败——查日志" } ]
  },
  "note": "这个触发为什么存在",            // 可选，作为 plist 注释
  "disabled": true                          // 可选；保留声明，materializer 视 plist 为孤儿
}

用法

# 编译所有声明 → ~/Library/LaunchAgents/dev.taprun.trigger.*.plist
tap schedule            # 以 JSON 报告，任何拒绝则 exit 1

# 删除声明已消失/禁用的 plist
tap schedule --prune

# 激活 / 触发 / 移除（launchd 侧——`tap schedule` 只写文件）
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.taprun.trigger.<site>.<name>.plist
launchctl kickstart -k gui/$(id -u)/dev.taprun.trigger.<site>.<name>   # 立即触发
launchctl bootout   gui/$(id -u)/dev.taprun.trigger.<site>.<name>
launchctl list | grep dev.taprun.trigger                                # 状态

日志在 ~/Library/Logs/taprun/<label>.log|.err。

硬闸门（编译时，均有测试覆盖）

• 前台闸门（安全）——含 trusted:true op 的 plan 被拒绝：trusted 输入是 CDP 坐标级操作，需要前台标签页；03:00 的无人值守运行无法提供。是结构性 JSON 检查，不是文本匹配。
• 引用完整性——悬空 ref（磁盘上无对应 plan）在声明时即被拒，而非在失败日志里才发现。
• 写变体警告（质量）——变更类 plan 会编译但告警：确认后置条件非空虚，且 intent_key 在无人值守前已完成去重。
• 命名空间 containment（安全）——孤儿清扫与 --prune 结构性限定在 dev.taprun.trigger.*；外部 LaunchAgents 构造上不可达。
• 幂等——未变的声明不重写；有改动则报告 updated。

边界（记下以免被人"好心改坏"）

• 不要给引擎加调度循环——触发层应只做声明→产物的编译。
• 不要从 materializer 自动 bootstrap 进 launchd。 写文件是幂等且可审阅的；改 launchd 状态是单独、人类可见的一步（刻意的两阶段：先编译，再激活）。
• 浏览器事件触发（"当我打开 Xero 时拉报表"）是只有本地优先才能做的类，云端 routine 做不到——但当前无命名消费者，待有需求再议。
• 当前仅 macOS + launchd。Linux/Windows 端口 = 同一声明格式下的 systemd timer 等价物。无人值守运行只有在 Chrome 运行时才能抵达扩展 peer（launchd → tap CLI → host.sock → NM host）；L1/L2 fetch 类 plan（无 tab）无论如何都能跑——触发场景优先选它们。