platform-deploy-validate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Validating Deployment

部署验证

Run a server-side validation before deploying metadata. Validation surfaces errors without modifying the org and — for production targets — produces a job ID usable with

platform-quick-deploy

for a fast, test-free deploy.

在部署元数据前执行服务器端验证。验证会暴露错误但不会修改组织，并且针对Production目标会生成一个作业ID，可与

platform-quick-deploy

配合使用，实现快速、无需测试的部署。

Capability Resolution

能力选择

Always prefer

sf project deploy validate

(prod) or

sf project deploy start --dry-run

(sandbox/scratch) over the Tooling API directly.

始终优先使用

sf project deploy validate

（针对Production）或

sf project deploy start --dry-run

（针对沙盒/临时环境），而非直接使用Tooling API。

Workflow

工作流程

Step 1 — Confirm the target org

步骤1 — 确认目标组织

Classify the org with the gate's classifier — it is the authoritative source of truth (it handles sandbox/scratch markers, trial and Developer Edition hosts, and dev hubs, and returns one of

production|sandbox|scratch|trial|devhub|unknown

bash

sf org display --target-org <alias> --json | "${CLAUDE_PLUGIN_ROOT}/scripts/sf-deploy-gate" classify

Only

production

takes the production path (Step 2b); every other result takes the sandbox/scratch path (Step 2a).

使用网关的分类器对组织进行分类——这是权威的事实来源（它处理沙盒/临时环境标记、试用版和开发者版主机以及开发中心，并返回

production|sandbox|scratch|trial|devhub|unknown

中的一种）：

bash

sf org display --target-org <alias> --json | "${CLAUDE_PLUGIN_ROOT}/scripts/sf-deploy-gate" classify

只有

production

采用Production路径（步骤2b）；其他所有结果均采用沙盒/临时环境路径（步骤2a）。

Step 2a — Sandbox/Scratch path (dry-run)

步骤2a — 沙盒/临时环境路径（试运行）

bash

sf project deploy start --dry-run --target-org <alias> --json [scope flags]

Scope flags (use exactly one, not all):

```
--source-dir <path>
```
— deploy a directory
```
--metadata <Type:Name>
```
— deploy specific components
```
--manifest manifest/package.xml
```
— deploy from manifest

Default test level: omit

--test-level

for sandboxes (defers to org default). Add

--test-level RunLocalTests

only if the user asks.

Report back: success/failure, components attempted, any errors. No job ID is returned for dry-runs (this is expected).

bash

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（这是预期行为）。

Step 2b — Production path (validate)

步骤2b — Production路径（验证）

bash

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

Production validations REQUIRE a test level. Use

RunLocalTests

by default; switch to

RunSpecifiedTests --tests <ClassName>...

if the user has explicitly listed tests.

The response returns a job ID (

result.id

) valid for 10 days. Persist it for

platform-quick-deploy

bash

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

Report:

Validation result (passed / failed)
Job ID and 10-day expiry date
Test results summary (run / passed / failed)
Recommended next step:
```
platform-quick-deploy
```
with this job ID

bash

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

Production验证需要指定测试级别。默认使用

RunLocalTests

；如果用户明确列出测试用例，则切换为

RunSpecifiedTests --tests <ClassName>...

。

响应会返回一个作业ID（

result.id

），有效期为10天。请将其持久化以便

platform-quick-deploy

使用：

bash

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

反馈内容：

验证结果（通过/失败）
作业ID及10天有效期截止日期
测试结果摘要（运行数/通过数/失败数）
建议下一步操作：使用此作业ID执行
```
platform-quick-deploy
```

Step 3 — Failure triage

步骤3 — 失败排查

If validation fails, parse

result.details.componentFailures

and

result.details.runTestResult.failures

and surface:

Top 5 component errors with full message
Top 5 test failures with stack
Suggested fix (component name → likely cause: missing dependency, FLS, syntax, etc.)

Do NOT propose fixes that change unrelated metadata. Stay scoped to what the validation reported.

如果验证失败，解析

result.details.componentFailures

和

result.details.runTestResult.failures

并展示：

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

请勿提出修改无关元数据的修复方案。仅针对验证报告的内容提供建议。

Rules

规则

ALWAYS use
```
--json
```
on every CLI call
NEVER skip validation when targeting Production (do not run
```
sf project deploy start
```
against prod from this skill)
NEVER use
```
--ignore-errors
```
or
```
--ignore-warnings
```
during validation; those flags belong to actual deploys, not validation
If the user asks to "deploy to prod" without prior validation, FIRST run validation, THEN hand off to
```
platform-quick-deploy
```
(do not start a regular deploy against prod)
Persist the validation job ID to
```
.sfdx/last-validation.json
```
so the quick-deploy skill can find it

所有CLI调用必须使用
```
--json
```
参数
针对Production目标时，绝不跳过验证（请勿从此技能中针对Production运行
```
sf project deploy start
```
）
验证期间绝不使用
```
--ignore-errors
```
或
```
--ignore-warnings
```
；这些标志属于实际部署，而非验证
如果用户要求“部署到Production”但未事先验证，先执行验证，再移交至
```
platform-quick-deploy
```
（请勿针对Production启动常规部署）
将验证作业ID持久化到
```
.sfdx/last-validation.json
```
，以便快速部署技能可以找到它

Output

输出

Always end with:

✅ Validation passed → next-step pointer to
```
platform-quick-deploy
```
(with job ID + expiry) OR to
```
platform-metadata-deploy
```
for non-prod
❌ Validation failed → categorized error list and suggested next iteration

始终以以下内容结尾：

✅ 验证通过 → 指向
```
platform-quick-deploy
```
的下一步操作提示（包含作业ID和有效期），或针对非Production环境指向
```
platform-metadata-deploy
```
❌ 验证失败 → 分类错误列表及建议的下一步迭代