在 VS Code 中尝试

聊天扩展

Visual Studio Code 的 Copilot Chat 架构使扩展作者能够与 VS Code 中的聊天体验集成。聊天扩展是使用 Chat extension API 并贡献一个*聊天参与者*的 VS Code 扩展。聊天参与者是在特定领域内回答用户查询的领域专家。

用户可以通过在聊天视图中使用 @ 符号来引用提问模式中的聊天参与者。

此外,你还可以为聊天体验贡献一个语言模型工具。语言模型工具执行特定任务,可以在代理模式中自动调用,或者在提问模式编辑模式中通过使用 # 手动引用。

概述

聊天参与者的目标是使用户能够使用自然语言提示扩展,并提供特定领域的答案作为回应。

当用户在其聊天提示中显式提及 @participant 时,该提示将被转发到贡献该特定聊天参与者的扩展。然后,参与者使用 ResponseStream 响应请求。为了提供流畅的用户体验,Chat API 基于流式处理。聊天响应可以包含丰富内容,例如 Markdown、文件树、命令按钮等。获取有关支持的响应输出类型的更多信息。

聊天参与者可以使用不同的方法来处理用户查询

  • 使用 AI 解释请求并生成响应,例如通过使用语言模型 API
  • 将用户请求转发到后端服务,由其处理请求并返回响应。
  • 使用程序化逻辑和本地资源生成响应。

为了帮助用户进一步进行对话,参与者可以为每个响应提供*后续提问*。后续提问是聊天用户界面中显示的建议,可能会为用户提供有关聊天扩展功能的灵感。

参与者还可以贡献*命令*,这是常用用户意图的简写表示法,并由 / 符号指示。然后,扩展可以使用该命令相应地提示语言模型。例如,/explain@workspace 参与者的一个命令,对应于语言模型应解释某些代码的意图。

使用语言模型

聊天参与者可以通过多种方式使用语言模型。一些参与者仅使用语言模型来获取对自定义提示的回答,例如示例聊天参与者。其他参与者则更高级,并像自主代理一样,在语言模型的帮助下调用多个工具。此类高级参与者的一个例子是内置的 @workspace,它了解你的工作区并可以回答相关问题。在内部,@workspace 由多种工具提供支持:GitHub 的知识图谱,结合语义搜索、本地代码索引以及 VS Code 的语言服务。

通过 GitHub Apps 扩展 GitHub Copilot

此外,可以通过创建 GitHub App 来扩展 GitHub Copilot,该 App 在聊天视图中贡献一个聊天参与者。GitHub App 由服务支持,并在所有 GitHub Copilot 界面(例如 github.com、Visual Studio 或 VS Code)上工作。另一方面,GitHub App 无法完全访问 VS Code API。要了解如何通过 GitHub App 扩展 GitHub Copilot,请参阅GitHub 文档

聊天用户体验的组成部分

以下截图显示了示例扩展在 Visual Studio Code 聊天体验中的不同聊天概念。

Chat concepts explanation

  1. 使用 @ 语法调用 @cat 聊天参与者
  2. 使用 / 语法调用 /teach 命令
  3. 用户提供的查询,也称为用户提示
  4. 指示 Copilot 正在使用 @cat 聊天参与者的图标和参与者 fullName
  5. @cat 提供的 Markdown 响应
  6. Markdown 响应中包含的代码片段
  7. @cat 响应中包含的按钮,该按钮调用 VS Code 命令
  8. 聊天参与者提供的建议后续提问
  9. 带有聊天参与者 description 属性提供的占位符文本的聊天输入字段

开发聊天扩展

聊天扩展是将聊天参与者贡献到 聊天视图的扩展。

实现聊天扩展所需的最低功能是

  • 注册聊天参与者,让用户可以使用 VS Code 聊天视图中的 @ 符号调用它。
  • 定义请求处理程序,用于解释用户问题并在聊天视图中返回响应。

你可以通过以下可选功能进一步扩展聊天扩展的功能

  • 注册聊天命令,为用户提供常用问题的简写表示法
  • 定义建议的后续提问,帮助用户继续对话

作为开发聊天扩展的起点,你可以参考我们的聊天扩展示例。此示例实现了一个简单的猫咪导师,可以使用猫咪的比喻解释计算机科学主题。

Diagram showing how extension can contribute to chat

注册聊天扩展

创建聊天扩展的第一步是在你的 package.json 中注册它,提供唯一的 idnamedescription

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

然后,用户可以使用 @ 符号和你提供的 name 在聊天视图中引用聊天参与者。fullName 显示在你的参与者响应的标题区域。description 用作聊天输入字段中的占位符文本。

