水产投入品核对 PerryLink/dsh-aqua-input-check

dsh-aqua-input-check — 水产养殖投入品登记完整性与休药期日期检查

dsh-aqua-input-check 读取一份水产养殖投入品登记表——养殖场表头，加上每条投入品记录一行——检查这份登记表自身的完整性和日期计算：每条记录是否写明池塘和物种，写明了投入品的记录是否填了数量和用药日期，用药日期是否在未来，收获是否遵守记录自身写明的休药期，放养记录是否带来源和检疫证明编号，投入品类型是否来自你配置的词表，以及批号是否唯一。
它不判断养殖做法是否合规、产品是否可安全食用、用药是否恰当，也不判断是否应受处罚。

它能回答什么

| 你问 | 它回答 |
| 记录写明了投入品，但池塘和物种列空着。 | AQ-001 要求每条记录至少填 pondNo 和 species 之一。它只检查两者中是否填了一个，不判断该投入品是否适合该物种。 |
| 投入品名称填了，但数量和用药日期是空的。 | 只要 inputName 填了，AQ-002 就要求填 inputQty 和 usedAt。它检查字段是否记录，不检查剂量是否合适、用药是否对症。 |
| 用药日期写成 15/03/2026，还有一行填了下个月的日期。 | AQ-003 接受 2026-03-15 和 2026-03-15 09:30；无法解析的 usedAt 报为不可解析，晚于检查日期的报为未来日期。它不涉及休药期——本包根本不附带休药天数。 |
| 我们 6 月 1 日用药，记录的休药期是 20 天，6 月 15 日收获。这能查出来吗？ | 能。AQ-004 比较 usedAt、harvestAt 和记录自身的 withdrawalDays，把该行报为短缺相应天数。报出问题意味着「按你记录的休药期，收获提前了」——不是说产品不安全，那需要残留检测，本插件看不到。如果这三个字段没有全部填写且可解析，规则报 skipped，不擅自假定一个休药期。 |
| 我们用的投入品类型不在列表里——什么都没报。 | AQ-006 报 skipped，因为本包不附带投入品类型词表：values 为空，直到你配置一个。配置之后，规则检查存储的 inputType 是否属于你的取值。它不判断该投入品能否合法使用——那需要禁用药物清单和产品批准文号。 |
| 同一批号出现在两行里。 | AQ-007 报告重复，并指出这两行。比较时忽略空白；同一批次有多条输入记录很正常，只要批号相同即可——不要为此复用行号列。没有批号列时，它报告无法运行，而不是静默通过。 |

遵循的标准

| 文档 | 编号 | 引用它的规则 |
| 《水产养殖质量安全管理规定》 | 农业部令（现行令号与条号本次未核实） | AQ-001, AQ-002, AQ-005, AQ-007 |
| 《绿色食品 渔药使用准则》 | NY/T 755—2022（2022-07-11 发布、2022-10-01 实施；全部代替已废止的 NY/T 755—2013；属绿色食品系列标准；条号本次未取得） | AQ-003, AQ-004 |
| 本机构养殖生产管理口径（本机构配置） | 无统一标准（本条依据为本机构配置的类型口径） | AQ-006 |

边界： 本插件检查一份水产养殖投入品记录的完整性与日期运算——每条记录是否写明池塘和品种，写明的投入品是否记录数量和用药日期，用药日期是否不在未来，采收是否遵守记录中写明的休药期，放养是否记录来源和检疫证明，投入品类型是否出自你的词表，批号是否唯一。它不判定养殖操作是否合规、产品是否可安全食用、用药是否恰当，也不判定是否应受处罚。

⚠️ 本插件刻意不去知道的事

它不内置任何休药期。 AQ-004 检查的是采收日期距用药日期至少达到记录自身休药期列所写的天数。所以一条发现的意思是「按你记录的休药期，采收提前了 N 天」——绝不是「这个产品不安全」。残留安全需要检测结果，而本插件看不到。没有采收日期的记录会在 skipped 里报告自己，而不是假定一个休药期。

