Back to Details

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
If 
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
or 
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
or 
# 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
to 
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环境）。