China Travel Planner

Data & APIs

Plan and optimize travel within China using flyai / Fliggy search capabilities plus public metro-network data when needed. Use when the user wants a domestic China trip plan, weekend getaway, city itinerary, family trip, holiday route, hotel recommendation, flight comparison, attraction shortlist, budget-based plan, or a practical travel guide that combines transportation, hotel, POI, and day-by-day scheduling for destinations inside mainland China. Also use when the trip has transit constraints such as covering every metro line at least once, choosing hotels by metro convenience, anchoring plans around a fixed hotel, or mixing city travel with nearby side trips.

Install

openclaw skills install china-travel-planner

China Travel Planner

Plan practical domestic trips in China by combining itinerary design with real-time-ish search from flyai.

This skill is for planning-first travel help. Use it to turn a vague request like “清明去杭州玩两天怎么安排” into a usable plan with destination logic, transport suggestions, hotel area recommendations, attraction picks, and a day-by-day itinerary.

Core workflow

Clarify the trip frame
- Extract or ask for: departure city, destination, travel dates, duration, traveler type, budget, pace, and priorities.
- Also detect hard constraints such as:
  - fixed hotel already booked
  - must-visit cities
  - every metro line must be ridden at least once
  - hotel must be close to a given metro line / station / interchange
- If the user is vague, make reasonable assumptions and label them clearly.
Pick the planning mode
- Light plan: quick destination ideas or a rough 1-3 day outline.
- Standard plan: transport + hotel area + POIs + daily itinerary.
- Comparison plan: compare 2-3 destinations, hotel zones, or transport options.
- Booking-oriented plan: prioritize flight/hotel/ticket search and provide booking links.
- Transit-constrained plan: optimize around metro-line coverage, fixed hotel anchors, or nearby side trips.
Choose the right data source mix
- Use flyai fliggy-fast-search for broad natural-language discovery.
- Use flyai search-flight for flight comparison when flights matter.
- Use flyai search-hotels for hotel options near a city or POI.
- Use flyai search-poi for attraction candidates inside the target city.
- Use public metro data when the plan depends on line coverage, station lists, or metro-aware hotel selection.
Turn results into a China-friendly plan
- Prefer practical advice over generic marketing copy.
- For domestic travel, explicitly cover:
  - how to arrive: plane / high-speed rail / city transfer logic
  - where to stay: district / landmark / transport convenience
  - must-see vs optional POIs
  - crowd avoidance / holiday pressure / realistic pacing
  - budget bands
  - if transit constraints exist: which lines are covered on which days
Produce a final answer that is actually usable
- Start with the recommendation.
- Then give the itinerary and concrete options.
- Keep it readable; do not dump raw JSON unless the user explicitly wants structured output.
When the trip may become a web page or reusable artifact, also prepare structured data
- Prefer a stable JSON structure that can populate reusable cards and sections.
- Align with a page-data model such as: meta, hero, stats, hotels, metroCoverage, days, sideTrips, attractions, tips.
- Keep destination-specific wording in data values, not in page/template structure.

Planning heuristics for domestic China trips

Trip type presets

1. Weekend / short break

Default to 2D1N or 3D2N.
Prefer compact cities or one core area.
Avoid stuffing too many attractions into one day.
Optimize for low transfer friction.

2. Family trip

Prefer fewer hotel changes.
Reduce aggressive early departures.
Prioritize stable meal / restroom / stroller / queue conditions when relevant.
Recommend attractions with mixed-age tolerance.

3. Holiday trip

Warn about crowding, traffic, and price spikes.
Suggest early/late entry windows and alternative districts.
Offer a mainstream plan plus a crowd-avoidance backup.

4. Budget trip

Prioritize rail over flight where reasonable.
Prefer transport-convenient hotel areas over luxury scenic isolation.
Separate “must spend” from “optional upgrade”.

5. Relaxed trip

Limit major POIs per day.
Add café / night walk / slow sightseeing blocks.
Favor one scenic area plus one food/urban area per day.

How to use flyai commands

A. Broad discovery

Use when the user is still fuzzy, such as:

“杭州三天怎么玩”
“五一国内去哪儿适合亲子”
“苏州周末度假住哪方便”

Command pattern:

flyai fliggy-fast-search --query "杭州三日游"

Use broad search first to collect candidate products, local experiences, hotel packages, or bundled travel ideas.

B. Flight comparison

Use when the user is traveling farther or explicitly asks about flights.

Command pattern:

flyai search-flight --origin "北京" --destination "杭州" --dep-date 2026-04-04 --sort-type 3

Prefer sorting by:

3 for lowest price
8 for direct-priority
4 for shortest duration

