Back to Details

lsp-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LSP Auto-Configuration Skill

LSP自动配置Skill

Manual control and troubleshooting for Language Server Protocol (LSP) configuration.
Language Server Protocol (LSP)配置的手动控制与故障排查

Important: LSP is Configured Automatically

重要提示：LSP会自动配置

You probably don't need this skill! LSP is configured automatically when you run 
amplihack claude
.
When amplihack launches Claude Code, it automatically:
  • Detects programming languages in your project
  • Sets 
    ENABLE_LSP_TOOL=1
    environment variable
  • Installs required LSP plugins via Claude Code plugin marketplace
  • Configures project-specific settings in 
    .env
You'll see: 
📡 LSP: Detected 3 language(s): python, javascript...
when amplihack starts Claude Code.
你很可能不需要这个技能！ 当你运行
amplihack claude
时，LSP会自动完成配置。
当amplihack启动Claude Code时，它会自动执行以下操作：
  • 检测项目中的编程语言
  • 设置
    ENABLE_LSP_TOOL=1
    环境变量
  • 通过Claude Code插件市场安装所需的LSP插件
  • 在
    .env
    中配置项目特定的设置
你会看到： 当amplihack启动Claude Code时，会显示
📡 LSP: Detected 3 language(s): python, javascript...
。

When to Use This Skill

何时使用此技能

Use 
/lsp-setup
only when you need to:
  • Check Status: Verify LSP configuration is working (
    /lsp-setup --status-only
    )
  • Troubleshoot Issues: Diagnose why code intelligence isn't working
  • Force Reconfiguration: Rebuild LSP config after manual changes (
    /lsp-setup --force
    )
  • Add New Languages: Configure LSP for newly added languages
Don't use this skill if: LSP is already working! The automatic setup handles 99% of cases.
仅在以下场景使用
/lsp-setup
：
  • 检查状态：验证LSP配置是否正常工作（
    /lsp-setup --status-only
    ）
  • 排查问题：诊断代码智能功能失效的原因
  • 强制重新配置：手动修改后重建LSP配置（
    /lsp-setup --force
    ）
  • 添加新语言：为新增的语言配置LSP
如果LSP已经正常工作，请不要使用此技能！ 自动设置可以处理99%的场景。

Overview

概述

The LSP Setup skill provides manual control over the same LSP auto-configuration that happens automatically at launch. It supports 16 popular programming languages out of the box and gives you direct access to configuration, status checking, and troubleshooting.
LSP配置Skill提供对启动时自动执行的LSP配置流程的手动控制权。它默认支持16种流行编程语言，让你可以直接进行配置、状态检查和故障排查。

What LSP Provides to You

LSP为你带来的能力

When LSP is properly configured, Claude Code gains powerful code intelligence capabilities that enhance the AI's understanding of your codebase:
当LSP配置完成后，Claude Code将获得强大的代码智能能力，提升AI对代码库的理解：

Real-Time Code Intelligence

实时代码智能

Type Information - Claude can see the exact types of variables, functions, and classes:
python
undefined
类型信息 - Claude可以查看变量、函数和类的确切类型：
python
undefined

Claude can hover over 'user' and see: Type: User (class from models.py)

Claude悬停在'user'上时可以看到：类型: User（来自models.py的类）

user = get_current_user()

**Go to Definition** - Claude can jump to where symbols are defined:

```python
user = get_current_user()

**跳转到定义** - Claude可以跳转到符号的定义位置：

```python

Claude can navigate from 'authenticate()' call to its definition in auth.py

Claude可以从'authenticate()'调用导航到其在auth.py中的定义

result = authenticate(credentials)

**Code Diagnostics** - Claude receives real-time error detection from LSP servers:

```python
result = authenticate(credentials)

**代码诊断** - Claude会接收来自LSP服务器的实时错误检测：

```python

Pyright reports: "Set" is not accessed

Pyright报告："Set"未被访问

from typing import List, Set # Claude sees this warning
undefined
from typing import List, Set # Claude会看到此警告
undefined

How Claude Uses LSP

Claude如何使用LSP

Better Code Understanding - Instead of guessing types and behavior, Claude gets precise information from LSP servers about:
  • Function signatures and return types
  • Class hierarchies and inheritance
  • Import paths and module structure
  • Errors and warnings before runtime
Smarter Suggestions - With LSP data, Claude provides:
  • Accurate refactoring recommendations
  • Type-safe code completions
  • Precise error fixes
  • Context-aware code generation
Example Workflow:
You: "Fix the type error in user_service.py"

Without LSP: Claude reads the file, guesses at types, may miss subtle issues

With LSP: Claude receives diagnostic:
  Line 42: Expected type 'User | None', got 'str'
  → Claude provides exact fix based on actual type information
更精准的代码理解 - Claude不再需要猜测类型和行为，而是从LSP服务器获取以下精准信息：
  • 函数签名和返回类型
  • 类层次结构与继承关系
  • 导入路径和模块结构
  • 运行前的错误和警告
