校验并迁移 OKF v0.2 知识包：用确定性…

需要验证、lint 或检查 Open Knowledge Format (OKF) bundle 是否符合 v0.2 规范（§11），或在对 bundle 提交改动前一致性检查/迁移时使用。

适用场景

解决思路

1. 对目标 bundle 运行确定性一致性检查器；未给路径时默认使用项目的 `.okf/` 目录：`uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS`。
2. 若 `uv` 不可用，回退执行：`python3 -m pip install --quiet pyyaml && python3 "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS`。
3. 用 `${CLAUDE_SKILL_DIR}` 定位脚本：无论技能作为 `okf` 插件运行还是独立安装（如 `npx skills add`），检查器都与技能同目录，始终能找到。
4. 把 ERROR 当作硬性 §11 不一致失败处理（无可解析 frontmatter、缺失或为空的 `type`、文件无法按 UTF-8 读取），说明 bundle 不符合规范，逐条全部修复。
5. 记住只有 `index.md` 和 `log.md` 是保留文件：按 §11.1，目录树中其它所有 `.md`（包括约定文件）都算 concept。因此放在 bundle 旁的 `AGENTS.md` 或 `README.md` 会报 ERROR，修复方式是给它加上带 `type` 的 frontmatter（`Document` 就合适）；不要用 skip-list 跳过（那会让检查器自身不符合规范）。若文件不属于知识内容，把它移到 bundle 根目录之上。
6. 把 warn 当作软性提示，逐项评估并在代价低时修复：缺失推荐字段、非 ISO 格式的 log 日期、跨链接断裂、v0.2 family 格式错误、脚注未指向任何来源、actor 不符合 §7 形状、Attested Computation 缺 `runtime`、computation 路径解析不到任何位置、在保留文件中出现 frontmatter（§8、§9）、根 `index.md` 带多余键或声明了不同的 `okf_version`（§12）。这些警告从不阻断，且规范 §6.1 明确容忍断链。
7. 优先处理 §7 的 near-miss 警告，例如 `Human:dana` 或 `human/dana`：§5.3 依据精确的小写 `human:` 前缀判定信任层级，写错会让概念被静默当成机器确认，而实际有人审阅过——见到就改。
8. v0.1 bundle 同样可以校验：旧的 `timestamp` 或 `# Citations` 段落会被报为 warning 并指出其 v0.2 替代（`generated.at`、`sources`），绝不会报 error（§13.1）。在 `--strict` 下这些警告会使运行失败，这是迁移的推动力，而 `--migrate` 是出路。
9. 迁移 v0.1 bundle 时用 `--migrate`：它会在校验前就地重写 bundle（本技能唯一的非只读模式），因此对用户未明确要求迁移的 bundle 运行前，先说明它会改动什么。迁移是文本级的（注释、键顺序、引号风格都保留）且幂等，命令示例：`uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" .okf --migrate --strict`。
10. 迁移具体动作：把 `timestamp` 提升为 `generated: { by: process:okf-migrate, at }`，把 `# Citations` 列表提升为 `sources`，并递增 `okf_version`。
11. 向用户重复两个迁移限制：pre-v0.2 内容的 `generated.by` 无法恢复（因此用 `process:` actor，概念在 §5.3 下正确保持 `unverified`）；v0.1 从未编码 per-claim `[^id]` 归属，所以只有来源列表会被提升。
12. 按退出码判断结果：存在任何 error，或警告数超过阈值即返回非零。`--strict` 不允许任何警告，`--max-warnings N` 允许 N 条，默认允许任意多条。加 `--json` 输出机器可读结果（在 CI 中有用）。

适用边界 · 注意事项

• 目标不是遵循 §11 规范的 OKF bundle（例如普通文档目录）时不适用。
• 用户未明确要求迁移时不要运行 `--migrate`，因为它会就地改写 bundle 文件。
• 不要通过 skip-list 排除 README.md/AGENTS.md 来消除报错，那会让检查器不符合规范；应补 frontmatter 或把文件移出 bundle 根目录。