销售预测 Pro 技能

快速开始

# 首次使用：复制配置模板
cp ~/.workbuddy/skills/sales-forecast-pro/config/projects/template.yaml \
   ~/.workbuddy/skills/sales-forecast-pro/config/projects/我的项目.yaml

# 编辑配置文件（改data_source里的列名）
# 然后运行预测
python ~/.workbuddy/skills/sales-forecast-pro/run.py --project 我的项目 --months 3

项目配置（template.yaml 说明）

project:
  name: "项目显示名称"
  forecast_lead: 2          # 提前N个月预测（5月→预测8月，填2）

data_source:
  file: "销售数据.xlsx"       # 支持相对路径（相对于配置文件目录）
  sheet: "销售底表"           # sheet名，不填则读第一个
  sku_col: "SKU"            # SKU列名
  date_col: "时间"            # 日期列名（支持202312或2023-12格式）
  sales_col: "成交商品件数"   # 预测目标列（销量）
  amount_col: "成交金额"      # 可选：同时预测金额

factors:
  file: "影响因子.xlsx"        # 影响因子维护文件（可选）
  sheet_per_sku: true         # true=每个SKU一个sheet；false=所有SKU在一个sheet
  sku_col: "SKU"            # sheet_per_sku=false时生效
  date_row: 6                # 日期所在行（1-indexed，从1开始数）
  factor_start_row: 7        # 因子开始行
  auto_predict:               # 自动预判因子配置
    - name: "节假日/大促"
      method: "holiday_calendar"
      params:
        calendar: "CN"       # 中国节假日
    - name: "季节性"
      method: "month_auto"
      params:
        peak_months: [6,7,8]  # 旺季月份，填1则该月因子=1

output:
  output_dir: "./output"      # 输出目录（相对于工作目录）
  output_file: "预测结果_{date}.xlsx"
  sheets:
    - name: "预测结果"
    - name: "因子权重"
    - name: "模型评估"
    - name: "预测解释"

影响因子配置指南

现有22个因子（你的文件已有）

| 代码 | 因子名 | 值含义 | 建议 | |------|---------|--------|------| | a | 促销 | 1=有促销 | 手动维护 | | b | 定价策略 | 1=降价 | 手动维护 | | c | 广告活动 | 1=有投放 | 手动维护 | | d | 新品发布 | 1=有新品 | 手动维护 | | e | 产品变更 | 1=有变更 | 手动维护 | | f | 渠道促销 | 1=有渠道活动 | 手动维护 | | g | 客户业务计划 | 1=有计划 | 手动维护 | | h | 客户活动 | 1=有活动 | 手动维护 | | i | 宏观经济 | -1/0/1 | 手动维护 | | j | 行业趋势 | -1/0/1 | 手动维护 | | k | 竞争对手行动 | -1=竞品强势 | 手动维护 | | l | 季节性 | 1=旺季 | 自动预判（见上）| | m | 节假日/大促 | 1=有大促 | 自动预判 | | n | 地区差异 | 1=重点地区 | 手动维护 | | o | 天气 | -1/0/1 | 手动维护 | | p | 人工干预 | 手动调整值 | 手动维护 | | q | 直播/达播 | 1=有直播 | 手动维护 | | r | 平台销售订单 | -1/0/1 | 手动维护 | | s | 缺货 | -1=缺货 | 手动维护 | | t | 投放费用 | 1=高投放 | 手动维护 | | u | 行业补贴 | 1=有补贴 | 手动维护 | | v | 明星代言 | 1=有代言 | 手动维护 |

建议补充的因子（可在Excel里追加行 w~z）

| 代码 | 因子名 | 值含义 | 数据来源 | |------|---------|--------|----------| | w | 评价评分变化 | -1/0/+1 | 自动：对比上月评分 | | x | 价格竞争力 | -1/0/+1 | 自动：对比竞品均价 | | y | 库存可售天数 | -1/0/+1 | 手动或自动（ERP接入）| | z | 达播场次 | 数值（场次） | 手动维护 | | aa | 内容种草指数 | 数值 | 手动维护 | | ab | 会员复购率 | 数值% | 自动（CRM数据）| | ac | 流量成本变化 | -1/0/+1 | 手动维护 |

如何在Excel里添加新因子：

在影响因子文件的因子列表末尾（当前是行27 v 明星代言）下方插入新行
第一列填因子代码（w/aa/ab...），第二列填因子名
对应月份列填 -1/0/1 或具体数值
修改配置文件 factors.factor_start_row 不需要改（自动识别）

运行方式

# 基本用法：预测未来3个月
python run.py --project sfxq --months 3

# 指定历史数据最少月份数（默认24）
python run.py --project sfxq --months 3 --min-history 24

