🎁 Get the FREE AI Skills Starter GuideSubscribe →
BytesAgainBytesAgain
🦀 ClawHub

flight-monitor

by @jackzhao3925

机票查询与价格监控技能。支持单程/往返查询、价格阈值提醒、定时监控、手机推送通知(Bark/Server酱/PushDeer)。触发词示例:查一下北京到三亚的机票、帮我看看上海飞成都下周六往返票、监控杭州到西安3月26日机票低于500提醒我、查看所有机票监控任务。

Versionv1.1.1
Downloads891
TERMINAL
clawhub install flight-monitor

📖 About This Skill


name: flight-monitor description: 机票查询与价格监控技能。支持单程/往返查询、价格阈值提醒、定时监控、手机推送通知(Bark/Server酱/PushDeer)。触发词示例:查一下北京到三亚的机票、帮我看看上海飞成都下周六往返票、监控杭州到西安3月26日机票低于500提醒我、查看所有机票监控任务。

Flight Monitor Skill

查询国内外实时机票价格,设置低价提醒,支持定时监控。无需浏览器自动化,无需 API 密钥。


Quick Start

单程查询

查一下北京到三亚 3 月 25 日的机票价格
Check flights from BJS to SYX on 2026-03-25
查询杭州到西安 3 月 26 日,低于 500 元的机票

往返查询

帮我看看上海飞成都,4 月 1 日去 4 月 5 日回
上海到成都下周六往返票

设置价格监控与推送

监控赣州到哈尔滨 4 月 10 日,每天查一次,低于 700 提醒我
Monitor BJS to SYX on 2026-03-25, daily, alert if under ¥1500

管理监控任务

查看我所有的机票监控任务
暂停北京到三亚的监控
删除杭州到西安的监控任务

配置手机推送

设置推送 Bark Key: xxxxx


Core Workflow

Step 1 — Parse User Intent

Extract these parameters from the user's message:

| Parameter | Required | Example | |-----------|----------|---------| | 出发城市 dep | Yes | 北京 / BJS | | 到达城市 arr | Yes | 三亚 / SYX | | 出发日期 date | Yes | 2026-04-10 | | 返程日期 return_date | Round-trip only | 2026-04-15 | | 最高价 max_price | No | 700 | | 监控频率 freq | For monitoring | daily / 6h |

City name→code resolution is handled automatically by the scripts. For cities not recognized, check references/city_codes.md.

Step 2 — Query Flight Data

⚠️ CRITICAL DATE RULE: Always use the user's exact travel date. NEVER substitute today's date.

#### Step 2a — Run search_flights.py (always do this first)

python scripts/search_flights.py --from  --to  --date 
python scripts/search_flights.py --from KOW --to HRB --date 2026-04-10 --max-price 700
python scripts/search_flights.py --from SHA --to CTU --date 2026-04-01 --return-date 2026-04-05

The script tries three data sources in order and returns one of:

| Result source | What it means | What you do next | |----------------|---------------|------------------| | ctrip | Full flight list fetched directly — done | Format the flights list into a table. Skip all web searches. | | zbape | Lowest price summary only (no schedule) | Show the price summary + booking links. Skip all web searches. | | fallback | APIs unavailable | Do exactly ONE web_search using the search_query field. Then stop. Do NOT fetch any URLs. |

#### Step 2b — Fallback web_search (only when source == "fallback")

Use the exact query string from search_query in the script output:

web_search("")

Parse snippets for: airline name, flight number, departure time, arrival time, price. Stop after this one search, regardless of result quality. Use whatever data the snippets contain.