isSticky 属性控制聊天参与者是否是持久的,这意味着用户开始与参与者交互后,参与者名称会自动前置到聊天输入字段中。

我们建议使用小写 name,并对 fullName 使用首字母大写,以与现有聊天参与者保持一致。获取有关聊天参与者命名约定的更多信息。

注意

某些参与者名称是保留的,如果你使用保留名称,VS Code 将显示你的参与者的完全限定名称(包括扩展 ID)。

必须在 package.json 中提前注册参与者和命令,以便 VS Code 可以在适当的时候激活你的扩展,而不是在其需要之前。

注册后,你的扩展只需使用 vscode.chat.createChatParticipant 创建参与者即可。创建参与者时,你需要提供你在 package.json 中定义的 ID,以及一个请求处理程序

以下代码片段展示了如何创建 @cat 聊天参与者(在你的 package.json 中注册后)

export function activate(context: vscode.ExtensionContext) {
  // Register the chat participant and its request handler
  const cat = vscode.chat.createChatParticipant('chat-sample.cat', handler);

  // Optionally, set some properties for @cat
  cat.iconPath = vscode.Uri.joinPath(context.extensionUri, 'cat.jpeg');

  // Add the chat request handler here
}

注册并创建聊天参与者后,现在需要实现请求处理程序来处理用户的请求。

实现请求处理程序

请求处理程序负责处理 VS Code 聊天视图中的用户聊天请求。每次用户在聊天输入字段中输入提示时,都会调用聊天请求处理程序。以下是实现聊天请求处理程序的典型步骤

  1. 定义请求处理程序
  2. 确定用户请求的意图
  3. 执行逻辑以回答用户问题
  4. 返回响应给用户

定义请求处理程序

你在扩展的 activate 函数内部定义请求处理程序 (vscode.ChatRequestHandler)。

以下代码片段展示了如何定义请求处理程序

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
};

确定请求意图

要确定用户请求的意图,你可以引用 vscode.ChatRequest 参数来访问用户的提示、命令和聊天位置。或者,你可以利用语言模型来确定用户的意图,而不是使用传统逻辑。作为 request 对象的一部分,你会获得用户在聊天模型下拉列表中选择的语言模型实例。了解如何在你的扩展中使用语言模型 API

以下代码片段展示了首先使用命令,然后使用用户提示来确定用户意图的基本结构

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
  }
};

处理请求

接下来,你需要实现处理用户请求的实际逻辑。通常,聊天扩展使用 request.model 语言模型实例来处理请求。在这种情况下,你可以调整语言模型提示以匹配用户的意图。或者,你可以通过调用后端服务、使用传统编程逻辑或结合所有这些选项来实现扩展逻辑。例如,你可以调用网络搜索来收集额外信息,然后将其作为上下文提供给语言模型。

在处理当前请求时,你可能希望引用之前的聊天消息。例如,如果之前的响应返回了 C# 代码片段,用户当前的请求可能是“用 Python 提供代码”。了解如何使用聊天消息历史记录

如果你想根据聊天输入的位置以不同方式处理请求,可以使用 vscode.ChatRequestlocation 属性。例如,如果用户从终端内联聊天发送请求,你可能会查找 shell 命令。而如果用户使用聊天视图,则可以返回更详细的响应。

返回聊天响应

处理完请求后,你必须在聊天视图中向用户返回响应。聊天扩展可以使用流式传输来响应用户查询。响应可以包含不同的内容类型:markdown、图像、引用、进度、按钮和文件树。例如,生成此响应

Response from the cat extension that includes code, markdown and a button

扩展可以使用响应流的方式如下

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: []
});

获取有关支持的聊天响应输出类型的更多信息。

实际上,扩展通常会向语言模型发送请求。一旦从语言模型获得响应,它们可能会进一步处理,并决定是否应将任何内容流回给用户。VS Code Chat API 基于流式传输,并与流式语言模型 API 兼容。这使得扩展能够持续报告进度和结果,旨在提供流畅的用户体验。了解如何使用语言模型 API

使用聊天消息历史记录

参与者可以访问当前聊天会话的消息历史记录。参与者只能访问其中被提及的消息。history 项是 ChatRequestTurnChatResponseTurn。例如,使用以下代码片段检索用户在当前聊天会话中发送给你的参与者的所有先前请求

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

历史记录不会自动包含在提示中,由参与者决定是否在将消息传递给语言模型时添加历史记录作为额外上下文。

注册命令

聊天参与者可以贡献命令,这些命令是扩展提供的特定功能的快捷方式。用户可以使用 / 语法在聊天中引用命令,例如 /explain

