Skill: f2quantum/sea-route (version 1.0.0)

--- name: sea-route description: "Sea route navigation: generate the shortest maritime route between two ports or coordinates, output navigation waypoints and an interactive HTML map. Use when the user mentions sea route, shipping route, maritime navigation, port-to-port distance, 海运航线, 航线规划, 海上路线, 港口距离, 船运路线." version: 1.0.0 tags: - navigation - maritime - visualization - map --- # Sea Route Navigation Skill Generate the shortest sea route between two points on the globe. Returns navigation waypoints (coordinates) and an interactive HTML map visualization. ## When to Use - User asks for a sea/shipping/maritime route between two locations - User wants port-to-port distance or travel time estimate - User needs navigation waypoints for maritime routing - User wants a visual map of a shipping lane ## How It Works This skill uses a Python script (`scripts/sea_route.py`) powered by the `searoute` library. It computes the shortest path over ocean, avoids land masses, and outputs: 1. **Waypoint coordinates** (longitude, latitude) printed to stdout as JSON 2. **An interactive HTML map** saved to a user-specified path (default: `./sea_route_map.html`) The script uses `uv` for dependency management — no manual `pip install` needed. ## Usage ### Step 1 — Resolve user input to coordinates The user may provide: - **City / port names** (e.g., "天津" and "大阪", "Rotterdam" and "Singapore") - **Coordinates** directly (e.g., `[117.75, 38.99]`) If the user provides city or port names, you MUST convert them to `[longitude, latitude]` coordinates yourself before calling the script. Use well-known port coordinates: | Port | Longitude | Latitude | |------|-----------|----------| | 天津港 (Tianjin) | 117.75 | 38.99 | | 上海港 (Shanghai) | 121.47 | 31.23 | | 大阪港 (Osaka) | 135.25 | 34.65 | | 深圳港 (Shenzhen) | 114.27 | 22.55 | | 香港 (Hong Kong) | 114.17 | 22.28 | | 新加坡 (Singapore) | 103.85 | 1.29 | | 鹿特丹 (Rotterdam) | 4.50 | 51.90 | | 汉堡 (Hamburg) | 9.97 | 53.53 | | 洛杉矶 (Los Angeles) | -118.27 | 33.73 | | 纽约 (New York) | -74.04 | 40.67 | | 迪拜 (Dubai) | 55.27 | 25.27 | | 悉尼 (Sydney) | 151.21 | -33.87 | | 釜山 (Busan) | 129.04 | 35.10 | | 东京 (Tokyo) | 139.77 | 35.45 | | 高雄 (Kaohsiung) | 120.29 | 22.61 | For ports not listed above, look up reasonable coordinates for the port area. ### Step 2 — Run the script Run with `uv`: ```bash uv run --script /path/to/skills/sea-route/scripts/sea_route.py \ --origin-lon <LON> --origin-lat <LAT> \ --dest-lon <LON> --dest-lat <LAT> \ --origin-name "Port A" --dest-name "Port B" \ --output ./sea_route_map.html ``` **Parameters:** | Flag | Required | Description | |------|----------|-------------| | `--origin-lon` | Yes | Origin longitude | | `--origin-lat` | Yes | Origin latitude | | `--dest-lon` | Yes | Destination longitude | | `--dest-lat` | Yes | Destination latitude | | `--origin-name` | No | Display name for origin (default: "Origin") | | `--dest-name` | No | Display name for destination (default: "Destination") | | `--output` | No | Output HTML file path (default: `./sea_route_map.html`) | ### Step 3 — Present results to user The script prints a JSON object to stdout with this structure: ```json { "origin": {"name": "Tianjin", "lon": 117.75, "lat": 38.99}, "destination": {"name": "Osaka", "lon": 135.25, "lat": 34.65}, "distance_km": 1891, "duration_hours": 42.5, "waypoints": [ {"seq": 1, "lon": 118.1725, "lat": 38.7726}, ... ], "html_map": "./sea_route_map.html" } ``` Present to the user: 1. A summary: origin → destination, distance, estimated time 2. The waypoint coordinate table 3. Tell them the HTML map file path and offer to open it ### Step 4 — Open the map (optional) If the user wants to see the map: ```bash open ./sea_route_map.html # macOS xdg-open ./sea_route_map.html # Linux ``` ## Example Interaction **User:** 帮我生成从天津到大阪的海运航线 **Agent:** 1. Resolve: 天津港 → [117.75, 38.99], 大阪港 → [135.25, 34.65] 2. Run: ```bash uv run --script ~/.agents/skills/sea-route/scripts/sea_route.py \ --origin-lon 117.75 --origin-lat 38.99 \ --dest-lon 135.25 --dest-lat 34.65 \ --origin-name "天津港" --dest-name "大阪港" \ --output ./tianjin_osaka_route.html ``` 3. Parse JSON output, present waypoints and summary 4. Open the HTML map ## Notes - The `searoute` library generates approximate maritime routes suitable for visualization and distance estimation. It is NOT intended for real navigation. - Coordinates use `[longitude, latitude]` order (GeoJSON convention). - The script requires `uv` to be installed. It uses inline script dependencies — no virtual environment setup needed. - Estimated speed is ~25 knots (typical cargo vessel cruising speed).


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