AI核对型 AI 工具

建筑工程材料用量与损耗核对（免费版）

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

什么时候用

谁在什么时候用：项目物资员 / 施工员 / 预算员 / 成本会计在**每个分部分项完工、每月物资盘点与成本归集、

限额领料考核结算之前** —— 「材料需用计划与实际消耗对照表」是材料成本、超耗扣款与物资台账的原始依据，

签完再改就要走签证 / 变更流程。

这张表会逐项核对什么（免费版执行 6 类，逐条都带原文行号）：

1. 损耗量复算 —— 损耗量 = 领用量 − 实际消耗量，差 0.01 也会报。
2. 损耗率复算 —— 损耗率 = 损耗量 ÷ 领用量 × 100%，分母是领用量。
3. 损耗率与参考上限比对 —— 用表内「损耗率上限」列；表里没有这一列时按参考上限 5.00% 提示。
4. 需用计划量与实际消耗量差异 —— 实耗量超过需用计划量时报出超出多少、超出几个百分点。
5. 合计行逐列复核 —— 合计行的需用计划量 / 领用量 / 实际消耗量 / 损耗量 = 各明细行之和。
6. 重复材料行与关键字段空缺 —— 同一分部分项 + 同一期间 + 同一材料 + 同一规格出现两次以上；

必需列为空或写着「待填 / 待补 / — / N/A」。

每条结论都带原文行号与算式，可被第三方用同一份输入复算；

材料不足时不给结论，会明确列出还缺什么，也不会用默认值编出结论。

这个免费版查什么

上面 6 类就是本版本执行的全部检查项。跑 --sample 会在 scope.checks 里打印本次实际执行了哪些，

scope.checks_not_run 会如实列出本版本没有执行的检查项（只列出，不会伪造结论）。

怎么用

node scripts/run.mjs --sample                      # 先看样例（样例本身就是一张自洽的对照表）
node scripts/run.mjs --input 你的材料.json          # 跑自己的材料
node scripts/run.mjs --input 你的材料.json --json   # 机器可读输出

入参两种写法都行：

• {"text": "（把表的表头和若干行一起复制进来，Tab 分隔最稳）"}
• 直接把「材料需用计划与实际消耗对照表」（含表头）从 Excel 复制成文本贴进 .json 里；

文件不是合法 JSON 时整体按纯文本材料处理。

必需列（缺一列就不给结论）：分部分项工程、期间、材料名称、需用计划量、领用量、实际消耗量、损耗量、损耗率。

可选列：规格型号、单位、损耗率上限、单价、备注（不填也能跑；损耗率上限缺失时退化成参考上限 5.00%）。

出参

• status：success 才有结论；insufficient_input 表示材料不足，此时没有 result、没有 findings，

只有 missing（缺什么）与 advice（怎么补）。

• result.findings[]：每条含 level（P0/P1/P2）、category、line（原文行号）、message（含算式与差额）、

advice、basis（引用原文整行）。

• result.summary：`rows / parts / periods / materials / total / p0 / p1 / p2 /

planned_total / issued_total / actual_total / loss_total / verdict`

（NO_ISSUE_FOUND | NEEDS_REVIEW | ERROR_FOUND）。

• result.scope：本次执行的 checks、未执行的 checks_not_run、loss_rate_cap（上限口径来源）、

tolerance、rate_tolerance、executed_locally: true、network_used: false。

• result.checks_out_of_scope：本工具根本不做的判断清单（边界诚实）。
• CLI 退出码：0 已执行检查 / 1 没给入参 / 3 材料不足 / 4 入参读不到或无法解析 / 9 未预期错误。

常见错法（本产品专属）

1. 损耗率的分母写成需用计划量或实耗量：本表口径是 损耗率 = 损耗量 ÷ 领用量。

分母换成计划量时，只要领用量与计划量不等，每一行的损耗率都会不对（而且方向一致地偏大或偏小）。