回答问题时的任务之一是确定用户意图。例如,VS Code 可以推断 Create a new workspace with Node.js Express Pug TypeScript 意味着你想要一个新项目,但 @workspace /new Node.js Express Pug TypeScript 更清晰、更简洁,并节省打字时间。如果你在聊天输入字段中输入 /,VS Code 会显示已注册命令及其描述的列表。

List of commands in chat for @workspace

聊天参与者可以通过在 package.json 中添加命令及其描述来贡献命令

"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"
                }
            ]
        }
    ]
}

获取有关斜杠命令命名约定的更多信息。

注册后续提问

每次聊天请求后,VS Code 会调用后续提问提供程序来获取建议的后续问题以显示给用户。然后用户可以选择后续问题,并立即将其发送到聊天扩展。后续问题可以为用户提供灵感,以进一步进行对话,或发现聊天扩展的更多功能。

以下代码片段展示了如何在聊天扩展中注册后续提问

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

后续提问应写成问题或方向,而不仅仅是简洁的命令。

实现参与者检测

为了更容易使用自然语言与聊天参与者交互,你可以实现参与者检测。参与者检测是一种将用户问题自动路由到合适的参与者的方式,而无需在提示中显式提及参与者。例如,如果用户问“我如何向我的项目添加登录页面?”,该问题将自动路由到 @workspace 参与者,因为它可以回答有关用户项目的问题。

VS Code 使用聊天参与者描述和示例来确定将聊天提示路由到哪个参与者。你可以在扩展的 package.json 文件中的 disambiguation 属性中指定此信息。disambiguation 属性包含一个检测类别列表,每个类别都有一个描述和示例。

属性 描述 示例
category 检测类别。如果参与者服务于不同的目的,你可以为每个目的设置一个类别。
  • cat
  • workspace_questions
  • web_questions
description 适合此参与者的各类问题的详细描述。
  • 用户想以非正式的方式学习一个特定的计算机科学主题。
  • 用户只是想放松一下,看看猫玩耍。
examples 具有代表性的示例问题列表。
  • 教我使用比喻理解 C++ 指针
  • 用简单的方式给我解释什么是链表
  • 你能给我看看一只猫玩激光笔吗?

你可以为整个聊天参与者、特定命令或两者结合定义参与者检测。

以下代码片段展示了如何在参与者级别实现参与者检测。

"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?"
                    ]
                }
            ]
        }
    ]
}

类似地,你也可以通过为 commands 属性中的一个或多个项添加 disambiguation 属性来在命令级别配置参与者检测。

应用以下指南来提高你的扩展的参与者检测准确性

  • 具体:描述和示例应尽可能具体,以避免与其他参与者冲突。避免在参与者和命令信息中使用通用术语。
  • 使用示例:示例应具有代表性,反映适合该参与者的问题类型。使用同义词和变体来涵盖广泛的用户查询。
  • 使用自然语言:描述和示例应使用自然语言书写,就像你在向用户解释该参与者一样。
  • 测试检测:使用不同的示例问题测试参与者检测,并验证与内置聊天参与者没有冲突。
注意

内置聊天参与者在参与者检测中具有优先权。例如,一个操作工作区文件的聊天参与者可能与内置的 @workspace 参与者冲突。

支持的聊天响应输出类型

要返回聊天请求的响应,你可以使用 ChatResponseStream 参数,它位于 ChatRequestHandler 上。

