platform-trial-org-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

What this skill does

此Skill的功能

Creates a Salesforce trial org by inserting a

SignupRequest

sObject with the

sf

CLI — the same request the Trialforce/developer web signup form issues under the hood. There is no bespoke signup endpoint: signup = inserting a

SignupRequest

(key prefix

0SR

) against an authenticated host org (a Trialforce Source Org / Env Hub / partner org that is entitled to create trial orgs).

The flow is two CLI calls: (1) create the

SignupRequest

, (2) read it back to pick up the assigned org id (creation is asynchronous — the org id appears shortly after the insert).

通过

sf

CLI插入

SignupRequest

sObject来创建Salesforce试用组织，这与Trialforce/开发者网页注册表单在后台发起的请求完全相同。这里没有定制化的注册端点：注册操作本质就是针对已验证的宿主组织（有权创建试用组织的Trialforce源组织/环境中心/合作伙伴组织）插入

SignupRequest

（键前缀

0SR

）。

流程包含两次CLI调用：(1) 创建

SignupRequest

，(2) 读取该记录以获取分配的组织ID（创建是异步操作——插入后不久会生成组织ID）。

Prerequisites — confirm before executing

前置条件——执行前确认

Authenticated host org — always confirm which one, explicitly. You are signing up from an authenticated host org, not anonymously. The
```
sf
```
CLI operates against an org you have already logged into once (
```
sf org login web
```
, or
```
sf org login
```
).
Always pass an explicit
--target-org
(
-o
) with the host org's alias or username on every command, and confirm the target with the user before creating — even if a default org is configured. Creating a
```
SignupRequest
```
is a real provisioning action; do not let it run against whatever org happens to be the default.
- Do not rely on the default-org fallback. With no
```
-o
```
  , the CLI resolves the target from
```
--target-org
```
  →
```
SF_TARGET_ORG
```
  env var → local then global
```
target-org
```
  config, and errors (
  NoDefaultEnvError
  ) if none is set — it never auto-picks among your connected orgs. That default may be an unrelated dev/scratch org, so an omitted
```
-o
```
  is either wrong-org or a hard failure. Never omit it.
- The user may have many authenticated orgs. Run
```
sf org list
```
  and, if the intended host org is ambiguous or not provided, ask the user which alias/username to use. Do not guess.
- Verify the chosen org is
  Connected
  in
```
sf org list
```
  before creating (stale refresh tokens / expired certs show as error states, not
```
Connected
```
  ).
- Never invent credentials.
Host org must be entitled to create trial orgs, and the invoking user must have sufficient access on it. The skill does not run a separate permission check — the
```
sf data create record
```
call (Step 1) is the definitive gate, and the same API enforcement is what a check would rely on. If the org is not entitled, the
```
SignupRequest
```
entity is not exposed and the create fails with a non-zero
```
status
```
and
```
name
```
/
```
code
```
of
```
NOT_FOUND
```
("The requested resource does not exist") or
```
INVALID_TYPE
```
("sObject type 'SignupRequest' is not supported"). This case is handled in Step 1's error table.
When it happens, stop (it is not retryable from the CLI) and report to the user: (a) the raw CLI error as-is — the exact
```
name
```
/
```
errorCode
```
and
```
message
```
the CLI returned, verbatim — and (b) that they should reach out to Salesforce support to get the org enabled for trial-org creation, then try again. Do NOT diagnose or name which permission is missing — just surface the raw error and point them to support.

已完成身份验证的宿主组织——务必明确确认具体是哪一个。你是从已验证的宿主组织发起注册，而非匿名注册。
```
sf
```
CLI会针对你已登录过的组织运行（通过
```
sf org login web
```
或
```
sf org login
```
登录）。
务必在每个命令中传入明确的
--target-org
（简写
-o
）参数，指定宿主组织的别名或用户名，并在创建前与用户确认目标组织——即使已配置默认组织也是如此。创建
```
SignupRequest
```
是真实的资源分配操作，切勿让其在任意默认组织上执行。
- 不要依赖默认组织的回退机制。如果未传入
```
-o
```
  ，CLI会按以下顺序解析目标组织：
```
--target-org
```
  →
```
SF_TARGET_ORG
```
  环境变量 → 本地然后全局的
```
target-org
```
  配置，如果都未设置则会报错（
  NoDefaultEnvError
  ）——它不会自动从已连接的组织中选择。默认组织可能是无关的开发者/临时组织，因此省略
