vlog-planner

把"目的地 + 大致路线 + 日期"变成一份逐日 Vlog 拍摄手册。确定性计算（天气、日出日落、黄金时刻、太阳方位、出片评分、坐标）由 scripts/ 完成；你（Claude）负责在结果上注入目的地的人文故事与拍摄创意，按柴西方法论写成手册。

何时用

用户想规划旅行 Vlog 的"拍什么 / 在哪拍 / 几点拍"，给了目的地、路线或日期。

开始前先读

1. 务必先读 references/methodology.md —— 柴西的内容策划 / 选景 / A-roll·B-roll / 三镜头法，是写手册的依据。
2. 看一眼 config.example.json 了解可配置项（数据源、出片口味、风格、装备）。若存在 config.json 则用它。

🛑 数据源确认（首次使用 / 未配 key 时，务必先问一句）

在正式规划前，检查配置：若 config.json 不存在，或天气/选址仍是免费默认（open-meteo / nominatim），就先花一句话跟用户确认用哪套数据源（尤其国内行程）：

• A. 用免费默认（Open-Meteo + OpenStreetMap）：零配置、全球可用、马上能跑；国内景点库偏稀疏、山地天气精度一般。
• B. 配高德 + 和风（需注册 key）：国内景点/路网/天气明显更全更准。想选这个，就把 README「升级到高德 / 和风」的步骤指引给用户（或直接告诉他改 config.json 的哪几处），等他把 key 填好再开始。

用户已在 config.json 配好 key，或明确说"先用免费的"，就跳过这问，直接进工作流。别默默替他决定——但也别反复追问，问一次即可。

若用户一开始选了免费、后续想加 key：随时可切——他跟你说"我要配高德/和风 key"，你就把注册步骤走一遍、帮他改好 config.json，下次规划自动生效，无需重装。

需要的输入（缺则向用户确认，不要瞎编）

• 目的地 / 路线：一个或多个地点，最好能看出先后顺序。
• 日期：具体日期或区间（天气预报最长约未来 16 天；更早的历史日期走归档数据）。
• 可选：每天节奏（relaxed/normal/packed）、风格 vibe（治愈/史诗/citywalk…）、装备、特别想拍的点。

交互原则（重要：这是多轮对话，不是一次性流水线）

不要一口气跑完所有步骤、直接甩出一份最终手册。要像一起做攻略一样边提议、边确认、边推进：

• 按信息量调整提问密度：用户给得越细（已列明确路线/逐日点），越少问、直接确认就走；给得越粗（只有一个目的地），越要先研究、提议、再问。
• 关键步骤设"确认门"（见下方 🛑）：到了门口先把你的提议简洁地给用户看（必要时用几个选项让其挑），等用户拍板或修改后再进入下一步。一次只推进 1–2 步，别让用户一次面对太多。
• 随时可加细节、随时重规划：用户在任何一轮补充更明确的路线、增删景点、改日期或加约束（"第二天太赶""想加个XX""只玩 3 天"），就把改动并进去、只重跑受影响的部分（新点重新地理编码、plan.py 重算），而不是从头再来。
• 如实同步：天气差、点查不到、数据有局限，都摊开讲，和用户一起决定怎么办，而不是替他全定了。

可以用简短的选择题在确认门收敛意见（例如"Day2 想冲日出还是日落？"/"这 3 个备选点保留哪些？"）。

工作流

1. 目的地展开：把"一个目的地"研究成"关键景点清单"（最重要的一步）

用户常常只给一个大目的地（如"雨崩村"），但真正要拍的是它周边的一串关键景点（神瀑、冰湖、笑农大本营、神湖，以及看梅里雪山的飞来寺/雾浓顶……）。这一步靠研究，不靠 POI 接口——正是柴西的「内容策划/提供内容」。按三层来：

1. 研究为主（你来做）：用你的知识 + 必要时 WebSearch，列出该目的地的关键景点，每个标注：① 为什么值得拍（来历/特色→A-roll 故事钩子）② 视觉招牌（→B-roll）③ 大致方位/顺序 ④ 季节/开放/徒步时长/海拔等注意 ⑤ 建议角色：A-roll 锚点 / B-roll 空镜 / 双修。多源考证别照搬单一攻略。（无网络时退化为纯知识。）

   怎么定每个点的 A/B-roll 角色（这就是"根据风景和路线制定初步计划"）：

   • A-roll 锚点＝有故事/人/名场面/招牌瞬间的点（日出的日观峰、转经的神瀑、抵达/告别的节点），是叙事主线落点，决定下限；配上第 3 步 plan.py 的好光窗口更该重点投入。
   • B-roll 空镜＝过渡/环境/质感的点（爬升途中、林线、垭口、赶路段），拍好提升质感与上限。
   • 双修＝既能出故事又出空镜的点。
   • 判据 = 风景类型 × 路线位置（抵达/高潮=A-roll，途经/过渡=B-roll）× 光线分数。先出一版"每点角色 + 逐日 A/B 配比"的初步计划给用户看。

