Description

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

README (SKILL.md)

\r \r

Flight Monitor Skill\r

Name: flight-monitor
Author: jackzhao3925

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

Quick Start\r

\r

单程查询\r

\r

查一下北京到三亚 3 月 25 日的机票价格\r
Check flights from BJS to SYX on 2026-03-25\r
查询杭州到西安 3 月 26 日，低于 500 元的机票\r
```\r
\r
### 往返查询\r
\r
```\r
帮我看看上海飞成都，4 月 1 日去 4 月 5 日回\r
上海到成都下周六往返票\r
```\r
\r
### 设置价格监控与推送\r
\r
```\r
监控赣州到哈尔滨 4 月 10 日，每天查一次，低于 700 提醒我\r
Monitor BJS to SYX on 2026-03-25, daily, alert if under ¥1500\r
```\r
\r
### 管理监控任务\r
\r
```\r
查看我所有的机票监控任务\r
暂停北京到三亚的监控\r
删除杭州到西安的监控任务\r
```\r
\r
### 配置手机推送\r
\r
```\r
设置推送 Bark Key: xxxxx\r
```\r
\r
---\r
\r
## Core Workflow\r
\r
### Step 1 — Parse User Intent\r
\r
Extract these parameters from the user's message:\r
\r
| Parameter | Required | Example |\r
|-----------|----------|---------|\r
| 出发城市 dep | Yes | 北京 / BJS |\r
| 到达城市 arr | Yes | 三亚 / SYX |\r
| 出发日期 date | Yes | 2026-04-10 |\r
| 返程日期 return_date | Round-trip only | 2026-04-15 |\r
| 最高价 max_price | No | 700 |\r
| 监控频率 freq | For monitoring | daily / 6h |\r
\r
City name→code resolution is handled automatically by the scripts.\r
For cities not recognized, check `references/city_codes.md`.\r
\r
### Step 2 — Query Flight Data\r
\r
**⚠️ CRITICAL DATE RULE: Always use the user's exact travel date. NEVER substitute today's date.**\r
\r
#### Step 2a — Run search_flights.py (always do this first)\r
\r
```bash\r
python scripts/search_flights.py --from \x3Cdep> --to \x3Carr> --date \x3CYYYY-MM-DD>\r
python scripts/search_flights.py --from KOW --to HRB --date 2026-04-10 --max-price 700\r
python scripts/search_flights.py --from SHA --to CTU --date 2026-04-01 --return-date 2026-04-05\r
```\r
\r
The script tries three data sources in order and returns one of:\r
\r
| Result `source` | What it means | What you do next |\r
|----------------|---------------|------------------|\r
| `ctrip` | Full flight list fetched directly — **done** | Format the `flights` list into a table. **Skip all web searches.** |\r
| `zbape` | Lowest price summary only (no schedule) | Show the price summary + booking links. **Skip all web searches.** |\r
| `fallback` | APIs unavailable | Do **exactly ONE** `web_search` using the `search_query` field. Then stop. **Do NOT fetch any URLs.** |\r
\r
#### Step 2b — Fallback web_search (only when source == "fallback")\r
\r
Use the exact query string from `search_query` in the script output:\r
\r
```\r
web_search("\x3Cvalue of search_query field>")\r
```\r
\r
Parse snippets for: airline name, flight number, departure time, arrival time, price.\r
**Stop after this one search**, regardless of result quality. Use whatever data the snippets contain.\r
\r
#### HARD RULES — no exceptions\r
\r
- **NEVER call `web_fetch`** on any URL (携程/去哪儿/Skyscanner are all JS-rendered; fetching wastes time and returns nothing useful).\r
- **NEVER run more than 1 `web_search`** per query direction (outbound / return).\r
- **NEVER try multiple search engines** or reformulate the query if the first search returns partial data.\r
- If data is incomplete after one search, present what you have and note the limitation.\r
\r
### Step 3 — Record Price History\r
\r
After querying, always record the result for trend tracking:\r
\r
```bash\r
python scripts/price_history.py append \\r
  --from KOW --to HRB --date 2026-04-10 \\r
  --price \x3Clowest_price_found> --flight "\x3Cflight_number>" --threshold 700\r
