monthly-ops-report · 运营月报生成器

将结构化运营数据一键生成统一视觉、可直接嵌入邮件的高清 PNG 月报素材（封面 + 九大内容模块 + 页脚 + 完整长图）。本 skill 是业务级模板层，封装了运营月报的完整模块结构、文案提示词与接口契约；底层图片渲染复用 html-to-email-images skill（纯 SVG 图表 + playwright 截图）。

定位：任何产品/游戏做同类月报时，只需按数据契约填 data.json + 传入产品名/周期，即可产出整份月报，无需从零设计模块与配色。

When to use

用户要求生成"运营月报""月度报告""XX 产品月报图片素材"，且希望可嵌入邮件的纯图片形式（非 SPA/交互网页）。
用户要求复用本月报模板给其他产品（换产品名、换数据、换周期）。
用户要求单独调用某个模块（如只做满意度分析、只做回流数据分析）或梳理模块提示词。

输入参数（Input Parameters）

调用本 skill 时，按以下参数组织输入。参数以「命名 = 说明（是否必填）」列出：

| 参数名 | 说明 | 必填 | 示例 | |--------|------|------|------| | product_name | 产品/游戏名称，用于封面标题与文案 | 是 | [您的产品名] | | report_title | 报告主标题（默认 {period}运营月报） | 否 | 2026年6月份运营月报 | | period | 统计周期（YYYY-MM 或起止日期） | 是 | 2026-06 / 2026年6月1日—6月30日 | | team_name | 出品团队署名 | 否 | [您的团队] | | data_source | 数据来源文件清单（回流/聊天/满意度/匹配率等） | 是 | 见「数据契约」 | | modules | 要生成的模块编号列表，缺省=全部（00–08） | 否 | ["00","01","02","05"] | | theme | 视觉主题，默认 sunset（末世日落） | 否 | sunset / tech / fresh | | banner_image | 封面海报图路径（16:9 优先），无则用纯色封面 | 否 | banner.jpg | | moments_images | 朋友圈配图目录（模块07用） | 否 | weixin_moments/ | | output_dir | 输出目录，默认 email_images/ | 否 | email_images/ |

输出格式规范（Output Format）

输出目录（默认 email_images/）下 N+2 张 PNG：
- 00_封面头图.png … 08_页脚签名.png：各模块单图，640px 宽 · deviceScaleFactor 2（实际 1280px）· 可自定义配色。
- 99_完整长图.png：所有已启用模块纵向拼接的整份长图，用于整体预览/一图到底嵌入。
命名规范：{序号2位}_{模块中文名}.png，序号即模块编号，保证排序与拼接顺序一致。
所有图可直接拖入 Outlook/QQ/网易/Foxmail 邮件正文，无需外链、无需 JS。

模块地图（Module Map）

| 编号 | 模块 | 核心内容 | 数据键 | 提示词 | |------|------|----------|--------|--------| | 00 | 封面头图 | 海报满幅 + 主标题 + 周期署名 | meta | P0 | | 01 | 项目概述 | 一段话总结 + 整体核心 KPI 卡 | mod1/派生 | P1 | | 02 | 用户维系与匹配率 | 分层维系人数趋势、匹配率趋势(70-100%)、留存对比 | mod2 | P2 | | 03 | 服务数据概览 | 分层消息量、每日趋势、时段分布、峰值 | mod3 | P3 | | 04 | 反馈问题 TOP10 | 问题占比表 + 环比变化 | mod4 | P4 | | 05 | 用户满意度分析 | 分层满意度、典型不满意反馈（隐藏无样本层） | mod5 | P5 | | 06 | 回流数据分析 | 7天/30天回流率趋势、触达对比、付费金额 | mod6 | P6 | | 07 | 社交推广内容 | 发布概况 + 内容模块(配图挪进卡片右侧) | mod7 | P7 | | 08 | 页脚签名 | 团队署名 + 生成时间 | meta | — |

每个模块的独立提示词（角色/输入格式/输出结构/风格长度约束）见 @references/module-prompts.md，解耦设计、可单独或组合调用。

接口调用规范

完整的请求方式、参数命名、数据契约、返回结构、错误码见 @references/api-spec.md。速览：

请求方式：函数式调用 generate_monthly_report(product_name, period, data_source, modules=None, ...)，或直接把参数写进 data.json 的 meta 段后运行构建脚本。
返回结构：{ code, message, data: { output_dir, images:[...], full_image, modules_rendered:[...] } }。
错误码：0 成功；1001 缺必填参数；1002 data.json 结构不合法；2001 图表渲染失败；2002 截图失败(chromium)；3001 模块编号非法。

Steps

收集输入：确认 product_name、period、data_source；缺失必填项 → 报错码 1001 并向用户询问。
组织数据契约：把各数据源分析结果写入 data.json，字段严格对齐 @references/api-spec.md；meta 写入产品名/标题/周期/团队/时间。
写 build 脚本：复用 html-to-email-images 骨架（@scripts/build_report.py 已封装全量 SVG 图表与组件），传入 data.json 即可。配色/组件/图表函数全部内置。
渲染截图：运行构建脚本 → playwright 逐块截图(deviceScaleFactor:2) + 完整长图。
文案生成（可选）：需 AI 生成/润色某模块时，取 @references/module-prompts.md 对应提示词（P0–P7），喂入该模块数据，产出符合约束的文案后回填。
复查：Read 关键模块 PNG，确认数值/标签/配色统一、无样本层已隐藏。
增量改单块：只改一个模块时走 html-to-email-images 增量套路（单块 build → 截该块 → PIL 重合长图），不全量重跑。
清理 + 交付：删临时脚本，present_files 展示（完整长图放最前）。

扩展指南

新增产品：复制 data.json 模板，改 meta + 各模块数据即可；配色/结构不动。若某模块无数据，在 modules 里剔除该编号。
新增模块：① 在 api-spec.md 增加数据键定义；② 在 build_report.py 新增 section_XX() 函数（复用现成组件）；③ 在 module-prompts.md 增加提示词 PX；④ 加入模块地图。模块之间完全解耦。
换主题：改 build 脚本顶部配色常量（当前 sunset 末世日落；可扩展 tech/fresh 等）。

Pitfalls

本 skill 是业务模板层，图片渲染细节（chromium 路径、数字开头 id 用属性选择器、ymin 区间、标签避让、PIL 重合长图）全部沿用 html-to-email-images 的 Pitfalls。
无样本层隐藏：模块05/02 里若某分层样本=0，必须过滤，不渲染空行/空点。
小数精度：满意度均分传 dec=2；回流率/占比 {:.1f}；金额千分位。
国内配色惯例：涨=红，跌=绿。
提示词解耦：调单模块提示词时只喂该模块数据，不塞整份 data.json。

Verification

逐张 Read 关键模块 PNG，目视确认数值/标签/配色/隐藏逻辑。
ls -la {output_dir}/*.png 确认张数与体积正常。
返回结构 code==0 且 images 数量 = 启用模块数 + 1（长图）。

@references/module-prompts.md @references/api-spec.md @references/data-schema.example.json @scripts/build_report.py