学情差距核对 PerryLink/dsh-learning-gap-check

dsh-learning-gap-check — 能力差距与发展计划登记表检查

dsh-learning-gap-check 读取一份能力差距与发展计划登记表——员工表头加上每个能力一行——检查这份登记表自身的算术与闭环：每个差距是否写明岗位和能力，记录的水平能否解析为数字，差距是否等于要求水平减去实际水平，超出你配置阈值的差距是否带有发展行动，行动是否写明负责人和截止日期，完成日期是否不晚于截止日期，行动状态是否出自你自己的词表。

它能回答什么

| 你问 | 它回答什么 |
| 某行写了能力，但岗位留空。 | 只有当 position 和 competency 都为空时，LG-001 才报告该行；两者填了其一就够了。它检查的是该行是否写明岗位和能力，不判断该岗位的能力要求是否合理或完整。 |
| 我们的水平写成词（熟练、掌握）或字母（A/B/C）——会怎样？ | LG-002 读取 actualLevel，要求它能解析为数字，所以写成词或字母的水平会被报告为无法解析。插件不自带能力等级表：把登记表转成数字等级，或者同时禁用 LG-002 和 LG-003。它只检查能否解析——评估是否客观、是否准确，它不做判断。 |
| 差距列写的是 3，但要求 4 减去实际 2 等于 2——这能抓到吗？ | LG-003 以 0 为容差重新计算 requiredLevel − actualLevel，报告存储的 gapLevel 对不上的行。只有三列都存有可解析的数字时它才运行；缺一个，规则就转为 skipped。负差距照原样报告，因为列有可能写反了，而规则不判断差距多大才算问题。 |
| 某行记录了发展行动，但没有负责人，也没有截止日期。 | 只要某行的 action 填了，LG-005 就要求它有 owner 和 dueAt，缺任何一个就报告该行。它检查这两个字段是否记录，不判断行动是否有效、截止日期是否合理。 |
| 某行的完成日期晚于截止日期，或者两列填反了顺序。 | LG-006 在每一行比较 dueAt 与 completedAt，截止日期早于完成日期就报告该行。规则包用自己的话说明了限度：它只比较两个日期的先后，不判断工作是否真的按期完成。无法解析的日期会单独报告，而不是略过。 |
| LG-004 和 LG-007 从不报告任何内容——这是否意味着我的台账通过了这两条规则？ | 不是：这两条规则都会在 skipped 里报告自己。LG-004 出厂时 threshold: 0，表示尚未配置——请设置差距达到多大时就必须采取培养行动。LG-007 出厂时状态词表为空——请按你所在机构自己的说法填入。配置完成后，LG-004 只检查行动列是否填写，LG-007 只检查状态值是否在你的词表里；两者都不判断行动是否真的执行了。 |

遵循的标准

| 文件 | 编号 | 引用它的规则 |
| 《质量管理 能力管理和人员发展指南》 | GB/T 19025—2023（质量管理 能力管理和人员发展指南；2023-03-17 发布并实施；归口全国质量管理和质量保证标准化技术委员会；条号本次未取得） | LG-001, LG-002, LG-003, LG-005, LG-006 |
| 本机构培训与发展管理口径（本机构配置） | 无统一标准（本条依据为本机构配置的差距阈值） | LG-004 |
| 本机构培训与发展管理口径（本机构配置） | 无统一标准（本条依据为本机构配置的状态口径） | LG-007 |

边界： 本插件检查能力差距与培养计划台账的算术与闭环——每个差距是否写明岗位和能力项，两个等级列是否能解析为数字，差距是否等于要求减实际，超出阈值的差距是否带有培养行动，行动是否写明负责人和截止日期，完成日期是否不晚于截止日期，行动状态是否来自你的词表。它不判断员工是否胜任、评估是否客观、培养行动是否有效，也不判断某人是否应被调岗或辞退。

⚠️ 本插件刻意不包含的内容

