Chat-Teilnehmer-API

Chat-Teilnehmer sind spezialisierte Assistenten, die es Benutzern ermöglichen, den Chat in VS Code mit domänenspezifischen Experten zu erweitern. Benutzer rufen einen Chat-Teilnehmer auf, indem sie ihn mit @ erwähnen, und der Teilnehmer ist dann für die Bearbeitung der natürlichsprachlichen Eingabeaufforderung des Benutzers verantwortlich.

In dieser Erweitungsanleitung erfahren Sie, wie Sie einen Chat-Teilnehmer mit der Chat-Teilnehmer-API erstellen.

VS Code verfügt über mehrere integrierte Chat-Teilnehmer wie @vscode, @terminal oder @workspace. Diese sind für die Beantwortung von Fragen zu ihren jeweiligen Domänen optimiert.

Chat-Teilnehmer unterscheiden sich von Sprachmodell-Tools, die als Teil des LLM aufgerufen werden, das die zur Lösung der Chat-Eingabeaufforderung des Benutzers erforderlichen Schritte orchestriert. Chat-Teilnehmer empfangen die Eingabeaufforderung des Benutzers und orchestrieren die erforderlichen Aufgaben selbst.

Warum einen Chat-Teilnehmer in Ihrer Erweiterung implementieren?

Die Implementierung eines Chat-Teilnehmers in Ihrer Erweiterung bietet mehrere Vorteile

• Erweitern Sie den Chat mit spezialisiertem, domänenspezifischem Wissen und Fachwissen. Der integrierte @vscode-Teilnehmer verfügt beispielsweise über Wissen über VS Code und seine Erweiterungs-APIs.
• Eigenständige Konversation durch Verwaltung der End-to-End-Chat-Eingabeaufforderung und -Antwort des Benutzers.
• Tiefgehende Integration mit VS Code durch Nutzung des breiten Spektrums an Erweiterungs-APIs. Verwenden Sie beispielsweise die Debug-APIs, um den aktuellen Debugging-Kontext abzurufen und ihn als Teil der Funktionalität des Tools zu verwenden.
• Verteilen und Bereitstellen von Chat-Teilnehmern über den Visual Studio Marketplace, um eine zuverlässige und nahtlose Benutzererfahrung zu bieten. Benutzer benötigen keinen separaten Installations- und Aktualisierungsprozess.

Sie könnten die Implementierung eines Sprachmodell-Tools oder eines MCP-Servers in Erwägung ziehen, wenn Sie domänenspezifische Funktionen bereitstellen möchten, die automatisch als Teil einer autonomen, agentenbasierten Codierungssitzung aufgerufen werden können. Weitere Details zu den verschiedenen Optionen und zur Entscheidung, welcher Ansatz zu verwenden ist, finden Sie in der Übersicht über KI-Erweiterbarkeit.

Teile der Chat-Benutzeroberfläche

Der folgende Screenshot zeigt die verschiedenen Chat-Konzepte in der Visual Studio Code Chat-Benutzeroberfläche für die Beispielerweiterung.

1. Verwenden Sie die @-Syntax, um den Chat-Teilnehmer @cat aufzurufen
2. Verwenden Sie die /-Syntax, um den Befehl /teach aufzurufen
3. Vom Benutzer bereitgestellte Abfrage, auch bekannt als Benutzer-Prompt
4. Symbol und fullName des Teilnehmers, die anzeigen, dass Copilot den Chat-Teilnehmer @cat verwendet
5. Markdown-Antwort, bereitgestellt von @cat
6. Code-Fragment, das in der Markdown-Antwort enthalten ist
7. Schaltfläche, die in der @cat-Antwort enthalten ist; die Schaltfläche ruft einen VS Code-Befehl auf
8. Vorgeschlagene Nachfragen, die vom Chat-Teilnehmer bereitgestellt werden
9. Chat-Eingabefeld mit dem Platzhaltertext, der von der description-Eigenschaft des Chat-Teilnehmers bereitgestellt wird

Chat-Teilnehmer erstellen

Die Implementierung eines Chat-Teilnehmers besteht aus den folgenden Teilen

1. Definieren Sie den Chat-Teilnehmer in der Datei package.json Ihrer Erweiterung.
2. Implementieren Sie einen Anforderungs-Handler, um die Chat-Eingabeaufforderung des Benutzers zu verarbeiten und eine Antwort zurückzugeben.
3. (Optional) Implementieren Sie Chat-Slash-Befehle, um Benutzern eine Kurzdarstellung für gängige Aufgaben zu bieten.
4. (Optional) Definieren Sie vorgeschlagene Nachfragen.
5. (Optional) Implementieren Sie die Teilnehmererkennung, bei der VS Code eine Chat-Anfrage automatisch an den entsprechenden Chat-Teilnehmer weiterleitet, ohne dass der Benutzer ihn explizit erwähnen muss.

