快速开始
本章带你从什么都没装走到读懂一条真实漏洞记录——每一步之后都有一小段说明，让你不只知道该敲什么，还明白刚刚发生了什么。
两条路
上手有两种方式，二选一。
- 路径 A —— 让 AI 替你做（推荐，"AI First"）。 如果你用 Claude Code 或 Codex，就不必手动安装任何东西。从 AI Agent 接入 页复制那段引导提示词，粘贴给你的智能体，它会自动安装 CLI、发现技能，然后开始干活。想知道为什么这样能行，直接跳到 启用 Claude Code 技能。
- 路径 B —— 自己动手。 手动安装 CLI 并逐条运行命令。这就是本页余下的内容。
第 1 步 —— 安装 CLI
挑一个适合你机器的方式。三种方式都以 osv version 结尾——它既确认安装成功，又打印所支持的 OSV schema 版本。
::: tabs == 预编译二进制（任意平台）
零依赖方案——不需要 Go 工具链。从 最新 Release 下载匹配你 OS/架构的二进制：
# Linux amd64 示例（把版本号与平台换成你自己的）。
# 将 v0.1.0 替换为 Releases 页面上最新的 tag。
VERSION=v0.1.0
curl -fsSL -o osv.tar.gz \
https://github.com/scagogogo/osv-schema-skills/releases/download/${VERSION}/osv_${VERSION}_linux_amd64.tar.gz
tar -xzf osv.tar.gz osv
sudo mv osv /usr/local/bin/
osv version二进制覆盖 Linux（amd64/arm64/arm）、macOS（amd64/arm64）与 Windows（amd64/arm64）。每个 Release 还附带 checksums.txt 供你校验完整性。若最新 release 暂无预编译资产，改用下方的 go install。
== go install
如果你已有 Go 1.18+：
go install github.com/scagogogo/osv-schema-skills/cmd/osv@latest
osv version它会把 osv 放进 $(go env GOPATH)/bin——确保该目录在你的 PATH 上。
== 源码构建
想改代码或构建某个特定提交：
git clone https://github.com/scagogogo/osv-schema-skills.git
cd osv-schema-skills
go build -o osv ./cmd/osv/
./osv version:::
刚刚发生了什么
你现在有了一个自包含的单文件二进制 osv。它把整个 Go 内核嵌在里面——没有运行时、没有配置文件、不用再装别的。下面所有内容，都是这一个二进制在读 JSON。
第 2 步 —— 解析你的第一条记录
拿仓库自带的样例来解析：
osv parse test_data/GHSA-vxv8-r8q2-63xw.json预期输出（节选）：
ID: GHSA-vxv8-r8q2-63xw
Schema Version: 1.4.0
Summary: ...
Aliases: CVE-2022-35981
CVE: CVE-2022-35981
Severity:
CVSS_V3: CVSS:3.1/... (score: 0.0)
Affected Packages:
...为什么分数是 0.0？
这里的 score 字段是 CVSS 向量字符串（CVSS:3.1/AV:N/…），不是数字。parse 调用的是 GetScore()，它对该字符串跑 strconv.ParseFloat——在向量字符串上必然失败，于是返回 0.0 并吞掉错误。这正是 方法清单页 记录的那个坑：要区分真实的 0.0 与向量字符串解析失败，请用 GetScoreAsFloat()（检查 err）或 GetScoreAsPointer()（检查 nil）。想从向量拿到数值分数，你得自行解析向量。
读懂输出
每一行都能对应回 项目介绍 里的某一层 OSV 模型：
| 输出行 | OSV 字段 | 含义 |
|---|---|---|
ID | id | 记录的唯一主键 |
Schema Version | schema_version | 遵循的 OSV 版本 |
Summary | summary | 一行人类可读描述 |
Severity → CVSS_V3 | severity[] | CVSS 向量，外加解析出的数值分数 |
Affected Packages | affected[] | 哪个生态 + 包 + 版本中招 |
想看全部——日期、关联 ID、完整详情、每个范围的事件？加 -v：
osv parse -v test_data/GHSA-vxv8-r8q2-63xw.json需要给脚本或智能体用的机器可读输出？加 -o json：
osv parse -o json test_data/GHSA-vxv8-r8q2-63xw.json第 3 步 —— 30 秒工作流
解析只是第一个动词。实践中你会串起好几个：
对着样例逐个动词试一遍：
osv validate test_data/GHSA-vxv8-r8q2-63xw.json # 是否合规？
osv filter -e PyPI test_data/GHSA-vxv8-r8q2-63xw.json # 只看受影响的 PyPI 项
osv query --severity cvss3 test_data/GHSA-vxv8-r8q2-63xw.json # CVSS v3 条目（向量 + 分数）四个命令分别给你什么
把它想成一条自然的递进：parse 看清它，validate 信任它，filter 缩小它，query 精确取出一个事实。逐个参数的详情见 CLI 参考。
第 4 步 —— 使用 Go SDK（可选）
如果你写的是 Go 而非驱动 Shell，同一个内核只差一个 import：
go get -u github.com/scagogogo/osv-schema-skillspackage main
import (
"fmt"
"log"
osv "github.com/scagogogo/osv-schema-skills"
)
func main() {
v, err := osv.UnmarshalFromJsonFile[any, any]("vulnerability.json")
if err != nil {
log.Fatal(err) // 构造器绝不静默返回 nil
}
fmt.Printf("ID: %s\n", v.ID)
fmt.Printf("CVE: %s\n", v.Aliases.GetCVE())
}[any, any] 这两个类型参数就是 EcosystemSpecific 和 DatabaseSpecific 泛型——通用解析用 any 即可，或者塞进你自己的结构体，对自定义字段获得带类型的访问。详见 Go SDK 指南。
启用 Claude Code 技能
这里就是 AI-First 的回报所在。在 Claude Code 中打开本仓库，7 个技能自动激活——无需插件、无需配置：
git clone https://github.com/scagogogo/osv-schema-skills.git
cd osv-schema-skills
claude # 技能已生效为什么零配置就能行：每个技能都是 .claude/skills/ 下的一个 SKILL.md 文件。Claude Code 在打开时发现它们，读取每个的 description（它的触发条件），当你的请求匹配时，就替你运行声明好的 osv 命令。你从不点名命令——你只描述意图。
每个技能何时触发见 技能总览，能同样用于 Codex 的复制粘贴提示词见 AI Agent 接入。
排错
| 现象 | 可能原因与解决 |
|---|---|
osv: command not found | 二进制不在 PATH 上。用 go install 的把 $(go env GOPATH)/bin 加进 PATH；用二进制的把它移到 /usr/local/bin。 |
at least one filter flag is required / at least one query flag is required | osv filter/osv query 至少需要一个选择标志——如 -e PyPI 或 --severity cvss3。filter 报错会列出它的三个（--ecosystem、--ref-type、--alias）；query 会列出它的四个（--severity、--maven、--ranges、--events）。 |
数值分数显示 0.0 | score 字段是 CVSS 向量字符串 而非数字——这是预期行为。见 方法清单 → severity。 |
Go < 1.18 上 go install 失败 | 泛型内核需要 Go 1.18+。运行 go version 并升级。 |
下一步
- CLI 参考 —— 每条命令与参数
- Skills 总览 —— 7 个自动触发的技能
- Go SDK 指南 —— 从 Go 带类型访问
- OSV Schema 参考 —— 完整数据模型