platform-lsp-integrate

使用 Salesforce LSP

salesforce-development 插件托管了一个名为 salesforce-lsp 的本地 MCP 服务，它会按需启动 Salesforce 语言服务器子进程，并将其语义能力作为 MCP 工具提供。本技能是其他技能调用这些工具时遵循的约定，也是“如何使用 Salesforce LSP？”这个问题的答案——包括每个工具的功能、如何读取其结果、每个错误代码的含义，以及主机不可用时如何回退。

这是一个文档/参考技能，不会编写或部署代码；它会告诉你（以及其他技能）如何正确调用 LSP 工具。

此插件版本仅包含 Apex + SOQL。 salesforce-lsp 主机附带 Apex 语言服务器（@salesforce/apex-ls）和 SOQL 语言服务器。此插件有意不捆绑 LWC 语言服务器——主机虽会注册 lwc.* 工具，但这些工具在此处始终会返回 unavailable 类响应封装。将任何 lwc.* 调用视为不可用，并使用回退方式（读取组件源代码 / 部署并编译）。

何时使用此技能

• 用户询问如何使用 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、关闭开关）。

工具

所有工具都由 MCP 服务 salesforce-lsp 提供（调用名称遵循插件前缀模式： mcp__plugin_salesforce-development_salesforce-lsp__<tool_name>，其中工具名称中的点会替换为下划线——例如，apex.diagnostics 会变成 mcp__plugin_salesforce-development_salesforce-lsp__apex_diagnostics）。服务按需启动：首次调用需要语言服务器的工具时，会启动相应子进程（Apex 的冷启动只需几秒，且仅发生一次），之后会重复使用。纯静态分析工具不会启动任何进程。

Apex（会启动 Apex LSP）

工具	用途	关键输入	关键输出
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

工具	用途	是否会启动？	主要输出
validate_soql	解析 SOQL 字符串，检查语法错误	SOQL LSP	{ ok, diagnostics: [{ line, column, severity, message }] }
complete_soql	在光标处根据架构补全（针对组织解析 SObject、字段、选项列表值）	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	使缓存的组织 describe 失效，以便补全重新获取	否	{ ok, removed }

刚部署了字段/对象，但无法解析？ 如果 SOQL 或 Apex 引用了刚部署的字段后出错（例如 No such column 'Foo__c'，或 complete_soql 中没有提供该字段），且问题出现在部署后不久，则缓存的组织 describe 已过期——调用 refresh_org_schema 使其失效，然后重新运行检查，再判断是否为代码错误或需要重命名。这是应对部署后架构延迟的办法；在将问题视为查询/类中的 bug 之前，先尝试此操作。（此操作只会清除本地缓存，无法加快服务器端的同步；因此，如果组织本身尚未完成字段发布，稍后重新运行是备用方案。）

LWC — 此版本中不可用

宿主已注册 lwc.* 工具（lwc.diagnostics、lwc.hover、lwc.definition、lwc.completion、lwc.workspace_symbols），但此插件未附带 LWC 语言服务器。每次调用 lwc.* 都会返回不可用信封。处理 LWC 时，请改为直接读取组件源代码/模板，或通过部署编译并读取 CLI 错误。

诊断 / 健康状态

工具	用途	是否会启动？
lsp.health	只读查看 kill-switch 模式、工作区、各服务器状态、断路器状态、冷启动耗时、apex-ls 版本	否 — 永不启动

所有位置坐标均从 1 开始（line/column）。validate_soql 的诊断坐标相对于查询字符串，而非文件；如果查询来自 extract_soql_from_apex，请根据该查询的范围换算回文件位置。

调用 / 回退约定

每项调用 LSP 工具的技能都遵循相同的三条规则：