更智能的建议 - 借助LSP数据，Claude可以提供：
  • 准确的重构建议
  • 类型安全的代码补全
  • 精准的错误修复
  • 上下文感知的代码生成
示例工作流:
你: "修复user_service.py中的类型错误"

无LSP时：Claude读取文件，猜测类型，可能遗漏细微问题

有LSP时：Claude接收诊断信息:
  第42行：预期类型'User | None'，实际得到'str'
  → Claude基于实际类型信息提供精确修复方案

What You'll Notice

你会注意到的变化

After 
/lsp-setup
configures your project:
  1. More Accurate Responses - Claude's code suggestions match your actual types and APIs
  2. Faster Debugging - Claude sees the same errors your IDE would show
  3. Better Refactoring - Claude can safely rename variables across files using LSP references
  4. Improved Navigation - Claude can find definitions, usages, and implementations precisely
/lsp-setup
配置项目后：
  1. 更准确的响应 - Claude的代码建议与你的实际类型和API匹配
  2. 更快的调试 - Claude可以看到与IDE相同的错误
  3. 更好的重构 - Claude可以使用LSP引用安全地跨文件重命名变量
  4. 更精准的导航 - Claude可以精确查找定义、用法和实现

Important Note

重要说明

LSP enhances Claude's capabilities behind the scenes. You don't interact with LSP directly - it makes Claude smarter about your code automatically.
LSP在后台增强Claude的能力。你无需直接与LSP交互——它会自动让Claude更懂你的代码。

When to Use This Skill

何时使用此技能

Use 
/lsp-setup
when you:
  • Start working on a new project in Claude Code
  • Add a new programming language to an existing project
  • Experience missing or incorrect code intelligence features
  • Want to verify your LSP configuration is correct
  • Need to troubleshoot LSP server connection issues
在以下场景使用
/lsp-setup
：
  • 首次在Claude Code中处理新项目
  • 向现有项目添加新编程语言
  • 遇到代码智能功能缺失或错误的情况
  • 想要验证LSP配置是否正确
  • 需要排查LSP服务器连接问题

How It Works

工作原理

LSP Architecture - Three Layers

LSP架构 - 三层结构

Claude Code's LSP system uses a three-layer architecture that must all be configured for LSP features to work:
Layer 1: System LSP Binaries (User-installed)
  • LSP server executables installed on your system via npm, brew, rustup, etc.
  • Example: 
    npm install -g pyright
    installs the Pyright LSP server binary
  • These are the actual language analysis engines
Layer 2: Claude Code LSP Plugins (Installed via cclsp)
  • Claude Code plugins that connect to Layer 1 binaries
  • Installed using: 
    npx cclsp install <server-name>
  • The 
    cclsp
    tool uses the 
    claude-code-lsps
    plugin marketplace
  • These act as bridges between Claude Code and LSP servers
Layer 3: Project Configuration (.env file)
  • Project-specific settings: virtual environments, project roots, etc.
  • Must include 
    ENABLE_LSP_TOOL=1
    to activate LSP features
  • Stored in 
    .env
    at project root
Important: 
cclsp
and 
claude-code-lsps
work together. 
cclsp
is the installation tool, 
claude-code-lsps
is the plugin marketplace it uses. They are complementary, not alternatives.
Claude Code的LSP系统采用三层架构，必须全部配置完成才能使用LSP功能：
第一层：系统LSP二进制文件（用户安装）
  • 通过npm、brew、rustup等安装在系统上的LSP服务器可执行文件
  • 示例：
    npm install -g pyright
    安装Pyright LSP服务器二进制文件
  • 这些是实际的语言分析引擎
第二层：Claude Code LSP插件（通过cclsp安装）
  • 连接第一层二进制文件的Claude Code插件
  • 使用
    npx cclsp install <server-name>
    安装
  • cclsp
    工具使用
    claude-code-lsps
    插件市场
  • 这些插件充当Claude Code与LSP服务器之间的桥梁
第三层：项目配置（.env文件）
  • 项目特定设置：虚拟环境、项目根目录等
  • 必须包含
    ENABLE_LSP_TOOL=1
    才能激活LSP功能
  • 存储在项目根目录的
    .env
    文件中
重要提示：
cclsp
和
claude-code-lsps
协同工作。
cclsp
是安装工具，
claude-code-lsps
是它使用的插件市场。它们是互补关系，而非替代关系。

The Skill's 4-Phase Process

技能的四阶段流程

The 
/lsp-setup
skill automates the workflow from 
npx cclsp@latest setup
:
/lsp-setup
技能自动执行
npx cclsp@latest setup
的工作流：

Phase 1: Language Detection

阶段1：语言检测

Scans your project directory to identify programming languages based on file extensions and framework markers. Detects 16 languages including Python, TypeScript, JavaScript, Rust, Go, Java, and more.
扫描项目目录，根据文件扩展名和框架标记识别编程语言。支持检测16种语言，包括Python、TypeScript、JavaScript、Rust、Go、Java等。