For domestic planning, mention whether high-speed rail may be more sensible if flight transfer friction is high.

C. Hotel search

Use when deciding where to stay, especially around scenic areas or transit hubs.

Command pattern:

flyai search-hotels --dest-name "杭州" --poi-name "西湖" --check-in-date 2026-04-04 --check-out-date 2026-04-06 --sort rate_desc

Hotel guidance:

If the user values convenience, recommend by area first, hotel second.
Explain why the area works: near metro / scenic area / food street / station.
When budget is unclear, give 3 price bands if possible.

D. POI search

Use when building the daily route.

Command pattern:

flyai search-poi --city-name "杭州" --keyword "西湖"

Group POIs into:

must-see
optional swap-ins
niche / backup choices

Output rules

Always return a curated plan, not raw command output.
If flyai returns image URLs, place the image line before the booking link.
If flyai returns booking/detail URLs, include them when helpful.
Mention that recommendations are based on fly.ai / Fliggy results when using those results.
In Feishu chats, prefer bullets over markdown tables unless the comparison truly benefits from a table.

Structured output mode for reusable web pages

When the user wants a web page, reusable framework, shareable itinerary page, or future automation, also organize the content into stable sections.

Recommended top-level keys:

meta
hero
stats
hotels
metroCoverage
days
sideTrips
attractions
tips

What to produce

Whenever possible, produce two synchronized layers:

Readable itinerary summary
Structured trip data

The readable summary should be easy to read in chat. The structured layer should be easy to feed into travel-page-framework.

Card conventions

Hotel cards

Use fields such as:

phase
name
dateRange
station
status
price
distanceToMetro
image
highlights

Day cards

Use fields such as:

day
date
theme
city
hotel
metroLines
segments.morning
segments.afternoon
segments.evening
note

Attraction cards

Use fields such as:

name
city
type
image
description
bestFor

Keep structured card text concise and web-friendly.

Working rule

If the user explicitly wants a web page, page framework, reusable travel card layout, or future rendering, read references/structured-output-mode.md and organize the plan so the text layer and structured layer remain consistent.

Page generation pipeline

Use this when the user wants a shareable web page, standalone HTML itinerary, or asks for a "travel page" / "行程页面". The pipeline turns a travel plan into a static HTML page powered by the travel-page-framework.

Flow

plan (chat) → structured trip-data.json → tpf-generate → tpf validate → tpf build → dist/index.html

Step-by-step

Plan the trip using the normal planning workflow above.
Generate structured JSON from a natural-language prompt:

python3 skills/china-travel-planner/page-generator/scripts/tpf-generate.py \
  "杭州3天2晚，西湖+灵隐寺，住湖滨，预算2000" \
  --with-metro --with-images --pretty \
  -o data/trip-data.json

Options:

--with-metro: auto-fetch metro/subway data for the city
--with-images: auto-search Wikimedia Commons for attraction images
--from-file prompt.txt: read prompt from a file instead of CLI arg
--output / -o: output path (default: trip-data.json)
--pretty: pretty-print the JSON

Review and refine the generated trip-data.json. The auto-generated skeleton is a starting point — fill in richer descriptions, swap placeholder images, and adjust day-by-day segments as needed. Follow the content guidelines in page-generator/schema/trip-content-guidelines.md.
Validate the data against the schema:

cd <project-dir>   # must contain data/trip-data.json
python3 skills/china-travel-planner/page-generator/scripts/tpf-cli.py validate

Build the static site:

python3 skills/china-travel-planner/page-generator/scripts/tpf-cli.py build

This produces dist/index.html + dist/trip-data.json. Preview with:

cd dist && python3 -m http.server 8080

(Optional) Deploy to GitHub Pages:

python3 skills/china-travel-planner/page-generator/scripts/tpf-cli.py deploy --to gh-pages

Schema and content guidelines

JSON schema: page-generator/schema/trip-schema.json
Content writing guide: page-generator/schema/trip-content-guidelines.md
Required top-level keys: meta, hero, stats, hotels, metroCoverage, days, sideTrips, attractions, tips

When to use tpf-generate vs manual JSON

tpf-generate: quick scaffolding from a one-liner prompt. Good for getting the structure right fast.
Manual JSON: when you already have a detailed plan from the chat workflow and want precise control over every field.

In practice, generate the skeleton first, then hand-edit or have the agent refine it.

When information is missing

If critical info is missing, ask at most the smallest set of questions needed. Prioritize:

出发地
日期 / 天数
预算
几个人、什么类型（情侣 / 亲子 / 家庭 / 独自）

If the user just wants a quick answer, do not block on questions. State assumptions and give a draft plan.

