经营分析图表（对外版）2.2

把用户数据直接渲染为可交付图表。默认使用统一入口，不要复制或重写整段绘图代码。

亮点一览

一句话:把 JSON / CSV 经营数据,一条命令渲染成汇报级、咨询风的中文图表。

| # | 亮点 | 说明 | |---|------|------| | 01 | 10 种咨询风图表 | 折线图、柱状图、横向条形图、漏斗图、双Y轴图、堆叠柱状图、气泡四象限图、瀑布图、热力图、饼/环图——趋势、对比、构成、转化、归因、密度全覆盖。 | | 02 | 端到端执行 | 从原始数据到成品 PNG/SVG 一步到位,自动产出有结论的标题,无需手动画图或写绘图代码。 | | 03 | 咨询风格元素 | 克制配色、参考线、强调色单点突出、数据标签智能标注、留白与版式——对齐麦肯锡 / BCG / 贝恩汇报审美。 | | 04 | 双输出模式 | 默认高清 PNG(16:9、dpi=200、约 3200×1800);需要可编辑矢量图时一键输出 SVG。 | | 05 | 自动数据清洗 | 数据校验、万 / 亿单位自动缩放、百分数解析、缺失值断点(不擅自填 0)——脏数据也能安全出图。 | | 06 | 可选功能(自然语言开启) | 配色主题(4 套) / 对比基准(基期并排) / 强调时段(周期底色带) / 参考线(均值·目标值虚线)——一句话说出即自动启用,无需记参数。 |

核心能力：4 种咨询风主题配色 × 10 种图表模板

4 种咨询风主题配色（--theme <键>，缺省 default）：

| 主题 | 键 | 风格 | 适用场景 | |------|-----|------|---------| | 默认蓝 | default | 通用稳重 | 常规经营分析、无特殊风格需求 | | 麦肯锡蓝 | mckinsey | 沉稳权威 | 高管汇报、Board Deck | | 波士顿绿 | bcg | 增长基调 | 增长主题、规模扩张叙事 | | 贝恩红 | bain | 醒目诊断 | 效率诊断、问题聚焦 |

10 种图表模板（chart_type）：line（折线）· bar（柱状）· horizontal_bar（横向条形/排名）· funnel（漏斗）· combo（双Y轴图）· stacked_bar（堆叠结构）· bubble（气泡四象限）· waterfall（瀑布归因）· heatmap（热力矩阵）· pie/donut（饼/环，克制使用）。

图型选择见下方图型路由，配色细节见配色主题。

可选功能（可自然语言要求AI）

以下能力默认不开启，用户用自然语言提出即可自动启用，无需记参数：

| 可选功能 | 用户可以这样说 | 效果 | |---------|--------------|------| | 配色主题 | "用麦肯锡蓝 / BCG绿 / 贝恩红" | 一键切换 4 套咨询风主题配色（默认蓝 / 麦肯锡蓝 / BCG绿 / 贝恩红），缺省用默认蓝。 | | 对比基准 | "有没有对照组 / 基期,并排对比一下" | 基期灰、本期主色并排,增速最高组用强调色,Action Title 自动算涨跌幅。 | | 强调时段 | "给某个周期加底色带阴影" | 在指定时间点画底色带 + 标注（如"3月大促"），聚焦关键周期。 | | 参考线 | "拉一条均值 / 目标值的虚线" | 叠加均值 / 目标值 / 自定义值参考线,可限定计算范围,自动标注数值。 |

工作流

Step 1：识别用户意图和数据结构

Step 2：按路由表选择图型

Step 3：整理 JSON 配置

将数据整理成JSON配置；字段说明见输入格式。

未提供Action Title时，让引擎从数据生成；不得编造标题数字。

Step 4：运行渲染

python3 scripts/render_chart.py --input <config.json> --output <chart.png>
# 咨询风主题（缺省 default）：--theme default|mckinsey|bcg|bain
# 可选指定中文字体（缺省 default 微软雅黑）：--font kaiti|simhei

Step 5：检查成品

打开成品检查中文、标签重叠、标题数字、图例和留白。发现问题时只调整配置或对应渲染器。

Step 6：交付

图表文件 + 一句话洞察。

图型路由

| 数据意图 | chart_type | |---|---| | 时间走势、1—5条序列 | line | | 最多7组分类对比 | bar | | 长标签、超过7组分类、排名 | horizontal_bar | | 3—7阶段转化链路 | funnel | | 规模与增速、两个量纲（双Y轴图） | combo | | 构成、渠道贡献、占比 | stacked_bar | | X/Y定位，气泡表示第三维度 | bubble | | 总量变动归因、增减项拆解（利润/销售额环比拆分、预算vs实际） | waterfall | | 行×列矩阵密度（时段×渠道、地域×品类等交叉热度） | heatmap | | 占比构成（不推荐，仅用户明确点名要饼图/环形图时才用） | pie / donut |

不要用双Y轴表达两个没有业务关系的指标。不要用气泡图承载超过30个点。

饼图克制原则（必读）：本 skill 默认不主动用饼图/环形图表达占比——咨询风规避饼图，占比首选 stacked_bar（堆叠结构）或 horizontal_bar（排名）。仅当用户指名道姓要"饼图/环形图/pie/donut"时才用 pie/donut；否则即便意图是占比，也走 stacked_bar。