它不提供能力等级量表，并假定等级是数字。 LG-002 和 LG-003 读取三个数字列，并检查它们之间的算术。若台账使用字母等级（A/B/C）或词语（熟练/掌握），会被报告为无法解析，因为比较这类等级属于建模决策，插件不会替你做。请转换量表，或停用这些规则。

它不提供「差距多大才需要行动」的阈值。 差距达到多少就必须采取培养行动，属于机构的人才管理决策——有些单位任何缺口都要求行动，有些则容忍一定差距——所以 LG-004 的阈值初始为 0，在你设置之前，该规则会在 skipped 里报告自己。

状态词表出厂为空，原因相同。日期规则只检查截止日期不早于完成日期，这是数据录入层面的属性：它不判断工作是否完成得晚了。

规则包里的每个 excerpt 都明确写着，条款原文未取得。 相关制度见 GB/T 19025（与 ISO 10015 等同）以及各机构的任职资格与培训规定。核验环节无法取得逐字条款原文，因此规则包在 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 |

它做什么

注册 learning_gap_check 工具。它读取一份差距与计划登记表 —— 员工表头，加上每个能力项一行 —— 套用带版本号的规则包，返回报告。

| 规则 | 检查内容 | 严重级别 | 依据类型 |
| LG-001 | 岗位和能力项都已记录 | warn | principle |
| LG-002 | 实际等级能解析为数字 | warn | principle |
| LG-003 | 差距等于要求等级减实际等级 | warn | principle |
| LG-004 | 差距超过你的阈值时必须带措施（默认关闭） | info | local |
| LG-005 | 措施要写明责任人和完成期限 | warn | principle |
| LG-006 | 完成期限不早于完成日期 | warn | principle |
| LG-007 | 状态取自你的词表（默认关闭） | info | local |

安装

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

配置

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

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

- LG-003 resultField / expression / tolerance —— 差距的算法，默认是 requiredLevel − actualLevel，不带容差。结果为负数时按原样报告，因为它可能意味着两列写反了。
- LG-004 triggerField / threshold / requiredField —— 你定的规则，规定措施何时变成必填。阈值为 0 表示规则不运行；1 表示差距达到一步或更多。
- LG-005 conditionField / requiredFields —— 什么情况下触发对责任人和完成期限的要求。
- LG-007 values —— 你的状态词表，例如 [未开始, 进行中, 已完成, 已验收]。留空表示不检查。

材料格式

工具接受 JSON 或 YAML：

employee: 张工 department: 设备部 plan: 2026 年度能力提升计划 cycle: 2026 上半年 rows:
- { 序号: '1', 岗位: 设备工程师, 能力项: 设备故障诊断, 要求等级: '4',
现有等级: '2', 差距等级: '2', 评估方法: 实操考核 + 主管评价, 评估日期: 2026-03-01, 培养措施: 安排为期三个月的现场带教与故障复盘, 责任人: 李主管, 完成期限: 2026-06-30, 完成日期: 2026-06-20, 状态: 进行中, 评估人: 王经理 } 列名匹配不区分大小写，并忽略空格、下划线和连字符；登记表自己的列名会保留，所以每条发现都会指明它读取的是哪一列。

规则来源

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

故障排查

- LG-002 在我的 熟练 等级上触发。 插件假定等级是数字，这样才能检查算术。请转换等级刻度，或者禁用 LG-002 和 LG-003。
- LG-003 触发，且「应为」是负数。 实际等级超过了要求的等级。要么是两列写反了，要么是该行记录的人资历过高；判断属于哪种情况，然后修正数据或禁用该规则。
- LG-004 从不运行。 它的阈值是 0；请设置一个缺口大小，达到该值就必须采取行动。
- LG-006 触发，但工作按时完成了。 该规则拿截止日期和完成日期比较，所以完成日期早于截止日期意味着两列写反了。它不会对逾期做出任何发现。
- LG-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-learning-gap-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-learning-gap-check # refresh src/shared from ../_shared

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

许可证

Apache License 2.0 © 2026 dsh-learning-gap-check contributors。