dx-org-snapshot-manage

dx-org-snapshot-manage

通过 sf org create snapshot、sf org get snapshot、sf org list snapshot 和 sf org delete snapshot，协调 Salesforce 临时组织快照的完整生命周期：创建、获取（状态）、列出和删除。快照是临时组织在某个时间点的副本（包含其元数据和数据）。你可以在临时组织定义文件中通过名称引用快照，以保存的状态为基础创建新组织。

---

工具限制

执行 sf org ... snapshot 命令时只能使用 Bash 工具。请勿使用 MCP 工具——完全忽略它们。

**用于评估/测试的输出产物：**只要有可用的输出目录，就必须始终将命令的完整 JSON 响应写入文件。请勿询问用户要写入哪个文件——此技能已指定文件名。每次执行命令后：(1) 如果用户指定了输出路径，立即写入该路径；(2) 否则运行 [ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output' 以检测评估目录；(3) 使用以下文件名，将命令完整且未经修改的 JSON 响应写入 <output-dir>/<filename>：create-snapshot-result.json、get-snapshot-result.json、list-snapshots-result.json 或 delete-snapshot-result.json。这是生成的输出——无需询问即可写入。(4) 如果通过以上任一检查都找不到输出目录，则在最终回复中原样包含命令完整且未经修改的 JSON 响应（例如放在围栏代码块中），不要省略该产物。

---

与其他技能的关系

此技能负责快照的完整生命周期——创建、获取状态、列出和删除。它不负责创建临时组织。

• 任何快照操作（创建、查看状态、列出、删除、检查过期情况）→ 使用此技能。
• 创建临时组织，包括使用现有快照创建（--snapshot <name>）→ 使用 dx-org-manage。
• 组织形状（不含数据的基准配置，sf org create/list/delete shape）→ 使用 dx-org-shape-manage。组织形状和快照是不同的产物，使用不同的命令——请参阅下方的比较。

	快照（此技能）	组织形状（dx-org-shape-manage）
捕获内容	某个时间点的完整副本：元数据和数据	仅基准配置：功能、限制、版本、Metadata API 设置
命令	sf org create/get/list/delete snapshot	sf org create/list/delete shape
引用方式	在临时组织定义文件中使用 snapshot（名称）	在临时组织定义文件中使用 sourceOrg（组织 ID）
前提条件	Dev Hub 已启用 Scratch Org Snapshots	源组织已启用 Org Shape for Scratch Orgs
操作对象	Dev Hub（--target-dev-hub）	源组织（--target-org）

---

范围

• 范围内：创建临时组织快照（sf org create snapshot）、获取状态（sf org get snapshot）、列出（sf org list snapshot）和删除（sf org delete snapshot）
• 范围外：创建组织形状（dx-org-shape-manage）、创建临时组织——包括使用快照创建（dx-org-manage）

---

必需输入

根据用户的请求推断：

• 操作：创建、获取、列出或删除（见工作流步骤 1）
• Dev Hub：拥有这些快照的 Dev Hub 的用户名或别名。通过 --target-dev-hub（-v）传入；如果已设置 target-dev-hub 配置变量，则为可选项。所有四个命令都针对 Dev Hub 操作，绝不能使用 --target-org。
• 源组织（仅创建）：要创建快照的 Scratch 组织 ID（以 00D 开头）、用户名或别名。通过 --source-org（-o）传入。
• 快照名称（仅创建）：快照的唯一名称，最多 15 个字符。通过 --name（-n）传入。
• 快照名称或 ID（仅获取和删除）：快照的名称或 ID（以 0Oo 开头）。通过 --snapshot（-s）传入。
• 描述（创建时可选）：记录快照内容。
• 到期阈值（天数）（仅列出即将到期的快照）：没有对应的 CLI 标志——这是针对 ExpirationDate 的客户端筛选条件（见命令模式）。

---

工作流

1. 确定操作，并与下方的命令模式匹配。
2. 解析 Dev Hub——如果未提供 --target-dev-hub，使用 sf config get target-dev-hub 检查默认值。切勿编造占位 Dev Hub 名称（例如 my-dev-hub）——无法解析 Hub 时必须停止；建议改用 sf org login web --set-default-dev-hub。
3. 创建时，确认源组织和快照名称——源组织必须是 Scratch 组织；名称必须在 Dev Hub 中唯一且不超过 15 个字符。
4. 使用 Bash 工具执行，并带上 --json 标志。
5. 报告结果（见输出要求和示例文件）。

命令模式

操作	用户意图	使用 Bash 工具执行
创建	仅指定名称来创建快照	sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --json
创建	创建快照并指定描述	sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --description "<desc>" --json
创建	显式指定 Dev Hub	sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --target-dev-hub <devHub> --json
获取	查看快照状态/详情	sf org get snapshot --snapshot <name|0Oo...> --json
列出	列出 Dev Hub 中的所有快照	sf org list snapshot --json
列出	列出 N 天内到期的快照	sf org list snapshot --json → 使用 jq 按 ExpirationDate 筛选（见 references/cli_flags.md）
删除	删除快照（会提示确认）	sf org delete snapshot --snapshot <name|0Oo...> --json
删除	删除时不提示确认（脚本/CI）	sf org delete snapshot --snapshot <name|0Oo...> --no-prompt --json
删除	删除多个/所有快照	先运行 sf org list snapshot --json，与用户确认目标名称，然后对每个快照分别运行一次 sf org delete snapshot --snapshot <name>——没有批量删除命令

快照创建是异步的。 create 会返回一条记录，其 Status 初始通常为 InProgress，而 ExpirationDate 仍为 null。在使用快照创建 Scratch 组织之前，使用 sf org get snapshot 轮询，直到确认 Status 为 Active（已在真实 Dev Hub 上进行实时验证——见 examples/create_success_output.json 与 examples/get_output.json）。

---

规则 / 约束

约束	原因
始终使用 --json 标志	提供结构化输出，便于可靠地解析和处理错误
所有命令都针对 Dev Hub 运行	使用 --target-dev-hub（而非 --target-org）——仅当已设置 target-dev-hub 配置时才可省略
Dev Hub 必须启用 Scratch Org Snapshots	否则命令会失败——请联系 Salesforce 启用该功能
源组织（创建时）必须是 scratch org	Snapshots 仅适用于 scratch org
Snapshot 名称在 Dev Hub 中必须 唯一，且不超过 15 个字符	名称过长会触发 STRING_TOO_LONG（已在线验证）
创建操作是异步的	create 可能会在 snapshot 变为 Active 之前返回——请使用 sf org get snapshot 轮询
没有更新、重命名或延长过期时间的命令。	已验证——CLI（以及底层平台对象）仅提供 create/get/list/delete。若要更改 snapshot 的名称、描述或过期时间，请将其删除并重新创建。
没有批量删除命令。	每次调用 sf org delete snapshot 都只会删除一个 snapshot
sf org list snapshot 不支持服务端筛选	会返回所有可见的 snapshot；请在客户端筛选状态/过期时间（例如使用 jq）
delete 默认会提示确认	在非交互式环境或 CI 中使用 --no-prompt（-p）
批量删除或使用 --no-prompt 删除时，必须先进行明确确认	删除多个或所有 snapshot 之前——或任何使用 --no-prompt 的删除操作之前——先运行 sf org list snapshot --json，向用户回显已确定的目标名称，并取得明确确认。删除操作不可撤销。
权限会影响可见性和删除权限	除非 Dev Hub 管理员授予 View All / Modify All 权限，否则用户只能查看/删除自己的 snapshot

---

故障排除

问题	解决方案
@salesforce/plugin-signups does not exist in the registry	Snapshot 命令位于 signups 插件中，该插件随常规 sf 安装一起提供。这意味着 CLI 环境不完整（精简/离线镜像）——请勿在离线环境中尝试 sf plugins install，这会失败并陷入循环。建议在联网的计算机上修复环境（运行 sf update 或重新安装）。
Scratch Org Snapshots isn't enabled for your Dev Hub.	Dev Hub 未启用 snapshot 功能——请联系 Salesforce 启用该功能
No snapshot found with the given name or id: <value> (SingleRecordQuery_NoRecords)	已在线验证——get/delete 找不到对应名称/ID；该 snapshot 在此 Dev Hub 中不存在。运行 sf org list snapshot --json 查看可用的 snapshot
STRING_TOO_LONG — "Org Snapshot Name: data value too large... (max length=15)"	已在线验证——--name 的值超过 15 个字符。请缩短后重试
Snapshot 名称已存在（DuplicateValue）	每个 Dev Hub 中的名称必须唯一——请选择其他名称
Status 一直是 InProgress	创建操作是异步的——请继续使用 sf org get snapshot 轮询，直到 Status 变为 Active
Status 为 Error（请查看 Error 字段）	阅读 Error 字段，删除失败的 snapshot，然后重新创建
NotADevHubError	目标组织不是 Dev Hub——请将 --target-dev-hub 指向实际的 Dev Hub
未找到默认 Dev Hub 组织	请提供 --target-dev-hub <alias>，或使用 sf config set target-dev-hub=<alias> 设置默认值

---

输出预期

使用 --json 时，所有命令都会返回 JSON。get/list 会返回原始的 OrgSnapshot sobject 记录 — 已通过实时验证，其中包含 sobject attributes 包装对象以及 Id、SnapshotName、Description、Status（New、InProgress、Active、Error、Expired 或 Deleted）、SourceOrg、CreatedDate、LastModifiedDate、ExpirationDate（在状态变为 Active 前为 null）和 Error。

• Create → 单条快照记录（创建后 Status 立即为 InProgress；ExpirationDate 为 null）。
• Get → 单条快照记录 — 可用它轮询 Status。
• List → 快照记录数组，按 CreatedDate 排序。若不存在任何记录，则返回空数组。
• Delete → { "id": "0Oo...", "success": true, "errors": [] }。如果用户拒绝确认提示，则不返回结果。

确切的响应结构请参阅下方的示例文件（这些示例是通过真实 Dev Hub 实时捕获的，并非假设）。

---

跨技能集成

需求	委托给
从快照创建临时组织	dx-org-manage 技能（在定义文件中将 snapshot 设为快照名称，或使用 --snapshot <name>）
创建/列出/删除组织 形状，而非快照	dx-org-shape-manage 技能

---

参考文件索引

文件	何时阅读
references/cli_flags.md	create/get/list/delete 的详细标志参考，包括用于筛选即将到期快照的 jq 管道
references/snapshot_usage.md	快照处于 Active 状态后，如何在临时组织定义文件中使用快照名称

示例文件

文件	用途
examples/create_success_output.json	成功创建快照（Status: InProgress）
examples/create_error_output.json	STRING_TOO_LONG — 名称超过 15 个字符
examples/get_output.json	获取 Active 快照的响应（已填充 ExpirationDate）
examples/list_output.json	列表响应 — 快照记录数组
examples/delete_output.json	成功删除响应