dx-org-shape-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dx-org-shape-manage

Coordinates the full lifecycle of Salesforce org shapes — create, list, and delete — via

sf org create shape

sf org list shape

, and

sf org delete shape

. An org shape captures the baseline setup of a source org (features, limits, edition, and Metadata API settings) without its data or metadata.

通过

sf org create shape

、

sf org list shape

和

sf org delete shape

命令协调Salesforce Org Shape的完整生命周期——创建、列出和删除。Org Shape捕获源组织的基线设置（功能、限制、版本和Metadata API设置），不包含其数据或元数据。

Tool Restrictions

工具限制

Use ONLY the Bash tool to execute the

sf org ... shape

commands. Do NOT use MCP tools — ignore them completely.

Output artifacts for eval/testing: ALWAYS write the command's complete JSON response to a file when an output directory is available. Do NOT ask the user what file to write — this skill defines the filenames. After executing each command: (1) if the user specified an output path (e.g. "write all generated files into folder X"), write there immediately; (2) otherwise run

[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'

to detect the eval directory; (3) write the command's full, unmodified JSON response (including the

status

result

warnings

wrapper) to

<output-dir>/<filename>

using these filenames:

create-shape-result.json

for shape creation,

list-shapes-result.json

for listing shapes,

list-shapes-inactive-result.json

for the inactive-shapes SOQL query, or

delete-shapes-result.json

for shape deletion. This is the generated output — write it without asking. Do NOT say "no files to generate" for these operations; the JSON result IS the output artifact.

仅使用Bash工具执行

sf org ... shape

命令。请勿使用MCP工具——完全忽略它们。

评估/测试输出产物： 当存在输出目录时，务必将命令的完整JSON响应写入文件。不要询问用户要写入哪个文件——此Skill已定义文件名。执行每个命令后：(1) 如果用户指定了输出路径（例如“将所有生成的文件写入文件夹X”），立即写入该路径；(2) 否则运行