Sie können mit einem grundlegenden Beispielprojekt beginnen.

1. Registrieren Sie den Chat-Teilnehmer

Der erste Schritt zur Erstellung einer Chat-Erweiterung ist die Registrierung in Ihrer package.json mit den folgenden Eigenschaften

• id: Eine eindeutige Kennung für den Chat-Teilnehmer, wie in der Datei package.json definiert.
• name: Ein kurzer Name für den Chat-Teilnehmer, der für @-Erwähnungen im Chat verwendet wird.
• fullName: Der vollständige Name des Chat-Teilnehmers, der im Titelbereich der Antwort angezeigt wird.
• description: Eine kurze Beschreibung des Zwecks des Chat-Teilnehmers, die als Platzhaltertext im Chat-Eingabefeld verwendet wird.
• isSticky: Ein boolescher Wert, der angibt, ob der Chat-Teilnehmer nach der Antwort im Chat-Eingabefeld persistent ist.

"contributes": {
        "chatParticipants": [
            {
                "id": "chat-sample.my-participant",
                "name": "my-participant",
                "fullName": "My Participant",
                "description": "What can I teach you?",
                "isSticky": true
            }
        ]
}

Wir empfehlen, einen Kleinbuchstaben für name und Camel Case für fullName zu verwenden, um mit vorhandenen Chat-Teilnehmern übereinzustimmen. Weitere Informationen zu den Namenskonventionen für Chat-Teilnehmer.

2. Implementieren Sie einen Anforderungs-Handler

Implementieren Sie den Chat-Teilnehmer mit der Chat-Teilnehmer-API. Dies umfasst die folgenden Schritte

1. Bei Aktivierung der Erweiterung erstellen Sie den Teilnehmer mit vscode.chat.createChatParticipant.

   Geben Sie die ID an, die Sie in package.json definiert haben, und einen Verweis auf den Anforderungs-Handler, den Sie im nächsten Schritt implementieren.

   export function activate(context: vscode.ExtensionContext) {
     // Register the chat participant and its request handler
     const cat = vscode.chat.createChatParticipant('chat-sample.my-participant', handler);
   
     // Optionally, set some properties for @cat
     cat.iconPath = vscode.Uri.joinPath(context.extensionUri, 'cat.jpeg');
   
     // Add the chat request handler here
   }
   

2. Definieren Sie in der Funktion activate den Anforderungs-Handler vscode.ChatRequestHandler.

   Der Anforderungs-Handler ist für die Verarbeitung der Chat-Anfragen des Benutzers in der VS Code Chat-Ansicht zuständig. Jedes Mal, wenn ein Benutzer eine Eingabeaufforderung in das Chat-Eingabefeld eingibt, wird der Chat-Anforderungs-Handler aufgerufen.

   const handler: vscode.ChatRequestHandler = async (
     request: vscode.ChatRequest,
     context: vscode.ChatContext,
     stream: vscode.ChatResponseStream,
     token: vscode.CancellationToken
   ): Promise<ICatChatResult> => {
     // Chat request handler implementation goes here
   };
   

3. Ermitteln Sie die Absicht des Benutzers anhand von vscode.ChatRequest.

   Um die Absicht der Benutzeranfrage zu ermitteln, können Sie den Parameter vscode.ChatRequest referenzieren, um auf den Text der Eingabeaufforderung des Benutzers, Befehle und den Chat-Speicherort zuzugreifen.

   Optional können Sie das Sprachmodell nutzen, um die Benutzerabsicht zu ermitteln, anstatt traditionelle Logik zu verwenden. Als Teil des request-Objekts erhalten Sie eine Sprachmodellinstanz, die der Benutzer in der Dropdown-Liste des Chat-Modells ausgewählt hat. Erfahren Sie, wie Sie die Sprachmodell-API in Ihrer Erweiterung verwenden können.

   Der folgende Codeausschnitt zeigt die grundlegende Struktur der ersten Verwendung des Befehls und dann der Benutzereingabeaufforderung zur Ermittlung der Benutzerabsicht

   const handler: vscode.ChatRequestHandler = async (
     request: vscode.ChatRequest,
     context: vscode.ChatContext,
     stream: vscode.ChatResponseStream,
     token: vscode.CancellationToken
   ): Promise<ICatChatResult> => {
     // Test for the `teach` command
     if (request.command == 'teach') {
       // Add logic here to handle the teaching scenario
       doTeaching(request.prompt, request.variables);
     } else {
       // Determine the user's intent
       const intent = determineUserIntent(request.prompt, request.variables, request.model);
   
       // Add logic here to handle other scenarios
     }
   };
   

