kb-lint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

kb-lint — health-check the bundle

kb-lint — 知识包健康检查

Keep a bundle trustworthy as it compounds by catching drift — the decay a growing knowledge base accumulates. Two passes: a deterministic conformance check (mechanical, scripted) and a drift audit (fuzzy, judgment). Run both; report findings by severity. With

fix

, repair what is safe.

随着知识库不断扩充，会逐渐出现“漂移”（即知识库增长过程中产生的衰退问题），使用kb-lint可确保bundle的可信度。该工具包含两个检查阶段：确定性合规性检查（机械、脚本化）和漂移审计（模糊、基于判断）。需运行这两个阶段，并按严重程度报告结果。启用

fix

模式可修复安全的问题。

1. Conformance (deterministic)

1. 合规性检查（确定性）

For a bundle-wide format or lifecycle migration, first inventory active metadata with the same frontmatter-aware checker:

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

The inventory parses only each concept's leading YAML frontmatter and reports body

# Citations

separately. Its

observations

include counts and exact paths for every active top-level key and status value;

legacy_citations

counts citation sections, numbered items, separately defined footnote sources, total source records, and common citation shapes;

structured_sources

counts the postflight concepts, entries, and entries carrying

resource

. An absent observation means zero. Do not use repository-wide grep to classify active metadata because prose and fenced examples can contain inactive field names and lifecycle values. Resolve every reported frontmatter error before planning from the counts.

Run the bundled checker against the target bundle (default

knowledge/

). It is a zero-dependency Node script (

node >=18

);

<skill-dir>

is this skill's directory —

${CLAUDE_SKILL_DIR}

under Claude Code, or whatever path your host exposes for the skill:

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

It reports ERROR for a hard SPEC §11 failure and warn for producer-profile defects in optional v0.2 fields, broken links, non-ISO log dates, and stale dates. Optional-family warnings never make the bundle non-conformant. Broken links are explicitly tolerated by §6.1.

Completion criterion: the checker has run and every ERROR it reported is listed for the report (and fixed, if in

fix

mode).

若要进行全包范围的格式或生命周期迁移，首先使用支持前置元数据的检查工具盘点活跃元数据：

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

该盘点工具仅解析每个概念开头的YAML前置元数据，并单独报告正文的

# Citations

部分。其

observations

字段包含每个活跃顶级键和状态值的计数及精确路径；

legacy_citations

字段统计引用章节、编号条目、单独定义的脚注来源、总来源记录数以及常见引用格式；

structured_sources

字段统计后期处理的概念、条目以及带有

resource

的条目。未出现的观测项表示数量为0。请勿使用仓库全局grep来分类活跃元数据，因为散文内容和代码示例中可能包含非活跃字段名和生命周期值。在根据计数制定计划前，需解决所有报告的前置元数据错误。

针对目标包（默认路径为

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. Drift audit (judgment)

2. 漂移审计（基于判断）

The checker can't see meaning. Audit the bundle for the ways a compounding artifact rots — this is the legwork that makes lint worth running. Cover every check:

Contradictions — concepts asserting conflicting facts that aren't linked
```
conflicts_with
```
.
Stale claims — statements a newer source has superseded but that were never marked
```
superseded_by
```
; overviews behind their children.
Orphans — concepts with zero inbound cross-links (index/log exempt; overviews exempt).
Missing cross-references — concepts about the same entity/theme that don't link to each other.
Coverage gaps — entities named repeatedly across concepts but lacking their own concept; data gaps a source or web search could fill.
Provenance gaps — concepts making external claims with neither OKF v0.2
```
sources
```
nor a legacy
```
# Citations
```
/ Reference trail.
v0.2 metadata drift —
```
sources
```
entries without
```
resource
```
, footnote labels without a matching
```
sources[].id
```
, malformed
```
generated
```
/
```
verified
```
actors or dates, invalid lifecycle values, and Attested Computations missing their required runtime or computation contract.
Repository drift — for living repository documentation, missing paths in
```
sources[].resource
```
, evidence that no longer supports the documented behavior, or source changes since
```
spec/repository_state.md
```
's
```
documented_revision
```
that affect a concept without a corresponding update. A lingering
```
documented_worktree: true
```
there requires comparison with the current working tree. Skip this check when repository evidence or Git history is unavailable.
Schema drift — types used but absent from
```
spec/types.md
```
; documented types that no longer describe their concepts; spelling/case variants; or one overloaded type hiding several recurring, materially distinct entity kinds. Treat unused documented types as Info, not an error.