[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'

来检测评估目录；(3) 将命令的完整、未修改的JSON响应（包括

status

result

warnings

包装器）写入

<output-dir>/<filename>

，文件名规则如下：创建Shape用

create-shape-result.json

，列出Shape用

list-shapes-result.json

，查询非活跃Shape用

list-shapes-inactive-result.json

，删除Shape用

delete-shapes-result.json

。这就是生成的输出——无需询问直接写入。对于这些操作，请勿说“无文件生成”；JSON结果就是输出产物。

Scope

适用范围

In scope: Creating (
```
sf org create shape
```
), listing (
```
sf org list shape
```
), listing including inactive shapes for a specific source org (SOQL against
```
ShapeRepresentation
```
), and deleting (
```
sf org delete shape
```
) org shapes
Out of scope: Creating snapshots, creating scratch orgs (use
```
dx-org-manage
```
)

范围内：创建（
```
sf org create shape
```
）、列出（
```
sf org list shape
```
）、列出特定源组织的所有Shape（包括非活跃的，通过对
```
ShapeRepresentation
```
执行SOQL查询）以及删除（
```
sf org delete shape
```
）Org Shape
范围外：创建快照、创建临时组织（使用
```
dx-org-manage
```
）

Required Inputs

必填输入

Infer from the user's request:

Operation: create, list, list-including-inactive, or delete (see Workflow step 1)
Source org (create, delete, & list-including-inactive): Username or alias of the org to shape / whose shapes to delete or query. Passed via
```
--target-org
```
. Plain listing (Active/InProgress only) needs no source org.

Notes:

There is no
```
--name
```
or
```
--description
```
flag — a shape is identified by the source org's ID, not a custom name.
There is no
```
--target-dev-hub
```
flag — the shape commands operate on the source org directly, not a Dev Hub.

从用户请求中推断：

操作类型：create、list、list-including-inactive或delete（见工作流程步骤1）
源组织（创建、删除、列出含非活跃Shape时）：要创建Shape的组织/要删除或查询其Shape的组织的用户名或别名。通过
```
--target-org
```
参数传递。普通列出操作（仅Active/InProgress状态）无需指定源组织。

注意：

没有
```
--name
```
或
```
--description
```
参数——Shape通过源组织的ID标识，而非自定义名称。
没有
```
--target-dev-hub
```
参数——Shape命令直接对源组织操作，而非Dev Hub。

Workflow

工作流程

Identify the operation and match it to the command pattern below.
For create/delete, confirm the source org — identify the username/alias. If not provided, check the default with
```
sf config get target-org
```
.
Execute via Bash tool with the
```
--json
```
flag.
Report the result (see Output Expectations and the example files).

识别操作类型，并匹配下方的命令模式。
创建/删除操作时，确认源组织——识别用户名/别名。如果未提供，通过
```
sf config get target-org
```
检查默认组织。
通过Bash工具执行，并添加
```
--json
```
参数。
报告结果（见输出预期和示例文件）。

Command Patterns

命令模式

Operation	User intent	Execute via Bash tool
Create	Create shape from an org	`sf org create shape --target-org <alias> --json`
Create	Create shape from the default target org	`sf org create shape --json`
List	List all org shapes + IDs/status (Active/InProgress only)	`sf org list shape --json`
List	Save the list to a file	`sf org list shape --json > tmp/MyOrgShapeList.json`
List (including inactive)	List all shapes — including `Inactive` ones — for a specific source org	`sf data query --target-org <alias> --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json`
Delete	Delete shapes for an org (with confirm prompt)	`sf org delete shape --target-org <alias> --json`
Delete	Delete shapes without prompting (scripts/CI)	`sf org delete shape --target-org <alias> --no-prompt --json`

After creating a shape, run

sf org list shape --json

to get its org ID.

操作类型	用户意图	通过Bash工具执行
Create	从某组织创建Shape	`sf org create shape --target-org <alias> --json`
Create	从默认目标组织创建Shape	`sf org create shape --json`
List	列出所有Org Shape及其ID/状态（仅Active/InProgress）	`sf org list shape --json`
List	将列表保存到文件	`sf org list shape --json > tmp/MyOrgShapeList.json`
List (包含非活跃)	列出特定源组织的所有Shape——包括 `Inactive` 状态的	`sf data query --target-org <alias> --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json`
Delete	删除某组织的Shape（带确认提示）	`sf org delete shape --target-org <alias> --json`
Delete	无提示删除Shape（脚本/CI场景）	`sf org delete shape --target-org <alias> --no-prompt --json`

创建Shape后，运行

sf org list shape --json

获取其组织ID。

Listing Inactive Shapes

列出非活跃Shape

sf org list shape

has no flag to surface

Inactive

shapes and no
--target-org
flag (it always scans every locally authenticated org). To see a source org's full shape history — including shapes superseded by a later

sf org create shape

run — query

ShapeRepresentation

directly:

bash

sf data query --target-org <alias> --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json

Only use this query when the user explicitly asks for inactive or all/historical shapes for a named source org. For ordinary "list my org shapes" requests, keep using

sf org list shape

— it is the documented, cross-org command and matches the rest of this skill's behavior.

Notes:

```
ShapeRepresentation
```
has no
```
SourceOrgId
```
,
```
username
```
, or
```
alias
```
field — report the raw query fields (
```
Id
```
,
```
Name
```
,
```
Status
```
,
```
CreatedDate
```
,
```
LastModifiedDate
```
) as returned; do not invent an
```
orgId
```
/
```
username
```
/
```
alias
```
for these rows.
Add
```
WHERE Status = 'Inactive'
```
to scope to only inactive shapes if the user asks for inactive shapes specifically (as opposed to "all"/"history").
Requires the same
```
ShapeRepresentation
```
CRUD access as create/delete.

sf org list shape

没有参数可以显示

Inactive

状态的Shape，也没有

--target-org

参数（它始终扫描所有本地已认证的组织）。要查看源组织的完整Shape历史——包括被后续

sf org create shape

运行取代的Shape——需直接查询

ShapeRepresentation

：

bash

sf data query --target-org <alias> --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json

仅当用户明确要求查看特定源组织的非活跃或所有/历史Shape时，才使用此查询。对于普通的“列出我的Org Shape”请求，继续使用

sf org list shape

——这是官方文档推荐的跨组织命令，与本Skill的其他行为一致。

注意：

```
ShapeRepresentation
```
没有
```
SourceOrgId
```
、
```
username
```
或
```
alias
```
字段——按返回的原始查询字段（
```
Id
```
、
```
Name
```
、
```
Status
```
、
```
CreatedDate
```
、
```
LastModifiedDate
```
）报告；不要为这些记录虚构
```
orgId
```
/
```
username
```
/
```
alias
```
。
如果用户明确要求查看非活跃Shape（而非“所有”/“历史”），添加
```
WHERE Status = 'Inactive'
```
来筛选仅非活跃Shape。
需要与创建/删除操作相同的
```
ShapeRepresentation
```
CRUD权限。

Rules / Constraints

规则与约束

Constraint	Rationale
Always use `--json` flag	Provides structured output for reliable parsing and error handling
Source org must have Org Shape for Scratch Orgs enabled	Without it, create/delete fail with a no-access error — enable via Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs in the source org
User needs access to the `ShapeRepresentation` object	Without CRUD access, create fails with `NoCrudAccessCreateShape` — ask the org admin
`--target-org` is the SOURCE org, not a Dev Hub	Create/delete operate on this org; it is not a Dev Hub operation. List takes no `--target-org`
No `--name` / `--description` flags	A shape is keyed off the source org's ID, not a custom name
One active shape per source org	Re-running create replaces the prior shape (marks it inactive). `delete` removes all shapes for the org
`delete` prompts for confirmation by default	Use `--no-prompt` ( `-p` ) for non-interactive/CI use; declining the prompt aborts with no deletion

约束	理由
始终使用 `--json` 参数	提供结构化输出，便于可靠解析和错误处理
源组织必须启用Org Shape for Scratch Orgs	未启用的话，创建/删除操作会因无权限错误失败——在源组织中通过设置 → 临时组织 → 启用Org Shape for Scratch Orgs开启
用户需要拥有 `ShapeRepresentation` 对象的访问权限	无CRUD权限的话，创建操作会失败并提示 `NoCrudAccessCreateShape` ——联系组织管理员
`--target-org` 是源组织，而非Dev Hub	创建/删除操作直接对该组织执行；这不是Dev Hub操作。列出操作不需要 `--target-org`
没有 `--name` / `--description` 参数	Shape以源组织的ID为标识，而非自定义名称
每个源组织只能有一个活跃Shape	再次运行创建命令会替换之前的Shape（标记为非活跃）。 `delete` 操作会删除该组织的所有Shape
`delete` 操作默认会提示确认	非交互/CI场景使用 `--no-prompt` （ `-p` ）参数；拒绝确认提示会终止操作且不删除任何内容

Troubleshooting

故障排除

Issue	Resolution
`ShapeRepresentationNoAccess` — "The org needs to be enabled for org shape before one can be created"	Source org isn't enabled for org shape — in the source org go to Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs, turn it on, then retry
`NoCrudAccessCreateShape` — "Can't create org shape. Contact the org admin..."	You lack access to the `ShapeRepresentation` object — ask the org admin to grant access, then retry
`ShapeCreateFailed` — "Error creating scratch definition file..."	Generic create failure — verify the source org is reachable/authenticated and retry; if it persists, contact Salesforce support
`UNKNOWN_EXCEPTION` on create (generic error with a support ErrorId, reproducible on retry)	The source org is not fully enabled for org shape even though `ShapeRepresentation` may be partially visible — confirm Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs is on in the source org and that your user has CRUD on `ShapeRepresentation` , then retry
`sf org list shape` returns an empty list	No shapes exist yet (or none are `Active` / `InProgress` ) — create one with `sf org create shape`
`sf org list shape` doesn't show a shape the user expects	It only surfaces `Active` / `InProgress` shapes and has no flag to change this — a prior `sf org create shape` run may have marked it `Inactive` . Use the SOQL query in "Listing Inactive Shapes" against that specific source org instead
Delete exits with code 68 (partial failure)	Some shapes failed to delete — inspect the `failures` array in the JSON for per-shape messages, then retry
Delete exits with code 1 (all failed)	Deletion failed entirely — confirm the org is enabled for org shape and you have access
`No org found for <alias>` / `NamedOrgNotFoundError`	Source org alias doesn't exist or isn't authenticated — verify with `sf org list` or re-auth with `sf org login web`
No default target org and `--target-org` omitted	Provide `--target-org <alias>` or set a default with `sf config set target-org=<alias>`

问题	解决方法
`ShapeRepresentationNoAccess` — “组织需要启用Org Shape才能创建”	源组织未启用Org Shape——在源组织中进入设置 → 临时组织 → 启用Org Shape for Scratch Orgs，开启后重试
`NoCrudAccessCreateShape` — “无法创建Org Shape。请联系组织管理员...”	你没有 `ShapeRepresentation` 对象的访问权限——请组织管理员授予权限后重试
`ShapeCreateFailed` — “创建临时组织定义文件时出错...”	通用创建失败错误——验证源组织是否可访问/已认证，然后重试；如果问题持续，联系Salesforce支持
创建时出现 `UNKNOWN_EXCEPTION` （包含支持ErrorId的通用错误，重试仍出现）	即使 `ShapeRepresentation` 部分可见，源组织也未完全启用Org Shape——确认源组织中设置 → 临时组织 → 启用Org Shape for Scratch Orgs已开启，且你的用户拥有 `ShapeRepresentation` 的CRUD权限，然后重试
`sf org list shape` 返回空列表	还没有Shape存在（或没有处于 `Active` / `InProgress` 状态的Shape）——使用 `sf org create shape` 创建一个
`sf org list shape` 未显示用户预期的Shape	它仅显示 `Active` / `InProgress` 状态的Shape，且没有参数可以更改此设置——之前的 `sf org create shape` 运行可能已将其标记为 `Inactive` 。改用“列出非活跃Shape”中的SOQL查询针对该特定源组织查询
删除操作返回代码68（部分失败）	部分Shape删除失败——检查JSON中的 `failures` 数组获取每个Shape的错误信息，然后重试
删除操作返回代码1（全部失败）	删除完全失败——确认组织已启用Org Shape且你拥有访问权限
`No org found for <alias>` / `NamedOrgNotFoundError`	源组织别名不存在或未认证——通过 `sf org list` 验证，或使用 `sf org login web` 重新认证
没有默认目标组织且未指定 `--target-org`	指定 `--target-org <alias>` 或通过 `sf config set target-org=<alias>` 设置默认组织

Output Expectations

输出预期

All commands return JSON when

--json

is used:

Create →
```
shapeId
```
,
```
success
```
, and
```
errors
```
.

List → an array of shapes, each with

orgId

username

alias

shapeId

status

(

Active

InProgress

createdBy

, and

createdDate

List (including inactive) → a SOQL query result (

records

totalSize

done

), each record with

Id

Name

Status

(

Active

InProgress

, or

Inactive

CreatedDate

, and

LastModifiedDate

— no

orgId

username

alias

, since

ShapeRepresentation

has no such fields.

Delete →
```
orgId
```
,
```
shapeIds
```
(deleted), and
```
failures
```
. Returns no result if the user declines the confirmation prompt.

See the example files referenced below for full response structures.

添加

--json

参数后，所有命令都会返回JSON：

Create → 返回
```
shapeId
```
、
```
success
```
和
```
errors
```
。
List → 返回Shape数组，每个Shape包含
```
orgId
```
、
```
username
```
、
```
alias
```
、
```
shapeId
```
、
```
status
```
（
```
Active
```
或
```
InProgress
```
）、
```
createdBy
```
和
```
createdDate
```
。
List (包含非活跃) → 返回SOQL查询结果（
```
records
```
、
```
totalSize
```
、
```
done
```
），每条记录包含
```
Id
```
、
```
Name
```
、
```
Status
```
（
```
Active
```
、
```
InProgress
```
或
```
Inactive
```
）、
```
CreatedDate
```
和
```
LastModifiedDate
```
——没有
```
orgId
```
/
```
username
```
/
```
alias
```
，因为
```
ShapeRepresentation
```
没有这些字段。
Delete → 返回
```
orgId
```
、
```
shapeIds
```
（已删除的ID）和
```
failures
```
。如果用户拒绝确认提示，不会返回任何结果。

请参考下方引用的示例文件查看完整响应结构。

Cross-Skill Integration

跨Skill集成

Need	Delegate to
Create a scratch org, or create/use a snapshot	`dx-org-manage` skill

需求	委托给
创建临时组织，或创建/使用快照	`dx-org-manage` Skill

Reference File Index

参考文件索引

File	When to read
`examples/create_success_output.json`	To understand the successful shape-creation response structure
`examples/create_error_output.json`	To handle common create error scenarios
`examples/list_output.json`	To understand the list response structure (org IDs, status)
`examples/list_inactive_output.json`	To understand the SOQL query response structure for listing shapes including `Inactive` ones
`examples/delete_output.json`	To understand the delete response structure (deleted IDs, failures)
`references/cli_flags.md`	For detailed explanation of all flags across create/list/delete

文件	阅读场景
`examples/create_success_output.json`	了解成功创建Shape的响应结构
`examples/create_error_output.json`	处理常见的创建错误场景
`examples/list_output.json`	了解列出操作的响应结构（组织ID、状态）
`examples/list_inactive_output.json`	了解包含 `Inactive` 状态的Shape查询响应结构
`examples/delete_output.json`	了解删除操作的响应结构（已删除ID、失败信息）
`references/cli_flags.md`	详细了解创建/列出/删除操作的所有参数