Back to Details

platform-environment-validate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Validating: Salesforce Development Environment

验证：Salesforce开发环境

Validate all required prerequisites and surface a clear, actionable status report. This skill is on-demand — it does not run automatically on session start. Run it explicitly to check or repair your local setup.
验证所有必需的先决条件，并生成清晰、可执行的状态报告。此技能为按需触发——不会在会话启动时自动运行。需显式运行以检查或修复本地设置。

Phase 1: Prerequisite Scan

阶段1：先决条件扫描

Run the tool check:
bash
${CLAUDE_PLUGIN_ROOT}/scripts/sf-context check-tools
The output is a JSON object with a 
tools
array. Parse it and render a status report grouped by severity:
=========================

🔴 Critical (N):
   <tool>: <message>

🟡 Warnings (N):
   <tool>: <message>

🟢 Successfully Configured (N):
   <tool> <version>

ℹ️ Informational (N):
   <tool>: <message>

=========================
Status definitions:
  • 🔴 Critical (
    critical
    ) — tool is missing or below minimum version; Salesforce development cannot proceed without it
  • 🟡 Warning (
    warn
    ) — tool is installed but on an old version, non-LTS release, or has a configuration issue
  • 🟢 OK (
    ok
    ) — tool is installed and meets all requirements
  • ℹ️ Info (
    info
    ) — not a problem; a contextual note that cannot be auto-verified (e.g. MCP process health). Informational rows do not count against an "all green" result.
A setup is "all green" when there are no 🔴 or 🟡 rows; ℹ️ rows are expected and fine.
Deterministic results — do NOT override a failure: the JSON report is the authoritative, machine-readable result. If a tool reports 🔴/🟡, report it as-is. Do not re-run the tool a different way (PowerShell, a raw shell probe, a different command) and then present the result as 🟢 — a fallback that happens to find the tool does not mean the deterministic check passed. A failed check must stay failed until that same 
check-tools
check passes. When the report includes a 
diagnostic
block (attached on any critical failure), surface it: it carries the platform, active shell, working directory, plugin root, and the resolved executable paths — the fastest way to see why a tool didn't resolve (e.g. a Windows 
sf.cmd
not on 
PATH
). The diagnostic is secret-free by design; never add tokens or org auth to it.
MCP is reported as three distinct rows — never inferred from one another: 
Salesforce MCP (config)
(is 
.mcp.json
+ the 
sf-mcp-proxy.bundled.js
present?), 
Salesforce MCP (endpoint)
(is the platform endpoint reachable?), and 
Salesforce MCP (process)
(is the MCP process actually healthy?). The process row is reported as ℹ️ informational (not a warning) — this script cannot see the MCP subprocess that Claude Code owns, so a green config/endpoint must not be presented as a working MCP. Confirm process health with 
/mcp
or 
/doctor
. The endpoint row probes the org instance URL as a connectivity proxy, not the platform-MCP endpoint itself.
运行工具检查：
bash
${CLAUDE_PLUGIN_ROOT}/scripts/sf-context check-tools
输出为包含
tools
数组的JSON对象。解析该对象并按严重程度分组呈现状态报告：
=========================

🔴 关键问题 (N)：
   <工具>：<消息>

🟡 警告 (N)：
   <工具>：<消息>

🟢 配置成功 (N)：
   <工具> <版本>

ℹ️ 信息提示 (N)：
   <工具>：<消息>

=========================
状态定义：
  • 🔴 关键（
    critical
    ）——工具缺失或版本低于最低要求；无此工具无法进行Salesforce开发
  • 🟡 警告（
    warn
    ）——工具已安装但版本过旧、非LTS版本或存在配置问题
  • 🟢 正常（
    ok
    ）——工具已安装且满足所有要求
  • ℹ️ 信息（
    info
    ）——无问题；无法自动验证的上下文说明（如MCP进程健康状态）。信息行不会影响“全绿”结果的判定。
