Citywalk 路线生成器

工作流程

Step 1：收集需求

向用户询问以下信息（可合并为一次提问）：

• 目标城市/街区（必需，如"上海武康路"）
• 主题（必需，如"咖啡漫步 / 美食探店 / 建筑摄影 / 文艺书店"）
• 时长预算（如"半天 / 3-4小时 / 全天"）
• 人群类型（情侣 / 朋友 / 独自 / 亲子）
• 是否提供小红书笔记链接（可选，提供则直接 web_fetch 解析）

Step 2：抓取小红书数据

若用户提供链接，使用 web_fetch 解析笔记内容，提取：

• 路线站点顺序与名称
• 每站的拍照建议、必点美食、实用贴士
• 口语化文案风格

若未提供链接，使用 web_search 搜索：

小红书 {城市} {主题} citywalk 路线 2026
小红书 {街区} 探店 打卡 攻略

提取高频出现的站点（按提及次数排序，取 Top 5-8）。

Step 3：规划路线

站点规划原则：

• 按地理顺序排列（不走回头路）
• 3-8个站点，根据时长调整
• 类型多样（景点 + 咖啡 + 美食 + 购物 + 休息点）
• 动静结合：每2-3个景点安排一个休息点
• 连续步行控制在 1.5km 以内

每个站点需通过 Nominatim OSM 查询获取精确坐标（见 Step 3.5），禁止凭记忆估算：

{ "name": "站点名", "lat": 纬度, "lng": 经度 }

Step 3.5：坐标校验（必做）

使用脚本 scripts/verify_coords.py 校验所有站点坐标，生成地图前必须通过校验。

执行方式：

# 基础校验（生成报告）
python3 .codebuddy/skills/citywalk-route-generator/scripts/verify_coords.py \
    --json stations.json --city 北京

# 自动修正 ERROR 级别坐标并输出修正后的 JSON
python3 .codebuddy/skills/citywalk-route-generator/scripts/verify_coords.py \
    --json stations.json --city 上海 --auto-fix --out stations_fixed.json

校验内容：

处理规则：

• ✅ OK（≤150m）：坐标准确，直接进入 Step 4
• ⚠️ WARN（150-500m）：人工判断是否接受，或替换为 OSM 推荐坐标
• ❌ ERROR（>500m）：必须修正。使用 --auto-fix 自动替换，或手动查询 Nominatim：

```

https://nominatim.openstreetmap.org/search?q={站点名} {城市}&format=json&accept-language=zh&limit=3

```

坐标获取标准流程（每个站点）：

1. 通过 web_fetch 查询 Nominatim：

```

https://nominatim.openstreetmap.org/search?q={站点名}+{城市}&format=json&limit=3&accept-language=zh

```

1. 取第一个结果的 lat / lon 字段
2. 若结果为 0 条，尝试更宽泛的关键词（如去掉"胡同""路"等后缀）
3. 记录到 stations.json，运行 verify_coords.py 校验

> ⚠️ 严禁凭记忆或 AI 知识直接填写坐标。实测偏差可达 500m-1.3km，会导致地图标记落在错误街道。

Step 4：生成路线地图（本地静态图）

使用脚本 scripts/gen_map.py 生成地图图片并内嵌为 base64。

执行方式：

1. 将站点 JSON 数据写入脚本变量（或通过参数传入）
2. 运行脚本：

python3 .codebuddy/skills/citywalk-route-generator/scripts/gen_map.py

3. 脚本会：
• 自动计算最佳 zoom（让路线占底图 80% 面积）
• 拉取 OSM 瓦片拼合为底图
• 用 Pillow 绘制：加粗路线、编号圆圈、站名标签、路段距离气泡、方向箭头
• 输出 base64 PNG 字符串

1. 将 base64 以 形式内嵌进 HTML

关键技术细节（踩坑记录）：

Step 5：撰写站点内容（小红书风格）

标题公式： {地点名}｜{核心卖点}超详细打卡路线

示例：武康路咖啡漫步｜全程不绕路超详细打卡路线

Hero 区副标题： 口语化，带情绪，点明核心体验

示例：梧桐树下边走边喝，5家咖啡馆+百年老建筑，随手一拍都是风景🌿

每个站点卡片 header 必须包含开放时间标签（景点/付费场所必填，街区/胡同可选）：

<!-- 景点示例 -->
<span class="station-hours">🕘 09:00-17:00 | 16:30停止入场 | 周一闭馆</span>
<!-- 开放街区示例 -->
<span class="station-hours">🕘 全天开放 | 店铺约11:00营业</span>
<!-- 商业园区示例 -->
<span class="station-hours">🕘 10:00-22:00</span>

CSS 样式：