4. Fügen Sie Logik zur Verarbeitung der Benutzeranfrage hinzu.

   Oft verwenden Chat-Erweiterungen die Sprachmodellinstanz request.model zur Verarbeitung der Anfrage. In diesem Fall können Sie die Eingabeaufforderung des Sprachmodells an die Benutzerabsicht anpassen.

   Alternativ können Sie die Erweiterungslogik durch Aufrufen eines Backend-Dienstes, durch Verwendung traditioneller Programmierlogik oder durch eine Kombination all dieser Optionen implementieren. Sie könnten beispielsweise eine Websuche aufrufen, um zusätzliche Informationen zu sammeln, die Sie dann als Kontext für das Sprachmodell bereitstellen.

   Bei der Verarbeitung der aktuellen Anfrage möchten Sie möglicherweise auf frühere Chat-Nachrichten verweisen. Wenn beispielsweise eine frühere Antwort einen C#-Code-Schnipsel zurückgegeben hat, könnte die aktuelle Anfrage des Benutzers lauten: „Gib den Code in Python.“ Erfahren Sie, wie Sie den Chat-Nachrichtenverlauf verwenden können.

   Wenn Sie eine Anfrage basierend auf dem Speicherort der Chat-Eingabe (Chat-Ansicht, Schnelleingabe, Inline-Chat) unterschiedlich verarbeiten möchten, können Sie die Eigenschaft location von vscode.ChatRequest verwenden. Wenn der Benutzer beispielsweise eine Anfrage aus dem Terminal-Inline-Chat sendet, könnten Sie nach einem Shell-Befehl suchen. Wenn der Benutzer jedoch die Chat-Ansicht verwendet, könnten Sie eine ausführlichere Antwort zurückgeben.

5. Geben Sie die Chat-Antwort an den Benutzer zurück.

   Sobald Sie die Anfrage verarbeitet haben, müssen Sie eine Antwort an den Benutzer in der Chat-Ansicht zurückgeben. Sie können Streaming verwenden, um auf Benutzeranfragen zu antworten.

   Antworten können verschiedene Inhaltstypen enthalten: Markdown, Bilder, Referenzen, Fortschritt, Schaltflächen und Dateistrukturen.

   

   Eine Erweiterung kann den Antwortstrom auf folgende Weise nutzen

   stream.progress('Picking the right topic to teach...');
   stream.markdown(`\`\`\`typescript
   const myStack = new Stack();
   myStack.push(1); // pushing a number on the stack (or let's say, adding a fish to the stack)
   myStack.push(2); // adding another fish (number 2)
   console.log(myStack.pop()); // eating the top fish, will output: 2
   \`\`\`
   So remember, Code Kitten, in a stack, the last fish in is the first fish out - which we tech cats call LIFO (Last In, First Out).`);
   
   stream.button({
     command: 'cat.meow',
     title: vscode.l10n.t('Meow!'),
     arguments: []
   });
   

   Weitere Informationen zu den unterstützten Chat-Antwortausgabetypen.

   In der Praxis senden Erweiterungen normalerweise eine Anfrage an das Sprachmodell. Sobald sie eine Antwort vom Sprachmodell erhalten, verarbeiten sie diese möglicherweise weiter und entscheiden, ob sie etwas an den Benutzer streamen sollen. Die VS Code Chat-API ist Streaming-basiert und kompatibel mit der Streaming-Version der Sprachmodell-API. Dies ermöglicht es Erweiterungen, Fortschritte und Ergebnisse kontinuierlich zu melden, mit dem Ziel einer reibungslosen Benutzererfahrung. Erfahren Sie, wie Sie die Sprachmodell-API verwenden können.

3. Slash-Befehle registrieren

Ein Chat-Teilnehmer kann Slash-Befehle beitragen, die Verknüpfungen zu spezifischen Funktionen darstellen, die von der Erweiterung bereitgestellt werden. Benutzer können Slash-Befehle im Chat mit der /-Syntax referenzieren, z. B. /explain.

Eine der Aufgaben bei der Beantwortung von Fragen ist die Ermittlung der Benutzerabsicht. VS Code könnte beispielsweise ableiten, dass Create a new workspace with Node.js Express Pug TypeScript bedeutet, dass Sie ein neues Projekt wünschen, aber @workspace /new Node.js Express Pug TypeScript ist expliziter, prägnanter und spart Tippzeit. Wenn Sie / in das Chat-Eingabefeld eingeben, bietet VS Code eine Liste registrierter Befehle mit deren Beschreibung an.

Chat-Teilnehmer können Slash-Befehle mit ihrer Beschreibung beitragen, indem sie diese in package.json hinzufügen

"contributes": {
    "chatParticipants": [
        {
            "id": "chat-sample.cat",
            "name": "cat",
            "fullName": "Cat",
            "description": "Meow! What can I teach you?",
            "isSticky": true,
            "commands": [
                {
                    "name": "teach",
                    "description": "Pick at random a computer science concept then explain it in purfect way of a cat"
                },
                {
                    "name": "play",
                    "description": "Do whatever you want, you are a cat after all"
                }
            ]
        }
    ]
}