以下列表提供了聊天视图中聊天响应的输出类型。聊天响应可以结合多种不同的输出类型。

  • Markdown

    渲染 Markdown 文本片段,包括简单文本或图像。你可以使用CommonMark 规范中的任何 Markdown 语法。使用 ChatResponseStream.markdown 方法并提供 Markdown 文本。

    示例代码片段

    // 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://vscode.js.cn).\n\n');
    stream.markdown('![VS Code](https://vscode.js.cn/assets/favicon.ico)');
    
  • 代码块

    渲染支持 IntelliSense、代码格式化和交互式控件的代码块,以便将代码应用到活动编辑器。要显示代码块,使用 ChatResponseStream.markdown 方法并应用代码块的 Markdown 语法(使用反引号)。

    示例代码片段

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

    在聊天响应中渲染内联链接,用户可以选择该链接来调用 VS Code 命令。要显示命令链接,使用 ChatResponseStream.markdown 方法并使用链接的 Markdown 语法 [链接文本](command:commandId),其中你在 URL 中提供命令 ID。例如,以下链接打开命令面板:[Command Palette](command:workbench.action.showCommands)

    为了防止从服务加载 Markdown 文本时发生命令注入,你必须使用一个 vscode.MarkdownString 对象,并将其 isTrusted 属性设置为受信任的 VS Code 命令 ID 列表。启用命令链接需要此属性。如果未设置 isTrusted 属性或未列出命令,则命令链接将不起作用。

    示例代码片段

    // 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);
    

    如果命令带有参数,你需要先将参数进行 JSON 编码,然后将 JSON 字符串编码为 URI 组件。然后将编码后的参数作为查询字符串附加到命令链接。

    // 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);
    
  • 命令按钮

    渲染一个调用 VS Code 命令的按钮。该命令可以是内置命令,也可以是你自己在扩展中定义的命令。使用 ChatResponseStream.button 方法并提供按钮文本和命令 ID。

    示例代码片段

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

    渲染一个文件树控件,让用户可以预览单个文件。例如,在提议创建新工作区时显示工作区预览。使用 ChatResponseStream.filetree 方法并提供文件树元素数组和文件的基本位置(文件夹)。

    示例代码片段

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

    在长时间运行的操作期间渲染进度消息,为用户提供中间反馈。例如,报告多步操作中每个步骤的完成情况。使用 ChatResponseStream.progress 方法并提供消息。

    示例代码片段

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

    在引用列表中添加外部 URL 或编辑器位置的引用,以指示你使用哪些信息作为上下文。使用 ChatResponseStream.reference 方法并提供引用位置。

    示例代码片段

    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://vscode.js.cn');
    
    // 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);
    
  • 内联引用

    添加指向 URI 或编辑器位置的内联引用。使用 ChatResponseStream.anchor 方法并提供锚点位置和可选标题。要引用符号(例如,类或变量),你将使用编辑器中的位置。

    示例代码片段

    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');
    

重要:图像和链接仅在它们源自受信任域名列表中的域时可用。获取有关 VS Code 中的链接保护 的更多信息。

实现工具调用

为了响应用户请求,聊天扩展可以调用语言模型工具。了解更多关于语言模型工具工具调用流程的信息。

你可以通过两种方式实现工具调用

  • 通过使用@vscode/chat-extension-utils来简化在聊天扩展中调用工具的过程。
  • 通过自行实现工具调用,这让你对工具调用过程有更多控制权。例如,在将工具响应发送到 LLM 之前执行额外的验证或以特定方式处理工具响应。

使用聊天扩展库实现工具调用

你可以使用@vscode/chat-extension-utils来简化在聊天扩展中调用工具的过程。

在你的聊天参与者vscode.ChatRequestHandler 函数中实现工具调用。

  1. 确定当前聊天上下文的相关工具。你可以使用 vscode.lm.tools 访问所有可用工具。

    以下代码片段展示了如何过滤工具,仅保留具有特定标签的工具。

    const tools =
      request.command === 'all'
        ? vscode.lm.tools
        : vscode.lm.tools.filter(tool => tool.tags.includes('chat-tools-sample'));
    
  2. 使用 sendChatParticipantRequest 将请求和工具定义发送给 LLM。

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

    ChatHandlerOptions 对象具有以下属性

    • prompt:(可选)聊天参与者提示的指令。
    • model:(可选)用于请求的模型。如果未指定,则使用聊天上下文中的模型。
    • tools:(可选)考虑用于请求的工具列表。
    • requestJustification:(可选)描述发起请求原因的字符串。
    • responseStreamOptions:(可选)启用 sendChatParticipantRequest 将响应流回 VS Code。或者,你也可以启用引用和/或响应文本。
  3. 返回 LLM 的结果。这可能包含错误详细信息或工具调用元数据。

    return await libResult.result;
    

工具调用示例的完整源代码可在 VS Code 扩展示例仓库中找到。

自行实现工具调用

对于更高级的场景,你也可以自行实现工具调用。或者,你可以使用 @vscode/prompt-tsx 库来制作 LLM 提示。通过自行实现工具调用,你对工具调用过程有更多控制权。例如,在将工具响应发送到 LLM 之前执行额外的验证或以特定方式处理工具响应。

在 VS Code 扩展示例仓库中查看使用 prompt-tsx 实现工具调用的完整源代码。

衡量成功

我们建议你通过为 Unhelpful 用户反馈事件和你的参与者处理的总请求数添加遥测日志来衡量你的参与者的成功。然后可以将初始参与者成功指标定义为: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
  });
});

与你的聊天响应的任何其他用户交互都应视为积极指标(例如,用户选择在聊天响应中生成的按钮)。在使用 AI 时,通过遥测衡量成功至关重要,因为这是一种非确定性技术。运行实验、衡量并迭代改进你的参与者,以确保良好的用户体验。

