dx-org-manage

必须：严格遵循以下说明。请勿改用 MCP 工具。

工具限制： 所有 sf CLI 命令都必须使用 Bash 工具。结构化输出始终添加 --json。请勿使用 mcp__salesforce_dx__* 工具执行 org 创建、snapshot 或打开操作——本技能提供了完整流程。

评测/测试的输出产物： 只要有可用的输出目录，就始终将命令的 JSON 响应写入文件。请勿询问用户要将文件写到哪里——本技能已定义文件名。执行命令后：（1）如果用户指定了输出路径（例如“将所有生成的文件写入文件夹 X”），立即写入该路径；（2）否则运行 [ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output' 来检测评测目录；（3）使用以下文件名，将命令的完整 JSON 响应写入 <output-dir>/<filename>：创建 org 时使用 scratch-org-result.json（批量创建 N 个 org 时，使用 scratch-org-result-1.json … scratch-org-result-N.json），列表操作使用 scratch-org-list-result.json，显示操作使用 org-display-result.json，恢复操作使用 scratch-org-resume-result.json，删除操作使用 scratch-org-delete-result.json。这些就是生成的输出——直接写入，无需询问。打开操作除外——它们会启动浏览器，不写入产物；请参阅“打开 Org”。

---

创建 Scratch Org

必须按顺序执行以下步骤：

步骤 1. 确定环境和创建方式：

首先，如果用户指定了明确的来源，则使用该来源：“definition file”或 .json 路径 → definition-file 方式；“snapshot”/“from snapshot” → snapshot 方式；“org shape”/“source-org” → shape 方式。只能指定一种创建来源类型（edition、snapshot 或 shape）；如果暗示了两种不同类型，则停止并询问（标志覆盖同一维度的 definition-file 值是允许的）。

否则，根据环境确定：

• 自动模式（零提示）： 如果存在 sfdx-project.json，且恰好存在一个 config/*scratch-def.json，并且可以解析出 Dev Hub（已设置默认的 target-dev-hub，或恰好有一个已认证的 Dev Hub），则立即使用该文件、已解析的 Dev Hub、派生的别名和 CLI 默认值创建——无需询问。此模式也支持批量创建（见下文）。
• 状态 A（位于项目中），但不符合自动模式： 列出 config/*scratch-def.json——0 个文件 → 默认使用 --edition developer（如果需要 features/settings，则可编写定义文件，见下文）；1 个文件 → 使用该文件；多个文件 → 询问用户选择哪一个（绝不默默选取）。
• 状态 B（没有 sfdx-project.json）： 不要阻止，也不要默默创建临时 org——提供引导式的 3 种选择（指向一个项目 / 使用 sf template generate project --name <name> 搭建项目 / 在此处创建临时 org，然后引导用户选择来源）。请参阅 references/scratch-org-create.md。

批量创建——“创建 N 个 scratch org”： 没有原生的数量标志——循环执行创建命令 N 次，并使用 N 个不同的别名（<base>-1 … <base>-N，每个别名都要检查冲突，确保不会重新指向现有 org）。报告每个 org，并为每个 org 写入一个产物。如果循环中途遇到 Dev Hub 限额错误，原样显示 CLI 错误，并报告已成功创建的 org。

编写定义文件： 如果用户要求 features/settings，且没有合适的文件，则编写一个名称明确的新定义文件（先创建初始文件再修改；仅使用有文档说明的字段；不得覆盖现有文件），展示该文件，并据此创建。在非交互式/评测环境中，编写文件后直接继续创建，无需等待用户确认编辑。详情请参阅 references/scratch-org-create.md 和 references/definition_file_options.md。

步骤 2. 将 Dev Hub 解析为具体值，然后显式传入。 仅解析一次，将其解析为实际用户名或别名，并在步骤 3 的每条命令中通过 --target-dev-hub 传入该确切值。解析顺序：

1. 用户明确指定的 Dev Hub → 原样使用。
2. 否则使用默认值： sf config get target-dev-hub --json 返回的非空 result[0].value。

   sf config get target-dev-hub --json
   

3. 否则使用唯一已通过身份验证的 Dev Hub。 运行以下确切命令——不要自行编写筛选条件。Dev Hub 可能出现在 sf org list 的任意分类（devHubs、nonScratchOrgs、other、sandboxes、scratchOrgs）中；只检查一个分类（例如仅检查 .other[]）的筛选条件会漏掉它，让你误以为不存在 Dev Hub：

   sf org list --json | jq -r '[.result.devHubs[]?, .result.nonScratchOrgs[]?, .result.other[]?, .result.sandboxes[]?, .result.scratchOrgs[]?] | map(select(.isDevHub == true).username) | unique | .[]'
   

   • 恰好打印一个用户名 → 使用该用户名。
   • 打印零个 → 没有已通过身份验证的 Dev Hub。不要运行 sf org create——没有可传给 --target-dev-hub 的值，任何创建尝试都会失败。请改为在此处停止：建议运行 sf org login web --set-default-dev-hub；如果有可用的输出目录，则将该建议写入为产物。不要继续执行第 3 步。
   • 打印两个或更多 → 询问用户要使用哪一个（不要随意选择）。

• 绝不要编造或猜测 Dev Hub 名称。 虚构占位别名（例如 eval-target、my-dev-hub、DevHub）是评估失败的首要原因——CLI 会正确地以 NotADevHubError 拒绝它。如果上述命令未打印任何内容，表示此环境中不存在 Dev Hub——这不意味着你应该替换成一个名称。不存在可编造的有效备用名称：未确定 Dev Hub 就必须停止，不能猜测其值。不要使用虚构的 --target-dev-hub 运行 sf org create scratch，也不要在没有 --target-dev-hub 标志的情况下运行它（这会导致 NoDefaultDevHubError）。停止并建议运行 sf org login web --set-default-dev-hub。
• 在某些 CLI 设置中，默认的 target-dev-hub 可能按目录限定（执行 cd 后，sf config get 可能返回空值），因此第 3 步检查所有分类的 sf org list 是可靠的备用方案——它不受目录限制。
• 确定具体的 Dev Hub 值之前，不要继续。

第 3 步。根据方法构建并执行命令：

定义文件：

sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json

仅指定版本：

sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json

基于快照：

sf org create scratch --snapshot <snapshot-name> --target-dev-hub <alias> --alias <name> --json

基于组织形状：

sf org create scratch --source-org <source-org-id> --target-dev-hub <alias> --alias <name> --json

--source-org 接受 15 个字符的源组织 ID——即捕获组织形状的组织的 ID（00D… 组织 ID），而不是 sf org list shape 显示的 3SR… 形状记录 ID。用户提供的 ID 必须原样传递。如果 CLI 拒绝该 ID（例如出现 InvalidIdLengthError、InvalidPrefixError），请原样报告该错误并停止——不要截断、重新格式化、猜测或使用其他 ID 重试。

按要求应用以下标志：

• --duration-days <days> — 默认值为 7，最大值为 30
• --set-default — 将其设为默认组织
• --no-track-source — 禁用源跟踪（适用于 CI/CD）

第 4 步。必须运行 org list 并写入输出（仅限成功路径）： 仅当第 3 步成功创建组织时才运行此步骤。如果第 3 步返回错误，则跳过此步骤，改为遵循下方的错误处理。组织创建完成后，必须运行以下命令：

sf org list --json

然后：

1. 解析 JSON 结果并找到 scratchOrgs 数组
2. 找到 username 与第 3 步创建结果中的用户名相符的条目
3. 提取完整的组织对象（其中包含：alias、username、orgId、instanceUrl、loginUrl、isDefaultUsername、orgEdition、status、expirationDate、devHubUsername，以及 CLI 返回的其他字段）。
4. 向用户报告：
   • 已创建 scratch 组织。
   • 别名：[org list 条目中的别名]
   • 用户名：[username]
   • 组织 ID：[orgId]
5. 如果存在输出目录（根据上述输出产物规则），则将提取出的组织对象原样写入 <output-dir>/scratch-org-result.json——此技能只是一个透传包装器。写入 CLI 为该组织返回的所有字段；不要筛选、加入白名单或删除非敏感字段（例如，instanceName、createdOrgInstance、signupUsername、orgName、edition 都是 CLI 可自由返回的非敏感元数据，必须保留）。唯一绝不能输出的是实时机密：accessToken 和 sfdxAuthUrl——CLI 已在 --json 输出中将它们脱敏（返回值类似 "[REDACTED] …"），因此只需保留该脱敏结果，绝不能取消脱敏或重新推导真实值。

示例：如果 sf org list --json 返回 {"result": {"scratchOrgs": [{"alias": "feature-dev", "username": "[email protected]", "orgId": "00D...", ...}]}}，则将内部组织对象 {"alias": "feature-dev", "username": "[email protected]", "orgId": "00D...", ...}（该组织的完整对象）写入文件。

写入提取出的组织列表条目（已解析的组织记录），而不是原始创建命令响应。不要向用户建议验证步骤。

错误处理（第 3 步创建失败——未创建任何组织）： 将 CLI 的错误输出原样展示给用户（不得改写、重试或编辑定义文件）。不要执行第 4 步（没有可列出或提取的组织）。如果存在输出目录，则将创建命令的原始错误 JSON 原样写入 <output-dir>/scratch-org-result.json——这是该命令的响应，也是此次失败运行的输出产物。（对于批处理，将错误写入失败组织对应的产物中，并仍然写入失败前已成功创建的任何组织条目。）然后，如果 CLI 错误与以下任一项匹配，添加相应提示：

• “Snapshot not found” → 建议运行 sf org list snapshot --target-dev-hub <alias>
• “No default Dev Hub” → 建议运行 sf org login web --set-default-dev-hub

需要更多详细信息时：

• 有关完整创建工作流（AUTO MODE、STATE A/B、批处理、定义文件编写）→ 加载 references/scratch-org-create.md；有关列出/显示/恢复/删除 → 加载 references/scratch-org-operations.md
• 有关可用功能、设置和定义文件结构 → 加载 references/definition_file_options.md
• 有关版本选择指南和对比 → 加载 references/edition_types.md
• 要在此处引用快照前创建/检查/列出/删除快照 → 使用 dx-org-snapshot-manage 技能

---

列出 Scratch Orgs

第 1 步。执行：

sf org list --json

第 2 步。报告并写入输出： 默认视图 = result.scratchOrgs[] 中的活跃 Scratch Org；报告每个组织的别名 / 用户名 / orgId / 到期时间。将 --all（包含已过期/已删除的组织）和 --clean 说明为可选项，而非默认选项。将 result.scratchOrgs[] 数组写入 <output-dir>/scratch-org-list-result.json（遵循输出产物规则）。

详情： references/scratch-org-operations.md。

---

显示组织

第 1 步。执行：

sf org display --target-org <alias> --json

第 2 步。报告并写入输出： 报告别名 / 用户名 / orgId / instanceUrl / 状态 / 到期时间。将带包装的 {status, result} JSON 写入 <output-dir>/org-display-result.json——不要解包。在任何提交的示例/黄金样例中，accessToken 和 sfdxAuthUrl 必须已脱敏（值以 [REDACTED] 开头）。

--verbose： 绝不要添加此选项，也绝不要在此技能中运行它——它会将 sfdxAuthUrl（刷新令牌）返回到 Agent 上下文中。如果用户需要授权 URL，告知他们在自己的终端中自行运行 sf org display --verbose。

详情： references/scratch-org-operations.md。

---

恢复暂存组织创建

适用于使用 --async 运行或超时（退出代码 69）的创建操作。

步骤 1. 执行：

sf org resume scratch --job-id <id> --json

如果用户提供了明确的 --job-id，则使用该值；否则默认使用 --use-most-recent。如果没有最近的任务，则原样显示 CLI 的未找到结果，并提示用户运行 sf org list——不要编造任务 ID。

**步骤 2. 写入输出：**将命令返回的 JSON 原样写入 <output-dir>/scratch-org-resume-result.json。

详情：references/scratch-org-operations.md。

---

删除暂存组织

有破坏性——无法撤销。

**步骤 1. 运行前确认。**询问“删除暂存组织 X 吗？”，并等待确认，除非用户已经明确表示要删除。如果目标是当前默认组织，则在确认时特别指出（额外保护措施）。

步骤 2. 执行（仅在确认后）：

sf org delete scratch --target-org <alias> --no-prompt --json

--no-prompt 会在技能自身确认后传入，这样 Agent 就不会卡在 CLI 的交互提示上等待。

**步骤 3. 写入输出：**将命令返回的 JSON 原样写入 <output-dir>/scratch-org-delete-result.json。

详情：references/scratch-org-operations.md。

---

打开组织

必需步骤——按顺序执行：

仅启动浏览器——绝不使用 --json 或 --url-only。打开是此技能中唯一不写入任何产物的操作。直接运行 sf org open 会启动浏览器并登录用户，且不会输出登录 URL，因此不会让凭据进入 Agent 上下文或文件。不要添加 --json：sf org open --json 会在 result.url 中返回有效的登录 URL（/secur/frontdoor.jsp?otp=/sid=<token>），其作用等同于凭据——将它提取到上下文中（即使是在写入前将其编辑掉）正是直接运行命令所避免的 S1 泄露。出于相同原因，禁止使用 --url-only：如果用户明确要求 URL 而非浏览器（例如“仅 URL”“只给我链接”“无头/远程”），不要运行该命令——请告知用户在自己的终端中运行 sf org open --url-only（处理方式与 sf org display --verbose 相同）。模糊的“打开我的组织”请求只需打开浏览器。

步骤 1. 将用户请求与命令对应：

用户想要	命令
打开默认组织	sf org open
打开指定组织	sf org open --target-org <alias>
指定浏览器	sf org open --browser chrome
无痕模式	sf org open --private
导航到路径	sf org open --path '<path>'
打开元数据文件	sf org open --source-file <file-path>
仅 URL	**不要运行。**告知用户在本地运行 sf org open --url-only——它会返回有效的登录令牌，技能不得输出该令牌。

**步骤 2. 使用 Bash 工具执行对应的命令。**成功时，直接运行 sf org open 不会输出任何内容——这是预期行为。

**步骤 3. 报告结果：**告知用户已在浏览器中打开组织（或路径/元数据文件）。打开操作不需要写入任何产物——不要写入 org-url-result.json 或任何文件，也不要添加 --json 来生成产物。如果命令报错，请按下文的错误处理方式处理。

错误处理：

• “no target org” → 建议运行 sf config set target-org <alias>
• “auth error” → 建议运行 sf org login web --alias <alias>

需要更多详情时：

• 有关完整的组织打开工作流和所有可用标志 → 加载 references/opening-org.md

---

参考文件索引

如需详细指导，请加载以下参考文件：

文件	何时阅读
references/scratch-org-create.md	创建临时组织（版本、定义文件、快照、组织形状）、AUTO MODE、STATE A/B 项目处理、批量创建以及定义文件编写
references/scratch-org-operations.md	操作现有组织：列出、显示、恢复、删除，以及通用生命周期规则和故障排除
references/definition_file_options.md	用户需要配置组织功能、设置，或使用基本组织创建之外的高级定义文件选项
references/edition_types.md	用户询问应选择哪个版本，或需要了解不同版本的差异
references/opening-org.md	用户需要导航到特定设置路径、打开元数据文件，或使用高级打开标志

如需创建、检查、列出或删除快照本身（而非仅使用快照），请使用 dx-org-snapshot-manage 技能。

示例文件

用于测试和故障排除的示例命令输出：

文件	用途
examples/scratch-orgs/success_definition_file.json	使用 --definition-file 成功创建临时组织
examples/scratch-orgs/success_edition.json	使用 --edition developer 成功创建临时组织
examples/scratch-orgs/success_snapshot.json	使用 --snapshot 成功创建临时组织
examples/scratch-orgs/success_shape.json	使用 --source-org（组织形状）成功创建临时组织
examples/scratch-orgs/error_no_devhub.json	Dev Hub 未通过身份验证时出现的错误
examples/scratch-orgs/error_timeout.json	创建组织期间发生超时错误（退出代码 69）
examples/scratch-orgs/list_output.json	sf org list --json 输出（活动临时组织数组）
examples/scratch-orgs/display_output.json	sf org display --json 输出（已包装，令牌已隐藏）
examples/scratch-orgs/resume_output.json	sf org resume scratch --json 输出（已完成的组织）
examples/scratch-orgs/delete_output.json	sf org delete scratch --json 输出