当无🔴或🟡行时，即为“全绿”设置；ℹ️行属于预期情况，无需处理。
结果具有确定性——请勿覆盖失败结果： JSON报告是权威的机器可读结果。若某工具报告为🔴/🟡，需如实呈现。请勿通过其他方式（PowerShell、原始shell探测、不同命令）重新运行工具，然后将结果显示为🟢——即使 fallback 方式找到工具，也不代表确定性检查已通过。失败的检查必须保持失败状态，直到同一
check-tools
检查通过。当报告包含
diagnostic
块（在任何关键失败时附加），需展示该内容：它包含平台信息、活动shell、工作目录、插件根目录以及解析后的可执行文件路径——这是快速排查工具无法解析原因的最佳方式（如Windows系统中
sf.cmd
未加入
PATH
）。诊断内容设计为无敏感信息；切勿添加令牌或组织身份验证信息。
MCP需分为三个独立行报告——切勿相互推断：
Salesforce MCP (config)
（是否存在
.mcp.json
和
sf-mcp-proxy.bundled.js
？）、
Salesforce MCP (endpoint)
（平台端点是否可达？）和
Salesforce MCP (process)
（MCP进程是否实际健康？）。进程行报告为ℹ️信息提示（非警告）——此脚本无法查看Claude Code所管理的MCP子进程，因此绿色的配置/端点状态不得表示MCP正常运行。需通过
/mcp
或
/doctor
确认进程健康状态。端点行探测的是组织实例URL作为连接代理，而非平台-MCP端点本身。

Tools Checked

检查的工具

ToolMinimum RequirementVerification
Salesforce CLIPresent, and on the latest release
sf --version
(🟡 when an update is available)
Code Analyzer pluginInstalled or JIT-registered
sf plugins inspect @salesforce/plugin-code-analyzer
, falling back to the CLI's 
oclif.jitPlugins
registry
Node.js>= 18 (even/LTS)
node --version
NPM>= 3.10
npm --version
GitMust be present
git --version
Salesforce MCP (config)
.mcp.json
configured + proxy bundle present		Plugin root 
.mcp.json
check + 
sf-mcp-proxy.bundled.js
presence
Salesforce MCP (endpoint)Org instance URL reachable (connectivity proxy)HTTP probe of org instance URL
Salesforce MCP (process)ℹ️ informational — not verifiable hereConfirm with 
/mcp
or 
/doctor
Source TrackingEnabled for connected org
sf project deploy preview
All external tools (
sf
, 
npm
, 
node
, 
git
) are launched through a single cross-platform resolver: 
shutil.which
(PATHEXT-aware) finds the tool, and a Windows 
.cmd
/
.bat
shim (
sf.cmd
, 
npm.cmd
) is invoked via a COMSPEC-wrapped argv array — never a shell string — so this scan and 
/salesforce-development:org
detect 
sf
/
npm
/the default org correctly on Windows, macOS, and Linux.
Code Analyzer is a JIT plugin — registered ≠ installed. The Salesforce CLI declares 
@salesforce/plugin-code-analyzer
as a "just-in-time" (JIT) plugin: it is only physically installed the first time a 
sf code-analyzer
command runs. Until then, 
sf plugins inspect
fails for it even though it is fully available to the user. The check therefore treats JIT registration as success — if 
inspect
returns no version, it falls back to the CLI's own 
oclif.jitPlugins
registry (read from the root entry of 
sf plugins --json
) and reports 🟢 with the pinned version and a note that it auto-installs on first use. Only a plugin that is neither installed nor JIT-registered is 🔴 critical.
工具最低要求验证方式
Salesforce CLI已安装且为最新版本
sf --version
（有可用更新时显示🟡）
Code Analyzer插件已安装或已注册JIT
sf plugins inspect @salesforce/plugin-code-analyzer
，若失败则回退到CLI的
oclif.jitPlugins
注册表
Node.js>= 18（偶数/LTS版本）
node --version
NPM>= 3.10
npm --version
Git必须已安装
git --version
Salesforce MCP (config)
.mcp.json
已配置且代理包存在		检查插件根目录的
.mcp.json
以及
sf-mcp-proxy.bundled.js
是否存在
Salesforce MCP (endpoint)组织实例URL可达（连接代理）HTTP探测组织实例URL
Salesforce MCP (process)ℹ️ 信息提示——无法在此验证通过
/mcp
或
/doctor
确认
Source Tracking已为连接组织启用
sf project deploy preview
所有外部工具（
sf
、
npm
、
node
、
git
）均通过单一跨平台解析器启动：
shutil.which
（支持PATHEXT）查找工具，Windows系统的
.cmd
/
.bat
Shim（
sf.cmd
、
npm.cmd
）通过COMSPEC包装的argv数组调用——绝不使用shell字符串——因此此扫描和
/salesforce-development:org
可在Windows、macOS和Linux系统上正确检测
sf
/
npm
/默认组织。
Code Analyzer是JIT插件——注册≠安装。 Salesforce CLI将
@salesforce/plugin-code-analyzer
声明为“即时（JIT）”插件：仅在首次运行
sf code-analyzer
命令时才会实际安装。在此之前，
sf plugins inspect
针对该插件会失败，但用户仍可完全使用它。因此检查会将JIT注册视为成功——若
inspect
未返回版本，则回退到CLI自身的
oclif.jitPlugins
注册表（从
sf plugins --json
的根条目读取），并报告为🟢，同时标注其会在首次使用时自动安装。只有既未安装也未注册JIT的插件才会被标记为🔴关键问题。

