文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载Language Model API 是 VS Code 提供给扩展作者的官方接口它让扩展可以直接调用语言模型如 GitHub Copilot 背后的 GPT 系列模型从而在编辑器、聊天、调试等场景中注入 AI 能力。本文以 api/extension-guides/ai/language-model.md 为核心系统讲解从提示词构建、模型选择、请求发送到流式响应解析的完整链路并结合仓库中的 Chat Participant API 指南、prompt-tsx 提示词编排指南 与 Code Tutor 实战教程 展开源码级补充读完你将能独立实现一个具备自然语言理解能力的 AI 扩展。适用场景与完整使用流程Language Model API 允许你通过 API 参考 中的lm命名空间使用语言模型把 AI 驱动的功能与自然语言处理能力集成进 VS Code 扩展。它的典型用途是 Chat 扩展用语言模型解读用户的自然语言请求并生成回答。但它的使用并不局限于聊天场景你完全可以在以下类型的扩展中使用语言扩展例如 Rust 扩展可以用语言模型为重命名操作提供更智能的默认命名建议调试器扩展辅助分析堆栈、生成调试建议命令 与 任务提供方把 AI 能力作为自定义命令或任务的一部分。使用 Language Model API 的过程由三个步骤构成构建语言模型提示词Build the language model prompt——组织给模型的指令与上下文发送语言模型请求Send the language model request——选择合适的模型并提交请求解析响应Interpret the response——处理流式返回的文本输出给用户或触发后续逻辑。构建语言模型提示词与语言模型交互前扩展首先要精心组织提示词prompt提示词既承载这个模型要完成什么任务的宽泛指令也定义用户消息应该如何在上下文中被解读。Language Model API 支持两种消息类型来构建提示词消息类型用途User用户消息提供指令与用户的具体请求Assistant助手消息把之前语言模型的响应历史作为上下文加入提示词注意当前 Language Model API不支持 system 消息。如果你需要设定系统级角色约束请把它写进第一条 User 消息中下文示例正是这么做的。构建提示词有两种方式LanguageModelChatMessage类直接以字符串形式提供一条或多条消息适合刚上手 Language Model API 的开发者vscode/prompt-tsx库用 TSX 语法声明式编排提示词适合对提示词组合有更强控制需求的场景。例如该库可以动态适配不同模型各自的上下文窗口大小。技巧善用 VS Code 丰富的扩展 API 获取最相关的上下文并写入提示词——例如把编辑器当前活动文件的内容包含进去能让模型基于真实代码作答。使用 LanguageModelChatMessage 类Language Model API 提供了LanguageModelChatMessage类来表示和创建聊天消息通过LanguageModelChatMessage.User与LanguageModelChatMessage.Assistant两个静态方法分别创建用户消息与助手消息。下面示例中的第一条消息为提示词提供上下文模型回复时采用的人设这里是一只猫模型生成回复时必须遵守的规则这里要求用猫的比喻以幽默方式讲解计算机科学概念。第二条消息则给出用户的具体请求或指令它决定在第一条消息给定的上下文之上要完成的具体任务const craftedPrompt [ vscode.LanguageModelChatMessage.User(You are a cat! Think carefully and step by step like a cat would. Your job is to explain computer science concepts in the funny manner of a cat, using cat metaphors. Always start your response by stating what concept you are explaining. Always include code samples.), vscode.LanguageModelChatMessage.User(I want to understand recursion) ];消息数组可以包含任意多条消息这正是把多轮对话历史塞进提示词的基础近期的 User/Assistant 轮次按时间顺序排列模型即可读懂上下文。用 prompt-tsx 编排复杂提示词当提示词结构变复杂需要动态拼接对话历史、按优先级裁剪内容以适配上下文窗口时api/extension-guides/ai/prompt-tsx.md 介绍的vscode/prompt-tsx库提供了更工程化的方案。它的核心能力包括基于 TSX 的提示词渲染用组件组合提示词可读性与可维护性更高基于优先级的裁剪priority-based pruning自动裁剪提示词中优先级较低的部分使其适配模型上下文窗口灵活的 token 管理通过flexGrow、flexReserve、flexBasis等属性协同分配 token 预算工具集成与 VS Code 的语言模型工具 API 对接。对话历史的优先级处理是 prompt-tsx 的典型用法。通常建议按如下顺序排列优先级从高到低基础提示词指令当前用户查询最近几轮聊天历史任何支撑性数据放得下的剩余历史。在库中每个 TSX 节点的优先级类似于zIndex数值越大优先级越高。通过定义HistoryMessages与MyPrompt等PromptElement组件配合PrioritizedList辅助组件自动为子节点分配升序或降序优先级即可把历史消息合理地分层融入提示词——较新的对话轮次优先保留较早的历史在需要时最先被裁剪。发送语言模型请求提示词构建完成后进入请求阶段包含两步选择模型与发送请求。选择语言模型selectChatModels使用selectChatModels方法选择要使用的语言模型它返回符合指定条件的模型数组。可以指定以下属性来筛选模型vendor供应商id模型唯一标识family模型家族version版本通过这些属性你可以宽泛匹配某个供应商或家族的所有模型也可以精确选中某个具体 ID 的模型。例如以下代码选择所有Copilot供应商的模型不区分家族与版本const models await vscode.lm.selectChatModels({ vendor: copilot }); // No models available if (models.length 0) { // TODO: handle the case when no models are available }如果没有任何模型匹配指定条件selectChatModels返回空数组扩展必须妥善处理这种情况例如提示用户登录 GitHub Copilot 或选择可用模型。重要Copilot 的语言模型要求用户先同意扩展才能使用它们。同意机制表现为一次身份验证对话框因此selectChatModels应该由用户主动发起的动作如一条命令触发而不应在扩展激活时静默调用。提示当前支持的模型家族包括gpt-4o、gpt-4o-mini、o1、o1-mini、claude-3.5-sonnet。如果不确定该选哪个综合性能与质量推荐gpt-4o针对编辑器内的直接交互场景推荐响应更快的gpt-4o-mini。若你正在实现 Chat 参与者官方强烈建议直接使用 chat request handler 的request对象中传入的模型而不是自行调用selectChatModels——这样扩展会尊重用户在聊天模型下拉框中自行选择的模型。发送请求sendRequest 与错误处理选中模型后调用模型实例上的sendRequest方法发送请求。你需要传入之前构建好的提示词、附加选项示例中为空对象{}以及取消令牌CancellationToken。请求可能失败例如模型不存在、用户未同意使用 Language Model API、配额quota超限等。请使用LanguageModelError区分不同类型的错误try { const [model] await vscode.lm.selectChatModels({ vendor: copilot, family: gpt-4o }); const request model.sendRequest(craftedPrompt, {}, token); } catch (err) { // Making the chat request might fail because // - model does not exist // - user consent not given // - quota limits were exceeded if (err instanceof vscode.LanguageModelError) { console.log(err.message, err.code, err.cause); if (err.cause instanceof Error err.cause.message.includes(off_topic)) { stream.markdown(vscode.l10n.t(I\m sorry, I can only explain computer science concepts.)); } } else { // add other error handling logic throw err; } }注意LanguageModelError的三个关键字段err.message——人类可读的错误描述err.code——机器可读的错误码可用于精确分支err.cause——底层原始错误对象例如包含off_topic标记的拒绝原因模型拒绝回答越界话题可以据此给用户更友好的本地化提示如上面的vscode.l10n.t(...)。完整命令示例把流式响应写回编辑器下面的完整示例注册一个文本编辑器命令它用语言模型把当前活动编辑器里的所有变量名改成有趣的猫名并边生成边流式写入编辑器保证流畅的用户体验vscode.commands.registerTextEditorCommand(cat.namesInEditor, async (textEditor: vscode.TextEditor) { // Replace all variables in active editor with cat names and words const [model] await vscode.lm.selectChatModels({ vendor: copilot, family: gpt-4o }); let chatResponse: vscode.LanguageModelChatResponse | undefined; const text textEditor.document.getText(); const messages [ vscode.LanguageModelChatMessage.User(You are a cat! Think carefully and step by step like a cat would. Your job is to replace all variable names in the following code with funny cat variable names. Be creative. IMPORTANT respond just with code. Do not use markdown!), vscode.LanguageModelChatMessage.User(text) ]; try { chatResponse await model.sendRequest(messages, {}, new vscode.CancellationTokenSource().token); } catch (err) { if (err instanceof vscode.LanguageModelError) { console.log(err.message, err.code, err.cause) } else { throw err; } return; } // Clear the editor content before inserting new content await textEditor.edit(edit { const start new vscode.Position(0, 0); const end new vscode.Position(textEditor.document.lineCount - 1, textEditor.document.lineAt(textEditor.document.lineCount - 1).text.length); edit.delete(new vscode.Range(start, end)); }); try { // Stream the code into the editor as it is coming in from the Language Model for await (const fragment of chatResponse.text) { await textEditor.edit(edit { const lastLine textEditor.document.lineAt(textEditor.document.lineCount - 1); const position new vscode.Position(lastLine.lineNumber, lastLine.text.length); edit.insert(position, fragment); }); } } catch (err) { // async response stream may fail, e.g network interruption or server side error await textEditor.edit(edit { const lastLine textEditor.document.lineAt(textEditor.document.lineCount - 1); const position new vscode.Position(lastLine.lineNumber, lastLine.text.length); edit.insert(position, (Errorerr).message); }); } });这个示例同时演示了三个关键点提示词中的只回复代码、不要用 Markdown指令约束输出格式for await...of chatResponse.text异步迭代流式分片以及发送请求与流式消费响应两处都必须分别做错误处理后者常因网络中断或服务端错误失败。解析语言模型响应发送请求后必须处理语言模型 API 返回的响应。取决于使用场景你可以把响应直接透传给用户也可以解析响应并执行额外逻辑例如上面的示例中把文本插入编辑器。LanguageModelChatResponse是**基于流streaming**的响应这让你能提供平滑的用户体验——例如与 Chat API 结合时持续汇报结果与进度。流式处理过程中也可能出错如网络连接问题务必在代码中加入相应的错误处理。流式响应的消费模式总结如下使用for await (const fragment of chatResponse.text)逐片读取文本分片分片通常很短一个词甚至一个标点所以累积拼接后再按业务规则切分例如等到出现完整 JSON 的收尾}再解析每个textEditor.edit(...)都是一次编辑事务需要基于文档当前末尾位置动态计算插入点流式消费的try/catch与发送请求的try/catch要分开写因为失败时机与原因不同。端到端实战从提示词到编辑器注解api/extension-guides/ai/language-model-tutorial.md 提供了一个完整的端到端实践构建一个Code Tutor代码导师扩展用 Language Model API 生成代码改进建议并通过 VS Code 的 decoration装饰机制以内联注解形式展示在编辑器中用户悬停即可查看完整建议。其实现链路可以归纳为四步正好覆盖本指南的三个核心步骤获取带行号的代码使用registerTextEditorCommand拿到用户当前打开的TextEditor再通过textEditor.visibleRanges[0]获取可视区域的首尾行逐行拼出行号: 代码内容的文本串发送代码与提示词selectChatModels({ vendor: copilot, family: gpt-4o })选中模型把一段精心构造的ANNOTATION_PROMPT角色设定 输出格式约束 few-shot 示例要求模型以{ line: 1, suggestion: ... }形式的 JSON 对象逐条输出建议与带行号代码作为两条 User 消息一起发送流式解析注解在parseChatResponse中累积流式分片每当遇到}就尝试JSON.parse出完整注解并应用 decoration未解析成功则静默跳过继续累积以 decoration 展示createTextEditorDecorationType定义内联样式灰色、截断到 25 字符setDecorations把注解渲染到对应行末尾完整建议通过hoverMessage在悬停时展示。教程还在package.json的contributes中通过menus的editor/title分组把命令挂到编辑器标题栏配合 图标规范 中的$(comment)图标用户一键即可开关注解。这说明 Language Model API 与编辑器 UI 扩展能力可以无缝组合——AI 能力不再是聊天框专属而是可以深度嵌入开发者的日常编辑流。使用注意事项模型可用性没有任何具体模型会被承诺永久支持。在扩展中引用语言模型时请对请求采取防御式策略优雅地处理无法访问某个特定模型的情况——例如模型下架、用户所在地区/账户不可用、未登录 GitHub Copilot 等这些都可能导致selectChatModels返回空数组或sendRequest抛错。选择合适的模型扩展作者可以自行判断哪个模型最适合自己的扩展。官方推荐gpt-4o性能与质量均衡。要获取当前可用的完整模型列表可用如下代码const allModels await vscode.lm.selectChatModels(MODEL_SELECTOR);注意推荐的 GPT-4o 模型有64Ktoken 的上限。selectChatModels返回的模型对象带有maxInputTokens属性可以直接读出该模型的 token 上限。这些上限会随着对扩展使用方式的了解而逐步放宽。速率限制Rate limiting扩展应负责任地使用语言模型并留意速率限制。VS Code 对用户保持透明用户可以看到扩展正在如何使用语言模型、每个扩展发送了多少请求、这些请求如何影响各自的配额。另外不要用 Language Model API 做集成测试——受速率限制影响这类测试不稳定。VS Code 内部使用专用的非生产语言模型进行模拟测试官方正在思考如何为扩展提供可扩展的语言模型测试方案。测试你的扩展Language Model API 的响应是非确定性的完全相同的请求可能得到不同的响应这给测试带来挑战。因此测试策略要区分对待可单元测试的部分构建提示词、解析语言模型响应这两段逻辑是确定性的可以在不调用真实语言模型的情况下进行单元测试不可轻易测试的部分与语言模型本身的交互及响应获取是非确定性的难以稳定测试。官方建议把扩展代码设计成模块化结构让提示词构建 响应解析与模型调用解耦从而对确定性的部分充分做单元测试。例如 Code Tutor 教程中的getVisibleCodeWithLineNumbers、parseChatResponse、applyDecoration都是职责单一、便于单独测试的函数。发布你的扩展创建好 AI 扩展后可以将其发布到 Visual Studio Marketplace。发布前请注意以下几点发布前建议阅读Microsoft AI 工具与实践准则Microsoft AI tools and practices guidelines它提供了负责任地开发与使用 AI 技术的最佳实践通过发布到 Marketplace你的扩展即遵循GitHub Copilot 可扩展性可接受开发与使用政策GitHub Copilot extensibility acceptable development and use policy如果你的扩展除了使用 Language Model API 之外还贡献了其他功能不要在扩展清单中引入对 GitHub Copilot 的扩展依赖。这样不使用 GitHub Copilot 的用户也能正常使用扩展中与语言模型无关的功能而无须安装 GitHub Copilot——当然访问语言模型的代码路径仍要做好相应的错误处理按 发布扩展 中描述的流程上传到 Marketplace。相关文档Language Model API 参考lm命名空间、LanguageModelChat、LanguageModelChatResponse等类型定义构建语言模型提示词prompt-tsx构建 VS Code 聊天扩展Chat Participant API教程用 Language Model API 生成 AI 代码注解AI 可扩展性全景概览语言模型、工具与聊天 API 的选型对比赞分享文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载相关推荐VS Code AI 扩展能力全指南Language Model 工具、MCP 工具、Chat Participant 与 Language Model API 的选择与实现VS Code AI 扩展能力全指南Language Model 工具、MCP 工具、Chat Participant 与 Language Model AP文档教程在 Roo Code 中使用 VS Code Language Model API接入 GitHub Copilot 与其他扩展模型在 Roo Code 中使用 VS Code Language Model API接入 GitHub Copilot 与其他扩展模型 Roo Code 内置了人工智能AI Agent代码智能体开发工具工具调用MCP ClientsVS Code 扩展实战使用 GitHub Copilot Language Model API 构建 Code Tutor 行内代码注释扩展VS Code 扩展实战使用 GitHub Copilot Language Model API 构建 Code Tutor 行内代码注释扩展 本篇文章基于示例工程上一篇解锁虚拟显示扩展全攻略Parsec VDD打造高效多屏工作流下一篇数据自主权的技术突围WechatDecrypt解密工具深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考