platform-sharing-rules-generate

共享规则生成器

获取、创建、编辑和删除 Salesforce 共享规则元数据，以控制超出组织范围默认值的记录级访问权限。支持基于条件的规则、基于角色/组所有者的规则，以及 Experience Sites 的访客用户规则。

范围

• 范围内：创建、编辑、删除和检索（获取）sharingCriteriaRules、sharingOwnerRules 和 sharingGuestRules 元数据；使用 Metadata API Retrieve 模式从组织检索现有共享规则；将新规则追加到现有文件；修改规则条件或访问级别；从元数据文件中移除规则；为访客和门户配置文件配置规则。
• 范围外：更改组织范围默认值（OWD/共享模型）、创建 Experience Sites、配置权限集或配置文件（使用 platform-permission-set-generate）、基于区域的共享规则。

---

澄清问题

如果尚不明确，请在继续之前向用户确认：

对于获取操作：

• 应检索哪个对象的共享规则？（标准或自定义对象 API 名称，或所有对象）
• 应从哪个目标组织检索规则？（组织别名或默认组织）

对于创建操作：

• 共享规则应应用于哪个对象？（标准或自定义对象 API 名称）
• 规则类型是什么？（基于条件的规则、基于角色/组所有者的规则，或访客用户规则）
• 应与谁共享记录？（角色名称、组、门户角色或访客用户昵称）
• 访问级别是什么？（Read 或 Read/Write）
• 对于基于条件的规则：需要匹配哪些字段条件？

对于编辑操作：

• 应修改哪个现有规则？（规则 fullName 或标签）
• 要进行哪些更改？（访问级别、条件、标签——注意：sharedTo 和 sharedFrom 无法就地编辑）

对于删除操作：

• 应移除哪些规则？（规则 fullName 或标签）
• 确认规则所属的对象

---

必需输入

继续之前，收集或推断以下信息：

• 对象 API 名称：规则所针对的 sObject（例如，Account、Property__c）
• 规则类型：sharingCriteriaRules、sharingOwnerRules 或 sharingGuestRules 之一
• 共享目标：角色、组、门户角色或访客用户社区昵称
• 访问级别：Read 或 Edit（对应只读或读/写）
• 条件（适用于条件规则/访客规则）：每个筛选项的字段名称、操作和取值

除非另有指定，否则使用以下默认值：

• 访问级别：Read
• 条件规则的 includeRecordsOwnedByAll：true
• 访客规则的 includeHVUOwnedRecords：false
• 账户共享规则包含 accountSettings，且所有子访问级别都设为 None

---

工作流

每个阶段内的步骤按顺序执行。阶段 3 根据操作类型分支——只执行匹配的分支。阶段 4 仅适用于创建、编辑和删除（获取操作在阶段 3 结束）。

阶段 1 — 发现

1. 解析 SFDX 项目路径——找到项目的 sfdx-project.json，并确定 sharingRules/ 所在的包目录。

2. 始终使用 Metadata API Retrieve 模式从组织检索最新的共享规则：

   sf project retrieve start --metadata "SharingRules:<ObjectName>" --target-org <org>
   

   这样可以确保本地文件反映组织的当前状态。切勿信任可能过时的本地文件——对过时文件执行编辑或删除操作，可能会重新创建组织中已删除的规则，或覆盖其他用户所做的更改。

3. 读取检索到的文件——解析 <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml，了解现有规则并避免重复。

阶段 2 — 确定操作和规则类型

4. 识别操作 — 确定用户想要获取、创建、编辑还是删除共享规则。

5. 根据用户意图选择规则类型。阅读 references/rule-types.md，了解每种类型的完整架构及其必需元素。

6. 对于 Account 共享规则：必须包含 accountSettings 元素。除非用户另有说明，否则将子访问级别设为 None。

7. 对于 Guest 规则：sharedTo 必须使用 <guestUser>，并填入站点访客用户的社区昵称。Guest 规则绝不能使用 <role> 或 <group>。

阶段 3 — 执行操作

获取：

8a. 使用阶段 1 中已检索的文件 — 第 2 步的检索操作已从 org 中获取最新的 <ObjectName>.sharingRules-meta.xml。无需再次检索。

8b. 读取并展示检索到的规则 — 解析 .sharingRules-meta.xml 文件，并以易读的格式向用户展示规则，包括： - 规则名称（fullName）和标签 - 规则类型（基于条件、基于所有者或 Guest） - 访问级别 - 共享对象 - 条件（如适用）

对于获取操作，跳过阶段 4（无需写入）。检索操作本身已将元数据文件写入本地项目。

创建：

8a. 按照 references/rule-types.md 中的架构构造 XML。主要结构： - 每个对象对应一个 .sharingRules-meta.xml 文件 - 同一对象的所有规则放在同一个文件中 - 如果要追加到现有文件中，将新规则元素添加到现有 <SharingRules> 根元素内

