工资表 → 每人一张工资条图片
把一个工资表 Excel 按行拆开，每人生成一张独立 PNG，图片顶部保留原表的大标题。
何时使用
- 用户上传/指向
.xlsx/.xlsm工资表，要求"按人名拆成工资条""每人一张图""批量出工资条截图" - 需要把内部工资表转成可单独发给员工的图片
- 计件工资、劳务费、提成结算表等同构需求
不适用：没有姓名列的汇总表；需要 PDF 或 Word 工资条（本技能只出 PNG）。
执行流程
1. 确认输入
拿到 Excel 的绝对路径。上下文里有附件路径就直接用；不明确时先问一句。
用户未指定输出目录时，输出到工作区目录下的 工资条图片/。
2. 确保依赖
脚本依赖 openpyxl + Pillow，用托管 Python 运行，缺依赖先装：
"C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe" -m pip install -q openpyxl pillow
该解释器不存在时，用 install_binary 安装 Python 后建 venv，遵循系统提示的运行时隔离要求。
3. 运行脚本
"<python>" "C:/Users/Administrator/.workbuddy/skills/payslip-image-generator/scripts/generate_payslips.py" "<工资表.xlsx>" --out "<输出目录>"
脚本自动完成：定位大标题 → 定位表头（支持双行表头、横向/纵向合并）→ 识别姓名列 → 跳过合计/小计行 → 两种版式批量出图 → 生成 index.html 预览页。
脚本 stdout 是 JSON 结构报告，必须读它再决定后续动作。 关键字段：
| 字段 | 含义 |
|---|---|
title |
提取到的大标题，核对是否与表格一致 |
name_column |
识别到的姓名列，明显不对时用 --name-col 重跑 |
value_columns |
提取到的明细列，用于判断漏列/多列 |
person_count / persons |
人数与名单，核对是否漏人或把表头当成人 |
warnings |
被跳过的行及原因 |
outputs |
两个版式的目录与张数 |
4. 自检
person_count与 Excel 实际行数是否吻合，差值只能来自合计行/空姓名行且应出现在warningsname_column是"序号"或金额列 → 必须--name-col "姓名"重跑title为兜底值"工资条" → 没找到标题行，用--title "..."指定- 用 Read 工具抽看 2 张图（金额量级不同的两个人），确认标题未截断、金额未错位、实发高亮正确
- 结果异常 → 按
references/troubleshooting.md调参重跑
5. 交付
present_files展示：至少 2 张示例图（卡片 + 横条）+ 两个index.html- 汇报：识别的标题、人数、输出目录、各版式张数、被跳过的行
- 提醒薪资敏感，别外发到公开渠道
版式说明
| 版式 | 目录 | 特征 | 适用 |
|---|---|---|---|
卡片竖排 card |
卡片竖排/ |
顶部色带大标题 + 姓名 + "项目：金额"逐行竖排 + 实发高亮 | 微信/手机单独发给员工 |
传统横条 strip |
横条式/ |
大标题 + 表头一行 + 数据一行，列多时自动分块折行 | 打印裁切、贴工资袋 |
默认两种都出。只要一种时传 --layout card 或 --layout strip。
排版规则：
- 标题优先单行；单行放不下在空格处均衡折两行；仍放不下才降字号
- 标题已含公司名/期间时副标题不重复；不含时自动补
公司 · 期间 - 金额千分位，整数不带小数，有小数保留两位
- 文本列（部门、岗位、工号等）原样输出
- 列名含"实发"自动高亮；含"合计/应发工资"的汇总行加分隔线强调
- 底部水印默认"薪资保密 · 请勿外传"，
--watermark ""关闭
参数速查
| 参数 | 说明 |
|---|---|
--out DIR |
输出目录，默认 <excel目录>/工资条图片 |
--sheet NAME |
指定工作表；默认第一张有数据的表 |
--layout card\|strip\|both |
版式，默认 both |
--title TEXT |
强制大标题 |
--company TEXT / --period TEXT |
覆盖自动提取的公司名 / 工资期间 |
--name-col TEXT |
姓名列名（模糊匹配），识别失败时必用 |
--cols-include REGEX |
只保留匹配列，如 "工资\|奖\|扣\|实发" |
--cols-exclude REGEX |
排除匹配列，如 "身份证\|银行卡\|备注" |
--sort-by-col TEXT |
按该列数值降序生成，如 实发工资 |
--watermark TEXT |
底部水印，"" 关闭 |
--scale INT |
渲染倍率，默认 2；追求清晰用 3 |
--no-index |
不生成 index.html |
常见需求对应做法
| 用户说法 | 做法 |
|---|---|
| "只要某些列" | --cols-include "基本工资\|绩效\|补贴\|社保\|个税\|实发" |
| "不要身份证/银行卡" | --cols-exclude "身份证\|银行卡\|账号" |
| "按金额从高到低" | --sort-by-col 实发工资 |
| "标题要改" | --title "XX公司2026年10月工资条" |
| "去掉保密提示" | --watermark "" |
| "图不够清晰" | --scale 3 |
| "多个月份多个 sheet" | 每个 sheet 各跑一次：--sheet "10月" --out .../10月 |
注意事项
- 表格必须"一行一人"。若"一人一列"横向排布，先转置或直接告知不支持。
- 脚本用
data_only=True读公式缓存值。公式列全空 → 让用户用 Excel 打开保存一次后重跑。 - 姓名重复时文件名加
_2/_3后缀，图片内姓名不变。 - 上百人时图片多，先抽 3 人确认版式，再放量。