Weitere Informationen zu den Namenskonventionen für Slash-Befehle.

4. Nachfragen registrieren

Nach jeder Chat-Anfrage ruft VS Code Nachfrage-Provider auf, um vorgeschlagene Nachfragen zu erhalten, die dem Benutzer angezeigt werden. Der Benutzer kann dann die Nachfrage auswählen und sie sofort an die Chat-Erweiterung senden. Verwenden Sie die ChatFollowupProvider-API, um Nachfragen vom Typ ChatFollowup zu registrieren.

Der folgende Codeausschnitt zeigt, wie Nachfragen in einer Chat-Erweiterung registriert werden

cat.followupProvider = {
    provideFollowups(result: ICatChatResult, context: vscode.ChatContext, token: vscode.CancellationToken) {
        if (result.metadata.command === 'teach') {
            return [{
                prompt: 'let us play',
                label: vscode.l10n.t('Play with the cat')
            } satisfies vscode.ChatFollowup];
        }
    }
};

5. Teilnehmererkennung implementieren

Um die Nutzung von Chat-Teilnehmern mit natürlicher Sprache zu vereinfachen, können Sie die Teilnehmererkennung implementieren. Die Teilnehmererkennung ist eine Möglichkeit, die Frage des Benutzers automatisch an einen geeigneten Teilnehmer weiterzuleiten, ohne den Teilnehmer in der Eingabeaufforderung explizit erwähnen zu müssen. Wenn der Benutzer beispielsweise fragt: „Wie füge ich meinem Projekt eine Anmeldeseite hinzu?“, wird die Frage automatisch an den @workspace-Teilnehmer weitergeleitet, da dieser Fragen zu seinem Projekt beantworten kann.

VS Code verwendet die Beschreibung und Beispiele des Chat-Teilnehmers, um zu bestimmen, an welchen Teilnehmer eine Chat-Eingabeaufforderung weitergeleitet werden soll. Sie können diese Informationen in der Eigenschaft disambiguation in der Datei package.json der Erweiterung angeben. Die Eigenschaft disambiguation enthält eine Liste von Erkennungskategorien, jede mit einer Beschreibung und Beispielen.

Sie können die Teilnehmererkennung für den gesamten Chat-Teilnehmer, für bestimmte Befehle oder eine Kombination aus beidem definieren.

Der folgende Codeausschnitt zeigt, wie die Teilnehmererkennung auf Teilnehmer-Ebene implementiert wird.

"contributes": {
    "chatParticipants": [
        {
            "id": "chat-sample.cat",
            "fullName": "Cat",
            "name": "cat",
            "description": "Meow! What can I teach you?",

            "disambiguation": [
                {
                    "category": "cat",
                    "description": "The user wants to learn a specific computer science topic in an informal way.",
                    "examples": [
                        "Teach me C++ pointers using metaphors",
                        "Explain to me what is a linked list in a simple way",
                        "Can you explain to me what is a function in programming?"
                    ]
                }
            ]
        }
    ]
}

Ebenso können Sie die Teilnehmererkennung auf Befehlsebene konfigurieren, indem Sie eine disambiguation-Eigenschaft für ein oder mehrere Elemente in der commands-Eigenschaft hinzufügen.

Wenden Sie die folgenden Richtlinien an, um die Genauigkeit der Teilnehmererkennung für Ihre Erweiterung zu verbessern

• Seien Sie spezifisch: Die Beschreibung und die Beispiele sollten so spezifisch wie möglich sein, um Konflikte mit anderen Teilnehmern zu vermeiden. Vermeiden Sie generische Terminologie in den Teilnehmer- und Befehlsinformationen.
• Verwenden Sie Beispiele: Die Beispiele sollten repräsentativ für die Arten von Fragen sein, die für den Teilnehmer geeignet sind. Verwenden Sie Synonyme und Variationen, um eine breite Palette von Benutzeranfragen abzudecken.
• Verwenden Sie natürliche Sprache: Die Beschreibung und die Beispiele sollten in natürlicher Sprache verfasst sein, als ob Sie den Teilnehmer einem Benutzer erklären würden.
• Testen Sie die Erkennung: Testen Sie die Teilnehmererkennung mit einer Variation von Beispielfragen und verifizieren Sie, dass es keine Konflikte mit integrierten Chat-Teilnehmern gibt.

Chat-Nachrichtenverlauf verwenden

Teilnehmer haben Zugriff auf den Nachrichtenverlauf der aktuellen Chatsitzung. Ein Teilnehmer kann nur Nachrichten abrufen, bei denen er erwähnt wurde. Ein history-Element ist entweder ein ChatRequestTurn oder ein ChatResponseTurn. Verwenden Sie beispielsweise den folgenden Codeausschnitt, um alle früheren Anfragen abzurufen, die der Benutzer in der aktuellen Chatsitzung an Ihren Teilnehmer gesendet hat

