deploying-metadata

deploying-metadata：全面的 Salesforce DevOps 自动化

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

此技能适用的任务

以下工作请使用 deploying-metadata：

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

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

• 编写 Apex 代码 → generating-apex
• 编写 LWC 组件 → generating-lwc-components
• 创建自定义对象或字段 → generating-custom-object、generating-custom-field
• 构建 Flow → generating-flow
• 执行组织数据操作 → handling-sf-data
• 编写或测试 Agentforce Agent → developing-agentforce

---

关键操作规则

• 仅使用 sf CLI v2。
• 对于不支持源跟踪的组织，部署／检索命令必须明确指定范围，例如 --source-dir、--metadata 或 --manifest。
• 执行实际部署前，优先先使用 --dry-run。
• 对于 Flow，应安全部署，并在验证后再激活。
• 元数据通过验证或部署后，有关创建测试数据的指导应委派给 handling-sf-data。

默认部署顺序

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

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

---

首先收集必要信息

询问或推断：

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

部署前检查：

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

---

建议工作流

1. 部署前检查

确认身份验证、代码库结构、包目录和目标范围。

2. 先验证

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

变更集范围明确时，使用限定清单或元数据范围的验证方式。

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

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

1. 立即部署
2. 分配权限集
3. 通过 handling-sf-data 创建测试数据
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

# quick deploy after successful validation
sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json

5. 验证

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

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

6. 清晰报告

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

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

---

高信号故障模式

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

完整工作流：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) — 编写指南请参阅 generating-apex。

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

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

---

Agentforce 部署说明

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

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

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

• references/agent-deployment-guide.md

---

跨技能集成

需求	委派给	原因
创建自定义对象	generating-custom-object	在部署前定义对象
创建自定义字段	generating-custom-field	在部署前定义字段
Apex 编写 / 修复	generating-apex	编写和修复代码
创建 / 修复 Flow	generating-flow	Flow 编写和激活指南
测试数据或种子记录	handling-sf-data	先描述再设置数据，并进行清理
Agent 编写和发布就绪检查	developing-agentforce	确保 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>