参考线（Reference Line）

在配置 JSON 中添加 reference_line 字段即可启用。仅在用户明确要求时添加，不默认使用。

{
  "reference_line": {
    "type": "mean",
    "scope": [24, 25, 26, 27],
    "label": "日均23.20亿"
  }
}

| 参数 | 说明 | |------|------| | type | "mean" 自动算均值 / "target" 按给定值 / "custom" 任意值 | | value | type 为 target/custom 时必填 | | scope | 可选，限定计算均值的数据点索引列表 | | label | 参考线标注文字，缺省时自动生成 |

适用图表：折线、柱状、双Y轴图（combo）、堆叠柱（横线）；横向条形图（竖线）。漏斗和气泡不适用。

输出规则

默认 PNG 为固定 16:9、3200×1800、200 DPI、白底，适配飞书文档高清插图。
PNG 不使用 bbox_inches="tight" 改变画布尺寸；通过版式参数控制留白。
用户要求可编辑矢量图时输出SVG。
用户不指定主题时使用default；高管汇报可选mckinsey，增长主题可选bcg，效率诊断可选bain。
字体默认default（微软雅黑，缺失时退 Noto/苹方等系统黑体，跨平台安全）；另提供kaiti(楷体) 与 simhei(黑体) 两档。命令行传 --font <键> 或配置写 "font":"kaiti"；目标平台缺该字体时自动回退default，不报错。
Action Title必须是结论句，并与数据一致。
强调色单图只用于一个最重要对象。
Y轴默认从0开始；只有用户明确要求且说明原因时才截断。
折线点数不超过8时可全量标注；更多数据只标起止、极值和指定重点。
浅色背景使用深色标签，深色背景使用白色标签。
Source必须注明真实来源；示例数据使用Source: Mock Data。

对外示例脱敏

对外演示、模拟数据和内置样例中，金额指标统一使用“销售额”。
渠道名称统一使用“渠道A”、“渠道B”、“渠道C”等中性占位名。
不在对外示例中使用真实业务平台、内容形态、产品线或内部术语。
用户提供真实字段时可按原数据出图；仅对 Skill 自带的公开示例强制脱敏。

插入飞书文档（必读）

把本 skill 产出的图表插入飞书文档时，必须在插入步骤显式指定显示宽度 width≈800（正文满宽），height 留空自动按比例。

根因：本 skill 默认 dpi=200、输出像素 3000+，若插入时不传 width，飞书会按图片原始像素尺寸渲染，把高分辨率图缩成一小块、撑不开、无法铺满正文。
不得通过降低 dpi 来规避——那会让图重新变模糊，等于用一个 bug 换另一个。清晰度（dpi/像素）与显示大小（插入时的 width）是两件独立的事，正确解法是保持高 dpi + 插入时锁定 width。
对应到 lark-doc 的落地写法（实测，按此执行）：
- ⚠️ 当前 lark-cli 的 docs +media-insert 不支持 --width 参数，直接传会报 unknown flag: --width，无法控宽。
- 正确做法是两步法：
  1. 先用 docs +media-insert --doc <id> --file ./xxx.png --align center 上传图片，从返回 JSON 里拿到 file_token（注意：--file 只接受当前目录下的相对路径，绝对路径会被拒，先 cp 到工作目录）。
  2. 再用 docs +update --command block_insert_after --block-id <锚点> --content '<img src="<file_token>" width="800" height="<按比例算>" caption="..."/>' 复用同一个 file_token，通过 XML 的 width/height 锁定显示尺寸。height 按原图宽高比换算（例：原图 3170×1838，比例≈1.725，width=800 → height≈464）。
- 复用 file_token 可在同一文档插入多份不同宽度而不重复上传。

数据表格

本对外版不包含咨询风电子表格产出能力，仅生成图表（PNG/SVG）。如需数据表，请在飞书电子表格中自行整理。

详细视觉规则按需读取：

图型判断与表达：图型规则
配色语义：配色主题
版式与标注：排版规则
飞书画板：画板输出

样例输入

可运行的 JSON / CSV 样例位于 assets/sample-inputs/，用于快速试跑和修改，不作为规则文档加载。

python3 scripts/render_chart.py \
  --input assets/sample-inputs/line.json \
  --output outputs/line.png

输入原则

JSON是首选输入，最稳定。
CSV可直接读取，但必须指定--chart-type。
用户粘贴Markdown表格或少量自然语言数据时，先转换为JSON再渲染。
缺失值使用null或空单元格；折线图显示断点，不能擅自填0。
百分数建议使用普通数值，如31.2表示31.2%；带%文本也可解析。
输入已经以万或亿为单位时显式设置unit，避免再次缩放。

验证

修改脚本后运行：

python3 scripts/smoke_test.py

测试必须写入临时目录，不得删除用户的outputs/。任何图型失败时测试必须返回非零退出码。

依赖

依赖：matplotlib>=3.7、numpy>=1.24、Pillow>=10.0。缺少依赖时安装：

python3 -m pip install --user --break-system-packages "matplotlib>=3.7" "numpy>=1.24" "Pillow>=10.0"