const previousMessages = context.history.filter(h => h instanceof vscode.ChatRequestTurn);

Der Verlauf wird nicht automatisch in die Eingabeaufforderung aufgenommen; es liegt am Teilnehmer, zu entscheiden, ob er den Verlauf als zusätzlichen Kontext hinzufügen möchte, wenn er Nachrichten an das Sprachmodell übergibt.

Unterstützte Chat-Antwortausgabetypen

Um eine Antwort auf eine Chat-Anfrage zu geben, verwenden Sie den Parameter ChatResponseStream im ChatRequestHandler.

Die folgende Liste zeigt die Ausgabetypen für eine Chat-Antwort in der Chat-Ansicht. Eine Chat-Antwort kann mehrere verschiedene Ausgabetypen kombinieren.

• Markdown

  Rendern Sie ein Fragment von Markdown-Text, einfachem Text oder Bildern. Sie können jede Markdown-Syntax verwenden, die Teil der CommonMark-Spezifikation ist. Verwenden Sie die Methode ChatResponseStream.markdown und geben Sie den Markdown-Text an.

  Beispielcode-Schnipsel

  // Render Markdown text
  stream.markdown('# This is a title \n');
  stream.markdown('This is stylized text that uses _italics_ and **bold**. ');
  stream.markdown('This is a [link](https://visualstudiocode.de).\n\n');
  stream.markdown('![VS Code](https://visualstudiocode.de/assets/favicon.ico)');
  

• Code-Block

  Rendern Sie einen Code-Block, der IntelliSense, Code-Formatierung und interaktive Steuerelemente zum Anwenden des Codes auf den aktiven Editor unterstützt. Um einen Code-Block anzuzeigen, verwenden Sie die Methode ChatResponseStream.markdown und wenden Sie die Markdown-Syntax für Code-Blöcke (mit Backticks) an.

  Beispielcode-Schnipsel

  // Render a code block that enables users to interact with
  stream.markdown('```bash\n');
  stream.markdown('```ls -l\n');
  stream.markdown('```');
  

• Befehls-Link

  Rendern Sie einen Link, der sich im Chat-Antwort im Text befindet und den Benutzer auswählen kann, um einen VS Code-Befehl aufzurufen. Um einen Befehls-Link anzuzeigen, verwenden Sie die Methode ChatResponseStream.markdown und verwenden Sie die Markdown-Syntax für Links [Link-Text](command:commandId), wobei Sie die Befehls-ID in der URL angeben. Der folgende Link öffnet beispielsweise die Befehlspalette: [Command Palette](command:workbench.action.showCommands).

  Um sich vor Befehlsinjektionen zu schützen, wenn Sie den Markdown-Text von einem Dienst laden, müssen Sie ein vscode.MarkdownString-Objekt mit der Eigenschaft isTrusted verwenden, die auf die Liste vertrauenswürdiger VS Code-Befehls-IDs gesetzt ist. Diese Eigenschaft ist erforderlich, damit der Befehls-Link funktioniert. Wenn die Eigenschaft isTrusted nicht gesetzt ist oder ein Befehl nicht aufgeführt ist, funktioniert der Befehls-Link nicht.

  Beispielcode-Schnipsel

  // Use command URIs to link to commands from Markdown
  let markdownCommandString: vscode.MarkdownString = new vscode.MarkdownString(
    `[Use cat names](command:${CAT_NAMES_COMMAND_ID})`
  );
  markdownCommandString.isTrusted = { enabledCommands: [CAT_NAMES_COMMAND_ID] };
  
  stream.markdown(markdownCommandString);
  

  Wenn der Befehl Argumente nimmt, müssen Sie die Argumente zuerst JSON-codieren und dann die JSON-Zeichenkette als URI-Komponente codieren. Fügen Sie dann die codierten Argumente als Abfragezeichenfolge an den Befehls-Link an.

  // Encode the command arguments
  const encodedArgs = encodeURIComponent(JSON.stringify(args));
  
  // Use command URIs with arguments to link to commands from Markdown
  let markdownCommandString: vscode.MarkdownString = new vscode.MarkdownString(
    `[Use cat names](command:${CAT_NAMES_COMMAND_ID}?${encodedArgs})`
  );
  markdownCommandString.isTrusted = { enabledCommands: [CAT_NAMES_COMMAND_ID] };
  
  stream.markdown(markdownCommandString);
  

• Befehls-Schaltfläche

  Rendern Sie eine Schaltfläche, die einen VS Code-Befehl aufruft. Der Befehl kann ein integrierter Befehl sein oder einer, den Sie in Ihrer Erweiterung definieren. Verwenden Sie die Methode ChatResponseStream.button und geben Sie den Schaltflächentext und die Befehls-ID an.

  Beispielcode-Schnipsel

  // Render a button to trigger a VS Code command
  stream.button({
    command: 'my.command',
    title: vscode.l10n.t('Run my command')
  });
  

