dx-org-devhub-configure

启用 Dev Hub 并查看临时组织分配额

在 Salesforce 组织中启用 Dev Hub、确认它是否已启用，并查看组织的临时组织分配额（活动和每日上限，以及剩余数量）——适用于默认组织或指定组织。此技能还可以配置 Dev Hub 子偏好设置（打包、组织形状导出、临时组织快照），并列出从 Dev Hub 创建的活动临时组织。

Dev Hub 是一项组织功能，可让你创建和管理临时组织以及第二代（2GP）/解锁包。

何时使用

适用于以下请求：

• “启用 Dev Hub”/“打开 Dev Hub”/“为此组织设置临时组织。”
• “我的组织启用了 Dev Hub 吗？”/“检查 Dev Hub 是否已开启。”
• “我可以创建多少个临时组织？”/“我的临时组织分配额/上限是多少？”/“我还剩多少个临时组织名额？”
• “开启打包/2GP/解锁包”/“启用组织形状导出”/“启用临时组织快照”（Dev Hub 子偏好设置）。
• “列出我的 Dev Hub 上的临时组织。”

何时不使用

不要在以下情况触发此技能：

• 创建或删除单个临时组织——这需要使用 sf org create scratch / sf org delete scratch，属于另一种工作流。此技能用于启用 Dev Hub 功能并报告分配额；它不会创建临时组织。
• 切换默认/活动组织——请使用 dx-org-switch。
• 试用或组织到期日期（“我的组织何时到期”）——请使用 dx-org-trial-expiration-check。

如何判断 Dev Hub 是否已启用

标准对象 ScratchOrgInfo 仅在启用 Dev Hub 后才会配置并可供查询。因此，成功执行 SELECT COUNT() FROM ScratchOrgInfo 表示 Dev Hub 已开启；出现 INVALID_TYPE 错误则表示它已关闭。这是可靠的判断依据。

不要仅凭 sf org list limits 判断是否已启用：即使在 Dev Hub 已关闭的组织中，它也会报告 ActiveScratchOrgs / DailyScratchOrgs 行，因此限额只能显示分配额，无法表明是否已启用。

启用方式（重要）

• Dev Hub 主开关是可部署的 Metadata API 字段 DevHubSettings.enableScratchOrgManagementPref。没有 enableDevHub 字段，也没有专门用于开启它的 sf 命令——部署此设置正是 Setup 开关所执行的操作。
• 启用后无法撤销——开启后，Dev Hub 不能关闭。
• 需要拥有 ModifyAllData 或 ModifyMetadata 权限的用户（System Administrator 具有这些权限）。不具备这些权限的用户会收到 INSUFFICIENT_ACCESS。
• 无法在 sandbox 或已注册命名空间的组织中启用。
• 适用于 Developer、Enterprise、Performance、Unlimited 和试用版。

步骤

1. 重要：运行捆绑的辅助脚本。该脚本可处理 Dev Hub 检测、启用部署（默认安全地进行试运行）、分配计算和结构化输出，并且适用于 macOS 和 Linux。务必从技能目录使用绝对路径调用它——切勿使用 ./scripts/，因为它会相对于用户的当前目录解析，可能运行错误的脚本或导致失败。脚本会自行检查：如果 $0 不是绝对路径，就会以用法错误退出，因此请传入 <skill_dir> 的完整路径（即包含此 SKILL.md 的目录）。

   bash "<skill_dir>/scripts/devhub.sh" <alias-or-username>            # status: on? + allocation
   bash "<skill_dir>/scripts/devhub.sh"                               # default org (target-org)
   bash "<skill_dir>/scripts/devhub.sh" <org> --allocation           # allocation only
   bash "<skill_dir>/scripts/devhub.sh" <org> --enable               # validate enabling (dry run)
   bash "<skill_dir>/scripts/devhub.sh" <org> --enable --apply       # actually enable (irreversible)
   bash "<skill_dir>/scripts/devhub.sh" <org> --list-scratch         # list active scratch orgs
   bash "<skill_dir>/scripts/devhub.sh" <alias> --instance-url <url> --enable --apply  # log in first, then enable
   bash "<skill_dir>/scripts/devhub.sh" <url>                        # bare instance URL: log in to it
   

   如果用户提供了实例 URL（其 My Domain、沙盒或预发布／临时登录 URL，例如 https://my-domain.my.salesforce.com），请使用 --instance-url <url> 传入该原始 URL——脚本接受 Salesforce 所有的主机名，并会使用 sf org login web --instance-url <url> 登录，然后继续执行。也可以直接将 URL 作为位置参数传入，作为同一选项的简写。

   <skill_dir> 是包含此 SKILL.md 的目录的绝对路径。