Scripts

`scripts/fetch_subway_data.py`

Use this script when the plan depends on metro / subway line coverage or station lists.

Examples:

python3 skills/china-travel-planner/scripts/fetch_subway_data.py 长沙 --pretty
python3 skills/china-travel-planner/scripts/fetch_subway_data.py changsha --stations-only --pretty
python3 skills/china-travel-planner/scripts/fetch_subway_data.py 湘潭 --pretty

Behavior:

reads the AMap subway city index
resolves the city by Chinese name / pinyin / city id
fetches line + station data
outputs JSON for downstream planning

Use the result to:

count how many lines a city has
list line names
see station lists for each line
support "every line must be ridden once" planning

`scripts/metro_hotel_match.py`

Use this script to rank hotels by metro convenience.

Examples:

python3 skills/china-travel-planner/scripts/metro_hotel_match.py \
  --subway changsha-subway.json \
  --hotels hotels.json \
  --target-line "1号线" \
  --target-station "黄土岭" \
  --pretty

Behavior:

reads subway JSON and hotel JSON
scores hotels by target station / line mentions plus transit-convenience hints
returns a ranked list with reasons

`scripts/coverage_plan_notes.py`

Use this script to generate lightweight notes for line-coverage planning.

Examples:

python3 skills/china-travel-planner/scripts/coverage_plan_notes.py \
  --subway changsha-subway.json \
  --hotel-station "黄土岭" \
  --pretty

Behavior:

summarizes each line
notes whether the hotel anchor lies on that line
gives rough planning hints for route design

`page-generator/scripts/wikimedia_image_search.py`

Use this script to find free-license images from Wikimedia Commons for attractions, landmarks, or city scenes. Use it when populating image fields in structured trip data.

Keyword search:

python3 skills/china-travel-planner/page-generator/scripts/wikimedia_image_search.py "橘子洲 长沙" --limit 3 --pretty

Category browse:

python3 skills/china-travel-planner/page-generator/scripts/wikimedia_image_search.py --category "Orange Isle" --limit 5 --pretty

Batch mode (read a JSON file with multiple search specs):

python3 skills/china-travel-planner/page-generator/scripts/wikimedia_image_search.py \
  --batch landmarks.json --output results.json --pretty

Batch input format (landmarks.json):

[
  {"name": "五一广场", "query": "Changsha Wuyi Square"},
  {"name": "橘子洲", "category": "Orange Isle"},
  {"name": "岳阳楼", "query": "Yueyang Tower Hunan"}
]

Options:

--limit / -n: number of results (default: 5)
--width / -w: thumbnail width in pixels (default: 1200)
--output / -o: write results to file instead of stdout
--pretty: pretty-print JSON

Output: JSON array of {title, url, thumbUrl, width, height, license, description}. All images carry free licenses (CC / Public Domain).

References

Read these only when needed:

../flyai/references/fliggy-fast-search.md for broad natural-language search
../flyai/references/search-flight.md for flight parameters and output fields
../flyai/references/search-hotels.md for hotel filters and fields
../flyai/references/search-poi.md for attraction filters and fields
references/subway-aware-planning.md for metro-line coverage, fixed-hotel anchors, and metro-aware hotel selection
references/domestic-planning-prompts.md for common domestic trip phrasing and default itinerary patterns
references/structured-output-mode.md for producing reusable structured trip data alongside readable itinerary text
page-generator/schema/trip-content-guidelines.md for reusable travel-page content structure and card-writing conventions

China Travel Planner

Install

China Travel Planner

Core workflow

Planning heuristics for domestic China trips

Trip type presets

1. Weekend / short break

2. Family trip

3. Holiday trip

4. Budget trip

5. Relaxed trip

How to use flyai commands

A. Broad discovery

B. Flight comparison

C. Hotel search

D. POI search

Output rules

Recommended answer structure

Fast recommendation

Trip snapshot

Day-by-day itinerary

Hotel suggestion

Transport suggestion

Notes

Structured output mode for reusable web pages

What to produce

Card conventions

Hotel cards

Day cards

Attraction cards

Working rule

Page generation pipeline

Flow

Step-by-step

Schema and content guidelines

When to use tpf-generate vs manual JSON

When information is missing

Scripts

scripts/fetch_subway_data.py

scripts/metro_hotel_match.py

scripts/coverage_plan_notes.py

page-generator/scripts/wikimedia_image_search.py

References

Related skills

`scripts/fetch_subway_data.py`

`scripts/metro_hotel_match.py`

`scripts/coverage_plan_notes.py`

`page-generator/scripts/wikimedia_image_search.py`