Phase 2: Install / Update

阶段2：安装/更新

If all green: Confirm setup is complete. The user is ready to develop.
If warnings or critical items exist: Present the user with options:
Some tools need attention. What would you like to do?

  [1] Fix all items
  [2] Choose which items to fix
  [3] Skip for now
For each tool the user wants to fix, provide the correct install/update command for their OS. Do not run install commands automatically — show the command and ask the user to confirm before running it.
若全绿： 确认设置已完成。用户已准备好进行开发。
若存在警告或关键问题： 向用户提供以下选项：
部分工具需要处理。您希望执行以下哪项操作？

  [1] 修复所有项
  [2] 选择要修复的项
  [3] 暂时跳过
对于用户想要修复的每个工具，提供适用于其操作系统的正确安装/更新命令。请勿自动运行安装命令——需展示命令并在运行前征得用户确认。

Install / Update Commands by Tool

按工具分类的安装/更新命令

Salesforce CLI — not installed:
bash
undefined
Salesforce CLI — 未安装：
bash
undefined

macOS/Linux (npm)

macOS/Linux（npm）

npm install --global @salesforce/cli
npm install --global @salesforce/cli

macOS (Homebrew)

macOS（Homebrew）

brew install sf

**Salesforce CLI — update:**
```bash
sf update
Code Analyzer plugin — not installed:
bash
sf plugins install @salesforce/plugin-code-analyzer
Code Analyzer plugin — update:
bash
sf plugins update @salesforce/plugin-code-analyzer
Node.js — not installed or below minimum:
bash
undefined
brew install sf

**Salesforce CLI — 更新：**
```bash
sf update
Code Analyzer插件 — 未安装：
bash
sf plugins install @salesforce/plugin-code-analyzer
Code Analyzer插件 — 更新：
bash
sf plugins update @salesforce/plugin-code-analyzer
Node.js — 未安装或版本低于最低要求：
bash
undefined

macOS (nvm — recommended, installs LTS)

macOS（nvm — 推荐，安装LTS版本）

nvm install --lts && nvm use --lts
nvm install --lts && nvm use --lts

macOS (Homebrew)

macOS（Homebrew）

brew install node
brew install node