• Dateistruktur

  Rendern Sie eine Dateistrukturansicht, die es Benutzern ermöglicht, einzelne Dateien in der Vorschau anzuzeigen. Zeigen Sie beispielsweise eine Workspace-Vorschau an, wenn Sie die Erstellung eines neuen Workspaces vorschlagen. Verwenden Sie die Methode ChatResponseStream.filetree und geben Sie ein Array von Dateistrukturelementen und den Basisort (Ordner) der Dateien an.

  Beispielcode-Schnipsel

  // Create a file tree instance
  var tree: vscode.ChatResponseFileTree[] = [
    {
      name: 'myworkspace',
      children: [{ name: 'README' }, { name: 'app.js' }, { name: 'package.json' }]
    }
  ];
  
  // Render the file tree control at a base location
  stream.filetree(tree, baseLocation);
  

• Fortschrittsmeldung

  Rendern Sie eine Fortschrittsmeldung während eines lang andauernden Vorgangs, um dem Benutzer eine Zwischenmeldung zu geben. Berichten Sie beispielsweise über den Abschluss jedes Schritts in einem mehrstufigen Vorgang. Verwenden Sie die Methode ChatResponseStream.progress und geben Sie die Meldung an.

  Beispielcode-Schnipsel

  // Render a progress message
  stream.progress('Connecting to the database.');
  

• Referenz

  Fügen Sie eine Referenz für eine externe URL oder einen Editor-Speicherort in die Referenzliste ein, um anzugeben, welche Informationen Sie als Kontext verwenden. Verwenden Sie die Methode ChatResponseStream.reference und geben Sie den Speicherort der Referenz an.

  Beispielcode-Schnipsel

  const fileUri: vscode.Uri = vscode.Uri.file('/path/to/workspace/app.js'); // On Windows, the path should be in the format of 'c:\\path\\to\\workspace\\app.js'
  const fileRange: vscode.Range = new vscode.Range(0, 0, 3, 0);
  const externalUri: vscode.Uri = vscode.Uri.parse('https://visualstudiocode.de');
  
  // Add a reference to an entire file
  stream.reference(fileUri);
  
  // Add a reference to a specific selection within a file
  stream.reference(new vscode.Location(fileUri, fileRange));
  
  // Add a reference to an external URL
  stream.reference(externalUri);
  

• Inline-Referenz

  Fügen Sie eine Inline-Referenz zu einer URI oder einem Editor-Speicherort hinzu. Verwenden Sie die Methode ChatResponseStream.anchor und geben Sie den Anker-Speicherort und einen optionalen Titel an. Um ein Symbol (z. B. eine Klasse oder Variable) zu referenzieren, würden Sie einen Speicherort in einem Editor verwenden.

  Beispielcode-Schnipsel

  const symbolLocation: vscode.Uri = vscode.Uri.parse('location-to-a-symbol');
  
  // Render an inline anchor to a symbol in the workspace
  stream.anchor(symbolLocation, 'MySymbol');
  

Wichtig: Bilder und Links sind nur verfügbar, wenn sie von einer Domäne stammen, die in der Liste der vertrauenswürdigen Domänen enthalten ist. Weitere Informationen zu Link-Schutz in VS Code.

Tool-Aufrufe implementieren

Um auf eine Benutzeranfrage zu antworten, kann eine Chat-Erweiterung Sprachmodell-Tools aufrufen. Erfahren Sie mehr über Sprachmodell-Tools und den Tool-Calling-Flow.

Sie können Tool-Aufrufe auf zwei Arten implementieren

• Durch die Verwendung der @vscode/chat-extension-utils Bibliothek, um den Prozess des Aufrufens von Tools in einer Chat-Erweiterung zu vereinfachen.
• Durch die Implementierung von Tool-Aufrufen selbst, was Ihnen mehr Kontrolle über den Tool-Calling-Prozess gibt. Zum Beispiel, um zusätzliche Validierungen durchzuführen oder Tool-Antworten auf eine bestimmte Weise zu verarbeiten, bevor sie an die LLM gesendet werden.

Tool-Aufrufe mit der Chat-Erweiterungsbibliothek implementieren

Sie können die @vscode/chat-extension-utils Bibliothek verwenden, um den Prozess des Aufrufens von Tools in einer Chat-Erweiterung zu vereinfachen.

Implementieren Sie Tool-Aufrufe in der Funktion vscode.ChatRequestHandler Ihres Chat-Teilnehmers.

1. Bestimmen Sie die relevanten Tools für den aktuellen Chat-Kontext. Sie können auf alle verfügbaren Tools über vscode.lm.tools zugreifen.

   Der folgende Codeausschnitt zeigt, wie Tools gefiltert werden, um nur diejenigen mit einem bestimmten Tag zu erhalten.

   const tools =
     request.command === 'all'
       ? vscode.lm.tools
       : vscode.lm.tools.filter(tool => tool.tags.includes('chat-tools-sample'));
   

