jfrog

JFrog Skill

所有 JFrog Agent 交互的基础技能。涵盖 JFrog Platform 概念、jf CLI 安装与认证，以及到工作流技能的意图路由。

一览（始终阅读的核心内容）

本会话中面向网络的 jf。在 <SID> 之前豁免：jf --version、 jf config show。

Tier A — 始终阅读的底线（在首次非豁免 jf 之前）：

• UA： 环境检查 执行一次 → 若退出码为 0/1，将其精确的 stdout 行导出为 JFROG_CLI_USER_AGENT，置于每个运行 jf 的 bash 顶部（切勿自行编造 / 重建 UA）
• CLI 提示： 在环境检查退出码 0/1 之后（跳过 jfrog-init / 仅 MCP）。NEWER_AVAILABLE → 绝不阻塞：立即 --clear（在任何其他命令之前），完成任务，在回复末尾附上升级说明；SKIP → 静默
• 服务： 解析默认值一次 → 在子命令之后使用 --server-id <SID>（jf api --server-id …，绝不 jf --server-id … api）。一个请求 → 一个服务（除非用户指定了多个服务，例如 compare <a> and <b>）
• 错误（401/403/404/超时）： 绝不切换服务。使用 AQL 列出仓库（本地或 <remote>-cache）。401 → 重新登录同一服务，然后一次重试（唯一允许的相同请求例外）。403/404/超时 → 绝不重新发起相同的路径 + 查询（package-block 403 → jfrog-package-curation）。空的 offset/page → 停止。分页器 ≤20 页。相同路径 403 → 停止（一次跳转）
• 不做预操作变更： 缺失的仓库/制品/构建 → 停止 + 报告；不得创建/复制/移动/上传以填补缺口（请求变通 ≠ 授权）
• 绝不猜测工具 / jf api 路径 → 工具列表 / --help / references/。404 → 停止（不进行猜测性重试）。jf api 需要产品前缀（/artifactory、/xray、……）。绝不使用 GET /api/v1/artifacts 列出仓库
• 硬性规则信号： 谨慎执行、 服务选择规则、 下方 注意事项 的 Tier A 条目 —— 不是提示
• 注意事项底线（Tier A）： 绝不使用交互式方式（jf config add、jf login、模板向导……）；如果调用带有 --server-id 却失败，不要在不用它的情况下重试；401 → 一次重新登录重试；403/404/超时 → 停止，绝不跳转或循环；--quiet 不是全局的 —— 添加前检查 --help

Tier B — 路径门控的 MUST（在 jf api / AQL / 高级 CLI I/O / 通过 shell 获取 MCP 结果的反模式之前）：完整 references/cli-gotchas.md、 references/jf-api.md、 references/preserving-command-output.md、 references/cli-command-discovery.md。 安装 / jf setup / 普通 CLI 不需要 Tier B。

Tier C — 按需： references/INDEX.md 领域参考；需要时查阅登录 / CLI 安装。

目录（优先阅读完整的 SKILL.md；如果你只看到顶部，一览 = Tier A 底线）：

章节	主题
工具选择策略	MCP vs CLI vs jf api
前置条件、环境检查	在首次非豁免 jf 之前
谨慎执行、服务选择规则	Tier A 硬性规则
注意事项 —— 硬性规则	Tier A 提醒；完整 cli-gotchas.md = Tier B
路径门控的基础参考	Tier B MUST 在 jf api / 高级 CLI 之前
何时阅读参考文件 → references/INDEX.md	Tier C 领域参考
命令发现 / jf api	当这些路径适用时属于 Tier B
结构化输入 / 批处理 / 保留输出	模板 / 并行 / 临时文件

部分读取的下限： 在首次非豁免 jf 之前，先读取 Tier A（本节）。尽可能优先使用完整的 SKILL.md。仅当 下一步操作需要 jf api / AQL / 高级 CLI I/O（检查清单）时，才加载 Tier B。领域 细节 → Tier C references/INDEX.md。

通过三个工具层级与 JFrog Platform 交互 —— 参见 工具选择策略。在代码示例中， <skill_path> 是本 skill 的目录，由 Agent 自动解析。 如果无法解析，请定位此 SKILL.md 文件并使用其父目录。

