multi-user-trip-planner

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

1. Real-time data first: Always query 12306 API before estimation. Never fabricate train schedules or prices.
2. 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.
3. Strategy diversity: Results include different strategy types (same-train, partial-same-train, transfer-merge, synchronized-arrival), not just variations of one strategy.
4. Graceful degradation: When no feasible plans exist, provide relaxation suggestions. When API fails, fall back to estimation.

Quick Start

1. Quick plan: Call trip_planner_quick_plan(origins="Guangzhou,Wuhan", destination="Beijing", date="2026-04-20")
2. Review results: Check top_plans for ranked options with scores, strategies, and trade-offs
3. Present to user: Explain top 2-3 options with key differences (time, price, arrival spread)
4. Adjust if needed: If total_feasible == 0, check relaxation_suggestions and re-run with relaxed constraints

Tool Selection

Weight Profiles

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