Phase 2: LSP Configuration

阶段2：LSP配置

Generates the appropriate LSP server configuration for each detected language. Checks if:
  1. System LSP binaries are installed (Layer 1)
  2. Claude Code plugins are installed (Layer 2)
Provides installation guidance if either is missing. NEVER auto-installs - user has full control.
为每种检测到的语言生成相应的LSP服务器配置。检查：
  1. 系统LSP二进制文件是否已安装（第一层）
  2. Claude Code插件是否已安装（第二层）
如果其中任何一项缺失，提供安装指导。绝不会自动安装——用户拥有完全控制权。

Phase 3: Project Configuration

阶段3：项目配置

Creates or updates 
.env
file with project-specific LSP settings (Layer 3):
  • Workspace-specific options (Python virtual environments, Node.js project roots, etc.)
  • ENABLE_LSP_TOOL=1 (required for LSP features to activate)
创建或更新
.env
文件，添加项目特定的LSP设置（第三层）：
  • 工作区特定选项（Python虚拟环境、Node.js项目根目录等）
  • ENABLE_LSP_TOOL=1（激活LSP功能必需）

Phase 4: Verification

阶段4：验证

Tests each LSP server connection and reports status. Provides actionable guidance for any configuration issues.
测试每个LSP服务器的连接并报告状态。为任何配置问题提供可操作的指导。

Usage

使用方法

Basic Usage

基础用法

bash
/lsp-setup
Detects all languages in your project and configures LSP servers automatically.
bash
/lsp-setup
检测项目中的所有语言并自动配置LSP服务器。

Check Status Only

仅检查状态

bash
/lsp-setup --status-only
Reports current LSP configuration and server availability without making changes.
bash
/lsp-setup --status-only
报告当前LSP配置和服务器可用性，不进行任何更改。

Force Reconfiguration

强制重新配置

bash
/lsp-setup --force
Regenerates LSP configuration even if valid configuration already exists.
bash
/lsp-setup --force
即使已存在有效的配置，也重新生成LSP配置。

Specific Languages

指定语言

bash
/lsp-setup --languages python,typescript
Configures LSP servers only for specified languages.
bash
/lsp-setup --languages python,typescript
仅为指定的语言配置LSP服务器。

Manual Plugin Management

手动插件管理

If you need to manage Claude Code LSP plugins directly, use the 
cclsp
command:
bash
undefined
如果需要直接管理Claude Code LSP插件，请使用
cclsp
命令：
bash
undefined

Install a plugin (Layer 2)

安装插件（第二层）

npx cclsp install pyright
npx cclsp install pyright

List installed plugins

列出已安装的插件

npx cclsp list
npx cclsp list

Remove a plugin

移除插件

npx cclsp remove pyright
npx cclsp remove pyright

Full setup workflow (what /lsp-setup automates)

完整设置工作流（/lsp-setup自动执行的操作）

npx cclsp@latest setup

The `/lsp-setup` skill automates the `npx cclsp@latest setup` workflow, adding intelligent language detection and project-specific configuration.
npx cclsp@latest setup

`/lsp-setup`技能自动执行`npx cclsp@latest setup`工作流，并添加智能语言检测和项目特定配置。

Supported Languages

支持的语言

