Salesforce 元数据部署与 CI/CD 编排：需要…

用 sf CLI v2 安全验证、部署、验证和编排 Salesforce 元数据，并处理 scratch org/沙箱/CI/CD 与部署失败诊断。

适用场景

解决思路

1. 仅使用 sf CLI v2 执行 Salesforce 部署编排。
2. 不要使用已退役的 sf scanner；静态分析使用 Code Analyzer v5，即 sf code-analyzer。
3. 在非 source-tracking org 上，deploy/retrieve 命令必须显式指定范围，例如 --source-dir、--metadata 或 --manifest。
4. 真实部署前优先使用 --dry-run 进行验证。
5. 对 Flow 先安全部署，验证后再激活。
6. 元数据验证或部署后，将测试数据创建交给 sf-data。
7. 按默认部署顺序执行：1 Custom objects / fields；2 Permission sets；3 Apex；4 Flows as Draft；5 Flow activation / post-verify，以避免依赖和 FLS 失败。
8. 先询问或推断目标 org alias 和环境类型。
9. 确认部署范围：source-dir、metadata 列表或 manifest。
10. 确认操作类型：仅验证、部署、quick deploy、retrieve 或 CI/CD 指导。
11. 确认所需 test level 和回滚预期。
12. 确认是否涉及特殊元数据类型：Flow、permission sets、agents、packages。
13. 执行预检命令 sf --version。
14. 执行预检命令 sf org list。
15. 执行预检命令 sf org display --target-org <alias> --json。
16. 执行预检命令 test -f sfdx-project.json。
17. 预检阶段确认认证、仓库结构、package 目录和目标范围。
18. 先验证：sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json。
19. 当变更集有针对性时，使用 manifest 或 metadata 范围的验证。
20. 验证成功后，提供下一步安全流程：立即部署。
21. 验证成功后，提供下一步安全流程：分配 permission sets。
22. 验证成功后，提供下一步安全流程：通过 sf-data 创建测试数据。
23. 验证成功后，提供下一步安全流程：运行测试/冒烟检查。
24. 验证成功后，提供下一步安全流程：按顺序编排多个 post-deploy 步骤。
25. 部署最小正确范围，source-dir 部署：sf project deploy start --source-dir force-app --target-org <alias> --wait 30 --json。
26. 部署最小正确范围，manifest 部署：sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30 --json。
27. 使用 Spring '26 相关测试选择的 manifest 部署：sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunRelevantTests --wait 30 --json。
28. 验证成功后的 quick deploy：sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json。
29. 验证部署报告：sf project deploy report --job-id <job-id> --target-org <alias> --json。
30. 随后验证测试、Flow 状态、权限分配和冒烟测试行为。
31. 清晰报告：总结已部署、失败、跳过内容以及下一步安全动作。
32. 使用 references/deployment-report-template.md 输出模板。
33. 处理 FIELD_CUSTOM_VALIDATION_EXCEPTION：可能由 validation rule 或坏测试数据导致，调整数据或规则时序。
34. 处理 INVALID_CROSS_REFERENCE_KEY：缺少依赖，先包含被引用的元数据。
35. 处理 CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY：trigger / Flow / validation 副作用，检查自动化栈和失败逻辑。
36. 处理部署期间测试失败：代码损坏或脆弱测试，运行定向测试，修复根因，重新验证。
37. 处理 permset 中找不到字段/对象：顺序错误，先部署 objects/fields 再部署 permission sets。
38. 处理 Flow invalid / version conflict：依赖或激活问题，先作为 Draft 部署，验证后再激活。
39. 需要完整工作流时查阅 references/orchestration.md 和 references/trigger-deployment-safety.md。
40. CI/CD 默认流水线按此形状：1 authenticate；2 validate repo / org state；3 static analysis；4 dry-run deploy；5 tests + coverage gates；6 deploy；7 verify + notify。
41. 当 org 策略和发布风险允许时，对 Apex 密集型部署考虑 --test-level RunRelevantTests。
42. 配合现代 Apex 测试注解 @IsTest(testFor=...) 和 @IsTest(isCritical=true)，参考 sf-apex。
43. Agentforce 部署时，用本技能编排 agents 周围的部署/发布顺序，但作者决策用 agent-specific 技能。
44. 对 .agent 编写和验证使用 sf-ai-agentscript。
45. 对 Agent Builder / Prompt Builder / metadata 配置使用 sf-ai-agentforce。
46. Agent DevOps 详情（包括 Agent: pseudo metadata、publish/activate、sync-between-orgs）查阅 references/agent-deployment-guide.md。
47. 跨技能集成：custom object/field 创建交给 sf-metadata，因为需先定义元数据再部署。
48. 跨技能集成：Apex 编译/评审/修复交给 sf-apex。
49. 跨技能集成：Flow 创建/修复交给 sf-flow。
50. 跨技能集成：测试数据或 seed records 交给 sf-data。
51. 跨技能集成：Agent Script 构建/发布就绪交给 sf-ai-agentscript。
52. 从 references/orchestration.md、references/deployment-workflows.md、references/deployment-report-template.md 开始查阅。
53. 专用部署安全参考：references/trigger-deployment-safety.md、references/agent-deployment-guide.md、references/deploy.sh。
54. 完成格式输出：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>。

适用边界 · 注意事项

• 不要用于编写 Apex/LWC 代码、创建 metadata XML、构建 Flow、查询 org 数据或编写 Agent Script 逻辑；这些分别交给 sf-apex、sf-lwc、sf-metadata、sf-flow、sf-data、sf-ai-agentscript。
• 不要在未安装/未认证 sf CLI v2 或没有目标 Salesforce org/alias 时使用。
• 不要用本技能做 Agentforce agent 的作者决策；作者决策交给 sf-ai-agentscript 和 sf-ai-agentforce。