# 指定输出文件路径
python run.py --project sfxq --output 我的预测结果.xlsx

# 只生成因子权重，不跑预测（调试用）
python run.py --project sfxq --only-weights

# 详细日志
python run.py --project sfxq --verbose

输出Excel说明

Sheet1：预测结果

| SKU | 商品名称 | 预测月份 | 基线预测(件) | 调整后预测(件) | 置信下限 | 置信上限 | 异常标注 | |------|----------|----------|---------------|----------------|----------|----------|----------|

Sheet2：因子权重

每个SKU的22个因子权重系数（模型学习结果），正值=正向影响，负值=负向影响

Sheet3：模型评估

历史拟合MAPE、各SKU准确率、特征重要性排序

Sheet4：预测解释

自然语言解释每个SKU每个月的预测原因，例如：

"6088552 2026年8月预测3,456件（较上月+12%），主要驱动：节假日/大促(+8%)、广告活动(+5%)；风险因子：竞争对手行动(-2%)"

依赖安装

pip install pandas openpyxl xgboost scikit-learn matplotlib seaborn
# 可选：Prophet（时间序列基线）
pip install prophet

新增项目快捷流程

cp template.yaml 新项目名.yaml
打开 新项目名.yaml，修改 data_source 部分：
- file: 销售数据Excel路径
- sku_col: SKU列名（区分大小写）
- date_col: 日期列名
- sales_col: 销量列名
（可选）修改 factors.file 指向影响因子Excel
python run.py --project 新项目名 --months 3
查看 output/预测结果_日期.xlsx

常见问题

Q: 新SKU只有6个月数据能预测吗？ A: 最少需要12个月。不足时用同类SKU的因子权重迁移，准确率会低一些。建议24个月以上最稳定。

Q: 影响因子Excel里未来月份还没填怎么办？ A: 技能会自动用 auto_predict 配置预判节假日/大促，其他因子默认为0（无影响）。建议每月更新影响因子文件。

Q: 预测结果不准怎么办？ A: 检查：①历史数据是否有异常值（缺货/大促月份）②影响因子是否填全③尝试调整 forecast_lead（提前月数）。可在配置里手动调整因子权重基准值。

模板与配置

Excel因子维护模板

模板文件：templates/因子维护模板.xlsx

使用方法：

复制模板到工作目录：cp templates/因子维护模板.xlsx ~/影响因子_项目名.xlsx
打开Excel，复制sheet（右键sheet标签 → 移动或复制）→ 重命名为SKU编码
在C7:N28区域手动填 -1/0/1：
- -1 = 负向影响（抑制销售）
- 0 = 无影响
- 1 = 正向影响（促进销售）
保存后在yaml里配置 factors.file: "影响因子_项目名.xlsx"

自动预判的因子（无需手动填）：

m. 节假日/大促：技能自动识别中国法定节假日和电商大促
l. 季节性：根据月份自动填（6-8月=1，其他=0）

项目配置模板

模板文件：config/projects/template.yaml

新建项目：

cp config/projects/template.yaml config/projects/新项目名.yaml
# 编辑新yaml，改 data_source 和 factors 路径
python run.py --project 新项目名 --months 3

完整使用说明

详细使用说明见 README.md（同目录下），包含：

快速开始（5分钟上手）
第1步：准备销售数据Excel
第2步：维护影响因子Excel（手动调整）
第3步：配置yaml（复制改参数）
第4步：运行预测
第5步：解读输出Excel
高级用法（新增项目、调整因子列表、调整月份范围）
常见问题解答

文件结构

sales-forecast-pro/
├── SKILL.md              # 技能描述（AI触发用）
├── README.md             # 使用说明（用户手册）✅
├── run.py                # 主入口
├── config/
│   ├── projects/
│   │   ├── template.yaml      # 配置模板（复制改参数）✅
│   │   └── sfxq.yaml        # 丝芙格芮项目配置
│   └── factors.yaml          # 因子定义（可选）
├── core/
│   ├── parse.py         # 数据解析
│   ├── factors.py       # 因子管理
│   ├── model.py        # 预测引擎
│   ├── explain.py      # 解释生成
│   └── output.py      # Excel输出
├── templates/
│   └── 因子维护模板.xlsx    # Excel模板（手动填因子）✅
└── output/                 # 预测结果输出目录

更新记录

2026-05-20：初始版本，支持丝芙格芮项目
- ✅ 数据解析：支持202312和2023-12日期格式
- ✅ 因子管理：支持手动维护+自动预判（节假日/季节性）
- ✅ 预测引擎：XGBoost回归 + 时间序列基线
- ✅ 输出：4个Sheet（预测结果/因子权重/模型评估/预测解释）
- ✅ 模板：Excel因子维护模板 + yaml配置模板
- ✅ 文档：README.md 完整使用说明