# jianhao-travel-planner

Adopt this skill: https://proskills.md/skills/other/awangwang123-jianhao-travel-planner

Page: https://proskills.md/skills/other/awangwang123-jianhao-travel-planner
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 18788
upstream: https://github.com/awangwang123/jianhao-travel-planner/blob/HEAD/SKILL.md

```text
---
name: jianhao-travel-planner
description: 见好 · 旅行规划器——出行路书工作流（通用版）。当用户提出旅游、出行、周末去哪、做攻略、做路书、目的地推荐、行程规划、自驾方案、当日行程、今天去哪、特产推荐等需求时触发。按「需求采集→目的地筛选→实查复核→六维度路书（吃/玩/住/行/拍+避雷）+随行两件套（当日旅行模式/特产三问）→行程中动态调整→素材采集→复盘回流」全流程执行，输出自包含路书文件。核心铁律：关键信息必须联网实查、未核实必标注、动线不绕路、天气定节奏、内容预埋（机位+钩子）。
---

# 见好 · 旅行规划器（jianhao-travel-planner · 公用版 v1.7）

> **公用版说明（2026-09-21 从作者本体 v3.26 派生；v1.2 于 2026-09-29 升级基准骨架——导航双通道/当日定位；v1.3 于 2026-09-30 正文条款对齐作者本体 v3.49 的国内通用部分（必答清单/价格含税总价制/图源三级链等）；v1.4 于 2026-10-03 增补本体 v3.50 五条价格纪律；v1.5 于 2026-10-05 增补本体 v3.51-52（机械交付闸门 tools/checklist.py+头部执行速查卡）；v1.7 于 2026-10-08 增补本体 v3.55-59 国内通用条款（今日速览标准件/升级体验必答化/冷知识卡与 Plan B 固定件/slot 主次律/机位信息标准/tips 两组兼备/导览图插画化基线/R2 门槛/住宿选房顺位等）+checklist.py v1.2+新增 check_hooks.py；国际/出境版条款测试中，完成后随出境版发布）**
> 本文件是作者自用版 travel-planner 的公用/开源版：方法骨架、产出形态、自查清单与本体一致；按开源前置工序做了 7 项改造——
> ① **抓取链切公开源**：正餐情报走大众点评/高德地图/小红书等公开平台交叉验证，不再依赖博主作品抓取流水线（不需要任何登录态）；
> ② **配套口径三改**：证据分级适配公开源 / 收录门槛 R2 的「穷尽」判定改为「地图 POI+多源交叉穷尽」/ 信源名单由使用者自建（不预置任何博主白名单）；
> ③ **脱敏去个人化**：用户档案改填空模板、作者个人设定降级为参考示例、个人文件路径全部清除；
> ④ **长辈/官方版叠加档完整保留**（四件套+决策替做+温馨提示）；
> ⑤ **配图硬规矩保留** + Pexels 免费 key 自注册指引（2 分钟，见「工具与依赖」）；
> ⑥ **工程工具随包附带**（`tools/consistency.py` 骨架校验 + `tools/desource.py` 脱敏），去 AI 味通道二改可选；
> ⑦ **版本演进记录原样保留**——每条规矩后面的"血案"（翻车实录）是这套标准为什么成立的解释，比规矩本身更值得读。记录中的署名（作者与协作者）是真实迭代存档，正文运行区已不含个人依赖。
> 🏠 **本工作流的维护与更新**：github.com/awangwang123/jianhao-travel-planner —— 反馈、许愿池与新版本发布均在此仓库。
>
> **安装**：整个目录（SKILL.md + assets/ + tools/）复制到 `~/.claude/skills/jianhao-travel-planner/`（全局）或项目 `.claude/skills/jianhao-travel-planner/`（单项目）即可被 Claude Code 自动加载。
> ⚠️ **与自用版的关系**：本文件由作者的自用版本 travel-planner 派生（自用版含作者个人档案、不公开）。公用版技术名 `jianhao-travel-planner` 与自用版不同名，二者可在同一台机器共存、互不覆盖。
> 版本 v3.54（2026-10-07，「工具缺口改」拍板）｜**tools/checklist.py 升 v1.1 四项扩容**（成品终审实证：机械检查全过但四类问题全漏——检查项必须跟上翻车形态）：①**图渲染**（视觉项内**先滚动触发懒加载**再逐张查，报 N/N）②**badge 在位**（每日卡 today-badge 元素逐天查——被「无日期模式」掩盖的潜伏缺陷显性化）③**存储键跨成品污染**（键前缀→城市映射+标题比对，从别的成品抄脚本没改键即拦）④**长【】指引残留**（≥15 字【】=骨架填稿指引未删即拦；【估算】【未核实】等短标注不受影响）。顺修 intel 空壳误报（选装区块不装=正常）。毒抓自测+异版回归零误伤。
> 版本 v3.39（2026-09-30，作者 复核抓汇率错误后的回写）｜**货币条款执行失误实锤+补强**：国际版三册自动双币种换算时沿用了稿内旧汇率（$7.2、100₱≈12.5 元）未实查——实际中间价 USD/CNY **6.7411**（2026-09-29 中国外汇交易中心）、USD/PHP **62.65**（比索年内大幅贬值），偏差 7%/16%。**补强（并入 v3.35 货币条款）**：换算前当日实查汇率、稿内旧口径视为待验证数据；另记自动换算脚本禁用跨行长字符类正则（base64 单行 O(n²) 卡死教训，用按行扫描）。
> 版本 v3.38（2026-09-30，两拍板）｜**①每日配图对称律**——每日张数=**2 或 4，禁 3 张**（.photos 是 2 列网格，3 张=2+1 不对称；国际版三份 作者提案定规），并入自查⑱。**②骨架 JS 位置契约**——head 只放门控块，主逻辑+兜底必须在 `</body>` 前：协作方国际版三份曾把整套 JS 拼进 head 门控位，脚本在 body 生成前运行，`getElementById('fontInc')` 等全空指针，addEventListener 静默报错、滚动高亮/当日模式全灭（页面看着正常极难察觉）。落位=阶段 3 JS 六件事 bullet+自查⑱。📦 协作方待同步。
> 版本 v3.37（2026-09-29，三拍板：A「赞同」/B「同意」/C「同意」）｜**①作者推荐资格制**——author「推荐」区块=**选装件非默认件**：仅当作者对目的地有真实推荐资历（家乡/长期居住/亲历有发言权）才装（武汉=作者家乡✓）；无资历目的地（东京/檀香山/大岛/马尼拉等游客视角稿）一律不装该区块与导航项——推荐板块的信用来自作者真推过，无资格硬写=编造推荐人格（协作方国际版三份无资历硬装且抒情实证；东京版误装待删）。②**信息归位一处**——每个信息只有一个家，跨区块**禁整句复制**：日卡=当时当地行动指令（细节多时改指针「详见提示区/门票表」）、tips=通用防坑、门票表=价格与预约口径、Plan B=事发处置、sos=全局兜底；同一信息 ≥2 个叙事区整句重复即违规，归位=保留最合适一处、其余删或改指针（檀香山防晒 3 处/珍珠港门票 3 处实证）。③**骨架稳定基线（作者：「把这版基准骨架稳定保持下来」）**——`assets/路书_基准骨架.html`（指纹 `9c3c6249a4`+导航双通道 navLock）为**唯一派生源**，2026-09-29 冻结；东京版=基线标杆成品；⚠️两条分发通路（协作方副本/公用版 GitHub v1.1）尚停在无导航修复的旧 JS，派生禁出旧通路。派生首检（自查㉖）增 **navLock 存在性**检查；自查增 ㉘信息归位与作者资格。📦 协作方待同步。
> 版本 v3.36（2026-09-29，🔴**出入境双清单**：两份出入境调研报告供料——中国护照出国签证体系七类+17 坑+来华非签证痛点四层，作者拍板「开工」）｜v3.35 ②条「签证与入境」升级为**出入境双清单**：触发参数化三元组（游客国籍×目的地×过境国——外国人去外国同样触发，作者 提问驱动）、权威源随游客国籍切（通用仲裁源 Timatic/IATA 与航司值机同库）；**出境链五环节**（签证三查/时间轴倒排含电子入境卡独立待办/订单策略先办签后出票/边检海关红线含药品案例/过境落地含分段购票必查过境签）；**来华链四层**（抵达前 72h 强制清单/预约硬门槛/住宿确认/支付宝小程序在地通路）；红线三连+AI 边界+数据纪律（政策迭代极快禁用记忆作答）+输出物四件套（签证体检卡/时序表/避坑清单/出发前 7 天复核）；自查㉗出入境链完整性检查（含 v3.35 双币种粒度口径）。调研正本 `作者留存的调研报告`。📦 协作方待同步。
> 版本 v3.35（2026-09-28，🔴**国际版能力**：东京实战+GitHub 五仓拆解反哺，作者授权任务「优化完善旅游 skill 国外功能」、协作方复核通过）｜**14 条全原创**（思路参考公开仓库拆解报告，合规：CC BY-NC/BSL 仓只借鉴思路不移植文本）：①阶段 0 **国际游客画像三问**（国籍护照/出发地本币/首访复访——禁默认假设，「香港假设」案根治）②阶段 2 **国际版专属实查五条**（签证按国籍实查+使领馆提醒显性呈现/汇率文首声明+全文双币种/cash-heavy 现金依赖标记/插头电压对比「无需转换头」/评论即纠错源近 6 个月）③行维度 **国际交通方法论六条**（机场五变量决策/交通卡四步协议/通票 break-even 禁默认/离境 buffer 三档/无房窗口行李具名「写了没有也是回答」/app 时间陷阱）④**地理集群原则**（同天一个集群不横穿+每日动线图画出验证，朋友现地判集群案固化）⑤避雷表 **国际版人身安全块**（使领馆提醒+紧急电话+电诈场景+夜间区域四件前置——拆解发现全场空白，差异化）⑥自查㉓-㉖（**fail-closed 终审**「未核实=失败/未执行必须声明禁报 0」+命中异常看上下文结构/跨集群折返检查/国际版身份画像 grep/SVG≥天数+1）。配套产物：`作者留存的调研报告`（五仓拆解报告+大陆口径实查+东京路书全档）。📦 协作方待同步。
> 版本 v3.34（2026-09-26，武汉路书全流程实战回写，验收定稿）｜**分发上线工序（新阶段：成稿 ≠ 终点）**：①🔴**双产物**——本地完整版（断网可开）与**瘦身在线版**并行：部署版图统一重压 820px/q72（3.0MB→1.39MB 实证），zip 内 index.html ②部署通路=BTI scripts/deploy.py（.env 凭据+SFTP，paramiko 需在位）③🔴**上线实测三件套**：curl 状态码+体积+耗时+title 抽查，缺一不算上线（实证 200/1.35MB/0.16s）④**发布渠道策略**——抖音站外链接严查：**图片二维码重点严查禁用**、置顶文字地址有折叠风险、兜底=评论区扣关键词+**私信发图包**（私信发图不受限）；微信私发链接顺畅=部署主用途 ⑤**发布物料规格**——图文 3:4（1024×1365）、网名水印右下角半透明、组合=首屏/总览导览图/路线卡/美食清单/实拍 5 张+**私信图包 8 张**（封面/每日长图/美食全表/门票避雷预算三合一）⑥**署名口径**——图上水印=使用者的社交账号名，工具名只作文案卖点不进署名；发布物料由使用者亲自发布，AI 只制作物料⑦构建/部署命令禁静默吞错+产物新构建断言（正本《工作规范》四、D6，本次实证）⑧**升级传播矩阵**（正本《工作规范》四、D8——本次 README 落后 7 版/协作方副本停更即案源）。📦 协作方待同步。
> 版本 v3.33（2026-09-26，作者定稿改称）｜**推荐池术语定稿「博主推荐」**——原「作者推荐」（v3.29⑩/v3.31 口径）全部改称「博主推荐」；实拍图署名口径同步为「博主实拍」；旧称「作者推荐/本地人推荐」在成稿中出现即视为回潮（终审 ⑧ 已改三查：博主推荐≥1、本地人推荐=0、作者推荐=0）。📦 协作方待同步。
> 版本 v3.32（2026-09-26，实战抓出机制缺口「你们都没更新过 MD 素材，重做 HTML 每次都犯错」）｜🔴**修正双写制**——md 事实源与 HTML 成稿是**双产物**：任何成稿修正（内容/店池归属/口径/行程结构）必须**当批回写 md**，只改 HTML=欠账；**重建/重放必须从最新事实源派生**，禁止从旧 HTML/旧快照拼装（武汉 v4 重建丢 15 项修正+md 停在 01:20 十几轮修正零回写实证——旧 md 派生=旧错误必然重演）；交付校验加一道：md 与 HTML 关键决策点一致性 grep（点名店/餐段安排/口径措辞抽 N 条对表）。📦 协作方待同步。
> 版本 v3.31（2026-09-26，作者拍板 B 方案归属定稿，⑩细则化）｜**点名店三池归属**：①**彩蛋池**（只在「作者推荐」彩蛋板块出现，行程与美食清单正文全清）：硒施绿豆皮/鹏辉酒家/熊二烧烤/院子烧烤/胡胖子/粗茶淡饭·蒸鲜/松滋鸡/财大小吃街 ②**场地型豁免**：兼具景点/餐饮场地属性的店（湖滨客舍/30 PARK）可留行程动线，但删「本地朋友推荐/本地人推荐」类措辞，改读者视角描述（「东湖景区里一家店」「湖边下午茶据点」）③**主表**：夏氏砂锅/精粉世家（作者拍板归主表）+执行方自找店凑目标家数（武汉=20 家）；主表≠推荐池，互不混池。📦 协作方待同步。
> 版本 v3.30（2026-09-26，作者批「SVG 垃圾/不调研不学/本地库不用/挑图没概念就搜」后固化）｜**挑图先建概念+SVG 规范硬执行**：①🔴**挑图先建概念**——挑图前先写下该地标的真实外观特征（重建年份/形制/颜色/标志物），再到 Commons 挑图并**核对文件描述页的拍摄对象+拍摄年份**；三类直接跳过：古画/版画冒充实景（武汉黄鹤楼=绢本古画实锤）、建设期照片（鹦鹉洲大桥=塔吊未合龙实锤）、重滤镜无标志物（东湖=渔船剪影认不出实锤）；验收**逐张导出 base64 亲验**——图注落位对≠图内容对，两层分开验 ②🔴**SVG 导览图=v3.5 规范硬执行（武汉 6/6 全复发）**——6/6 无指北针（六要素缺「方向」）、6/6 零地标插画；个例硬伤：总览汉江画成从东汇入（实际自西北来）、day3 动线横穿湖心（穿水系=不存在的路）、day4 终点画进长江+汉江整条缺失（晴川阁核心特征=两江交汇口）、day5 等距水平线零地理；硬杠杠：**文字禁压线/禁入水/禁被遮挡、动线禁穿水系、每图至少 2-3 个地标小图标、支流汇入方向对照真实地图（⑪具体化）、交付前逐张截图亲验（自查⑮）**。📦 协作方待同步。
> 版本 v3.29（2026-09-26，武汉实战回写，作者拍板「严格执行」）｜**老毛病机械化+成稿工序补全**：①🔴**餐行机械钩**——每日必须有早/午/晚三行（v3.22 立规后广州/宁波/武汉三次再犯，武汉 5 天全漏）→交付前逐日 grep 三餐行数并报数，「园内/高铁上解决」也要有行 ②🔴**视觉资产三件套独立工序**——配图 figure≥天数+分散型景点 SVG 示意图+使用者点名店标记样式，与内容填写并列、缺一不算完成（武汉 v1 全缺实证：流水线只填了内容）③**派生首检**——从基准骨架派生第一动作=核对基准指纹（当前 `9c3c6249a4`）+立即改 title（武汉 v1 title=「基准骨架」直接成稿实证）④**点名店核销制**——使用者点名店=checklist 逐家勾销，交付报 N/N（武汉来菜丢失实证）⑤**相对时间禁令**——成稿禁「现在/明天」，一律绝对日期（「9/27 前抢省博票」式）⑥**「雨天备用」→「雨天方案」**——备用暗示可有可无，方案=正选之一 ⑦**信史/民俗标注成稿删除**——标注供内部审，成稿内容保留、标签去掉 ⑧**骨架组件修正（本次已落四副本+开源仓 push 2f94146，指纹 9c3c6249a4 不变——修的是注释/JS/footer 不碰 style）**——tips 标准结构示例写入注释（.tip::before 数字占 44px 首列，内容必须包一层元素，裸文本溢出竖排=武汉 v1 实证）+observer rootMargin 监测带 15%→40%（防矮区块高亮漏触发）+页脚补家族标语；顺带发现并修复：协作项目副本骨架 CSS 停旧指纹 769d1d9f64（v3.27 样式同步漏它），已对齐⑨**导航与页脚文案随趟定制**——「路程与停车」仅自驾趟用、页脚自驾话术非自驾趟删（武汉两处语境错位实证）⑩**点名店呈现形态（v3.29 定稿）**——使用者点名店集中呈现在美食清单结尾的**「作者推荐」彩蛋板块**（称呼用「作者推荐」，不用「本地人推荐」）；与「缘分型彩蛋」（无店名 R2 目标）分立。⑪**地理示意图必须先查真实地图对照再画**——「示意图非等比」≠「方位可以随意」：三镇/江向/相对方位本身就是信息，画错比不画更害人（武汉总览图古德寺画到对岸/东湖画到北边实证）；画前先对照地图 App 或权威地图确认江向/区界/相对方位 ⑫**气候数据实查+标来源**——气温区间禁拍脑袋（武汉初稿「15~24℃」实查应为「21~33℃+冷空气骤降可能」，偏低 6 度导致穿衣建议全错）；口径=当地气象台历年同期实况，且必须带「出发前 3 天看当日预报终判」提示。📦 协作方待同步。
> 版本 v3.28（2026-09-26，作者拍板补课；协作方v3.27/v3.28 并入本体取并集，撞号归并——协作方v3.27=口碑分级、协作方v3.28=十二条方法论，均已收编，双侧同号）｜**双向复核沉淀+协作方12 条+机位审美线**：①🔴**对外稿脱敏铁律**——内部代号/博主 ID 信源列/博主个人消费账单（「别人的马内」）一律不进对外稿；验收=成稿 grep「作者\|马内\|内部代号」必须 0（武汉素材稿正文真名×20 漏抓实证）②🔴**口径变更重扫**——口径/标准/红线升级后，此前基于旧口径的通过项全部失效重扫；批复时注明依据口径（CC×4 轮没抓到真名的根因）③**机位审美筛选线**——信源≥3 源交叉（官方文旅/市府官微/摄影攻略，不吃单一爆款图文）；「大开大阖」大场景优先（江桥楼湖同框/天际线/日落蓝调），纯市井杂乱类剔除——烟火气归美食线管，机位线只管大片；几何/未来感建筑也收（大智无界数据点）；先搜当地摄影圈验证过的封神点位，不拍脑袋发明 ④**夜景灯光秀专项**——基建强市必查灯光秀时间锚+烟花秀等特殊节点预约渠道（武汉两江四岸 19:00-22:00/国庆烟花「平安武汉」预约实证）⑤**场馆口径分歧处理**——官方口径与地图/平台不一致时两说并列+给核实电话或公众号，不擅自裁决（武汉图书馆新馆实证）⑥**节假日官宣必查**——法定假期的灯光秀/夜场/烟花以官方发布会通稿为准 ⑦**收录优先序+口碑分档**——使用者本地点名店=
```

