Suporte ao Protocolo de Servidor de Linguagem (LSP)

O Qwen Code oferece suporte nativo ao Protocolo de Servidor de Linguagem (LSP), permitindo funcionalidades avançadas de inteligência de código como ir para definição, localizar referências, diagnósticos e ações de código. Essa integração permite que o agente de IA entenda seu código de forma mais profunda e forneça assistência mais precisa.

Visão Geral

O suporte LSP no Qwen Code funciona conectando-se a servidores de linguagem que entendem seu código. Depois de configurar servidores via .lsp.json (ou extensões), o Qwen Code pode iniciá-los e usá-los para:

• Navegar até definições de símbolos
• Localizar todas as referências a um símbolo
• Obter informações ao passar o mouse (documentação, informações de tipo)
• Visualizar mensagens de diagnóstico (erros, avisos)
• Acessar ações de código (correções rápidas, refatorações)
• Analisar hierarquias de chamada

Início Rápido

O LSP é uma funcionalidade experimental no Qwen Code. Para ativá-lo, use a flag de linha de comando --experimental-lsp:

qwen --experimental-lsp

Os servidores LSP são orientados por configuração. Você deve defini-los no .lsp.json (ou via extensões) para que o Qwen Code os inicie.

Pré-requisitos

Você precisa ter o servidor de linguagem para sua linguagem de programação instalado:

Configuração

Arquivo .lsp.json

Você pode configurar servidores de linguagem usando um arquivo .lsp.json na raiz do seu projeto. Cada chave de nível superior é um identificador de linguagem, e seu valor é o objeto de configuração do servidor.

Formato básico:

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact",
      ".js": "javascript",
      ".jsx": "javascriptreact"
    }
  }
}

Configuração C/C++ (clangd)

Dependências:

• clangd (LLVM) deve estar instalado e disponível no PATH.
• Um banco de dados de compilação (compile_commands.json) ou compile_flags.txt é necessário para resultados precisos.

Exemplo:

{
  "cpp": {
    "command": "clangd",
    "args": [
      "--background-index",
      "--clang-tidy",
      "--header-insertion=iwyu",
      "--completion-style=detailed"
    ]
  }
}

Configuração Java (jdtls)

Dependências:

• JDK instalado e disponível no PATH (java).
• JDTLS instalado e disponível no PATH (jdtls).

Exemplo:

{
  "java": {
    "command": "jdtls",
    "args": ["-configuration", ".jdtls-config", "-data", ".jdtls-workspace"]
  }
}

Opções de Configuração

Campos Obrigatórios

Campos Opcionais

Transporte TCP/Socket

Para servidores que usam transporte TCP ou socket Unix:

{
  "remote-lsp": {
    "transport": "tcp",
    "socket": {
      "host": "127.0.0.1",
      "port": 9999
    },
    "extensionToLanguage": {
      ".custom": "custom"
    }
  }
}

Operações LSP Disponíveis

O Qwen Code expõe a funcionalidade LSP através da ferramenta unificada lsp. Aqui estão as operações disponíveis:

Operações baseadas em localização (goToDefinition, findReferences, hover, goToImplementation e prepareCallHierarchy) exigem uma posição exata de filePath + line + character. Se você não souber a posição exata, use workspaceSymbol ou documentSymbol primeiro para localizar o símbolo.

Navegação de Código

Ir para Definição

Encontra onde um símbolo é definido.

Operação: goToDefinition
Parâmetros:
  - filePath: Caminho para o arquivo
  - line: Número da linha (baseado em 1)
  - character: Número da coluna (baseado em 1)

Localizar Referências

Encontra todas as referências a um símbolo.

Operação: findReferences
Parâmetros:
  - filePath: Caminho para o arquivo
  - line: Número da linha (baseado em 1)
  - character: Número da coluna (baseado em 1)
  - includeDeclaration: Incluir a própria declaração (opcional)

Ir para Implementação

Encontra implementações de uma interface ou método abstrato.

Operação: goToImplementation
Parâmetros:
  - filePath: Caminho para o arquivo
  - line: Número da linha (baseado em 1)
  - character: Número da coluna (baseado em 1)

Informações de Símbolo

Hover (Passar o Mouse)

Obtém documentação e informações de tipo para um símbolo.

Operação: hover
Parâmetros:
  - filePath: Caminho para o arquivo
  - line: Número da linha (baseado em 1)
  - character: Número da coluna (baseado em 1)

Símbolos do Documento

Obtém todos os símbolos de um documento.

Operação: documentSymbol
Parâmetros:
  - filePath: Caminho para o arquivo

Pesquisa de Símbolos no Workspace

Pesquisa símbolos em todo o workspace.

