# VIP Report Skill Bundle

这是一套围绕 VIP 月报模板的本地 skill 骨架。

已落地内容：

- 总 skill：`vip-report`
- 子 skill：
  - `overview`
  - `data-sync`
  - `presentation`
- 基础脚本：
  - 模板 manifest 提取
  - PowerPoint COM shape inventory
  - 基线渲染
  - `pptx` 包级比对

当前生成目标不是“重新画一份 PPT”，而是：

- 保留原始模板
- 只替换模板中的现有内容
- 每次生成都和基准模板做对比

## 迁移到新电脑 Checklist

1. 准备运行环境（Windows）
- 安装 `Python 3.10+`（建议 3.11）。
- 安装 `Node.js 18+`，确保命令行可用 `npx`。
- 安装 `Microsoft PowerPoint`（`render.mode=com` 依赖 COM 自动化）。
- 确认网络可访问 `http://tableau.charleskeith.cn`。

2. 复制目录与文件
- 复制 skill 目录：`C:\Users\<你的用户名>\.codex\skills\vip-report`。
- 复制配置目录：`C:\Users\<你的用户名>\.codex\vip-report`。
- 准备模板文件：`Report.pptx`（路径可自定义，需写入 `config.yaml`）。
- 准备来源映射：`slide-source-map.yaml`（路径需写入 `config.yaml`）。

3. 修改配置（必须）
- 打开 `C:\Users\<你的用户名>\.codex\vip-report\config.yaml`。
- 使用 `config.yaml.example` 作为参考，至少检查：
- `tableau.username` / `tableau.password`
- `mysql.username` / `mysql.password`（若该页用到数据库）
- `paths.template_pptx`
- `paths.slide_source_map`
- `paths.workdir`
- `render.mode`（默认 `com`）
- `report.month_cn` / `report.year` / `report.compare_year`（按当期月报设置）

4. 安装 Python 依赖（首次）
- 执行：`python -m pip install pillow pyyaml`

5. 最小化验证（先只跑 S02）
- 执行：
- `powershell -ExecutionPolicy Bypass -File C:\Users\<你的用户名>\.codex\skills\vip-report\bin\vip-report-monthly-sales-sync.ps1 -ConfigPath C:\Users\<你的用户名>\.codex\vip-report\config.yaml -Slides S02 -ReportMonth 二月 -ReportYear 2026 -CompareYear 2025 -Render`
- 产物应生成在 `config.yaml -> paths.workdir` 指向目录下。

6. 常见问题
- 报错 `PowerPoint.Application` 创建失败：通常是未安装 Office 或权限不足。
- 报错 `npx` 不存在：Node.js 未安装或 PATH 未生效。
- Tableau 偶发 `get_workbook` 空对象：属于页面初始化时序问题，脚本已内置重试；仍失败时直接重跑同命令一次。
