mcpField
V
validate

validate

github.com/scaccogatto测试与质量433931 次安装今天更新
代码仓库

关于 validate

validate 是用于按确定性规则检查 OKF bundle 是否合规的技能。它报告错误和警告，支持适用于 CI 的 JSON 输出，也可在验证前迁移 v0.1 bundle。

主要功能

  1. 01确定性 bundle 合规检查
  2. 02报告错误与警告
  3. 03面向 CI 的 JSON 输出
  4. 04原地迁移 v0.1 bundle

适用场景

  1. 01分享前检查 OKF bundle
  2. 02在 CI 中运行合规检查
  3. 03将 v0.1 bundle 迁移到 v0.2

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/scaccogatto/okf-skills --skill validate

安装后在 Claude Code 中输入/validate确认已加载。

附带文件scripts/okf_validate.py

详细介绍

验证 OKF 包

对目标包运行确定性符合性检查器。未提供路径时，默认使用项目的 .okf/ 目录。

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

如果无法使用 uv，请改用：

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

无论此技能作为 okf 插件的一部分运行，还是独立安装（例如通过 npx skills add），${CLAUDE_SKILL_DIR} 都会解析到正确路径，因此总能在技能旁找到检查器。

解读结果：

  • ERROR → 严重的 §11 符合性失败（没有可解析的 frontmatter、type 缺失或为空，或检查器无法以 UTF-8 编码读取文件）。该包不符合规范。请修复所有此类问题。

只有 index.md 和 log.md 是保留文件：§11.1 规定，树中其他所有 .md 文件都是概念文件，包括约定文件。因此，将 AGENTS.md 或 README.md 放在包旁边会导致 ERROR，除非为其添加带有 type 的 frontmatter（Document 是合适的值）；这就是修复方法。添加跳过列表会导致检查器不符合规范。如果该文件不属于知识内容，请将其移到包根目录之外。

  • warn → 软性建议（缺少推荐字段、日志日期不是 ISO 格式、交叉链接失效、v0.2 家族格式错误、脚注未命名任何来源、actor 不符合 §7 格式、Attested Computation 缺少 runtime、计算路径无法解析到任何位置、保留文件中有 frontmatter（§8、§9）、根目录 index.md 带有额外键或声明了不同的 okf_version（§12））。不会阻止操作；规范明确允许存在失效链接（尤其是 §6.1 中的情况）。修复成本低时再修复。

有一条警告比其他警告更值得关注：§7 中看似符合但实际不符合的写法，例如 Human:dana 或 human/dana。§5.3 根据完全小写的 human: 前缀来确定信任层级，因此即使有人审核过，概念也会悄然显示为机器确认。发现后请立即修复。

v0.1 包也能通过验证：旧版 timestamp 或 # Citations 部分会作为警告报告，并指出对应的 v0.2 替代项（generated.at、sources），不会报错（§13.1）。使用 --strict 时，这些警告会导致运行失败——这正是迁移提示，而 --migrate 就是迁移入口。

迁移 v0.1 包

--migrate 会在验证前直接重写包中的内容——这是此技能唯一非只读的模式，因此在对用户未要求迁移的包运行之前，请先说明它会改动哪些内容。该操作按文本进行（注释、键顺序和引号都会保留），且具备幂等性。

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: actor；根据 §5.3，该概念会正确地保持为 unverified），而 v0.1 从未记录过逐条声明的 [^id] 归属信息，因此只会提升来源列表。

退出代码

如果存在任何错误，或警告超过限制，则返回非零代码： --strict 不允许有任何警告，--max-warnings N 允许 N 条，默认允许任意数量。添加 --json 可输出机器可读结果（适用于 CI）。

评论

支持 Markdown