超出范围：MCP 服务管理。 安装、列出、移除或 配置 MCP 服务（例如"安装一个 MCP"、"我可以安装哪些 MCP"、 "列出我的 MCP"、"我可以使用哪些 MCP 服务"、"我批准的 MCP 目录里有什么"）由 JFrog Agent Guard 工作流 （@jfrog/agent-guard）处理 —— 这是一个单独的工作流，不是本 skill。

工具选择策略

按顺序尝试各层级；仅当当前层级不 覆盖该操作或执行失败时，才进入下一层级：

1. JFrog MCP 工具（首选）：针对 JFrog MCP 服务调用 CallMcpTool。从服务的工具列表中 发现可用工具；切勿猜测工具名称。
2. jf CLI 子命令（回退）：专用命令，例如 jf rt upload、jf rt dl、jf build-publish。
3. jf api（最后手段）：没有专用 子命令的 REST/GraphQL 端点。先验证路径 —— 参见 谨慎执行中的规则 6。

MCP 和 CLI 可能使用不同的令牌作用域。遇到一次 403 → 尝试另一个 层级一次（package-block → jfrog-package-curation）。401 → 然后 对该 URL 重试一次。

前置条件

以下工具必须在 PATH 上可用：

工具	用途
jq	解析 CLI 和 API 输出的 JSON

来自 Tier 2 和 Tier 3 的所有 JFrog HTTP 流量都通过 jf CLI 本身 （jf api，参见下文使用 jf api 调用平台 API）—— 任何 JFrog 交互都不需要独立的 curl。

JFrog 调用的运行时权限。 所有涉及网络的 jf 调用 都需要来自 Agent 运行时的出站 HTTPS 升级。保存 ~/.jfrog/ 凭据（登录期间的 jf config add）额外需要 文件系统写入升级。

运行时	网络	网络 + ~/.jfrog/ 写入
Cursor	required_permissions: ["full_network"]	required_permissions: ["all"]
Claude Code	allowed-tools: Bash(jf:*) + 主机允许列表	同上 + 文件系统允许列表
其他	在运行时/沙箱层配置	同上

如果 jf 以退出码 1 退出且输出为空，运行时的网络门禁是 首先要检查的事项 —— 使用上述适当的升级重新运行。

环境检查

MCP（Tier 1）跳过此检查 —— 直接继续。在本次会话的首次 Tier 2 或 Tier 3（jf）操作之前，运行环境检查。在退出码 0/1 时，逐字记住其 stdout 行作为本会话余下时间的 <UA>。在 jfrog-init 期间跳过 CLI 提议。

bash <skill_path>/scripts/check-environment.sh <model-slug>
# exit 0/1 stdout: exactly one opaque line — that line IS <UA>. Copy it byte-for-byte.
# Do not parse, rebuild, or approximate the export value from this comment.
# stderr: JSON state (cached 24h at ${JFROG_CLI_HOME_DIR:-$HOME/.jfrog}/skills-cache/jfrog-skill-state.json)

然后，仅在退出码 0/1 时：

bash <skill_path>/scripts/cli-newer-version-offer.sh
# SKIP → continue the original task; do not mention the offer.
# NEWER_AVAILABLE <cli_version> <latest> (suggest_upgrade) → never block or ask
# mid-task. Immediately run (before any other command):
#   bash <skill_path>/scripts/cli-newer-version-offer.sh --clear
# Then finish the original task (success or failure) and end the final reply
# with this line verbatim as its very last line (no other upgrade mention):
#   JFrog CLI <latest> is available (you have <cli_version>). Upgrade? Yes / No
# Yes (later turn) → references/jfrog-cli-install-upgrade.md, then
# check-environment.sh --force (Tier 2/3 only on exit 0/1). No → silent.
# Next offer = next new latest. JFROG_CLI_AVOID_NEW_VERSION_WARNING=true → SKIP.

退出码 2/3 不产生 <UA>；遵循下面的退出码表，并且 不要继续到 Tier 2 或 3。