Completion criterion: every check above has been run across the whole bundle and its findings recorded — not a sample.

检查工具无法识别语义内容。需审计包中复合工件出现衰退的情况——这是让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
```
中未定义的类型；文档化类型不再描述其对应概念；拼写/大小写变体；单个重载类型隐藏了多个重复、本质不同的实体类型。未使用的文档化类型视为信息提示，而非错误。

完成标准： 已对整个包运行上述所有检查项，并记录了所有发现——而非抽样检查。

3. Report

3. 报告

Present findings grouped by check, each tagged:

Error — §11 conformance failures. The bundle is non-conformant until fixed.
Warning — drift that degrades trust (contradictions, stale claims, orphans, broken links).
Info — suggestions (coverage gaps, new concepts or sources worth adding).

Turn coverage gaps into concrete next moves: questions to investigate, sources to ingest, or repository evidence to inspect through kb-document. Append a dated summary (counts + notable findings) to the bundle's

log.md

— append-only.

Completion criterion: a severity-grouped report is delivered and a

log.md

summary appended.

按检查项分组展示发现结果，每个结果标记如下：

Error：违反第11节合规性要求的问题。包在修复前不合规。
Warning：降低可信度的漂移问题（矛盾、过期声明、孤立项、无效链接）。
Info：建议项（覆盖缺口、值得添加的新概念或来源）。

将覆盖缺口转化为具体的下一步行动：需要调查的问题、需要导入的来源，或需要通过kb-document检查的仓库证据。在包的

log.md

中追加带日期的摘要（计数+重要发现）——仅允许追加内容。

完成标准： 已提交按严重程度分组的报告，并在

log.md

中追加了摘要。

Fix mode

修复模式

If invoked with

fix

, repair only what is safe and unambiguous, then re-report what was fixed vs. what needs a human:

Safe to auto-fix: stale overviews (regenerate from children), missing cross-links, malformed log dates, broken links with an obvious target, index entries out of sync with files.
Never auto-fix: anything that changes a claim's meaning. A contradiction or a stale claim is resolved by ingest under the trust model (supersede/conflict) — never by editing meaning in place here. Type renames, merges, splits, deprecations, and migrations also require user confirmation; report the proposed schema change and affected concepts together. Route living repository behavior that needs a meaning update to kb-document, which applies the trust model's narrow versioned-repository exception with source evidence and a revision log.

Completion criterion: every safe issue is fixed and every meaning-level issue is flagged (not touched); the re-report distinguishes the two.

若启用

fix

模式，仅修复安全且明确的问题，然后重新报告已修复项与需人工处理的项：

可安全自动修复的内容：过期的概述（从子内容重新生成）、缺失的交叉链接、格式错误的日志日期、有明确目标的无效链接、与文件不同步的索引条目。
禁止自动修复的内容：任何会改变声明语义的内容。矛盾或过期的声明需根据信任模型通过导入解决（取代/冲突）——绝不能在此处直接编辑语义内容。类型重命名、合并、拆分、弃用和迁移也需用户确认；需同时报告拟议的Schema变更及受影响的概念。对于需要更新语义的动态仓库行为，需交由kb-document处理，该工具会结合来源证据和修订日志，应用信任模型中针对版本化仓库的窄例外规则。

完成标准： 所有安全问题已修复，所有语义层面问题已标记（未修改）；重新报告需区分这两类问题。