dx-org-shape-manage

dx-org-shape-manage

通过 sf org create shape、sf org list shape 和 sf org delete shape 管理 Salesforce 组织形状的完整生命周期——创建、列出和删除。组织形状会捕获源组织的基线设置（功能、限制、版本和 Metadata API 设置），但不包括其数据或元数据。

---

工具限制

执行 sf org ... shape 命令时，只能使用 Bash 工具。请勿使用 MCP 工具——完全忽略它们。

用于评估/测试的输出产物：只要有可用的输出目录，始终将命令的完整 JSON 响应写入文件。不要询问用户要写入哪个文件——本技能规定了文件名。执行每条命令后：(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>：创建组织形状使用 create-shape-result.json，列出组织形状使用 list-shapes-result.json，查询非活动组织形状使用 list-shapes-inactive-result.json，删除组织形状使用 delete-shapes-result.json。这就是生成的输出——无需询问，直接写入。执行这些操作时，不要说“没有文件需要生成”；JSON 结果就是输出产物。

---

范围

• 范围内：创建（sf org create shape）、列出（sf org list shape）、列出特定源组织（SOQL 查询 ShapeRepresentation）的非活动组织形状，以及删除（sf org delete shape）组织形状
• 范围外：创建/检查/列出/删除快照（使用 dx-org-snapshot-manage），创建临时组织（使用 dx-org-manage）

---

必需输入

根据用户请求推断：

• 操作：create、list、list-including-inactive 或 delete（参见工作流步骤 1）
• 源组织（create、delete 和 list-including-inactive）：要创建组织形状的组织，或要删除其组织形状或查询其组织形状的组织的用户名或别名。通过 --target-org 传入。常规列出操作（仅 Active/InProgress）不需要源组织。

说明：

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

---

工作流

1. 识别操作，并匹配下方的命令模式。
2. 对于创建/删除，确认源组织——确定用户名/别名。如果未提供，请通过 sf config get target-org 检查默认值。
3. 通过 Bash 工具执行，并使用 --json 标志。
4. 报告结果（参见输出要求和示例文件）。

命令模式

操作	用户意图	通过 Bash 工具执行
创建	根据某个组织创建组织形状	sf org create shape --target-org <alias> --json
创建	根据默认目标组织创建组织形状	sf org create shape --json
列出	列出所有组织形状及其 ID/状态（仅 Active/InProgress）	sf org list shape --json
列出	将列表保存到文件	sf org list shape --json > tmp/MyOrgShapeList.json
列出（包括非活动组织形状）	列出特定源组织的所有组织形状，包括 Inactive 组织形状	sf data query --target-org <alias> --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json
删除	删除某个组织的组织形状（显示确认提示）	sf org delete shape --target-org <alias> --json
删除	无提示地删除组织形状（用于脚本/CI）	sf org delete shape --target-org <alias> --no-prompt --json

创建组织形状后，运行 sf org list shape --json 获取其组织 ID。

列出非活动形状

sf org list shape 没有用于显示 Inactive 形状的标志，也没有 --target-org 标志（它始终会扫描所有本地已验证身份的组织）。若要查看源组织的完整形状历史记录（包括被之后运行的 sf org create shape 替代的形状），请直接查询 ShapeRepresentation：

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

仅当用户明确要求查看某个指定源组织的非活动形状或全部／历史形状时，才使用此查询。对于普通的“列出我的组织形状”请求，请继续使用 sf org list shape——这是文档中介绍的跨组织命令，且与此技能的其他行为一致。

注意：

• ShapeRepresentation 没有 SourceOrgId、username 或 alias 字段——请按原样报告查询返回的字段（Id、Name、Status、CreatedDate、LastModifiedDate）；不要为这些行虚构 orgId／username／alias。
• 如果用户专门要求查看非活动形状（而非“全部”／“历史”形状），请添加 WHERE Status = 'Inactive'，以便仅筛选非活动形状。
• 需要与创建／删除操作相同的 ShapeRepresentation CRUD 访问权限。

---

规则／约束

约束	原因
始终使用 --json 标志	提供结构化输出，便于可靠地解析和处理错误
源组织必须启用 Org Shape for Scratch Orgs	未启用时，创建／删除操作会因无访问权限而失败——请在源组织中通过 Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs 启用
用户需要访问 ShapeRepresentation 对象	没有 CRUD 访问权限时，创建操作会失败并显示 NoCrudAccessCreateShape——请联系组织管理员
--target-org 指向源组织，而非 Dev Hub	创建／删除操作在此组织上执行；这不是 Dev Hub 操作。列表命令不接受 --target-org
没有 --name／--description 标志	形状以源组织的 ID 为键，而非自定义名称
每个源组织只能有一个活动形状	重新运行创建命令会替换先前的形状（将其标记为非活动）。delete 会删除该组织的所有形状
默认情况下，delete 会提示确认	非交互式／CI 使用时请添加 --no-prompt（-p）；拒绝确认提示会中止操作，不会删除任何内容

---

故障排除

问题	解决方法
ShapeRepresentationNoAccess — “必须先为组织启用组织形状，才能创建组织形状”	源组织未启用组织形状——在源组织中前往 设置 → 暂存组织 → 为暂存组织启用组织形状，开启此选项，然后重试
NoCrudAccessCreateShape — “无法创建组织形状。请联系组织管理员……”	你没有访问 ShapeRepresentation 对象的权限——请组织管理员授予访问权限，然后重试
ShapeCreateFailed — “创建暂存定义文件时出错……”	创建失败的一般错误——确认源组织可访问且已完成身份验证，然后重试；如果问题仍然存在，请联系 Salesforce 支持
创建时出现 UNKNOWN_EXCEPTION（通用错误，附带支持用 ErrorId，重试后仍可复现）	源组织尚未完全启用组织形状，即使 ShapeRepresentation 可能已部分可见——确认源组织中已启用 设置 → 暂存组织 → 为暂存组织启用组织形状，且你的用户对 ShapeRepresentation 具有 CRUD 权限，然后重试
sf org list shape 返回空列表	尚不存在任何形状（或没有状态为 Active/InProgress 的形状）——使用 sf org create shape 创建一个
sf org list shape 未显示用户预期的形状	此命令只显示状态为 Active/InProgress 的形状，且没有可更改此行为的标志——之前运行 sf org create shape 可能已将其标记为 Inactive。请改为针对该特定源组织使用“列出非活动形状”中的 SOQL 查询
删除以代码 68 退出（部分失败）	部分形状删除失败——检查 JSON 中的 failures 数组，查看每个形状对应的消息，然后重试
删除以代码 1 退出（全部失败）	删除完全失败——确认组织已启用组织形状，且你具有访问权限
No org found for <alias> / NamedOrgNotFoundError	源组织别名不存在或尚未完成身份验证——使用 sf org list 验证，或使用 sf org login web 重新进行身份验证
未设置默认目标组织，且未指定 --target-org	提供 --target-org <alias>，或使用 sf config set target-org=<alias> 设置默认组织

---

输出预期

使用 --json 时，所有命令均返回 JSON：

• 创建 → shapeId、success 和 errors。
• 列表 → 形状数组，每个形状包含 orgId、username、alias、shapeId、status（Active 或 InProgress）、createdBy 和 createdDate。
• 列表（包含非活动形状） → SOQL 查询结果（records、totalSize、done），每条记录包含 Id、Name、Status（Active、InProgress 或 Inactive）、CreatedDate 和 LastModifiedDate——不包含 orgId/username/alias，因为 ShapeRepresentation 没有这些字段。
• 删除 → orgId、shapeIds（已删除）和 failures。如果用户拒绝确认提示，则不返回结果。

有关完整的响应结构，请参阅下文引用的示例文件。

---

跨技能集成

需求	委派给
创建暂存组织，或创建/使用快照来创建暂存组织	dx-org-manage 技能
创建快照、查看其状态、列出快照或删除快照	dx-org-snapshot-manage 技能

---

参考文件索引

文件	阅读时机
examples/create_success_output.json	了解成功创建形状时的响应结构
examples/create_error_output.json	处理常见的创建错误场景
examples/list_output.json	了解列表响应结构（组织 ID、状态）
examples/list_inactive_output.json	了解列出包含 Inactive 形状的 SOQL 查询响应结构
examples/delete_output.json	了解删除响应结构（已删除 ID、失败项）
references/cli_flags.md	详细了解创建/列表/删除命令的所有标志