.station-hours { background:#fffbeb; color:#b7791f; padding:3px 10px; border-radius:12px; font-size:12px; font-weight:600; border:1px solid #fbd38d; }

判断规则：

• 有门票/需预约的景点 → 必须填写，含闭馆日
• 商业园区/创意园 → 填写园区整体时间
• 胡同/开放街区 → 填写"全天开放"并注明店铺营业时间
• 纯商业店铺（咖啡馆等） → 可不加，在避坑提醒中说明

每个站点卡片必须包含 4 个信息块：

📸 出片机位   — 精确到角度+时间（如"落地窗逆光，下午4点最佳"）
🍽️ 必点清单   — 具体菜品/饮品名称+价格
💰 消费参考   — 分项价格区间（人均/单品）
💡 避坑提醒   — 开门时间、排队情况、注意事项等实用信息

写作规范：

• ✅ 具体："二楼靠窗逆光机位，工作日下午3点光线最柔和"
• ❌ 模糊："环境不错，适合拍照"
• ✅ 口语化："性价比遥遥领先"、"这颜值你值得"、"绝了"
• ❌ 官方宣传语："提供优质服务"、"历史悠久"
• ✅ 价格精确："拿铁 ¥20，自带杯减5元"
• ❌ 价格模糊："价格适中"

Step 6：生成 HTML 文件

以 assets/route-template.html 为基础（或直接生成完整 HTML），包含：

必需区块：

1. Hero 区 — 路线标题、副标题、主题标签、基础信息（时长/距离/交通起点/人均消费）
2. 路线地图 — base64 内嵌静态图片
3. 路线概览 — 统计卡片（站点数/时长/距离/消费/最佳季节/交通）
4. 详细站点 — 每站4块信息格 + 站点描述
5. 分享按钮 — 打印 + 复制链接

HTML 命名规范： {city}_{theme}_citywalk.html

示例：shanghai_wukang_coffee_citywalk.html

Step 7：预览与交付

preview_url("http://localhost:PORT/xxx_citywalk.html")

检查清单：

• [ ] 地图底图正常显示（不黑屏、不空白）
• [ ] 标记位置与实际地理位置吻合
• [ ] 路线标注清晰（编号、站名、距离均可读）
• [ ] 站点顺序合理（无回头路）
• [ ] 4块信息格内容具体、价格真实
• [ ] 响应式布局（宽屏/移动端）

地图脚本说明（scripts/gen_map.py）

脚本核心逻辑：

# 1. 动态计算最佳 zoom
def calc_best_zoom(bounds, map_w, map_h, target_fill=0.80):
    # 让路线范围占底图 target_fill 比例
    # 用 ceil 而非 floor，确保路线足够大
    zoom = ceil(min(zoom_for_w, zoom_for_h))
    return max(10, min(19, zoom))

# 2. 坐标转换（Mercator 投影）
def to_pixel(lng, lat, center_lng, center_lat, zoom, map_w, map_h):
    # 返回 [0, map_w] × [0, map_h] 范围内的像素坐标
    ...

# 3. 拼合 OSM 瓦片
for tx, ty in tile_range:
    url = f"https://tile.openstreetmap.org/{zoom}/{tx}/{ty}.png"
    # 需要设置 User-Agent，否则 OSM 拒绝请求

# 4. Pillow 绘制标注
# 绘制顺序：路线描边 → 主线 → 距离标签 → 方向箭头 → 站点圆圈 → 站名标签

# 5. 输出 base64
buf = io.BytesIO()
img.save(buf, "PNG")
b64 = base64.b64encode(buf.getvalue()).decode()

环境依赖： Pillow（标准 macOS Python 环境通常已自带）

内容质量标准

站点描述（2-4句）

• 第1句：核心亮点/历史背景（10字内说清楚）
• 第2句：氛围/视觉描述（带感官词）
• 第3句：当前状态/与其他站点关联
• 第4句（可选）：交通/起点信息

信息块要求

资源文件

常见问题

Q: OSM 瓦片下载失败？

A: 确保网络连通，User-Agent 设为 Mozilla/5.0 CityWalkMapGen/1.0，避免被 429 拒绝。

Q: 路线标记偏离实际街道？

A: 坐标估算错误，实测偏差可达 500m-1.3km。必须先运行 verify_coords.py 校验，用 --auto-fix 自动修正 ERROR 级别坐标。

Q: verify_coords.py 报 WARN 但坐标感觉是对的？

A: WARN（150-500m）可能是 OSM 数据中该地点的中心点与实际入口位置有偏差（如大型寺庙）。人工判断后可接受，或在 JSON 中手动指定入口坐标而非中心点。

Q: 站名标签重叠？

A: 减小 zoom 或将 target_fill 调低（如 0.70），让站点间距更大。

Q: 路线图太小/太大？

A: 修改 calc_best_zoom 的 target_fill 参数（0.70-0.90）。

Q: 小红书链接无法直接访问？

A: 先用 web_fetch 访问短链，若返回重定向，再对重定向后的 URL 发起第二次 web_fetch。

Q: Nominatim 返回结果为空？

A: 尝试简化查询词（如"雍和宫"而非"雍和宫大街12号"），或加城市名限定（"雍和宫 北京"）。

版本： v2.0 (2026-04-13) — 基于上海武康路路线实战经验全面重写

核心原则： 地图坐标准确 > 视觉美观 > 内容丰富