## File: README.md
upstream: https://github.com/awangwang123/jianhao-travel-planner/blob/HEAD/README.md

````text
<div align="center">

# 见好 · 旅行路书

**让 AI 按统一流程查资料、排行程，制作可在手机和电脑查看的旅行路书。**

<sub>English: <a href="README.en.md">README.en.md</a> — what this is, what you get, and how to install it in any AI agent.</sub>

<p>
  <a href="https://github.com/awangwang123/jianhao-travel-planner/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/awangwang123/jianhao-travel-planner?style=flat-square"></a>
  <a href="https://github.com/awangwang123/jianhao-travel-planner/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/awangwang123/jianhao-travel-planner?style=flat-square"></a>
  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/awangwang123/jianhao-travel-planner?style=flat-square"></a>
  <a href="https://www.python.org/downloads/"><img alt="Python 3.8+" src="https://img.shields.io/badge/python-3.8%2B-blue?style=flat-square"></a>
  <a href="https://github.com/awangwang123/jianhao-travel-planner/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/awangwang123/jianhao-travel-planner/ci.yml?branch=main&style=flat-square&label=CI"></a>
</p>

<sub><a href="#这是什么">📖 开始使用</a> · <a href="preview/hero.jpg">🖼 看成品示例</a> · <a href="https://github.com/awangwang123/jianhao-travel-planner/releases">⬇️ 下载稳定版</a> · <a href="https://github.com/awangwang123/jianhao-travel-planner/issues">❓ 遇到问题</a> · <a href="TUTORIAL.md">零基础教程</a></sub>