它不内置允许或禁用投入品清单。 AQ-006 检查的是投入品类型是否为你配置的类型；某个产品能否合法使用，需要禁用药物清单和产品的批准文号，本插件不涉足这些。

规则包里的每一条 excerpt 都明明白白写着：未取得条款原文。 相关制度见《水产养殖质量安全管理规定》、NY 5361、NY/T 755 和 GB 13078。核验环节无法取回逐字条款原文，因此规则包在 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 |
| 平台 | 全部（纯 ESM；无原生代码、无网络、无模型调用） |
| 工具模式 | 在 native、ptc 和 both 下均可工作；一季的记录请用 ptc |

它做什么

注册 aqua_input_check 工具。它读取一份投入品登记表——养殖场表头，加上每条投入品记录一行——套用带版本号的规则包，返回一份报告。

| 规则 | 检查内容 | 严重级别 | 依据类型 |
| AQ-001 | 塘口和养殖品种已记录 | warn | principle |
| AQ-002 | 具名投入品记录了投入量和使用日期 | warn | principle |
| AQ-003 | 使用日期不在未来 | warn | principle |
| AQ-004 | 起捕遵守记录的休药期 | warn | principle |
| AQ-005 | 投苗记录了苗种来源和检疫证号 | warn | principle |
| AQ-006 | 投入品类型来自你的词表（默认关闭） | info | local |
| AQ-007 | 批次编号唯一 | warn | principle |

安装

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

配置

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

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

- AQ-004 的 earlierField / laterField / minDaysField——两个日期，以及存放所需间隔天数的列。休药期来自记录本身，没有内置任何数值。
- AQ-006 的 values——你的投入品类型，例如 [配合饲料, 冰鲜鱼, 水质改良剂, 抗菌药, 杀虫药, 消毒剂, 疫苗]。留空表示不检查。
- AQ-002 的 conditionField / requiredFields——什么条件触发投入量与日期的必填要求。

材料格式

工具接受 JSON 或 YAML：

farm: 某某水产养殖场 site: 某某镇某某村 area: 86 亩 rows:
- { 序号: '1', 批次编号: B-2026-0001, 塘口编号: T-03, 养殖品种: 草鱼,
投苗日期: 2026-02-20, 苗种来源: 某某苗种场, 检疫证号: JY-2026-0031, 投入品类型: 配合饲料, 投入品名称: 草鱼配合饲料 2 号, 投入量: '350', 投入量单位: kg, 使用日期: 2026-03-01, 休药期天数: '0', 起捕日期: 2026-06-20 }

列名匹配不区分大小写，并忽略空格、下划线和连字符；登记表自己的列名会保留，所以每条发现都会指出它读的是哪一列。注意，序号被当作该行的显示编号——请给批次标识单独一列（批次编号）。

规则来源

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

故障排查

- AQ-004 报告自身被跳过。 两个日期或休药期缺了一个。比如只记录投喂、没有收获记录，就不在检查范围内。
- AQ-004 触发了，但我认为这批是安全的。 这条结论是算术推出来的：收获早于你记录的休药期。残留是否构成问题，需要检测结果才能判断。
- AQ-006 从不运行。 它的词表是空的；把你养殖场用到的投入品类型填进去。
- AQ-007 在一条有多条投入品记录的批次上触发。 同一批次的几条记录应当共用同一个批次号。如果你的台账给每一行单独编号，请停用这条规则，或改用一列独立的标识符。
- 插件装上了，但工具始终不出现。 检查 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-aqua-input-check@0.1.0 --dsh-version <runtime> --accept-risk
- check 报告 manifest-peers 失败。 静态检查器拿一个硬编码的 peer 范围来比对，而这个范围早于 0.2 系列。运行时会在安装时强制校验 peer 兼容性，所以声明的范围才是正确的；这是 dsh-plugin-dev 里已知的上游问题。

Development

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-aqua-input-check # refresh src/shared from ../_shared

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

License

Apache License 2.0 © 2026 dsh-aqua-input-check contributors.