LanguageLSP ServerSystem Binary Installation (Layer 1)Claude Code Plugin (Layer 2)
Pythonpyright
npm install -g pyright
npx cclsp install pyright
TypeScriptvtsls
npm install -g @vtsls/language-server
npx cclsp install vtsls
JavaScriptvtsls
npm install -g @vtsls/language-server
npx cclsp install vtsls
Rustrust-analyzer
rustup component add rust-analyzer
npx cclsp install rust-analyzer
Gogopls
go install golang.org/x/tools/gopls@latest
npx cclsp install gopls
JavajdtlsDownload from eclipse.org/jdtls
npx cclsp install jdtls
C/C++clangd
brew install llvm
(macOS) / 
apt install clangd
(Linux)
npx cclsp install clangd
C#omnisharpDownload from omnisharp.net
npx cclsp install omnisharp
Rubyruby-lsp
gem install ruby-lsp
npx cclsp install ruby-lsp
PHPphpactor
composer global require phpactor/phpactor
npx cclsp install phpactor
Bashbash-language-server
npm install -g bash-language-server
npx cclsp install bash-language-server
YAMLyaml-language-server
npm install -g yaml-language-server
npx cclsp install yaml-language-server
JSONvscode-json-languageserver
npm install -g vscode-json-languageserver
npx cclsp install vscode-json-languageserver
HTMLvscode-html-languageserver
npm install -g vscode-html-languageserver
npx cclsp install vscode-html-languageserver
CSSvscode-css-languageserver
npm install -g vscode-css-languageserver
npx cclsp install vscode-css-languageserver
Markdownmarksman
brew install marksman
(macOS) / Download from GitHub
npx cclsp install marksman
Note: Both Layer 1 (system binary) and Layer 2 (Claude Code plugin) must be installed for LSP features to work.
语言LSP服务器系统二进制文件安装（第一层）Claude Code插件（第二层）
Pythonpyright
npm install -g pyright
npx cclsp install pyright
TypeScriptvtsls
npm install -g @vtsls/language-server
npx cclsp install vtsls
JavaScriptvtsls
npm install -g @vtsls/language-server
npx cclsp install vtsls
Rustrust-analyzer
rustup component add rust-analyzer
npx cclsp install rust-analyzer
Gogopls
go install golang.org/x/tools/gopls@latest
npx cclsp install gopls
Javajdtls从eclipse.org/jdtls下载
npx cclsp install jdtls
C/C++clangd
brew install llvm
（macOS）/ 
apt install clangd
（Linux）
npx cclsp install clangd
C#omnisharp从omnisharp.net下载
npx cclsp install omnisharp
Rubyruby-lsp
gem install ruby-lsp
npx cclsp install ruby-lsp
PHPphpactor
composer global require phpactor/phpactor
npx cclsp install phpactor
Bashbash-language-server
npm install -g bash-language-server
npx cclsp install bash-language-server
YAMLyaml-language-server
npm install -g yaml-language-server
npx cclsp install yaml-language-server
JSONvscode-json-languageserver
npm install -g vscode-json-languageserver
npx cclsp install vscode-json-languageserver
HTMLvscode-html-languageserver
npm install -g vscode-html-languageserver
npx cclsp install vscode-html-languageserver
CSSvscode-css-languageserver
npm install -g vscode-css-languageserver
npx cclsp install vscode-css-languageserver
Markdownmarksman
brew install marksman
（macOS）/ 从GitHub下载
npx cclsp install marksman
注意：必须同时安装第一层（系统二进制文件）和第二层（Claude Code插件）才能使用LSP功能。

Example: Python Project Setup

示例：Python项目配置

bash
$ cd my-python-project
$ /lsp-setup

[LSP Setup] Detecting languages...
✓ Found: Python (23 files)
✓ Found: YAML (2 files)
✓ Found: Markdown (1 file)

[LSP Setup] Configuring LSP servers...
✓ pyright: Installed at /usr/local/bin/pyright
✓ yaml-language-server: Installed at /usr/local/bin/yaml-language-server
✓ marksman: Installed at /usr/local/bin/marksman

[LSP Setup] Configuring project...
✓ Created .env with LSP configuration
✓ Detected Python virtual environment: .venv
✓ Configured pyright to use .venv/bin/python

[LSP Setup] Verifying connections...
✓ pyright: Connected (Python 3.11.5)
✓ yaml-language-server: Connected
✓ marksman: Connected

Configuration complete! LSP servers ready.
bash
$ cd my-python-project
$ /lsp-setup

[LSP配置] 检测语言...
✓ 发现：Python（23个文件）
✓ 发现：YAML（2个文件）
✓ 发现：Markdown（1个文件）

[LSP配置] 配置LSP服务器...
✓ pyright：已安装在/usr/local/bin/pyright
✓ yaml-language-server：已安装在/usr/local/bin/yaml-language-server
✓ marksman：已安装在/usr/local/bin/marksman

[LSP配置] 配置项目...
✓ 创建包含LSP配置的.env文件
✓ 检测到Python虚拟环境：.venv
✓ 配置pyright使用.venv/bin/python

[LSP配置] 验证连接...
✓ pyright：已连接（Python 3.11.5）
✓ yaml-language-server：已连接
✓ marksman：已连接

配置完成！LSP服务器已就绪。

Example: Polyglot Project Setup

示例：多语言项目配置

bash
$ cd my-fullstack-app
$ /lsp-setup

[LSP Setup] Detecting languages...
✓ Found: TypeScript (45 files)
✓ Found: Python (12 files)
✓ Found: Rust (8 files)
✓ Found: JSON (6 files)

[LSP Setup] Configuring LSP servers...
✓ vtsls: Installed
✓ pyright: Installed
✗ rust-analyzer: Not found

[LSP Setup] Installation guidance:
To install rust-analyzer:
  $ rustup component add rust-analyzer

Would you like to continue with available servers? [Y/n] y

[LSP Setup] Configuring project...
✓ Created .env with LSP configuration
✓ Detected Node.js project root: ./frontend
✓ Detected Python project root: ./backend
✓ Detected Rust workspace: ./services

[LSP Setup] Verifying connections...
✓ vtsls: Connected (TypeScript 5.3.3)
✓ pyright: Connected (Python 3.11.5)
⚠ rust-analyzer: Skipped (not installed)

Configuration complete! 2/3 LSP servers ready.
Run `rustup component add rust-analyzer` to enable Rust support.
bash
$ cd my-fullstack-app
$ /lsp-setup

