Skip to content

tanweiping1012-source/travel-planner

travel-planner-mvp

Verified

Create evidence-backed, read-only travel plans using Amap, a community 12306 rail MCP, and approved browser research. Use for 行程规划、路线安排、景点取舍、高铁或机票比较、酒店住宿比价、预算分析、旅行可行性检查,以及中国境内多城市旅行规划(境外目的地降级为浏览器辅助规划)。

FileKindSize
SKILL.mdskill md12.5 KB
agents/openai.yamlconfig344 B
examples/final_plan.jsonconfig2.6 KB
examples/itinerary.jsonconfig1020 B
examples/rail_query.jsonconfig2.9 KB
examples/social_research.jsonconfig1.3 KB
examples/trip_request.jsonconfig1.1 KB
references/browser-use.mdmarkdown14.8 KB
references/client-compatibility.mdmarkdown5.4 KB
references/data-contracts.mdmarkdown26.6 KB
references/intake-template.mdmarkdown4.9 KB
references/rail-mcp.mdmarkdown4.3 KB
references/script-tools.mdmarkdown3.5 KB
references/workflow.mdmarkdown13.3 KB
scripts/audit_release.shexecutablescript3.4 KB
scripts/prepare_release.shexecutablescript1.8 KB
scripts/setup_amap_key.shexecutablescript828 B
scripts/setup_rail_mcp.shexecutablescript3.8 KB
scripts/travel_planner.pyexecutablescript11.8 KB
scripts/validate_skill.pyexecutablescript5.5 KB

references/workflow.md

View on GitHub
# Read-Only Workflow

## State Machine

```text
COLLECT_REQUIREMENTS
  -> VALIDATE_REQUEST
  -> CLARIFY_CONSTRAINTS (only when validator requires it)
  -> SOURCE_PREFLIGHT
  -> REQUEST_BROWSER_APPROVAL
  -> SOCIAL_RESEARCH
  -> COMPILE_DESTINATION_BRIEF
  -> VALIDATE_PLACES_AND_LOCAL_ROUTES
  -> BUILD_ROUTE_SKELETONS
  -> TRANSPORT_RESEARCH
  -> ATTACH_PRICES
  -> FEASIBILITY_CHECK
  -> REPAIR_OR_RANK
  -> CONTENT_COMPLETENESS_CHECK
  -> REFRESH_DYNAMIC_DATA
  -> PRESENT
```

Never let raw provider responses enter candidate generation.
Do not perform Xiaohongshu and OTA browser research concurrently.

## Intake Gate

1. Normalize the initial user message or README form into `trip_request.json`.
2. Run `validate-request`.
3. When status is `READY`, proceed without repeating any intake question.
4. When status is `NEEDS_CLARIFICATION`, ask one batched question containing
   every returned missing field and conflict.
5. When status is `INVALID`, request corrected values before source research.
6. Ask again later only when live evidence introduces a new material conflict.

Examples of new material conflicts include:

- A `CORE` place is closed or legally inaccessible.
- A route exceeds the stated mobility or altitude limit.
- The only feasible route exceeds the stated budget.
- A weather-dependent core experience conflicts with the user's declared risk
  tolerance.
- A required login mode exceeds the approved Browser Use scope.

Do not ask about lower-value optional preferences when a labeled assumption can
resolve them. Safety and legal access never become optional trade-offs.

## Source Preflight

Return one status per connector:

```text
READY
PUBLIC_READY
LOGIN_REQUIRED
CONNECTED
EXPIRED
DEGRADED
BLOCKED
UNAVAILABLE
```

Required checks:

- Amap credential exists and one live POI request succeeds.
- The local 12306 MCP lists its expected read-only tools.
- OTA and Xiaohongshu access matches the validated provider-specific approval.
- Browser session state is observed, never assumed.

## Phase 1: Destination Research

Xiaohongshu is a discovery input, so it must run before transport pricing.

1. Search style, duration, public-transport, and risk-oriented queries.
2. Start anonymously and request manual login only when the page requires it.
3. Read three to eight high-signal notes.
4. Extract place names, timing advice, queue reports, and risk claims.
5. Preserve every selected note URL and normalize the evidence.
6. Finish or explicitly stop the Xiaohongshu phase.
7. Compile results with `compile-research`.
8. Produce a `DestinationBrief` containing:
   - Candidate places
   - Defining features
   - Why each place fits the requested style
   - Suggested duration and best time
   - Physical load and accessibility concerns
   - Transport and queue claims
   - Source URLs and confidence

The phase is incomplete when it only produces place names.

## Coverage Gate

Before any map work, establish whether the destination is inside Amap's
coverage. Geocode the destination city with `expect_settlement=True`.

