社保汇总工作簿
本 skill 用于把「各公司员工五险明细的源 .xlsx 数据」同步进一个具备最终版式的社保汇总模板，生成新的总社保表。
触发材料（最少只需要一项）：
- 必填：一个包含各公司员工五险明细的源 .xlsx 文件或目录（--data-folder）
- 选填：参考模板工作簿（--reference-workbook）。不传时，必须自动使用 skill 内置模板 assets/template.xlsx，无需向用户索取。
- 一个“在不改模板结构的前提下生成新的总社保表”的需求（如「总结 / 汇总 / 生成 / 整理 / 导出社保表」）
> ⚠️ 关键：只要用户给了社保数据文件/目录，就要直接运行脚本生成工作簿，而不是只做一份文字或数据层面的“总结报告”。内置模板就是默认参考表，不要因为没有收到显式参考表就停下来询问或退化为纯文本总结。
兼容约定：
- SKILL.md 仍然是 Codex / agent 侧的规则说明主文件。
- skill.yml 提供更接近 WorkBuddy 桌面端的展示、触发和输入元数据。
- 为避免重复维护，WorkBuddy 入口也直接指向 SKILL.md，不再额外拆出单独的 prompt.md。
工作流程
- 在处理工作簿逻辑前，先读取
references/field-rules.md。 - 使用参考表和数据目录运行
scripts/social_insurance_workbook.py。 - 默认行为是先复制参考表，再输出新文件，而不是直接修改原表。
- 参考表是结构唯一依据：分页名、合并单元格、小计/合计行、公式、格式和整体布局都必须保留。
- 只允许在"员工数据区起始行"和"小计行"之间同步员工行。
- 如果用户没有提供参照表，必须自动使用 skill 内置模板
assets/template.xlsx，不得因此向用户索要参考表，也不得退化为只做文字/数据总结。 脚本在不传--reference-workbook时会自动加载该内置模板。
运行命令
# 不传参照表（使用内置模板）
python scripts/social_insurance_workbook.py --data-folder <folder> [--output-path <output.xlsx>]
# 显式传参照表（覆盖内置模板）
python scripts/social_insurance_workbook.py --reference-workbook <template.xlsx> --data-folder <folder> [--output-path <output.xlsx>]
参数说明：
- --reference-workbook：可选，参考模板工作簿；不传时使用 skill 内置模板 assets/template.xlsx
- --data-folder：必填，源数据工作簿目录
- --output-path：可选，显式输出路径；如果不传，使用内置模板时输出到数据目录，传了参照表时输出到参照表同目录
触发即执行（核心行为）
本 skill 的默认动作就是「运行脚本生成带公式的社保汇总工作簿」。内置模板随时可用，不需要用户额外提供参照表，也不需要用户显式要求“用模板”。
- 用户说「总结 / 汇总 / 生成 / 整理 / 导出社保表」并附带社保数据文件或目录时 → 立即运行脚本（不传
--reference-workbook，脚本自动用内置模板）。 - 不要因为只收到一个数据文件、没收到参考表，就改去做纯文字/数据的总结报告——那属于未充分使用本 skill。
- 只有在用户明确要求用自己的参考表时，才传
--reference-workbook覆盖内置模板。 - 若用户只给了单个数据文件（不是目录），先把它放进一个临时目录再传给
--data-folder即可。
必须遵守的行为
- 最终结果里只保留“该分页对应数据表”里出现的员工。
- 如果某员工同时存在于数据表和参考表：
只更新五险金额列，保留参考表里的静态信息列。 - 对于匹配上的员工，参考表中从
一级部门到缴费基数的内容必须原样保留；
只能用数据表去替换五险金额列。 - 如果某员工出现在数据表里、但不在参考表里：
只能在小计上方插入一行，复制邻近员工行的样式和公式，再填写识别到的员工与五险列。 - 如果某员工仅出现在数据表、不在参考表中：
不得猜测或编造一级部门到缴费基数的内容；除非模板本身已有明确值可保留，否则保持为空。 - 如果某员工存在于参考表、但不在数据表中：
只能删除该员工行。 - 不要手工重写
小计、合计、审核、制表等行。 - 不要用源数据里的静态金额覆盖模板最后的汇总公式列。
错误示例
以下情况一律视为回归错误：
-
参考表用错。
错误示例：读取的是一个模板，却用另一个公式风格不同的工作簿来校验公式行为。
正确做法：传给--reference-workbook的那一份文件，才是唯一的公式和版式依据。 -
把模板公式改写成自己的公式模式。
错误示例：模板里是=SUM(J$4:INDEX(J:J,ROW()-1))，输出后变成=SUM(J4:J19)。
正确做法：保留模板原本的公式模式，只允许行号随着员工增删而移动。 -
共享公式在首列之后被改坏。
错误示例：科创的小计行J20正确，但K20及后续列被改成单独公式，或起始列引用错了。
正确做法：保留模板原有的 shared-formula XML 信息，让后续列继续属于同一组共享公式。 -
插入员工行后，小计/合计关系被破坏。
错误示例：鼎久管道多了一个员工，小计/合计整体下移后，结果开始直接汇总员工行，或引用错到前一行。
正确做法：小计行保留模板的小计公式模式，合计行保留模板的合计公式模式，两者都应作为整块随行号平移。 -
插入员工行后，员工行横向汇总公式被破坏。
错误示例：鼎久建设第23行还正确，但从插入出来的第24行开始，个人缴费金额汇总/单位缴费金额汇总指到了27、28或69行。
正确做法：每一名员工的最后汇总列都必须引用“该员工所在行”的五险列，不能引用到别的行。 -
误信
openpyxl自动翻译出来的员工行公式。
错误示例：复制邻近员工行后，直接相信Translator生成的公式一定正确。
正确做法：员工行最后汇总列的公式要按模板公式模式恢复，确保每一行都引用自己的行号。 -
丢失数组公式或稀疏公式行。
错误示例：生韵乐看起来“没公式了”，其实是因为该行本来就只有少数单元格挂公式节点，其他空白是设计的一部分。
正确做法：数组公式和稀疏公式单元格都必须按模板 XML 原样保留。 -
只填写个人部分，不填写单位部分。
错误示例：结果表里只写了个人缴费，单位缴费为空。
正确做法：模板存在的个人五险和单位五险金额列，都必须回填。 -
把匹配员工从
一级部门到缴费基数的列覆盖掉。
错误示例：某员工同时存在于参考表和数据表，但输出时把其一级部门到缴费基数的值清空、平移或重写了。
正确做法：匹配员工的这些基础列必须与参考表保持完全一致，只替换五险金额列。 -
给新增员工乱猜
一级部门到缴费基数。
错误示例：某员工只存在于数据表中，输出时却自动填了不相关的部门、公司或缴费基数。
正确做法：对参考表中不存在的新增员工，这些基础列应保持空白，除非模板自身已有明确默认值。 -
数据表里同名员工多行时没有累计。
错误示例：同一员工在源表中出现多行，最后只保留了最后一行金额。
正确做法：写入结果前，先把同名员工的所有源记录累计汇总。 -
映射过于死板，导致公司漏提。
错误示例：鼎久货运、鼎生物资，或文件名带(1)的文件，因为不是精确同名就被跳过。
正确做法：优先使用映射表，再在 Python 内部做文件名变体和分页别名归一。 -
只检查小计/合计，没有检查中间员工行。
错误示例：只看科创或鼎久建设的小计还在，就误以为整页正确；实际上中间员工行汇总列已经错了。
正确做法：要同时检查首个、中间、最后一个员工行的最后两列汇总公式，尤其是新增员工附近。 -
校验时写死行号。
错误示例：始终去看科创的J20，即使人数变化后小计已经挪到J28。
正确做法：先根据当前分页结构定位真实的小计行，再检查该位置上的公式。
分页映射规则
- 没有匹配到数据文件的分页直接跳过，保留模板原样，不报错。
- 映射分为三步，按优先级依次执行：
1. 精确文件名匹配：使用references/default-sheet-mapping.json中的默认映射
2. 别名子串匹配：使用references/sheet-aliases.json中的别名列表，对数据文件名的归一化 stem 做子串匹配
3. 员工名字匹配（回退机制）：当上述两步都无法匹配时，读取模板分页中的员工名字集合，与未匹配数据文件的员工名字集合做交叉比对。若重叠人数超过阈值（≥ max(2, 30%源数据人数)), 则将重叠最多的数据文件分配给该分页。这是最可靠的匹配方式，但仅在文件名/别名匹配失败后才启用，避免不必要的文件读取开销。 - 所有中文文件名、别名、表头匹配逻辑都应留在 Python 内部处理，不要依赖 shell 层文本匹配。
校验要求
在报告成功之前，至少完成以下校验：
- 运行 scripts/test_social_insurance_workbook.py
- 用真实输入运行主脚本
- 确认输出文件已生成，且原参考表未被修改
- 生成结果必须与“本次传入的参考表”对照检查，不能对着另一份样例表做判断
- 当公式保真度很重要时，要检查工作表 XML 中的 shared formulas / array formulas，而不是只看 openpyxl 展示出来的公式字符串
- 不仅要看小计/合计，还要检查首个、中间、最后一个员工行上的 个人缴费金额汇总 与 单位缴费金额汇总
- 要确认最后两列的小计值与页面上可见员工行求和结果一致，防止中间员工行公式漂移
- 校验时不要假设小计行号固定，必须先从工作表内容里动态定位
失败处理
出现以下情况时，应立即停止并给出明确错误：
- 某个有数据文件映射的参考分页缺少必要的员工列或五险列
- 输出路径无法写入；这时应改写到新文件名，而不是反复覆盖同一个被占用文件
- 未提供参照表且 skill 内置模板不存在
