Watchers

RSS・JSON API・GitHub を定期的に見に行き、既読の印で重複を省きます。

skill の情報

参考: SKILL.md 全文

Watchers

外部の情報源を一定の間隔で見に行き、新しいものにだけ反応します。すぐ使えるスクリプトが 3 本と、既読の印を扱う共通の部品が付いています。cron に組み込んでもいいですし、必要なときに端末から手で動かしても構いません。

使う場面

• RSS / Atom のフィードを見張って、新しい記事を知らせてほしいとき
• GitHub リポジトリの issue / pull request / リリース / コミットを見張りたいとき
• 好きな JSON のエンドポイントを定期的に見に行き、新しい項目が出たら知らせてほしいとき
• 「X を見張るものを作って」「X が変わったら教えて」と頼まれたとき

考え方

見張り役は、次のことをするだけのスクリプトです。

1. 外部の情報源からデータを取ってくる
2. これまでに見た ID を記録したファイルと突き合わせる
3. 新しい記録を書き戻す
4. 新しいものを標準出力に出す（何もなければ何も出さない）

下で紹介するスクリプトは、この 3 つをまとめて面倒を見ます。エージェントは terminal ツールからこれらを実行し（cron のジョブでも、Webhook からでも、対話の途中でも構いません）、新しく出たものを報告します。

すぐ使えるスクリプト

3 本とも、skill を入れると $HERMES_HOME/skills/devops/watchers/scripts/ に置かれます。どれも状態ファイルの置き場として WATCHER_STATE_DIR（既定は $HERMES_HOME/watcher-state/）を読み、--name に渡した名前で区別します。

3 本に共通する点:

• 初回の実行は基準を記録するだけ — すでにあるフィードを流し直しません
• 記録する ID は上限つき（最大 500 件）で、メモリが膨らまないようにしています
• 出力の形式は項目ごとに ## <title>\n<url>\n\n<optional body>
• 新しいものがなければ標準出力は空 — 呼び出す側はそれを「何もなし」として扱います
• 取得に失敗したときは 0 以外の終了コードを返します

使い方

terminal ツールから直接実行します。

python $HERMES_HOME/skills/devops/watchers/scripts/watch_rss.py \
  --name hn --url https://news.ycombinator.com/rss --max 5

GitHub のリポジトリを見張ります（匿名だと 1 時間あたり 60 回の制限に当たるので、${HERMES_HOME:-~/.hermes}/.env に GITHUB_TOKEN を設定してください）。

python $HERMES_HOME/skills/devops/watchers/scripts/watch_github.py \
  --name hermes-issues --repo NousResearch/hermes-agent --scope issues

好きな JSON の API を見に行きます。

python $HERMES_HOME/skills/devops/watchers/scripts/watch_http_json.py \
  --name api --url https://api.example.com/events \
  --id-field event_id --items-path data.events

cron に組み込む

cron のジョブを組んでほしいと、こんなふうにエージェントに頼みます。

> 15 分おきに watch_rss.py --name hn --url https://news.ycombinator.com/rss を実行してください。何か出たら見出しをまとめて届けてください。何も出なければ黙っていてください。

エージェントは cron のジョブの中のエージェントのループから、terminal ツール経由でスクリプトを呼びます。cron に組み込みの --script フラグを変える必要はありません。

状態ファイル

どの見張り役も $HERMES_HOME/watcher-state/<name>.json を書きます。中を見るには、こうします。

cat $HERMES_HOME/watcher-state/hn.json

もう一度最初から流し直したい（次の実行を初回として扱いたい）ときは、こうします。

rm $HERMES_HOME/watcher-state/hn.json

自分で書く

3 本のスクリプトはどれも同じ型です。既読の印を読み、取ってきて、差分を出し、保存し、出力する。共通の部品は scripts/_watermark.py で、これを import すれば、書き込みの安全性・ID 件数の上限・初回の基準づくりがそのまま手に入ります。どれだけ短く書けるかは、3 本のどれを見てもわかります。

よくつまずくところ

1. 毎回「新着なし」の見出しを出してしまう。 呼び出す側は「標準出力が空＝何もなし」と決めてかかっています。差分が空のときに何か出すと、通知先を埋め尽くしてしまいます。同梱のスクリプトは気をつけていますが、自作のものも同じようにしてください。
2. 初回の実行で項目が出ると思い込む。 出ません。初回は基準を記録するだけです。最初にまとめて受け取りたいなら、初回の実行後に状態ファイルを消すか、自作のスクリプトに --prime-with-latest N のようなフラグを足してください。
3. 既読の印が際限なく増える。 共通の部品は 500 件で頭打ちにします。更新の多いフィードでは増やし、容量の厳しいファイルシステムでは減らしてください。
4. エージェントのサンドボックスから書けない場所を状態の置き場にする。 $HERMES_HOME/watcher-state/ なら必ず書けます。Docker や Modal のバックエンドからは、ホスト側の任意のパスが見えないことがあります。