1. 优先使用 LSP 工具，而不是猜测。 如果有工具可用于某个步骤（验证查询、检查类的编译、根据组织架构进行补全），应先调用该工具，再回退到手动分析。
2. 将错误信封视为“不可用”，绝不能视为“通过”。 工具可能会返回 { error: <code> }，而非结果（参见错误代码）。遇到此类代码时，在报告中记录 <tool>=unavailable: <code>，并继续执行回退流程——绝不能仅仅因为未运行检查，就报告输入有效/无误。
3. 降低能力，不要失败。 LSP 是加速工具，而非硬性依赖。如果宿主完全不可用，salesforce-lsp 工具将不存在——此时应针对该步骤回退到 CLI/手动流程，并说明这一点。

LSP 主机不可用时

如果插件/主机不可用，则不会注册上述 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: <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 提示）无法解析组织架构	关键字补全仍然可用；请提供确切的字段/对象名称，或连接组织。不要将 __…_PLACEHOLDER 标签当作真实字段显示

前三种是所有需要启动服务的工具共用的临时/配置状态；其余情况则是特定工作区/组织/文件上下文中符合预期且正常的状态，并非安装损坏的迹象。（no_lwc_bundles / unsupported_lwc_file 是仅适用于 LWC 的代码；在此构建版本中未包含 LWC 服务器，因此 lwc.* 无论如何都会返回不可用。）

调试 LSP

分为三层，按成本从低到高排列：

1. lsp.health（MCP 工具）。 最快速的检查方式——不会启动子进程。报告停用开关模式、解析出的工作区、各服务器状态、断路器状态、上次冷启动耗时和内置 apex-ls 版本。请 Claude“运行 lsp.health”，或直接调用 lsp.health 工具。

2. bin/lsp-doctor（CLI）。 更深入的安装级诊断，用于支持和入门引导。验证已提交的资源包是否存在、内置 apex-ls 产物是否可解析、组织架构缓存是否可解析，以及每个 LSP 子进程是否能实际启动。健康时退出码为 0；出现问题时退出码为 1，并输出结构化的逐项检查结果。

   "${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)
   

   （在此构建版本中，lsp-doctor 会报告缺少 LWC 服务器——这是预期情况；此处仅包含 Apex + SOQL。）

3. SFDX_LSP_DEBUG=1。 将单行 JSON 遥测数据（启动耗时、缓存命中、断路器事件、各工具延迟）输出到 stderr。默认关闭（零开销）。

停用开关 — SFDX_LSP

控制或禁用 LSP 的快捷方式。设置环境变量：

SFDX_LSP	效果
未设置 / all	所有内置 LSP 均可启动（默认）
apex-only	只有 Apex LSP 可以启动；SOQL 工具返回 lsp_disabled
disabled	不启动任何 LSP；所有 LSP 工具都返回 lsp_disabled

要判断问题是否由 LSP 导致，请设置 SFDX_LSP=disabled 并重新运行：如果问题仍然存在，则与 LSP 无关，而且技能会自动回退到非 LSP 路径。未知值会默认设为 all（并发出警告），因此拼写错误不会悄悄禁用此功能。

部署前诊断门禁

PreToolUse 钩子（bin/lsp-precheck）会对即将由 sf project deploy start/validate 推送的 .cls/.trigger 文件运行 Apex 诊断，并给出决策。它采用故障时放行策略：任何错误（包括 LSP 缺失或响应缓慢） 都会允许部署。模式由 SFDX_LSP_DEPLOY_GATE 控制 （off | warn | block，默认值为 warn）——warn 会显示诊断信息但不阻止部署；block 会拒绝存在 Apex 编译错误的部署。

验证

• 询问“如何使用 Salesforce LSP 工具？”时，此技能会匹配并列出 工具及其输入、输出和回退约定。
• 在 /skills 列表中显示为 platform-lsp-integrate。
• 提供错误代码（例如 no_apex_workspace）时，它会解释其含义和 正确的恢复方法，不会将未运行的检查视为通过。

跨技能集成

需求	委派给
对刚编写的 Apex 进行编译检查和分析	platform-apex-generate
验证 .cls/.trigger 中的内联 SOQL	validate_soql（此技能）；回退方案：通过 sf data query --json 以只读方式运行
编写并运行针对该组织的 SOQL 查询	complete_soql + sf data query
部署前诊断门禁的行为	参见上文“部署前诊断门禁”