[LSP配置] 检测语言...
✓ 发现：TypeScript（45个文件）
✓ 发现：Python（12个文件）
✓ 发现：Rust（8个文件）
✓ 发现：JSON（6个文件）

[LSP配置] 配置LSP服务器...
✓ vtsls：已安装
✓ pyright：已安装
✗ rust-analyzer：未找到

[LSP配置] 安装指导：
安装rust-analyzer：
  $ rustup component add rust-analyzer

是否继续使用可用的服务器？[Y/n] y

[LSP配置] 配置项目...
✓ 创建包含LSP配置的.env文件
✓ 检测到Node.js项目根目录：./frontend
✓ 检测到Python项目根目录：./backend
✓ 检测到Rust工作区：./services

[LSP配置] 验证连接...
✓ vtsls：已连接（TypeScript 5.3.3）
✓ pyright：已连接（Python 3.11.5）
⚠ rust-analyzer：已跳过（未安装）

配置完成！3个LSP服务器中2个已就绪。
运行`rustup component add rust-analyzer`以启用Rust支持。

How to Verify LSP is Working

如何验证LSP是否正常工作

After running 
/lsp-setup
, here's how to confirm LSP is providing code intelligence to Claude:
运行
/lsp-setup
后，可通过以下方式确认LSP是否为Claude提供代码智能：

Method 1: Check for Diagnostics

方法1：检查诊断信息

Ask Claude to analyze a file with intentional errors:
You: "What issues do you see in src/main.py?"

If LSP is working: Claude will report specific diagnostics from Pyright
  → "Line 15: 'name' is not accessed"
  → "Line 23: Expected type 'int', got 'str'"

If LSP is NOT working: Claude only sees what's in the file content
  → Generic observations about code style
  → No specific type errors or warnings
让Claude分析一个包含故意错误的文件:
你: "src/main.py中有什么问题？"

LSP正常工作时：Claude会报告来自Pyright的具体诊断信息
  → "第15行：'name'未被访问"
  → "第23行：预期类型'int'，实际得到'str'"

LSP未工作时：Claude只能看到文件内容
  → 关于代码风格的一般性观察
  → 没有具体的类型错误或警告

Method 2: Request Type Information

方法2：请求类型信息

Ask Claude about types in your code:
You: "What's the type of the 'user' variable in auth.py line 42?"

If LSP is working: Claude provides exact type from LSP
  → "Type: User | None (from models.User)"

If LSP is NOT working: Claude guesses based on context
  → "It appears to be a User object based on the code"
询问Claude代码中的类型:
你: "auth.py第42行中'user'变量的类型是什么？"

LSP正常工作时：Claude从LSP提供确切类型
  → "类型：User | None（来自models.User）"

LSP未工作时：Claude基于上下文猜测
  → "根据代码，它似乎是一个User对象"

Method 3: Test Navigation

方法3：测试导航功能

Ask Claude to find definitions:
You: "Where is the authenticate() function defined?"

If LSP is working: Claude uses LSP goToDefinition
  → "Defined in src/auth/service.py:156"

If LSP is NOT working: Claude searches file contents
  → "I found it by searching for 'def authenticate'"
让Claude查找定义:
你: "authenticate()函数定义在哪里？"

LSP正常工作时：Claude使用LSP的跳转到定义功能
  → "定义在src/auth/service.py:156"

LSP未工作时：Claude搜索文件内容
  → "我通过搜索'def authenticate'找到了它"

Method 4: Check Status Command

方法4：运行状态检查命令

Run the status check:
bash
/lsp-setup --status-only
Expected Output (LSP Working):
[LSP Setup] Configuration Status:

✓ Python (pyright): Connected
  - System Binary: /usr/local/bin/pyright-langserver
  - Plugin: Installed and active
  - Project Config: .env configured with ENABLE_LSP_TOOL=1

✓ TypeScript (vtsls): Connected
  - System Binary: /usr/local/bin/vtsls
  - Plugin: Installed and active
  - Project Config: .env configured with ENABLE_LSP_TOOL=1

Overall Status: ✓ All LSP servers ready (2/2)
Problem Output (LSP NOT Working):
[LSP Setup] Configuration Status:

✗ Python (pyright): Not Connected
  - System Binary: Not found
  - Plugin: Not installed
  - Project Config: Missing ENABLE_LSP_TOOL=1

Issue: Run 'npm install -g pyright' and 'npx cclsp install pyright'
运行状态检查:
bash
/lsp-setup --status-only
预期输出（LSP正常工作）:
[LSP配置] 配置状态:

✓ Python（pyright）：已连接
  - 系统二进制文件：/usr/local/bin/pyright-langserver
  - 插件：已安装并激活
  - 项目配置：.env已配置ENABLE_LSP_TOOL=1

✓ TypeScript（vtsls）：已连接
  - 系统二进制文件：/usr/local/bin/vtsls
  - 插件：已安装并激活
  - 项目配置：.env已配置ENABLE_LSP_TOOL=1

