platform-sandbox-configure

Sandbox 生命周期管理

通过 Connect REST API 管理 Salesforce 沙盒环境 — 列出清单、激活或丢弃已完成的刷新、创建和刷新沙盒，以及永久删除沙盒。

此技能负责的任务

在以下工作中使用 platform-sandbox-configure：

• 列出或检索所有沙盒（GET /sandbox/reports）
• 按名称或 ID（07E 前缀）获取特定沙盒的详情或状态
• 按许可证类型检查许可证使用情况和剩余容量（GET /sandbox/licenses）
• 刷新完成后激活沙盒（应用刷新）
• 丢弃已完成的刷新（保留现有沙盒数据不变）
• 永久删除沙盒以释放许可证
• 验证激活或删除是否已完成
• 创建新的沙盒（Developer、Developer Pro、Partial Copy 或 Full）
• 使用最新生产数据刷新现有沙盒

以下情况请委派给其他技能：

• 克隆沙盒 → Tooling API（SandboxInfo sObject）
• 根据 SOP 生成复制后自动化 JSON 配置 → automation-sandbox-post-copy-config-generate
• 将复制后自动化 JSON 配置应用于沙盒或运行该配置 → automation-sandbox-post-copy-configure

---

帮助（交互式菜单）

用户输入 sandbox -help 或 sandbox help 时，只回复显示以下编号操作列表的文本消息。不要调用任何 API 或工具 — 只显示此菜单并等待用户回复编号。

Agent 必须按以下原样 Markdown 回复（不要放在代码块中 — 直接将其呈现为项目符号列表）：

Sandbox 生命周期管理

1. 清单与详情

• a. 列出所有沙盒 — 名称、类型、状态、ID
• b. 获取详情（按名称）— 状态、许可证、配置
• c. 获取详情（按 ID）— 直接提供 07E ID
• d. 检查许可证使用情况 — 按许可证类型查看可用数量与已用数量

2. 创建与刷新

• a. 创建新沙盒 — Dev、Dev Pro、Partial、Full
• b. 刷新沙盒 — 使用最新生产数据

3. 激活、丢弃与删除

• a. 激活沙盒 — 应用已完成的刷新
• b. 丢弃刷新 — 拒绝刷新，保留现有数据
• c. 删除沙盒 — 永久移除

4. 验证与监控

• a. 验证激活状态 — 检查激活是否已完成
• b. 验证删除状态 — 检查删除是否已完成

5. 复制后自动化

• a. 创建复制后自动化 JSON 配置 — 根据 SOP 生成配置
• b. 运行复制后自动化 — 将 JSON 配置应用于沙盒

请回复代码（例如“3a”），或描述你的需求。

用户回复后，询问所需信息：

选项	后续问题
1a	无需输入 — 立即继续
1b	“沙盒名称是什么？”
1c	“沙盒 ID 是什么？（以 07E 开头）”
1d	无需输入 — 立即继续
2a	首先调用 GET /sandbox/licenses（第 9 节）并显示可用数量与已用数量；然后询问名称和许可证类型（Developer、Developer_Pro、Partial_Copy、Full）
2b	首先调用 GET /sandbox/reports（第 1 节）并列出符合刷新条件的沙盒（isPendingActivation: false）；然后询问要刷新哪个沙盒
3a	“要操作哪个沙盒？请提供名称或 07E ID。”
3b	“要操作哪个沙盒？请提供名称或 07E ID。”
3c	“要操作哪个沙盒？请提供名称或 07E ID。”
4a	“你激活的是哪个沙盒？请提供名称或 07E ID。”
4b	“你删除的是哪个沙盒？请提供名称或 07E ID。”
5a	“正在委派给复制后配置生成器 — 请提供 SOP（文件、文本或截图）。”
5b	“正在委派给复制后配置运行器 — 请提供配置 JSON 文件和目标沙盒。”

执行下方对应的操作。**例外：**5a/5b 需要委派 — 5a → automation-sandbox-post-copy-config-generate；5b → automation-sandbox-post-copy-configure。此技能不实现复制后自动化；请勿直接生成或应用配置。

---

API 基础地址

重要： 在此技能中执行沙盒操作时，请使用 Connect REST API。存在两种发现方式：

• 按名称： 调用 GET /sandbox/reports 列出所有沙盒，并通过 sandboxName 找到匹配项。
• 按 ID（07E 前缀）： 直接调用 GET /sandbox/sandboxes/{sandboxId}——不要调用 /sandbox/reports。

这两种方式都会返回包含 sandboxId（前缀为 07E）的沙盒记录；所有生命周期变更操作都需要此 ID。

sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

完整的响应结构请参阅 references/api-response-shapes.md。