Operação: workspaceSymbol
Parâmetros:
  - query: String de consulta
  - limit: Resultados máximos (opcional)

Hierarquia de Chamada

Preparar Hierarquia de Chamada

Obtém o item de hierarquia de chamada em uma posição.

Operação: prepareCallHierarchy
Parâmetros:
  - filePath: Caminho para o arquivo
  - line: Número da linha (baseado em 1)
  - character: Número da coluna (baseado em 1)

Chamadas Recebidas

Encontra todas as funções que chamam a função fornecida.

Operação: incomingCalls
Parâmetros:
  - callHierarchyItem: Item de prepareCallHierarchy

Chamadas Enviadas

Encontra todas as funções chamadas pela função fornecida.

Operação: outgoingCalls
Parâmetros:
  - callHierarchyItem: Item de prepareCallHierarchy

Diagnósticos

Diagnósticos de Arquivo

Obtém mensagens de diagnóstico (erros, avisos) para um arquivo.

Operação: diagnostics
Parâmetros:
  - filePath: Caminho para o arquivo

Diagnósticos do Workspace

Obtém todas as mensagens de diagnóstico em todo o workspace.

Operação: workspaceDiagnostics
Parâmetros:
  - limit: Resultados máximos (opcional)

Ações de Código

Obter Ações de Código

Obtém as ações de código disponíveis (correções rápidas, refatorações) em uma localização.

Operação: codeActions
Parâmetros:
  - filePath: Caminho para o arquivo
  - line: Número da linha inicial (baseado em 1)
  - character: Número da coluna inicial (baseado em 1)
  - endLine: Número da linha final (opcional, padrão = line)
  - endCharacter: Coluna final (opcional, padrão = character)
  - diagnostics: Diagnósticos para obter ações (opcional)
  - codeActionKinds: Filtrar por tipo de ação (opcional)

Tipos de ação de código:

• quickfix - Correções rápidas para erros/avisos
• refactor - Operações de refatoração
• refactor.extract - Extrair para função/variável
• refactor.inline - Inline de função/variável
• source - Ações de código fonte
• source.organizeImports - Organizar imports
• source.fixAll - Corrigir todos os problemas corrigíveis automaticamente

Segurança

Por padrão, os servidores LSP só são iniciados em workspaces confiáveis. Isso ocorre porque os servidores de linguagem executam com as permissões do seu usuário e podem executar código.

Controles de Confiança

• Workspace Confiável: Servidores LSP iniciam se configurados
• Workspace Não Confiável: Servidores LSP não iniciam, a menos que trustRequired: false esteja definido na configuração do servidor

Para marcar um workspace como confiável, use o comando /trust.

Substituição de Confiança por Servidor

Você pode substituir os requisitos de confiança para servidores específicos em sua configuração:

{
  "safe-server": {
    "command": "safe-language-server",
    "args": ["--stdio"],
    "trustRequired": false,
    "extensionToLanguage": {
      ".safe": "safe"
    }
  }
}

Solução de Problemas

Servidor Não Inicia

1. Verifique a flag --experimental-lsp: Certifique-se de que está usando a flag ao iniciar o Qwen Code
2. Verifique se o servidor está instalado: Execute o comando manualmente (ex.: clangd --version) para confirmar
3. Verifique o comando: O binário do servidor deve estar no PATH do sistema ou especificado como caminho absoluto (ex.: /opt/llvm/bin/clangd). Caminhos relativos que saem do workspace são bloqueados
4. Verifique a confiança do workspace: O workspace deve estar confiável para LSP (use /trust)
5. Verifique os logs: Inicie o Qwen Code com --debug e então procure por entradas relacionadas ao LSP no log de depuração (veja a seção de Depuração abaixo)
6. Verifique o processo: Execute ps aux | grep <nome-do-servidor> para verificar se o processo do servidor está em execução

Desempenho Lento

1. Projetos grandes: Considere excluir node_modules e outros diretórios grandes
2. Timeout do servidor: Aumente startupTimeout na configuração do servidor para servidores lentos

Nenhum Resultado

1. Servidor não pronto: O servidor pode ainda estar indexando. Para projetos C/C++ com clangd, certifique-se de que --background-index está nos argumentos e que um compile_commands.json (ou compile_flags.txt) existe na raiz do projeto ou em um diretório pai. Use --compile-commands-dir=<caminho> se estiver em um subdiretório de build
2. Arquivo não salvo: Salve seu arquivo para que o servidor capte as alterações
3. Linguagem errada: Verifique se o servidor correto está em execução para sua linguagem
4. Verifique o processo: Execute ps aux | grep <nome-do-servidor> para verificar se o servidor está realmente em execução

Depuração

O LSP não possui uma flag de depuração separada. Use o modo de depuração normal do Qwen Code juntamente com a flag de funcionalidade LSP:

qwen --experimental-lsp --debug

Os logs de depuração são gravados no diretório de log de depuração da sessão. Para verificar entradas relacionadas ao LSP:

# Diretório de runtime padrão
rg "LSP|Native LSP|clangd|connection closed" ~/.qwen/debug/latest
# Ou, sem ripgrep:
grep -E "LSP|Native LSP|clangd|connection closed" ~/.qwen/debug/latest
 
# Se QWEN_RUNTIME_DIR estiver configurado
rg "LSP|Native LSP|clangd|connection closed" "$QWEN_RUNTIME_DIR/debug/latest"

Entradas úteis incluem:

• [LSP] ...: Logs emitidos pelo serviço LSP nativo e gerenciador de servidores.
• [CONFIG] Native LSP status after discovery: ...: Configuração do servidor LSP descoberta para a sessão.
• [CONFIG] Native LSP status after startup: ...: Resultado da inicialização do servidor, incluindo contagens de prontos/falhas.
• [STATUS] LSP status snapshot for /status: ...: Instantâneo de status impresso ao executar /status no modo de depuração.

Você também pode executar /status no CLI para ver um breve resumo do LSP:

LSP: disabled
LSP: enabled, 1/1 ready
LSP: enabled, 0/1 ready (1 failed)
LSP: enabled, no servers configured
LSP: enabled, status unavailable

Para detalhes por servidor, execute /lsp:

**LSP Server Status**

| Server | Command | Languages | Status |
|--------|---------|-----------|--------|
| clangd | `clangd` | c, cpp | READY |
| pyright | `pyright-langserver` | python | FAILED - startup failed |

Mensagens de erro comuns a serem observadas:

command path is unsafe        -> caminho relativo escapa do workspace; use caminho absoluto ou adicione ao PATH
command not found             -> binário do servidor não instalado ou não está no PATH
requires trusted workspace    -> execute /trust primeiro
LSP connection closed         -> servidor iniciou, mas saiu ou fechou stdio antes de responder à inicialização

Para falhas de inicialização do clangd, verifique o servidor diretamente a partir da raiz do projeto:

clangd --version
clangd --check=/path/to/file.cpp --log=verbose

Projetos C/C++ geralmente devem fornecer um compile_commands.json ou compile_flags.txt. Se o banco de dados de compilação estiver em um diretório de build, passe-o para o clangd:

{
  "cpp": {
    "command": "clangd",
    "args": ["--background-index", "--compile-commands-dir=build"]
  }
}

ps aux | grep clangd   # ou typescript-language-server, jdtls, etc.

Configuração de LSP por Extensão

As extensões podem fornecer configurações de servidor LSP através do campo lspServers em seu plugin.json. Isso pode ser um objeto inline ou um caminho para um arquivo .lsp.json. O Qwen Code carrega essas configurações quando a extensão está habilitada. O formato é o mesmo layout chaveado por linguagem usado nos arquivos .lsp.json do projeto.

Melhores Práticas

1. Instale servidores de linguagem globalmente: Isso garante que estejam disponíveis em todos os projetos
2. Use configurações específicas do projeto: Configure opções do servidor por projeto quando necessário via .lsp.json
3. Mantenha os servidores atualizados: Atualize seus servidores de linguagem regularmente para obter melhores resultados
4. Confie com sabedoria: Confie apenas em workspaces de fontes confiáveis

FAQ

P: Como ativo o LSP?

Use a flag --experimental-lsp ao iniciar o Qwen Code:

qwen --experimental-lsp

P: Como saber quais servidores de linguagem estão em execução?

Inicie o Qwen Code com LSP e modo de depuração ativados:

qwen --experimental-lsp --debug

Em seguida, execute /status para um resumo breve, /lsp para status por servidor, ou inspecione o log de depuração:

# Diretório de runtime padrão
rg "LSP|Native LSP|<nome-do-servidor>" ~/.qwen/debug/latest
# Ou:
grep -E "LSP|Native LSP|<nome-do-servidor>" ~/.qwen/debug/latest
 
# Se QWEN_RUNTIME_DIR estiver configurado
rg "LSP|Native LSP|<nome-do-servidor>" "$QWEN_RUNTIME_DIR/debug/latest"

O LSP usa o modo --debug normal do Qwen Code; não há uma flag de depuração separada para LSP.

P: Posso usar vários servidores de linguagem para o mesmo tipo de arquivo?

Sim, mas apenas um será usado para cada operação. O primeiro servidor que retornar resultados vence.

P: O LSP funciona no modo sandbox?

Os servidores LSP são executados fora do sandbox para acessar seu código. Eles estão sujeitos aos controles de confiança do workspace.