命名限制与约定

聊天参与者命名约定

属性 描述 命名指南
id 聊天参与者的全局唯一标识符
  • 字符串值
  • 使用扩展名称作为前缀,后跟你的扩展的唯一 ID
  • 示例:chat-sample.cat, code-visualizer.code-visualizer-participant
name 聊天参与者的名称,用户通过 @ 符号引用
  • 由字母数字字符、下划线和连字符组成的字符串值
  • 建议仅使用小写以确保与现有聊天参与者的一致性
  • 通过引用你的公司名称或其功能,确保参与者的目的从其名称中清晰可见
  • 某些参与者名称是保留的。如果你使用保留名称,将显示完全限定名称,包括扩展 ID
  • 示例:vscode, terminal, code-visualizer
fullName (可选)参与者的全名,显示为来自参与者的响应标签
  • 字符串值
  • 建议使用首字母大写
  • 为你的参与者使用你的公司名称、品牌名称或用户友好的名称
  • 示例:GitHub Copilot, VS Code, Math Tutor
description (可选)对聊天参与者功能的简短描述,显示为聊天输入字段或参与者列表中的占位符文本
  • 字符串值
  • 建议使用句子大小写,末尾不带标点符号
  • 保持描述简短以避免水平滚动
  • 示例:询问有关 VS Code 的问题, 为你的代码生成 UML 图

在任何面向用户的元素中提及你的聊天参与者时,例如属性、聊天响应或聊天用户界面,建议不要使用术语 *参与者*,因为它是 API 的名称。例如,@cat 扩展可以称为“面向 GitHub Copilot 的猫咪扩展”。

斜杠命令命名约定

属性 描述 命名指南
name 斜杠命令的名称,用户通过 / 符号引用
  • 字符串值
  • 建议使用小驼峰命名法,以与现有斜杠命令保持一致
  • 确保命令的用途从其名称中清晰可见
  • 示例:fix, explain, runCommand
description (可选)对斜杠命令功能的简短描述,显示为聊天输入字段或参与者和命令列表中的占位符文本
  • 字符串值
  • 建议使用句子大小写,末尾不带标点符号
  • 保持描述简短以避免水平滚动
  • 示例:在 VS Code 中搜索并执行命令, 为选定的代码生成单元测试

指南

聊天参与者不应仅仅是问答机器人。在构建聊天参与者时,要有创造力,并使用现有的 VS Code API 在 VS Code 中创建丰富的集成。用户也喜欢丰富且便捷的交互,例如响应中的按钮,或引导用户到聊天中你的参与者的菜单项。思考人工智能可以帮助用户的现实生活场景。

并非所有扩展都适合贡献聊天参与者。聊天中存在过多参与者可能会导致糟糕的用户体验。当你想控制完整的提示(包括给语言模型的指令)时,聊天参与者是最佳选择。你可以重用精心设计的 Copilot 系统消息,并且可以向其他参与者贡献上下文。

例如,语言扩展(例如 C++ 扩展)可以通过多种其他方式贡献功能

  • 贡献将语言服务智能带入用户查询的工具。例如,C++ 扩展可以将 #cpp 工具解析为工作区的 C++ 状态。这为 Copilot 语言模型提供了正确的 C++ 上下文,从而提高了 Copilot 对 C++ 问题的回答质量。
  • 贡献使用语言模型的智能操作,可选择与传统语言服务知识结合使用,以提供出色的用户体验。例如,C++ 可能已经提供了一个“提取到方法”智能操作,该操作使用语言模型为新方法生成一个合适的默认名称。

如果聊天扩展即将执行耗时操作或编辑或删除无法撤消的内容,则应明确征求用户同意。为了提供良好的用户体验,我们不鼓励扩展贡献多个聊天参与者。每个扩展最多一个聊天参与者是一个简单的模型,在 UI 中具有良好的可伸缩性。

发布你的扩展

创建 AI 扩展后,你可以将扩展发布到 Visual Studio Marketplace

  • 在发布到 VS Marketplace 之前,我们建议你阅读Microsoft AI 工具和实践指南。这些指南提供了负责任地开发和使用 AI 技术的最佳实践。
  • 通过发布到 VS Marketplace,你的扩展将遵守GitHub Copilot 扩展性可接受开发和使用政策
  • 按照发布扩展中所述上传到 Marketplace。
  • 如果你的扩展已经贡献了除聊天之外的功能,我们建议你不要在扩展清单中引入对 GitHub Copilot 的扩展依赖。这确保了不使用 GitHub Copilot 的扩展用户无需安装 GitHub Copilot 即可使用非聊天功能。