name: store-network-planner
version: 1.3.3
description: >
连锁门店网络布局规划与选址评估技能。支持多业态选址：餐饮/快消/服装/水果生鲜/娱乐场所。
核心目标：找出优质点位，开能盈利的门店。
V1.2 新增：地理空间分析（地图落位/距离/覆盖人口/等时圈/空白点扫描）
V1.3 增强：Streamlit Web 界面 / 真实人口栅格 / 预测闭环 / PPT 自动生成 / 4 个实战案例
V1.3.1 调整：Web界面在Agent场景不可用，已替换为图片模式（matplotlib PNG）
V1.3.2 增强：能力自检模块（matplotlib+AI文生图）+ AI 装修效果图
V1.3.3 增强：vision门店照片分析 / VI一致性 / 客流热力图 / 多Agent并行
V1.3.4 增强：图片智能压缩（4档位：微信/报告/缩略图/邮件）
V1.3.5 增强：analogy_predict_enhanced bug修复（兼容中英字段）+ 客流波动预测（4因子模型）
V1.3.6 增强：天气 API 自动接入（和风/心知/mock 降级）+ PDF 报告生成（fpdf2 + 中文字体）+ 25 个脚本全栈回归测试 25/25 通过

trigger_keywords:
# 选址类
- 新店选址 / 点位评估 / 门店布局规划 / 落位
- 商圈分析 / 商圈调研 / 客流统计 / 客流热力
- 竞争对标 / 竞品分析 / 跨业态竞争
- 周边配套 / 公共资源 / 聚客点
# PDF / 邮件附件（V1.3.6 新增）
- PDF 报告 / 邮件附件 / 打印版报告
- 客流周报 / 选址评估 PDF / 综合评估报告
# 财务类
- 盈利预测 / 盈亏平衡 / 回本周期 / 投资测算 / 投资回收期
# 规划类
- 年度开店计划 / 城市进入 / 区域规划 / 网络布局
- 门店加密 / 门店分级 / 攻防地图 / 自相竞争
- 门店关闭 / 门店迁移 / 门店升级 / 关店决策
# 督导类
- 区域督导 / 门店巡查 / 整改 / 经营异常
# 预测类
- 好店预测 / 预测模型 / 类比法 / 回归法
- 预测精度 / 置信区间 / 预测需要什么数据
- 渗透率 / 覆盖半径 / 覆盖效率
# 跨业态
- 餐饮选址 / 便利店选址 / 服装选址 / 水果店选址 / 娱乐场所选址
# 地理空间（V1.2 新增）
- 地图 / 落位图 / 选址图 / 落点
- 周边 / 半径 / 距离 / 自相竞争距离
- 覆盖人口 / 等时圈 / 空白点 / 区域扫描
- 攻防地图 / 竞品分布 / 网络规划
- 经纬度 / 地理坐标 / 缓冲区 / 通勤
# AI 文生图（V1.3.2 新增）
- 装修图 / 效果图 / 概念图 / 装修参考
- 菜品图 / 菜品拍摄 / 菜品图
- 门头图 / 招牌设计 / 视觉设计
- 选址概念图 / 商圈概念图
# V1.3.3 新增
- 门店照片 / 督导巡查 / 现场照片
- VI 一致性 / 品牌一致性 / VI 检测
- 客流热力 / 人流数据 / 热力图
- 多 Agent / 并行分析 / subagent
# V1.3.4 新增
- 图片压缩 / 照片太大 / 压缩图片 / 缩图
- 微信发图 / 飞书发图 / 钉钉发图 / 工作群发图
- 报告插图 / PPT 插图 / 文档插图
- 缩略图 / 列表预览 / 图片预览
# V1.3.5 新增
- 客流预测 / 客流波动 / 客流估算 / 客流预估
- 明天客流 / 这周客流 / 下周客流
- 节日客流 / 国庆 / 春节 / 中秋 / 情人节
- 天气影响 / 下雨 / 高温 / 暴雨 / 严寒
- 备货预测 / 排班建议 / 营业时间
# V1.3.6 新增
- 天气 API / 天气预报 / 和风天气 / 心知天气 / QWeather / Seniverse
- 7 天预报 / 未来天气 / 自动天气
- PDF 报告 / 邮件报告 / 打印版报告 / 客流周报 PDF
- fpdf2 / 中文 PDF / 字体 / wqy-zenhei

