schemafit icon

schemafit

schemafit 是一款本地优先的 CLI,用于检查 JSON Schema、结构化输出规范和工具定义是否符合主流 LLM 提供商约束,帮助团队在 CI 中提前发现并阻止上线前的提供商特定 schema 问题。

schemafit

概览

schemafit 是一款本地优先的 CLI,用于检查结构化输出、JSON Schema 和工具定义负载是否符合主流 LLM 提供商的约束面。页面将其定位为一种在提供商特定的 schema 失败到达生产环境之前就将其捕获的方法。

它不会等到 API 返回 400,而是会标出每个违规项对应的精确 JSON-Pointer 路径、关键字和原因,然后以非零状态退出,使 CI 能够让变更失败。它还提供尽力而为的修复流程、列出提供商的命令,以及可选的 live-verify 模式,用于检查静态规则包是否已与当前提供商文档发生漂移。

功能特性

静态 schema lint 检查

根据提供商特定的约束面检查 schema,并返回精确的 JSON-Pointer 路径、违反的关键字和原因。

版本化规则包

将提供商规则编码为声明式、版本化的规则包,使检查结果可审查,并与已记录的约束相对应,而不是依赖临时逻辑。

CI 强制执行与 SARIF 输出

以非零退出码失败,并可输出 SARIF,从而让违规问题阻止 CI,并在 GitHub 代码扫描中显现。

本地优先、离线运行

可离线运行,无需 API 密钥、无需模型调用,也没有运行时依赖,因此便于内置和审计。

schema 修复流程

包含修复命令,可通过删除或重写有问题的关键字,生成尽力而为、对提供商有效的变体。

提供商列表与漂移检测

提供 providers 命令,以及可选的 live-verify 模式,用于将静态规则包与提供商文档进行比较并检测漂移。

使用场景

  • 合并前的 schema 校验

    在构建流水线中使用 schemafit,提前捕获会在目标提供商上返回 400 的 schema,从而让拉取请求在有问题的 schema 发布前就失败。

  • 多提供商 schema 维护

    在支持多个 LLM 厂商时,对一组 schema 运行 lint 检查,以便尽早发现提供商特定的关键字冲突。

  • 尽力而为的 schema 修复

    当某个 schema 需要为特定 API 面进行适配时,使用修复命令生成一个对提供商有效的变体。

  • 代码扫描工作流

    当你希望 schema 违规出现在 GitHub 代码扫描或 Security 选项卡中时,生成 SARIF 输出。

  • 离线验证

    在网络受限环境中,从全新克隆的仓库运行演示或 lint 命令,因为核心工作流是离线且无需密钥的。

Pros and Cons

Pros

  • 可在本地运行,不需要 API 密钥、模型调用或运行时依赖。
  • 通过一个 schema lint 工作流即可面向多个主流提供商。
  • 会准确呈现失败的路径、关键字和原因,便于更直接地调试。
  • 可以在坏 schema 到达生产环境前让 CI 失败。
  • 为代码扫描工作流提供 SARIF 输出,并支持可选的 live-verify 漂移检查。

Cons

  • 源内容没有提供完整的支持矩阵、安装矩阵或平台限制,除了说明该 CLI 是静态且离线运行之外。
  • 修复流程被描述为尽力而为,因此并不保证能为每个 schema 生成完整或语义上完美的修复结果。

FAQ

schemafit 是做什么的?

它是一款本地优先的 CLI,用于根据 OpenAI、Anthropic、Gemini、Mistral 和 Cohere 的文档化约束面检查 schema。源内容还描述了用于检查、修复、列出受支持提供商以及运行密封式演示的命令。

schemafit 需要 API 密钥或模型调用吗?

源内容称它是静态且离线运行的,不需要 API 密钥,也没有运行时依赖。它可以在全新克隆后运行,或者在一次 pip install 之后运行。

schemafit 可以用于 CI 吗?

可以。产品描述说 lint 会以非零退出码结束,因此 CI 可以在 schema 到达生产环境之前让构建失败。它还提到可为 GitHub 代码扫描和 Security 选项卡输出 SARIF。

schemafit 覆盖哪些提供商?

页面明确列出了 OpenAI、Anthropic、Gemini、Mistral 和 Cohere 作为受支持提供商。它还说明提供商规则包是版本化的,并基于已记录的约束。

schemafit 只报告问题,还是也能修复 schema?

页面说明修复流程可以通过删除或重写有问题的关键字,输出一个尽力而为、对提供商有效的 schema 变体,同时尽量保留原意。它还提到 v0.5 中可选的 live-verify 模式用于检测漂移。

Quick Facts

类别
开发者工具
产品类型
CLI
许可证
MIT
运行方式
静态、离线
支持的提供商
OpenAI, Anthropic, Gemini, Mistral, Cohere
来源域名
danmercede.com