重要： 不要使用 Tooling API（SandboxInfo/SandboxProcess）进行发现——变更端点需要 Connect REST API 的 sandboxId（07E），而不是 SandboxInfo.Id（0GQ）或 SandboxProcess.Id（0GR）。

生命周期读取（状态、库存、详情、许可证、待激活）绝不要使用 SOQL / run_soql_query / sf data query。 这些数据仅存在于 Connect REST API 中——没有任何 SObject 会返回这些数据。（对 SandboxInfo 使用 sf data query --use-tooling-api 仍可用于 Create/Refresh 变更操作，但不能用于生命周期读取。）

按 API 返回的内容原样报告结果——绝不要编造错误或原因。 count: 0 是成功结果（不存在沙盒）——记录为 not_found，不要将其误判为失败，也不要改用 SOQL 重试。如果 API 返回错误，请逐字记录错误正文——不要推测原因（例如“必定是 scratch org”）；此端点不会报告组织版本或类型，所以任何此类猜测都是捏造。

所需权限：ManageSandboxes

不可逆操作——务必先确认

操作	不可逆原因
创建	会消耗所选类型的许可证
激活	使用刷新的数据覆盖沙盒
丢弃	刷新数据将丢失
删除	沙盒将被永久移除
使用 AutoActivate=true 刷新	完成后会自动应用——效果等同于激活

---

操作

1. 列出沙盒库存

端点： GET /services/data/v66.0/sandbox/reports

返回所有沙盒的列表，包含其 ID、名称、状态和许可证类型。

sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

完整的响应结构请参阅 references/api-response-shapes.md。

适用场景： 用户询问“列出我的所有沙盒”“我有多少个沙盒”“我的沙盒状态如何”

关键响应字段：

• sandbox.sandboxId（07E 前缀）——所有变更操作都需要此字段
• sandbox.sandboxName——沙盒名称（顶层字段）
• sandbox.license——Developer、Developer Pro、Partial Copy、Full
• sandbox.isPendingActivation——如果刷新等待激活，则为 true
• sandbox.canActivate / canDelete / canDiscard——权限标志

---

2. 获取沙盒详情

端点： GET /services/data/v66.0/sandbox/sandboxes/{sandboxId}

返回指定沙盒的详细信息。

适用场景： 用户询问特定沙盒的状态、配置或元数据。

关键响应字段：

• status——Active、Pending Activation、Activating、Completed 等
• isPendingActivation——如果刷新已完成且等待用户决定，则为 true
• sandboxType——Developer、DeveloperPro、PartialCopy、Full
• sourceId——源组织的 ID

---

3. 激活沙盒（应用刷新）

端点： PATCH /services/data/v66.0/sandbox/activate/{sandboxId}

关键领域规则： 此操作仅适用于已完成刷新且处于“Pending Activation”状态的沙盒。它会将刷新的数据应用到沙盒。它不会“使非活动沙盒重新上线”或“启动”沙盒。

前置条件：

• 沙盒必须处于 Pending Activation 状态
• 刷新必须已成功完成
• 用户必须拥有 ManageSandboxes 权限

调用 PATCH /activate 之前：

• 已通过 GET /sandbox/sandboxes/{id} 确认沙盒处于 Pending Activation 状态（isPendingActivation: true）
• 已确认刷新已成功完成
• 已获得用户明确确认——此操作会用刷新的数据覆盖沙盒，且无法撤销

适用情形： 用户说“激活它”“应用刷新”“使用最新数据”

激活后： 沙盒将使用新刷新的生产数据运行。

---

4. 验证激活

端点： GET /services/data/v66.0/sandbox/sandboxes/{sandboxId}

激活后轮询此端点，确认状态已变为 Active。这是验证步骤，不是独立的用户操作。

适用情形： Agent 需要确认激活已完成（在激活后自动调用）。

---

5. 丢弃沙盒（拒绝刷新）

端点： DELETE /services/data/v66.0/sandbox/discardsandbox/{sandboxId}

关键领域规则： 此操作仅适用于已完成刷新且处于“Pending Activation”状态的沙盒。它会拒绝此次刷新——现有沙盒会继续运行，当前数据保持不变。它不会：

• 释放许可证
• 软删除或隐藏沙盒
• 重置沙盒，使其与生产环境一致

前置条件：

• 沙盒必须处于 Pending Activation 状态
• 刷新必须已完成

调用 DELETE /discardsandbox 之前：

• 已通过 GET /sandbox/sandboxes/{id} 确认沙盒处于 Pending Activation 状态（isPendingActivation: true）
• 已确认这是丢弃操作（拒绝刷新），而不是删除操作（永久移除）
• 已获得用户明确确认——刷新数据将永久丢失且无法撤销

