土壤地下水记录核对 PerryLink/dsh-soilwater-check

dsh-soilwater-check — 土壤和地下水监测记录表的完整性与算术一致性检查

dsh-soilwater-check 读取一份土壤和地下水监测记录表——项目表头，加上每个点位、每个参数一行——检查这份记录表自身的完整性与算术：每一行是否写明点位和参数，记录的结果能否解析为数字，采样日期能否解析且不晚于检查日期，是否记录了适用的标准，超标判定是否与结果同记录表自身写明的限值比较结果一致，样品编号有无重复，表头是否声明了项目和调查阶段，参数列中有无模板占位符残留。

它能回答什么

| 你的疑问 | 它的回答 |
| 记录表的判定写着达标，但结果高于旁边写的限值。这种情况能查出来吗？ | 能。SW-005 拿结果与记录表自身记录的限值比较，判定与比较结果不一致时报告该行。它不自带任何限值，所以查不出限值取自错误标准或错误用地类别的情况；判定落在配置的超标/达标列表之外时，单独报告。 |
| result 单元格写的是 未检出 或 <0.01，因为数值低于检出限。检查会怎么处理？ | SW-002 会报告它。这条规则只读取单元格中的数字部分（0.85 和 1.2×10-3 都接受），所以检出限写法会被有意报为无法解析——请记录数值，把备注放到另一列，或者停用这条规则。它检查的是能否解析，不判断数据是否真实、方法是否正确。 |
| 有一行的 standard 列为空。 | SW-004 要求每一行只要带这一列就必须填写标准。它检查的是标准写了没有，不是写得对不对：记录的标准是否匹配用地和介质，属于实质性问题，插件留给读者判断。 |
| 有一行记录的采样日期晚于检查日期，另一行把日期写成 2026/3/15。 | SW-003 会报告晚于检查日期的 sampledAt。它能读取 2026-03-15 和 2026-03-15 09:30；其他写法一律报为无法解析，不会悄悄跳过。这条规则只比较日期，不判断数据是否可靠。 |
| 同一个 labNo 出现在两行，因为一份样品分析了多个参数。 | SW-006 会报告样品编号重复，因为重复会切断实验室报告与记录表之间的对应关系；比较时忽略空白。一份样品的多个参数共用一个样品编号是正常形态——把它们放在不同行，但不要复用行号列。完全没有样品编号列时，这条规则会在 skipped 中报告自己，而不是静默通过。 |
| parameter 单元格仍写着 待填 或 【】，因为台账是从模板复制来的。 | SW-008 报告参数列里残留的占位符（【、】、{{、XXX、待填、TBD、示例 等，可在规则包里编辑）。注意 SW-001 只要求点位名称或参数填上即可，所以占位符在那里算已填；真正抓住它的是占位符规则。两条规则都不判断监测因子选得对不对。 |

遵循的标准

| 文件 | 编号 | 引用它的规则 |
| 《建设用地土壤污染状况调查技术导则》 | HJ 25.1—2019（代替 HJ 25.1-2014；条号本次未取得） | SW-001, SW-003, SW-007, SW-008 |
| 《地下水环境监测技术规范》 | HJ 164—2020（代替 HJ/T 164—2004；2020-12-01 发布、2021-03-01 实施；条号本次未取得） | SW-002, SW-006 |
| 《土壤环境质量 建设用地土壤污染风险管控标准（试行）》 | GB 36600—2018（本次未取得条文） | SW-004, SW-005 |

边界： 这个插件检查土壤与地下水监测台账的完整性和算术——每条记录是否写明点位和参数、结果能否解析成数字、采样日期是否在未来、是否记录了适用标准、超标判定是否与结果同台账所记限值的比较结果一致、样品编号是否唯一、台账是否写明项目和调查阶段、是否还有占位符残留。它不判断场地是否污染、是否需要修复、修复目标是否达标，也不判断调查结论是否成立。

⚠️ 这个插件刻意做不到的事

它不带限值，也不检查限值取自正确的标准。 SW-005 拿实测结果同台账自己记录的限值比较，检查判定是否一致。所以它发现不了那个要命的错误：筛选值取自错误的标准或错误的用地类别。 在 GB 36600 第一类和第二类筛选值之间取舍，或在 GB 36600 与 GB/T 14848 之间取舍，取决于用地和介质——这两样插件都不读。这条限制写在规则包头部、SW-004 和 SW-005 的说明里，以及故障排查一节。

SW-002 要求数字可解析，所以写成检出限记法（未检出、<0.01）的台账会被刻意报为无法解析——把数值连同备注一起记录，或者关掉这条规则。

规则包里每个 excerpt 都明说了条文原文未取得。 制度依据在 GB 36600—2018、GB/T 14848—2017、HJ 25.1 和 HJ 164 里。核对环节拿不到逐字条文，所以规则包在 excerpt 字段里直接写明这一缺口，并把每条规则都保持在 warn 或 info。拿到条文后，把每个 excerpt 换成真实条款，并把 kind 提到 direct。

兼容性

| 层面 | 状态 |
| 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 |
| Platforms | 全部平台（纯 ESM；无原生代码，无网络，不调用模型） |
| Tool mode | 在 native、ptc 和 both 下都能用；要做完整采样轮次请用 ptc |

功能说明

注册 soilwater_check 工具。它读取一份监测记录 —— 项目表头，加上每个点位与参数各一行 —— 套用带版本号的规则包，返回报告。

| 规则 | 检查内容 | 严重级别 | 依据类型 |
| SW-001 | 点位和参数都已记录 | warn | principle |
| SW-002 | 结果能解析为数字 | warn | principle |
| SW-003 | 采样日期不在未来 | warn | principle |
| SW-004 | 记录了适用的标准 | warn | principle |
| SW-005 | 判定结论与结果、限值一致 | warn | principle |
| SW-006 | 样品编号唯一 | warn | principle |
| SW-007 | 记录写明了项目和调查阶段 | warn | principle |
| SW-008 | 参数列里没有未替换的占位符 | warn | principle |

安装

dsh plugin --profile <name> add dsh-soilwater-check
dsh --profile <name> --dump-config | grep 'dsh-soilwater-check'

配置

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

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

- SW-005 的 valueField / limitField / verdictField / overValues / atMostValues / tolerance —— 三个列名和两套判定词表，默认分别是 [超标, 是, Y, yes, true, 超出, 不合格] 和 [达标, 否, N, no, false, 未超标, 合格]。判定词不在两个词表里时会报告出来，这样新写法就不会悄悄溜过去。
- SW-008 的 terms —— 要查找的占位符。

材料格式

工具接受 JSON 或 YAML：

project: 某某场地调查 phase: 初步调查 rows:
- { 序号: '1', 点位名称: S1 表层土, 介质: 土壤, 采样日期: 2026-03-05,
样品编号: TR-2026-0018, 监测项目: 砷, 监测结果: '12.5', 单位: mg/kg, 执行标准: GB 36600—2018 第二类用地筛选值, 标准限值: '60', 超标情况: 达标 }

列名匹配不区分大小写，并忽略空格、下划线和连字符；记录自身的列名会保留，所以问题项会指出它读取的是哪一列。结果可以带单位；检出限写法会刻意报告为无法解析。

规则来源

规则数据放在 rules/soilwater-check.yaml。规则包的表头完整说明了引用缺口，每个规则的 note 会复述该规则的关键部分。加载时的守卫通常强制「摘录必须是至少八个字符的真实引用」，但它分不清引用和描述——所以这个规则包靠头部、每条规则的 note，以及一个测试来兜底，该测试断言每个 excerpt 都允许这个缺口。

故障排查

- SW-005 放过了一个我知道是错的限值。 它只拿这个限值和登记表里写的限值比对。这个限值是否属于正确的标准和土地利用类别，是个实质性问题，它不涉及。
- SW-005 对等于限值的结果报错。 相等算作未超标；如果你的规则把「等于筛选值」当作超标，把 tolerance 调到略低于零，或者调整数据。
- SW-002 对 未检出 报错。 检出限写法不是数字。记录一个带备注的值，或者禁用这条规则。
- SW-006 对同一样品的多行报错。 同一样品的不同参数共用样品编号是合理的——这条规则以样品编号列为键，所以别把行号列复用给它。
- 插件装上了，但工具一直不出现。 检查 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-soilwater-check@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, the shared table-plugin suite plus paired fixtures
pnpm run build # tsdown -> lib/index.mjs + lib/index.d.mts
node ../scripts/sync-shared.mjs dsh-soilwater-check # refresh src/shared from ../_shared

这个插件是纯数据的：src/model.ts 声明表结构，共享套件提供读取器和检查引擎，规则包声明每一项检查。

许可证

Apache License 2.0 © 2026 dsh-soilwater-check contributors。