预测考核台账核对 PerryLink/dsh-forecast-penalty

dsh-forecast-penalty — 预测准确率考核登记簿与考核费用算术校验

dsh-forecast-penalty 读取一份预测准确率考核登记簿 —— 表头加每个考核期一行 —— 校验登记簿自身的完整性与算术：考核期、考核对象、市场是否写明，预测值、实际值、准确率能否解析为数字，存储的准确率是否与你配置的定义公式一致、考核费用是否与你配置的费用公式一致，币种是否写成三字母代码，考核期有无重复，备注列有无未替换的占位符残留。每一项无法执行的检查都会连同原因写进 skipped。

它能回答什么

| 你的问题 | 它的回答 |
| 登记簿始终没写覆盖哪个场站、哪个市场，还有一个预测值写成 --。 | FP-001 要求写明考核对象与市场，FP-002 要求预测值能解析为数字；-- 会被报出。FP-001 只检查这两项是否填写，不检查场站名称是否正确，FP-002 也不判断预测是否准确。 |
| 我存储的准确率与我自己市场的定义公式不一致，考核费用也与基数乘单价不符。 | FP-003 把存储值同规则包中配置的定义公式比对 —— 内置表达式只是一种常见约定和示例，不是你市场的规则，请替换 expression 或停用该规则 —— 容差 1.5 个百分点。FP-004 把考核费用同 考核基数 × 考核单价 比对，容差 0.01；基数由你录入。两者都不判断考核方法是否适用、是否应当计收费用。 |
| 币种列有的行空着，有的行写 元。 | FP-005 要求三字母大写代码，如 CNY 或 USD，所以空值和 元 都会被报出；这条规则的局限是只判断格式，不判断你机构的人民币该用哪个代码，也不判断所选币种是否正确。 |
| 同一个考核期出现在多行。 | FP-006 会报出重复的考核期，因为重复会让考核费用累计两次，也说不清该期是登记了两次还是考核了两次；比对时忽略空白。同一考核期按时段和档位分别考核，本来就会产生多行 —— 请在备注列区分，或改用不同的考核期标识，或停用该规则。它不判断哪一行是重复项。 |
| 备注列里还留着 【】、XXX 或 TBD。 | 备注列里出现规则包中配置的任一占位符时，FP-007 会报出该行，因为从模板复制来的台账会让读者以为考核真的做过了。词表由你自行调整，规则不判断备注文字是否属实。 |
| 我的材料里整列都缺失——规则会悄悄放过吗？ | 不会。列级规则（FP-002、FP-005、FP-006、FP-007）会在 skipped 下报出自己，理由是该材料没有这一列，报告会把它和「跑了但没发现差异行」的规则区分开。没跑过的检查，绝不会被当成通过。 |

遵循的标准

| 文件 | 编号 | 引用它的规则 |
| 电力市场考核办法与并网调度协议（无国家标准） | 无统一标准（本条依据为台账可追溯性） | FP-001 |
| 电力市场考核办法与并网调度协议（无国家标准） | 无统一标准（本条依据为算术可行性） | FP-002 |
| 电力市场考核办法与并网调度协议（无国家标准） | 无统一标准（本条依据为本机构配置的准确率定义式） | FP-003 |
| 电力市场考核办法与并网调度协议（无国家标准） | 无统一标准（本条依据为本机构配置的考核算式） | FP-004 |
| 《表示货币的代码》 | GB/T 12406—2022（表示货币的代码；2022-12-30 发布并实施；全部代替 GB/T 12406—2008（该版名称为「表示货币和资金的代码」）——注意旧版名称含"资金"；修改采用 ISO 4217:2015，非等同采用；条号本次未取得） | FP-005 |
| 电力市场考核办法与并网调度协议（无国家标准） | 无统一标准（本条依据为台账唯一性） | FP-006 |
| 电力市场考核办法与并网调度协议（无国家标准） | 无统一标准（本条依据为台账真实性） | FP-007 |

边界： 本插件检查的是预测准确率考核台账的算术——考核周期和考核对象是否写明，预测值和实际值能否解析，准确率数值是否与你配置的定义式相符，考核费用是否与你的费用算式相符，货币是否遵循其格式，考核周期是否重复，以及是否还有占位符残留。它不判断该不该收这笔费用、准确率是否达标、是否适用免考核或申诉。这些取决于市场规则、免考核情形和争议处理程序。