适用情形： 用户说“丢弃刷新”“保留现有数据”“不要应用刷新”“拒绝刷新”

警告： 丢弃操作无法撤销。如果用户之后想要获取最新生产数据，需要重新触发刷新。

---

6. 删除沙盒（永久）

端点： DELETE /services/data/v66.0/sandbox/deletesandbox/{sandboxId}

永久移除沙盒并释放许可证。

前置条件：

• 沙盒必须存在
• 用户必须拥有 ManageSandboxes 权限

调用 DELETE /deletesandbox 之前：

• 已向用户说明沙盒详情（名称、许可证、状态），并获得明确的删除批准

适用情形： 用户说“删除此沙盒”“永久移除它”“释放许可证”

警告： 此操作不可逆。执行前务必向用户确认。请展示沙盒名称、许可证和状态，以确保安全。

如果用户要求恢复已删除的沙盒： 目前没有记录任何恢复途径——请升级给 Support 处理，不要猜测恢复方法。

---

7. 创建新沙盒

从头创建一个新沙盒。支持两种方式——根据用户偏好选择；除非用户要求使用定义文件或可重复使用的 DX 蓝图，否则默认采用方式 A。

前提条件：

• 组织中必须有可用的所请求类型的许可证
• 沙盒名称必须唯一且尚未被使用
• 用户必须拥有 ManageSandboxes 权限

创建前——务必先确认：

• 已收集名称/许可证；已询问该许可证的可选输入项（references/definition-file-approach.md）

• 已展示以下确认摘要——通用字段以及该许可证对应的字段：

  即将创建新沙盒——请确认：

  • 名称： <SandboxName>
  • 描述： <Description or "(none)">
  • 创建来源： 生产环境
  • 许可证： <Developer | Developer Pro | Partial Copy | Full>
  • （以及该许可证对应的字段——参见 references/definition-file-approach.md）

  继续操作前，您可以随时修改以上内容。

• 已收到明确确认——这会消耗所选类型的许可证

方式 A — Tooling API 记录（直接）

API： Tooling API — SandboxInfo sObject

必需输入：

• SandboxName — 新沙盒的名称（字母数字，最多 10 个字符）
• LicenseType — 可选值：Developer、Developer_Pro、Partial_Copy、Full

可选输入：

• Description — 沙盒用途
• Features — 存储升级：Developer→400 MB，Developer_Pro→2 GB（不可逆）；不适用于 Partial_Copy/Full
• ApexClassId — 实现 SandboxPostCopy 的 Apex 类（创建后运行）
• ActivationUserGroupId — 访问组（默认：所有活跃用户）
• TemplateId / HistoryDays / CopyChatter / CopyArchivedActivities — 仅适用于 Partial_Copy/Full；各许可证对应的表格见 references/definition-file-approach.md

# Create a Developer sandbox
sf data create record --sobject SandboxInfo --use-tooling-api --values "SandboxName='mybox' LicenseType='Developer'"

方式 B — 沙盒定义文件（Salesforce CLI）

原生 DX 路径：编写 JSON 定义文件，然后运行 sf org create sandbox --definition-file <file> --alias <name> --target-org <org>。适用于已纳入版本控制的可重复配置，或基于名称的 Apex/组引用。JSON 示例、命令和字段表见 references/definition-file-approach.md。

创建后： 系统会创建一个 SandboxProcess 记录，其状态为 Processing。沙盒复制会立即开始。

创建了错误类型： 删除后使用正确类型重新创建。

重命名： 不是独立操作——仅通过 Refresh 的 SandboxName 输入生效。

---

8. 刷新现有沙盒

使用最新生产环境数据刷新沙盒。支持两种方式——根据用户偏好选择；除非用户要求使用定义文件，否则默认采用方式 A。

方案 A — Tooling API 记录（直接）

API： Tooling API — SandboxInfo sObject（PATCH）

通过更新现有的 SandboxInfo 记录来刷新。

必需输入：

• Sandbox 名称 — 用于查找 SandboxInfo 记录 ID（前缀为 0GQ）

可选输入：

• SandboxName — 刷新后沙盒的新名称（如用户想要重命名；仅限字母数字字符，最多 10 个字符）
• Description — 沙盒的新描述或更新后的描述
• AutoActivate — true 表示刷新完成后自动激活（默认值：false）
• Features — 存储升级：Developer→400 MB，Developer_Pro→2 GB（不可逆）；不适用于 Partial_Copy/Full
• ActivationUserGroupId — 访问组（默认值：所有活跃用户）
• TemplateId / HistoryDays / CopyChatter — 仅适用于 Partial_Copy/Full；按许可证划分的表格见 references/definition-file-approach.md

触发刷新前 — 务必先确认：