<img src="preview/hero.jpg" width="680" alt="路书成品（桌面 + 导览图 + 手机）">

<sub>开源技能包，需配合 AI 助手使用 · 统一模板 · 事实核查流程 · 机械检查工具 · MIT</sub>

</div>

---

## 这是什么

一套「出行路书」工作流：你说"想出去玩"，它按固定流程采集需求 → 联网实查 → 产出**路书**（md 事实源 + 单文件 HTML 双版本：本地完整版断网可开 + 瘦身在线版一键部署）+ **美食情报卡**（按城市持续追加的数据资产）。

> [!TIP]
> **SKILL.md 的版本史是精华**——每条规矩背后都是一次真实翻车（图注落位对 ≠ 图内容对、数指标不算对比、价钱是挂牌价不是实付价……），建议通读，比规矩本身更值钱。

## 你能得到什么

- 📄 **单文件路书**：本地完整版断网可开，手机、电脑、打印纸都好看
- 🌐 **一键部署在线版**（需自有服务器，可选）：瘦身网页版一键部署，点开链接即看
- 🔍 **信息可信**：关键信息联网实查带来源，出发前按当日预报终判
- 🖼 **每天有实拍图**：真实景点照片 + 手绘行程导览图，不堆网图
- 🍜 **吃饭有章法**：推荐店各归各位，照抄照选两相宜
- 🚫 **隐私干净**：对外内容零敏感残留
- 🍱 **美食情报卡**：按城市持续追加的数据资产，越用越厚
- ✅ **交付可验收**：内置 `tools/checklist.py` 机械检查清单（随版本演进，以工具输出为准），AI 交稿前必跑——你也能一键验收 AI 有没有偷懒。注意：机械检查通过 ≠ 关键事实（交通/票务/价格）已核验，出行前请按路书内的核实状态标注复核

