platform-environment-validate

验证：Salesforce 开发环境

验证所有必需的先决条件，并提供清晰、可执行的状态报告。此技能按需运行，不会在会话开始时自动运行。请显式运行它，以检查或修复本地设置。

阶段 1：先决条件扫描

运行工具检查：

${CLAUDE_PLUGIN_ROOT}/scripts/sf-context check-tools

输出是一个包含 tools 数组的 JSON 对象（任何关键故障时还会附带 diagnostic 区块）。

横幅会自动绘制——请勿重新生成。 运行 check-tools 时，插件会确定性地在可见通道上绘制带边框的 “Ready to build on Salesforce?” 横幅——每个工具占一行状态、底部给出结论，以及指引页脚——与 SessionStart 横幅完全一致。这是一个 Tier-1 界面：请阅读 JSON 以便理解，但不要重新输出、重画或重新渲染横幅。只需简短说明结果对用户意味着什么，然后进入阶段 2。

绘制出的横幅如下所示（仅作示例——每行中的版本／消息文本直接取自 JSON：🟢 对应 version，🟡／🔴 对应 message + 修复提示，ℹ️ 对应备注；以下内容展示的是样式，而非固定字符串）：

──────────────────────────────────────────────────────────────
 Ready to build on Salesforce?   checking your toolchain…
──────────────────────────────────────────────────────────────
 🟢 Salesforce CLI             v2.144.6
 🟢 Code Analyzer              v5.14.0 · JIT, auto-installs on first use
 🟢 Node.js                    v22.11.0 LTS
 🟢 NPM                        v10.9.0
 🟢 Git                        v2.50.1
 🟢 Salesforce MCP (config)    .mcp.json + proxy present
 🟢 Salesforce MCP (endpoint)  org instance reachable
 ℹ️  Salesforce MCP (process)   confirm with /mcp or /doctor
 🟢 Source Tracking            enabled
──────────────────────────────────────────────────────────────
 ✓ toolchain ready                                (skill: platform-environment-validate)

每行的状态圆点表示状态——🔴 critical（缺失或低于最低要求，无法继续进行 Salesforce 开发），🟡 warn（已安装，但版本过旧、非 LTS 或配置错误），🟢 ok，ℹ️ info（无法自动验证的上下文提示，例如 MCP 进程健康状态）。带边框的页脚会给出结论和最相关的一条 Next: 步骤。JSON 中的 status 字段是每个工具状态的权威来源；撰写简短说明时请依据这些状态。

如果横幅未能绘制（Claude Code 版本较旧，或绘制失败时的回退情况），不要根据 JSON 手动绘制。请改用确定性渲染器打印：

${CLAUDE_PLUGIN_ROOT}/scripts/sf-context readiness-banner

该命令会读取 check-tools 刚刚记录的同一扫描结果，并打印完全相同的带边框横幅——按固定顺序列出各行、给出底部结论，以及包含 Next: 步骤的“这里不需要记住命令”指引页脚——因此，顺序、间距、计数和后续步骤的选择都由脚本统一决定，无需手动推导。check-tools JSON 仍是权威、机器可读的结果。

结果是确定性的——不要覆盖失败状态： JSON 报告是权威、机器可读的结果。如果工具报告为 🔴／🟡，请如实报告。不要换用其他方式重新运行工具（PowerShell、原始 shell 探测或其他命令），再将结果说成 🟢——即使回退方式碰巧找到了该工具，也不代表确定性检查通过。只有同一个 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 端点。

已检查的工具

工具	最低要求	验证方式
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（配置）	已配置 .mcp.json，且存在代理包	检查插件根目录中的 .mcp.json，并确认 sf-mcp-proxy.bundled.js 存在
Salesforce MCP（端点）	可访问组织实例 URL（连接代理）	对组织实例 URL 执行 HTTP 探测
Salesforce MCP（进程）	ℹ️ 仅供参考 — 此处无法验证	使用 /mcp 或 /doctor 确认
源跟踪	已为连接的组织启用	sf project deploy preview

所有外部工具（sf、npm、node、git）都通过统一的跨平台解析器启动：使用 shutil.which（支持 PATHEXT）查找工具；在 Windows 上则通过 COMSPEC 包装的 argv 数组调用 .cmd/.bat 命令垫片（sf.cmd、npm.cmd），绝不使用 shell 字符串。因此，在 Windows、macOS 和 Linux 上，此扫描和 /salesforce-development:org 都能正确检测 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 注册的插件才是 🔴 严重问题。

阶段 2：安装 / 更新

如果全部为绿色： 确认设置已完成。用户可以开始开发。

如果存在警告或严重问题： 向用户提供以下选项：

Some tools need attention. What would you like to do?

  [1] Fix all items
  [2] Choose which items to fix
  [3] Skip for now

对于用户想要修复的每个工具，提供适用于其操作系统的正确安装/更新命令。不要自动运行安装命令 — 显示命令并在运行前征求用户确认。

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

Salesforce CLI — 未安装：

# macOS/Linux (npm)
npm install --global @salesforce/cli

# macOS (Homebrew)
brew install sf

Salesforce CLI — 更新：

sf update

Code Analyzer 插件 — 未安装：

sf plugins install @salesforce/plugin-code-analyzer

Code Analyzer 插件 — 更新：

sf plugins update @salesforce/plugin-code-analyzer

Node.js — 未安装或版本低于最低要求：

# macOS (nvm — recommended, installs LTS)
nvm install --lts && nvm use --lts

# macOS (Homebrew)
brew install node

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

NPM — 更新：

npm install --global npm@latest

Git — 未安装：

# macOS (Xcode CLT)
xcode-select --install

# macOS (Homebrew)
brew install git

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

源跟踪 — 未启用：

sf org enable tracking --target-org <alias>

Salesforce MCP — 配置错误： 如果 .mcp.json 缺失或为空，请重新加载插件：

/reload-plugins

重要说明

• 安装会修改 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 SessionStart hook 会显示一次通知，并要求 Agent 提供更新选项（sf update；对于通过 npm 全局安装的用户，则使用 npm install --global @salesforce/cli@latest）。如果用户拒绝更新或更新失败，系统会记录按版本设置的免打扰门槛（.sf/sf-cli-update-state.json），因此不会再提示同一版本，但发布新版本后会再次提示。设置 SFDX_SKIP_CLI_UPDATE_CHECK=1 可完全禁用此项检查。