整体状态：✓ 所有LSP服务器已就绪（2/2）
问题输出（LSP未工作）:
[LSP配置] 配置状态:

✗ Python（pyright）：未连接
  - 系统二进制文件：未找到
  - 插件：未安装
  - 项目配置：缺少ENABLE_LSP_TOOL=1

问题：运行'npm install -g pyright'和'npx cclsp install pyright'

What Success Looks Like

正常工作的表现

When LSP is working properly, you'll notice:
  1. Claude mentions specific line numbers when discussing errors
  2. Claude provides exact types instead of guessing
  3. Claude sees warnings/errors before code runs (like your IDE does)
  4. Claude can navigate code structure using LSP's understanding
LSP正常工作时，你会注意到：
  1. Claude讨论错误时会提到具体行号
  2. Claude提供确切类型而非猜测
  3. Claude在运行代码前就能看到警告/错误（和IDE一样）
  4. Claude可以使用LSP的理解导航代码结构

What Failure Looks Like

未工作的表现

When LSP is NOT working, you'll notice:
  1. Claude only sees file contents - no type information or diagnostics
  2. Claude makes educated guesses about types and behavior
  3. Claude doesn't mention errors until you run the code
  4. Claude searches text instead of using semantic understanding
LSP未工作时，你会注意到：
  1. Claude只能看到文件内容 - 没有类型信息或诊断
  2. Claude对类型和行为进行合理猜测
  3. Claude在你运行代码前不会提到错误
  4. Claude搜索文本而非使用语义理解

Troubleshooting

故障排查

Issue: LSP server not found

问题：LSP服务器未找到

Symptom: "rust-analyzer: Not found" during configuration
Solution: Install the LSP server using the provided installation command
bash
$ rustup component add rust-analyzer
$ /lsp-setup --force  # Reconfigure after installation
症状：配置过程中显示"rust-analyzer: Not found"
解决方案：使用提供的安装命令安装LSP服务器
bash
$ rustup component add rust-analyzer
$ /lsp-setup --force  # 安装后重新配置

Issue: LSP server crashes on startup

问题：LSP服务器启动时崩溃

Symptom: "pyright: Connection failed" during verification
Solution: Check LSP server logs and verify installation
bash
undefined
症状：验证过程中显示"pyright: Connection failed"
解决方案：检查LSP服务器日志并验证安装
bash
undefined

Check if server is properly installed

检查服务器是否正确安装

$ which pyright /usr/local/bin/pyright
$ which pyright /usr/local/bin/pyright

Test server manually

手动测试服务器

$ pyright --version pyright 1.1.332
$ pyright --version pyright 1.1.332

Check Claude Code LSP logs

查看Claude Code LSP日志

$ cat ~/.claude-code/lsp-logs/pyright.log
undefined
$ cat ~/.claude-code/lsp-logs/pyright.log
undefined

Issue: Wrong Python interpreter used

问题：使用了错误的Python解释器

Symptom: Import errors despite packages being installed in virtual environment
Solution: Verify 
.env
configuration points to correct Python interpreter
bash
undefined
症状：虚拟环境中已安装包，但仍出现导入错误
解决方案：验证
.env
配置指向正确的Python解释器
bash
undefined

Check current configuration

检查当前配置

$ cat .env | grep PYTHON
$ cat .env | grep PYTHON

Should show:

应该显示:

LSP_PYTHON_INTERPRETER=/path/to/.venv/bin/python
LSP_PYTHON_INTERPRETER=/path/to/.venv/bin/python

If incorrect, update manually or run:

如果不正确，手动更新或运行:

$ /lsp-setup --force
undefined
$ /lsp-setup --force
undefined

Issue: TypeScript project not detected

问题：未检测到TypeScript项目

Symptom: No TypeScript LSP configuration despite 
.ts
files present
Solution: Ensure 
tsconfig.json
exists in project root
bash
undefined
症状：存在
.ts
文件但未配置TypeScript LSP
解决方案：确保项目根目录存在
tsconfig.json
bash
undefined

Create minimal tsconfig.json

创建最小化的tsconfig.json

$ cat > tsconfig.json << EOF { "compilerOptions": { "target": "ES2020", "module": "commonjs", "strict": true } } EOF
$ /lsp-setup --force
undefined
$ cat > tsconfig.json << EOF { "compilerOptions": { "target": "ES2020", "module": "commonjs", "strict": true } } EOF
$ /lsp-setup --force
undefined

Issue: Multiple Python versions causing conflicts

问题：多个Python版本导致冲突

Symptom: "Module not found" errors when LSP server uses wrong Python version
Solution: Explicitly set Python interpreter in 
.env
bash
undefined
症状：LSP服务器使用错误的Python版本时出现"模块未找到"错误
解决方案：在
.env
中显式设置Python解释器
bash
undefined

Edit .env manually

手动编辑.env

LSP_PYTHON_INTERPRETER=/usr/bin/python3.11
LSP_PYTHON_INTERPRETER=/usr/bin/python3.11

