dx-org-trial-expiration-check

组织到期检查

确定 Salesforce 组织何时到期、还剩多少天，以及是否已到期——可检查一个组织、默认组织或所有已通过身份验证的组织。结果会优先排序（已到期和最早到期的组织排在前面），并附带一行摘要。此技能还可输出机器可读结果，用于设置提醒；为面临风险的组织打印备份命令；并说明如何续期即将到期的试用版或 Developer Edition 组织。

适用场景

以下请求会触发此技能：

• “我的试用版组织何时到期？”／“它还有效吗，还是已经到期了？”
• “我的试用版还剩多少天？”
• “我的哪些组织即将到期？”／“30 天内到期的有哪些？”
• “提醒我／为即将到期的组织设置 cron 作业”（使用 --json + --fail-if-expiring）。
• “在组织到期前备份它”（使用 --preserve）。
• “如何延长／续期我的试用版（或 Developer Edition）组织？”（使用 --renew）。

此技能适用于试用版、Developer Edition 组织（任何具有 TrialExpirationDate 的组织）以及临时组织（使用 sf org list 中的 expirationDate）。

不适用场景

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

• Sandbox 刷新时间——这不是到期日期。
• 创建、删除或切换组织——此技能只会读取到期信息并打印指导；它不会创建、删除、刷新组织，也不会更改活动组织或默认组织。（如需切换默认组织，请使用 dx-org-switch。）
• 非 Salesforce 试用版——例如 AWS 免费套餐、Netflix 或其他供应商的试用版。此技能仅适用于 Salesforce。

如何确定到期时间

• 试用版／Developer Edition 组织：权威来源是组织的 Organization.TrialExpirationDate 字段，通过 SOQL（sf data query）读取。付费／生产组织的此字段为 null，因此会显示没有试用版到期时间——这是预期结果，并非错误。
• **临时组织：**使用 sf org list 报告的 expirationDate（不会对临时组织发起 SOQL 查询）。

步骤

1. 重要：运行随附的辅助脚本，该脚本会处理日期计算（剩余天数、是否已到期、即将到期警告）、优先排序和结构化输出，并可在 macOS 和 Linux 上运行。务必从技能目录通过绝对路径调用该脚本——不要使用 ./scripts/，因为它会根据用户的当前目录解析，可能运行错误的脚本或运行失败。

   执行前，请确认：

   • <skill_dir> 是绝对路径（以 / 开头），而不是相对路径
   • 此路径指向该技能自己的目录（包含此 SKILL.md 的目录）

   bash "<skill_dir>/scripts/check_expiration.sh" <alias-or-username>   # one org
   bash "<skill_dir>/scripts/check_expiration.sh"                       # default org (target-org config)
   bash "<skill_dir>/scripts/check_expiration.sh" --all                 # every authenticated org
   bash "<skill_dir>/scripts/check_expiration.sh" --all --within 30     # only orgs expiring within 30 days
   

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

2. 将脚本输出转达给用户。如果无法查询某个组织，请提供脚本打印的 sf org login web 命令，供用户进行身份验证。根据用户的请求选择可选标志（见下文）：需要保存工作时使用 --preserve，询问如何延长时使用 --renew，用于自动化时使用 --json/--csv，用于 cron/CI 门禁时使用 --fail-if-expiring。

选项

标志	用途
--all、-a	检查所有已通过身份验证的组织。
--within <days>、-w	仅显示在 N 天内到期的组织（包括已到期的组织；不包括付费／生产组织）。也支持 --within=30。
--json	输出组织记录的 JSON 数组（仅数据）。
--csv	输出 CSV 行（仅数据）。
--preserve	为即将到期／已到期的组织打印备份命令。
--renew	打印试用版／DE 延期和重新激活指南。
--fail-if-expiring[=N]	如果任何组织将在 N 天内到期，则以状态码 3 退出（默认为 7 天）。
--no-scratch	排除临时组织（仅检查试用版／DE）。
--help、-h	显示用法。

标志的顺序不限，且可以组合使用（例如 --all --within 30 --json）。

优先级输出

面向用户的输出按紧急程度分组——先是 已过期，然后是 即将过期 （7 天内，标记为 Warning），接着是 有效，然后是 试用期未设到期日期， 最后是任何无法查询的组织——并以一行摘要结尾：

Org expiration status for all authenticated orgs:

Expired:
  old-trial                       trial/DE edition expired 2026-06-20  (EXPIRED 19 day(s) ago)

Expiring soon (within 7 day(s)):
  almost-up                       trial/DE edition expires 2026-07-14  (expires in 5 day(s)  Warning)

Active (not expiring soon):
  acme-trial                      trial/DE edition expires 2026-08-15  (expires in 37 day(s))
  my-scratch                      scratch org expires 2026-07-25  (expires in 16 day(s))

No trial expiration (paid/production):
  prod                            no trial expiration (paid/production org)

Summary: 1 expired, 1 expiring within 7 day(s), 2 active, 1 with no expiration.