## 一份路书里有什么

| 板块 | 内容 |
|------|------|
| 总览 | 一句话行程 + 天气 + 出发前倒计时（勾选式）+ 装备清单 + 总览导览图 |
| 路程 | 交通方式怎么选 + 路程总表（里程/时长）+ 支付提示 |
| 每日行程 | 半小时级时段卡 + 实拍图 + 当日导览图 + 交通/机位/雨天方案 |
| 门票预约 | 多档价格 + 预约与放票口径 |
| 温馨提示 | 真实场景 + 应对，不写正确的废话 |
| 住宿 | 选点逻辑 + 退房时间 + 订房三问 |
| 预算 | 三档概览 + 逐项明细 + 隐藏成本 |
| 应急 | 全局兜底 + 紧急电话与领事保护 |
| 美食清单 | 按天按顿给店 + 必点 + 人均 |
| 特产 | 带什么 + 在哪买 |

## 换个目的地，形态自动适配

![海岛目的地的路程板块](preview/form.jpg)

<sub>海岛型目的地的路程板块——租车 / 公交 / 打车分层给方案，行程要素按目的地自动换挡</sub>

## 出境路书，同一套标准（v1.14 出境能力包）

![出境能力样张](preview/egypt_outbound.jpg)

<sub>埃及 7 天文化线·出境四件样张：热门未排目的地的取舍说明 / 出入境与支付分层 / 双币种预算（含税实付口径）/ 应急领保——行程与个人信息已脱敏，完整条款见 SKILL.md「出境册附加条款」</sub>