2. 启用功能时，默认先进行试运行。运行 --enable（不带 --apply）以验证部署，然后转达结果。由于启用操作不可逆，只有在用户明确要求实际启用 Dev Hub 时，才运行 --enable --apply。应用操作需要明确指定组织别名或用户名；脚本不会修改隐式默认组织。如果因权限问题而拒绝部署，请提供脚本打印的 Setup UI 替代方案。

3. 转达脚本输出。如果无法查询组织，请提供脚本打印的 sf org login web 命令，以便用户进行身份验证。根据请求选择可选标志（见下文）：仅查询限制时使用 --allocation；枚举临时组织时使用 --list-scratch；启用子偏好设置时使用 --packaging / --snapshots / --shape；用于自动化时使用 --json。

完成前

返回答案前，请确认以下事项：

• 重要：通过绝对路径调用了辅助脚本（bash "<skill_dir>/scripts/devhub.sh" …），绝未使用 ./scripts/（脚本会拒绝非绝对路径的 $0）。
• 除非用户明确要求实际启用 Dev Hub 或部署偏好设置，否则没有运行 --apply——启用操作不可逆。
• 转达了脚本自身的输出（状态／分配结果，或其打印的登录／Setup UI 指引），而非自行编写答案替代。

选项

标志	用途
--allocation, -A	仅显示临时组织分配情况（Active/Daily）。
--list-scratch, -l	列出由此 Dev Hub 创建的活跃临时组织。
--enable, -e	启用 Dev Hub（部署 enableScratchOrgManagementPref=true）。除非使用 --apply，否则仅进行试运行。
--configure, -c	配置子首选项，但不启用或重新启用主开关。需搭配一个首选项标志。
--packaging	enablePackaging2=true（Unlocked + 2GP 包）。
--snapshots	enableScratchOrgSnapshotPref=true。
--shape	enableShapeExportPref=true。
--scratch-management	enableScratchOrgManagementPref=true（Dev Hub 开关）。
--pref KEY=VALUE	任意 DevHubSettings 子首选项（KEY 以 enable 开头，VALUE 为 true/false）。可重复使用。
--apply	实际部署到明确指定的组织。--enable/--configure 默认仅进行验证，不实际部署。
--login	先通过 sf org login web 验证组织身份（会打开浏览器），然后执行操作。
--instance-url <url>	登录到指定实例（My Domain、沙盒或预发布/临时实例），使用 sf org login web --instance-url <url>。隐含 --login。
--json	输出机器可读的 JSON。
--fail-if-disabled	如果 Dev Hub 未启用，则以 3 退出（用于 CI/cron 门控）。
--help, -h	显示用法。

--enable 可与子首选项标志组合使用，以同时启用和配置 （例如 --enable --packaging --apply）。如果省略，组织默认使用 target-org，其次为 target-dev-hub。

输出示例

脚本会在运行时打印权威输出。如果需要了解已启用和未启用状态的输出内容 （包括分配表以及启用/设置界面的说明），请阅读 examples/status-output.md；否则可跳过，以保持 工作流精简。

自动化结构化输出（--json）

在任何模式下都可以使用 --json 获取机器可读的输出（不含说明文字）。状态查询会返回 devHubEnabled、status 和 allocation 对象；启用操作会返回 success、applied 和 devHubVerifiedState。结果确定，无需大模型。