⚠️ 这是市场规则，不是国家标准——规则包自己也是这么说的

准确率定义、免考核阈值、单位费率和结算依据，都由各电力市场的考核办法与并网调度协议规定。各省差异很大（有的用 1 − 偏差，有的用均方根误差，有的按时段和档位考核），不存在统一的国家标准。所以本规则包不会编造标准号：每条规则的 excerpt 都明确写出，其依据是算术自洽性或本地配置的约定，不存在可引用的条款。

随包附带两个公式作为示例，且都标注为示例：

- FP-003 的准确率默认是 预测值 ÷ 实际值 × 100，容差 1.5 个百分点。这只是一种常见约定，不是任何市场的规则。使用前，请把 expression 换成你所在市场规则里的公式——或者停用该规则。注释里已写明这一点。
- FP-004 charge 检查 考核费用 = 考核基数 × 考核单价。考核基数由你按所在市场的规则算好后手动录入，因为阈值、区间和电量口径属于市场自己的业务，本插件不会替你推导。任何地方都没有内置单价。

有一点值得知道：准确性规则之所以以 info 级别发布，正是因为它的公式属于部署时的选择，而不是经过验证的硬性要求。

兼容性

| 层面 | 状态 |
| 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 |

功能说明

注册 forecast_penalty 工具。它读取一份考核台账 —— 主体表头加上每个时段一行 —— 应用版本化的规则包，然后返回报告。

| 规则 | 检查内容 | 级别 | 依据 |
| FP-001 | 台账写明主体和市场 | warn | 可追溯性 |
| FP-002 | 预测数值可解析为数字 | warn | 算术可行性 |
| FP-003 | 准确性符合你定义的公式 | info | 本地公式 |
| FP-004 | 费用符合你的费用公式 | info | 本地公式 |
| FP-005 | 币种为三字母代码 | warn | GB/T 12406 |
| FP-006 | 考核时段不重复 | warn | 台账唯一性 |
| FP-007 | 备注列不含未替换的占位符 | warn | 台账完整性 |

安装

dsh plugin --profile <name> add dsh-forecast-penalty
dsh --profile <name> --dump-config | grep 'dsh-forecast-penalty'

配置

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

值得了解的规则级参数：

- FP-003 expression —— 准确性定义。运算有 divide、product、sum、subtract（第一个字段减去其余字段）和 percent（第一个字段 ÷ 第二个 × 100），还可选 scale 乘数。tolerance 默认 1.5 个百分点；按你的舍入约定设置。
- FP-004 expression / tolerance —— 费用公式，默认 考核基数 × 考核单价，容差 0.01。
- FP-005 pattern —— 币种形态；默认三个大写字母。
- FP-007 terms —— 要查找的占位符。

材料格式

工具接受 JSON 或 YAML：

subject: 某某风电场 market: 省内现货 rows:
- { 考核期: 2026-03, 预测值: '966', 实际值: '1000', 准确率: '96.60',
考核门槛: '95', 考核基数: '80', 考核单价: '50', 考核费用: '4000', 币制: CNY }

列名匹配时不区分大小写，并忽略空格、下划线和连字符；台账自己的列名会保留，所以每条发现都会指明它读的是哪一列。数值单元格可以带千位分隔符和百分号。

规则来源

规则数据放在 rules/forecast-penalty.yaml。考核制度属于市场规则，不是标准，所以规则包里的 basis 条目会明确说明这一点，而不是去引用某个标准；唯一的外部引用是币种代码标准，其摘录也承认未取得条款原文。加载时的守卫仍然要求每条规则都带文档、条款、摘录和来源，也仍然禁止把本地配置的检查设为 error。

故障排查

- 每一行都触发 FP-003。 准确率是按另一套公式算出来的，和配置里的公式不一致。把 expression 换成你所在市场的公式，或者停用这条规则——不要为了掩盖定义不一致而放宽容差。
- FP-004 报告自己被跳过。 台账里没有考核基数列，或者没有费用。基数由你自己算、自己记；插件不会替你推导。
- FP-005 在 元 上触发。 默认模式要求三个大写字母。按你结算文件的习惯收窄或放宽它。
- FP-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-forecast-penalty@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-forecast-penalty # refresh src/shared from ../_shared

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

许可证

Apache License 2.0 © 2026 dsh-forecast-penalty contributors.