\r
# View history for a route\r
python scripts/price_history.py show --from KOW --to HRB --date 2026-04-10\r
\r
# List all routes with history\r
python scripts/price_history.py list\r
```\r
\r
History files: `~/.workbuddy/flight-monitor/{DEP}-{ARR}-{DATE}.json`\r
\r
### Step 4 — Check Alert & Send Notification\r
\r
After recording, check if the price is at or below threshold:\r
\r
```bash\r
python scripts/price_history.py show --from KOW --to HRB --date 2026-04-10\r
```\r
\r
If the output contains "低价提醒" (price ≤ threshold):\r
\r
```bash\r
python scripts/notify.py \\r
  --title "机票低价提醒 KOW→HRB" \\r
  --body "赣州→哈尔滨 2026-04-10 最低价 ¥\x3Cprice>，低于阈值¥700！推荐航班 \x3Cflight>" \\r
  --url "https://flights.ctrip.com/itinerary/oneway/kow-hrb?depdate=2026-04-10"\r
```\r
\r
notify.py will automatically use whichever push service is configured.\r
If no push service is configured, it will print instructions to set one up.\r
\r
### Step 5 — Set Up Monitoring (when user requests recurring checks)\r
\r
```bash\r
# Add a daily monitor with price alert\r
python scripts/monitor_manager.py add \\r
  --from KOW --to HRB --date 2026-04-10 \\r
  --freq daily --threshold 700\r
\r
# Every 6 hours\r
python scripts/monitor_manager.py add \\r
  --from HGH --to SIA --date 2026-03-26 --freq 6h\r
