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:

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.

更多技能請訪問小蔥技能站7w4.net。

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

python scripts/search_flights.py --from <dep> --to <arr> --date <YYYY-MM-DD>
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:

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

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

web_search("<value of search_query field>")

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 <lowest_price_found> --flight "<flight_number>" --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 最低價 ¥<price>，低於閾值¥700！推薦航班 <flight>" \
  --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 <YOUR_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 <YOUR_SENDKEY>

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 <YOUR_KEY>

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

Frequency Options

Recommended frequencies by lead time:

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  [立即預訂 →](https://flights.ctrip.com/itinerary/oneway/kow-hrb?depdate=2026-04-10)

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 <KEY> 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 <YOUR_KEY>
# Get a free key at: https://api.zbape.com/doc/54

這是一款實用且功能成熟的機票監控工具，能查詢即時票價、設定低價提醒、自動推送通知，對有出行計劃的使用者很有幫助。介面清晰、操作流暢，支援多種免費推送方式，使用體驗良好。安全性設計可靠，無需擔心資訊洩露風險。文件存在少量檔名不一致的小問題，但不影響核心使用。總體質量良好，值得使用。