2. Senden Sie die Anfrage und die Tool-Definitionen an die LLM mit sendChatParticipantRequest.

   const libResult = chatUtils.sendChatParticipantRequest(
     request,
     chatContext,
     {
       prompt: 'You are a cat! Answer as a cat.',
       responseStreamOptions: {
         stream,
         references: true,
         responseText: true
       },
       tools
     },
     token
   );
   

   Das Objekt ChatHandlerOptions hat die folgenden Eigenschaften

   • prompt: (optional) Anweisungen für die Eingabeaufforderung des Chat-Teilnehmers.
   • model: (optional) Das zu verwendende Modell für die Anfrage. Wenn nicht angegeben, wird das Modell aus dem Chat-Kontext verwendet.
   • tools: (optional) Die zu berücksichtigenden Tools für die Anfrage.
   • requestJustification: (optional) Eine Zeichenkette, die beschreibt, warum die Anfrage gestellt wird.
   • responseStreamOptions: (optional) Ermöglicht sendChatParticipantRequest das Streamen der Antwort zurück an VS Code. Optional können Sie auch Referenzen und/oder Antworttext aktivieren.

3. Geben Sie das Ergebnis von der LLM zurück. Dies kann Fehlerdetails oder Metadaten für Tool-Aufrufe enthalten.

   return await libResult.result;
   

Der vollständige Quellcode dieses Tool-Calling-Beispiels ist im VS Code Extension Samples-Repository verfügbar.

Tool-Aufrufe selbst implementieren

Für fortgeschrittenere Szenarien können Sie Tool-Aufrufe auch selbst implementieren. Optional können Sie die Bibliothek @vscode/prompt-tsx zum Erstellen von LLM-Prompts verwenden. Durch die eigene Implementierung von Tool-Aufrufen haben Sie mehr Kontrolle über den Tool-Calling-Prozess. Zum Beispiel, um zusätzliche Validierungen durchzuführen oder Tool-Antworten auf eine bestimmte Weise zu verarbeiten, bevor sie an die LLM gesendet werden.

Sehen Sie sich den vollständigen Quellcode für die Implementierung von Tool-Aufrufen mit prompt-tsx im VS Code Extension Samples-Repository an.

Erfolg messen

Wir empfehlen, den Erfolg Ihres Teilnehmers zu messen, indem Sie Telemetrie-Protokolle für Unhelpful-Benutzerfeedbackereignisse und für die Gesamtzahl der von Ihrem Teilnehmer bearbeiteten Anfragen hinzufügen. Eine anfängliche Erfolgsmetrik für den Teilnehmer kann dann definiert werden als: unhelpful_feedback_count / total_requests.

const logger = vscode.env.createTelemetryLogger({
  // telemetry logging implementation goes here
});

cat.onDidReceiveFeedback((feedback: vscode.ChatResultFeedback) => {
  // Log chat result feedback to be able to compute the success metric of the participant
  logger.logUsage('chatResultFeedback', {
    kind: feedback.kind
  });
});

Jede andere Benutzerinteraktion mit Ihrer Chat-Antwort sollte als positive Metrik gemessen werden (z. B. die Auswahl einer Schaltfläche durch den Benutzer, die in einer Chat-Antwort generiert wurde). Die Messung des Erfolgs mit Telemetrie ist bei der Arbeit mit KI entscheidend, da es sich um eine nicht-deterministische Technologie handelt. Führen Sie Experimente durch, messen Sie und verbessern Sie Ihren Teilnehmer iterativ, um eine gute Benutzererfahrung zu gewährleisten.

Richtlinien und Konventionen

Richtlinien

Chat-Teilnehmer sollten keine reinen Frage-Antwort-Bots sein. Seien Sie bei der Erstellung eines Chat-Teilnehmers kreativ und nutzen Sie die vorhandene VS Code-API, um reichhaltige Integrationen in VS Code zu schaffen. Benutzer lieben auch reichhaltige und praktische Interaktionen, wie z. B. Schaltflächen in Ihren Antworten, Menüpunkte, die Benutzer zu Ihrem Teilnehmer im Chat bringen. Denken Sie an reale Szenarien, in denen KI Ihren Benutzern helfen kann.

Es macht nicht für jede Erweiterung Sinn, einen Chat-Teilnehmer beizutragen. Zu viele Teilnehmer im Chat können zu einer schlechten Benutzererfahrung führen. Chat-Teilnehmer sind am besten geeignet, wenn Sie die vollständige Eingabeaufforderung steuern möchten, einschließlich Anweisungen für das Sprachmodell. Sie können die sorgfältig erstellte Copilot-Systemnachricht wiederverwenden und Sie können Kontext zu anderen Teilnehmern beitragen.

