platform-metadata-deploy

platform-metadata-deploy：全面的 Salesforce DevOps 自动化

当用户需要部署编排时使用此技能：包括试运行验证、定向或基于清单的部署、CI/CD 工作流建议、临时组织管理、故障排查，或 Salesforce 元数据的安全发布顺序。

此技能适用的任务

在任务涉及以下内容时使用 platform-metadata-deploy：

• sf project deploy start、quick、report 或检索工作流
• 对象、权限集、Apex 和 Flows 的发布顺序
• CI/CD 门禁、测试级别选择或部署报告
• 部署失败和依赖项排序问题的排查

以下情况应委派给其他技能：

• 编写 Apex 代码（此技能只负责部署）
• 编写 LWC 组件 → experience-lwc-generate
• 创建自定义对象或字段 → platform-custom-object-generate
• 构建 Flows → automation-flow-generate
• 执行组织数据操作 → platform-data-manage
• 编写或测试 Agentforce agents → agentforce-generate

---

关键操作规则

• 仅使用 sf CLI v2。
• 对于非源代码跟踪组织，部署／检索命令必须指定明确范围，例如 --source-dir、--metadata 或 --manifest。
• 正式部署前，优先先使用 --dry-run。
• 绝不能对生产组织运行 sf project deploy start。 生产部署必须使用下文的验证 → 快速部署流程（服务器端验证会返回一个 10 天有效的作业 ID；快速部署会在无需重新运行测试的情况下将其正式部署，但必须先获得明确确认）。
• 对于 Flows，应安全部署，并且仅在验证后激活。
• 元数据验证或部署完成后，测试数据创建指南应委派给 platform-data-manage。

默认部署顺序

阶段	元数据
1	自定义对象／字段
2	权限集
3	Apex
4	Flows（草稿）
5	Flow 激活／部署后验证

此顺序可避免许多依赖项和 FLS 失败。

---

首先收集所需信息

询问或推断以下信息：

• 目标组织别名和环境类型
• 部署范围：source-dir、元数据列表或清单
• 此操作是仅验证、部署、快速部署、检索，还是 CI/CD 指南
• 所需的测试级别和回滚预期
• 是否涉及特殊元数据类型（Flow、权限集、agents、软件包）

部署前检查：

sf --version
sf org list --skip-connection-status
sf org display --target-org <alias> --json
test -f sfdx-project.json

---

推荐工作流

1. 部署前检查

确认身份验证、仓库结构、软件包目录和目标范围。

1a. 对目标组织分类（决定走生产环境还是非生产环境路径）

任何部署之前，先根据 sf org list 记录对目标组织进行分类——路径取决于该组织是否为生产环境。不要根据 sf org display 进行分类：它只报告纯 My Domain，且省略 sandbox/scratch/trial 字段，因此 Sandbox-or-Demo Org (SDO) 会被误判为生产环境（forcedotcom/sf-skills#356）。sf org list 记录包含真实的分类布尔值。传入 --skip-connection-status，这样就只进行本地读取，不会为每个已认证组织刷新 OAuth 令牌（forcedotcom/sf-skills#349）：

sf org list --skip-connection-status --json

找到 alias、username 或 orgId 与目标匹配的记录，然后根据该记录分类（以第一个匹配项为准）：

• Scratch — isScratch 为 true。
• Sandbox — isSandbox 为 true，或者 instanceUrl 包含 --（My Domain 的 sandbox 标记）或 test.salesforce.com。
• Trial / Developer Edition — trailExpirationDate（CLI 中的拼写；也接受 trialExpirationDate）是一个未来日期，或者 instanceUrl 主机包含 orgfarm-、.develop.my.salesforce.com、.pc-rnd. 或 .scratch.my.salesforce.com。过去的日期不算——登录时会缓存该日期，且不会刷新，因此已转换的 trial 会保留过期的旧日期，不属于 trial。

其他所有情况均为生产环境——包括没有显示上述任何信号的 Dev Hub（isDevHub 为 true），因为 Dev Hub 通常在客户自己的生产组织中启用。如果找不到匹配记录，或记录没有可用信息（没有 instanceUrl 且没有任何标志），则视为未知，并在继续之前询问用户，而不是假定为生产或非生产环境。

• 非生产环境 → dry-run + deploy 路径（步骤 2–6）。
• 生产环境 → validate → quick-deploy 路径（生产环境部署）。切勿对生产环境运行 sf project deploy start。

2. 先验证（非生产环境）

sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json

变更集范围明确时，使用基于 manifest 或元数据范围的验证。

3. 验证成功后，提供下一个安全工作流选项

验证成功后，引导用户执行正确的下一步：

1. 立即部署
2. 分配权限集
3. 通过 platform-data-manage 创建测试数据
4. 运行测试 / 冒烟检查
5. 按顺序编排多个部署后步骤

4. 部署最小且正确的范围

# source-dir deploy
sf project deploy start --source-dir force-app --target-org <alias> --wait 30 --json

# manifest deploy
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30 --json