## 触发词

安装后，跟 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
- 博主白名单（原个人设定已移除）

## 看完整成品

<details>
<summary><b>展开看武汉 5 天 4 晚完整路书（长图，约 2MB）</b></summary>

![完整路书长图](preview/roadbook.jpg)

</details>

## 上线反响

![抖音数据](preview/douyin.jpg)

<sub>开源次日的抖音介绍视频：12.6 万播放 · 2889 收藏（数据截至 2026-09-30）</sub>

## 版本

当前 **v1.19**（2026-11-03）。最近两版要点：

- **v1.19**：新增「中转衔接与廉价航空」条款与知识蒸馏核查规则（转述 ≠ 核查）；最小流程改造——`QUICKSTART.md` 一页纸入口、标准模板、`pipeline new/outline`、`fetch_images`
- **v1.18**：完整示范配图改为标注「虚构示意」的插画；导览图出界检查收成三态（越界 FAIL / 查不完 FAIL / 无图 SKIP）；已发布标签不再覆盖

v1.0 起的逐版记录在 [CHANGELOG.md](CHANGELOG.md)。稳定包以 [Releases](https://github.com/awangwang123/jianhao-travel-planner/releases) 为准，主分支是开发态。

## 反馈与共创

- 🐛 **报错/用不了**：[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) 随便聊
- 🛠 **参与改进**：看 [CONTRIBUTING.md](CONTRIBUTING.md)（怎么报错、许愿、提 PR）
````