bash "<skill_dir>/scripts/devhub.sh" my-devhub --json
# {"org":"my-devhub","devHubEnabled":true,"status":"enabled", ... }

如果 Dev Hub 未启用，--fail-if-disabled 会以 3 退出（并向 stderr 打印一行 ALERT:），以便定时作业据此进行门控。

退出代码

• 0 成功
• 1 无法查询组织，或部署失败（身份验证/连接/部署）
• 2 用法错误或缺少依赖项（sf 或 jq）
• 3 Dev Hub 未启用（仅当设置了 --fail-if-disabled 时）

身份验证

如果尚未对组织进行身份验证，此技能可以使用 --login（或 --instance-url <url>）代为登录，然后在同一次运行中继续执行所请求的操作——用户提供实例 URL 时，推荐使用此方式：

将 <url> 替换为用户的实际实例 URL（此处显示的是通用 https://my-domain.my.salesforce.com 占位符）：

# Log in to a specific instance (My Domain / pre-release / sandbox), then enable:
bash "<skill_dir>/scripts/devhub.sh" my-alias \
  --instance-url https://my-domain.my.salesforce.com --enable --apply

# Bare instance URL as shorthand — logs in to it, then reports status:
bash "<skill_dir>/scripts/devhub.sh" https://my-domain.my.salesforce.com

# Just authenticate an org (no other action):
bash "<skill_dir>/scripts/devhub.sh" my-alias --login

sf org login web 会打开浏览器以进行 OAuth 流程；请及时完成（会话会超时）。提供的位置参数（my-alias）会成为 CLI 别名；看起来像 URL（包含 ://）的位置参数则会作为要登录的 --instance-url。此选项仅接受 HTTPS Salesforce 所有的主机名。对于标准 生产/DE/试用版登录（login.salesforce.com），请省略 --instance-url。如果浏览器流程持续超时，脚本会输出用于基于代码登录的 sf org login device 备用方案。

如果组织尚未通过身份验证，且未传入登录标志，脚本则会打印确切的登录并重新运行命令——如果提供了实例 URL，则会使用该 URL：

  my-org                         could not query org (...)

  To authenticate against https://my-domain.my.salesforce.com, run:
    sf org login web --instance-url "https://my-domain.my.salesforce.com" --alias "my-org"
  Or let this script log you in and continue in one step:
    devhub.sh "my-org" --instance-url "https://my-domain.my.salesforce.com" --login
  Then re-run. List existing logins with:  sf org list

手动备用方案（脚本不可用时）

# Detect Dev Hub (INVALID_TYPE error means OFF; a count means ON):
sf data query --query "SELECT COUNT() FROM ScratchOrgInfo" --target-org <org> --json

# Enable Dev Hub via the Tooling API (what the Setup toggle does; irreversible):
sf api request rest "/services/data/v47.0/tooling/sobjects/DevHubSettings/DevHub" \
  --method PATCH \
  --body '{"FullName":"DevHub","Metadata":{"enableScratchOrgManagementPref":true}}' \
  --target-org <org>

# Or enable in the UI: Setup > Quick Find > "Dev Hub" > turn Enable Dev Hub On.

# View scratch org allocation:
sf org list limits --target-org <org> --json | jq '.result[] | select(.name|test("ScratchOrg"))'

说明

• 需要在 PATH 中安装 Salesforce CLI（sf）和 jq，并且至少有一个已通过身份验证的组织（sf org login web）。
• 启用后，将该组织设为默认 Dev Hub： sf config set target-dev-hub <org>。
• 启用打包（enablePackaging2）要求先启用 Dev Hub——--enable --packaging 会在单次部署中处理好顺序。
• 非管理员用户仍需要对象访问权限（对 ScratchOrgInfo 和 ActiveScratchOrg 具有读取/创建权限）才能创建或查看临时组织；还需要“创建和更新第二代包”权限才能构建 2GP/解锁包。
• 要切换默认组织，请使用 dx-org-switch；要检查到期时间，请使用 dx-org-trial-expiration-check。