mcpField
P
platform-deploy-validate

platform-deploy-validate

github.com/forcedotcom云与 DevOps1.1k3.1k 次安装1 天前更新
代码仓库

关于 platform-deploy-validate

用于 Salesforce 项目的部署前验证，按目标组织类型选择沙箱干运行或生产验证。生产验证会保存可供 platform-quick-deploy 使用的作业 ID，并提供失败分类指引。

主要功能

  1. 01按组织类型选择验证流程
  2. 02沙箱与临时组织干运行
  3. 03生产环境运行测试验证
  4. 04保存验证作业 ID 供快速部署
  5. 05归纳组件和测试失败

适用场景

  1. 01部署到生产环境前验证元数据
  2. 02在沙箱中检查部署范围而不修改组织
  3. 03分析部署验证中的组件或测试错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/forcedotcom/sf-skills --skill platform-deploy-validate

安装后在 Claude Code 中输入/platform-deploy-validate确认已加载。

详细介绍

验证部署

部署元数据前，请运行服务端验证。验证会显示错误，但不会修改组织；对于生产环境目标，还会生成一个可用于 platform-quick-deploy 的作业 ID，以便快速部署且无需运行测试。

功能解析

始终优先使用 sf project deploy validate（生产环境）或 sf project deploy start --dry-run（沙盒／临时环境），而不是直接调用 Tooling API。

工作流

步骤 1 — 确认目标组织

使用 gate 的分类器对组织进行分类——它是权威事实来源，并以与部署钩子相同的方式解析组织（可处理沙盒／临时环境标记、试用版和 Developer Edition 组织（包括 SDO），并将没有上述信号的 Dev Hub 视为生产环境；返回值为 production|sandbox|scratch|trial|unknown）：

"${CLAUDE_PLUGIN_ROOT}/scripts/sf-deploy-gate" bucket <alias>

只有 production 才走生产环境路径（步骤 2b）；其他所有结果都走沙盒／临时环境路径（步骤 2a）。unknown 表示无法确认组织类型（通常是组织记录不完整）。请明确说明：部署门仍会允许部署，该组织的保存时自动部署会保持关闭，使用 sf org login web 重新进行身份验证通常可以恢复分类结果。

步骤 2a — 沙盒／临时环境路径（试运行）
sf project deploy start --dry-run --target-org <alias> --json [scope flags]

范围标志（仅使用其中一个，不要全部使用）：

  • --source-dir <path> — 部署一个目录
  • --metadata <Type:Name> — 部署指定组件
  • --manifest manifest/package.xml — 从清单部署

默认测试级别：沙盒环境下省略 --test-level（采用组织默认值）。仅在用户提出要求时添加 --test-level RunLocalTests。

反馈内容：成功／失败、尝试部署的组件，以及任何错误。试运行不会返回作业 ID（这是预期行为）。

步骤 2b — 生产环境路径（验证）
sf project deploy validate --target-org <alias> --json [scope flags] --test-level RunLocalTests

生产环境验证必须指定测试级别。默认使用 RunLocalTests；如果用户明确列出了测试，则改用 RunSpecifiedTests --tests <ClassName>...。

响应会返回一个作业 ID（result.id），有效期为 10 天。请保存该 ID，以供 platform-quick-deploy 使用：

mkdir -p .sfdx
echo '{"jobId":"<id>","createdAt":"<iso8601>","targetOrg":"<alias>","testLevel":"RunLocalTests"}' > .sfdx/last-validation.json

反馈内容：

  • 验证结果（通过／失败）
  • 作业 ID 和 10 天后的到期日期
  • 测试结果摘要（运行数／通过数／失败数）
  • 建议的下一步：使用此作业 ID 调用 platform-quick-deploy
步骤 3 — 失败排查

如果验证失败，请解析 result.details.componentFailures 和 result.details.runTestResult.failures，并列出：

  • 前 5 个组件错误及完整消息
  • 前 5 个测试失败及调用栈
  • 建议的修复方案（组件名称 → 可能的原因：缺少依赖项、FLS、语法错误等）

不要提出会更改无关元数据的修复方案。仅处理验证报告中指出的问题。

规则

  • 每次调用 CLI 时都必须使用 --json
  • 面向 Production 时绝不能跳过验证（不要在此技能中对生产环境运行 sf project deploy start）
  • 验证期间绝不能使用 --ignore-errors 或 --ignore-warnings；这些标志仅适用于实际部署，不适用于验证
  • 如果用户要求“部署到生产环境”，但尚未进行验证，必须先运行验证，然后交由 platform-quick-deploy 处理（不要对生产环境启动常规部署）
  • 将验证作业 ID 保存到 .sfdx/last-validation.json，以便 quick-deploy 技能找到它

输出

始终以以下内容结尾：

  • ✅ 验证通过 → 指向下一步 platform-quick-deploy（附作业 ID 和到期时间），或非生产环境的 platform-metadata-deploy
  • ❌ 验证失败 → 分类列出错误并建议下一轮处理方式

评论

支持 Markdown