传入你自己的模型 slug，小写，带版本（例如 opus-4.7、 gpt-5.6-sol、gemini-2.5-pro、composer-2-fast）。这些是示例，不是 允许列表 —— 逐字输出新的/未列出的名称，而不是 unknown。不是 harness/角色（subagent、agent）或裸系列（claude、gpt）； 子 Agent 继承父级的 slug。仅当确实无法识别时才使用 unknown。

切勿编造 JFROG_CLI_USER_AGENT

退出码为 0/1 时，脚本的 stdout 行就是 <UA>——原样导出（切勿编造、重建或编辑）。退出码为 2/3 时，不存在 <UA>——切勿合成一个。当前 stdout 以 jfrog-skills/ 开头，而不是 model/。

• 父会话：如果缺少 <UA> 或它以 model/ 开头（旧格式）， 则丢弃它并重新运行 check-environment.sh。仅当新的退出码为 0/1 stdout 行不以 model/ 开头时，才导出该行；否则停止 （不要编造）。
• 子 Agent：仅使用父会话传入的确切 <UA>——切勿重新运行脚本或构造替代值。如果缺少该值或它以 model/ 开头，则停止（不要导出 / 不要编造）；不要重新运行。

每次 bash 调用只导出一次 JFROG_CLI_USER_AGENT

在每次运行 jf 的 bash 调用开头，导出一次 <UA>； 该次调用中的所有 jf 调用都会使用它：

export JFROG_CLI_USER_AGENT='<UA>'
export JFROG_CLI_AI_MODEL='<model-slug>'   # jf >= 2.120.0 emits ai-model/<slug> from this
jf config show
jf api /artifactory/api/system/version

JFROG_CLI_AI_MODEL 用于传递 CLI 无法从环境中推断出的模型；将它与 <UA> 一起导出（使用传给脚本的相同 <model-slug>）。较旧的 CLI 会忽略它；如果脚本记录了 slug，已记住的 <UA> 中就包含该 slug。