用于告警和 cron 的结构化输出（--json / --csv）

对于仪表板、电子表格或计划作业，请使用 --json 或 --csv 获取 机器可读记录（无描述性文本）。每条记录包含 org、kind、 expirationDate、daysRemaining（负数 = 已过期，null = 无到期日期）、 status 和 orgId。输出是确定性的，无需在流程中使用大模型。

# JSON, filtered to orgs expiring within 30 days:
bash "<skill_dir>/scripts/check_expiration.sh" --all --within 30 --json

Cron 监控程序 — 如果任何组织将在 N 天内到期（默认 7 天），--fail-if-expiring[=N] 将以状态码 3 退出（并向 stderr 打印一行 ALERT:），这样计划作业就能在组织失效前通知你：

# crontab: every morning at 9, alert if anything expires within 7 days
0 9 * * *  bash "<skill_dir>/scripts/check_expiration.sh" --all --fail-if-expiring 7 \
             || mail -s "Salesforce org expiring soon" [email protected]

在组织失效前保留你的工作（--preserve）

组织过期后，你将无法再访问其元数据和数据。对于每个即将过期或已过期的组织，--preserve 会打印可直接运行的备份命令（元数据清单 + retrieve，以及批量数据导出）。它只会打印命令——请自行检查并运行：

bash "<skill_dir>/scripts/check_expiration.sh" my-trial --preserve

延长或续期试用版 / Developer Edition 组织（--renew）

--renew 会打印当前的组织续用指引，并显示存在风险的组织的 Org ID，便于采取相应步骤：

• **合作伙伴：**通过 partners.salesforce.com → Ask Agentforce → "I want to extend my Trial Org" 申请延长 Trial Org（最多 +12 个月），并提供 Org ID。组织有效或过期未满 30 天时符合条件；LDV 组织除外。（Salesforce 帮助文章 000387818。）
• **非营利组织：**发送电子邮件给你的客户经理，主题为 "Trial Extension"，并提供试用启动邮件、Org ID 和用户名；AMER 地区联系 Power of Us Desk，其他地区联系 My Account 支持 / 1-800-NO-SOFTWARE。即使组织已过期也可以办理。（文章 004754220。）
• **Developer Edition：**DE 组织没有订阅期限，但长期不活跃后（约 180 天未登录）会被停用；请定期登录。如果组织已锁定（但尚未删除），请向 Salesforce Customer Support 提交工单以重新激活——一旦被永久删除，就无法恢复。
• 若要保留标准试用版的数据/配置，请在其失效前转换为付费版本或订阅付费版本。

退出代码

• 0 成功
• 1 无法查询某个组织（身份验证/连接错误）
• 2 用法错误或缺少依赖项（sf 或 jq）
• 3 超出 --fail-if-expiring 阈值（至少有一个组织即将过期）

两种情况同时发生时，--fail-if-expiring 超出阈值（3）优先于身份验证错误（1）：告警信号优先，确保监控程序仍会触发。如果作业还必须检测无法连接的组织，请运行 --json 并检查记录中是否有 status: "auth_error"，同时检查退出代码。请注意，凭据验证失败的组织无法检查日期，因此不会单独计入 --fail-if-expiring 超出阈值的情况。

如果 --fail-if-expiring 未指定数字，则后续的纯数字参数会被视为天数（例如 --fail-if-expiring 12345）。如果组织别名恰好全为数字，请先传入组织（check_expiration.sh 12345 --fail-if-expiring 7），以免被误认为阈值。

身份验证

如果组织尚未通过身份验证（没有已保存的凭据，或令牌已过期/撤销），脚本不会静默失败——它会打印确切的登录命令，然后要求重新运行：

  my-trial                       not authenticated — no saved credentials for this org

  To authenticate, run one of:
    sf org login web --alias "my-trial"
    sf org login web --alias <my-alias> --instance-url https://test.salesforce.com
  Then re-run this check. List existing logins with:  sf org list

sf org login web 会打开浏览器以完成 OAuth 流程。对于沙盒，请使用 --instance-url https://test.salesforce.com；适用时，也可以使用自定义 My Domain URL。

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

# Trial/DE expiration for one org (null = not a trial / paid org):
sf data query --query "SELECT Id, TrialExpirationDate FROM Organization" --target-org <org> --json

# Scratch org expiration comes from the org list, not SOQL:
sf org list --json

注意事项

• 需要将 Salesforce CLI（sf）和 jq 添加到 PATH，并且至少有一个已通过身份验证的组织（sf org login web）。
• 避免同时启动多个 sf 命令——CLI 在竞争资源时可能会变慢。为此，脚本会依次查询组织。
• sf org list 会提供一个 trailExpirationDate 字段（注意其中的拼写错误），但该字段通常为 null；脚本不会将其用于试用版/DE 组织，而是使用可靠的 SOQL TrialExpirationDate。对于临时组织，脚本会使用列表中的 expirationDate。