\r
# List all monitors\r
python scripts/monitor_manager.py list\r
\r
# Pause a monitor\r
python scripts/monitor_manager.py pause --id flight-KOW-HRB-2026-04-10\r
\r
# Remove a monitor\r
python scripts/monitor_manager.py remove --id flight-KOW-HRB-2026-04-10\r
\r
# Show details / manual trigger hint (does NOT execute any shell command)\r
python scripts/monitor_manager.py run --id flight-KOW-HRB-2026-04-10\r
```\r
\r
Monitor tasks are saved as TOML files under `~/.workbuddy/automations/`.\r
\r
**Security notes:**\r
- `monitor_manager.py` does **not** import `os` and contains **no** `os.system()` / `subprocess` calls.\r
- 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.\r
- The `run` subcommand only prints a safe hint — it never executes external commands.\r
\r
---\r
\r
## Push Notification Setup\r
\r
Three free services are supported. Configure one:\r
\r
### Option A — Bark (iOS only, recommended for iPhone users)\r
\r
1. Install Bark app from App Store\r
2. Open the app → copy your device key\r
3. Configure: `python scripts/notify.py --setup bark --key \x3CYOUR_KEY>`\r
\r
### Option B — Server酱 (WeChat notification, Android & iOS)\r
\r
1. Visit https://sct.ftqq.com/ and login with GitHub\r
2. Copy your SendKey\r
3. Configure: `python scripts/notify.py --setup serverchan --key \x3CYOUR_SENDKEY>`\r
\r
### Option C — PushDeer (open source, Android & iOS)\r
\r
1. Install PushDeer app or use web version at https://www.pushdeer.com/\r
2. Create a device and copy the push key\r
3. Configure: `python scripts/notify.py --setup pushdeer --key \x3CYOUR_KEY>`\r
\r
Configuration is saved to `~/.workbuddy/flight-monitor/notify_config.json`.\r
\r
---\r
\r
## Frequency Options\r
\r
| Input | Schedule | Label |\r
|-------|----------|-------|\r
| `hourly` / `1h` | Every 1 hour | 每1小时 |\r
| `2h` | Every 2 hours | 每2小时 |\r
| `3h` | Every 3 hours | 每3小时 |\r
| `6h` | Every 6 hours | 每6小时 |\r
| `12h` / `twice-daily` | Every 12 hours | 每12小时 |\r
| `daily` / `morning` | Daily at 09:00 CST | 每天9:00 |\r
\r
**Recommended frequencies by lead time:**\r
\r
| Lead Time | Recommended Freq |\r
|-----------|-----------------|\r
| 1 month+ | daily |\r
| 2 weeks | 12h |\r
| 1 week | 6h |\r
| 3 days | 3h |\r
\r
---\r
\r
## Output Format\r
\r
### Query Result (shown to user)\r
\r
Always present results in the following table format. For connecting flights, the\r
"中转" column must list the connection city and layover wait time (e.g. "转上海 1h20m").\r
\r
```markdown\r
## 机票查询：赣州(KOW) → 哈尔滨(HRB)\r
\r
**出行日期：** 2026-04-10（⚠️ 以下均为该日期价格）\r
**价格筛选：** ≤ ¥700\r
\r
| 航班 | 价格(含税) | 出发 | 到达 | 全程时长 | 中转（城市 + 等待时间） |\r
|------|-----------|------|------|----------|------------------------|\r
| 祥鹏 8L9549 | ¥620 | 09:35 | 13:30 | 3h55m | 直飞 |\r
| 东航 MU2993+MU5619 | ¥650 | 20:10 | 00:35+1 | 7h25m | 转上海虹桥 1h50m |\r
\r
最低价：¥620  [立即预订 →](https://flights.ctrip.com/itinerary/oneway/kow-hrb?depdate=2026-04-10)\r
```\r
\r
**Column definitions:**\r
- `全程时长`: total elapsed time from departure to final arrival (including layover)\r
- `中转（城市 + 等待时间）`: for connecting flights, list connection city + layover wait duration; write "直飞" for non-stop\r
\r
### Low-Price Alert (sent to phone)\r
\r
```\r
🔔 机票低价提醒！\r
\r
赣州(KOW) → 哈尔滨(HRB)  |  出行日期：2026-04-10\r
当前最低价：¥620（低于阈值 ¥700）\r
推荐航班：祥鹏 8L9549  09:35 → 13:30（直飞）\r
\r
立即预订：https://flights.ctrip.com/...\r
```\r
\r
---\r
\r
## Notes\r
\r
- **⚠️ Date discipline:** Always search for the user's exact travel date. The travel date is NOT today's date.\r
- **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.\r
- **Never use web_fetch:** All major OTA sites (携程, 去哪儿, Skyscanner) are JavaScript-rendered. Fetching them returns empty or useless content and wastes tokens.\r
- **Data source priority:** Ctrip AJAX API (richest, no key) → zbape.com (key required, lowest-price only) → single web_search fallback.\r
- **zbape key (optional):** Run `python scripts/search_flights.py --setup-zbape \x3CKEY>` once. Adds a useful lowest-price-per-date layer when the Ctrip API is rate-limited.\r
- **Push notifications:** Configure once, alerts fire automatically on every monitoring cycle when price drops below threshold.\r
- **City codes:** See `references/city_codes.md` for the full list.\r
\r
---\r
\r
## File Overview\r
\r
```\r
flight-monitor/\r
├── SKILL.md                    ← This file\r
├── scripts/\r
│   ├── search_flights.py       ← PRIMARY: Multi-source flight query (Ctrip API → zbape → fallback)\r
│   ├── query_flights.py        ← Legacy: Search query generator + booking links\r
│   ├── price_history.py        ← Append/read/alert price history records\r
│   ├── monitor_manager.py      ← Add/pause/remove scheduled monitors\r
│   └── notify.py               ← Mobile push notifications (Bark/Server酱/PushDeer)\r
└── references/\r
    └── city_codes.md           ← Full city name → IATA code table\r
```\r
\r
### Optional: zbape API key (adds lowest-price-per-date data when Ctrip API fails)\r
\r
```bash\r
python scripts/search_flights.py --setup-zbape \x3CYOUR_KEY>\r
# Get a free key at: https://api.zbape.com/doc/54\r
```\r

Usage Guidance

What to know before installing: - Behavior: The skill queries public flight APIs (Ctrip) and, when necessary, suggests a single web_search for the AI to run. It stores monitor configurations and price history in your home directory under ~/.workbuddy/flight-monitor and ~/.workbuddy/automations. - Credentials: No credentials are required by default. If you want push notifications you must supply a push service key (Bark/Server酱/PushDeer); these keys are saved to ~/.workbuddy/flight-monitor/notify_config.json. The search tool also supports an optional third-party zbape API key saved to ~/.workbuddy/flight-monitor/api_config.json. Treat those files like any other sensitive config (permission them appropriately). - Network: The scripts make outbound HTTPS requests to booking/OTA endpoints (e.g., flights.ctrip.com) and to push-service APIs. If you have network or privacy concerns, review the code and consider running it in a restricted environment. - Safety checks: The code uses input validation and path boundary checks to mitigate path traversal and unsafe filenames. monitor_manager.py intentionally avoids subprocess/os.system calls; monitor 'run' prints prompts rather than executing shell commands. - Minor note: SKILL.md's claim 'no API keys required' is true for the main Ctrip flow, but an optional zbape key is supported — only supply keys you trust. If you want higher assurance, inspect the bundled scripts (they are included) and confirm you are comfortable with local config files and outbound network connections before enabling automatic monitoring.

Capability Analysis

Type: OpenClaw Skill Name: flight-monitor Version: 1.1.1 The flight-monitor skill bundle is a well-structured tool for querying and monitoring flight prices with support for mobile notifications. The implementation demonstrates good security awareness, incorporating strict regex-based input validation and path boundary checks in `monitor_manager.py` and `price_history.py` to mitigate path traversal risks. The scripts interact with legitimate third-party APIs (e.g., flights.ctrip.com, api.zbape.com, and notification services like api.day.app) solely to perform the stated functions, with no evidence of malicious intent, data exfiltration, or harmful prompt injection.

Capability Assessment

ℹ Purpose & Capability

Overall the requested files, network calls, and local storage align with a flight search + monitoring skill. Minor inconsistency: SKILL.md states '无需 API 密钥' (no API keys required) while search_flights.py supports an optional zbape API key stored in ~/.workbuddy/flight-monitor/api_config.json; this is optional and not required for the primary Ctrip-based flow, but the README claim is slightly optimistic.

✓ Instruction Scope

SKILL.md gives precise runtime steps: run search_flights.py (primary), fall back to a single web_search only if needed, record results via price_history.py, and send notifications via notify.py. The instructions explicitly forbid arbitrary web_fetch and limit web_search use to one query, and the scripts operate only on per-route files under ~/.workbuddy. There are no instructions to read unrelated system files or environment secrets.

✓ Install Mechanism

No install spec / remote downloads are present — the skill is instruction + bundled scripts. All code is local and there is no installer that fetches arbitrary remote archives. This is a lower-risk distribution model (files are present in the skill bundle).

ℹ Credentials

The skill requests no environment variables or platform credentials. It does write/read configuration and history under the user's home (~/.workbuddy). Optional credentials are stored only if the user configures them: push service keys (Bark/Server酱/PushDeer) and an optional zbape API key. Storing user-provided keys locally is expected for push/API features but users should be aware these keys are stored in plaintext JSON in their home directory.

✓ Persistence & Privilege

The skill does persist monitor tasks and history under ~/.workbuddy and creates TOML/JSON files there; always: false and it does not request system-wide privileges. Code includes path boundary checks and whitelist regexes to prevent path traversal. The skill does not modify other skills' configs or request permanent platform-level privileges.

Version History

v1.1.1

- Functionality, workflow, and usage remain the same as the previous version.

v1.1.0

修复了以下漏洞： 1、shell 注入 2、路径穿越

v1.0.0

flight-monitor 1.0.0 - Initial release: Flight monitoring and price alert skill for domestic and international routes. - Supports one-way and round-trip flight search, price threshold alerts, and scheduled monitoring. - Push notifications via Bark, Server酱, or PushDeer. - Allows management of monitoring tasks: view, pause, or delete any active monitor. - Simple command interface for Chinese/English queries. - No API keys or browser automation required; leverages multi-source data with clear fallback logic.

Metadata

Slug flight-monitor

Version 1.1.1

License MIT-0

All-time Installs 1

Active Installs 1

Total Versions 3

Frequently Asked Questions

What is flight-monitor?

机票查询与价格监控技能。支持单程/往返查询、价格阈值提醒、定时监控、手机推送通知（Bark/Server酱/PushDeer）。触发词示例：查一下北京到三亚的机票、帮我看看上海飞成都下周六往返票、监控杭州到西安3月26日机票低于500提醒我、查看所有机票监控任务。 It is an AI Agent Skill for Claude Code / OpenClaw, with 272 downloads so far.

How do I install flight-monitor?

Run "/install flight-monitor" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is flight-monitor free?

Yes, flight-monitor is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does flight-monitor support?

flight-monitor is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created flight-monitor?

It is built and maintained by JackZhao3925 (@jackzhao3925); the current version is v1.1.1.

More Skills

flight-monitor