防护配置表核对 PerryLink/dsh-guard-plan-qc

dsh-guard-plan-qc — 劳动防护用品配置表检查

dsh-guard-plan-qc 读取一张劳动防护用品配置表 —— 计划中写明的人数和周期，外加每行一条已配置的产品 —— 检查这张表自身的完整性与内部一致性：每一行是否填了品名、规格型号和配置数量，配置数量能否解析为大于零的数字，它与你配置的每人系数乘以计划人数是否对得上，发放日期是否落在计划周期内，有效截止日期是否晚于发放日期，以及表格是否覆盖了你要求的品类。

它能回答什么

| 你的问题 | 它的回答 |
| 某行写了产品名，但规格型号留空。这会被报出来吗？ | 会。GP-001 要求每一行都填上 requiredFields 里的字段 —— 出厂配置是品名、规格型号和配置数量，可替换成你自己表格的列 —— 并报出该行以及它缺哪些字段；空字符串算未填。它只检查这些列有没有填，不检查产品或其规格是否正确。 |
| 配置数量单元格写的是「若干」。这和数量为零是一回事吗？ | 不是。GP-002 把两者分开报：解析不出来的值（比如「若干」）报为不是数字，能解析但不大于零的值则连同数字本身一起报出。2双、１，２００ 和 2 件 都能解析，单位照带。这条规则不检查数字是否属实，也不检查数量够不够；把 checkQuantity 设为 false 它就不跑。 |
| 人数是 20，factors 里绝缘手套每人 2 副，但该行配置了 30。这会被抓到吗？ | 会，前提是配置了 factors。GP-003 用每人系数乘以人数，找出数量偏差超过其 tolerance 的匹配行并报出。factors 出厂为空，所以按默认交付时，这条规则会在 skipped 里说明原因，而不是悄悄放过；材料没有声明人数时，它也会出现在那里。系数是你查到的数字，不是国家规定的数字 —— 规则不判断它是否合理。 |
| 计划周期是 2026-03-01 到 2026-03-31，某条发放日期写的是 2026-02-20。这会被报出来吗？ | 会。GP-004 把该行报为早于 periodFrom。周期取自材料的顶层 periodFrom / periodTo；两者都缺时，规则会在 skipped 里说明，而不是假定一个周期；解析不出来的日期单独报出，不会悄悄跳过。 |
| 有效截止日期和发放日期是同一天。这能通过吗？ | 不能。GP-005 要求有效截止日期晚于发放日期，不满足就报出该行，且只在行里同时写了两个日期时才运行。这个有效期够不够长 —— 取决于产品和岗位 —— 不在判断范围内。 |
| 表格里写的是安全帽，但我要求的清单写的是安全头盔。会被报成未覆盖吗？ | 会。GP-006 按字面包含关系比对品名和规格型号，所以同一个产品换个说法就会被报成未覆盖；把常见写法都列上，或者统一表格里的措辞。requiredCategories 默认是空的，所以按交付状态，这条规则会在 skipped 里报告自己。它只检查类别是否出现，不检查产品是否适合该项目。 |

遵循的标准

| 文件 | 编号 | 被哪些规则引用 |
| 《个体防护装备配备规范》 | GB 39800.1—2020（个体防护装备配备规范 第1部分：总则；标准号不带"/T"⇒强制性；2020-12-24 发布、2022-01-01 实施；主管部门应急管理部；条号本次未取得） | GP-001, GP-002, GP-003, GP-004, GP-005, GP-006 |

边界： 这个插件检查的是一张劳动防护用品配置表，看表格能被要求做到的事——每一行都要写明产品、规格和数量，数量是正数，与计划里写的人数对得上，发放日期落在计划周期内，有效期在发放日期之后，表格覆盖你要求的类别。它不判断某个产品对某种危害是不是正确的防护、防护等级够不够，或者算不算特种劳动防护用品。

⚠️ 在相信报告里的引用之前，先读这段

这个插件规则包里每一条 excerpt 都明说了：没有取得条款原文。 制度依据是 GB 39800.1《个体防护装备配备规范》 和《劳动防护用品监督管理规定》。
这个插件的核验环节没能从这些文件里取到逐字条款原文，所以规则包没有去转述一段引文，而是在 excerpt 字段里直接说明这个缺口，把诚实的推理写进 note。因此所有内容都封顶在 warn（由原则推导）或 info（本地配置），并且有测试断言：没有任何规则声称自己拥有并不存在的引文。拿到原文后，必须做两件事：把每条 excerpt 换成真实条款，把 kind 提升为 direct。

能让这个插件变强的两个数字，正是它拒绝编造的两个。 每个人需要几件（GP-003 的 factors）和某个岗位必须覆盖哪些产品类别（GP-006 的 requiredCategories），取决于你项目的危害识别，而不是某个全国统一数字。两者默认都是空的，而列表未设置的规则会在 skipped 里报告自己，而不是直接通过。

兼容性

| 层面 | 状态 |
| Harness | 对等范围 >=0.1.2-rc.1 <0.2.0 \|\| >=0.2.0-0 <0.3.0 —— 已验证同时接受 0.2.0-rc.2 和 0.2.1-alpha.1。故意不声明 engines.dsh：它没有读取方，也无法拒绝宿主 |
| Node | ^22.19.0 || >=24.0.0 |
| 平台 | 全部（纯 ESM；无原生代码、无网络、无模型调用） |
| 工具模式 | 在 native、ptc 和 both 下都能用；处理一批计划时用 ptc |

