trigger-sentinel-author

Trigger 哨兵与后台事件监控专家 (Trigger Sentinel Author)

本技能指导 AI Agent（如桐乃及其他助手）掌握 MioChat 核心 Sentinel 系统的设计哲学，并使用 sentinel 工具自主编写、部署和管理后台条件监控哨兵。

1. 核心设计哲学与唤醒机制

Sentinel 系统的核心使命是：让 Agent 拥有在后台自主监控并随时“带着证据醒来”的能力。

核心铁律与角色区分

1. sentinel vs cron 的绝对界限：
   • sentinel（条件监控探针）：平时在后台静默跑脚本，零 Token 消耗；仅当外部条件满足并在 stdout 输出 @WAKE@ 时，才将证据注入会话唤醒 Agent。
   • cron（纯时间闹钟）：无外部条件，到点直接触发 LLM 回复。严禁使用 cron 轮询监控外部状态！
2. 唤醒 = 向绑定会话追加一条标准的系统事件注入消息；
3. 身份随 Session：唤醒消息注入哪个会话，就由该会话绑定的 Agent 自然接收并处理。

2. 标准两步工作流（铁律）

创建哨兵时，必须严格执行以下两步流，严禁在工具参数中直接塞大段代码：

第一步：编写独立的巡检脚本文件并落盘

使用文件工具在 channels-data/triggers/scripts/ 目录下创建脚本文件（如 btc_watcher.js）。

• 动态参数读取：脚本运行时的上下文参数必须通过 process.env.TRIGGER_PARAMS 读取解析（JSON 格式），实现脚本逻辑与阈值配置解耦。
• @WAKE@ 标准契约：满足唤醒条件时，脚本最后一行必须输出：

   @WAKE@ {"wake": true, "reason": "【事件原因描述】", "data": { ...关键证据与明细... }}
  

脚本应在自身进程内完成循环、等待、重试和资源清理；检测到条件后输出一条 @WAKE@ 并退出。sentinel 会记录 PID，收到唤醒后停止当前进程；persistent 模式会重新启动脚本继续监听，once 模式则结束生命周期。

所有哨兵脚本都必须读取第一个运行参数：

• test：只执行一次快速检查并退出，用于 sentinel(action="run") 验证脚本可用性和回显结果；
• loop：正式后台运行，脚本自行循环/等待条件；
• 缺少参数或参数不是 test/loop：必须立即报错并以非零码退出。

系统启动后台哨兵时只会传入 loop，调试试跑只会传入 test。不要把运行参数 放到 TRIGGER_PARAMS 中，也不要让脚本在没有运行参数时默认进入后台循环。

Node.js 编写范例（推荐，原生支持 fetch 与 process.env）

// channels-data/triggers/scripts/btc_watcher.js
const runMode = process.argv[2];
if (runMode !== 'test' && runMode !== 'loop') {
  console.error('usage: btc_watcher.js test|loop');
  process.exit(64);
}

const params = JSON.parse(process.env.TRIGGER_PARAMS || '{}');
const targetPrice = params.targetPrice || 80000;
const symbol = params.symbol || 'BTCUSDT';

async function checkOnce() {
  try {
    const res = await fetch(`https://api.binance.com/api/v3/ticker/price?symbol=${symbol}`);
    const data = await res.json();
    const currentPrice = parseFloat(data.price);

    if (currentPrice >= targetPrice) {
      console.log('@WAKE@ ' + JSON.stringify({
        wake: true,
        reason: `${symbol} 当前价格 ${currentPrice} 已突破预设警戒线 ${targetPrice}!`,
        data: { currentPrice, targetPrice, timestamp: Date.now() }
      }));
      return true;
    }
    console.log(`[巡检正常] ${symbol} 当前价格 ${currentPrice}，未达到目标 ${targetPrice}`);
    return false;
  } catch (err) {
    console.error('[巡检异常]', err.message);
    return false;
  }
}

if (runMode === 'test') {
  await checkOnce();
  process.exit(0);
}

while (true) {
  if (await checkOnce()) process.exit(0);
  await new Promise((resolve) => setTimeout(resolve, 5 * 60 * 1000));
}