JFrog State Persistence 是一个用于管理引导清单（onboarding manifest）持久化的技能，目的是为引导过程保留审计轨迹。它支持两种存储后端，具体使用哪一种由清单中的 state.destination 字段决定，默认值为 artifactory。
一、用途 该技能负责在 JFrog 项目引导流程中保存和读取配置清单快照。它既可以在引导开始前检查是否已有历史清单，也可以在引导完成后将最终清单上传或推送保存。
二、两种后端
- Artifactory（默认）：将清单存储在专用的 JFrog 通用（generic）仓库中。
- Git：将清单提交并推送到一个 Git 仓库。
三、输入参数（来自清单的 state 段）
- state.destination：默认 artifactory，可选 artifactory 或 git。
- state.artifactory.project：默认 system，用于存储清单的 JFrog 项目键。
- state.artifactory.repository：默认 system-configuration，项目内的通用仓库键。
- state.git.repo：使用 git 时必填，格式为 owner/repo。
- state.git.path：默认 /，Git 仓库中的目录路径。
- state.git.branch：默认 main，提交的目标分支。 如果清单中缺少 state 段，则默认使用 Artifactory，项目为 system、仓库为 system-configuration。
四、常量
- 上传路径模式：<ISO-8601-timestamp>/jfrog-configuration-manifest.yaml
- 时间戳格式：YYYY-MM-DDTHH-MM-SSZ（例如 2026-02-17T15-30-00Z）
- Artifactory 与 Git 两种后端使用相同的路径模式。
五、安全（Artifactory 后端） Artifactory 状态项目仅限平台管理员访问：所有 admin_privileges 均设为 false（项目级管理员无法管理成员或资源）；不会向该项目添加任何用户或组；只有平台管理员令牌（用于引导操作）具有读写权限。不要将状态项目包含在清单的 jfrog_projects 列表中，它是由引导代理管理的内部基础设施。此规则同时适用于默认的 system 项目以及通过 state.artifactory.project 配置的自定义项目。
六、路由 在执行任何操作前，先从清单读取 state.destination（默认 artifactory），再分支到对应后端的操作。
七、操作概览 0. 加载凭据：若 JFROG_URL 或 JFROG_ACCESS_TOKEN 为空，则尝试从 .env 文件加载。 随后读取可配置参数（Artifactory 与 Git 后端各自的参数）。
Artifactory 后端操作：
- 操作 A：确保项目与仓库存在（幂等）。包括检查/创建项目、验证没有意外成员、检查/创建仓库。创建项目时所有 admin_privileges 设为 false；创建仓库为 local、generic 类型并归属该项目。409（已存在）视为成功。
- 操作 B：列出并下载已有清单。列出快照文件夹、按 ISO-8601 时间戳排序取最新并下载、列出所有带时间戳的快照。
- 操作 C：上传清单。使用时间戳路径 PUT 上传 jfrog-configuration-manifest.yaml，并提供 curl 作为回退方式。
Git 后端操作：
- 操作 D：验证 Git 仓库可访问（git ls-remote）。
- 操作 E：列出并下载已有清单（浅克隆、列出时间戳文件夹、取最新清单、清理临时目录）。
- 操作 F：上传清单（克隆、写入时间戳目录、提交并推送、清理）。
八、错误处理
- 409 Conflict：项目或仓库已存在，视为成功（Artifactory）。
- 403 Forbidden：令牌缺少平台管理员权限，应报告给用户（Artifactory）。
- 列出/下载时 404 Not Found：尚无清单，不是错误，正常继续。
- Git 推送失败：警告用户，建议检查凭据与分支保护规则。
- 若上传/推送失败，警告用户但不中止整体引导（清单是便利功能，不是硬性要求）。
九、在编排技能中的使用 编排技能 jfrog-project-onboarding 在两个时点调用本技能：
- 预检（步骤 0）：读取 state.destination。Artifactory 调用操作 A + B 确保仓库存在并检查历史清单；Git 调用操作 D + E 验证仓库并检查历史清单。若发现历史清单，提醒用户并提供检索最新清单的选项。
- 完成后（最后一步）：Artifactory 调用操作 C 上传；Git 调用操作 F 提交并推送。
十、限制与说明 该技能依赖 jf CLI（jf api）执行操作，curl 作为回退。Artifactory 状态项目为内部基础设施，不应纳入清单的 jfrog_projects 列表。清单上传/推送失败不会中止引导流程。关于具体收费、价格、平台支持范围等，资料中暂未提供。