# manifest deploy with Spring '26 relevant-test selection
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunRelevantTests --wait 30 --json

5. 验证

sf project deploy report --job-id <job-id> --target-org <alias> --json

然后验证测试、Flow 状态、权限分配和冒烟测试行为。

6. 清晰汇报

总结已部署的内容、失败的内容、跳过的内容，以及下一个安全操作。

输出模板：references/deployment-report-template.md

---

生产环境部署（validate → quick-deploy）

生产环境绝不会通过 sf project deploy start 部署。这是一个两步晋级流程：先通过服务端验证生成作业 ID，然后通过 quick deploy 晋级该已验证的作业，且不会重新运行测试，并要求明确确认。

P1. 针对生产环境进行验证

生产环境验证必须指定测试级别。默认使用 RunLocalTests；只有用户明确列出测试时，才切换为 RunSpecifiedTests --tests <ClassName>...。

sf project deploy validate --target-org <alias> --json [scope flags] --test-level RunLocalTests

范围标志——必须且只能使用一个：--source-dir <path>、--metadata <Type:Name> 或 --manifest manifest/package.xml。

响应会返回一个作业 ID（result.id），有效期为 10 天。请将其与目标的不可变身份信息一并保存——即通过 sf org display 获取的组织 ID 和实例 URL，而不只是别名——这样快速部署才能证明此验证对应的是即将部署到的组织：

mkdir -p .sfdx
ORG_JSON=$(sf org display --target-org <alias> --json)
ORG_ID=$(printf '%s' "$ORG_JSON" | jq -r '.result.id')
INSTANCE_URL=$(printf '%s' "$ORG_JSON" | jq -r '.result.instanceUrl')
printf '{"jobId":"%s","createdAt":"%s","targetOrg":"%s","orgId":"%s","instanceUrl":"%s","testLevel":"RunLocalTests"}\n' \
  "<id>" "<iso8601>" "<alias>" "$ORG_ID" "$INSTANCE_URL" > .sfdx/last-validation.json

验证失败时，请根据 result.details.componentFailures 和 result.details.runTestResult.failures 进行排查——展示主要组件错误和测试失败，并给出有针对性的修复方向，然后停止。验证期间绝不使用 --ignore-errors/--ignore-warnings。

P2. 严格把关快速部署

部署之前，核实以下五项：

1. 目标是生产环境——通过步骤 1a 的分类结果重新确认。
2. 存在验证记录——读取 .sfdx/last-validation.json，或询问作业 ID，或回退到 --use-most-recent。现在就将 --use-most-recent 解析为具体的作业 ID（不要将其作为未解析的标志继续传递），以便下面的检查针对已知作业运行。
3. 验证属于此目标——重新运行 sf org display --target-org <alias> --json，并要求当前的 result.id（组织 ID）与 .sfdx/last-validation.json 中保存的 orgId 相同。这可以避免缓存过期的风险：缓存的作业 ID 会从部署缓存中解析其组织，因此如果不执行此检查，横幅可能显示组织 B，而作业却会部署到组织 A。若不匹配，或保存的记录缺少可供比对的 orgId/instanceUrl，则视为必须停止，并针对预期目标重新验证（P1）。绝不部署无法证明目标组织的验证记录。
4. 验证仍然有效——显式指定的 --job-id 不超过 10 天；通过 --use-most-recent 解析出的记录不超过 3 天。若已过期，先重新验证（P1）。
5. 明确的用户确认——显示下方横幅，并要求用户明确回复 "yes"。横幅中的每个字段都必须来自已核实的验证记录和刚刚获取的组织数据，绝不可使用未经核实的输入。绝不自动确认。

┌─ PRODUCTION DEPLOY ─────────────────────────────┐
│ Org alias:      <alias>                         │
│ Instance:       <instanceUrl>                   │
│ Edition:        <edition>                       │
│ Validation ID:  <jobId>                         │
│ Validated:      <createdAt> (X days ago)        │
│ Components:     <componentCount> queued         │
│ Tests:          <run>/<passed>/<failed>         │
└─────────────────────────────────────────────────┘
Confirm deploy to PRODUCTION? (yes/no)

sf org display --json 不会返回版本。请从 Organization 对象的 OrganizationType 中读取 <edition>（例如 Enterprise Edition）：

sf data query --query "SELECT OrganizationType FROM Organization" --target-org <alias> --json | jq -r '.result.records[0].OrganizationType'

P3. 推广并审计

P2 横幅中的字面文本“yes”即为授权。在 Salesforce 开发插件上下文中，PreToolUse 钩子（sf-deploy-gate）会阻止不带参数的生产环境 deploy quick，并且仅在命令包含机器可读的确认标记 CONFIRM_PROD=1 时才允许执行。输出此标记，以传递用户刚刚给出的确认——它不是独立的绕过方式，因此只能在用户明确回答“yes”之后添加，绝不可提前添加：

# plugin context: CONFIRM_PROD=1 relays P2's confirmation to the safety hook
CONFIRM_PROD=1 sf project deploy quick --job-id <validation-id> --target-org <alias> --wait 30 --json

