travel-plan-viz

_{👋 我是 Migo · 你的旅行领航员 —— 候鸟天生会规划路线、掐准时间}

🗺️ Migo · 旅行领航

_{travel-plan-viz}

把一趟旅行变成一个美观、离线可读、手机优先的单文件 HTML 页面

交互地图 · 每日时间轴 · 出发前订票提醒 · 行前须知 · 待选航班 · 片区价位酒店

一个 Claude Code / Codex 通用 Skill（也可适配其他 Agent）

_{🎬 更多 AI 工具实战玩法：作者抖音 @泽轩604（app 内搜索即达 · 本项目的抖音原帖）}

_{✨ 特点 · 🧑‍💻 零基础安装 · 🚀 安装 · ❓ FAQ · 🏗️ 原理 · ⭐ Star}

_{中文 · English}

_{趋势图由本仓库 GitHub Action 基于 GitHub 星标数据每日自动重绘,非实时;实时 Star 数请看页面顶部。
Chart is redrawn daily by this repo's GitHub Action from GitHub stargazer data (not real-time) — see the count at the top of the page for the live number.}

travel-plan-viz 是一个 Claude Code / Codex 通用 Skill（也可适配其他 Agent）。你只要说一句"帮我做香港 4 天 3 晚的旅行计划"，它就会联网调研、排好行程、生成一个精美的单文件 HTML 网页——手机上随时打开，文字行程离线可读，整页可截图存相册。

灵感来自社区的 "vibe coding 旅游攻略" 玩法，升级为一个正式、可复用、把易错逻辑固化下来的 Skill。

混合架构——易错的机械逻辑固化为可复用引擎，视觉表现每次交给"设计步骤"重新生成：

• assets/map.js：Leaflet 地图引擎（编号标记、路线、iOS/Android 导航链接、GCJ-02→WGS-84 坐标纠偏）
• assets/reminders.js：提醒引擎（截止日期计算、清单/徽标渲染）
• assets/validate.js：契约校验引擎（生成后机械检查字段/坐标/必需区块，ERROR 必须修复）
• assets/page-contract.md：内容契约，告诉设计步骤每个区块要哪些数据
• references/research-guide.md：联网调研指南（坐标/图片/营业时间/天气/交通…，含图片必须校验可加载、票价不查实时）
• references/design-guidelines.md：内置美学准则（无外部设计 skill 时的兜底）

设计步骤可插拔、无硬依赖：如果你装了 frontend-design 或 huashu-design（花叔Design）这类设计 skill，会自动调用、效果更佳；都没装也能用内置美学准则出一份像样的页面。所以本 skill 可独立安装，不强制先装别的。

第三方旅行 skill 可选适配（同样是软依赖）：如果你另装了飞猪、高德、腾讯地图、滴滴等官方旅行 skill，本 skill 会调用它们补充实时数据（航班 / 酒店 / 路线规划 / 天气 / 精确坐标），并在页面附上「去预订 / 导航 / 叫车」链接；没装则照常走联网调研，页面不缺任何区块。这些数据的实时性与真实性由对应官方 skill 负责，本 skill 只做适配与呈现、不做背书。

🧑‍💻 我完全不懂代码怎么装？ 有一份从「什么是 GitHub、怎么下载」讲到「装完对 AI 说哪句话」的保姆级教程，Windows / Mac 每一步都有：👉 零基础安装指南 INSTALL.md。下面的一行命令是给熟悉终端的用户的快捷方式。

把 skill 链接到对应 Agent 的 skills 目录：

# Claude Code
ln -sfn "$(pwd)/travel-plan-viz" ~/.claude/skills/travel-plan-viz
# OpenAI Codex
ln -sfn "$(pwd)/travel-plan-viz" ~/.codex/skills/travel-plan-viz

用其他 Agent？ 本 skill 平台无关——核心是一份指令 + 三个纯 JS 引擎。没有 skills 机制的 Agent，把 travel-plan-viz/SKILL.md 当作指令喂给它即可。完整适配方法与「通用适配提示词」见 travel-plan-viz/references/porting-to-other-agents.md。

在 Claude Code / Codex 里直接说：

帮我做香港 4 天 3 晚的旅行计划          # 模式 A：从零规划

这是我的行程<贴上文字/HTML>，帮我做成网页   # 模式 B：已有计划

生成后，把 HTML 文件丢回给 Claude 还能继续改，例如："第三天太赶，把 X 挪到第四天"——页面内嵌了完整行程 JSON，改的是数据、重渲染呈现，不会丢字段。

samples/ 目录下有现成产物，浏览器直接打开：

• chengdu-4d3n-real.html —— 成都 4 天 3 晚（模式 A：只给目的地+天数，从零规划，含都江堰/青城山一日 + 二选一方案）
• hongkong-4d3n-real.html —— 香港 4 天 3 晚（真实联网数据）
• shenzhen-3d2n-real.html —— 深圳 3 天 2 晚（只给天数，从零生成）
• tokyo-5d4n-real.html —— 东京 5 天 4 晚（模式 B：粗略计划 + Agent 建议后生成）

Q：这和直接问豆包 / 千问 / ChatGPT「帮我写个攻略」有什么区别？

直接问大模型，得到的是一段文字或一次性的页面。这个 skill 把容易出错的环节固化成了可复用的工程流程：

• 行程体检：丢现成计划进来，它会对照「完善行程」清单提几条可选优化建议（克制、不硬来），不只是转个格式；
• 单文件离线可读：一个 .html 存进手机，没网也能看文字行程；
• 点导航：地图上每个景点一键跳手机导航（iOS 走 Apple Maps，Android 走 geo: 深链，境内点位另附高德地图、境外另附 Google 地图免 key 链接）；
• 订票倒推提醒：按出发日期倒推「几号前该订什么」，页顶自动生成待办清单；
• 机械校验 + 可持续迭代：生成后自动校验坐标 / 字段 / 必需区块，行程数据以 JSON 内嵌页面——之后说一句「把第三天的 X 挪到第四天」就能改，不丢字段。

Q：AI 攻略是不是伪需求？信息还得自己核实。

一半同意。价格、营业时间、班次这类时效信息，确实必须以官方渠道为准——所以页面自带全覆盖免责声明，并引导到官方 App 核实，这一点不装。这个 skill 的价值不在「替你核实、替你预订」，而在整理与提醒：把散落的信息排成能直接照着走的行程页，把「几号前订什么」替你倒推出来。核实那一步，诚实地留给你。

Q：能做外国城市吗？

能。samples/ 里的东京 5 天 4 晚就是现成例子。地图用 OpenStreetMap 全球瓦片，海外坐标本身就是 WGS-84 标准、无需纠偏；只有来自高德 / 腾讯的国内坐标才需要 GCJ-02 纠偏（skill 会自动处理）。

travel-plan-viz/
  SKILL.md              # 工作流编排：判断模式 → 调研 → 生成
  assets/
    map.js              # Leaflet 地图引擎：标记/路线/导航链接/坐标纠偏（已单测）
    reminders.js        # 提醒引擎（已单测）
    validate.js         # 契约校验引擎：生成后机械检查（已单测，含 CLI）
    page-contract.md    # 给设计步骤的内容契约
  references/
    research-guide.md   # 联网调研指南
    design-guidelines.md # 内置美学准则（无外部设计 skill 时兜底）
    porting-to-other-agents.md # 跨 Agent 适配指南 + 通用提示词
samples/                # 生成的示例页面
test/                   # 引擎单元测试（node --test）
docs/superpowers/       # 设计文档与实现计划

node --test test/*.test.js

页面中所有信息（天气、航班、酒店、餐厅、门票、价格、营业时间、评分、活动等）均为 AI 基于公开资料整理的参考建议，可能不准确或已过时，请务必在官方渠道核实后再预订或前往。

MIT —— 随意使用、修改、商用，保留版权声明即可。欢迎 issue / PR。

travel-plan-viz is a Claude Code / Codex Skill (and portable to other agents). Just say "plan me a 4-day Hong Kong trip" and it will research online, build the itinerary, and generate a polished single-file HTML page — mobile-first, text readable offline, screenshot-friendly.

Inspired by the community "vibe-coding travel guide" trick, turned into a proper, reusable Skill that hard-codes the error-prone bits.

A hybrid architecture — error-prone mechanics are baked into reusable engines, while the visual design is regenerated each time by a "design step":

• assets/map.js — Leaflet engine (numbered markers, route, iOS/Android navigation links, GCJ-02→WGS-84 conversion)
• assets/reminders.js — reminder engine (deadline math, checklist/badge rendering)
• assets/validate.js — contract validation engine (mechanical post-generation checks on fields/coordinates/required blocks; errors must be fixed)
• assets/page-contract.md — content contract telling the design step what each block needs
• references/research-guide.md — web-research guide (coords/photos/hours/weather/transport…, images must be verified loadable, no realtime pricing)
• references/design-guidelines.md — built-in aesthetic guidelines (fallback when no external design skill is present)

The design step is pluggable, with no hard dependency: if you have a design skill like frontend-design or huashu-design, it's used automatically for better results; without any, the built-in guidelines still produce a presentable page. So this skill installs standalone — no need to install anything else first.

Optional adaptation to official travel skills (also a soft dependency): if you separately install official travel skills like Fliggy, Amap, Tencent Maps, or DiDi, this skill calls them to enrich realtime data (flights / hotels / route planning / weather / precise coordinates) and adds "book / navigate / hail a ride" links on the page; without them it falls back to web research and no block is missing. The realtime accuracy of that data is owned by those official skills — this skill only adapts and presents it, without endorsement.

New to all this? There's a zero-basics, step-by-step install guide (Windows & Mac, written in Chinese): INSTALL.md.

Link the skill into your agent's skills directory:

# Claude Code
ln -sfn "$(pwd)/travel-plan-viz" ~/.claude/skills/travel-plan-viz
# OpenAI Codex
ln -sfn "$(pwd)/travel-plan-viz" ~/.codex/skills/travel-plan-viz

Using another agent? This skill is platform-agnostic — it's just an instruction file plus three vanilla-JS engines. For agents without a skills mechanism, feed travel-plan-viz/SKILL.md as instructions. Full porting steps and a ready-to-paste adaptation prompt: travel-plan-viz/references/porting-to-other-agents.md.

In Claude Code or Codex, just say:

Plan me a 4-day, 3-night trip to Hong Kong       # Mode A: plan from scratch

Here is my itinerary <paste text/HTML>, make a page   # Mode B: existing plan

After it's generated, hand the HTML back to Claude to keep editing, e.g. "Day 3 is too packed, move X to Day 4." The full trip data is embedded as JSON in the page, so edits change the data and re-render — nothing gets lost.

Ready-made outputs in samples/, open them in a browser:

• chengdu-4d3n-real.html — Chengdu, 4D3N (Mode A: planned from just destination + days; Dujiangyan/Mt. Qingcheng day trip + either-or options)
• hongkong-4d3n-real.html — Hong Kong, 4D3N (real researched data)
• shenzhen-3d2n-real.html — Shenzhen, 3D2N (generated from days only)
• tokyo-5d4n-real.html — Tokyo, 5D4N (Mode B: rough plan + agent suggestions)

Q: How is this different from just asking a chatbot to "write me an itinerary"?

A plain chat gives you a wall of text or a one-off page. This skill bakes the error-prone parts into a reusable pipeline: an itinerary health-check with restrained optional suggestions (Mode B), a single offline-readable HTML file, tap-to-navigate map pins, booking reminders back-calculated from your departure date, mechanical post-generation validation, and embedded JSON data so the page stays editable without losing fields.

Q: "AI travel guides are pointless — you have to verify everything yourself anyway."

Half agreed. Time-sensitive info (prices, opening hours, schedules) must be verified through official channels — which is exactly why every page ships with a full-coverage disclaimer pointing to official apps. The value here is organizing and reminding — laying scattered info out as a usable itinerary page and back-calculating what to book by when — not verifying or booking for you. That last step is honestly left to you.

Q: Does it work for cities outside China?

Yes — the Tokyo 5D4N sample is one. The map uses global OpenStreetMap tiles; overseas coordinates are already WGS-84 and need no conversion (GCJ-02 correction only applies to coordinates coming from Amap/Tencent).

travel-plan-viz/
  SKILL.md              # workflow: detect mode → research → generate
  assets/
    map.js              # Leaflet engine: markers/route/nav links/coord conversion (unit-tested)
    reminders.js        # reminder engine (unit-tested)
    validate.js         # contract validation engine: post-generation checks (unit-tested, has CLI)
    page-contract.md    # content contract for the design step
  references/
    research-guide.md   # web-research guide
    design-guidelines.md # built-in aesthetics (fallback w/o external design skill)
    porting-to-other-agents.md # cross-agent porting guide + adaptation prompt
samples/                # generated example pages
test/                   # engine unit tests (node --test)
docs/superpowers/       # design specs & implementation plans

node --test test/*.test.js

All information on the page (weather, flights, hotels, restaurants, tickets, prices, opening hours, ratings, events, etc.) is AI-compiled from public sources, for reference only — it may be inaccurate or outdated. Always verify on official channels before booking or going.

MIT — use, modify, and ship it freely; just keep the copyright notice. Issues and PRs welcome.