---
## 这是什么
一套「出行路书」工作流：你说"想出去玩"，它按固定流程采集需求 → 联网实查 → 产出**路书**（md 事实源 + 单文件 HTML 双版本：本地完整版断网可开 + 瘦身在线版一键部署）+ **美食情报卡**（按城市持续追加的数据资产）。
> [!TIP]
> **SKILL.md 的版本史是精华**——每条规矩背后都是一次真实翻车（图注落位对 ≠ 图内容对、数指标不算对比、价钱是挂牌价不是实付价……），建议通读，比规矩本身更值钱。
## 你能得到什么
- 📄 **单文件路书**：本地完整版断网可开，手机、电脑、打印纸都好看
- 🌐 **一键部署在线版**（需自有服务器，可选）：瘦身网页版一键部署，点开链接即看
- 🔍 **信息可信**：关键信息联网实查带来源，出发前按当日预报终判
- 🖼 **每天有实拍图**：真实景点照片 + 手绘行程导览图，不堆网图
- 🍜 **吃饭有章法**：推荐店各归各位，照抄照选两相宜
- 🚫 **隐私干净**：对外内容零敏感残留
- 🍱 **美食情报卡**：按城市持续追加的数据资产，越用越厚
- ✅ **交付可验收**：内置 `tools/checklist.py` 机械检查清单（随版本演进，以工具输出为准），AI 交稿前必跑——你也能一键验收 AI 有没有偷懒。注意：机械检查通过 ≠ 关键事实（交通/票务/价格）已核验，出行前请按路书内的核实状态标注复核
## 一份路书里有什么
| 板块 | 内容 |
|------|------|
| 总览 | 一句话行程 + 天气 + 出发前倒计时（勾选式）+ 装备清单 + 总览导览图 |
| 路程 | 交通方式怎么选 + 路程总表（里程/时长）+ 支付提示 |
| 每日行程 | 半小时级时段卡 + 实拍图 + 当日导览图 + 交通/机位/雨天方案 |
| 门票预约 | 多档价格 + 预约与放票口径 |
| 温馨提示 | 真实场景 + 应对，不写正确的废话 |
| 住宿 | 选点逻辑 + 退房时间 + 订房三问 |
| 预算 | 三档概览 + 逐项明细 + 隐藏成本 |
| 应急 | 全局兜底 + 紧急电话与领事保护 |
| 美食清单 | 按天按顿给店 + 必点 + 人均 |
| 特产 | 带什么 + 在哪买 |
## 换个目的地，形态自动适配
海岛型目的地的路程板块——租车 / 公交 / 打车分层给方案，行程要素按目的地自动换挡
## 出境路书，同一套标准（v1.14 出境能力包）
埃及 7 天文化线·出境四件样张：热门未排目的地的取舍说明 / 出入境与支付分层 / 双币种预算（含税实付口径）/ 应急领保——行程与个人信息已脱敏，完整条款见 SKILL.md「出境册附加条款」
## 触发词
安装后，跟 AI 说这些话会自动触发本 Skill：
> 去哪玩 / 旅行攻略 / 周末去哪 / 做攻略 / 行程规划 / 自驾方案 / 当日行程 / 今天去哪 / 特产推荐
## 安装（2 分钟）
> 🐣 **完全没接触过 Claude Code？** 直接看 **[零基础跑通指南 TUTORIAL.md](TUTORIAL.md)**——从装 AI 助手到拿到第一份路书，每一步带自检。
解压后你会得到一个 `jianhao-travel-planner` 文件夹（别改名），把它整个放进 skills 目录：
- **全局**（推荐）：`~/.claude/skills/`（Windows 即 `C:\Users\<用户名>\.claude\skills\`）
- **单项目**：`<项目>\.claude\skills\`
- **可选：启用 pre-push 白名单闸门**（防止白名单外文件被误推上仓）：在仓目录执行 `git config core.hooksPath tools/githooks`——之后任何 push 前自动核对文件清单，白名单外会被硬拦截。
装好后的路径应该是 `…/skills/jianhao-travel-planner/SKILL.md`。放对之后，跟 AI 说"周末想去 XX 玩"就会被自动触发。
### 不用 Claude Code？任意 AI 助手都能用
这个技能包本质是**一个文件夹 + 一份工作流文档**，不绑定任何特定 AI。其他 AI 助手（任何能读文件、能联网的 Agent 环境）通用安装法：
1. 把 `jianhao-travel-planner` 文件夹原样放进 AI 的工作区（或直接把文件夹拖给它）
2. 对 AI 说：
> 「这是一个旅行规划技能包。**先完整阅读 SKILL.md 全文再动手**，**禁止把它改写成摘要或精简入口文件**——工作流全文就是执行正文。然后按阶段 0 先向我提问（出发地/日期/人数与关系），确认需求后再开始。」
3. `assets/`（基准骨架）和 `tools/`（检查脚本）保持原目录结构，AI 制作路书时会用到
> ⚠️ **为什么不许摘要改写**：实测有 AI 环境把 93KB 工作流正文塞进附录、自写了个摘要入口——阶段 0 提问条款、交付自查清单全被埋掉，做出的路书出发地默认错误、零提问直接开工。全文在，条款才在。
> 💡 **如果 AI 没问你就开始做路书**，把这句发给它：「按 SKILL.md 阶段 0 先向我提问（出发地/日期/人数与关系），确认后动工——你的开工前置闸漏执行了。」
> 📝 **需求一次说全**体验最好：出发地 + 日期窗口 + 几个人什么关系 + 有无特殊成员。说"我要去山东玩 5 天"它也会追问，但一次说全省一轮。
目录结构（缺一不可）：
```
jianhao-travel-planner/
├── SKILL.md ← 工作流正本
├── assets/ ← 路书+情报卡两份 HTML 基准骨架
└── tools/ ← consistency.py（骨架校验）+ desource.py（脱敏）
```
> ⚠️ **已有同名包？** 如果 skills 目录里已存在 `jianhao-travel-planner` 文件夹，本包拷入会覆盖它（作者的自用版叫 `travel-planner`，不同名、不受影响）。
## 配图（图源与 API key 可选，成品每日配图是硬要求）
路书要求"每天都有图"——**不配图过不了交付自查清单第⑱项**；但**配图渠道完全可选**，任选其一即可满足：
1. **Wikimedia Commons**（默认图源，免费免 key）：按「地标名」精准检索实拍照片，挑近期真实照片用；若在你的网络环境不可达，skill 自动改用下一级图源，不影响出图
2. **Pexels**（免费可商用，需注册 API key）：key 存本机 `.env`（`PEXELS_API_KEY=你的key`）或环境变量，适合氛围空镜——**key 只是图源之一的选择项，没有它走默认图源即可**
3. **AI 生图**：用自己的生图工具产「（示意）」图——页脚注明「AI 生成示意」即可
非实拍图标注「（示意）」、页脚写明来源即可。
## 稳定版下载
不想折腾安装？[Releases 页](https://github.com/awangwang123/jianhao-travel-planner/releases)提供打包好的稳定版 zip（含技能规范与全部工具）；主分支为最新开发态，两者可能不同步——**使用以 Releases 为准**。
## 工具模式（不装 skill，直接用生成工具链）
v1.17 起随包提供完整生成工具链——不想让 AI 走整套技能流程的话，也可以按 `schema.md` 填写 `trip_data.json`（可交给任意 AI 按 schema 代填）。**推荐用随包统一入口一条链跑完**（数据校验 → 生成 → 导览图注入 → 最终成品检查，自动按序执行并计时）；带 `--visual` 连视觉验收（桌面/手机双视口 + 图渲染逐张确认）一起跑：
```bash
py tools/pipeline.py full fixtures/demo/demo_full.json 我的示范册.html --visual
```
也可分步执行（**顺序重要——导览图注入后必须再做最终成品检查**）：
```bash
py tools/validate_trip_data.py 你的trip_data.json # ① 数据闸（V01-V22：引用/枚举/日期对齐/费用三态/时刻单源等）
py tools/gen_roadbook.py 你的trip_data.json 路书.html # ② 生成（骨架指纹校验，天数自适应）
py tools/apply_routes.py 你的trip_data.json 路书.html # ③ 导览图注入（有 routes 时执行；无 routes 自动跳过）
py tools/checklist.py 路书.html --visual # ④ 最终成品检查（注入后的最终页面，FAIL 清零才交付）
```
### 样本分工（三类，别混用）
| 样本 | 用途 | 成品检查预期 |
|---|---|---|
| `fixtures/demo/demo_full.json` | **完整示范：第一次跑通用它**——虚构 3 天册，含导览图、7 张虚构示意配图与全部板块 | 四步（含 `--visual`）跑完 **FAIL 0**，7/7 配图真渲染 |
| `fixtures/synth/book3/8/10.json` | 最小合成样本：**只用于测试链路**（内容空壳/配图不足属预期） | 内容类 FAIL 属预期，非上手示范 |
| `fixtures/good_full.json` | 校验演示：演示数据规则（不可渲染生成） | 仅数据闸 |
| `fixtures/synth_abroad_sample.json` | 出境格式样本（跨日红眼/时区/双币种） | 配合 test_abroad 使用 |
- 回归测试（合成数据，不含真实目的地信息）：`py tools/test_synth_regression.py`；出境格式：`py tools/test_abroad.py`
- 出境样本：`fixtures/synth_abroad_sample.json`（跨日红眼/时区/双币种）
- 依赖：仅 Python 3.8+ 标准库；`checklist.py --visual` 的视觉检查可选装 Playwright（缺失自动 SKIP 声明）
## 第一次使用前
打开 `SKILL.md` 末尾的「用户档案（填空模板）」，复制填写你自己的偏好（出发地/口味/作息/同行者常态），填完这套 skill 就"认识"你了。信源名单不用预置——它会用大众点评+高德+小红书交叉验证，你在旅途中刷到靠谱探店内容可以补进自己的名单。
## 不需要的东西
- 任何平台登录态（抖音/小红书/B站都不需要）
- 付费 API
- 博主白名单（原个人设定已移除）
## 看完整成品
展开看武汉 5 天 4 晚完整路书（长图，约 2MB）
## 上线反响
开源次日的抖音介绍视频：12.6 万播放 · 2889 收藏（数据截至 2026-09-30）
## 版本
- **v1.18**（2026-10-26）：修复完整示范样本配图——七张 1×1 占位图替换为标注「虚构示意 · 非真实景点」的示意插画；页尾图源/动线声明改中性缺省（不再自动声称 Pexels/OSRM，数据侧可如实覆盖）；导览图出界检查兼容程序化导览图并三态收紧（查出越界=FAIL、未能完成检查=FAIL 阻断、无图=SKIP 单列）；工具模式统一入口显式带 `--visual`；发布打包防缺件防裹挟
- **v1.17**（2026-10-24）：**工具链公开化**——生成器/数据校验器/导览图程序化/事实派生等八件工具与 schema/骨架/合成样本随包发布，新增「工具模式」四步机械全链；教程与 README 承诺修正（耗时/助手能力/检查边界/配图边界）
- **v1.16**（2026-10-24）：修复部分页面无法识别行程时段的问题；未读取到时段时明确报错不漏检；减少餐段重复识别误报；作息默认节奏条文化（默认 09:30—10:00 开始游玩，不写起床细节）。**稳定版下载走 [Releases 页](https://github.com/awangwang123/jianhao-travel-planner/releases)（v1.16 起 zip 随 Release 发布）；主分支为最新开发态，两者可能不同步，以 Releases 为准**
- **v1.15**（2026-10-21）：问题反馈模板适配双路线——报错单不再绑定 Claude Code，任意 AI 助手用户可顺填报错，新增「你用的 AI 助手」排查字段
- **v1.14**（2026-10-19）：**出境能力包正式收录**——实查通路三层级/签证体检卡/出入境双清单/双币种+含税实付/sos 领保块/装备卡/热门未排取舍说明（新节「出境册附加条款」）；checklist.py 同步 v1.9（24 项机械闸+修复指引+出界断言）；新工具 basemap_tool.py（真底图工具链）+prep_fetch.py（日照/汇率/坐标预抓）；新节「提速·导览图·验收增补」——提速五条/导览图六条+总览比例家族基准/验收规范一页纸/三档位/价格复用边界
- **v1.13**（2026-10-15）：开工前置闸——SKILL.md 速查卡+阶段 0 新增「出发地/日期窗/人数与关系禁默认+需求确认单」条款（根治他环境"零提问默认北京出发"实测事故）；禁止 AI 摘要改写 SKILL.md（93KB 正文被改造成附录的实测教训）；导览图双通路定序——手绘 SVG=无网无 key 兜底正路硬执行；README 新增「任意 AI 助手通用安装法」+ 用户纠偏咒语 + 需求说全提示
- **v1.12**（2026-10-14）：美食清单按天分组式定稿（禁顿列大表）+密度硬标准四条；铁律 8 补航班聚合口径实证案例；跨板块归位黑名单
- **v1.11**（2026-10-13）：SKILL.md 瘦身——版本演进翻车实录 42 条迁 HISTORY.md（一条不删），AI 触发加载体积减 35%，条款埋深漏读风险下降
- **v1.10**（2026-10-13）：tools/checklist.py 同步至 v1.6——「形态检查组」八项（eyebrow 白名单/冷知识卡逐日/机位三条全覆盖/参数速查卡/导航格式/美食备选列/示意双写/工具条占位）+存储键双形态抓取+图渲染滚到页底二次确认
- **v1.9**（2026-10-10）：移动端表格排版根治（fixed+colgroup，桌面零变化）+大交通实时实查铁律+导航当日标记废止+日落时刻 API 实查+订房机位距离顺位
- **v1.8**（2026-10-09）：新增游客优惠检查（票根经济/文旅消费券，知会型呈现）
- **v1.7**（2026-10-08）：每日卡标准件——今日速览三件事式开头、冷知识卡与 Plan B 转固定件；机位改顺路提示（位置+时段+拍法）；提示与避雷两组兼备；导览图插画化基线（多色动线）；住宿选房顺位；R2 店收录门槛
- **v1.6**（2026-10-07）：checklist.py 四项扩容——图渲染懒加载、当日徽章在位、存储键防跨成品污染、填稿指引残留拦截
- **v1.5**（2026-10-05）：新增 tools/checklist.py 机械检查+头部执行速查卡
- **v1.4**（2026-10-03）：价格纪律五条——餐饮人均口径/路程时长写线路名/估算不豁免实查/价格多处同步/收录差集核查
- **v1.3**（2026-09-30）：内容深度定标——六板块必答清单/价格含税总价制/图源三级链/总览八件
- **v1.2**（2026-09-29）：导航体验升级——侧栏滚动按序高亮、点击锁定、当日自动定位
- **v1.1**（2026-09-26）：修正打包结构与安装说明
- **v1.0**（2026-09-23）：开源首发
## 反馈与共创
- 🐛 **报错/用不了**：[Issues](https://github.com/awangwang123/jianhao-travel-planner/issues) 发帖（有模板）
- 📍 **许愿城市**：[旅行许愿池](https://github.com/awangwang123/jianhao-travel-planner/discussions/1)——点赞最高的城市，下一份官方示例就是它（附完整生成过程记录）
- 💬 其他想法：[Discussions](https://github.com/awangwang123/jianhao-travel-planner/discussions) 随便聊
开源技能包，需配合 AI 助手使用 · 统一模板 · 事实核查流程 · 机械检查工具 · MIT