• 已收集沙盒名称；询问用户是否需要设置其许可证对应的可选输入（references/definition-file-approach.md）

• 已显示以下确认摘要：

  正在刷新沙盒 <name> — 请确认：

  • 重命名为： <SandboxName or "(no change)">
  • 描述： <Description or "(no change)">
  • 自动激活： <Yes | No (default)>
  • 沙盒访问权限： <ActivationUserGroupId or "All Active Users">
  • （以及此许可证对应的字段 — 见 references/definition-file-approach.md）

  继续操作前，您可以随时修改以上任一项。

• 已获得明确确认 — 刷新会使用生产数据覆盖沙盒；Auto-Activate=Yes 会自动应用（等同于激活）

步骤：

# 1. Look up SandboxInfo record Id by name
sf data query --query "SELECT Id, SandboxName, LicenseType, Description FROM SandboxInfo WHERE SandboxName = '<name>'" --use-tooling-api --json

# 2. PATCH to trigger refresh; include SandboxName/Description only if the user changed them
# Description is free text — escape any embedded single quotes (' -> \') before interpolating
sf data update record --sobject SandboxInfo --use-tooling-api --record-id <0GQ-id> --values "AutoActivate=true SandboxName='<newName>' Description='<description>'"

方案 B — 沙盒定义文件（Salesforce CLI）

使用创建时所用的同一份 JSON 定义文件蓝图，通过 sf org refresh sandbox --name <name> --definition-file <file> --target-org <org> 进行刷新。JSON 示例、命令和字段表见 references/definition-file-approach.md。

前置条件：

• 沙盒必须存在且处于可刷新的状态
• 必须已达到刷新间隔（Developer = 1 天，Dev Pro = 1 天，Partial = 5 天，Full = 29 天）
• 用户必须拥有 ManageSandboxes 权限

刷新后： 会创建一条新的 SandboxProcess 记录，状态为 Processing。如果 AutoActivate=true，沙盒会在刷新完成后自动激活；否则会进入 Pending Activation 状态。

尚未达到刷新间隔： 说明上次刷新的日期和符合条件的日期。若需要更早获得更新的副本，且有闲置许可证，可使用克隆（委托）方案。

---

9. 检查许可证使用情况

端点： GET /services/data/v66.0/sandbox/licenses

返回各许可证类型的许可证容量、使用量和剩余数量 — 无需沙盒名称或 ID。

sf api request rest "/services/data/v66.0/sandbox/licenses" --method GET

完整的响应格式见 references/api-response-shapes.md。

适用场景： 用户询问“我还剩多少个沙盒许可证”“我的许可证使用情况如何”“我还能创建另一个 Full 沙盒吗”，或在创建/刷新沙盒前确认该 licenseType 是否有可用容量。

关键响应字段：

• licenseType — DEVELOPER、DEVELOPER_PRO、PARTIAL、FULL
• limit — 此类型的许可证总数
• used — 当前已分配数量
• available — 剩余数量（即 limit - used）

因许可证数量限制而无法创建/刷新： 可提供其他可用类型供选择、删除过期沙盒以释放许可证、请管理员增加许可证，或 — 如果是已过期的 Courtesy Full Copy — 购买或转换该许可证。

---

Agent 决策指南

首先解析 sandboxId：按名称查找时，调用 GET /sandbox/reports 并匹配 sandboxName；按 ID 查找（前缀为 07E）时，直接调用 GET /sandbox/sandboxes/{sandboxId} — 不要调用 /sandbox/reports。

用户说……	操作	关键检查
"显示我的所有沙盒"	GET /sandbox/reports	—
"X 的状态如何？"	GET /sandbox/reports（按名称）或 GET /sandbox/sandboxes/{id}（按 ID）	—
"激活沙盒 X"	1. 解析 sandboxId 2. PATCH /sandbox/activate/{sandboxId}	必须为 isPendingActivation: true；先向用户确认
"丢弃 X 上的刷新"	1. 解析 sandboxId 2. DELETE /sandbox/discardsandbox/{sandboxId}	必须为 isPendingActivation: true；先向用户确认
"删除沙盒 X"	1. 解析 sandboxId 2. DELETE /sandbox/deletesandbox/{sandboxId}	先向用户确认

---

应避免的常见错误

错误	正确理解
使用 activate 来“启动”任何沙盒	activate 仅适用于已完成的刷新
使用 discard 来“隐藏”或“软删除”	discard 仅用于拒绝待处理的刷新
未先检查状态就激活	始终验证 isPendingActivation = true
在创建、激活、丢弃、删除或使用 AutoActivate=true 刷新时跳过确认	请参阅上方的不可逆操作 — 始终先确认
创建时提供 AutoActivate	仅用于刷新
刷新时提供 ApexClassId	仅用于创建