Back to Details

platform-lsp-integrate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using the Salesforce LSP

使用Salesforce LSP

The 
salesforce-development
plugin hosts a local MCP server named 
salesforce-lsp
 that lazily spawns Salesforce Language Server children and exposes their semantic capabilities as MCP tools. This skill is the contract other skills follow when they call those tools, and the answer to "how do I use the Salesforce LSP?" — what each tool does, how to read its result, what every error code means, and how to fall back when the host is absent.
This is a documentation/reference skill. It does not author or deploy code; it tells you (and other skills) how to drive the LSP tools correctly.
This plugin build vendors Apex + SOQL only. The 
salesforce-lsp
host ships the Apex language server (
@salesforce/apex-ls
) and the SOQL language server. The LWC language server is intentionally not bundled in this plugin — the 
lwc.*
tools are registered by the host but will always return an 
unavailable
-class envelope here. Treat any 
lwc.*
call as unavailable and use the fallback (read the component source / deploy-compile).
salesforce-development
插件托管了一个名为**
salesforce-lsp
的本地MCP服务器，它会延迟启动Salesforce语言服务器子进程，并将其语义能力以MCP工具的形式暴露出来。本技能是其他技能调用这些工具时需遵循的约定**，同时也是“如何使用Salesforce LSP？”的解答——包括每个工具的功能、如何读取结果、每个错误代码的含义，以及主机不可用时的回退方案。
这是一个文档/参考类技能，不负责编写或部署代码；它会告诉你（以及其他技能）如何正确调用LSP工具。
本插件版本仅支持Apex + SOQL。 
salesforce-lsp
主机包含Apex语言服务器（
@salesforce/apex-ls
）和SOQL语言服务器。LWC语言服务器未包含在本插件中——主机虽注册了
lwc.*
工具，但在此版本中始终返回
unavailable
类型的响应。请将任何
lwc.*
调用视为不可用，并使用回退方案（读取组件源码/部署编译）。

When to Use This Skill