```
-o
```
  要么会选错组织，要么直接失败。绝对不要省略该参数。
- 用户可能有多个已验证的组织。运行
```
sf org list
```
  命令，如果目标宿主组织不明确或未提供，请询问用户要使用哪个别名/用户名。切勿猜测。
- 验证所选组织在
  sf org list
  中显示为
  Connected
  状态（过期的刷新令牌/证书会显示为错误状态，而非
```
Connected
```
  ）。
- 切勿编造凭证。
宿主组织必须拥有创建试用组织的权限，且调用用户必须拥有足够的访问权限。此Skill不会单独运行权限检查——步骤1中的
```
sf data create record
```
调用就是最终的权限验证，且检查依赖的API规则与该调用一致。如果组织没有权限，
```
SignupRequest
```
实体不会被暴露，创建操作会失败，返回非零
```
status
```
以及
```
name
```
/
```
code
```
为
```
NOT_FOUND
```
（"请求的资源不存在"）或
```
INVALID_TYPE
```
（"不支持sObject类型'SignupRequest'"）。这种情况会在步骤1的错误表中处理。
发生这种情况时，停止操作（无法通过CLI重试）并向用户报告：(a) 原样返回原始CLI错误——包括CLI返回的精确
```
name
```
/
```
errorCode
```
和
```
message
```
；(b) 告知用户应联系Salesforce支持团队以启用该组织的试用组织创建权限，然后重试。不要诊断或指出缺少的具体权限——只需展示原始错误并引导用户联系支持。

Required Inputs — collect from the invoking user before any create

必填输入项——创建前向用户收集

Prompt the user for these and do NOT proceed until all are provided. Do not invent values. Ask for each one; if the user is unsure about a field, guide them using the "If the user is unsure" column before moving on.

Always required (5) — these are

required="true"

on the

SignupRequest

entity (

FirstName

is listed here for prompting convenience but is optional):

Input	Notes	If the user is unsure
`LastName`	Admin user's last name. Max 80 chars.	Any surname for the new org's admin user; it's just the admin contact name, use theirs.
`FirstName`	Optional. Admin user's first name. Ask for it, but proceed without it if the user doesn't provide one.	Optional — leave blank if unsure; only `LastName` is required for the admin user.
`Username`	Admin login username. Must be email-format and globally unique across all Salesforce orgs. Max 80 chars. Lowercased on save.	It does not have to be a real inbox — it just has to look like an email and be unique. Suggest a pattern like `admin@<company>-<something-unique>.com` . If it collides, you'll get a duplicate-username error on create; pick another.
`SignupEmail`	Admin user's real email address (welcome/login mail goes here).	This one must be a working inbox they can access — unlike `Username` , it should be a real address.
`Company`	Company / org name. Max 80 chars.	The organization name to show in the trial org; any descriptive name is fine.
`Country`	ISO country code, max 3 chars, e.g. `US` , `GB` , `IN` , `DE` . Validated at runtime against allowed codes (embargoed/invalid codes are rejected).	Use the 2-letter ISO code for their country (e.g. `US` for United States, `GB` for United Kingdom). Not a free-text country name.

Exactly one of (required, pick one — NOT both):

Input	Notes	If the user is unsure
`TemplateId`	Trialforce template ID (key prefix `0TT` , 15 chars) — defines the trial org's product/content.	Use a template when they want a specific pre-built product/content set. To find available templates, query the host org: `sf data query -o <HOST_ORG> -q "SELECT Id, TemplateName FROM TrialforceTemplate" --json` . If they just want a plain trial org, use `Edition` instead.
`Edition`	Org edition for a generic (non-template) trial. Generic values: `Developer` , `Group` , `Professional` , `Enterprise` (also `ServiceProfessional` , `SalesEnterprise` ). Partner/Trialforce editions are perm-gated.	If they just want "a dev org to try things," use `Developer` . Partner editions ( `PARTNER_` , `TRIALFORCE_` ) only work if the host org has partner/TMC perms — using one without the perm returns a `noPartnerAccess` error.

Ask the user to choose either a

TemplateId

or an

Edition

, not both:

Neither supplied → stop and ask. A create with no template and no edition fails validation with
```
missingEdition
```
(
```
ApiErrorCodes.INVALID_SIGNUP_OPTION
```
).
Both supplied → ask them to pick one; send only the chosen field. Combining them fails with
```
redundantTemplateId
```
. Neither may be combined with clone/source-org fields either.

