河流简介三件套（river-intro）
> 干的事：给一条河流做一份能直接拿去讲的简介，一次产出 HTML（网页）+ Word（讲义）+ PPT（课件） 三份。
> 一句话原则：数据先查证再落笔，讲解从「看得见的地图」出发，最后用一道数学题收尾。
何时使用
- 「介绍一下黄河 / 滦河 / 某某江」「做一份河流简介」
- 「大学选修课要讲一条河，帮我出课件」
- 「中小学研学材料」「景区讲解词 / 科普展板内容」
- 用户给了一条河名，要求整理成可讲的资料
不适用：水文专业报告、防洪调度方案、学术综述——本技能是通识科普深度。
能力边界
- ✅ 做什么：通识级河流简介、课件、讲义、科普网页。
- ✅ 产什么：同一份数据驱动的
river_spec.json→ HTML + DOCX + PPTX（PPT 页数随内容浮动，一般 12–20 页）。 - ❌ 不做什么：不编造任何数字；不使用非白名单地图服务；不写超出通识深度的专业推导。
受众定位（本技能的灵魂）
用户的原话是「对地理科学学者显得业余，对其他专业大学生显得专业」。落到写法上就是三句话：
- 术语要给白话台阶。第一次出现的术语必须紧跟一句人话解释，但不要加引号、不要写成词典体。
- 好：「流域面积 75 万平方千米——也就是雨水顺着地面汇进这条河的那片土地，大约相当于两个日本。」
- 差：「本流域属于典型季风气候区，径流年内分配不均，CV 值较高。」 - 数字必须有单位、有年份、有来源。这是「显得专业」的唯一来源。通篇不能出现没有出处的裸数字。
- 不用模型、不用公式推导、不用专业符号。允许出现的是：加减乘除、比例、百分比、单位换算、平均数。这是「显得业余」的边界。
细分三档，动手前先判断（用户没说就按 A 档）：
| 档 | 场景 | 篇幅 | 语气 | 趣味题难度 |
|---|---|---|---|---|
| A 大学选修课 | 通识课、选修课 | 全量，约 2500 字正文 | 平实、有据、带一点追问 | 初中数学 + 一次单位换算 |
| B 中小学 | 研学、课外 | 精简到 1200 字，段落短 | 口语、设问、多类比 | 小学数学，只用加减乘除 |
| C 景区 | 展板、讲解词 | 800 字，先讲看点 | 讲解腔、第二人称「您」 | 一道口算级问题 |
工作流
确认河流与用途 → 检索核实数据 → 取经纬度控制点 → 写 river_spec.json
→ 渲染地图 PNG → 渲染三件套 → 对照自检清单 → 交付
Step 1 确认两条信息（缺了才问，别反复追问）
- 哪条河（含别名，如「滦河 / 濡水」）。
- 给谁用：大学选修课 / 中小学 / 景区。用户没说就默认大学选修课。
其余（篇幅、配图、要不要加文化内容）按默认走，不要追问。
Step 2 检索核实数据（这一步不能跳）
用 WebSearch 逐项查证，至少交叉两个来源：
- 河长、流域面积、多年平均径流量、天然落差、河口位置
- 源头（精确到县/山系，注意「源头」有争议时并列写出主张）
- 干流流经的市、县（必须按从上游到下游的顺序整理）
- 主要支流（名称 + 长度 + 汇入位置）
- 流域内耕地面积、灌溉面积、粮食产量、渔获、牧业（牲畜存栏）等简要数据
- 气候类型、补给方式（雨水 / 冰雪融水 / 地下水）
数据纪律（硬性）：
- 查不到就写「暂无公开数据」，绝不估算、绝不编造。
- 同一指标不同来源打架时，写主流值，并在
notes里注明「另有 X 万之说」。 - 每个数字都要能追到来源，
sources数组里逐条登记（名称 + 年份 + 链接）。 - 数据年份超过 15 年的要注明年份，不要当现状讲。
Step 3 准备地图数据
地图规则见 references/map-guide.md，合规是红线，要点：
- 网页的默认地图是自绘示意图（内嵌 SVG）——不依赖联网、不依赖密钥，一定显示得出来。三件套里的静态图（Word / PPT 用 PNG）同源，都由
render_map.py依据公开经纬度控制点绘制，图注必须写「示意图，非标准地图」。 - 在线底图是可选增值项：HTML 里做成「点一下才加载」的腾讯地图 GL JS，加载失败只提示、不影响阅读。保留
__WB_HTTP_PORT__/__WB_TMAP_SECRET__占位符原样不动（宿主注入）。绝不要把在线地图做成页面默认视图——占位符没被注入时页面会只剩一个灰框。 - 干流采样点 16–40 个
[经度, 纬度]，从源头到河口按顺序。支流各 4–12 个点，首尾要接上：末端落在干流线上（偏差 < 5 千米），别画成悬空的平行线。 map.zones可选，给上中下游这种区域带做{name, bbox}标注，让阅读者一眼看出「这河上中下游是三种脾气」。- 若用户自己提供了公开/标准地图图片，可用
--basemap-image叠加（须同时给--extent）。
Step 4 填写 river_spec.json
复制 templates/river_spec.example.json 到工作目录，逐字段填写。这份 JSON 是三件套的唯一数据源，三份产出都由它渲染，改数据只改 JSON。
字段要点（完整说明见文件头注释与 references/content-spec.md）：
meta：河名、别名、用途档位（A/B/C）、一句话定位、制作者、日期quick_facts：4–6 个关键数字卡（河长、流域面积、年径流量、落差、流经省级区数）map：地图数据（见 Step 3）sections：正文分节，每节title+paragraphs[]+ 可选table/bulletscourse：按从上游到下游顺序的流经节点数组，每项{name, level, admin, note}（level: 省 / 市 / 县 / 区 / 乡镇）tributaries：主要支流数组economy：农林牧渔数据数组fun_questions：趣味问题数组（见 Step 5）sources：来源数组
Step 5 写趣味问题（本技能的差异化部分）
3–5 题，结合数学与地理，难度锚定初中数学，题干要给足数据让学生能算出来。
套路见 references/fun-questions.md（含 18 个可复用母题）。出题规则：
- 先给数据再提问，学生不需要额外查资料。
- 答案要给出完整算式，不只给结果。
- 每题末尾一句「这说明什么」，把数学拉回地理。
- 至少 1 题是反直觉的（例：地图放大后河会变长）。
- 至少 1 题是量级换算（例：年径流量 = 多少个西湖）。
标准结构：
{
"q": "题干（含全部已知数据）",
"hint": "提示（怎么下手，一句话）",
"answer": "完整算式 + 结果",
"why": "这说明什么（回到地理/生活）",
"level": "初中数学"
}
Step 6 渲染
先安装依赖（首次使用，三个包均来自 PyPI 官方源，建议装在虚拟环境里）：
pip install matplotlib python-docx python-pptx
然后把 <skill> 换成本技能所在目录（Windows 用 where，macOS / Linux 用 which 可直接定位 python3）：
PY=python3
SKILL=<skill目录绝对路径>
# 1) 先出地图
$PY $SKILL/scripts/render_map.py --spec river_spec.json --out-dir ./out
# 2) 再出三件套（自动引用上一步的 map.png / map.svg）
$PY $SKILL/scripts/build_river.py --spec river_spec.json --out-dir ./out
产出：out/<河名>简介.html、out/<河名>简介.docx、out/<河名>简介.pptx、out/map.png、out/map.svg。
只想要某一份：--only html / --only docx / --only pptx。
只需要矢量图（做网页/放大印刷）：render_map.py --formats svg。
若上面的解释器路径在本机不存在，改用系统 python3，并先
pip install python-docx python-pptx matplotlib。
脚本会打印每份产出的路径与页数/字数；报错会指明阶段，不要把报错吞掉。
内容要素清单（缺项要说明，不要硬凑）
用户指定的八项，加四项通识必备，共 12 项：
| # | 要素 | 要求 |
|---|---|---|
| 1 | 地图 | 网页默认内嵌自绘 SVG 示意图（必显示）+ 可选的在线底图；Word / PPT 用同源静态图 |
| 2 | 长度 | 干流全长 km，注明测量口径（"以 XX 为源"） |
| 3 | 源头 | 精确到县/山，有争议并列 |
| 4 | 流向 | 总体流向 + 关键转折（"先向东，过 XX 后折向东南"） |
| 5 | 主要支流 | 名称、长度、汇入岸别与位置 |
| 6 | 流域 | 流域面积、年径流量、气候、补给类型 |
| 7 | 农牧渔业 | 耕地、灌溉面积、粮食产量、渔获、牲畜存栏（查不到就写暂无） |
| 8 | 流经市县 | 严格按上游→下游，市在前县在后，逐段标注 |
| 9 | 落差与比降 | 天然落差 m、平均比降 ‰（给算式） |
| 10 | 水系形态 | 树枝状 / 扇形 / 羽状 / 平行状，一句话 |
| 11 | 人地关系 | 主要水利枢纽、桥梁、灌区、港口，或文化/景观看点 |
| 12 | 趣味问题 | 3–5 题，数学 + 地理，初中水平 |
三份产出的版式
| 产出 | 规格 |
|---|---|
| HTML | 单文件、浅色、响应式；含内嵌 SVG 地图（可选切在线底图）、关键数字卡、流向路线图、支流表、数据表、折叠式趣味问答、来源列表 |
| Word | A4、标题三级、正文宋体/标题黑体、表格三线式、图注居中、末尾附来源 |
| PPT | 16:9、12–20 页、每页一个主张、字大行稀、图表优先于段落；趣味题一页一题 |
交付自检清单（逐条过，别跳）
- [ ] 每个数字都有
sources条目？裸数字一律补来源或删掉。 - [ ] 流经市县顺序是从上游到下游？有没有跳段、重复？
- [ ] 地图数据源在白名单内？图注有没有标「示意图，非标准地图」、并说明圆点是「河段位置」而非驻地？
- [ ] 支流末端是否落在干流线上（没有悬空或横穿干流的线）？
- [ ] 趣味题给了完整算式和「这说明什么」？
- [ ] 术语第一次出现都跟了白话解释？
- [ ] HTML 打开后不联网也有地图（内嵌 SVG 一定可见）；点「在线底图」失败时只出提示、页面不塌？
- [ ] 三份产出的河名、数字完全一致（同一 JSON 渲染，理论上一致，但要抽查）？
- [ ] Word 里插图存在、图注在图下方、不跨页挤爆？
- [ ] PPT 配图没有超出 13.33×7.5 英寸画布（脚本已按高度适配，改动后要复核）？
- [ ] PPT 每页不超过 8 条要点，单条不超过两行？
常见问题
- 数据查不到：写「暂无公开数据」，并在交付说明里点名哪一项缺、缺的原因。不要拿邻近流域的数据顶替。
- 河长有多个版本（常见于源头认定不同）：主值写最通行的，括号注「XX 口径下为 XXXX km」。
- 脚本报缺中文字体：本机需有 PingFang / 宋体 / 黑体。脚本会自动探测，探测不到会在图上标「字体缺失，标注将显示为方框」。
- 在线底图点开是空白：说明腾讯地图的密钥/代理没配好。这是可选功能，不要为了它去改占位符——
__WB_HTTP_PORT__/__WB_TMAP_SECRET__必须原样留着由宿主注入。默认视图永远是自绘示意图，所以留一个空框是不允许的。 - 图上文字互相压在一起：
render_map.py有自动避让，压得厉害说明数据点太密（常见于县界附近几个水库/县城挤在一处）。把次要的点从map.points里删掉，或在map.points里保留但改kind降权。 - PPT 里地图被截断：不要手写固定宽高的插图，用
png_size()按可用区域等比适配（脚本已内置）。
参考文件
| 文件 | 内容 |
|---|---|
references/content-spec.md |
12 项要素逐项写法与措辞示例 |
references/audience-tone.md |
三档受众的语气样例与篇幅 |
references/fun-questions.md |
18 个趣味母题（数学 × 地理） |
references/map-guide.md |
地图合规红线与制图规范 |
templates/river_spec.example.json |
数据模板（含注释） |