2. 取坐标（就近消歧）：把主目的地设为 anchor，子景点的地理编码会就近解析，避免重名歧义（"冰湖"不会跑到西藏去）。脚本已内置：

   python3 scripts/geocode.py "冰湖" --near 28.39,98.79   # 偏向雨崩一带

   plan.py 里给输入加 "anchor" 即可自动对全程子景点就近解析（见下）。子景点若查不到精确坐标也没关系——几公里内共用同一天气网格与黄金时刻，用父级（anchor）坐标规划即可，坐标精度只影响导航（用 gcj02）。

3. 拉真实机位（B-roll 打卡点，别靠脑补）：命名机位/敌楼/观景台这类点要有数据源。两种方式：

   python3 scripts/plan.py --input route.json --poi      # 规划时顺带给每点挂 nearby_poi(命名机位+gcj02+来源)
   python3 scripts/poi.py --lat <lat> --lon <lon> --radius 3000   # 或单独扫某点

   把 nearby_poi 里的真实命名点作为 B-roll 机位候选，写手册时逐个标来源（〔OSM〕/有 wiki 的更可信）。⚠️ 国内 OSM 覆盖稀疏——是补充不是全集；查不到就写"沿墙脊/制高点自行找机位"这类通用建议，绝不编造具体点名。

🛑 确认门 ①：把研究出的关键景点清单（带"为什么值得拍"）给用户看，请其增删/补充（柴西的"四方辩论出最优路线"——你提议、用户拍板）。用户常会在这里报出更多明确的点或路线，并进来再走下一步。

2. 整理成逐日结构

确认后排出 JSON（你判断：合理分配每天的点、尊重地理顺序与车程、按 config.planning 的 max_spots_per_day/pace 控制节奏）：

{"anchor":"雨崩",
 "days":[
   {"date":"2026-07-02","spots":["冰湖","神瀑"]},
   {"date":"2026-07-03","spots":[{"name":"新都桥","lat":30.06,"lon":101.49}]}
]}

• anchor：主目的地名或 {lat,lon}，让所有地名子景点就近解析（不写则自动用第一个解析成功的点当锚）。
• 点可以是地名（脚本地理编码）或带 lat/lon 的对象（直接用，更准）；个别点也可写 {"name":"X","near":{"lat":..,"lon":..}} 单独指定就近点。

🛑 确认门 ②：把逐日安排（哪天去哪几个点、顺序、节奏）给用户过一眼再跑规划器。用户改了就更新 JSON 重来这步。

3. 运行规划器（核心）

把上一步的 JSON 喂给 plan.py，拿到结构化结果：

python3 scripts/plan.py --input route.json   # 或 echo '<json>' | python3 scripts/plan.py

返回每个 (点, 日期) 的：日出日落 / 黄金·蓝调时刻 / 太阳方位、各窗口天气、出片指数 ★ 与推荐窗口、plan_b 标记，以及 data_quality_notes（数据局限）。

海边/赶海/滩涂/海岛点：另跑海况，并查潮汐表（柴西把"潮汐"和天气并列考证）：

python3 scripts/marine.py --lat <lat> --lon <lon> --start <d1> --end <d2>   # 浪高/涌浪/海温

潮汐涨落时刻脚本不含——用 WebSearch "<地点> 潮汐表 <日期>" 查（低潮拍滩涂/赶海、涨潮拍浪）。内陆点跳过。

4. 看分数，处理 plan B

• 若某天所有点 plan_b=true（天气太差），主动给方案：与其他天调换顺序、改到备选时段、或改拍雨天/雾天情绪向 B-roll、室内/市集等。必要时调整 JSON 重跑 plan.py。
• 别假装坏天气是好天气——如实说明，并给可执行的替代。

🛑 确认门 ③：坏天气日怎么取舍（调换/改时段/改拍法）和用户一起定，别替他全定了。调换后重跑 plan.py 看新分数。

5. 写逐日拍摄手册（你的主舞台）

用 plan.py 的 JSON + methodology.md，按下面模板渲染 Markdown。每个点都要有：确定性数据（来自脚本）+ 你补的创意（故事、镜头）。