#### HARD RULES — no exceptions

  • NEVER call web_fetch on any URL (携程/去哪儿/Skyscanner are all JS-rendered; fetching wastes time and returns nothing useful).
  • NEVER run more than 1 web_search per query direction (outbound / return).
  • NEVER try multiple search engines or reformulate the query if the first search returns partial data.
  • If data is incomplete after one search, present what you have and note the limitation.
  • Step 3 — Record Price History

    After querying, always record the result for trend tracking:

    python scripts/price_history.py append \
      --from KOW --to HRB --date 2026-04-10 \
      --price  --flight "" --threshold 700

    View history for a route

    python scripts/price_history.py show --from KOW --to HRB --date 2026-04-10

    List all routes with history

    python scripts/price_history.py list

    History files: ~/.workbuddy/flight-monitor/{DEP}-{ARR}-{DATE}.json

    Step 4 — Check Alert & Send Notification

    After recording, check if the price is at or below threshold:

    python scripts/price_history.py show --from KOW --to HRB --date 2026-04-10
    

    If the output contains "低价提醒" (price ≤ threshold):

    python scripts/notify.py \
      --title "机票低价提醒 KOW→HRB" \
      --body "赣州→哈尔滨 2026-04-10 最低价 ¥,低于阈值¥700!推荐航班 " \
      --url "https://flights.ctrip.com/itinerary/oneway/kow-hrb?depdate=2026-04-10"
    

    notify.py will automatically use whichever push service is configured. If no push service is configured, it will print instructions to set one up.

    Step 5 — Set Up Monitoring (when user requests recurring checks)

    # Add a daily monitor with price alert
    python scripts/monitor_manager.py add \
      --from KOW --to HRB --date 2026-04-10 \
      --freq daily --threshold 700

    Every 6 hours

    python scripts/monitor_manager.py add \ --from HGH --to SIA --date 2026-03-26 --freq 6h

    List all monitors

    python scripts/monitor_manager.py list

    Pause a monitor

    python scripts/monitor_manager.py pause --id flight-KOW-HRB-2026-04-10

    Remove a monitor

    python scripts/monitor_manager.py remove --id flight-KOW-HRB-2026-04-10

    Show details / manual trigger hint (does NOT execute any shell command)

    python scripts/monitor_manager.py run --id flight-KOW-HRB-2026-04-10

    Monitor tasks are saved as TOML files under ~/.workbuddy/automations/.

    Security notes:

  • monitor_manager.py does not import os and contains no os.system() / subprocess calls.
  • All --id arguments are validated against a strict whitelist regex (flight-[A-Z]+-[A-Z]+-YYYY-MM-DD) before any filesystem access, preventing path traversal attacks.
  • The run subcommand only prints a safe hint — it never executes external commands.

  • Push Notification Setup

    Three free services are supported. Configure one:

    Option A — Bark (iOS only, recommended for iPhone users)

    1. Install Bark app from App Store 2. Open the app → copy your device key 3. Configure: python scripts/notify.py --setup bark --key

    Option B — Server酱 (WeChat notification, Android & iOS)

    1. Visit https://sct.ftqq.com/ and login with GitHub 2. Copy your SendKey 3. Configure: python scripts/notify.py --setup serverchan --key

    Option C — PushDeer (open source, Android & iOS)

    1. Install PushDeer app or use web version at https://www.pushdeer.com/ 2. Create a device and copy the push key 3. Configure: python scripts/notify.py --setup pushdeer --key

    Configuration is saved to ~/.workbuddy/flight-monitor/notify_config.json.


    Frequency Options

    | Input | Schedule | Label | |-------|----------|-------| | hourly / 1h | Every 1 hour | 每1小时 | | 2h | Every 2 hours | 每2小时 | | 3h | Every 3 hours | 每3小时 | | 6h | Every 6 hours | 每6小时 | | 12h / twice-daily | Every 12 hours | 每12小时 | | daily / morning | Daily at 09:00 CST | 每天9:00 |

    Recommended frequencies by lead time:

    | Lead Time | Recommended Freq | |-----------|-----------------| | 1 month+ | daily | | 2 weeks | 12h | | 1 week | 6h | | 3 days | 3h |


    Output Format

    Query Result (shown to user)

    Always present results in the following table format. For connecting flights, the "中转" column must list the connection city and layover wait time (e.g. "转上海 1h20m").

    ## 机票查询:赣州(KOW) → 哈尔滨(HRB)

    出行日期: 2026-04-10(⚠️ 以下均为该日期价格) 价格筛选: ≤ ¥700

    | 航班 | 价格(含税) | 出发 | 到达 | 全程时长 | 中转(城市 + 等待时间) | |------|-----------|------|------|----------|------------------------| | 祥鹏 8L9549 | ¥620 | 09:35 | 13:30 | 3h55m | 直飞 | | 东航 MU2993+MU5619 | ¥650 | 20:10 | 00:35+1 | 7h25m | 转上海虹桥 1h50m |

    最低价:¥620 立即预订 →

    Column definitions:

  • 全程时长: total elapsed time from departure to final arrival (including layover)
  • 中转(城市 + 等待时间): for connecting flights, list connection city + layover wait duration; write "直飞" for non-stop
  • Low-Price Alert (sent to phone)

    🔔 机票低价提醒!

    赣州(KOW) → 哈尔滨(HRB) | 出行日期:2026-04-10 当前最低价:¥620(低于阈值 ¥700) 推荐航班:祥鹏 8L9549 09:35 → 13:30(直飞)

    立即预订:https://flights.ctrip.com/...


    Notes

  • ⚠️ Date discipline: Always search for the user's exact travel date. The travel date is NOT today's date.
  • Query flow: Always start with search_flights.py. Only fall back to web_search when the script returns source: fallback. Maximum 1 search per direction.
  • Never use web_fetch: All major OTA sites (携程, 去哪儿, Skyscanner) are JavaScript-rendered. Fetching them returns empty or useless content and wastes tokens.
  • Data source priority: Ctrip AJAX API (richest, no key) → zbape.com (key required, lowest-price only) → single web_search fallback.
  • zbape key (optional): Run python scripts/search_flights.py --setup-zbape once. Adds a useful lowest-price-per-date layer when the Ctrip API is rate-limited.
  • Push notifications: Configure once, alerts fire automatically on every monitoring cycle when price drops below threshold.
  • City codes: See references/city_codes.md for the full list.

  • File Overview

    flight-monitor/
    ├── SKILL.md                    ← This file
    ├── scripts/
    │   ├── search_flights.py       ← PRIMARY: Multi-source flight query (Ctrip API → zbape → fallback)
    │   ├── query_flights.py        ← Legacy: Search query generator + booking links
    │   ├── price_history.py        ← Append/read/alert price history records
    │   ├── monitor_manager.py      ← Add/pause/remove scheduled monitors
    │   └── notify.py               ← Mobile push notifications (Bark/Server酱/PushDeer)
    └── references/
        └── city_codes.md           ← Full city name → IATA code table
    

    Optional: zbape API key (adds lowest-price-per-date data when Ctrip API fails)

    python scripts/search_flights.py --setup-zbape 
    

    Get a free key at: https://api.zbape.com/doc/54

    💡 Examples

    单程查询

    查一下北京到三亚 3 月 25 日的机票价格
    Check flights from BJS to SYX on 2026-03-25
    查询杭州到西安 3 月 26 日,低于 500 元的机票
    

    往返查询

    帮我看看上海飞成都,4 月 1 日去 4 月 5 日回
    上海到成都下周六往返票
    

    设置价格监控与推送

    监控赣州到哈尔滨 4 月 10 日,每天查一次,低于 700 提醒我
    Monitor BJS to SYX on 2026-03-25, daily, alert if under ¥1500
    

    管理监控任务

    查看我所有的机票监控任务
    暂停北京到三亚的监控
    删除杭州到西安的监控任务
    

    配置手机推送

    设置推送 Bark Key: xxxxx
    


    📋 Tips & Best Practices

  • ⚠️ Date discipline: Always search for the user's exact travel date. The travel date is NOT today's date.
  • Query flow: Always start with search_flights.py. Only fall back to web_search when the script returns source: fallback. Maximum 1 search per direction.
  • Never use web_fetch: All major OTA sites (携程, 去哪儿, Skyscanner) are JavaScript-rendered. Fetching them returns empty or useless content and wastes tokens.
  • Data source priority: Ctrip AJAX API (richest, no key) → zbape.com (key required, lowest-price only) → single web_search fallback.
  • zbape key (optional): Run python scripts/search_flights.py --setup-zbape once. Adds a useful lowest-price-per-date layer when the Ctrip API is rate-limited.
  • Push notifications: Configure once, alerts fire automatically on every monitoring cycle when price drops below threshold.
  • City codes: See references/city_codes.md for the full list.