8b. 为规则命名 — 根据意图生成 <fullName>（PascalCase，不含空格，且描述清晰）。生成匹配的 <label>，使用带空格的标题式大小写。

编辑：

8a. 定位目标规则 — 在现有的 .sharingRules-meta.xml 文件中，通过 <fullName> 或 <label> 查找规则。

8b. 限制不支持的编辑 — 平台不支持就地修改 <sharedTo> 或 <sharedFrom> 元素。如果用户请求更改共享目标或来源，拒绝编辑，并告知用户应删除现有规则，然后创建一个目标符合要求的新规则。规则类型变更也采用相同方式（参见 TC-16）。

8c. 根据规则类型确定修改内容： - 基于所有者的规则（sharingOwnerRules）：只能编辑 <accessLevel>。平台不支持修改所有者规则中的其他任何元素（sharedTo、sharedFrom、label）。如果用户请求修改访问级别以外的内容，拒绝请求，并告知用户应先删除规则，再创建新规则。 - 基于条件的规则（sharingCriteriaRules）：支持编辑的元素包括 <accessLevel>、<criteriaItems>、<label> 和 <booleanFilter>。 - Guest 规则（sharingGuestRules）：支持编辑的元素包括 <accessLevel>、<criteriaItems>、<label> 和 <includeHVUOwnedRecords>。

删除：

8a. 定位目标规则 — 在现有的 .sharingRules-meta.xml 文件中，通过 <fullName> 或 <label> 查找规则。

8b. 统计剩余规则数 — 运行 scripts/count-remaining-rules.sh <file> 获取规则总数。如果计数为 1（即只有将要删除的规则），必须在阶段 4 中彻底删除该文件。

8c. 将破坏性部署委托给 platform-destructive-deploy — 普通的 sf project deploy start 仅会添加内容，无法从 org 中删除规则。将此操作委托给 platform-destructive-deploy 技能，并提供以下上下文： - 元数据类型：SharingCriteriaRule、SharingOwnerRule 或 SharingGuestRule（取决于规则类型） - 成员：<ObjectName>.<RuleFullName> - 目标 org：用户指定的 org

阶段 4 — 编写并验证

9. 应用更改：

   • 创建：将文件写入 <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml。
   • 编辑：仅更新步骤 8b 中确定的元素；其他所有元素均保持原样。
   • 删除（仍有规则）：写入已移除目标规则的更新文件。
   • 删除（最后一条规则）：彻底删除文件 <packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml。

10. 运行以下验证清单，并在展示输出前参阅示例文件（examples/create-cases.md、examples/edit-cases.md、examples/delete-cases.md），了解各场景的预期行为。

---

验证清单

通用检查

• 文件是否包含 XML 声明和 <SharingRules xmlns="http://soap.sforce.com/2006/04/metadata"> 根元素？
• 每个对象是否恰好对应一个文件，且所有规则均在其中？
• <fullName> 是否使用 PascalCase，且不含空格？
• 是否存在 <label>，且内容易于理解？
• <accessLevel> 是否为 Read 或 Edit？

条件规则检查

• 是否存在 <includeRecordsOwnedByAll>（必需布尔值）？
• 每个 <criteriaItems> 是否都包含 <field>、<operation> 和 <value>？
• 选项列表值对于目标 org 是否有效？

访客规则检查 严重

• <sharedTo> 是否使用 <guestUser>（而非 <role> 或 <group>）？
• 是否存在 <includeHVUOwnedRecords>（必需布尔值）？
• 是否不存在 <includeRecordsOwnedByAll>（仅条件规则需要，访客规则不需要）？

所有者规则检查

• 规则是否同时包含 <sharedFrom> 和 <sharedTo> 元素？
• 两者是否都使用有效的 <role>、<roleAndSubordinates> 或 <group> 目标？

编辑操作检查

• 编辑是否基于刚刚检索的文件（而非过期的本地副本）？
• 编辑是否仅涉及该规则类型支持的字段？
  • 所有者规则：仅 accessLevel
  • 条件规则：accessLevel、criteriaItems、label、booleanFilter
  • 访客规则：accessLevel、criteriaItems、label、includeHVUOwnedRecords
• <sharedTo>/<sharedFrom> 是否保持不变？（如果用户要求更改这些元素，应拒绝并建议先删除再创建）
• 是否只修改了预期元素？
• 编辑后是否仍保留所有必需元素？
• 修改后的规则是否仍通过上述通用检查？

删除操作检查

• 是否删除了正确的规则（按 <fullName> 匹配）？
• 剩余 XML 是否格式正确且包含适当的 <SharingRules> 根元素？
• 如果没有剩余规则，是否已彻底删除文件？
• 是否已将 platform-destructive-deploy 委派处理，并使用正确的元数据类型（SharingCriteriaRule、SharingOwnerRule 或 SharingGuestRule）？

