工程质量保证金扣留与退还核对（免费版）

工程质量保证金（质保金/保修金）扣留与退还台账逐项核对，本期扣留金额 = 本期结算金额 × 扣留比例、保修期届满日 = 保修期起 + 保修期月数 − 1 日（含首日）、应退金额 = 累计扣留金额 − 保修期内扣减，逐行复算并做合计勾稽、重复结算单号与空缺检测，每条结论引用台账原文行号。触发词包括 质保金对不上、保修金该退没退、扣留比例算错、保修期届满日、质保金台账核对。

完全本地运行：引擎已经打包在本技能里（engine/ 目录）。 核对过程不需要联网、不需要 API Key、没有调用次数上限。

什么时候用

谁会在什么时候用：施工方的项目会计/成本员与发包方的基建财务，在每个结算期结账、 竣工结算对账、以及保修期满退还质保金这三个节点上，都要把质保金台账核一遍才能往下走； 核对结果直接决定这一笔钱这期退不退、退多少。

这张台账会逐项核对什么（免费版执行的 7 项）：

• 本期扣留金额 = 本期结算金额 × 扣留比例（比例可写 3 / 3% / 0.03，均按 3% 理解）
• 保修期届满日 = 保修期起 + 保修期月数 − 1 日（含首日口径：2024-05-01 起 24 个月 ⇒ 2026-04-30）
• 应退金额 = 累计扣留金额 − 保修期内扣减（扣减列为空按 0 计，并在结论里写明这一假定）
• 日期倒挂检测（届满日早于保修期起 / 退还日期早于保修期起）
• 合计行逐列复核（本期结算金额、本期扣留金额、累计扣留金额、退还金额、保修期内扣减）
• 重复结算单号检测
• 空白、占位符与无法识别的日期检测

每条结论都带台账原文行号（形如「台账第 2 行 · 结算单 JS-2024-001」）， 可由第三方用同一份输入和同一口径复算；材料不足时不给结论，会明确列出还缺什么。

这个免费版查什么

检查项以引擎导出的 CHECKS_GIVEN 为准，跑一次 --sample 就能看到实际执行了哪些。

怎么用

bash

node scripts/run.mjs --sample                 # 先看样例
node scripts/run.mjs --input 你的台账.json     # 跑自己的材料（{"text": "含表头的台账文本"}）

台账最少要有这些列：项目名称、结算单号、本期结算金额、扣留比例、本期扣留金额、 累计扣留金额、保修期起、保修期（月）、保修期止。其余列（结算日期、实际退还日期、 退还金额、保修期内扣减、扣减依据）有就一起核，没有不影响前 9 列的复算。 从 Excel 复制成文本、Tab 分隔最稳。

常见错法（这张台账里真的会有人这么填）

1. 比例写成一列三种口径：同一张表里既有「3」又有「3%」还有「0.03」，还夹着一个「0.3」（本意 3%， 实际是 30%）—— 本工具按「带 % 或数值大于 0.1 即百分数」归一化，0.3 会被当成 30% 并当场报出来。
2. 保修期届满日忘记减一天：2024-05-01 起 24 个月，台账写 2026-05-01，而含首日口径是 2026-04-30； 差这一天，到期判定、退还审批时点全跟着偏。
3. 把「累计扣留金额」当成本期扣留填：第二张结算单起，本期扣留与累计扣留两列混填， 退还时"累计扣留 − 扣减 ≠ 实退"，只能整张表倒回去查。
4. 同一结算单号贴两行：多标段/分期结算本该按结算单号分行，结果复制粘贴成了重复行， 扣留额和退还额一起翻倍，合计行也跟着虚增。
5. 到期该退的那行只留空白：既不写实际退还日期也不写退还金额，靠"空白=还没退"来记事； 免费版只会告诉你这一行的复算结果（不判定该不该退），到期没退要完整档才查。

需要完整档时（可选）

本免费版是完整可用的核心产出，本版本不包含下面这些项：

• 扣留比例超出合同上限（默认 3%，可用 payload.max_rate 覆盖）检测
• 保修期内扣减的合理性判定（无依据扣减 / 扣减超过累计扣留 / 扣减为负）
• 质保金应退未退的排期与逾期天数计算
• 质保金应退未退的可执行催办清单（含合同依据行号与建议动作）
• 保修期未满即已退还（提前退还）检测

同名工具的完整档是另一个独立商品（条款与条件以它自己的商品页为准）；两档的差别就是上面这些，没有别的。

边界（请务必知道）

本工具不做引擎 CHECKS_OUT_OF_SCOPE 里列的那些判断：不判断扣留比例是否合法（合同约定优先）、 不算逾期退还的资金占用费或利息、不处理银行保函/保险保单形式的质保金、不评价维修扣款本身该不该扣、 不读 .xlsx（需要你先导出成文本）。材料不足时不给结论，也不会输出「未发现问题」。

本免费版是完整可用的核心产出，但不包含下面这些检查（本次不会执行，也不会被伪造出来）：

• 扣留比例超出合同上限（默认 3%，可用 payload.max_rate 覆盖）检测
• 保修期内扣减的合理性判定（无依据扣减 / 扣减超过累计扣留 / 扣减为负）
• 质保金应退未退的排期与逾期天数计算
• 质保金应退未退的可执行催办清单（含合同依据行号与建议动作）
• 保修期未满即已退还（提前退还）检测