用途
该技能面向需要在 JFrog 平台上确认某个软件包版本是否安全、并安全下载该包的场景。它把「查找包 → 确定最新版本 → 判断是否已在平台内 → 检查 curation 策略 → 下载」串成一条可执行的工作流，帮助使用者在下载前获得目录安全信号与策略判定结果。
主要能力
- 在 JFrog Public Catalog 中按包类型与名称查找包，获取 latestVersion。
- 当 Public Catalog 未命中时，回退到 JFrog Platform 的 Stored Packages 查找（含 1st/2nd party 包）。
- 判断指定版本是否已存在于 JFrog Platform，并获取仓库位置信息（repositoryKey、repositoryType、leadArtifactPath）。
- 检查 curation 权限（通过 /artifactory/api/system/version 判断 addons 是否含 curation）。
- 在具备 curation 权限时，调用 Xray curation API 检查该包版本在所有仓库中是否被策略放行。
- 通过 jf rt dl 从本地、联邦或远程仓库下载制品，并处理远程仓库未缓存时的透明拉取。
使用方式
前置条件：先阅读 ../jfrog/SKILL.md 了解 JFrog Platform 概念、领域模型、CLI 配置与 API 模式；在构造 GraphQL 字段或 where 过滤前，阅读 ../jfrog/references/onemodel-graphql.md 与 ../jfrog/references/onemodel-query-examples.md，必要时针对 GET "$JFROG_URL/onemodel/api/v1/supergraph/schema" 重新生成或校验查询。
工作流步骤：
- 查找包：已知包类型时用 publicPackages.getPackage(type:, name:) 并包含 latestVersion { version }；类型未知时用 publicPackages.searchPackages 配合 nameContains。未命中则用 storedPackages.searchPackages 或 storedPackages.getPackage 查找。两处都未找到则报告「package not found」并停止。若返回多个不同类型，需向用户确认包类型。
- 确定最新版本：Public Catalog 取 latestVersion.version；Stored Packages 取 latestVersionName 或 versionsConnection 中最高版本。
- 检查版本是否在 JFrog Platform：用 storedPackages.searchPackageVersions 配合 hasPackageWith 过滤，并请求 locationsConnection。找到位置即视为可安全下载，进入第 4 步；未找到进入第 5 步。
- 从 JFrog Platform 下载：使用 jf rt dl（二进制下载不走 jf api）。local 或 federated 仓库直接下载；remote 仓库需去掉尾部 -cache 后对基础远程仓库下载。target 必须是完整文件路径（如 ./downloads/lodash-4.18.1.tgz），不能是目录。
- 检查 curation 权限：执行 jf api /artifactory/api/system/version | jq '.addons | index("curation") != null'。
- 具备 curation 时，用 Xray curation API（/xray/api/v1/curation/package_status/all_repos，POST）检查策略：exit 0 表示放行，可经远程仓库下载；stderr 出现 returned 403 表示被策略阻止，需报告原因并停止；其他非零退出视为操作失败。不具备 curation 时，直接查找对应包类型的远程仓库并下载。
并行化：包类型已知时，可并行查询 Public Catalog 与 Stored Packages；确定版本后，可并行查询存储包版本与 curation 权限。每个 jf api 调用独立认证，无需在调用间传递 shell 状态。
制品路径模式（当 leadArtifactPath 不可用时）：npm 为 <repo>/<pkg>/-/<pkg>-<version>.tgz；pypi 为 <repo>/<pkg>/<version>/<pkg>-<version>.tar.gz；maven 为 <repo>/<group-path>/<artifact>/<version>/<artifact>-<version>.jar；go 为 <repo>/<module>/@v/<version>.zip。
适用场景
- 在引入第三方依赖前，确认其版本是否被 JFrog 目录收录、是否已在平台内、是否被 curation 策略放行。
- 需要从 Artifactory 的本地、联邦或远程仓库下载指定版本制品。
- 需要区分「平台内已有」与「需经远程仓库拉取」两种下载路径。
限制与注意事项
- 二进制下载必须用 jf rt dl，不能用 jf api；jf api 不暴露 -L / -o，也不透明跟随重定向到二进制内容。
- 对远程仓库下载时，应针对基础远程仓库（去掉 -cache 后缀），它会透明触发远程拉取并缓存。
- jf rt dl --flat 的 target 必须是文件路径，传目录会报「open path: is a directory」并重试四次后失败。
- curation 端点在 Xray 下，路径为 /xray/api/v1/curation/package_status/all_repos，不要加 /artifactory 前缀。
- curation 结果判读依赖 jf api 的退出码与 stderr 中的 returned NNN 行，而非 stdout 的 %{http_code}；需将 stderr 重定向到文件后结合 RC 与 grep 'returned 403' 分支。
- curation API 的 packageType 必须小写，且为 npm、pypi、maven、go、nuget、docker、gradle 之一，其他值会报错。
- 用户未指定包类型时，按名称搜索可能返回多个类型，需先向用户确认。
- 关于收费、价格、平台支持范围等未在资料中说明的信息，暂未提供。