This skill intentionally scopes user-collected input to the fields above (the 5 always-required plus optional

FirstName

). Do not prompt for or surface other fields. The

SignupRequest

entity supports additional optional and perm-gated fields (

TrialDays

Subdomain

PreferredLanguage

SignupSource

, the OAuth-return pair, etc.); these are out of scope here and left to server defaults. They are documented in

references/signup_request_fields.md

for reference only — do not send them from this skill.

向用户索要以下信息，所有信息收集完成后再继续。切勿编造值。逐个询问；如果用户对某个字段不确定，请先使用「用户不确定时」列中的内容引导他们，再继续下一步。

始终必填的5项——这些在

SignupRequest

实体中标记为

required="true"

（

FirstName

在此列出仅为方便提示，实际为可选）：

输入项	说明	用户不确定时
`LastName`	管理员用户的姓氏。最大长度80字符。	可为新组织的管理员用户填写任意姓氏；这只是管理员的联系名称，使用用户自己的姓氏即可。
`FirstName`	可选。管理员用户的名字。询问用户，但如果用户未提供则可以跳过。	可选——不确定则留空；管理员用户仅需要 `LastName` 。
`Username`	管理员登录用户名。必须为邮箱格式，且在所有Salesforce组织中全局唯一。最大长度80字符。保存时会自动转为小写。	不必是真实邮箱——只需看起来像邮箱且唯一即可。建议使用类似 `admin@<公司>-<唯一标识>.com` 的格式。如果出现冲突，创建时会返回重复用户名错误，只需更换一个即可。
`SignupEmail`	管理员用户的真实邮箱地址（欢迎/登录邮件会发送至此）。	必须是用户可以访问的有效邮箱——与 `Username` 不同，这里应该填写真实地址。
`Company`	公司/组织名称。最大长度80字符。	试用组织中显示的组织名称；填写任何描述性名称均可。
`Country`	ISO国家代码，最大3字符，例如 `US` 、 `GB` 、 `IN` 、 `DE` 。运行时会验证是否为允许的代码（禁运/无效代码会被拒绝）。	使用用户所在国家的2位ISO代码（例如美国用 `US` ，英国用 `GB` ）。不要填写自由文本的国家名称。

二选一必填（选择其一，不可同时选）：

输入项	说明	用户不确定时
`TemplateId`	Trialforce模板ID（键前缀 `0TT` ，15字符）——定义试用组织的产品/内容。	当用户需要特定的预构建产品/内容集合时使用模板。要查找可用模板，查询宿主组织： `sf data query -o <HOST_ORG> -q "SELECT Id, TemplateName FROM TrialforceTemplate" --json` 。如果用户只需要普通试用组织，请使用 `Edition` 。
`Edition`	通用（非模板）试用组织的版本。通用值包括： `Developer` 、 `Group` 、 `Professional` 、 `Enterprise` （还有 `ServiceProfessional` 、 `SalesEnterprise` ）。合作伙伴/Trialforce版本受权限限制。	如果用户只是想要「一个用于测试的开发者组织」，请使用 `Developer` 。合作伙伴版本（ `PARTNER_` 、 `TRIALFORCE_` ）仅在宿主组织拥有合作伙伴/TMC权限时可用——无权限使用会返回 `noPartnerAccess` 错误。

请用户选择**

TemplateId

或

Edition

其中之一**，不可同时选择：

两者都未提供 → 停止操作并询问用户。既无模板也无版本的创建请求会因
```
missingEdition
```
（
```
ApiErrorCodes.INVALID_SIGNUP_OPTION
```
）失败。
两者都提供 → 请用户选择其一；仅发送所选字段。同时提供两者会触发
```
redundantTemplateId
```
错误。也不可将它们与克隆/源组织字段组合使用。

此Skill仅收集上述字段（5个必填项加可选的

FirstName

）。不要提示或使用其他字段。

SignupRequest

实体支持其他可选和受权限限制的字段（

TrialDays

、

Subdomain

、

PreferredLanguage

、

SignupSource

、OAuth返回对等等）；这些不在此Skill的范围内，将使用服务器默认值。它们仅在

references/signup_request_fields.md

中作为参考文档——请勿从此Skill发送这些字段。

Step 1 — Create the SignupRequest

步骤1——创建SignupRequest

Invoke the create script with the collected inputs. It enforces the "exactly one of

TemplateId

Edition

" rule, assembles and quotes the