A refusal is the expected answer for anywhere outside mainland China, and it
is the safe one. Amap does not return nothing for a place it does not have —
it returns the closest Chinese name with plausible coordinates, so 东京 comes
back as a village in Guangxi and 捷里别尔卡 as one in Guizhou. Coordinates
like these look exactly like verified facts and poison every distance and
duration computed from them.

This gate is a deliberate early check, not the only protection: `amap-snapshot`
resolves the trip's own origin and destination the same protected way
internally, so calling it directly does not bypass the refusal. Running this
gate first still matters, because it decides overseas mode *before* spending a
social-research phase or a route query on a destination that turns out to be
uncovered.

When the destination is outside coverage, the run continues in **overseas
mode**:

- Do not claim a verified POI, coordinate, or ground route.
- Do not produce transfer segments from map durations; there are none.
- Rail is unavailable; 12306 covers only mainland China.
- Browser research is the only remaining source, so the plan rests on it and
  must say so.
- Feasibility still runs, but with no route data it checks little. Say which
  checks were skipped rather than presenting the verdict as complete.
- `doctor` reporting `amap READY` means the credential works. It says nothing
  about whether the destination is covered.

## Phase 2: Place and Route Validation

### Map branch

1. Resolve origin, destination, airports, stations, and candidate places with
   `search-places`.
2. Reject closed or ambiguous POIs.
3. Validate every selected place from the destination brief.
4. Group nearby places into coherent day clusters.
5. Run `amap-snapshot` for every local route needed by a candidate — this is
   what a day cluster's real walking, transit, and driving time is measured
   against, not an estimate.

Do not ask the OTA for prices until at least one route skeleton exists.

## Phase 3: Transport Research

### Rail branch

1. Resolve station names with `search-stations`.
2. Query direct availability with `query-tickets`.
3. Query exact fares with `query-ticket-price`.
4. Query transfers only when direct service is unsuitable.
5. Normalize every payload with `normalize-rail` before reading any seat
   value. Availability mixes integers with `有` and `无`, so comparing the raw
   values is unsafe and `int()` raises on the words.
6. Map a selected train into an **activity**, not a segment. The journey time
   belongs to the ride itself; reaching the station is a separate segment
   measured by the map provider.
7. Keep the MCP source label and query timestamp.

### Flight branch

This branch starts only after the social browser phase is complete and the
route skeleton identifies the required gateway city and time windows.

1. Use Browser Use on an approved OTA web domain. Flight lists load
   asynchronously: the page title and the date field settle long before the
   results do, so an empty read is not an empty result. Re-read after a wait
   instead of concluding there are no flights, and observe the failure policy
   — stop after two consecutive empty reads rather than retrying indefinitely.
2. Start with the route skeleton's gateway and arrival/departure deadlines.
3. Search exact airports or city groups, dates, travelers, and cabin.
4. Extract visible offers only.
5. Retain channel, login state, baggage visibility, and timestamp.
6. Reject cheap offers that break downstream transfers.
7. Never interpret a monthly-low-price page as the requested live fare. The
   date strip above the results is exactly such a page. It is worth reading,
   because a neighbouring date is often dramatically cheaper, but a figure
   taken from it is a `PRICE_SIGNAL`: report it as a reason to check that
   date, never as a fare that was found.
8. Run `validate-flights` before any offer influences a candidate. It rejects
   a leg whose arrival precedes its departure, flags a stated duration that
   disagrees with the clock, and requires the unguaranteed-price caveat.
9. Map a selected flight into an **activity** carrying the check-in buffer,
   120 minutes domestic and 180 international.

### Lodging branch

Runs once the day clusters from the map branch exist, so candidate hotels can
be chosen by which places each day actually visits rather than by city alone —
this is the step that lets accommodation feed back into the route instead of
being bolted on after it is fixed.

1. **The login handoff happens before anything else.** An OTA hotel list shows
   a signed-out visitor no price at all — not a thin one, none — so this
   branch begins exactly like Xiaohongshu: stop, block on the question tool,
   name the site, and wait. Do not attempt a lodging search anonymously first;
   unlike flights, there is nothing there.
2. Search each day cluster's area, the stated check-in and check-out dates,
   and room count.
3. Extract visible offers: name, room type, the per-night card price, rating,
   and cancellation terms.
4. Record `login_state` and `member_tier` with every quote. A quote gathered
   signed out is impossible by construction; a quote gathered signed in
   without its tier cannot be told apart from a stranger's price.
5. Run `validate-lodging` before any offer influences a candidate. It derives
   the stay total from nights and rooms rather than trusting a card price —
   `¥556 起` for six nights is `¥3,336`, not `¥556` — and flags offers
   gathered under different login states or tiers as not comparable to each
   other.
