product-price-monitor

商品価格モニター

購入可能な具体的な商品を監視し、正規化した総額または在庫状況の条件に基づいて通知します。バリエーション、税金、手数料、通貨、在庫、キャンセル条件、重複通知を明示的に扱います。セットアップはフォアグラウンドで一度だけ実行し、定期チェックは cronjob の実行時に行います（price-watch オートメーションブループリントがこの処理を構成します）。

使用するタイミング

• 「このノートパソコンが1,000ドル未満になったら通知してください。」
• 「この航空券の運賃が500ドル未満になるか監視してください。」
• 「このホテルで返金可能な客室が出たら教えてください。」
• 「チケットや出品の在庫状況を追跡してください。」
• 既存の価格監視に対して cron の実行が発生したとき（手順4～6）。

次の用途には使わないでください：一度限りの「今の価格はいくらですか」という検索（web_search／web_extract を直接使用してください）。

手順 — セットアップ（フォアグラウンドで一度だけ）

1. 対象商品を正確に定義する

参照元 URL／プロバイダー、入手可能な場合は商品／出品 ID、バリエーション、数量、場所、日付、旅行者／宿泊者、会員資格／ログインに関する前提、状態、販売者、許容できる代替品を記録します。2つのバリエーションを取り違える余地がなくなれば完了です。

2. 通知条件を定義する

通貨、税込みか税抜きか、上限価格、在庫状況の条件、送料、返金可否、座席／客室／チケットのクラス、クールダウン期間、通知先を指定します。合成した例に対する通知判断が一意に定まれば完了です。

3. 最新の基準値を取得してから、スケジュールを設定する

web_extract または browser_exec で範囲を限定した最新の結果を取得し、取得時刻、参照元の価格、手数料／税金、在庫状況、条件を記録します。フォアグラウンドでの取得が一度成功するまでは、スケジュールを設定しないでください。監視契約（対象、条件、基準となる観測値）を ~/.hermes/price-watches/<watch-slug>.json 配下の状態ファイルに書き込み、その後ジョブを作成します：

cronjob(action="create",
        schedule="every 6h",
        prompt="Load the product-price-monitor skill and run the tick for the watch contract at ~/.hermes/price-watches/<watch-slug>.json.",
        deliver=<user's destination>)

レート制限とサイトの利用規約を守れる頻度を選択します。基準値が対象商品の監視契約と一致し、ジョブが存在すれば完了です。

手順 — 実行時（スケジュールされた各実行）

4. 取得して正規化する

参照元を再取得します。通貨換算はタイムスタンプ付きの為替レートを使用する場合に限り、参照元の通貨も保持します。基本価格、必須手数料、送料／税金、合計、在庫状況を分けて記録します。変動しやすいページメタデータは除外します。取得に失敗した場合、状態は不明です。報告するかスキップし、エラーページで最後に正常に取得した観測値を上書きしてはいけません。観測値が基準値と比較可能であるか、失敗として明示されれば完了です。

5. 比較して重複を抑制する

条件に応じて、しきい値への到達、条件を満たす在庫状況、大幅な値下げ、または在庫状況の回復を通知します。最後に正常に取得した観測値と最後の通知フィンガープリントを状態ファイルに保存します。同じオファーを再処理しても、2回目の通知を送信してはいけません。クールダウン期間を守ります。保存された状態に基づいて通知判断が一意に定まれば完了です。

6. 通知するか、何も通知しない

条件を満たした場合、通知には対象商品／バリエーション、観測した総額と参照元の通貨、在庫状況／条件、しきい値、取得タイムスタンプ、参照元リンク、重要な不確実性を含めます。在庫が確保されたと主張してはいけません。条件を満たすものがない場合は何も通知しません。定期的な「問題なし」の報告がリクエストされていない限り、「引き続き監視中」といった不要な通知は送らないでください。この実行の内容が状態ファイルに反映されれば完了です。

注意点

• 基本運賃と総額のしきい値を比較してしまう。
• サイズ、販売者、座席クラス、日付、客室条件を取り違えて通知する。
• 最後に正常に取得した値をエラーページで上書きする。
• ブロックを招いたりサイトの利用規約に違反したりするほど頻繁にポーリングする。
• フォアグラウンドでの取得が一度も成功していないのに、スケジュールを設定する。

検証

• 2つのバリエーションを取り違えないよう、監視契約で対象商品が特定されている。
• ジョブを作成する前に、フォアグラウンドでの取得が一度成功している。
• 状態ファイルから通知判断を再現したときに結果が一意に定まり、重複通知が抑制される。
• 取得失敗によって、最後に正常に取得した状態が置き換えられていない。
• 通知に総額、参照元の通貨、タイムスタンプ、参照元リンクが含まれている。