--values

payload, runs the insert, and prints the assigned

0SR…

id on success. Reference the script by its absolute path from the skill directory (

<skill_dir>/scripts/…

) — never

./scripts/

, which resolves against the user's working directory.

With a template:

bash

SR_ID=$(bash "<skill_dir>/scripts/create_signup_request.sh" \
  --target-org <HOST_ORG> \
  --last-name <LAST_NAME> --email <EMAIL> --username <UNIQUE_USERNAME> \
  --company "<COMPANY>" --country <ISO> --template-id 0TT... \
  --output-dir force-app/main/adk-eval-output)

With an edition (generic trial, no template): replace

--template-id 0TT...

with

--edition Developer

(or

Enterprise

, etc.). Add

--first-name <NAME>

only if the user supplied it — no other optional fields are sent by this skill. The script rejects supplying both

--template-id

and

--edition

, or neither.

Pass

--output-dir

(use

force-app/main/adk-eval-output

when it exists) so that if the create is rejected, the script still writes

<output-dir>/signup-request-result.json

capturing the create-rejected outcome and the raw error verbatim — the run's output artifact even when no org is created. On success this write is done by the Step 2 read-back instead.

On success the script prints the

0SR…

SignupRequest id (capture it as

SR_ID

). Pass

--json

instead to get the raw

sf

create envelope, which wraps a handle, not the org:

json

{ "status": 0, "result": { "id": "0SRxx0000000000", "success": true, "errors": [] } }

Handle create errors (synchronous field validation). On a rejected create the script exits non-zero and prints the raw CLI error (

name

code

message

) to stderr — surface it verbatim and act per the table below. When

--output-dir

was given, the script also writes the create-rejected artifact (

{ "outcome": "create-rejected", "error": {…}, "CreatedOrgId": null, "Status": null }

) to

<output-dir>/signup-request-result.json

; do not hand-author this file. This is field validation, returned immediately — distinct from the async

ErrorCode

in Step 2. These are server-side rejections (the record reaches the org and the platform rejects it at insert time) — do not describe them to the user as "client-side"; the CLI does not validate email/country format, picklist values, or field length locally. Do NOT poll a create that failed, and do NOT proceed to Step 2.

Failure	Meaning → what to tell the user
`missingEdition` / `INVALID_SIGNUP_OPTION`	Neither `TemplateId` nor `Edition` was sent — ask for one and retry.
`redundantTemplateId`	Both `TemplateId` and `Edition` were sent — drop one and retry.
`noPartnerAccess` / `NO_PARTNER_PERMISSION`	A partner/TSO edition was requested but the host org lacks the perm — use a generic edition ( `Developer` , etc.) or get the perm.
duplicate / invalid `Username` ( `INVALID_EMAIL_ADDRESS` )	`Username` is not email-format or not globally unique — ask for a different one and retry.
`INVALID_SIGNUP_COUNTRY`	`Country` is not a valid/allowed ISO code — fix and retry.
`INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST`	`Edition` is not an accepted value for the host org's restricted picklist (e.g. `Ultimate` ) — pick a valid generic edition and retry.
`STRING_TOO_LONG`	A field value exceeds its max length (the message names the field + `max length` , e.g. `LastName` over 80) — shorten it and retry.
`subdomainInUse` / invalid subdomain	Chosen `Subdomain` is taken or invalid — pick another.
`NOT_FOUND` ("The requested resource does not exist") or `INVALID_TYPE` ("sObject type 'SignupRequest' is not supported")	The `SignupRequest` entity is not exposed → the org is not entitled to create trial orgs. Not retryable. Stop and surface the raw CLI error as-is ( `name` / `errorCode` + `message` ), then tell the user to reach out to Salesforce support to get the org enabled. Do not name or diagnose the missing permission.
`INSUFFICIENT_ACCESS_OR_READONLY`	The entity is exposed but the user lacks the access to create the record — a user-permission problem, distinct from the org-entitlement failure above. Fix the user's permissions and retry.

For the full catalog and prefixes →

references/error_codes.md

For the full required/optional field list, types, and perm-gated fields → load
```
references/signup_request_fields.md
```
.
Do NOT send
```
TemplateId
```
together with clone/source-org fields (
```
redundantTemplateId
```
error). Do NOT request a partner/Trialforce edition without the host org's partner/TMC perm.

使用收集到的输入调用创建脚本。脚本会强制执行「

TemplateId

Edition