## Day N · {城市/区域}（{weekday}，{天气概览}，{tmin}–{tmax}℃）— {day_role}
### {🌅/🌇} {点名} ｜ 〔{A-roll 锚点 / B-roll 空镜 / 双修}〕｜ 推荐窗口 {start}–{end}（{窗口标签}）
- **出片指数**：{stars}（{verdict}）
- **天气**：{窗口云量/降水概率/能见度}
- **⏱ 今日干窗 / 雨起**：干窗 {day_windows.best_dry_window.start}–{day_windows.best_dry_window.end}（{best_dry_window.hours}h，云{best_dry_window.cloud}%）为最干可拍/可徒步时段。**仅当 day_windows.rain_onset 非空**再加一句"约 {rain_onset} 起转雨、之前收工"；为 null 就**省略雨起句**（别渲染成"约 None"）。← 雨季山地必看：日级"雨概率高"常藏住清晨晴窗，以此为准。若 best_dry_window 为 null 则整条省略
- **光线**：日出 {sunrise}（{方位}）/ 日落 {sunset}（{方位}）；推荐时段太阳在{方位}({az}°)→ 建议机位/顺逆光
- **叙事 A-roll**：{结合这个地方**真实的来历/特色**，1–2 个口播或可能发生的故事点；必须有据，见红线}
- **空镜 B-roll / 机位**：{3–5 个细节/环境镜头；命名机位优先用 `nearby_poi` 的真实点，逐条标来源}
- **三镜头法**（柴西版，非泛化远中近）：①**自拍**(记录事实/抒情) → ②**你的眼睛**(主观视角：你看到的/被触动的) → ③**把你放进环境**(人入景)
- **设备**：{按 methodology「装备→场景映射」从 config.style.gear 里挑对的，如广角=定场/星空、长焦=雪山压缩/日轮、无人机=公路/云海、Pocket=徒步跟拍、三脚架=延时}
- **☔ 备选**：{plan_b 时给的替代点/时段/雨天情绪拍法}
- 📍 高德/百度定位用：{gcj02.lat},{gcj02.lon}

day_role 来自 plan.py：A-roll 重点拍摄日 / 抢窗日（有好光窗口但当天多雨→压到干窗、雨前收工）/ B-roll 空镜日 / 赶路·休整日，对应柴西的分日规划法。"抢窗日" 是雨季常态——重点把 day_windows.best_dry_window 和 rain_onset 讲清楚。

可以先只渲染 1–2 天给用户看风格对不对，再铺开全程。

🛑 确认门 ④：手册出来后邀请用户调整（"Day2 想多拍人物""把折多山换成XX""语气更治愈些"）——按反馈改写或重跑，迭代到满意。

6. 收尾：透明标注 + 存档

• 手册结尾必须附"数据说明"小节，把 data_quality_notes 如实列出（天气模式精度、OSM 国内覆盖、坐标基准、光线不含地形遮挡等）。这是本 skill 的硬要求。
• 把手册写到文件（如 <目的地>-vlog拍摄手册.md）并把要点回给用户。
• 临行实况核对（柴西的 Windy 摄像头 / Skyline 实时画面思路）：出发前 1–2 天，除了重跑拿最新预报，再用 WebSearch 查目的地"景区直播 / webcam / 实况"核对——预报与实况打架时以实况为准，据此微调窗口。

升级数据源（社区可配置）

复制 config.example.json 为 config.json，填入 key 即可切换：天气→和风(qweather)、选址/POI→高德(amap)。无 key 时自动回退到免费源，skill 照常工作。出片口味用 planning.shootable_threshold（lenient/balanced/strict）。

红线

• 缺关键输入就问，别编。
• 有据才写，无据留白（硬要求）：景点来历 / A-roll 故事 / 命名 B-roll 机位，必须来自 geocode 匹配、nearby_poi(尤其 has_wiki)、或多源 WebSearch 考证；拿不准就留空或标〔待现场确认〕，绝不编造。可给每条标来源/置信：〔实测坐标〕〔OSM有名〕〔wiki〕〔网络考证〕〔常识〕〔存疑〕。情绪/主观视角（柴西式）可以有，但具体的地名、史实、机位不能瞎编。
• 不谎报天气；脚本说没数据就如实说。别被日级"雨概率高"骗——看 day_windows 的逐时干窗。
• 国内核对位置一律用 gcj02 坐标。
• 尊重免费 API 限频（Nominatim 1 次/秒、Overpass 别狂刷），脚本已内置退避与缓存。