validate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Validate an OKF bundle

验证OKF包

Run the deterministic conformance checker against the target bundle. Default to the project's

.okf/

directory when no path is given.

bash

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS

uv

is unavailable, fall back to:

bash

python3 -m pip install --quiet pyyaml && \
python3 "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS

${CLAUDE_SKILL_DIR}

resolves whether this skill runs as part of the

okf

plugin or is installed standalone (e.g. via

npx skills add

), so the checker is always found alongside the skill.

Interpret the result:

ERROR → a hard §11 conformance failure (no parseable frontmatter, or a missing/empty
```
type
```
). The bundle is non-conformant. Fix every one.
warn → soft guidance (missing recommended field, non-ISO log date, broken cross-link, a malformed v0.2 family, a footnote naming no source, an actor that misses the §7 shapes, a computation path that resolves nowhere). Never blocks; broken links in particular are explicitly tolerated by the spec (§6.1). Fix when cheap.

One warning is worth more than the others: a §7 near-miss such as

Human:dana

human/dana

. §5.3 keys trust tiers off the exact lowercase

human:

prefix, so the concept silently reads as machine-confirmed when a person did review it. Fix that one on sight.

v0.1 bundles validate too: a legacy

timestamp

# Citations

section is reported as a warning naming its v0.2 replacement (

generated.at

sources

), never as an error (§13.1). Under

--strict

those warnings do fail the run — that is the migration nudge, and

--migrate

is the door.

针对目标包运行确定性合规检查器。若未指定路径，默认使用项目的

.okf/

目录。

bash

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS

若

uv

不可用，可使用备用命令：

bash

python3 -m pip install --quiet pyyaml && \
python3 "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS

${CLAUDE_SKILL_DIR}

会自动解析该技能是作为

okf

插件运行还是独立安装（例如通过

npx skills add

），因此检查器始终与技能文件存放在一起。

结果解读：

ERROR → 违反第11节的硬性合规要求（无可解析的前置元数据，或
```
type
```
字段缺失/为空）。该包不符合规范。必须修复所有错误。
warn → 软性指导建议（缺失推荐字段、非ISO格式的日志日期、失效的交叉链接、格式错误的v0.2家族、未标注来源的脚注、不符合第7节格式的参与者、无法解析的计算路径）。此类警告不会阻止流程；尤其是失效链接，规范第6.1节明确允许存在。若修复成本低则建议修复。

其中有一个警告需要重点关注：接近第7节格式但存在错误的情况，例如

Human:dana

或

human/dana

。第5.3节的信任层级依赖于精确的小写前缀

human:

，因此如果是人工审核的内容却使用了错误格式，会被默认为机器确认的内容。遇到此类情况必须立即修复。

v0.1版本的包也可进行验证：旧版的

timestamp

或

# Citations

部分会被标记为警告，并提示对应的v0.2替代字段（

generated.at

、

sources

），不会被判定为错误（第13.1节）。在

--strict

模式下，这些警告会导致运行失败——这是迁移提示，而

--migrate

参数则是迁移入口。

Migrating a v0.1 bundle

迁移v0.1版本的包

--migrate

rewrites the bundle in place before validating — the one mode of this skill that is not read-only, so say what it will touch before running it on a bundle the user has not asked to migrate. It is textual (comments, key order and quoting survive) and idempotent.

bash

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" .okf --migrate --strict

It hoists

timestamp

generated: { by: process:okf-migrate, at }

, lifts a

# Citations

list into

sources

, and bumps

okf_version

. Two limits worth repeating to the user:

generated.by

cannot be recovered for pre-v0.2 content (hence the

process:

actor — the concept stays correctly

unverified

under §5.3), and per-claim

[^id]

attribution was never encoded in v0.1, so only the source list moves up.

--migrate

参数会在验证前就地重写包内容——这是该技能中唯一非只读的模式，因此在用户未明确要求迁移的包上运行该命令前，需告知用户它会修改哪些内容。该操作是基于文本的（注释、键的顺序和引号都会保留），且具有幂等性。

bash

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" .okf --migrate --strict

它会将

timestamp

字段升级为

generated: { by: process:okf-migrate, at }

，将

# Citations

列表移至

sources

字段，并更新

okf_version

。需要向用户说明两个限制：对于v0.2之前的内容，无法恢复

generated.by

字段（因此使用

process:

参与者——根据第5.3节，该内容会被正确标记为

unverified

）；另外v0.1版本从未编码每条声明的

[^id]

属性，因此仅会将来源列表移至顶层。

Exit codes

退出码

Non-zero if any error is present, or if warnings exceed the gate:

--strict

allows none,

--max-warnings N

allows N, the default allows any. Add

--json

for machine-readable output (useful in CI).

若存在任何错误，或警告数量超过限制，退出码为非零：

--strict

模式不允许任何警告，

--max-warnings N

允许最多N个警告，默认模式允许任意数量的警告。添加

--json

参数可获取机器可读的输出（适用于CI环境）。