连锁门店网络布局规划（V1.3.2 · 触发式加载版）

> 加载方式说明：本文档为入口与路由表。详细参数/案例/公式请按 → 跳转 标记加载对应 reference 文件。
> 核心原则：用户问什么 → 路由表匹配 → 按需加载对应模块，避免一次性加载所有内容（节省 token + 提升精度）。

零、首次使用（必读 · 能力自检）

> ⭐ 首次使用本 Skill 时必须运行此检查，确认当前环境能否生成图片。

快速检查

python scripts/capability_check.py

检查 3 项能力

自检输出示例（当前环境）

============================================================
  store-network-planner V1.3.2 能力自检
============================================================
✅ matplotlib 图表生成（核心）: OK
   • matplotlib: 3.10.9 / contextily: 1.7.0 / 中文字体: wqy-zenhei.ttc
✅ AI 文生图（可选，装修图/效果图）: OK
   • openai_dalle: True / provider: openai_dalle
✅ Agent 图片发送能力: OK
============================================================
整体状态: OK ✓ 所有能力正常，可以开始使用

检测时机

• ✅ 自动：3 个 geo 脚本（geo_helper/batch/advanced）每次运行时自动检测
• ✅ 手动：随时运行 python scripts/capability_check.py
• ✅ Agent 决策：调用 capability_check.get_capability_summary() 快速判断

配置 AI 文生图（可选）

如需生成装修效果图，请配置以下任一后端：

方法 1：OpenAI DALL-E 3（推荐）

pip install openai
export OPENAI_API_KEY=sk-xxx

方法 2：Replicate（多模型）

pip install replicate
export REPLICATE_API_TOKEN=r8_xxx

方法 3：Stability AI

pip install stability-sdk
export STABILITY_API_KEY=sk-xxx

方法 4：配置文件

# ~/.hermes/config.yaml
image_gen:
  provider: openai  # 或 replicate / stability
  api_key: sk-xxx

未配置时：所有数据图表（落位图/柱状图/雷达图）正常生成，仅 AI 装修图功能不可用。

零、快速路由（用户提问 → 加载什么）

> ⚠️ 本表为本 Skill 的核心，匹配用户意图后按需加载对应章节/文件，不要默认加载全部内容。

多关键词时按优先级路由：盈利 > 选址 > 规划 > 预测 > 督导。

一、业态分类体系（本 Skill 支持的五大业态）

→ 详细业态特征/选址特征：加载 references/business-analysis.md

二、用户画像采集（首次使用必问）

1. 业态类型：餐饮/快消/服装/水果生鲜/娱乐（必选）
2. 子类选择：见各业态子类列表
3. 产品特征：标准型/短效期/高库存/低库存
4. 目标客群：年龄/消费力/职业/消费习惯
5. 开发角色：总部开发/区域督导/加盟商

> 💡 用户画像采集后保存到记忆，后续会话自动应用。

三、六维评估模型（→ 评估"位置好不好"）

> ⚠️ 评估模型（专家打分，定性）≠ 预测模型（数据驱动，定量）。用户问"好店模型"实际想要的是预测模型（见十六）。

评级标准：≥80分优先开发 | 60-80分谨慎评估 | <60分放弃

→ 各维度详细参数/打分细则/业态差异化权重：加载 references/assessment-model.md

四、周边配套评估（第六维度 · 核心特色 · 内置概要）

4.1 交通条件（30%）

4.2 聚客点叠加公式（重要）

有效客流 = 基础客流 × (1 + 聚客点加成系数)
商场/购物中心：+30-50%
地铁站：+20-40%
菜市场：+20-30%（生鲜/餐饮强相关）
写字楼：+15-25%（快餐/咖啡强相关）
学校：+10-20%
医院：+10-20%
公园：+5-15%

叠加规则：多聚客点可叠加，2个以上加分上限150%（边际递减）

→ 完整聚客点评估/商圈人口分析/覆盖效率公式：加载 references/pedestrian-analysis.md

4.3 公共资源影响（按业态）

五、覆盖效率标准（按业态 · 内置速查）

单店覆盖人口基准（区域督导自查用）：
- 快餐：3-5万人，渗透率≥15%
- 便利店：0.5-1万人，渗透率≥20%
- 水果生鲜：0.5-1.5万人，渗透率≥25%

