dsh-hr-payroll-mcp

Readme

# 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