Windows — download from https://nodejs.org (LTS version)

Windows — 从https://nodejs.org下载（LTS版本）


**NPM — update:**
```bash
npm install --global npm@latest
Git — not installed:
bash
undefined

**NPM — 更新：**
```bash
npm install --global npm@latest
Git — 未安装：
bash
undefined

macOS (Xcode CLT)

macOS（Xcode CLT）

xcode-select --install
xcode-select --install

macOS (Homebrew)

macOS（Homebrew）

brew install git
brew install git

Windows — download from https://git-scm.com

Windows — 从https://git-scm.com下载


**Source Tracking — not enabled:**
```bash
sf org enable tracking --target-org <alias>
Salesforce MCP — misconfigured: If 
.mcp.json
is missing or empty, reload the plugin:
/reload-plugins

**Source Tracking — 未启用：**
```bash
sf org enable tracking --target-org <alias>
Salesforce MCP — 配置错误： 若
.mcp.json
缺失或为空，重新加载插件：
/reload-plugins

Important Notes

重要说明

  • After installing a tool that modifies PATH (Node.js, SF CLI), the user may need to exit and restart Claude Code for the change to take effect.
  • Source Tracking requires a connected org — if no org is configured, prompt to run 
    /salesforce-development:login
    first.
  • For org authentication issues (expired session, wrong org, INVALID_SESSION_ID), run 
    /salesforce-development:login
    instead of this skill.
  • SF CLI outdated → 🟡 in the readiness scan: readiness means latest. When the CLI's cached update check reports a newer release, 
    check-tools
    reports the Salesforce CLI as 🟡 (installed but outdated) with the correct update command, rather than 🟢. Unlike the session-start notice below, this warning ignores the per-version no-nag gate — an explicit readiness scan always reports the factual state — but it still honors the hard opt-out 
    SFDX_SKIP_CLI_UPDATE_CHECK=1
    .
  • SF CLI update notice at session start: when the CLI reports an available update, the 
    sf-context detect
    SessionStart hook surfaces it once and asks the agent to offer the update (
    sf update
    , or 
    npm install --global @salesforce/cli@latest
    for npm-global installs). Declining or a failed update records a per-version no-nag gate (
    .sf/sf-cli-update-state.json
    ) so the same version won't nag again, but a newer release will re-prompt. Set 
    SFDX_SKIP_CLI_UPDATE_CHECK=1
    to disable the check entirely.
  • 安装修改PATH的工具（Node.js、SF CLI）后，用户可能需要退出并重启Claude Code才能使更改生效。
  • Source Tracking需要已连接的组织——若未配置组织，提示用户先运行
    /salesforce-development:login
    。
  • 对于组织身份验证问题（会话过期、错误组织、INVALID_SESSION_ID），请运行
    /salesforce-development:login
    而非此技能。
  • SF CLI过时→准备情况扫描中显示🟡： 准备就绪意味着最新版本。当CLI的缓存更新检查报告有新版本时，
    check-tools
    会将Salesforce CLI标记为🟡（已安装但过时）并提供正确的更新命令，而非🟢。与下文的会话启动通知不同，此警告忽略每个版本的免提示限制——显式的准备情况扫描始终报告实际状态——但仍会遵守硬禁用选项
    SFDX_SKIP_CLI_UPDATE_CHECK=1
    。
  • 会话启动时的SF CLI更新通知： 当CLI报告有可用更新时，
    sf-context detect
    会话启动钩子会显示一次该通知，并要求助手提供更新选项（
    sf update
    ，对于npm全局安装则使用
    npm install --global @salesforce/cli@latest
    ）。拒绝更新或更新失败会记录每个版本的免提示标记（
    .sf/sf-cli-update-state.json
    ），因此同一版本不会再次提示，但新版本会重新触发提示。设置
    SFDX_SKIP_CLI_UPDATE_CHECK=1
    可完全禁用此检查。