Beispielsweise können Spracherweiterungen (wie die C++-Erweiterung) auf vielfältige Weise beitragen

• Stellen Sie Tools bereit, die Sprachdienst-Intelligenz in die Benutzerabfrage einbringen. Die C++-Erweiterung könnte beispielsweise das #cpp-Tool auf den C++-Status des Workspaces abbilden. Dies gibt dem Copilot-Sprachmodell den richtigen C++-Kontext, um die Qualität der Copilot-Antworten für C++ zu verbessern.
• Stellen Sie Smart Actions bereit, die das Sprachmodell verwenden, optional in Kombination mit herkömmlichem Sprachwissen, um eine großartige Benutzererfahrung zu bieten. Beispielsweise könnte C++ bereits eine Smart Action zum „Extrahieren in Methode“ anbieten, die das Sprachmodell verwendet, um einen passenden Standardnamen für die neue Methode zu generieren.

Chat-Erweiterungen sollten explizit die Zustimmung des Benutzers einholen, wenn sie eine kostspielige Operation durchführen oder etwas bearbeiten oder löschen, das nicht rückgängig gemacht werden kann. Um eine großartige Benutzererfahrung zu erzielen, raten wir davon ab, dass Erweiterungen mehrere Chat-Teilnehmer beitragen. Bis zu einem Chat-Teilnehmer pro Erweiterung ist ein einfaches Modell, das in der Benutzeroberfläche gut skaliert.

Namenskonventionen für Chat-Teilnehmer

Wenn Sie sich auf Ihren Chat-Teilnehmer in benutzersichtbaren Elementen wie Eigenschaften, Chat-Antworten oder der Chat-Benutzeroberfläche beziehen, wird empfohlen, nicht den Begriff Teilnehmer zu verwenden, da dies der Name der API ist. Zum Beispiel könnte die @cat-Erweiterung „Cat-Erweiterung für GitHub Copilot“ genannt werden.

Namenskonventionen für Slash-Befehle

Veröffentlichen Ihrer Erweiterung

Sobald Sie Ihre KI-Erweiterung erstellt haben, können Sie Ihre Erweiterung im Visual Studio Marketplace veröffentlichen

• Bevor Sie im VS Marketplace veröffentlichen, empfehlen wir Ihnen, die Microsoft AI Tools and Practices Guidelines zu lesen. Diese Richtlinien bieten Best Practices für die verantwortungsvolle Entwicklung und Nutzung von KI-Technologien.
• Durch die Veröffentlichung im VS Marketplace hält Ihre Erweiterung die GitHub Copilot Extensibility Acceptable Development and Use Policy ein.
• Laden Sie in den Marketplace hoch, wie in Erweiterung veröffentlichen beschrieben.
• Wenn Ihre Erweiterung bereits andere Funktionalitäten als Chat bereitstellt, empfehlen wir, keine Abhängigkeit von GitHub Copilot in der Erweiterungsmanifestdatei einzuführen. Dies stellt sicher, dass Erweiterungsbenutzer, die GitHub Copilot nicht verwenden, die Nicht-Chat-Funktionalität nutzen können, ohne GitHub Copilot installieren zu müssen.

Erweiterung von GitHub Copilot über GitHub Apps

Alternativ ist es möglich, GitHub Copilot zu erweitern, indem Sie eine GitHub-App erstellen, die einen Chat-Teilnehmer in der Chat-Ansicht bereitstellt. Eine GitHub-App wird von einem Dienst unterstützt und funktioniert auf allen GitHub Copilot-Oberflächen, wie github.com, Visual Studio oder VS Code. Auf der anderen Seite haben GitHub-Apps keinen vollständigen Zugriff auf die VS Code-API. Weitere Informationen zur Erweiterung von GitHub Copilot über eine GitHub-App finden Sie in der GitHub-Dokumentation.

Sprachmodell verwenden

Chat-Teilnehmer können das Sprachmodell auf vielfältige Weise nutzen. Einige Teilnehmer nutzen das Sprachmodell nur, um Antworten auf benutzerdefinierte Prompts zu erhalten, z. B. der Beispiel-Chat-Teilnehmer. Andere Teilnehmer sind fortgeschrittener und agieren wie autonome Agenten, die mithilfe des Sprachmodells mehrere Tools aufrufen. Ein Beispiel für einen solchen fortgeschrittenen Teilnehmer ist der integrierte @workspace, der Ihren Workspace kennt und Fragen dazu beantworten kann. Intern wird @workspace von mehreren Tools angetrieben: dem Wissensgraphen von GitHub, kombiniert mit semantischer Suche, lokalen Codeindizes und den Sprachdiensten von VS Code.

Verwandte Inhalte

• Chat-Teilnehmer-API-Referenz
• Sprachmodell-API in Ihrer Erweiterung verwenden
• Sprachmodell-Tool beitragen