Skill: rudy2steiner/flyai-travelmapify (version 2.2.2)

--- name: flyai-travelmapify version: 2.2.2 description: Create interactive travel route maps from location names with real FlyAI hotel search. Supports AI Vision analysis of travel planning images. author: rudy2steiner license: MIT tags: [travel, maps, routing, geocoding, flyai, hotels, unique-id, server-management, interactive, ai-vision] --- # Travel Mapify Create interactive, professional travel route maps from location names. ## Overview This skill automatically: 1. **Processes text input**: Parses comma-separated location names directly 2. **Geocodes locations** to get precise coordinates using Amap API 3. **Generates interactive maps** with route optimization and POI management 4. **Supports AI Vision workflow**: When given travel planning images, use agent's AI Vision to extract POI names, then process as text input 4. **Geocodes locations** to get precise coordinates using Amap API 5. **Generates interactive maps** with route optimization and POI management 6. **Integrates real hotel search** using FlyAI for actual hotel recommendations 7. **Creates professional outputs** ready for sharing and presentation ## When to Use **Text Input Mode:** - User provides comma-separated location names directly (e.g., "上海外滩,上海迪士尼乐园,豫园") - User wants to quickly create a travel map from a simple list of destinations - User has location names but no visual reference image **AI Vision Image Processing Workflow:** - User has a travel planning image (screenshot, photo, or digital plan) - Agent uses AI Vision to analyze the image and extract POI names with sequence/order - Extracted POI names are passed as text input to the skill - This hybrid approach combines AI automation with the skill's robust text processing **Hotel Integration Mode:** - User wants real hotel recommendations near their destination - User needs actual pricing and availability data - User wants booking links for hotels through FlyAI integration ## Workflow ### Step 1: Input Processing and POI Extraction **For Direct Text Input:** - Parse comma-separated location names directly - Create POI entries with high confidence (user-provided) - **Automatic city detection**: Smart city detection from location names (e.g., "北京军事博物馆" → city="北京") - **Fallback to default**: Uses Shanghai as default when no city can be detected **For Image Input (AI Vision Workflow):** - **Use agent's AI Vision capability** to analyze travel planning images - **Extract POI names and sequence** from numbered markers or route indicators - **Preserve exact order** as marked in the original image - **Pass extracted names as text input** to the skill's standard processing pipeline - **Leverage existing text processing** for geocoding, validation, and map generation ### Step 2: Geocoding and Coordinate Resolution - Use Amap geocoding API to resolve location names to precise coordinates - Handle ambiguous locations with user confirmation - Validate coordinate accuracy ### Step 3: Enhanced Map Generation - **Use optimized travel_mapify with unique map ID isolation** as main template with all UX improvements - **Automatic localStorage isolation** based on POI names to prevent data conflicts between different maps - **Optimized performance** with streamlined template generation and reduced dependencies - Create a single dual-mode interface with toggle between Edit/View modes - Implement drag-and-drop and arrow button reordering (edit mode only) - Generate optimized route with directional arrows - Add "Generate Final" functionality to download clean version - **Integrate real FlyAI hotel search** with professional loading states - **Replace alert popups** with notification system ### Step 4: Automatic Server Management - **Automatically start HTTP server** on port 9000 (or specified port) - **Automatically start hotel search server** on port 8770 (or specified port) - **Check if servers are already running** to avoid conflicts - **Provide direct access URLs** in output - **Ensure all functionality is ready** when map creation completes ### Step 4: Professional Output Delivery - Provide unified HTML file that works in both editing and presentation contexts - Include clear instructions for toggling modes and generating final version - Ensure mobile-responsive design ## File Structure ``` flyai-travelmapify/ ├── SKILL.md ├── INSTALL.md # Installation and setup guide ├── flyai-travelmapify.py # **PORTABLE ENTRY POINT**: Main executable script ├── scripts/ │ ├── config.py # **DYNAMIC CONFIGURATION**: Path and environment detection │ ├── main_travel_mapify_enhanced.py # **PRODUCTION MAIN**: Auto-starts servers + text input + unique ID isolation │ ├── geocode_locations.py # Amap geocoding integration │ ├── generate_from_optimized_template.py # Optimized template with unique map ID isolation │ └── hotel-search-server.py # FlyAI hotel search backend server **Note**: Image processing is handled externally using the agent's AI Vision capability. The extracted POI names are passed as text input to this skill. ├── references/ │ ├── amap_api_guide.md # Amap API usage patterns │ ├── poi_validation_rules.md # POI validation and filtering rules │ └── troubleshooting-guide.md # Common issues and solutions └── assets/ └── templates/ └── main-generic-template-with-unique-id.html # **PRODUCTION TEMPLATE**: Unique ID isolation + all features ``` **Main Template**: The skill now uses the **optimized travel_mapify system** with unique map ID isolation as the primary approach, which includes: - **Optimized Template Generation**: Streamlined HTML generation with minimal dependencies - **Unique Map ID Generation**: Automatically creates a hash-based ID from POI names (e.g., `travelMap_abc123`) to isolate localStorage data - **No Cross-Map Data Contamination**: Each travel map saves/retrieves data independently using its unique ID - **Persistent Per-Map State**: Hotel searches, date selections, and POI reordering are saved separately for each map - **Enhanced Performance**: Reduced template complexity and faster map loading - Real FlyAI hotel search integration - Professional notification system (no alert popups) - Loading states with timeout handling - Enhanced UX with smart defaults **Automatic Server Management**: The enhanced main script automatically starts both HTTP server (port 9000) and hotel search server (port 8770) when generating maps, ensuring all functionality is ready immediately. ## Usage Examples ### Portable Execution ```bash # From skill directory (recommended) python3 flyai-travelmapify.py --locations "上海外滩,迪士尼乐园,豫园" --output-html shanghai-trip.html # From any directory python3 /path/to/flyai-travelmapify/flyai-travelmapify.py --locations "北京故宫,天坛,颐和园" --output-html beijing-trip.html # AI Vision Image Processing Workflow: # 1. Use agent's AI Vision to analyze travel image and extract POI names # 2. Pass extracted names as text input to the skill # Example: locations="解放碑,山城步道,十八梯,白象居,湖广会馆,来福士,洪崖洞,千厮门大桥" # With custom ports python3 flyai-travelmapify.py --locations "Tokyo Tower,Shibuya Crossing" --output-html tokyo-trip.html --http-port 8080 --hotel-port 9000 ``` ### Image Input - AI Vision Enhanced User: "Here's my travel plan screenshot, can you make it interactive?" → Skill analyzes image using AI Vision model → If needed, requests clarification: "What city is this for?" or "How many attractions are marked?" → Extracts attractions with preserved sequence and generates interactive map ### Image Input - Manual Clarification User provides image → Skill detects uncertainty → Requests city context → User responds "重庆" → Skill processes with enhanced accuracy ### Image Input - Direct POI Entry When AI Vision cannot confidently identify attractions, skill prompts: "Please provide attraction names in order, separated by commas" ### Image Input - Advanced Usage User: "I have a photo of our Beijing itinerary, please create a shareable map" → Skill processes image, validates locations, creates optimized route with professional styling ### Text Input - Direct Locations with Auto City Detection User: "北京军事博物馆,北京科技大学" → Skill auto-detects city="北京" from location names → Parses locations directly, geocodes them, and generates interactive map ### Text Input - Default City Fallback User: "外滩,迪士尼乐园,豫园" → Skill cannot detect city from generic names → Uses default city="上海" for geocoding → Generates interactive map ### Text Input - Simple List User: "Create a travel map for: Tokyo Tower, Shibuya Crossing, Meiji Shrine" → Skill extracts location names, geocodes them, creates optimized route ### Hotel Search Integration User: Clicks "搜酒店" button in generated map → Real FlyAI hotel search returns actual hotel data with prices and booking links → No mock data - uses real-time Fliggy MCP integration → Professional UX with loading states and notifications (no alert popups) → Default dates: today for check-in, tomorrow for check-out (1-night stay) ### Customization Request User: "Can you adjust the route order and add missing locations?" → Skill provides editable interface with search functionality and reordering tools ## Technical Requirements - **Python 3.7+**: Required for all scripts (uses standard library only) - **FlyAI CLI**: Must be installed globally (`npm install -g @openclaw/flyai`) - **Amap API**: Uses built-in default API key (no user key required) - **Local Proxy**: Built-in proxy server handles Amap API requests (default port 8769) - **Web Browser**: Modern browser with JavaScript support for interactive features ## Required Skills This skill depends on the following OpenClaw skills: - **[amap-maps](https://github.com/openclaw/openclaw/tree/main/skills/amap-maps)**: Provides Amap LBS services for geocoding, POI search, and location services Both skills must be installed in your OpenClaw workspace under the `skills/` directory: ``` ~/.openclaw/workspace/ ├── skills/ │ ├── flyai-travelmapify/ │ └── amap-maps/ ``` ## Portable Design ✅ **No hardcoded paths** - Automatically detects OpenClaw workspace and FlyAI installation ✅ **Cross-platform** - Works on Windows, macOS, and Linux ✅ **Self-contained** - All scripts and templates included in skill directory ✅ **Environment-aware** - Adapts to different system configurations ✅ **Fallback mechanisms** - Multiple detection methods for required components ## Output Files The skill generates HTML files using the **optimized travel_mapify system with unique map ID isolation** as the main template: **`[location]-travel-map-optimized.html`** - Dual-mode interface with all professional enhancements: - **Real FlyAI Hotel Search Integration**: - Actual hotel data with prices and booking links - Loading states with "搜索中..." button text - 5-second timeout with auto-re-enable - No mock data - uses real Fliggy MCP integration - **Professional UX Improvements**: - Notification system instead of alert popups - Auto-hiding messages after 3 seconds - Smart date defaults (today check-in, tomorrow check-out) - **Edit Mode (📝)**: Full-featured editing interface with: - Left-panel POI management - Search functionality for adding new locations - Drag-and-drop and arrow button reordering - Real-time map preview - **View Mode (👁️)**: Clean presentation version with: - Optimized route display - Numbered POI markers with directional arrows - Professional styling ready for sharing - **Generate Final**: Download button to create a clean version without edit controls Files are self-contained and work in any modern web browser when served via HTTP server. ## Error Handling - **Poor Image Quality**: Request higher quality image or manual POI entry - **Ambiguous Locations**: Present options for user selection - **API Rate Limits**: Implement retry logic with exponential backoff - **Missing Coordinates**: Fall back to approximate coordinates with user verification - **HTML Display Issues**: Use local HTTP server instead of file:// protocol - **Map Loading Failures**: Check AMap API key restrictions and network connectivity - **localStorage Corruption**: Implement fallback data and validation logic ## Enhanced UX Features **Professional User Interface:** - **No alert popups**: All messages displayed in non-intrusive notification area - **Loading states**: Hotel search button shows "搜索中..." during API calls - **Timeout handling**: 5-second timeout automatically re-enables search button - **Auto-hiding notifications**: Messages disappear after 3 seconds - **Visual feedback**: Error messages in red, success messages in green **Smart Defaults:** - **Date selection**: Today for check-in, tomorrow for check-out (1-night stay) - **Hotel sorting**: Results sorted by distance from destination - **Top results**: Shows top 5 closest hotels for better user experience ## Best Practices - Always verify extracted POIs with the user before finalizing - Provide clear instructions for customizing the generated maps - Optimize for mobile viewing with responsive design - Include north indicator and scale reference for professional appearance - **Always test via HTTP server**: Never rely on file:// protocol for web applications - **Implement robust error handling**: Wrap API calls and provide user feedback - **Validate all inputs**: Sanitize data before processing - **Document dependencies**: Clearly specify API keys, network, and browser requirements - **Use optimized travel_mapify with unique map ID isolation**: All travel maps now automatically generate unique IDs based on POI names to prevent localStorage conflicts between different maps - **Leverage enhanced performance**: The optimized system provides faster map generation and loading


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector:  ()