六、盈利测算（→ 加载 references/profit-calculation.md）

6.1 成本结构差异（速查）

6.2 盈亏平衡公式

月固定成本 = 租金 + 人工 + 水电 + 折旧 + 其他
月盈亏平衡营业额 = 月固定成本 ÷ 毛利率
日需来客数 = 月盈亏平衡营业额 ÷ 30 ÷ 客单价

→ 完整测算器/分业态明细模板：加载 references/profit-calculation.md + 运行 scripts/profit_model.py

七、竞争分析框架（→ 加载 references/competitive-analysis.md）

7.1 竞争强度分级

7.2 跨业态竞争视角

• 互补业态 → 互相引流（餐饮+水果+便利店）
• 替代业态 → 争夺客流（同品类餐饮）
• 目的性业态 → 独立需求（影院 vs 快餐）

→ 完整分析框架/对标表/攻防地图：加载 references/competitive-analysis.md

八、自相竞争管控（警戒线 · 内置速查）

九～十二、商圈评估 / 人群画像 / 人口分析 / 开发周期

这些章节为参考性内容，用户主动问到"商圈怎么评估/客群怎么分析"时再加载：

• 九、商圈评估标准（按业态） → references/business-analysis.md
• 十、人群画像与消费能力 → references/business-analysis.md
• 十一、商圈人口分析（聚客点叠加/覆盖效率公式） → references/pedestrian-analysis.md
• 十二、开发周期管控（90-120天开业前关键节点） → references/business-analysis.md

十三、门店分级动态管理（区域督导核心 · 内置速查）

季度复盘 → 门店分级调整
A+店：连续3月营收超均值150% → 维持旗舰标准
A店：连续3月营收超均值100% → 观察升级
B店：连续3月营收低于均值70% → 预警整改
C店：连续3月亏损 → 评估关闭/转型/降级

关店标准：
  - 连续6月亏损且无好转趋势
  - 物业条件恶化（租金上涨/规划变更）
  - 商圈客流整体下降>30%

→ 完整分级标准/整改流程：加载 references/business-analysis.md

十四、输出模板（按场景）

14.1 新店选址评估报告

【新店选址评估报告】
业态：___  子类：___
门店名称/地址：___
商圈类型：___
评估总分：___/100（___等级）

一、商圈价值
二、位置评估
三、周边配套（核心新增）
  - 交通/停车/聚客点/公共资源/商圈成熟度
四、业态匹配分析
五、盈利预测（投资估算/成本结构/盈亏平衡/回本周期）
六、风险提示（自相竞争/跨业态/物业规划/聚客点变化）
七、综合建议：✓ 建议开店 / ⚠ 谨慎评估 / ✗ 不建议

14.2 城市进入评估报告

【城市进入评估报告】
城市：___  等级：___  目标业态：___

一、城市基本面（GDP/人口/消费力/商业地产）
二、目标业态市场分析（市场容量/竞争格局）
三、进入机会（机会商圈/差异化空间）
四、开发策略（目标门店数/业态组合/开发节奏/资源投入）
五、综合建议

14.3 门店分级整改报告

【门店分级整改报告】
门店：___  当前等级：___  整改目标：___

一、问题诊断（营收/客单/客流/成本结构）
二、根因分析（商圈衰退？管理问题？竞争挤压？）
三、整改措施（保留/降级/关闭）
四、时间表与责任人

十五、自相竞争排查 SOP（区域督导专用 · 内置）

Step 1: 距离筛查 → 新店与已开门店距离是否触发警戒线
Step 2: 客流分流分析 → 历史曲线对比、营业额影响测算
Step 3: 客群重叠度分析 → 同一目标客群比例 > 60%?
Step 4: 商圈容量评估 → 商圈总客流 ÷ 各店分流后单店客流
Step 5: 决策输出
  - 影响 < 10%：同意开店
  - 影响 10-25%：老店整改+新店谨慎
  - 影响 > 25%：新店选址调整/老店降级

十六、好店预测模型（→ 加载 references/prediction-methods.md）

> 用数据预测新店日均营业额，告别"凭经验"。

16.1 两种方法对比（用户最关心）

16.2 选型决策

16.3 模型评估标准（R²）

• R² ≥ 0.7：模型好，预测可信
• R² ≥ 0.5：模型一般，供参考
• R² < 0.5：模型弱，建议补充数据

16.4 常见陷阱速查

→ 完整相似度模型/特征工程/代码实现：加载 references/prediction-methods.md
→ 运行脚本：scripts/analogy_predictor.py 或 scripts/regression_predictor.py
→ Agent实现参考：加载 references/prediction-model-tech.md（陷阱与改进的技术细节）

十七、实战案例（持续沉淀）

> 此章节用于沉淀真实案例，每个案例包含：背景 → 决策依据 → 实际结果 → 反思。

→ 完整案例（背景/过程/结果/教训）：加载 references/cases.md
→ 案例数据文件：assets/cases/case*.csv（已有20家门店+8候选+10竞品的真实数据）

十八、文件索引（按用途分类）

核心文档（按场景加载）

可执行脚本

资产文件

模板文件

加载策略总结（Agent 必须遵守）

1. 入口加载：仅加载本 SKILL.md（约 8K tokens），理解路由表
2. 意图识别：根据用户提问匹配 trigger_keywords
3. 按需加载：仅加载匹配的 reference 文件
4. 避免陷阱：
   - ❌ 不要默认加载所有 reference
   - ❌ 看到"好店模型"不要先讲评估模型
   - ❌ 不要在用户没问预测时主动展开第十六章
5. 上下文感知：用户已说明业态/城市/角色后，跳过画像采集

依赖的可复用 Skill（类级能力）

本 Skill 大量使用了两个类级共享 Skill，新场景可直接套用：

• software-development/agent-image-output：Agent 场景下的图片输出范式（matplotlib PNG + MEDIA: 协议 + 能力自检 + base64 嵌图）。本 Skill 的 scripts/visualizer.py、scripts/capability_check.py、scripts/startup_check.py、scripts/ai_image_gen.py 全部基于此范式实现。
• software-development/pptx-and-matplotlib-pitfalls：python-pptx 与 matplotlib 的真实踩坑集（font.size 单位、marker 名称、gridspec 索引、文件大小、Agg backend）。本 Skill 开发过程中踩中的坑已沉淀到该 reference。

→ 当你需要为新场景设计 Agent 友好的可视化脚本时，先加载这两个 Skill，再写代码。

十九、地理空间分析（V1.2/V1.3 增强 · 全阶段覆盖）

> 为不会编程的督导/网络规划同事提供地图能力。三阶段可选其一或全部。

19.1 触发词

• 地图 / 落位图 / 选址图 / 落点
• 周边 / 半径 / 距离 / 自相竞争
• 覆盖人口 / 等时圈 / 空白点 / 区域扫描
• 攻防地图 / 竞品分布 / 网络规划
• 经纬度 / 地理坐标 / 缓冲区 / 通勤

19.2 数据源选择（首次使用）

默认推荐：高德地图（国内 POI 最准，6000次/日免费）

> 切换数据源：直接修改 scripts/config.json 即可。

19.3 三阶段能力速览

用户选择规则（询问用户）：

1. 仅评估一个店 → 阶段1
2. 评估多个候选店/做年度规划 → 阶段2
3. 区域级战略规划/城市进入 → 阶段3
4. 一次性用到所有功能 → 全部加载

19.4 阶段1 速查（5个核心）

# 1. 地址解析
python scripts/geo_helper.py geocode "北京西单北大街1号"

# 2. 两点距离
python scripts/geo_helper.py distance --from "A" --to "B"

# 3. 周边搜索（如 1km 内的商场）
python scripts/geo_helper.py nearby --address "A" --radius 1000 --type 商场

# 4. 简单落位图（HTML）
python scripts/geo_helper.py map --address "A" --with-poi

# 5. 自相竞争检查（与已有门店的距离）
python scripts/geo_helper.py cannibal --new "新店地址" --existing assets/stores-template.csv

19.5 阶段2 速查（3个核心）

# 1. 批量距离矩阵（多候选 × 多已有）
python scripts/geo_batch.py distance-matrix \
  --input assets/candidates-template.csv \
  --existing assets/stores-template.csv

# 2. 批量落位图（自店+候选+竞品）
python scripts/geo_batch.py map \
  --stores assets/stores-template.csv \
  --candidates assets/candidates-template.csv \
  --competitors 竞品.csv

# 3. 攻防地图（自店 vs 竞品）
python scripts/geo_batch.py battlemap \
  --self 自店.csv --competitor 竞品.csv

19.6 阶段3 速查（4个核心）

# 1. 真实覆盖人口分析
python scripts/geo_advanced.py population --stores stores.csv --radius 3000

# 2. 等时圈（步行15分钟真实可达）
python scripts/geo_advanced.py isochrone --address "A" --minutes 15 --mode walking

# 3. 空白点智能识别（区域扫描）
python scripts/geo_advanced.py gap-analysis --region "北京海淀区" --stores stores.csv

# 4. 完整商圈报告（综合输出）
python scripts/geo_advanced.py full-report --new-store "新店" --format html

19.7 输出格式

核心原则：本 Skill 在 Agent/Chatbot 场景下，所有可视化输出 PNG 图片（手机可看/QQ/微信可发）。

每个脚本运行时询问用户：
- 1. PNG 图片（推荐，50-150KB，手机可看）
- 2. Excel 文件（数据导向）
- 3. 两者都要

也可以直接用 --format 参数指定（image / excel / both）。

已删除的格式（V1.3.1）：
- ❌ HTML 网页（需要浏览器，Agent 场景无法使用）
- ❌ Streamlit Web 界面（用户本地无 Python 环境）
- ❌ Folium 交互地图（同上）

保留的格式：
- ✅ PNG 静态图片（含底图、指北针、图例）
- ✅ Excel 数据报表
- ✅ PPT 演示文稿（图片嵌入）

19.8 用户友好入口（Agent 场景专用）

核心约束：本 Skill 由 OpenClaw/HermesAgent 调用，用户没有 Python 环境、没有浏览器、看不到 HTML。

Agent 必须做的：
- ✅ 所有可视化输出 PNG 图片（matplotlib 静态图）
- ✅ 用 MEDIA:/path/to/image.png 直接发图给用户
- ✅ 中文标注 + 底图 + 图例（白底，督导友好）
- ✅ 单图 ≤ 200KB（适合手机流量）
- ❌ 禁止生成 HTML（用户打不开）
- ❌ 禁止依赖 Web 界面（Streamlit/Flask）

输出文件清单（Agent 可直接 send_media）：

Agent 回复模板：

已为您生成 3 张分析图：
📊 落位图：MEDIA:/path/to/location_map.png
📊 自相竞争：MEDIA:/path/to/cannibal_chart.png
📈 完整报告：MEDIA:/path/to/full_report_summary.png

主要结论：
- 综合评分 82/100（推荐开店）
- 3km 覆盖人口 18.5万
- 月营业额预测 ¥194,400
- 自相竞争 0 家触发

19.10 V1.3.3+ 增强模块（vision + VI + 热力图 + 多Agent + 图片压缩）

多 Agent 并行调用模板（V1.3.3 新）：

# Agent 一次发起 3 个并行任务
from multi_agent import dispatch_parallel_tasks
from delegate_task import delegate_task  # Hermes 内置

# 1. 构造共享 context
context = {
    "new_store_address": "北京丰台区方庄南路",
    "existing_stores_csv": "assets/cases/case1-existing-stores.csv",
    "candidates_csv": "assets/cases/case1-candidates.csv",
    "output_dir": "/tmp/store_analysis"
}

# 2. 调度 3 个任务
dispatch = dispatch_parallel_tasks(context)
# → 返回 3 个任务模板（单店/批量/预测）

# 3. Agent 用 delegate_task 并行执行（节省 60-180s）
results = delegate_task(tasks=[
    {"goal": dispatch["tasks"][0]["task"]["instructions"], "context": context, "toolsets": [...]},
    {"goal": dispatch["tasks"][1]["task"]["instructions"], "context": context, "toolsets": [...]},
    {"goal": dispatch["tasks"][2]["task"]["instructions"], "context": context, "toolsets": [...]},
])

# 4. 汇总
from multi_agent import aggregate_results
summary = aggregate_results(results)
# → {"consensus_score": 78, "total_images": 9, "successful": 3}

vision 图片分析调用模板：

from image_analyzer import analyze_store_photo, parse_vision_response, generate_improvement_report, render_audit_report

# 1. 生成 prompt
action = analyze_store_photo("/path/to/store.jpg", "store_audit")

# 2. Agent 调用 vision_analyze（实际由 Agent 执行）
# vision_analyze(image=action["image_path"], question=action["prompt"])

# 3. 解析响应
parsed = parse_vision_response(vision_response)

# 4. 生成报告
report = generate_improvement_report(parsed, store_name="方庄店")
img = render_audit_report(report, "audit_report.png")

VI 检测（纯本地，无需 AI）：

from vi_checker import full_vi_check, render_vi_report, DEFAULT_VI_CONFIG
result = full_vi_check("store.jpg", DEFAULT_VI_CONFIG, "方庄店")
img = render_vi_report(result, "vi_report.png")
# → 评分 65/100，违规：白超上限 / 主色集中

客流热力图：

from heatmap_gen import generate_heatmap
generate_heatmap(
    "csv:heatmap_data.csv",  # 或 "amap:API_KEY"
    store_locations=[{"lng": 116.43, "lat": 39.86, "name": "方庄店"}],
    output_path="heatmap.png"
)

能力自检一键运行：

python scripts/capability_check.py
# 输出 3 项检查：matplotlib / AI文生图 / Agent发送

AI 装修图生成（需配置文生图模型）：

from ai_image_gen import generate_store_exterior, generate_dish_photo
generate_store_exterior(style="modern_chinese", output_path="store.png")
generate_dish_photo("宫保鸡丁", output_path="dish.png")

Web 界面：❌ 已删除（V1.3.1）

Agent 调用图片生成（一行代码）：

from visualizer import plot_single_site
plot_single_site(
    center_lng=116.43, center_lat=39.86,
    address="北京方庄", radius_m=1500,
    facilities={"商场": [(lng, lat, "名称")]},
    output_path="output.png"
)
# 然后用 send_message(action="send", message="MEDIA:/abs/path/output.png")

19.10.5 图片智能压缩（image_compressor.py）

督导在门店用手机拍的照片（2-5MB）传到工作群经常被吐槽"太占内存"。本脚本提供 4 个档位的智能压缩：

4 档位：

4 阶梯压缩算法：
1. EXIF 自动旋转（手机横屏照片方向修正）
2. 智能缩尺寸（按最长边）
3. 调整 JPEG quality（85→70→50）
4. 转 WebP（同质量小 25-35%）

单图压缩：

python image_compressor.py photo.jpg --preset wechat
python image_compressor.py photo.jpg --use-for feishu  # 智能选档
python image_compressor.py photo.jpg --target-size 300 --format webp

批量压缩：

python image_compressor.py /path/to/photos/ --preset wechat --output /path/out/ --recursive
python image_compressor.py "*.jpg" --preset report

链式调用（被其他脚本集成）：

from image_compressor import compress_for_wechat, compress_for_report, compress_for_thumbnail

# 压到微信合适大小
out_path = compress_for_wechat("store_photo.jpg")

# 集成到 report_generator.py
def generate_vi_report(image_path, ...):
    # 先压缩再插入报告
    thumb = compress_for_thumbnail(image_path)
    ...

实测效果（模拟 10MB 手机照片）：
- 单图：10582 KB → 490 KB（节省 95.4%）
- 批量 5 张：10810 KB → 1158 KB（节省 89.3%）

19.10.6 天气 API 自动接入（weather_api.py · V1.3.6 新增）

客流预测需要天气数据，本脚本自动从和风天气 / 心知天气 / mock 三个数据源获取：

3 个 Provider：

Key 配置：

export QWEATHER_KEY=xxx
export SENIVERSE_KEY=xxx

统一入口（带自动降级）：

from weather_api import get_weather_forecast

# 沙箱环境/无 Key：自动降级到 mock（不抛异常）
forecast = get_weather_forecast(
    location="北京方庄",          # 支持 "城市名" 或 "lng,lat"
    days=7,
    provider="qweather",          # 缺 Key 时自动降级 mock
    use_mock_on_fail=True,        # 默认 True
)
# → [{"date": "...", "temp_max": 28, "temp_min": 20,
#    "precipitation": 0, "condition": "晴", "source": "..."}, ...]

# 与客流预测集成（一行集成）
from footfall_forecast import predict_week
results = predict_week(
    baseline=280, start_date="2026-06-15",
    weather_week=forecast,
)

CLI 模式（注意：INFO 信息走 stderr，JSON 干净输出到 stdout）：

python weather_api.py --provider qweather --city 北京方庄 --days 7
python weather_api.py --provider mock --city 116.43,39.86 --days 5 --json

与客流预测联动公式：

最终客流 = 基线 × (工作日因子 × 节假日因子 × 天气因子 × 季节因子)
其中天气因子由 temp_max/precipitation 自动计算（参考 weather_factor() 函数）

19.10.7 PDF 报告生成（pdf_report.py · V1.3.6 新增）

为开店建议/客流预测生成可邮件发送的 PDF 报告。3 个场景：

3 个入口：

# 1. 选址 PDF
from pdf_report import generate_site_pdf
out = generate_site_pdf(
    store_name="方庄店", address="北京方庄", score=78,
    monthly_revenue=380000, payback_months=14, population=125000,
    facility_data={"商场": 5, "地铁": 2},
    risks=["自相竞争"], suggestions=["签 5 年租约"],
    output_path="/tmp/report.pdf",
)

# 2. 客流 PDF
from pdf_report import generate_footfall_pdf
from footfall_forecast import predict_week
results = predict_week(280, "2026-06-15")
out = generate_footfall_pdf("A001", "北京方庄", results, "/tmp/footfall.pdf")

# 3. CLI
python pdf_report.py --demo --output test.pdf     # 客流周报
python pdf_report.py --type site --data data.json --output site.pdf

依赖：

pip install fpdf2 pypdf    # fpdf2 生成 + pypdf 验证
# 中文字体：系统需装 wqy-zenhei（/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc）
# 降级：没字体也能跑，中文变方块但不崩

19.11 详细文档

→ 完整功能说明/参数详解/常见场景：references/geo-analysis.md
→ 4 个实战案例（数据+背景+决策+结果+教训）：references/cases.md
→ API 速查（真实函数名/参数格式/返回 key）：references/api-quickref.md ⚠️ 链式调用前必看

19.12 链式调用 30 秒探测术

调用本 Skill 任何 from scripts.xxx import ... 之前，先用三件套确认真实 API：

# 1. 列真实函数名（防 score_candidate 这种乌龙）
grep -E "^def [a-z]" /home/ubuntu/.hermes/skills/store-network-planner/scripts/xxx.py

# 2. dump 真实返回结构（防 tasks vs dispatches 这种乌龙）
python3 -c "
import sys; sys.path.insert(0, '/home/ubuntu/.hermes/skills/store-network-planner/scripts')
from xxx import func; import json
print(json.dumps(func(real_args), ensure_ascii=False, indent=2)[:1500])
"

# 3. 看函数签名
grep -A 20 "def target_func" /home/ubuntu/.hermes/skills/store-network-planner/scripts/xxx.py

完整战例 + 通用原则见 systematic-debugging/references/api-surfacing.md。

19.13 V1.3.6 踩坑防御（必读 · 新增 5 个坑）

本节专门记录 V1.3.5 → V1.3.6 期间真实踩中的 5 个坑。任何修改 V1.3.6 新模块的代码前必看。

通用防御原则（来自这 5 个坑）：

1. 不要用 **dict 完整解包到函数，除非 dict 字段名 100% 对齐 — 静默失败最致命。
2. CLI 程序：INFO 必须走 stderr，stdout 只输出结构化数据（JSON/CSV/纯数据）。
3. PDF / 图片 / 报表类库：先用一个最小 demo 跑通再扩展，不要相信官方文档的"应该能工作"。
4. 跨语言字段名：中英字段兼容要在 API 入口做 fallback，不要在内部硬编码。
5. 外部依赖：网络、Key、权限三态降级。Agent 场景用户看不到 stack trace。

19.14 端到端回归测试（V1.3.6 新增）

全栈测试覆盖 11 章 / 25 个用例（每次发布前必跑）：

测试模板（/tmp/full_e2e_test.py 模式）：用 try/except 包每个用例，FAIL 时记录 traceback.format_exc()[:500]，最后输出 pass/fail/total 计数 + 健康度评分。

当前状态：25/25 通过（健康度 100/100）。