在插件之外（裸 CLI、无头模式/MCP）没有此类钩子——运行相同命令，但不带该标记。

Quick deploy 会启动一个具有自身作业 ID 的新部署——不会复用验证 ID。捕获响应并提取新 ID，轮询、报告和审计文件名都使用这个 ID；验证 ID 则单独保留以便追踪。如果响应中没有部署 ID，则停止：

QUICK_RESULT=$(CONFIRM_PROD=1 sf project deploy quick --job-id <validation-id> --target-org <alias> --wait 30 --json)
QUICK_DEPLOY_ID=$(printf '%s' "$QUICK_RESULT" | jq -r '.result.id')
[ -n "$QUICK_DEPLOY_ID" ] && [ "$QUICK_DEPLOY_ID" != "null" ] || { echo "No quick-deploy ID returned — do not report the validation ID as the deploy; investigate."; exit 1; }

Quick deploy 会推广已验证的组件，且不会重新运行测试。保存quick deploy 操作（而非验证操作）的报告以留存审计记录，然后指导部署后的验证（对关键路径进行冒烟测试、关注 Setup → Deployment Status，如果出现回归则准备回滚计划）：

mkdir -p .sfdx/deploy-history
sf project deploy report --job-id "$QUICK_DEPLOY_ID" --target-org <alias> --json > ".sfdx/deploy-history/${QUICK_DEPLOY_ID}.json"

如果 quick deploy 超时或仍处于进行中状态，使用 quick-deploy ID 进行轮询，而不是验证 ID。

在明确确认后添加 CONFIRM_PROD=1 是获准的操作方式——这并非“绕过”门禁。但绝不可覆盖用户尚未确认的拒绝，也绝不可覆盖因其他原因导致的拒绝——例如目标不匹配（P2 检查 3）、破坏性部署，或组织未知/未解决。说明这些拒绝并停止。

---

高信号故障模式

错误 / 症状	可能原因	默认修复方向
FIELD_CUSTOM_VALIDATION_EXCEPTION	验证规则或测试数据不正确	调整数据或规则时机
INVALID_CROSS_REFERENCE_KEY	缺少依赖项	先包含被引用的元数据
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY	触发器 / Flow / 验证的副作用	检查自动化调用链和失败逻辑
部署期间测试失败	代码有问题或测试不稳定	运行定向测试、修复根本原因并重新验证
权限集中的字段/对象未找到	顺序错误	先部署对象/字段，再部署权限集
Flow 无效 / 版本冲突	依赖项或激活问题	以 Draft 部署、验证，然后激活

完整工作流：references/orchestration.md、references/trigger-deployment-safety.md

---

CI/CD 指南

默认流水线结构：

1. 身份验证
2. 验证仓库 / 组织状态
3. 静态分析
4. 试运行部署
5. 测试 + 覆盖率门槛
6. 部署
7. 验证 + 通知

• 当组织策略和发布风险允许时，可考虑在 Apex 密集型部署中使用 --test-level RunRelevantTests。
• 配合现代 Apex 测试注解，例如 @IsTest(testFor=...) 和 @IsTest(isCritical=true)。

静态分析现已使用 Code Analyzer v5（sf code-analyzer），而非已停用的 sf scanner。

深入参考：references/deployment-workflows.md

---

Agentforce 部署说明

使用此技能协调 Agent 周边的部署/发布顺序，但内容编写决策应使用 Agent 专属技能：

• agentforce-generate，用于 .agent 编写、Agent Builder、Prompt Builder 和元数据配置

有关 Agent DevOps 的完整详情，包括 Agent: 伪元数据、发布/激活以及组织间同步，请参阅：

• references/agent-deployment-guide.md

---

跨技能集成

需求	委派给	原因
创建自定义对象／字段	platform-custom-object-generate	部署前定义对象和字段
部署后运行测试	platform-apex-test-run	部署后执行测试并检查覆盖率
创建／修复 Flow	automation-flow-generate	Flow 编写和激活指南
测试数据或种子记录	platform-data-manage	先描述再设置数据并进行清理
Agent 编写和发布准备情况	agentforce-generate	确保 Agent 特定内容正确

---

参考索引

从这里开始

• references/orchestration.md
• references/deployment-workflows.md
• references/deployment-report-template.md

专项部署安全

• references/trigger-deployment-safety.md
• references/agent-deployment-guide.md
• references/deploy.sh

资源模板

• assets/package.xml — 涵盖常见元数据类型的清单模板
• assets/destructiveChanges.xml — 用于从目标组织中移除元数据的模板

---

评分指南

分数	含义
90+	部署计划和执行指南完善
75–89	部署指南良好，仅有少量待审核事项
60–74	对部署风险的覆盖不完整
< 60	信心不足；推广前应完善计划

---

完成格式

Deployment goal: <validate / deploy / retrieve / pipeline>
Target org: <alias>
Scope: <source-dir / metadata / manifest>
Result: <passed / failed / partial>
Key findings: <errors, ordering, tests, skipped items>
Next step: <safe follow-up action>