lsp-setup

LSP 自动配置技能

用于手动控制和排查语言服务器协议（LSP）配置问题。

重要提示：LSP 已自动配置

你可能不需要这个技能！ 运行 amplihack claude 时，LSP 会自动配置。

amplihack 启动 Claude Code 时，会自动：

• 检测项目中的编程语言
• 设置 ENABLE_LSP_TOOL=1 环境变量
• 通过 Claude Code 插件市场安装所需的 LSP 插件
• 在 .env 中配置项目专属设置

你会看到： amplihack 启动 Claude Code 时显示 📡 LSP: Detected 3 language(s): python, javascript...。

何时使用此技能

仅在需要以下操作时使用 /lsp-setup：

• 检查状态：确认 LSP 配置是否正常运行（/lsp-setup --status-only）
• 排查问题：诊断代码智能功能为何无法运行
• 强制重新配置：手动更改后重建 LSP 配置（/lsp-setup --force）
• 添加新语言：为新添加的语言配置 LSP

如果 LSP 已正常运行，请勿使用此技能！ 自动设置可以处理 99% 的情况。

概述

LSP 设置技能可手动控制启动时自动执行的同一套 LSP 自动配置。它开箱即支持 16 种常见编程语言，并提供直接访问配置、状态检查和问题排查的功能。

LSP 能为你提供什么

正确配置 LSP 后，Claude Code 将获得强大的代码智能能力，从而增强 AI 对代码库的理解：

实时代码智能

类型信息——Claude 可以查看变量、函数和类的确切类型：

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

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

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

代码诊断——Claude 可从 LSP 服务实时接收错误检测结果：

# Pyright reports: "Set" is not accessed
from typing import List, Set  # Claude sees this warning

Claude 如何使用 LSP

更好地理解代码——Claude 无需猜测类型和行为，而是从 LSP 服务获取以下准确信息：

• 函数签名和返回类型
• 类层次结构和继承关系
• 导入路径和模块结构
• 运行前的错误和警告

更智能的建议——借助 LSP 数据，Claude 可以提供：

• 准确的重构建议
• 类型安全的代码补全
• 精确的错误修复
• 考虑上下文的代码生成

工作流示例：

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

你会注意到什么

/lsp-setup 为项目完成配置后：

1. 响应更加准确——Claude 的代码建议会与实际类型和 API 相符
2. 调试更快——Claude 能看到 IDE 会显示的同样错误
3. 重构效果更好——Claude 可以借助 LSP 引用，安全地跨文件重命名变量
4. 导航更加精准——Claude 可以准确查找定义、用法和实现

重要说明

LSP 会在幕后增强 Claude 的能力。你无需直接与 LSP 交互——它会自动提升 Claude 对代码的理解能力。

何时使用此技能

在以下情况下使用 /lsp-setup：

• 开始在 Claude Code 中处理新项目
• 为现有项目添加新的编程语言
• 发现代码智能功能缺失或不准确
• 想确认 LSP 配置是否正确
• 需要排查 LSP 服务连接问题

工作原理

LSP 架构 - 三层结构

Claude Code 的 LSP 系统采用三层架构，必须全部配置完成，LSP 功能才能正常工作：

第 1 层：系统 LSP 二进制文件（用户安装）

• 通过 npm、brew、rustup 等在系统上安装的 LSP 服务可执行文件。
• 示例：npm install -g pyright 会安装 Pyright LSP 服务二进制文件。
• 这些是实际的语言分析引擎。

第 2 层：Claude Code LSP 插件（通过 cclsp 安装）

• 连接第 1 层二进制文件的 Claude Code 插件。
• 使用以下命令安装：npx cclsp install <server-name>
• cclsp 工具使用 claude-code-lsps 插件市场。
• 这些插件充当 Claude Code 与 LSP 服务之间的桥梁。

第 3 层：项目配置（.env 文件）

• 项目专属设置：虚拟环境、项目根目录等。
• 必须包含 ENABLE_LSP_TOOL=1 才能启用 LSP 功能。
• 存储在项目根目录下的 .env 文件中。

重要：cclsp 和 claude-code-lsps 协同工作。cclsp 是安装工具，claude-code-lsps 是它使用的插件市场。两者相辅相成，并非替代关系。

此技能的 4 个阶段

/lsp-setup 技能会自动执行 npx cclsp@latest setup 工作流：

第 1 阶段：语言检测

扫描项目目录，根据文件扩展名和框架标记识别编程语言。可检测 16 种语言，包括 Python、TypeScript、JavaScript、Rust、Go、Java 等。