Or activate the correct virtual environment before running

或在运行前激活正确的虚拟环境

$ source .venv/bin/activate $ /lsp-setup --force
undefined
$ source .venv/bin/activate $ /lsp-setup --force
undefined

Configuration Files

配置文件

.env
(Project Root)

.env
（项目根目录）

The skill creates or updates 
.env
with LSP-specific configuration:
bash
undefined
技能会创建或更新
.env
文件，添加LSP特定配置：
bash
undefined

LSP Configuration - Auto-generated by /lsp-setup

LSP配置 - 由/lsp-setup自动生成

ENABLE_LSP_TOOL=1 # REQUIRED: Activates LSP features in Claude Code
ENABLE_LSP_TOOL=1 # 必需：激活Claude Code中的LSP功能

Project-specific settings (Layer 3)

项目特定设置（第三层）

LSP_PYTHON_INTERPRETER=/path/to/.venv/bin/python LSP_NODE_PROJECT_ROOT=/path/to/frontend LSP_RUST_WORKSPACE=/path/to/services LSP_GO_MODULE=/path/to/go.mod
LSP_PYTHON_INTERPRETER=/path/to/.venv/bin/python LSP_NODE_PROJECT_ROOT=/path/to/frontend LSP_RUST_WORKSPACE=/path/to/services LSP_GO_MODULE=/path/to/go.mod

Language Server Paths (auto-detected)

语言服务器路径（自动检测）

LSP_PYRIGHT_PATH=/usr/local/bin/pyright LSP_VTSLS_PATH=/usr/local/bin/vtsls LSP_RUST_ANALYZER_PATH=/usr/local/bin/rust-analyzer

**Critical**: `ENABLE_LSP_TOOL=1` must be present for LSP features to work. Without it, LSP servers won't be activated.
LSP_PYRIGHT_PATH=/usr/local/bin/pyright LSP_VTSLS_PATH=/usr/local/bin/vtsls LSP_RUST_ANALYZER_PATH=/usr/local/bin/rust-analyzer

**关键**：必须存在`ENABLE_LSP_TOOL=1`才能启用LSP功能。没有它，LSP服务器不会被激活。

Claude Code LSP Configuration

Claude Code LSP配置

The skill automatically updates Claude Code's LSP configuration. No manual editing required.
技能会自动更新Claude Code的LSP配置。无需手动编辑。

Integration with Claude Code

与Claude Code的集成

Once configured, Claude Code automatically:
  • Provides code completion based on project context
  • Shows real-time diagnostics (errors, warnings)
  • Enables "Go to Definition" navigation
  • Offers inline documentation on hover
  • Suggests intelligent refactorings
配置完成后，Claude Code会自动：
  • 根据项目上下文提供代码补全
  • 显示实时诊断信息（错误、警告）
  • 启用"跳转到定义"导航
  • 悬停时显示内联文档
  • 建议智能重构

Best Practices

最佳实践

  1. Run at project start: Configure LSP servers when you first open a project
  2. Update after adding languages: Rerun 
    /lsp-setup
    when adding new language files
  3. Commit 
    .env
    : Include LSP configuration in version control for team consistency
  4. Verify after installation: Use 
    --status-only
    to check server availability
  5. Keep servers updated: Regularly update LSP servers to latest versions
  1. 项目启动时运行：首次打开项目时配置LSP服务器
  2. 添加语言后更新：添加新语言文件时重新运行
    /lsp-setup
  3. 提交
    .env
    ：将LSP配置纳入版本控制，确保团队一致性
  4. 安装后验证：使用
    --status-only
    检查服务器可用性
  5. 保持服务器更新：定期将LSP服务器更新到最新版本

Technical Details

技术细节

Skill Type: Interactive command-driven workflow
Dependencies: None (pure skill, no external packages)
Execution Time: 2-10 seconds depending on project size
Persistence: Configuration stored in 
.env
and Claude Code settings
Supported Platforms: macOS, Linux, WSL
技能类型：交互式命令驱动工作流
依赖：无（纯技能，无外部包）
执行时间：2-10秒，取决于项目大小
持久性：配置存储在
.env
和Claude Code设置中
支持平台：macOS、Linux、WSL

Related Skills

相关技能

  • environment-setup
    - General development environment configuration
  • dependency-manager
    - Package and dependency management
  • project-init
    - New project initialization
  • environment-setup
    - 通用开发环境配置
  • dependency-manager
    - 包和依赖管理
  • project-init
    - 新项目初始化

Maintenance

维护

The LSP Setup skill requires no manual maintenance. It automatically adapts to your project structure and detects language changes on each run.
To update LSP server definitions or add new languages, see the developer documentation in 
README.md
.
LSP配置Skill无需手动维护。它会自动适应你的项目结构，并在每次运行时检测语言变化。
如需更新LSP服务器定义或添加新语言，请查看
README.md
中的开发者文档。

