kb-lint

kb-lint — 检查知识包健康状况

通过捕捉偏移（知识库不断增长时累积的衰退），让知识包在不断积累的同时保持可信。分两轮：确定性一致性检查（机械化、脚本化）和偏移审计（模糊、依赖判断）。两者都要运行；按严重程度报告发现。使用 fix 时，修复安全的问题。

1. 一致性（确定性）

对于影响整个知识包的格式或生命周期迁移，先使用相同的、可识别 frontmatter 的检查器盘点活动元数据：

node "<skill-dir>/scripts/conformance.mjs" <bundle-dir> --inventory --json

该盘点只解析每个概念开头的 YAML frontmatter，并单独报告正文中的 # Citations。其 observations 包含每个活动顶层键和状态值的计数及精确路径；legacy_citations 统计引用章节、编号条目、单独定义的脚注来源、来源记录总数和常见引用格式；structured_sources 统计 postflight 概念、条目以及带有 resource 的条目。未出现的 observation 表示数量为零。不要使用全仓库 grep 对活动元数据进行分类，因为正文和围栏代码示例可能包含非活动字段名和生命周期值。根据统计数据制定计划之前，先解决所有报告的 frontmatter 错误。

使用捆绑的检查器检查目标知识包（默认为 knowledge/）。这是一个零依赖 Node 脚本（node >=18）；<skill-dir> 是此技能的目录——在 Claude Code 中为 ${CLAUDE_SKILL_DIR}，或使用宿主环境为该技能提供的路径：

node "<skill-dir>/scripts/conformance.mjs" <bundle-dir>

对于违反硬性 SPEC §11 的情况，它会报告 ERROR；对于可选 v0.2 字段中的生产者配置文件缺陷、失效链接、非 ISO 日志日期和过时日期，则报告 warn。可选字段族的警告不会导致知识包不符合规范。§6.1 明确允许存在失效链接。

**完成标准：**检查器已运行，且其报告的每个 ERROR 都已列入报告（若处于 fix 模式，则已修复）。

2. 漂移审计（判断）

检查器无法理解含义。请审计知识包中会导致累积性产物逐渐失真的各种情况——这些细致工作能让 lint 值得运行。检查以下所有项目：

• 矛盾 — 概念断言了相互冲突的事实，却没有通过 conflicts_with 建立关联。
• 过时声明 — 较新的来源已取代某些陈述，但这些陈述从未标记为 superseded_by；概述内容落后于其子项。
• 孤立项 — 没有任何入向交叉链接的概念（索引／日志除外；概述除外）。
• 缺少交叉引用 — 涉及同一实体／主题的概念没有相互链接。
• 覆盖缺口 — 多个概念反复提及某些实体，却没有为其建立独立概念；来源或网络搜索可以补足的数据缺口。
• 溯源缺口 — 概念提出外部声明，却既没有 OKF v0.2 sources，也没有旧版 # Citations／参考文献链路。
• v0.2 元数据漂移 — sources 条目缺少 resource、脚注标签没有匹配的 sources[].id、generated／verified 中的执行者或日期格式错误、生命周期值无效，以及缺少必需运行时或计算契约的 Attested Computations。
• 仓库漂移 — 对于持续更新的仓库文档，检查 sources[].resource 中是否缺少路径、证据是否已无法支持文档记录的行为，或自 spec/repository_state.md 的 documented_revision 以来，影响某个概念的源代码变更是否尚未同步更新。若其中仍有 documented_worktree: true，则需要与当前工作树进行比对。若仓库证据或 Git 历史不可用，请跳过此项检查。
• Schema 漂移 — 使用的类型未列入 spec/types.md；文档记录的类型已无法描述其概念；拼写／大小写变体；或某个过于宽泛的类型掩盖了几种反复出现且实质不同的实体类别。未使用的文档类型应视为 Info，而非错误。

完成标准： 已对整个知识包运行上述所有检查，并记录结果，而非仅抽查部分内容。

3. 报告

按检查项分组呈现发现，并分别标记：

• Error — 不符合 §11 的要求。修复前，知识包不符合规范。
• Warning — 降低可信度的漂移（矛盾、过时声明或孤立项、失效链接）。
• Info — 建议（覆盖缺口、值得添加的新概念或来源）。

将覆盖缺口转化为具体的后续行动：需要调查的问题、需要摄取的来源，或需要通过 kb-document 检查的仓库证据。将附日期的摘要（数量统计及重要发现）追加到知识包的 log.md 中——只追加，不改写。

完成标准： 已提交按严重程度分组的报告，并已将摘要追加到 log.md。

修复模式

如果以 fix 调用，只修复安全且明确无误的问题，然后重新报告已修复的问题与仍需人工处理的问题：

• 可安全自动修复： 过时的概述（根据子项重新生成）、缺失的交叉链接、格式错误的日志日期、存在明显目标的失效链接、与文件不同步的索引条目。
• 绝不自动修复： 任何会改变声明含义的内容。矛盾或过时的声明应遵循信任模型，通过 ingest 处理（supersede／conflict）——绝不能在此直接编辑其含义。类型重命名、合并、拆分、弃用和迁移也需要用户确认；应一并报告拟议的 Schema 变更及受影响的概念。需要更新含义的持续更新型仓库行为，应交由 kb-document 处理；它会应用信任模型中针对版本化仓库的有限例外，并提供来源证据和修订日志。

完成标准： 所有可安全修复的问题均已修复，所有涉及含义的问题均已标记（未改动）；重新报告中清楚区分这两类问题。