helibeiqi/dsh-hr-payroll-mcp

dsh-hr-payroll-mcp

通用 HR 算薪 MCP 服务（零依赖 Node ESM，本地优先，PII 不出机）。

要解决的问题

各公司 HR 数据源表格格式不同（社保表、公积金表、绩效表…）、算薪规则与逻辑也不同。
本插件用三层架构把“差异”外部化，让引擎保持公司无关：

1. 法定计算引擎（公司无关） — 社保/公积金/个税均为全国或市级法定标准，算法全国统一，是本插件的护城河/知识资产。
2. Import Adapter（通用表头适配） — 列名同义词推断 + 用户确认映射 + 类型校验 + 缺失告警。各企业表头差异在此消解，不进代码。
3. Company Profile（企业配置） — 属地/公积金比例/薪资拆分比/免税项字典/四舍五入/专项附加来源。各企业差异在此配置。

唯一真正需要企业自定的只有绩效逻辑：用受限表达式安全求值器（仅 + - * / % ( ) 与变量，非任意 eval）表达，或查表。既灵活又不会执行恶意代码。

差异化（诚实定位）

- 纵向 HR SaaS（薪人薪事/易路/钉钉智能人事等）确实存在，但它们要求 PII 上传云端。本插件完全本地计算，PII 不出机 —— 对数据安全敏感的 HR、需离线审计/复核、或想把算薪接入本地 AI 工作流的场景是空白。
- 开源 payroll 库多为某国税法特化（如美国 payroll 库），中国社保/公积金/个税累计预扣法 + 按城市比例 + 通用表头适配 + MCP stdio 可驱动的组合，公开仓库中基本空缺。
- 与 dsh 生态的关系：作为本地数据/计算层，被 dsh agent 调用，配合 dsh-cn-fixedincome-mcp 等形成“本地优先”工具链。

工具清单（9 个）

| 工具 | 作用 |
|---|---|
| import_payroll_table | 表头适配：推断映射 + 置信度 + 未匹配/缺失告警 + 样例归一化 |
| load_company_profile / save_company_profile | 企业配置读写（仅存本机） |
| calc_social_insurance | 五险一金：基数 clamps 上下限，按险种可单独指定缴费基数，单位/个人分项；工伤按 injury_rate（仅单位）计入；可输出公司总人力成本 |
| calc_iit | 个税累计预扣法：本期税额 + 税率 |
| compute_payroll | 算薪编排：拆分+绩效→应发→社保→个税→实发，累计 YTD；并输出 company_cost（公司总人力成本 = 应发 + 单位社保 + 单位公积金 + 单位工伤） |
| validate_payroll | 校验：应发/实发重组一致性、非负、税逻辑 |
| emit_payslip | 导出工资条（CSV/JSON） |
| refresh_statutory | 参数库版本/覆盖城市（年度刷新提示） |

部署

1. 安装（复制到本机）：C:\Users\helib\dsh-hr-payroll-mcp\
2. 在 dsh cordis.patch.yml 注入 mcp server（见仓库 cordis.patch.yml）。
3. 注意：cordis.patch.yml 中的 args/cwd 写的是作者本机绝对路径，部署到你的机器需改成对应路径；或设置环境变量 PAYROLL_STATUTORY / PAYROLL_SYNONYMS / PAYROLL_PROFILE 指向你的文件。
4. 命令 !!js process.env.QUANT_MCP_NODE || process.execPath 免疫 Node 版本目录漂移。

重要边界（免责）

- 参数库需年度刷新：社保/公积金比例与基数上下限每年由各地官方调整，data/statutory.json 当前为 2026 年度参考值（version 2026-ref，覆盖 12 城：8 城已按 2026 官方通告更新，4 城待发布暂沿用 2025），使用前务必以属地当年官方文件为准。本插件仅供算法演示与离线计算，责任自负。
- 工伤保险特殊说明：工伤仅单位缴纳，比例按行业风险一类~八类（约 0.2%~1.9%）由属地经办机构核定。它不进个人工资，但计入公司总人力成本——因此本插件不把它放在城市参数库，而是统一通过 Company Profile 的 injury_rate 配置（calc_social_insurance / compute_payroll 均接受该参数）；compute_payroll 还会在 company_cost 中给出公司总人力成本（应发 + 单位社保 + 单位公积金 + 单位工伤）。
- 医保基数可能与养老不同：深圳、广州、杭州等城市的职工医保（含生育）缴费基数上下限与养老/失业不同，已在 statutory.json 内按险种单独标注（base_floor/base_cap），引擎据此分项 clamps。
- 2026 费率与执行日备注：广州/深圳 2025 年度医保单位费率含阶段性降费（深圳 5%、广州 5.35%），2026 年度已恢复至常规水平（深圳 6%、广州 6%+生育 0.85%）；杭州基数分上下半年（1-6 月 4986-25299 / 7-12 月 5346-26730），本库按下半年现行值收录；天津 2026 基数执行日为 9 月 1 日（非 7 月）；西安职工医保基数与养老基数分家（5132-25660 vs 4650-23250）。详细见 statutory.json 各城 _2026 字段。
- 绩效逻辑由用户自供：引擎只负责法定部分，绩效公式/查表由企业自行提供并确认。
- 未收录城市请用 refresh_statutory 扩展或选用已收录城市（当前：北京/上海/深圳/广州/杭州/成都/武汉/天津/重庆/苏州/南京/西安）。

覆盖城市（12）

- 已更新至 2026-ref（8）：北京 · 上海 · 天津 · 成都 · 杭州 · 深圳 · 广州 · 西安
- 待发布，暂沿用 2025-ref（4）：武汉 · 南京 · 苏州 · 重庆
2026 数据来源：北京市人社局/医保局/税务局 2026.8.21 + 北京公积金中心 2026.8.24（京房公积金管委会办〔2026〕6号）；上海市人社局 2026.8.18 + 上海公积金管委会 2026.8.18；天津市人社局/医保局/税务局 2026.8.21（执行日 2026-09-01）；川人社办发〔2025〕39号；浙人社发〔2025〕52号 + 杭州市医保局 2025.12.23（杭州分上下半年两套基数）；广东省人社厅（养老 2025.7-2026.6 周期）+ 深圳市医保局 2026 + 广州市医保局 2026.1（广深医保单位费率由阶段性降费恢复至常规水平）；西安市医保局（市医保发〔2026〕36号）+ 陕西省税务局 2026.7.30（西安医保基数与养老分家）。武汉/南京/苏州/重庆 2026 新基数待官方发布。具体以各地官方公告为准。

授权

MIT