切勿对每次 jf 调用重复赋值（不要在每一行都写 JFROG_CLI_USER_AGENT='<UA>' jf …）。这是一个会话级全局不变量：它适用于会话中的每一次 jf 调用，包括遵循任何基于此基础技能的工作流技能时所进行的 jf 调用。本技能其他部分和 references/*.md 中的示例为便于阅读省略了导出操作——此规则是全局的。启动子 Agent 时，在其提示词中传入 <UA>（参见 切勿编造），并说明 CLI 升级提示是否已显示。子 Agent 不会显示升级提示：遇到 NEWER_AVAILABLE 时，它们会执行 --clear 并返回该行；父会话则在回复末尾附上提示。

退出码	含义
0	缓存为最新状态——CLI 已就绪（Tier 2 和 Tier 3 可用），继续
1	缓存已刷新——CLI 已就绪（Tier 2 和 Tier 3 可用），继续
2	未安装 jf——Tier 2 和 Tier 3 不可用；仅剩 MCP（Tier 1）
3	jf 低于最低版本——Tier 2 和 Tier 3 不可用；仅剩 MCP（Tier 1）

退出码为 2 或 3 时，stdout 不会输出 <UA>。切勿根据本文档或 jf --version 编造或手动拼出一个。

退出码为 2 或 3 并非致命错误。尝试安装或升级 CLI （参见 references/jfrog-cli-install-upgrade.md）。如果安装成功， 重新运行环境检查。如果无法安装（没有权限、环境受限），则仅使用 MCP（Tier 1）。jf CLI 命令（Tier 2）和 jf api（Tier 3）都需要正常运行的 jf 安装。

JSON 解析（jq）

对 CLI 和 API 输出进行所有 JSON 解析时（管道、-r、筛选器），都使用 jq。

~/.jfrog/skills-cache/ — 仅允许存放指定文件

${JFROG_CLI_HOME_DIR:-$HOME/.jfrog}/skills-cache/ 不是通用临时或暂存目录。仅将其用于以下两种文件：

1. jfrog-skill-state.json——由 scripts/check-environment.sh 写入 （24 小时 CLI 检查缓存）。
2. onemodel-schema-${JFROG_SERVER_ID}.graphql——缓存的 OneModel 超图架构（参见 references/onemodel-graphql.md）。

切勿在 skills-cache/ 下保存 HTTP 响应正文、GraphQL 查询结果、临时 JSON、报告或其他临时文件。使用 JF_TMP=$(mktemp -d) && echo "$JF_TMP" 创建一个私有的会话级目录，并将这些文件写入其中（切勿直接在 /tmp 中使用可预测的名称）；在后续 Shell 步骤中重复使用回显的目录——采用下文保留命令输出中的相同模式。

谨慎执行

硬性规则 — 绝不跳过。 禁止投机性 / 准备性 / 猜测性操作。在任何 JFrog CLI 命令、MCP 工具调用或 API 调用之前：

1. 确认该操作是完成用户请求所必需的。 如果请求含糊不清或可能指向多个系统（例如 "builds" 可能指 Artifactory build-info 或 CI/CD 流水线运行）， 向用户请求澄清，而不是猜测。绝不从错误的系统获取数据 — 错误的答案比提问更糟糕。
2. 使用下方的 服务选择规则 确定目标服务 — 对于使用哪个服务，绝不能存在任何歧义
3. 对于变更操作（创建、更新、删除、上传），除非意图明确无误， 否则需与用户确认。这适用于所有层级 （MCP 工具、CLI 命令以及带 POST/PUT/DELETE 的 jf api）。
4. 优先使用读取操作，先了解当前状态，再进行更改
5. 绝不凭空捏造准备性变更。 如果请求的操作因未满足前置条件而失败 （指定仓库中缺少构件、 仓库不存在、包不在预期位置、未找到构建），停止并向用户报告该缺口。 不要执行复制、移动、上传、创建仓库或任何其他变更操作来满足 前置条件。"把它放进去好让下载成功"、"让它能用" 或 "做你需要做的任何事" 仍然是绕过手段 — 并非凭空捏造 缺失构件的许可。只有当该变更操作就是 用户请求的工作（发布此文件、创建此仓库、移动此 构件）时才可执行，而不是为了让另一个操作成功而充当辅助。这些 "辅助"变更 可能产生用户未曾考虑到的连锁影响 — 虚拟仓库 解析变化、存储配额消耗、复制触发、Xray 重新索引或权限传播。
6. 绝不猜测工具名称或 API 路径。 对于 MCP 工具，确认该工具 存在于服务的工具列表中。对于 jf api 路径，对照 <skill_path>/references/ 进行验证（或 JFrog OpenAPI specifications 如果你有网络访问权限）。遇到 404 时，停止并报告 — 绝不使用猜测的 替代路径重试。
7. 绝不在循环中重试失败的调用。 对 <repo>-cache 使用 AQL（虚拟仓库 不是 -cache）。401 → 然后重试一次。分页器上限 20 页 — cli-gotchas.md。不要凭空捏造 GET /api/v1/artifacts。

服务选择规则（强制）

硬性规则 — 绝不跳过或放宽。 错误服务的答案和静默 切换服务比停下来询问更糟糕。

单一服务不变式。 在解析出 <SID> 之后，每一个后续的 面向网络的 jf 调用都必须传入 --server-id <SID>（默认值在下方解析）； 在此之前，引导阶段的 jf --version / jf config show 保持豁免。对于一次用户 请求，所有网络 jf 调用使用恰好一个 server-id — 除非用户 指定要比较的服务（例如 compare <a> and <b>），此时每次调用都传入 各自目标的 --server-id。

JFrog MCP 和 CLI 使用独立认证。 MCP 工具通过 MCP 服务会话进行认证（而非 jf config）；CLI 命令通过 jf config 进行认证。如果你通过 jf config use 切换 CLI 目标服务， MCP 连接仍指向其原始服务。不要在同一会话中混用指向 不同服务的 MCP 和 CLI 调用。如果用户要求切换服务，请警告 MCP 工具将继续指向原始 服务，直到重新建立 MCP 连接。

绝不在 401/403/404、空结果或部分结果后于第二个已配置服务上 重试；绝不从 "my"/"our" 或从 jf config show 中看到额外条目 来推断多服务意图。覆盖： 仅当用户 明确指定另一个 id 时（"on <id>, …"、"use <id>"、"compare <a> and <b>"）— 推断的意图不构成覆盖。

每个会话只解析一次默认值

在首次调用 jf 之前，解析默认的 server-id，并在本次会话的其余时间内将其记作 <SID>，方式与 <UA> 相同：

jf config show 2>/dev/null \
  | awk '/^Server ID:/{id=$NF} /^Default:[[:space:]]*true/{print id; exit}'
# stdout: the default server-id; if empty, stop and ask which to use

后续每次调用 jf 都传入 --server-id <SID>。该标志位于子命令名称之后，而不是 jf 本身之后：

• ✅ jf api --server-id <SID> /artifactory/api/system/version
• ✅ jf rt ping --server-id <SID>
• ❌ jf --server-id <SID> api /… — 会因 flag provided but not defined 失败

启动子 Agent 时，在其提示词中传入 <SID> — 子 Agent 不会重新解析。此技能其他位置以及 references/*.md 中的示例为便于阅读省略了 --server-id；这条规则是全局规则，与 JFROG_CLI_USER_AGENT 相同。要添加新服务，请阅读 references/jfrog-login-flow.md。

出现任何错误时，停止 — 切勿切换

如果某次 jf 调用返回 403、404、网络错误、超时或任何其他非 401 失败，立即停止，不再调用 jf 并作出回复。遇到 401 → 重新登录同一服务，然后重试一次；如果仍然失败，就停止：

<server-id> 对 <endpoint> 返回了 <code>：<short reason>。其他 已配置的服务：<list> — 未经你的明确指示，我不会查询它们。你想如何继续？

路径门控的基础参考资料（调用 jf api / 使用高级 CLI 前必须阅读）

以下四个文件属于基础技能的 Tier B — 内容以前位于此 SKILL.md 中。它们不是可选的 INDEX 领域查找，也不要求在每条 CLI / setup 路径前阅读。

在调用 jf api、通过 jf api 使用 AQL、进行高级 CLI I/O（临时文件 / stdout-stderr 模式），或通过 shell/jq 处理 MCP 结果之前，必须完整阅读每个文件。普通的 jf（例如 jf setup、使用已知标志的 jf rt …）只需 Tier A（快速浏览）。

简短的 注意事项 Tier A 要点是本会话的基础 — 进入 Tier B 时，不能用它们替代完整的 references/cli-gotchas.md。

Tier B — 必须完整阅读（路径门控）	涵盖内容
references/cli-gotchas.md	注意事项、警告、已知问题、该做 / 不该做的事、I/O 和身份验证陷阱
references/jf-api.md	产品前缀表、标志、示例、GraphQL 负载
references/preserving-command-output.md	私有 mktemp -d 目录、不要为 jq 重新获取
references/cli-command-discovery.md	命名空间、顶层命令、Pipelines 退役

在 Tier B 路径上跳过其中任何文件 = 基础技能加载不完整 / 违反硬性规则。在仅限 Tier A 的路径（setup / 简单 CLI）上跳过它们，则不构成违规。

何时阅读参考文件

最好完整阅读此 SKILL.md。快速浏览 是部分阅读者的 Tier A 基础。上文的路径门控基础参考资料属于 Tier B（这些路径上必须阅读，并非每个会话都要阅读）。references/INDEX.md 中的其他所有内容均为 Tier C 领域细节 — 根据任务加载最相关的 2–3 个文件；跳过不涉及的领域。

references/INDEX.md 列出了所有 references/*.md 文件（Tier B + Tier C）。 添加 / 重命名 / 删除文件时 → 在同一变更中更新 INDEX — 若两者不一致，CI （tests/jfrog/test_reference_index_contract.py）将失败。

命令发现

运行 --help 验证选项 — 不要依赖记忆中的命令。

1. jf --help → 2. jf <namespace> --help → 3. jf <command> --help

Tier B — 依赖超出 --help 范围的命令发现之前，必须完整阅读： references/cli-command-discovery.md （命名空间、顶层生命周期 / 安全命令、Pipelines 退役）。

使用 jf api 调用平台 API

Platform REST/GraphQL 的第 3 层，自动完成身份验证。不要使用 jf rt curl / jf xr curl。 始终包含产品前缀 （/artifactory、/xray、/access 等）——省略会导致 404。

B 层——使用 jf api 前必须完整阅读： references/jf-api.md （前缀、标志、示例、OneModel GraphQL 负载）。正文输出到 stdout，状态输出到 stderr——参见 注意事项——硬性规则，切勿跳过 和完整的 cli-gotchas.md（B 层）。

结构化输入

交互式向导（jf rt rpt / ptt / rplt）不适用于 Agent。 通过 REST 获取现有配置并进行编辑：

jf api /artifactory/api/repositories/<repo-key>

更多 REST/模板模式 → 通过 references/INDEX.md 查看 references/artifactory-api-gaps.md 或 references/platform-admin-api-gaps.md。

注意事项——硬性规则（切勿跳过）

不是提示。 以下 A 层要点是必须始终阅读的最低要求。完整的 references/cli-gotchas.md 属于B 层——在使用 jf api / AQL / 高级 CLI I/O / 通过 Shell 使用 MCP 前，必须阅读；但每次使用 CLI 或 jf setup 前无需阅读。简短要点不能替代 B 层路径所需的完整文件。

A 层最低要求（每次非豁免的 jf 会话）：

• --quiet 并非全局选项——添加前先检查 --help
• --server-id： 如果调用因该选项失败，不要在不带该选项的情况下重试（可能会静默切换默认服务器）。参见服务器选择规则（强制）
• 仅限非交互模式——避免使用 jf config add、jf login、*template 向导；使用 references/jfrog-login-flow.md / REST
• 身份验证错误： 401 → 在同一台服务器上重新登录，然后重试一次。 403 → 停止（package-block → jfrog-package-curation）。404 → 路径错误，停止

B 层提醒（使用以下路径前，先加载完整的 cli-gotchas.md 和相关 B 层参考文档）：

• MCP： 直接读取结构化工具结果——不要通过 Shell / jq 传递
• jf api I/O： 正文 → stdout，状态 → stderr；将 stdout 传递给 jq； 绝不要使用 2>&1 | jq。不要使用 -L / -o——使用重定向：jf api … > "${JF_TMP:?}/<label>.json"
• 产品前缀是每个 jf api 路径的必需项（参见 B 层 jf-api.md）
• 不要为重试 jq 而重新获取数据——先保存输出 （保留命令输出 + B 层 preserving-command-output.md）

批量和并行执行

对于独立操作 → 采用最轻量的并行方式：(1) 在一个 Shell 中使用循环 / &，(2) 并行调用 Shell，(3) 对大规模扇出使用子 Agent。详情 → references/general-parallel-execution.md。

保留命令输出

将网络响应保存在私有的 mktemp -d 目录中（创建一次、输出路径并重复使用）；重新读取该文件以供 jq 使用——切勿为修正解析而重新运行同一个网络调用。

B 层——高级 I/O / 重新解析模式前必须完整阅读： references/preserving-command-output.md （JF_TMP 目录 + 输出路径，不重新获取 / 不跨上下文复用）。

运行 jf 之前 — 快速检查清单

一览 Tier A 底线；仅当下一个操作需要 jf api / 高级 CLI 时才添加 Tier B：

• export JFROG_CLI_USER_AGENT='<UA>' — check-environment.sh 退出码 0/1 的精确 stdout 行；CLI 提供已完成或 N/A（jfrog-init）；NEWER_AVAILABLE = 回复末尾备注，绝不中途停止任务
• 网络 jf：子命令之后加 --server-id <SID>（不是 jf --version / jf config show 前置 SID）
• 一个服务；出错 → 停止，不要切换（仅当用户指定 / compare 时才多服务）；不要为了填补空缺而做预先创建/复制/移动/上传
• 绝不猜测工具/路径 → list / --help / references/；404 → 停止；jf api 产品前缀；同一路径 403/404 → 停止（不分页）；绝不 GET /api/v1/artifacts
• Tier A 硬性规则：谨慎执行 + 服务选择 + 注意事项底线（交互式 / --server-id 重试 / 出错即停 / --quiet）
• Tier B（jf api / AQL / 高级 CLI I/O）：完整的 cli-gotchas.md、jf-api.md、preserving-command-output.md、cli-command-discovery.md