二选一」规则，组装并引用

--values

负载，运行插入操作，成功时打印分配的

0SR…

ID。请通过Skill目录的绝对路径引用脚本（

<skill_dir>/scripts/…

）——切勿使用

./scripts/

，因为它会解析为用户的工作目录。

使用模板：

bash

SR_ID=$(bash "<skill_dir>/scripts/create_signup_request.sh" \
  --target-org <HOST_ORG> \
  --last-name <LAST_NAME> --email <EMAIL> --username <UNIQUE_USERNAME> \
  --company "<COMPANY>" --country <ISO> --template-id 0TT... \
  --output-dir force-app/main/adk-eval-output)

使用版本（通用试用，无模板）： 将

--template-id 0TT...

替换为

--edition Developer

（或

Enterprise

等）。仅在用户提供了

FirstName

时添加

--first-name <NAME>

——此Skill不发送其他可选字段。脚本会拒绝同时提供

--template-id

和

--edition

，或两者都不提供的情况。

传入

--output-dir

（当

force-app/main/adk-eval-output

存在时使用该路径），这样如果创建操作被拒绝，脚本仍会将创建失败的结果和原始错误写入

<output-dir>/signup-request-result.json

——即使未创建组织，也会生成运行的输出工件。成功时，此写入操作会由步骤2的读取操作完成。

成功时脚本会打印

0SR…

格式的SignupRequest ID（将其捕获为

SR_ID

）。如果传入

--json

参数，会获取原始的

sf

创建包，其中包含的是一个句柄而非组织：

json

{ "status": 0, "result": { "id": "0SRxx0000000000", "success": true, "errors": [] } }

处理创建错误（同步字段验证）。创建被拒绝时，脚本会以非零状态退出，并将原始CLI错误（

name

code

message

）打印到标准错误流——原样展示错误并按照下表处理。如果传入了

--output-dir

，脚本还会将创建失败的工件（

{ "outcome": "create-rejected", "error": {…}, "CreatedOrgId": null, "Status": null }

）写入

<output-dir>/signup-request-result.json

；请勿手动创建此文件。这是字段验证，会立即返回——与步骤2中的异步

ErrorCode

不同。这些是服务器端拒绝（记录已提交到组织，平台在插入时拒绝）——不要向用户描述为「客户端错误」；CLI不会在本地验证邮箱/国家格式、选择列表值或字段长度。请勿重试失败的创建操作，也不要继续执行步骤2。

失败类型	含义→告知用户的内容
`missingEdition` / `INVALID_SIGNUP_OPTION`	未传入 `TemplateId` 或 `Edition` ——请用户提供其一并重试。
`redundantTemplateId`	同时传入了 `TemplateId` 和 `Edition` ——移除其一并重试。
`noPartnerAccess` / `NO_PARTNER_PERMISSION`	请求了合作伙伴/TSO版本，但宿主组织无权限——使用通用版本（如 `Developer` ）或获取权限。
重复/无效 `Username` （ `INVALID_EMAIL_ADDRESS` ）	`Username` 不是邮箱格式或不全局唯一——请用户更换并重试。
`INVALID_SIGNUP_COUNTRY`	`Country` 不是有效/允许的ISO代码——修正后重试。
`INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST`	`Edition` 不是宿主组织受限选择列表中的可接受值（例如 `Ultimate` ）——选择有效的通用版本并重试。
`STRING_TOO_LONG`	某个字段值超过最大长度（消息会指明字段+ `max length` ，例如 `LastName` 超过80字符）——缩短后重试。
`subdomainInUse` / 无效子域名	所选 `Subdomain` 已被占用或无效——更换一个。
`NOT_FOUND` （"请求的资源不存在"）或 `INVALID_TYPE` （"不支持sObject类型'SignupRequest'"）	`SignupRequest` 实体未被暴露→该组织无创建试用组织的权限。不可重试。停止操作并原样展示原始CLI错误（ `name` / `errorCode` + `message` ），然后告知用户应联系Salesforce支持团队以启用该组织的权限。不要指出或诊断缺少的具体权限。
`INSUFFICIENT_ACCESS_OR_READONLY`	实体已暴露，但用户无创建记录的权限——这是用户权限问题，与上述组织权限失败不同。修复用户权限后重试。

完整的错误目录和前缀请查看

references/error_codes.md

。

