| name | multi-user-trip-planner |
| description | Plan coordinated multi-user high-speed rail trips; when users need multi-person trip planning from different origins to one destination |
| dependency | {"python":["pydantic>=2.0","fastapi","uvicorn","httpx","requests","mcp"]} |
Multi-user Trip Planner
Plan and rank coordinated rail itineraries where N travelers depart from different origins and converge on one destination. Uses real-time 12306 data with three-tier fallback (12306-direct -> 12306-mcp -> distance-estimation).
When to Use This Skill
- User mentions multi-person trip planning ("我在广州，朋友在武汉，我们要去北京")
- Same-train routing across multiple boarding stations
- Transfer-merge meetup at intermediate hub
- Synchronized arrival from different departure cities
- Group rail trip comparison and ranking
- Chinese city names (广州、武汉、北京、同步到达、同车、中转)
Core Principles
- Real-time data first: Always query 12306 API before estimation. Never fabricate train schedules or prices.
- LLM does NOT filter or generate strategies: The skill handles data fetching, strategy generation, constraint validation, and scoring. LLM only parses intent, asks follow-ups, and presents results.
- Strategy diversity: Results include different strategy types (same-train, partial-same-train, transfer-merge, synchronized-arrival), not just variations of one strategy.
- Graceful degradation: When no feasible plans exist, provide relaxation suggestions. When API fails, fall back to estimation.
Quick Start
- Quick plan: Call
trip_planner_quick_plan(origins="Guangzhou,Wuhan", destination="Beijing", date="2026-04-20")
- Review results: Check
top_plans for ranked options with scores, strategies, and trade-offs
- Present to user: Explain top 2-3 options with key differences (time, price, arrival spread)
- Adjust if needed: If
total_feasible == 0, check relaxation_suggestions and re-run with relaxed constraints
Tool Selection
| Scenario | Tool | Why |
|---|
| Natural language / vague request | trip_planner_parse_request | Extract structured params from free text |
| Quick planning, only know cities + date | trip_planner_quick_plan | Minimal input, auto-resolves from real-time data, Chinese support |
| Full structured data ready | trip_planner_plan | Full control over constraints and weights |
| Data in JSON file | trip_planner_plan_from_file | Batch processing |
| Need auto-fetched candidates | trip_planner_plan_with_provider | Auto provider with real-time data |
| Explain a plan result | trip_planner_explain | Human-friendly summary |
| Verify station names | trip_planner_validate_stations | Check against verified database |
| List supported cities | trip_planner_list_cities | Show all 157 supported cities |
Weight Profiles
| Profile | Focus | When to Use |
|---|
balanced | Even trade-off | Default |
speed-first | Minimize travel time | Urgent trips |
comfort-first | Minimize transfers + standing | Elderly, families |
budget-first | Minimize price | Cost-sensitive |
sync-first | Minimize arrival gap | Must arrive together |
LLM Collaboration Rules
LLM MUST NOT: Fabricate train data, filter candidates based on own knowledge, decide which strategies to apply, override validation results.
LLM SHOULD: Extract structured params from natural language, ask follow-ups for missing info, present results in user-friendly language, help users choose between options, re-invoke skill with adjusted params when needed.
Data source transparency: Output always indicates data source. If distance-estimation was used, inform user that times and prices are approximate.
Navigation
For detailed information:
- Architecture & Data Flow:
references/architecture.md - Three-tier data acquisition, LLM-Skill boundary, complete pipeline
- API Reference:
references/api-reference.md - Full input/output schemas, tool parameters, provider modes
- Strategy Guide:
references/strategies.md - Strategy semantics, scoring formula, constraint rules, examples
Key Reminders
- ALWAYS use
trip_planner_quick_plan as the default entry point for most user requests
- When
total_feasible == 0, check relaxation_suggestions before telling user "no plans found"
- Data source
12306-direct = real-time; distance-estimation = approximate — always disclose this
- Default
data_source=auto (three-tier fallback) — no need to specify unless user requests a specific provider
- Chinese city names are supported in
trip_planner_quick_plan and trip_planner_parse_request
Execution
MCP Server
pip install mcp
python ${CLAUDE_SKILL_DIR}/scripts/mcp_server.py
CLI
python ${CLAUDE_SKILL_DIR}/scripts/plan_trips.py --input input.json --topk 3
FastAPI
pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt
python ${CLAUDE_SKILL_DIR}/scripts/service_api.py
Environment Variables
| Variable | Description | Default |
|---|
TRIP_PLANNER_12306_MCP_URL | 12306-MCP server endpoint | (empty) |
TRIP_PLANNER_CACHE_DIR | Cache directory | .cache/trip_planner |
TRIP_PLANNER_LOG_LEVEL | Logging level | WARNING |