何时使用本技能

  • A user asks how to use the Salesforce LSP, or which LSP/MCP tools are available.
  • A user asks what a specific tool does (
    apex.diagnostics
    , 
    validate_soql
    , 
    complete_soql
    , etc.) or how to read its output.
  • An LSP tool returned an error envelope (
    lsp_disabled
    , 
    spawn_timeout
    , 
    circuit_open
    , 
    no_apex_workspace
    , 
    no_org_connected
    ) and you need to know what it means and how to recover.
  • You're authoring or reviewing another skill that calls an LSP tool and need the canonical call/fallback pattern.
  • The LSP seems broken and you need to debug it (
    lsp.health
    , 
    ${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor
    , the kill switch).
  • 用户询问如何使用Salesforce LSP，或有哪些可用的LSP/MCP工具。
  • 用户询问特定工具的功能（如
    apex.diagnostics
    、
    validate_soql
    、
    complete_soql
    等）或如何读取其输出。
  • LSP工具返回错误响应（
    lsp_disabled
    、
    spawn_timeout
    、
    circuit_open
    、
    no_apex_workspace
    、
    no_org_connected
    ），你需要了解其含义及恢复方法。
  • 你正在编写或审核另一个调用LSP工具的技能，需要规范的调用/回退模式。
  • LSP出现故障，你需要调试它（使用
    lsp.health
    、
    ${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor
    、终止开关）。

The Tools

工具列表

All tools are served by the MCP server 
salesforce-lsp
 (invoke names follow the plugin-prefixed pattern: 
mcp__plugin_salesforce-development_salesforce-lsp__<tool_name>
, where dots in tool names become underscores — e.g. 
apex.diagnostics
becomes 
mcp__plugin_salesforce-development_salesforce-lsp__apex_diagnostics
). Spawning is lazy: a tool that needs a language server brings the child up on first call (a one-time cold start of a few seconds for Apex), then reuses it. The pure static-analysis tools never spawn anything.
所有工具均由MCP服务器**
salesforce-lsp
**提供服务（调用名称遵循插件前缀格式：
mcp__plugin_salesforce-development_salesforce-lsp__<tool_name>
，工具名称中的点会替换为下划线——例如
apex.diagnostics
变为
mcp__plugin_salesforce-development_salesforce-lsp__apex_diagnostics
）。启动是延迟式的：需要语言服务器的工具会在首次调用时启动子进程（Apex的首次冷启动需要几秒时间），之后会复用该进程。纯静态分析工具从不启动任何进程。

Apex (spawns the Apex LSP)

Apex（启动Apex LSP）

ToolPurposeKey inputKey output
apex.diagnostics
Compile-check a 
.cls
/
.trigger
; surface errors/warnings
{ filePath }
{ ok, diagnostics: [{ line, column, severity, message }] }
apex.hover
Type/signature at a position
{ filePath, line, character }
hover markdown
apex.documentSymbol
Outline of a file's symbols
{ filePath }
symbol tree
apex.completion
Code-completion at a position
{ filePath, line, character }
completion items
工具用途关键输入关键输出
apex.diagnostics
检查
.cls
/
.trigger
文件的编译情况；显示错误/警告
{ filePath }
{ ok, diagnostics: [{ line, column, severity, message }] }
apex.hover
获取指定位置的类型/签名信息
{ filePath, line, character }
悬停信息（markdown格式）
apex.documentSymbol
获取文件的符号大纲
{ filePath }
符号树
apex.completion
获取指定位置的代码补全建议
{ filePath, line, character }
补全项

SOQL

SOQL

ToolPurposeSpawns?Key output
validate_soql
Parse a SOQL string for syntax errorsSOQL LSP
{ ok, diagnostics: [{ line, column, severity, message }] }
complete_soql
Schema-aware completion at a cursor (SObjects, fields, picklist values resolved against the org)SOQL LSP
{ ok, items, expanded, unresolved, hint? }
extract_soql_from_apex
Statically pull every inline 
[SELECT …]
out of Apex		No (pure static)
{ ok, totalQueries, totalDynamic, files }
check_soql_selectivity
Selectivity heuristics (optional org LIMIT-0 probe)No by defaultselectivity report
refresh_org_schema
Invalidate the cached org describe so completion re-fetchesNo
{ ok, removed }
Just deployed a field/object and it won't resolve? When a SOQL or Apex reference to a freshly-deployed field fails (e.g. 
No such column 'Foo__c'
, or 
complete_soql
doesn't offer it) right after a deploy, the cached org describe is stale — call 
refresh_org_schema
 to invalidate it, then re-run the check before assuming a code error or renaming anything. This is the lever for post-deploy schema lag; reach for it before treating the failure as a bug in your query/class. (It only clears the local cache; it can't speed up server-side propagation, so if the org itself hasn't finished publishing the field, re-running after a moment is the fallback.)
工具用途是否启动进程？关键输出
validate_soql
解析SOQL字符串，检查语法错误SOQL LSP
{ ok, diagnostics: [{ line, column, severity, message }] }
complete_soql
基于光标位置的 schema 感知补全（根据组织解析SObjects、字段、选择列表值）SOQL LSP
{ ok, items, expanded, unresolved, hint? }
extract_soql_from_apex
从Apex中静态提取所有内联
[SELECT …]
语句		否（纯静态分析）
{ ok, totalQueries, totalDynamic, files }
check_soql_selectivity
选择性启发式分析（可选的组织LIMIT-0探测）默认否选择性报告
refresh_org_schema
使缓存的组织描述失效，以便补全操作重新获取最新信息否
{ ok, removed }
刚部署了字段/对象但无法解析？ 当部署后立即引用新部署的字段（例如
No such column 'Foo__c'
，或
complete_soql
未提供该字段的补全建议）失败时，说明缓存的组织描述已过期——调用**
refresh_org_schema
**使其失效，然后重新运行检查，不要直接认为是代码错误或重命名字段。这是解决部署后 schema 延迟的方法；在将失败视为查询/类中的bug之前，请先使用此方法。（它仅清除本地缓存；无法加快服务器端的传播速度，因此如果组织本身尚未完成字段发布，回退方案是等待片刻后重新运行。）

LWC — not available in this build

LWC——本版本不可用

The 
lwc.*
tools (
lwc.diagnostics
, 
lwc.hover
, 
lwc.definition
, 
lwc.completion
, 
lwc.workspace_symbols
) are registered by the host but the LWC language server is not vendored in this plugin. Every 
lwc.*
call returns an unavailable envelope. For LWC work, fall back to reading the component source/templates directly or deploy-compiling and reading the CLI errors.
lwc.*
工具（
lwc.diagnostics
、
lwc.hover
、
lwc.definition
、
lwc.completion
、
lwc.workspace_symbols
）虽由主机注册，但LWC语言服务器未包含在本插件中。所有
lwc.*
调用都会返回不可用响应。对于LWC相关工作，请回退到直接读取组件源码/模板，或通过部署编译并读取CLI错误。

Diagnostics / health

诊断/健康检查

ToolPurposeSpawns?
lsp.health
Read-only view of kill-switch mode, workspace, per-server state, circuit-breaker state, cold-spawn timing, apex-ls versionNo — never spawns
Coordinates everywhere are one-based (
line
/
column
). 
validate_soql
diagnostic coordinates are relative to the query string, not a file — when a query came from 
extract_soql_from_apex
, translate back using that query's range.
工具用途是否启动进程？
lsp.health
只读查看终止开关模式、工作区、每个服务器的状态、断路器状态、冷启动时间、apex-ls版本否——从不启动进程
所有坐标均为基于1的索引（
line
/
column
）。
validate_soql
的诊断坐标是相对于查询字符串的，而非文件——当查询来自
extract_soql_from_apex
时，请使用该查询的范围转换坐标。

The Call / Fallback Contract

调用/回退约定

Every skill that calls an LSP tool follows the same three rules:
  1. Prefer the LSP tool over guessing. If a tool exists for the step (validate a query, compile-check a class, complete against the org schema), call it before falling back to hand-analysis.
  2. Treat an error envelope as "unavailable," never as "passed." A tool may return 
    { error: <code> }
    instead of a result (see Error Codes). On any such code, record 
    <tool>=unavailable: <code>
    in your report and continue down the fallback path — never report the input as valid/clean just because the check didn't run.
  3. Degrade, don't fail. The LSP is an accelerator, not a hard dependency. If the host isn't available at all, the 
    salesforce-lsp
    tools simply won't exist — fall back to the CLI/manual path for that step and say so.
每个调用LSP工具的技能都遵循以下三条规则：
  1. 优先使用LSP工具而非猜测。 如果某步骤有对应的工具（验证查询、检查类编译情况、根据组织schema补全），请先调用工具，再回退到手动分析。
  2. 将错误响应视为“不可用”，而非“通过”。 工具可能返回
    { error: <code> }
    而非结果（参见错误代码）。对于任何此类代码，请在报告中记录
    <tool>=unavailable: <code>
    ，并继续执行回退路径——绝不要因为检查未运行就将输入视为有效/无问题。
  3. 降级处理，而非失败。 LSP是加速器，而非硬依赖。如果主机完全不可用，
    salesforce-lsp
    工具将不存在——请回退到该步骤的CLI/手动路径，并告知用户。

When the LSP host is absent

当LSP主机不可用时

If the plugin/host isn't available, the MCP tools above are not registered, so a call to (e.g.) 
validate_soql
will not resolve. Detect this the same way you detect an error envelope — the tool is unavailable — and use the documented fallback:
LSP tool unavailableFallback
apex.diagnostics
Deploy/compile via 
sf project deploy
and read CLI errors
validate_soql
Smoke-check by running the query read-only via 
sf data query --json
(a parse error surfaces in the CLI error)
complete_soql
sf sobject describe --sobject <O> --json
for fields; author from the user's stated names
extract_soql_from_apex
Read the file(s) and locate 
[SELECT … ]
by hand
apex.completion
/ 
apex.hover
Read the source directly
lwc.*
(always unavailable here)		Read the component source/templates directly, or deploy-compile and read CLI errors
如果插件/主机不可用，上述MCP工具未注册，因此调用（例如）
validate_soql
将无法解析。检测方式与检测错误响应相同——工具不可用——并使用文档中记录的回退方案：
LSP工具不可用回退方案
apex.diagnostics
通过
sf project deploy
部署/编译，并读取CLI错误
validate_soql
通过
sf data query --json
以只读方式运行查询进行快速检查（语法错误会在CLI错误中显示）
complete_soql
使用
sf sobject describe --sobject <O> --json
获取字段；根据用户指定的名称编写
extract_soql_from_apex
读取文件并手动定位
[SELECT … ]
apex.completion
/ 
apex.hover
直接读取源码
lwc.*
（本版本始终不可用）		直接读取组件源码/模板，或通过部署编译并读取CLI错误

Error Codes

错误代码

A tool returns 
{ error: <code> }
(or, for 
complete_soql
, a 
hint
) instead of a result. Each maps to a recovery:
CodeMeaningWhat to do
lsp_disabled
The kill switch (
SFDX_LSP
) forbids this language		Use the non-LSP fallback; or re-enable the LSP (see Debugging)
spawn_timeout
The language server didn't come up in timeRetry once; if it persists, fall back and run 
${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor
circuit_open
Repeated spawn failures tripped the breaker; calls are short-circuitedFall back now; investigate with 
lsp.health
/ 
${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor
no_apex_workspace
No 
classes/*.cls
under any package dir — Apex tools won't spawn		Expected in a non-Apex project; nothing to check
no_org_connected
(
complete_soql
hint) org schema couldn't be resolved		Keyword completion still works; ask for exact field/object names or connect an org. Do not surface 
__…_PLACEHOLDER
labels as real fields
The first three are transient/config states shared by every spawning tool; the rest are expected, healthy states for a particular workspace/org/file context — not signs of a broken install. (
no_lwc_bundles
/ 
unsupported_lwc_file
are LWC-only codes; in this build the LWC server is not vendored, so 
lwc.*
returns unavailable regardless.)
工具会返回
{ error: <code> }
（对于
complete_soql
，则返回
hint
）而非结果。每个代码对应一种恢复方法：
代码含义处理方法
lsp_disabled
终止开关（
SFDX_LSP
）禁止使用该语言		使用非LSP回退方案；或重新启用LSP（参见调试部分）
spawn_timeout
语言服务器未及时启动重试一次；如果问题持续，回退并运行
${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor
circuit_open
多次启动失败触发了断路器；调用被短路立即回退；使用
lsp.health
/ 
${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor
排查问题
no_apex_workspace
任何包目录下都没有
classes/*.cls
文件——Apex工具无法启动		非Apex项目中的预期情况；无需检查
no_org_connected
（
complete_soql
的提示）无法解析组织schema		关键字补全仍可工作；询问用户确切的字段/对象名称或连接组织。请勿将
__…_PLACEHOLDER
标签显示为真实字段
前三个是所有启动进程的工具共享的临时/配置状态；其余是特定工作区/组织/文件上下文的预期健康状态——并非安装损坏的迹象。（
no_lwc_bundles
/ 
unsupported_lwc_file
是LWC专属代码；在本版本中，LWC服务器未包含，因此
lwc.*
始终返回不可用。）

Debugging the LSP

调试LSP

Three layers, cheapest first:
  1. lsp.health
    (MCP tool).     The fastest check — never spawns a child. Reports the kill-switch mode, resolved workspace, per-server status, circuit-breaker state, last cold-spawn timing, and the vendored apex-ls version. Ask Claude to "run lsp.health," or call the 
    lsp.health
    tool directly.
  2. bin/lsp-doctor
    (CLI).     A deeper, install-level diagnostic for support and onboarding. Verifies the committed bundles exist, the vendored apex-ls artifacts resolve, the org-schema cache is parseable, and each LSP child can actually spawn. Exits 
    0
    when healthy, 
    1
    with structured per-check output when something is wrong.
    bash
    "${CLAUDE_PLUGIN_ROOT}"/bin/lsp-doctor            # human-readable report
"${CLAUDE_PLUGIN_ROOT}"/bin/lsp-doctor --json     # machine-readable
"${CLAUDE_PLUGIN_ROOT}"/bin/lsp-doctor --no-spawn # skip child-spawn probes (CI/restricted)
    (In this build 
    lsp-doctor
    will report the LWC server as missing — that is expected; only Apex + SOQL are vendored here.)
  3. SFDX_LSP_DEBUG=1
    .     Emits single-line JSON telemetry (spawn timing, cache hits, circuit events, per-tool latency) to stderr. Off by default (zero overhead).
分为三个层面，按成本从低到高排列：
  1. lsp.health
    （MCP工具）。     最快的检查方法——从不启动子进程。报告终止开关模式、已解析的工作区、每个服务器的状态、断路器状态、上次冷启动时间，以及包含的apex-ls版本。请Claude“运行lsp.health”，或直接调用
    lsp.health
    工具。
  2. bin/lsp-doctor
    （CLI）。     用于支持和入门的深度安装级诊断工具。验证已提交的包是否存在、包含的apex-ls工件是否可解析、组织schema缓存是否可解析，以及每个LSP子进程是否实际可启动。健康时退出码为
    0
    ；出现问题时退出码为
    1
    ，并输出结构化的检查结果。
    bash
    "${CLAUDE_PLUGIN_ROOT}"/bin/lsp-doctor            # 人类可读报告
"${CLAUDE_PLUGIN_ROOT}"/bin/lsp-doctor --json     # 机器可读格式
"${CLAUDE_PLUGIN_ROOT}"/bin/lsp-doctor --no-spawn # 跳过子进程启动探测（CI/受限环境）
    （在本版本中，
    lsp-doctor
    会报告LWC服务器缺失——这是预期情况；仅包含Apex + SOQL。）
  3. SFDX_LSP_DEBUG=1
    。     将单行JSON遥测数据（启动时间、缓存命中、断路器事件、每个工具的延迟）输出到stderr。默认关闭（零开销）。

The kill switch — 
SFDX_LSP

终止开关——
SFDX_LSP

The fast way to control or disable the LSP. Set the environment variable:
SFDX_LSP
Effect
unset / 
all
Every vendored LSP may spawn (default)
apex-only
Only the Apex LSP may spawn; SOQL tools return 
lsp_disabled
disabled
No LSP spawns; every LSP tool returns 
lsp_disabled
To rule the LSP in or out of a problem, set 
SFDX_LSP=disabled
and re-run: if the issue persists it isn't the LSP, and skills will have fallen back to their non-LSP paths automatically. An unknown value defaults to 
all
(with a warning) so a typo never silently disables the feature.
快速控制或禁用LSP的方法。设置环境变量：
SFDX_LSP
效果
未设置 / 
all
所有包含的LSP均可启动（默认）
apex-only
仅Apex LSP可启动；SOQL工具返回
lsp_disabled
disabled
不启动任何LSP；所有LSP工具返回
lsp_disabled
要确定问题是否与LSP相关，请设置
SFDX_LSP=disabled
并重新运行：如果问题仍然存在，则与LSP无关，技能会自动回退到非LSP路径。未知值默认视为
all
（并发出警告），因此输入错误不会静默禁用功能。

Pre-deploy diagnostics gate

部署前诊断网关

A 
PreToolUse
hook (
bin/lsp-precheck
) runs Apex diagnostics on the 
.cls
/
.trigger
files a 
sf project deploy start
/
validate
is about to push, and emits a decision. It is fail-open: any error (including a missing/slow LSP) allows the deploy. Mode is controlled by 
SFDX_LSP_DEPLOY_GATE
(
off
| 
warn
| 
block
, default 
warn
) — 
warn
surfaces diagnostics without blocking; 
block
denies a deploy that has Apex compile errors.
PreToolUse
钩子（
bin/lsp-precheck
）会在
sf project deploy start
/
validate
即将推送的
.cls
/
.trigger
文件上运行Apex诊断，并输出决策结果。它是故障开放的：任何错误（包括LSP缺失/缓慢）都允许部署。模式由
SFDX_LSP_DEPLOY_GATE
控制（
off
| 
warn
| 
block
，默认
warn
）——
warn
会显示诊断信息但不阻止部署；
block
会拒绝存在Apex编译错误的部署。

Verification

验证

  • Asked "how do I use the Salesforce LSP tools?", this skill is the match and lists the tools, their inputs/outputs, and the fallback contract.
  • Appears in the 
    /skills
    listing as 
    platform-lsp-integrate
    .
  • Given an error code (e.g. 
    no_apex_workspace
    ), it explains the meaning and the correct recovery without treating the unrun check as a pass.
  • 当被询问“如何使用Salesforce LSP工具？”时，本技能会匹配并列出工具、其输入/输出以及回退约定。
  • 在
    /skills
    列表中显示为
    platform-lsp-integrate
    。
  • 给定错误代码（例如
    no_apex_workspace
    ），它会解释含义和正确的恢复方法，不会将未运行的检查视为通过。

Cross-Skill Integration

跨技能集成

NeedDelegate to
Compile-check + analyze Apex you just wrote
platform-apex-generate
Validate inline SOQL in 
.cls
/
.trigger
validate_soql
(this skill); fallback: run read-only via 
sf data query --json
Author & run a SOQL query against the org
complete_soql
+ 
sf data query
Pre-deploy diagnostics gate behaviorsee "Pre-deploy diagnostics gate" above
需求委托给
编译检查 + 分析刚编写的Apex
platform-apex-generate
验证
.cls
/
.trigger
中的内联SOQL
validate_soql
（本技能）；回退方案：通过
sf data query --json
以只读方式运行
编写并针对组织运行SOQL查询
complete_soql
+ 
sf data query
部署前诊断网关行为参见上述“部署前诊断网关”部分