第 2 阶段：LSP 配置

为每种检测到的语言生成相应的 LSP 服务配置。检查以下项目：

1. 是否已安装系统 LSP 二进制文件（第 1 层）
2. 是否已安装 Claude Code 插件（第 2 层）

如果缺少任意一项，会提供安装指导。绝不会自动安装——用户拥有完全控制权。

第 3 阶段：项目配置

创建或更新 .env 文件，添加项目专属的 LSP 设置（第 3 层）：

• 工作区专属选项（Python 虚拟环境、Node.js 项目根目录等）
• ENABLE_LSP_TOOL=1（启用 LSP 功能所必需）

第 4 阶段：验证

测试每个 LSP 服务的连接并报告状态。针对任何配置问题提供可执行的指导。

用法

基本用法

/lsp-setup

检测项目中的所有语言并自动配置 LSP 服务。

仅检查状态

/lsp-setup --status-only

报告当前的 LSP 配置和服务可用性，不做任何更改。

强制重新配置

/lsp-setup --force

即使已有有效配置，也会重新生成 LSP 配置。

指定语言

/lsp-setup --languages python,typescript

仅为指定语言配置 LSP 服务。

手动管理插件

如果需要直接管理 Claude Code LSP 插件，请使用 cclsp 命令：

# Install a plugin (Layer 2)
npx cclsp install pyright

# List installed plugins
npx cclsp list

# Remove a plugin
npx cclsp remove pyright

# Full setup workflow (what /lsp-setup automates)
npx cclsp@latest setup

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

支持的语言

语言	LSP 服务	系统二进制文件安装（第 1 层）	Claude Code 插件（第 2 层）
Python	pyright	npm install -g pyright	npx cclsp install pyright
TypeScript	vtsls	npm install -g @vtsls/language-server	npx cclsp install vtsls
JavaScript	vtsls	npm install -g @vtsls/language-server	npx cclsp install vtsls
Rust	rust-analyzer	rustup component add rust-analyzer	npx cclsp install rust-analyzer
Go	gopls	go install golang.org/x/tools/gopls@latest	npx cclsp install gopls
Java	jdtls	从 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
Ruby	ruby-lsp	gem install ruby-lsp	npx cclsp install ruby-lsp
PHP	phpactor	composer global require phpactor/phpactor	npx cclsp install phpactor
Bash	bash-language-server	npm install -g bash-language-server	npx cclsp install bash-language-server
YAML	yaml-language-server	npm install -g yaml-language-server	npx cclsp install yaml-language-server
JSON	vscode-json-languageserver	npm install -g vscode-json-languageserver	npx cclsp install vscode-json-languageserver
HTML	vscode-html-languageserver	npm install -g vscode-html-languageserver	npx cclsp install vscode-html-languageserver
CSS	vscode-css-languageserver	npm install -g vscode-css-languageserver	npx cclsp install vscode-css-languageserver
Markdown	marksman	brew install marksman（macOS）/ 从 GitHub 下载	npx cclsp install marksman

注意：要使用 LSP 功能，必须同时安装第 1 层（系统二进制文件）和第 2 层（Claude Code 插件）。

示例：Python 项目设置

$ 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.

示例：多语言项目设置

$ 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.

如何验证 LSP 是否正常工作

运行 /lsp-setup 后，可以通过以下方式确认 LSP 正在为 Claude 提供代码智能：

方法 1：检查诊断信息

让 Claude 分析一个包含有意错误的文件：

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

方法 2：请求类型信息

询问 Claude 代码中的类型：

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"

方法 3：测试导航

让 Claude 查找定义：

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'"

方法 4：检查状态命令

运行状态检查：

/lsp-setup --status-only

预期输出（LSP 正常工作）：

[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)

异常输出（LSP 未正常工作）：