6. Reject a cheap offer with no free cancellation when the itinerary still has
   open feasibility risk; a rate that cannot be released costs more than it
   saves if an earlier repair later moves the traveller elsewhere.

## Browser Phase Gate

Use one browser worker and one dynamic site at a time:

```text
XIAOHONGSHU_OPEN
  -> XIAOHONGSHU_DONE | XIAOHONGSHU_BLOCKED
  -> SAVE_SOCIAL_RESEARCH
  -> CLOSE_OR_FREEZE_XIAOHONGSHU_TABS
  -> OTA_FLIGHT_OPEN
  -> OTA_FLIGHT_DONE | OTA_FLIGHT_BLOCKED
  -> SAVE_FLIGHT_RESEARCH
  -> OTA_LODGING_LOGIN_HANDOFF
  -> OTA_LODGING_OPEN
  -> OTA_LODGING_DONE | OTA_LODGING_BLOCKED
  -> SAVE_LODGING_RESEARCH
```

The flight and lodging phases share a domain and do not share a login state:
Ctrip flights read anonymously, Ctrip hotels do not. Finishing the flight
phase proves nothing about whether the lodging phase can skip its handoff.

Do not spawn a second browser worker to recover while the first worker is still
active. Instead, set a bounded phase budget and ask the same worker to return
partial results.

Recommended budgets:

- Login handoff: wait for the user without running another browser phase.
  This applies identically to Xiaohongshu and to Ctrip lodging.
- Xiaohongshu: three focused queries, three to eight notes, then stop.
- OTA flight search: up to ten representative offers.
- OTA flight follow-up: one additional time-window filter.
- OTA lodging search: up to ten representative offers per day cluster.
- A phase with no progress after two snapshot/recovery cycles becomes `BLOCKED`.

## Candidate Generation

Always build:

- Economy: lowest expected total cost that remains feasible.
- Balanced: best trade-off among cost, time, and style.
- Relaxed: fewer moves, larger buffers, and lower daily load.

Do not force three materially identical candidates.

Each day must answer:

- Where does the traveler go?
- What are the defining features of each major place?
- Why is it included for this travel style?
- How long should the traveler stay?
- How does the traveler move to the next place?
- What is the physical load and major caveat?

A timeline containing only transport segments is invalid.

## Feasibility and Repair

Run `evaluate`. Repair in this order:

1. Adjust activity times.
2. Increase transfer buffers.
3. Change transport option.
4. Swap adjacent places.
5. Move an optional place to another day.
6. Remove the lowest-priority optional place.

Stop after three repair attempts. Preserve infeasible candidates only when they
help explain a trade-off.

## Content Completeness

Run `validate-plan` before presentation. A plan fails when:

- It has no attraction day.
- A major attraction has no features or reason to visit.
- A day has no activity description.
- A transition between consecutive activities has no transport segment.
- Browser-derived prices lack channel or timestamp.
- A lodging offer lacks `login_state`, or was gathered signed out — Ctrip
  shows no room price to an anonymous visitor, so such an offer cannot be
  genuine.

`validate-plan` runs `validate-lodging` internally, so a plan with a broken
lodging quote fails here even if nothing else references it.

Do not present an invalid plan as complete.

## Dynamic Refresh

Immediately before presentation:

- Re-query shortlisted rail options.
- Re-open or refresh shortlisted flight results.
- Re-run `validate-flights` with the presentation time. `STALE_FLIGHT_PRICE`
  means the offer must be looked up again, not relabelled: the default limit
  is two hours, because a rail fare barely moves while an airfare from this
  morning may already be wrong.
- Re-run `validate-lodging` with the presentation time. Its default staleness
  window is twelve hours — a room rate moves slower than an airfare, but
  holiday-peak availability does not, and a `STALE_LODGING_PRICE` offer needs
  the same re-query as a stale fare, not a relabel.
- Re-run affected transfer checks if times or airports changed.
- Mark a result stale when refresh fails.

## Failure Policy

- Missing API key: stop live-map planning and explain how to configure it.
- Amap authentication error: retry at most once.
- Rail MCP blocked: fall back to read-only 12306 Browser Use only with approval.
- OTA login required: ask the user to take control; never type credentials.
- Xiaohongshu login required: ask the user to scan or log in manually.
- Missing social results: continue with map and official sources, and disclose the gap.
- Route unavailable: mark the candidate infeasible; never invent duration.
- Stale price or schedule: label it as reference-only and request a refresh.
- Captcha or blocked page: stop browser automation; do not bypass it.
- Browser and API sources conflict: keep both and explain the conflict.

## Safety Boundary

This workflow is read-only. It must never purchase, reserve, pay, publish,
comment, like, follow, or modify an external account.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall