竞品酒店价格跟踪与定价分析

概述

本技能编排了一个三阶段流程：

数据获取 — 执行用户的Python脚本拉取竞品酒店的价格数据（包含未来7天的价格，和历史采集的价格）。
价格分析 — 运行 scripts/analyze_prices.py 计算竞争差距、历史趋势、RevPAR估算和基于规则的定价建议。
Excel报告 — 运行 scripts/generate_report.py 生成格式精美的多工作表 .xlsx 工作簿，包含颜色编码的建议。

工作流程

步骤1 — 运行用户的数据获取脚本

获取数据所需的参数（tableId、fields、where、sort、offset、limit），参数使用风格为Nocodb的 V1 API参数风格，说明如下：

python  ~/.workbuddy/skills/hotel-price-analyst/scripts/list_supertable_records.py
# 预期输出：JSON或CSV文件（例如 price_data.json）

tableId: 必填，如无特殊说明默认使用 4367cbf5f1faec4227eb005dded65cf9。
fields: 非必填，不填则返回所有字段，要获取的字段，逗号分隔。如："当日价格、原价"
where: 过滤条件，用法如 "(Id,eq,1)~and(入住日期,gte,exactDate,2026-04-20)"
sort: 排序字段，如 "[{"field": "下载时间", "direction": "desc"}]"。
offset: 偏移量，从0开始。如：0
limit: 每页数量，默认10。如：1000

运行后的关键检查：

确认输出文件price_data.json存在且非空。
如果脚本失败，显示错误并请用户修复脚本后再继续。
如果输出文件路径不标准，请用户确认。

步骤2 — 准备工作

理解用户的意图，结合数据架构，确定分析思路
优化分析脚本确保与用户意图一致，数据架构一致
确定分析时间范围（如：最近7天）
确定分析房间范围（如：所有酒店、所有房型）
确定自营酒店，用户自助选择哪个酒店是自营酒店
环境准备

pip install pandas -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install openpyxl -i https://pypi.tuna.tsinghua.edu.cn/simple

步骤3 — 运行价格分析

~/.workbuddy/binaries/python/envs/default/bin/python \
  ~/.workbuddy/skills/hotel-price-analyst/scripts/analyze_prices.py \
  --input  <path/to/price_data.json_or_csv> \
  --hotel  "<own hotel name>" \
  --output analysis_result.json \
  --rooms  <total_room_count>          # 可选，默认100
  --threshold-high 10.0                # 可选：高于竞品平均% → 建议降价
  --threshold-low  -10.0               # 可选：低于竞品平均% → 建议涨价

脚本输出 analysis_result.json，包含：

competitive_gap — 自身价格与竞品平均价格对比（按日期/房型）
historical_trend — 周平均价格趋势
revpar — 各房型的RevPAR和估算收入
recommendations — 涨价/降价/保持的操作建议列表及理由

步骤4 — 生成Excel报告

注意：如果字段名称不一样则自动映射

~/.workbuddy/binaries/python/envs/default/bin/python \
  ~/.workbuddy/skills/hotel-price-analyst/scripts/generate_report.py \
  --input  analysis_result.json \
  --output 酒店调价报告_$(date +%Y%m%d).xlsx

生成的工作簿包含五个工作表： | 工作表 | 内容 | |-------|---------| | 摘要 | 报告元数据和操作计数摘要 | | 竞对比价 | 日期×房型价格差距表，颜色编码 | | 历史价格趋势 | 周平均价格及可选折线图 | | 收益RevPAR | 各房型的RevPAR、入住率和估算收入 | | 调价建议 | 完整建议列表：涨价（红色）/降价（绿色）/保持（金色） |

步骤5 — 展示结果

调用 present_files 并传入 .xlsx 文件路径，以便用户直接下载或预览。

数据架构参考

加载 references/data_schema.md 获取：

必填和可选列定义
JSON和CSV示例
用户脚本集成约定（如何构建数据获取脚本的输出）

最小必填列为：date、hotel_name、room_type、price、platform。

自定义提示

调整阈值： 修改 --threshold-high / --threshold-low 以调整"涨价/降价"建议的触发条件（默认±10%）。
房间数量： 传入 --rooms <n> 以在RevPAR工作表中获得准确的总收入估算。
入住率： 如果用户数据包含 occupancy_rate 列（0–1），将直接使用；否则假设为0.75。
多平台： 分析会自动对各平台价格取平均值；无需特殊处理。

错误处理

| 症状 | 可能原因 | 修复方法 | |---------|--------------|-----| | Hotel 'X' not found | --hotel 值与数据不匹配 | 检查数据文件中的拼写 | | Missing recommended columns | 数据架构不匹配 | 阅读 references/data_schema.md 并对齐脚本输出 | | pandas not found | 依赖未安装 | 运行步骤2的安装命令 | | 建议列表为空 | 所有差距均在±10%以内 | 降低阈值或检查数据完整性 |

资源

| 路径 | 用途 | |------|---------| | scripts/list_supertable_records.py | 数据获取脚本 — 获取价格数据 | | scripts/analyze_prices.py | 价格分析引擎 — 竞争差距、趋势、RevPAR、建议 | | scripts/generate_report.py | Excel报告生成器 — 5工作表颜色编码工作簿 | | references/data_schema.md | 用户脚本与分析管道之间的数据契约 |