Inspection LSP

Ajouté dans : @mastra/core@1.1.0

L’inspection LSP fournit une intelligence sémantique du code aux agents adossés à un workspace. Lorsque vous activez LSP dans un workspace, les agents peuvent inspecter les symboles des fichiers pris en charge afin d’obtenir des informations de survol et d’accéder à leurs définitions. Ils peuvent également rechercher leurs implémentations.

Quand utiliser l’inspection LSP

Utilisez l’inspection LSP lorsque votre agent a besoin de comprendre la sémantique du code, au-delà d’une simple recherche en texte brut :

• Inspecter les symboles et leurs types déduits dans n’importe quel langage pris en charge
• Trouver l’emplacement où un symbole est déclaré avant de modifier le code associé
• Explorer les implémentations dans une base de code sans parcourir manuellement chaque fichier
• Combiner l’inspection sémantique avec view et search_content pour naviguer plus rapidement
• Prendre en charge d’autres langages avec LSP en enregistrant des serveurs de langage personnalisés

Utilisation de base

Activez LSP dans un workspace en définissant lsp: true :

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: true,
})

Avec cette configuration, le workspace enregistre l’outil d’inspection LSP par défaut avec les outils de système de fichiers et de sandbox configurés.

Outil de l’agent

Lorsque LSP est activé, le workspace expose mastra_workspace_lsp_inspect par défaut.

{
  "path": "/absolute/path/to/file.ts",
  "line": 10,
  "match": "const foo = <<<bar()"
}

Le champ match doit contenir exactement un marqueur de curseur <<<. Ce marqueur indique la position du symbole sur la ligne spécifiée.

L’outil renvoie jusqu’à trois groupes de résultats :

Résultat	Description
hover	Informations de type ou documentation du symbole situé sous le curseur
diagnostics	Diagnostics LSP limités à la ligne inspectée, lorsqu’ils sont présents
definition	Emplacements des déclarations avec un aperçu d’une ligne
implementation	Emplacements des implémentations ou des utilisations

Remapper le nom de l’outil

Renommez l’outil si votre agent attend un nom plus court :

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  lsp: true,
  tools: {
    [WORKSPACE_TOOLS.LSP.LSP_INSPECT]: {
      name: 'lsp_inspect',
    },
  },
})

Cette opération modifie uniquement le nom exposé de l’outil. La clé de configuration reste WORKSPACE_TOOLS.LSP.LSP_INSPECT.

Configuration LSP

Définissez lsp sur true pour utiliser le comportement par défaut, ou fournissez un objet afin de personnaliser le démarrage des serveurs et les diagnostics :

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  lsp: {
    diagnosticTimeout: 4000,
    initTimeout: 8000,
    disableServers: ['eslint'],
    binaryOverrides: {
      typescript: '/custom/path/to/typescript-language-server --stdio',
    },
    searchPaths: ['/opt/homebrew/bin'],
  },
})

Utilisez une configuration personnalisée lorsque vous devez :

• Augmenter les délais d’expiration pour les dépôts volumineux
• Désactiver certains serveurs de langage
• Indiquer à Mastra des binaires personnalisés de serveurs de langage
• Ajouter des chemins de recherche de binaires dans les environnements soumis à des contraintes

Serveurs de langage personnalisés

Par défaut, Mastra prend en charge TypeScript, JavaScript, Python, Go et Rust. Pour utiliser l’inspection LSP avec d’autres langages, par exemple PHP, Ruby, Java, Kotlin, Swift ou Elixir, enregistrez un serveur de langage personnalisé au moyen du champ servers :

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: {
    servers: {
      phpactor: {
        id: 'phpactor',
        name: 'Phpactor Language Server',
        languageIds: ['php'],
        extensions: ['.php'],
        markers: ['composer.json'],
        command: 'phpactor language-server',
      },
    },
  },
})

Chaque définition de serveur personnalisé nécessite les champs suivants :

Champ	Description
id	Identifiant unique du serveur
name	Nom lisible affiché dans les journaux
languageIds	Identifiants de langage du protocole Language Server Protocol (LSP) gérés par ce serveur
extensions	Extensions de fichiers, point compris
markers	Fichiers ou répertoires qui identifient la racine du projet, par exemple composer.json ou Gemfile
command	Chaîne de commande complète permettant de démarrer le serveur

Lorsqu’un serveur possède plusieurs identifiants de langage, Mastra associe chaque extension à la première entrée de languageIds.

Vous pouvez également transmettre l’option facultative initializationOptions pour envoyer des paramètres personnalisés pendant l’établissement de la connexion LSP.

Les serveurs personnalisés sont fusionnés avec les serveurs intégrés. Pour remplacer un serveur intégré, utilisez le même id, par exemple id: 'go' remplace le serveur Go intégré. Enregistrez plusieurs serveurs pour prendre en charge plusieurs langages simultanément :

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: {
    servers: {
      phpactor: {
        id: 'phpactor',
        name: 'Phpactor Language Server',
        languageIds: ['php'],
        extensions: ['.php'],
        markers: ['composer.json'],
        command: 'phpactor language-server',
      },
      solargraph: {
        id: 'solargraph',
        name: 'Solargraph',
        languageIds: ['ruby'],
        extensions: ['.rb', '.erb'],
        markers: ['Gemfile'],
        command: 'solargraph stdio',
      },
    },
  },
})

Exigences et limitations

• L’inspection LSP fonctionne uniquement avec les types de fichiers associés à un serveur de langage intégré ou personnalisé
• Le path inspecté doit être résolu dans le système de fichiers du workspace ou dans les chemins autorisés
• L’inspection des packages externes peut aboutir à des fichiers de déclaration tels que .d.ts plutôt qu’aux fichiers sources utilisés au moment de l’exécution
• lsp_inspect complète view et search_content, mais ne remplace pas la lecture du code d’implémentation lorsque vous avez besoin du contexte complet

Ressources associées

• Vue d’ensemble du Workspace
• Système de fichiers
• Sandbox
• Recherche et indexation
• Référence de la classe Workspace