它做什么

注册 guard_plan_qc 工具。它读取一张配置表——行以表自身的列名为键，再加上计划的人数和周期——然后返回报告。

| 规则 | 检查内容 | 严重级别 | 依据类型 |
| GP-001 | 每一行都写明品名、规格型号和配置数量 | info | local |
| GP-002 | 数量能解析为正数 | warn | principle |
| GP-003 | 数量与人数 × 每人系数对得上（默认关闭） | info | local |
| GP-004 | 发放日期落在计划周期内 | warn | principle |
| GP-005 | 有效截止日期晚于发放日期 | warn | principle |
| GP-006 | 表格覆盖你要求的品类（默认关闭） | info | local |

安装

dsh plugin --profile <name> add dsh-guard-plan-qc
dsh --profile <name> --dump-config | grep 'dsh-guard-plan-qc'

配置

| 键 | 类型 | 默认值 | 说明 |
| rulesFile | string | rules/guard-plan-qc.yaml | 规则包路径，相对于包根目录 |
| disabledRules | string[] | [] | 要停止运行的规则 id；每个都会出现在 skipped 里 |
| onlyRules | string[] | [] | 只运行这些规则 id；留空则运行全部规则 |
| skipNotes | string | "" | 附加到每条 skipped 原因后面的备注 |
| timeoutMs | number | 120000 | 协作式工具超时预算 |

几个值得了解的规则级参数：

- GP-001 requiredFields——默认是 [品名, 规格型号, 配置数量]；换成你表单里的列名即可。
- GP-002 checkQuantity——设为 false 就不再检查数量。
- GP-003 factors——你的每人系数，例如
[{ match: 绝缘手套, perPerson: 2, tolerance: 0 }]。match 对品名做子串匹配。
- GP-006 requiredCategories——你的项目必须覆盖的产品，例如 [安全帽, 绝缘手套, 安全带]。也可以在每次调用时传入。

材料格式

工具接受 JSON 或 YAML：

subject: 某某厂房工程 headcount: 20 periodFrom: 2026-03-01 periodTo: 2026-03-31 rows:
- { 品名: 安全帽, 规格型号: V 型 黄色, 配置数量: "20", 发放日期: 2026-03-05, 有效截止日期: 2028-03-04 }
- { 品名: 绝缘手套, 规格型号: 12kV, 配置数量: "40", 发放日期: 2026-03-05 }

数量从字符串读取，所以表格导出的结果可以直接用：2双、1,200、１２ 和 1.5 都能解析。不是数字的单元格（若干、空白）会报告为无法解析，这不同于数量为零——两者需要不同的修法，所以产生的发现也不同。

GP-004 需要 periodFrom 和/或 periodTo；两者都没有时，它会在 skipped 里报告自己，而不是假定一个周期。GP-003 需要 headcount；没有时它会说明这一点。

规则来源

规则数据放在 rules/guard-plan-qc.yaml。规则包的头部完整说明了引用缺口，每条规则的 note 会重复其中对该规则重要的部分。加载时的守卫通常强制要求「摘录必须是至少八个字符的真实引用」，但它分不清引用和描述——所以这个包靠头部、每条规则的说明，还有一个测试来撑住——测试断言每个 excerpt 都承认这个缺口。

故障排查

- GP-003 或 GP-006 报告自己被跳过。 它们的列表是空的。factors 和 requiredCategories 来自你的危险源识别，插件不会替你猜。
- GP-003 在你故意设定的数量上触发。 你配置的系数不是实际在用的那个，或者材料里的人数已经过期。调高 tolerance，或者修正系数。
- GP-006 在一个表里已有的产品上触发。 比较是对 品名 和 规格型号 做字面子串测试，所以 安全帽 匹配不上 安全头盔。把你用到的写法都列出来，或者把表规范化。
- GP-004 不报告任何日期相关的内容。 没有声明计划周期，或者表里没有签发日期；两种情况规则都会在 skipped 里说明。
- 插件装上了，但工具一直不出现。 检查 main 是否指向 lib/index.mjs，以及 pnpm run build 是否生成了它；main 写错会让加载器静默跳过这个入口。
- dsh plugin add 以不兼容为由拒绝这个包。 peer 范围覆盖 0.1.x 和 0.2.x；如果你的运行时在这个范围之外，显式授予豁免： dsh plugin --profile <name> allow-version dsh-guard-plan-qc@0.1.0 --dsh-version <runtime> --accept-risk
- check 报告 manifest-peers 失败。 静态检查器比对的是一个硬编码的 peer 范围，比 0.2 这条线还早。运行时在安装时强制校验 peer 兼容性，所以声明的范围才是正确的那个；这是 dsh-plugin-dev 里已知的上游问题。

开发

pnpm install
pnpm run typecheck # tsc --noEmit
pnpm test # vitest, paired fixtures per rule
pnpm run build # tsdown -> lib/index.mjs + lib/index.d.mts
node ../scripts/sync-shared.mjs dsh-guard-plan-qc # refresh src/shared from ../_shared

许可证

Apache License 2.0 © 2026 dsh-guard-plan-qc contributors。