[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'

成功时的表现

LSP 正常工作时，你会发现：

1. Claude 会在讨论错误时提及具体行号
2. Claude 会提供确切类型，而不是猜测
3. Claude 会在代码运行前发现警告和错误（就像 IDE 一样）
4. Claude 可以利用 LSP 的理解导航代码结构

故障表现

当 LSP 无法正常工作时，你会发现：

1. Claude 只能看到文件内容——没有类型信息或诊断信息
2. Claude 会根据已有信息推测类型和行为
3. Claude 不会提及错误，直到你运行代码
4. Claude 会搜索文本，而不是利用语义理解

故障排除

问题：未找到 LSP 服务端

症状：配置时显示“rust-analyzer: Not found”

解决方案：使用提供的安装命令安装 LSP 服务端

$ rustup component add rust-analyzer
$ /lsp-setup --force  # Reconfigure after installation

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

症状：验证时显示“pyright: Connection failed”

解决方案：检查 LSP 服务端日志并确认安装无误

# Check if server is properly installed
$ which pyright
/usr/local/bin/pyright

# Test server manually
$ pyright --version
pyright 1.1.332

# Check Claude Code LSP logs
$ cat ~/.claude-code/lsp-logs/pyright.log

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

症状：尽管虚拟环境中已安装软件包，仍出现导入错误

解决方案：确认 .env 配置指向正确的 Python 解释器

# Check current configuration
$ cat .env | grep PYTHON

# Should show:
LSP_PYTHON_INTERPRETER=/path/to/.venv/bin/python

# If incorrect, update manually or run:
$ /lsp-setup --force

问题：未检测到 TypeScript 项目

症状：存在 .ts 文件，但没有 TypeScript LSP 配置

解决方案：确保项目根目录中存在 tsconfig.json

# Create minimal tsconfig.json
$ cat > tsconfig.json << EOF
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true
  }
}
EOF

$ /lsp-setup --force

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

症状：LSP 服务端使用了错误的 Python 版本，导致出现“Module not found”错误

解决方案：在 .env 中明确设置 Python 解释器

# Edit .env manually
LSP_PYTHON_INTERPRETER=/usr/bin/python3.11

# Or activate the correct virtual environment before running
$ source .venv/bin/activate
$ /lsp-setup --force

配置文件

.env（项目根目录）

此技能会创建或更新 .env，添加 LSP 专用配置：

# LSP Configuration - Auto-generated by /lsp-setup
ENABLE_LSP_TOOL=1  # REQUIRED: Activates LSP features in Claude Code

# 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

# 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

重要：必须存在 ENABLE_LSP_TOOL=1，LSP 功能才能正常工作。缺少该配置时，LSP 服务端不会启用。

Claude Code LSP 配置

此技能会自动更新 Claude Code 的 LSP 配置，无需手动编辑。

与 Claude Code 集成

配置完成后，Claude Code 会自动：

• 根据项目上下文提供代码补全
• 显示实时诊断信息（错误、警告）
• 启用“转到定义”导航
• 在悬停时提供行内文档
• 提供智能重构建议

最佳实践

1. 在项目启动时运行：首次打开项目时配置 LSP 服务端
2. 添加语言后更新：添加新的语言文件时，重新运行 /lsp-setup
3. 提交 .env：将 LSP 配置纳入版本控制，以确保团队配置一致
4. 安装后验证：使用 --status-only 检查服务端是否可用
5. 保持服务端更新：定期将 LSP 服务端更新到最新版本

技术详情

技能类型：交互式命令驱动工作流

依赖项：无（纯技能，无外部软件包）

执行时间：根据项目规模，需 2-10 秒

持久化：配置存储在 .env 和 Claude Code 设置中

支持的平台：macOS、Linux、WSL

相关技能

• environment-setup - 通用开发环境配置
• dependency-manager - 软件包与依赖项管理
• project-init - 新项目初始化

维护

LSP Setup 技能无需手动维护。它会自动适应你的项目结构，并在每次运行时检测语言变更。

如需更新 LSP 服务端定义或添加新语言，请参阅 README.md 中的开发者文档。

---

执行说明（适用于 Claude Code）

通过 /lsp-setup 或激活关键词激活此技能时，请执行以下工作流：

阶段 1：语言检测

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)

# Report findings
print(f"Detected {len(languages)} language(s):")
for lang in languages:
    print(f"  - {lang.language}: {lang.file_count} files")

阶段 2：检查当前状态

from lsp_setup import StatusTracker

# Get current LSP setup 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())

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

from lsp_setup import LSPConfigurator

# Configure .env file
configurator = LSPConfigurator(project_root)

# Enable LSP
if not configurator.is_lsp_enabled():
    configurator.enable_lsp()
    print("✓ Enabled LSP in .env")

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

from lsp_setup import PluginManager

# Install Claude Code plugins for detected languages
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)

# 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')}")

阶段 5：最终状态报告

# 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())

命令行参数（可选）

如果用户提供了以下参数，请予以支持：

• --status-only：跳过安装，仅报告当前状态
• --force：即使已安装所有插件，也重新安装
• --languages <lang1,lang2>：仅配置指定语言
• --dry-run：显示将要执行的操作，但不进行更改