1. 损耗量倒挤：先按经验写一个损耗率，再反推 损耗量 = 领用量 × 损耗率，结果与「领用量 − 实耗量」差几毛几分 ——

两条算式必须同时成立，报出来先看是哪一列被动过。

1. 上限列填成小数比率：这一列按百分数填（3.00 表示 3.00%）；绝对值小于 1 的数按比率口径换算

（0.03 ⇒ 3.00），但写成「0.03%」就会被当成 0.03%，绝大多数行都会判超限。

1. 以领代耗：现场还有一堆料没耗用就不办退库，损耗量直接把余料算进损耗 ——

会同时带出损耗率超上限与实耗超计划，先办退库单再跑这张表。

1. 同一分部分项同一材料拆成多行领料却都写同一个材料名称与规格：会被判重复材料行，用量与损耗被重复汇总；

分批领料请合并成一行，或在规格 / 备注里区分批次。

1. 合计行用上月表或计划表的数：合计行必须等于各明细行相加；差额通常是漏了一行明细、某行被重复计入，

或者合计是从别的表抄过来的。

1. 用「—」「待填」「无」「N/A」代替 0.00：占位符一律按"没填"处理，那一行的损耗勾稽核不动 ——

该是 0 就写 0.00。

这个免费版不包含

本免费版是完整可用的核心产出，本版本不包含下面这些项（它们会如实列在输出的 checks_not_run 里，绝不会伪造）：

• 超耗归因（计划偏差 / 施工损耗 / 计量口径 / 被盗或流失 / 返工）；
• 跨分部分项 / 跨期间超耗汇总台账（按分部分项 × 材料汇总加权损耗率与超耗金额）；
• 按超耗金额从大到小的处理清单（带原文行号与建议动作）；
• 跨期间损耗率漂移提示（同一材料在不同期间损耗率偏离参考中位数超过 5 个百分点）。

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

使用次数与完整档

本免费版会在本包目录里记一个使用次数（scripts/.hint-count，一个整数，不含任何机器或用户信息）。

· 前 3 次：完全离线（不发生任何网络请求），输出与现在完全一样；

· 第 4 次起：服务端会返回一段完整档说明（完整档是另一个独立商品，条款与价格以它自己的商品页为准），届时才会打印这一行；

· 第 4 次起才会向服务端问一次（只发包标识与次数），拿回完整档说明；

· 请求不可用（离线/超时/被拦截）时什么都不做，核对结果与退出码不受任何影响；

· 不想要这次统计可以加 --no-stats（核对功能完全不受影响，只是拿不到完整档说明）。

本版本不包含的检查项见上一节；需要完整档时按服务端返回的官方口令执行，付款由用户本人确认。

需要完整档时（可选）

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

• 超耗归因（计划偏差 / 施工损耗 / 计量口径 / 被盗或流失 / 返工）
• 跨分部分项 / 跨期间超耗汇总台账（按分部分项 × 材料汇总加权损耗率与超耗金额）
• 按超耗金额从大到小的处理清单（带原文行号与建议动作）
• 跨期间损耗率漂移提示（同一材料在不同期间损耗率偏离参考中位数超过 5 个百分点）

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

边界（请务必知道）

本工具不做引擎 checks_out_of_scope 里列的那些判断，其中最容易误解的三条：

• 不判断需用量定额是否合理（定额、损耗率上限以施工定额、投标文件与合同约定为准）；
• 不判断现场材料是不是真的被盗 / 流失 / 返工（本版本连归因提示也不做，只报"超出上限"这件事）；
• 不判断计量口径（以领代耗、领料退库、甲供材抵扣、调拨）是否符合本单位物资管理办法。

材料不足时不给结论，也不会输出「未发现问题」。

与相邻能力的区别：bom-consumption-variance-check 核的是制造业工单 / BOM 的用量差异 （标准用量 = 单位用量 × 产出数量）；本能力核的是建筑工程分部分项的「需用量 — 领用量 — 实耗量」损耗勾稽。