完整的必填/可选字段列表、类型和受权限限制的字段请查看
```
references/signup_request_fields.md
```
。
请勿同时发送
```
TemplateId
```
和克隆/源组织字段（会触发
```
redundantTemplateId
```
错误）。请勿在宿主组织无合作伙伴/TMC权限时请求合作伙伴/Trialforce版本。

Step 2 — Read the request once the org id is available (creation is async)

步骤2——组织ID可用后读取请求（创建为异步操作）

Provisioning happens asynchronously after the insert, so re-read the record to pick up the assigned org id. Invoke the read script — it applies a fixed, bounded read-back policy internally (stopping as soon as

CreatedOrgId

is populated or the status is terminal, and never polling indefinitely), prints the record as JSON, and writes the output artifact when

--output-dir

is given. Then act on the script's exit code (below) — the retry count and delay are the script's own deterministic logic; you do not re-implement or re-count them in prose. If the org id is not yet available, the script exits

so you can hand the request id back to the user:

bash

bash "<skill_dir>/scripts/get_signup_request.sh" \
  --target-org <HOST_ORG> --id "$SR_ID" [--output-dir <DIR>]

The script prints the

SignupRequest

record (the

sf

envelope's

result

) as JSON. Read these fields from it:

```
CreatedOrgId
```
— the new trial org id (
```
00D…
```
, 15 chars). Populated as soon as the org is allocated (often while
```
Status
```
is still
```
InProgress
```
); this is the script's stop signal.
```
CreatedOrgInstance
```
— instance hosting the new org (target follow-up calls here).
```
Username
```
— the admin login username on the record. Report the value read back from the record, not the raw input — it is lowercased on save, so the stored value is the accurate one to hand the user.
```
Status
```
— lifecycle
```
New
```
→
```
InProgress
```
→
```
Success
```
|
```
Error
```
(match case-insensitively).
```
LoginUrl
```
— present only if
```
IsSyncLogin
```
was set on create (perm-gated).

AuthCode

— present only if

ConnectedAppConsumerKey

ConnectedAppCallbackUrl

were set.

```
ErrorCode
```
— populated only when
Status = Error
. This is the async provisioning error (distinct from the synchronous create-time validation in Step 1), prefixed:
- ```
C-
```
  org creation error ·
```
S-
```
  signup data error ·
```
T-
```
  template error (e.g.
```
T-0002
```
  = template not found) ·
```
SH-
```
  org-shape error ·
```
VR-
```
  version-selection error ·
```
X-0001
```
  /
```
X-0002
```
  fatal/should-never-happen.

Act on the script's exit code. The org id lookup runs first — do not report anything to the user until the script returns. Report only what is actually on the record; never invent or relabel the

Status

0
—
```
CreatedOrgId
```
is populated. Proceed to Step 3 and report the org id together with the record's real
```
Status
```
and the
```
Username
```
.
3
— no org id available yet (not an error). The org has not been allocated. The script has already exhausted its bounded read-back — do NOT re-invoke it in a loop to keep polling. Report the SignupRequest id (
0SR…
), the record's Status
exactly as returned, and the
```
Username
```
; tell the user the org id is not available yet, and let them re-check later (see Step 3).
1
—
```
Status = Error
```
(stop and report the
```
ErrorCode
```
and its prefix meaning via
```
references/error_codes.md
```
; the org was not created), or the read itself failed (auth expired,
```
0SR
```
id not found) — surface the raw CLI error and stop.

插入后资源分配是异步进行的，因此需要重新读取记录以获取分配的组织ID。调用读取脚本——脚本内部会应用固定的、有限的读取策略（一旦

CreatedOrgId

被填充或状态变为终端状态就停止，不会无限轮询），以JSON格式打印记录，并在传入

--output-dir

时写入输出工件。然后根据脚本的退出码处理（如下）——重试次数和延迟由脚本自身的确定性逻辑控制；无需在流程中重新实现或计数。如果组织ID尚未可用，脚本会以

状态退出，此时你可以将请求ID返回给用户：

bash

bash "<skill_dir>/scripts/get_signup_request.sh" \
  --target-org <HOST_ORG> --id "$SR_ID" [--output-dir <DIR>]

脚本会以JSON格式打印

SignupRequest

记录（

sf

包中的

result

）。请从中读取以下字段：