Execution Instructions (For Claude Code)

执行说明（针对Claude Code）

When this skill is activated via 
/lsp-setup
or activation keywords, execute the following workflow:
当通过
/lsp-setup
或激活关键词触发此技能时，执行以下工作流：

Phase 1: Language Detection

阶段1：语言检测

python
from pathlib import Path
from lsp_setup import LanguageDetector
python
from pathlib import Path
from lsp_setup import LanguageDetector

Detect languages in current project

检测当前项目中的语言

detector = LanguageDetector() project_root = Path.cwd() languages = detector.detect_languages(project_root)
detector = LanguageDetector() project_root = Path.cwd() languages = detector.detect_languages(project_root)

Report findings

报告检测结果

print(f"Detected {len(languages)} language(s):") for lang in languages: print(f" - {lang.language}: {lang.file_count} files")
undefined
print(f"检测到{len(languages)}种语言:") for lang in languages: print(f" - {lang.language}: {lang.file_count}个文件")
undefined

Phase 2: Check Current Status

阶段2：检查当前状态

python
from lsp_setup import StatusTracker
python
from lsp_setup import StatusTracker

Get current LSP setup status

获取当前LSP设置状态

language_names = [lang.language for lang in languages] tracker = StatusTracker(project_root, language_names) status = tracker.get_full_status()
language_names = [lang.language for lang in languages] tracker = StatusTracker(project_root, language_names) status = tracker.get_full_status()

Show status

显示状态

print(tracker.generate_user_guidance())
undefined
print(tracker.generate_user_guidance())
undefined

Phase 3: Configure LSP (If Needed)

阶段3：配置LSP（如有需要）

python
from lsp_setup import LSPConfigurator
python
from lsp_setup import LSPConfigurator

Configure .env file

配置.env文件

configurator = LSPConfigurator(project_root)
configurator = LSPConfigurator(project_root)

Enable LSP

启用LSP

if not configurator.is_lsp_enabled(): configurator.enable_lsp() print("✓ Enabled LSP in .env")
undefined
if not configurator.is_lsp_enabled(): configurator.enable_lsp() print("✓ 在.env中启用LSP")
undefined

Phase 4: Install Plugins (If Needed)

阶段4：安装插件（如有需要）

python
from lsp_setup import PluginManager
python
from lsp_setup import PluginManager

Install Claude Code plugins for detected languages

为检测到的语言安装Claude Code插件

manager = PluginManager()
manager = PluginManager()

Check prerequisites

检查前置条件

if not manager.check_npx_available(): print("⚠ npx not found. Install Node.js first:") print(" macOS: brew install node") print(" Linux: sudo apt install nodejs") exit(1)
if not manager.check_npx_available(): print("⚠ 未找到npx。请先安装Node.js:") print(" macOS: brew install node") print(" Linux: sudo apt install nodejs") exit(1)

Install plugins for languages with missing Layer 2

为缺少第二层的语言安装插件

for lang_name in language_names: layer_2_status = status["layer_2"][lang_name] if not layer_2_status["installed"]: print(f"Installing {lang_name} plugin...") success = manager.install_plugin(lang_name) if success: print(f"✓ {lang_name} plugin installed") else: print(f"✗ Failed to install {lang_name} plugin") print(f" {layer_2_status.get('install_guide', 'See docs')}")
undefined
for lang_name in language_names: layer_2_status = status["layer_2"][lang_name] if not layer_2_status["installed"]: print(f"安装{lang_name}插件...") success = manager.install_plugin(lang_name) if success: print(f"✓ {lang_name}插件已安装") else: print(f"✗ 安装{lang_name}插件失败") print(f" {layer_2_status.get('install_guide', '请查看文档')}")
undefined

Phase 5: Final Status Report

阶段5：最终状态报告

python
undefined
python
undefined

Recheck status after installation

安装后重新检查状态

final_status = tracker.get_full_status()
if final_status["overall_ready"]: print("\n✅ LSP setup complete! All layers configured.") else: print("\n⚠ LSP partially configured. Next steps:") print(tracker.generate_user_guidance())
undefined
final_status = tracker.get_full_status()
if final_status["overall_ready"]: print("\n✅ LSP设置完成！所有层已配置。") else: print("\n⚠ LSP已部分配置。下一步：") print(tracker.generate_user_guidance())
undefined

Command-Line Arguments (Optional)

命令行参数（可选）

Support these arguments if provided by user:
  • --status-only
    : Skip installation, just report current status
  • --force
    : Reinstall all plugins even if already installed
  • --languages <lang1,lang2>
    : Configure only specific languages
  • --dry-run
    : Show what would be done without making changes
如果用户提供以下参数，请支持：
  • --status-only
    : 跳过安装，仅报告当前状态
  • --force
    : 即使已安装，也重新安装所有插件
  • --languages <lang1,lang2>
    : 仅配置指定的语言
  • --dry-run
    : 显示将要执行的操作，但不实际修改