Flight Monitor Skill

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

---

Quick Start

单程查询

CODEBLOCK0

往返查询

CODEBLOCK1

设置价格监控与推送

CODEBLOCK2

管理监控任务

CODEBLOCK3

配置手机推送

CODEBLOCK4

---

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)

CODEBLOCK5

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

Result INLINECODE1	What it means	What you do next
INLINECODE2	Full flight list fetched directly — done	Format the flights list into a table. Skip all web searches.
INLINECODE4

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:

CODEBLOCK6

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:

CODEBLOCK7

History files: INLINECODE11

Step 4 — Check Alert & Send Notification

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

CODEBLOCK8

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

CODEBLOCK9

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)

CODEBLOCK10

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. 1. Install Bark app from App Store
2. Open the app → copy your device key
3. Configure: INLINECODE20

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

1. 1. Visit https://sct.ftqq.com/ and login with GitHub
2. Copy your SendKey
3. Configure: INLINECODE21

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

1. 1. Install PushDeer app or use web version at https://www.pushdeer.com/
2. Create a device and copy the push key
3. Configure: INLINECODE22

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

---

Frequency Options

Input	Schedule	Label
INLINECODE24 / INLINECODE25	Every 1 hour	每1小时
INLINECODE26

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").

CODEBLOCK11

Column definitions:

• - 全程时长: total elapsed time from departure to final arrival (including layover)
• INLINECODE34: for connecting flights, list connection city + layover wait duration; write "直飞" for non-stop

Low-Price Alert (sent to phone)

CODEBLOCK12

---

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 webfetch: 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 websearch 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

CODEBLOCK13

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

CODEBLOCK14