```
CreatedOrgId
```
——新试用组织的ID（
```
00D…
```
，15字符）。组织分配完成后会立即填充（通常此时
```
Status
```
仍为
```
InProgress
```
）；这是脚本的停止信号。
```
CreatedOrgInstance
```
——托管新组织的实例（后续调用可针对此实例）。
```
Username
```
——记录中的管理员登录用户名。请报告从记录中读取的值，而非原始输入——保存时会转为小写，因此存储的值才是准确的，应告知用户。
```
Status
```
——生命周期状态：
```
New
```
→
```
InProgress
```
→
```
Success
```
|
```
Error
```
（大小写不敏感）。
```
LoginUrl
```
——仅当创建时设置了
```
IsSyncLogin
```
（受权限限制）时才存在。

AuthCode

——仅当设置了

ConnectedAppConsumerKey

ConnectedAppCallbackUrl

时才存在。

```
ErrorCode
```
——仅当
```
Status = Error
```
时填充。这是异步资源分配错误（与步骤1中的同步创建时验证错误不同），带有前缀：
- ```
C-
```
  组织创建错误 ·
```
S-
```
  注册数据错误 ·
```
T-
```
  模板错误（例如
```
T-0002
```
  =模板未找到） ·
```
SH-
```
  组织形态错误 ·
```
VR-
```
  版本选择错误 ·
```
X-0001
```
  /
```
X-0002
```
  致命/不应发生的错误。

根据脚本的退出码处理。组织ID查找优先进行——在脚本返回前不要向用户报告任何内容。仅报告记录中实际存在的内容；切勿编造或重新标记

Status

：

0
——
```
CreatedOrgId
```
已填充。继续执行步骤3，并向用户报告组织ID、记录的真实
```
Status
```
和
```
Username
```
。
3
——组织ID尚未可用（不是错误）。组织尚未分配。脚本已完成有限次数的读取——请勿循环调用脚本继续轮询。向用户报告SignupRequest ID（
0SR…
）、记录的**
```
Status
```
（原样返回）**和
```
Username
```
；告知用户组织ID尚未可用，可稍后重新查询（见步骤3）。
1
——
```
Status = Error
```
（停止操作并通过
```
references/error_codes.md
```
报告
```
ErrorCode
```
及其前缀含义；未创建组织），或读取操作本身失败（身份验证过期、
```
0SR
```
ID未找到）——展示原始CLI错误并停止操作。

Step 3 — Report details and hand off status checks

步骤3——报告详情并移交状态查询

Report after the Step 2 lookup returns — not before. When the user asks to create (or re-check) the org, run the read-back first and wait for it, then report all available details to the user in one go. Report only what is on the record; never fabricate or relabel a value — especially

Status

, which must be the exact string the response object carries:

SignupRequest id — the
```
0SR…
```
request id (from Step 1). Always report this — it is the handle the user (or a later check) uses to look the request up again, and it is the primary thing to hand back if the org id is not yet available.
CreatedOrgId — the new trial org id (
```
00D…
```
), when populated. If the read returned exit
```
3
```
(org id not yet available), say so plainly: the request was accepted and the org is still being provisioned; there is no org id to share yet.
CreatedOrgInstance — the instance hosting it, if present.
Username — the admin login username as stored on the record (lowercased on save). Always report this — it is what the user logs in with once the org is ready.
Status — the
```
Status
```
value exactly as it appears on the record. Echo whatever string the response carries; do not map, translate, infer, or pick from a fixed list. A still-pending status is normal at this point — provisioning finishes in the background.
LoginUrl / AuthCode — only if present.

Also tell the user that login details for the new org arrive by email — once provisioning completes, a welcome/login email is sent to the

SignupEmail

address, so they should watch that inbox to finish logging in. (This is why

SignupEmail

must be a real, accessible address.)

Then suggest, in plain language, how the user can re-check status later — provisioning may still be completing. Tell them they can just ask (the skill re-reads the record), for example:

"Check the status of my trial org 00D…
" (by the org id), or
"Check the status of signup request 0SR…
" (by the SignupRequest id).

Both resolve to a re-run of the Step 2 read script against the same

SignupRequest

record (the org id is looked up on that record). A later check should report the current

Status

exactly as returned on the record. If the record comes back with an error status, also report the

ErrorCode

and its prefix meaning via

references/error_codes.md

Output artifact. Write the current

SignupRequest

record as the run's output artifact by passing

--output-dir

to the Step 2 read script — the script writes

<output-dir>/signup-request-result.json

(creating the directory if needed). Use

force-app/main/adk-eval-output

as the output directory when it exists:

bash