特定于 Account 的检查 严重

• 如果对象是 Account，是否存在包含全部三个子元素的 <accountSettings>？
• <caseAccessLevel>、<contactAccessLevel>、<opportunityAccessLevel> 是否均已设置？

规则 / 约束

约束	原因
每个对象只能有一个 .sharingRules-meta.xml 文件	平台要求——多个文件会导致部署错误
访客规则的 sharedTo 必须使用 <guestUser>	使用 <role> 或 <group> 会导致错误：“Specify a guest user's nickname for the guestUser field”
Account 规则必须包含 <accountSettings>	缺少该元素会导致错误：“AccountSettings is required for account sharing rules”
条件规则必须包含 includeRecordsOwnedByAll	缺少该字段会导致错误：“Required field is missing: sharingCriteriaRules”
访客规则必须包含 includeHVUOwnedRecords	缺少该字段会导致部署失败
条件字段值必须是组织中存在的选项列表值	无效值会导致错误：“Picklist value does not exist”
切勿对文件路径进行硬编码——应从 sfdx-project.json 解析	客户项目使用自定义包目录
对于托管包中的自定义对象，请使用包含命名空间前缀的完整 API 名称（例如 ns__Object__c）	带命名空间前缀的对象会使用带前缀的名称存储共享规则
sharedTo 和 sharedFrom 不能原地编辑	平台不支持修改共享目标——部署会失败。请删除规则并新建
所有者规则只支持编辑 accessLevel	所有者规则的其他字段（label、sharedTo、sharedFrom）均不可修改——请删除并重新创建
编辑或删除前务必从组织中检索	本地文件可能已过时；编辑过时文件可能会重新创建已删除的规则，或覆盖并发更改
删除规则需要执行破坏性部署	普通部署只会添加内容——不会从组织中删除规则。请交由 platform-destructive-deploy 处理
编辑必须保留未修改的元素	只更改 accessLevel 时，不得更改 criteriaItems 或其他字段
删除时必须移除整个规则块	部分删除会留下无效 XML，并导致部署失败
删除最后一条规则时必须删除文件	不含子元素的空 <SharingRules> 根元素不是有效元数据

---

注意事项

问题	解决方法
访客规则使用了 <role>，而非 <guestUser>	替换为 <guestUser>CommunityNickname</guestUser>
Account 规则缺少 accountSettings	添加 <accountSettings>，并将三个访问级别子元素全部设为 None
条件规则缺少 includeRecordsOwnedByAll	添加 <includeRecordsOwnedByAll>true</includeRecordsOwnedByAll>
选项列表值不匹配	生成条件前，先查询组织中的有效值
追加内容时与现有规则名称重复	写入前检查现有的 <fullName> 值
找不到访客用户昵称	查询：SELECT CommunityNickname FROM User WHERE UserType='Guest' AND IsActive=true
用户要求编辑 sharedTo 或 sharedFrom	不支持——拒绝编辑，并告知用户应删除规则后再新建
用户要求编辑所有者规则中 accessLevel 以外的内容	不支持——所有者规则只允许编辑 accessLevel。拒绝请求，并告知用户应删除后重新创建
编辑导致规则类型变更（例如从条件规则变为所有者规则）	不支持——请删除旧规则并新建
本地文件已过时（规则已在组织中删除或更改）	编辑或删除前务必从组织中重新检索，以免重新创建已删除的规则
使用普通部署删除规则（没有破坏性清单）	规则仍会保留在组织中——请交由 platform-destructive-deploy 正确移除
删除的规则被其他自动化流程引用	提醒用户注意可能产生的下游影响
删除后 XML 格式错误	移除内容后确保 XML 结构正确；验证文件格式良好

---

输出预期

交付内容：

• 对于获取操作：<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml — 从 org 获取的共享规则文件，以及所有已找到规则的格式化摘要
• 对于创建/编辑/删除操作：<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml — 目标对象的完整共享规则文件

---

跨技能集成

需求	委派给
权限集配置	platform-permission-set-generate 技能
创建自定义对象（目标对象不存在时）	platform-custom-object-generate 技能
破坏性部署（从 org 删除规则）	platform-destructive-deploy 技能

---

参考文件索引

文件	阅读时机
references/rule-types.md	第 2 阶段 — 生成任何规则前，获取每种规则类型的完整 XML 架构
scripts/count-remaining-rules.sh	第 3 阶段，第 8b 步（删除）— 统计共享规则元素，以确定是否应删除文件
examples/create-cases.md	第 4 阶段，第 10 步 — 创建和追加场景的预期行为
examples/edit-cases.md	第 4 阶段，第 10 步 — 编辑场景的预期行为
examples/delete-cases.md	第 4 阶段，第 10 步 — 删除场景的预期行为