bash "<skill_dir>/scripts/get_signup_request.sh" \
  --target-org <HOST_ORG> --id "$SR_ID" \
  --output-dir force-app/main/adk-eval-output

This is the run's defined output — do not ask permission before writing it.

请在步骤2的查找操作返回后再报告——不要提前报告。当用户请求创建（或重新查询）组织时，先运行读取操作并等待结果，然后一次性向用户报告所有可用详情。仅报告记录中存在的内容；切勿编造或重新标记值——尤其是

Status

，必须与响应对象中的字符串完全一致：

SignupRequest ID——步骤1中的
```
0SR…
```
请求ID。务必报告此ID——这是用户（或后续查询）用于重新查找请求的句柄，如果组织ID尚未可用，这是主要返回给用户的内容。
CreatedOrgId——新试用组织的ID（
```
00D…
```
），已填充时报告。如果读取操作返回退出码
```
3
```
（组织ID尚未可用），请明确告知：请求已被接受，组织仍在创建中；目前无法提供组织ID。
CreatedOrgInstance——托管组织的实例（如果存在）。
Username——记录中存储的管理员登录用户名（保存时已转为小写）。务必报告此内容——这是组织就绪后用户登录所用的账号。
Status——记录中显示的
Status
值（完全一致）。原样返回响应中的字符串；不要映射、翻译、推断或从固定列表中选择。此时状态仍处于待处理是正常的——资源分配会在后台完成。
LoginUrl / AuthCode——仅当存在时报告。

同时告知用户新组织的登录详情会通过邮件发送——资源分配完成后，欢迎/登录邮件会发送至

SignupEmail

地址，因此用户应留意该邮箱以完成登录。（这就是为什么

SignupEmail

必须是真实可访问的地址。）

然后用通俗易懂的语言建议用户如何稍后重新查询状态——资源分配可能仍在进行中。告知用户只需提出请求即可（此Skill会重新读取记录），例如：

"查询我的试用组织**
```
00D…
```
**的状态"（通过组织ID），或
"查询注册请求**
```
0SR…
```
**的状态"（通过SignupRequest ID）。

两种方式都会针对同一

SignupRequest

记录重新运行步骤2的读取脚本（组织ID会从该记录中查找）。后续查询应报告记录中当前返回的
Status
（完全一致）。如果记录返回错误状态，还需通过

references/error_codes.md

报告

ErrorCode

及其前缀含义。

输出工件。通过向步骤2的读取脚本传入

--output-dir

，将当前的

SignupRequest

记录作为运行的输出工件写入——脚本会写入

<output-dir>/signup-request-result.json

（如果需要会创建目录）。当

force-app/main/adk-eval-output

存在时，请使用该路径作为输出目录：

bash

bash "<skill_dir>/scripts/get_signup_request.sh" \
  --target-org <HOST_ORG> --id "$SR_ID" \
  --output-dir force-app/main/adk-eval-output

这是运行的指定输出——写入前无需询问许可。

Reference File Index

参考文件索引

File	When to read
`references/signup_request_fields.md`	Full field reference — required/optional fields, types, defaults, perm-gated fields, editions
`references/error_codes.md`	Interpreting `ErrorCode` prefixes and common validation failures

文件	阅读时机
`references/signup_request_fields.md`	完整字段参考——必填/可选字段、类型、默认值、受权限限制的字段、版本
`references/error_codes.md`	解析 `ErrorCode` 前缀和常见验证失败

Example Files

示例文件

Load these only when you need to see the concrete shape of a payload or response — they are illustrative samples with placeholder ids (

0SRxx…

00Dxx…

), not values to send.

File	When to read
`examples/create_request.json`	When assembling the create — to confirm the field names/shape of the `SignupRequest` create payload
`examples/success_response.json`	When interpreting a successful create + read-back — shows the record once `CreatedOrgId` is populated
`examples/error_response.json`	When interpreting a rejected create — shows the shape of common validation/error responses

仅当需要查看负载或响应的具体格式时才加载这些文件——它们是带有占位符ID（

0SRxx…

、

00Dxx…

）的示例，并非要发送的值。

文件	阅读时机
`examples/create_request.json`	组装创建请求时——确认 `SignupRequest` 创建负载的字段名称/格式
`examples/success_response.json`	解析成功的创建+读取响应时——展示 `CreatedOrgId` 填充后的记录格式
`examples/error_response.json`	解析被拒绝的创建请求时——展示常见验证/错误响应的格式