示例工程【免费下载链接】vscode-extension-samplesSample code illustrating the VS Code extension API.项目地址https://gitcode.com/gh_mirrors/vs/vscode-extension-samples点击查看免费下载本指南围绕 vscode-extension-samples 仓库中的 chat-output-renderer-sample 展开讲解 VS Code 官方提出的proposedChat Output Renderer API 的完整使用方式让扩展向 VS Code 的聊天界面贡献自定义渲染组件由语言模型通过工具tool调用生成这些组件并借助 Webview API 完成渲染。读完本文你将掌握从package.json贡献点声明、工具注册、渲染器注册到 Webview 安全渲染与「模型自修复 Mermaid 标记」完整闭环的实战实现并能在自己的扩展中复用这套模式。一、示例概述Chat Output Renderer API 解决什么问题VS Code 默认的聊天界面只能以文本或少量固定形式展示模型输出。Chat Output Renderer APIproposed API允许扩展为聊天输出贡献自定义渲染组件custom rendered widgets其核心工作链路是语言模型在对话中调用扩展注册的工具Language Model Tool工具返回带自定义 MIME 类型的结构化数据VS Code 依据 MIME 类型匹配扩展注册的输出渲染器渲染器基于 Webview API 将数据渲染成富交互组件本示例为 Mermaid 图表。该 API 还能在渲染历史聊天记录中的旧组件时被再次调用源码注释It can also be invoked when rendering old Mermaid diagrams in the chat history见 src/extension.ts因此聊天记录回放时图表依然可正常显示。本示例选择 Mermaid.js 作为渲染目标直观展示从「模型生成图源码」到「聊天面板内渲染成图」的全过程。二、环境要求与运行方式2.1 环境前置条件按 README.md 的说明运行本示例需要满足VS Code 1.109 或更新版本该版本才开始包含 Chat Output Renderer 相关 API 支持。这一点与 package.json 中的engines: { vscode: ^1.109.0 }相互印证。Node.js 与 npm用于安装依赖和编译 TypeScript。2.2 安装与启动步骤# 1. 进入示例目录 cd chat-output-renderer-sample # 2. 安装依赖 npm install这里有一个容易被忽略的细节npm install触发 package.json 中的postinstall钩子npm run download-api其内部依次执行dts dev下载包含 proposed API 的类型定义和postdownload-api→dts main下载主 API 类型。由于chatOutputRenderer是 proposed API没有这一步骤TypeScript 编译将因缺少类型定义而失败依赖vscode/dts^0.4.0负责完成这项工作。安装完成后在 VS Code 中按F5或点击调试视图中的Run Extension目标即可运行。该调试配置来自 .vscode/launch.jsonpreLaunchTask: npm: watch会先启动编译任务任务定义在 .vscode/tasks.json 中对应tsc -watch -p ./并使用$tsc-watchproblem matcher 捕获编译错误、以isBackground: true作为后台任务运行随后扩展会在一个新的 VS Code 窗口中启动type: extensionHost--extensionDevelopmentPath${workspaceFolder}。三、工程配置声明工具与输出渲染器本示例的扩展清单文件 package.json 展示了两个关键的贡献点这是整个功能「能被 VS Code 识别」的基础。3.1 启用 proposed APIenabledApiProposals: [ chatOutputRenderer ]必须显式声明chatOutputRenderer代码中才能使用vscode.chat.registerChatOutputRenderer以及ExtendedLanguageModelToolResult2.toolResultDetails2等 proposed 类型。3.2 contributes.languageModelTools声明模型可调用的工具示例声明了两个工具package.json字段工具一Mermaid Renderer工具二Mermaid Creatorname/toolReferenceNameextSample_renderMermaidDiagramextSample_createMermaidDiagramdisplayNameMermaid RendererMermaid CreatormodelDescriptionRenders a Mermaid diagram from Mermaid.js markup.Creates a Mermaid diagram from a description and renders for the user.userDescriptionRender a Mermaid.js diagrams from markup.Creates and renders Mermaid.js diagrams.canBeReferencedInPrompttruetrueinputSchema{ markup: string }{ description: string }modelDescription与userDescription分别面向语言模型和用户展示用于决定模型「何时、如何」调用工具inputSchema则是工具的 JSON Schema 参数定义模型会依据它生成调用参数。3.3 contributes.chatOutputRenderers声明自定义输出渲染器chatOutputRenderers: [ { viewType: vscode-samples.mermaid, mimeTypes: [ application/vnd.chat-output-renderer.mermaid ] } ]viewType是渲染器的唯一标识与代码中registerChatOutputRenderer的第一个参数一一对应mimeTypes声明该渲染器处理哪些 MIME 类型的数据当工具结果携带匹配的 MIME 时VS Code 会调用此渲染器。这两组常量在 src/extension.ts 中有明确对应const viewType vscode-samples.mermaid; const mime application/vnd.chat-output-renderer.mermaid;3.4 依赖与编译运行期依赖package.jsonmermaid ^11.12.0图表渲染引擎、jsdom ^26.1.0为 mermaid 在 Node 侧解析提供 DOM 环境、dompurify ^3.3.1HTML 消毒编译配置tsconfig.jsonmodule: commonjs、target: ES2024、strict: true、outDir: out、rootDir: src编译产物输出到out/与package.json的main: ./out/extension.js对应。四、核心实现工具 渲染器的完整闭环示例入口 src/extension.ts 在activate中完成全部注册整体结构清晰注册两个工具 → 注册一个渲染器。4.1 工具一渲染已有的 Mermaid 标记context.subscriptions.push( vscode.lm.registerTool{ markup: string }(extSample_renderMermaidDiagram, { invoke: async (options, token) { let sourceCode options.input.markup; sourceCode await runMermaidMarkupFixLoop(sourceCode, token); return writeMermaidToolOutput(sourceCode); }, }) );该工具接收模型给出的markup字符串先经过「Mermaid 标记修复循环」保证语法尽量合法再调用writeMermaidToolOutput打包输出。工具定义见 src/extension.ts。4.2 工具二根据描述生成 Mermaid 图表context.subscriptions.push( vscode.lm.registerTool{ description: string }(extSample_createMermaidDiagram, { invoke: async (options, token) { const description options.input.description; let sourceCode await generateMermaidDiagram(description, token); if (!sourceCode) { throw new Error(Failed to generate Mermaid diagram from description); } sourceCode await runMermaidMarkupFixLoop(sourceCode, token); return writeMermaidToolOutput(sourceCode); }, }) );该工具接收自然语言描述先让语言模型生成 Mermaid 源码再做修复循环最后输出。两个工具共用同一套「生成 → 校验 → 修复 → 输出」管线体现复用的设计思路。工具定义见 src/extension.ts。4.3 渲染器将二进制数据渲染为 Webviewcontext.subscriptions.push( vscode.chat.registerChatOutputRenderer(viewType, { async renderChatOutput({ value }, chatOutputWebview, _ctx, _token) { const mermaidSource new TextDecoder().decode(value); const mermaidDist vscode.Uri.joinPath(context.extensionUri, node_modules, mermaid, dist); chatOutputWebview.webview.options { enableScripts: true, localResourceRoots: [mermaidDist], }; // ... 拼接 HTML 并注入 mermaid.esm.mjs }, }));关键点逐一拆解实现见 src/extension.tsvalue是二进制数据渲染器收到的value是Uint8Array需要用TextDecoder().decode(value)还原为 Mermaid 源码字符串Webview 资源定位vscode.Uri.joinPath(context.extensionUri, node_modules, mermaid, dist)指向扩展安装目录内 mermaid 的 ESM 产物目录并设置localResourceRoots限定 Webview 可加载的本地资源范围开启脚本enableScripts: true是 Webview 内执行 JavaScript 的前提HTML 内容以pre classmermaid承载源码通过script typemodule以asWebviewUri转换后的 URI 动态importmermaid 的mermaid.esm.mjs并调用mermaid.initialize({ startOnLoad: true })让页面加载完成后自动渲染。4.4 输出打包自定义 MIME 与二进制数据writeMermaidToolOutputsrc/extension.ts是打通「工具 → 渲染器」的关键桥梁function writeMermaidToolOutput(sourceCode: string): vscode.LanguageModelToolResult { const result new vscode.LanguageModelToolResult([ new vscode.LanguageModelTextPart(sourceCode) ]); (result as vscode.ExtendedLanguageModelToolResult2).toolResultDetails2 { mime, value: new TextEncoder().encode(sourceCode), }; return result; }工具结果主体仍是文本供语言模型继续阅读/引用同时通过 proposed 的toolResultDetails2附加mime与二进制value——VS Code 据此将结果路由到对应 MIME 的渲染器。mime常量与package.json中chatOutputRenderers.mimeTypes必须保持一致路由才能命中。五、Mermaid 标记的「自修复循环」让模型输出更可靠语言模型生成的 Mermaid 代码常有语法错误。示例实现了一个最大3 次maxFixAttempts 3见 src/extension.ts的修复循环保证渲染成功率validatemermaid.parse 校验 ├─ 成功 → 直接返回 └─ 失败 → 将源码 错误信息交给语言模型修复 → 重新校验最多 3 轮 最终无论结果如何返回「尽力而为」的源码核心逻辑runMermaidMarkupFixLoopsrc/extension.ts在每一轮都检查token.isCancellationRequested支持用户随时中断。5.1 语法校验在 Node 侧解析 MermaidvalidateMermaidMarkupsrc/extension.ts调用mermaid.parse(sourceCode)判断语法是否合法。由于 mermaid 需要浏览器 DOM 环境示例采用懒加载 JSDOM 打补丁的方式getMermaidInstance见 src/extension.tsconst createMermaidInstance async () { const { window } new JSDOM(); (global as any).window window; (global as any).DOMPurify DOMPurify(window); return import(mermaid); };即用jsdom构造一个空的window挂到global上同时用DOMPurify(window)提供 mermaid 依赖的消毒实现然后动态import(mermaid)。cached ??保证实例只创建一次。5.2 调用语言模型修复语法tryFixingUpMermaidMarkupsrc/extension.ts构造一组对话消息发给语言模型Assistant 消息声明任务根据错误信息修复 Mermaid 源码并要求「在 mermaid 围栏代码块内返回完整源码不加任何注释或解释」User 消息粘贴待修复源码和错误信息原文。随后parseMermaidMarkupFromChatResponsesrc/extension.ts流式收集模型响应校验首行以开头、末行以结尾剥离围栏后返回中间的源码若格式不符则返回undefined调用方回退使用原源码避免模型答非所问破坏已有内容。5.3 从描述生成图表generateMermaidDiagramsrc/extension.ts使用同样的提示词模式要求返回围栏代码块把用户描述转成 Mermaid 源码失败时抛出明确错误。六、语言模型选择策略getPreferredLmsrc/extension.ts按优先级选择可用的聊天模型return (await vscode.lm.selectChatModels({ family: gpt-4o-mini })).at(0) ?? (await vscode.lm.selectChatModels({ family: gpt-4o })).at(0) ?? (await vscode.lm.selectChatModels({})).at(0);即优先gpt-4o-mini成本低、速度快适合修复/生成这类轻量任务退而求其次选gpt-4o最后退回任意可用模型。需要说明该选择策略依赖用户 VS Code 环境中实际可用的语言模型供应商与模型系列不同环境下可用模型会有差异属于示例的合理默认而非硬性约束。若找不到可用模型修复流程会打印警告并返回原源码生成流程则直接抛错。七、安全与健壮性Webview 渲染的底线在聊天界面执行第三方代码模型生成的 Mermaid 源码存在注入风险示例在多处做了防护HTML 实体转义escapeHtmlTextsrc/extension.ts对 逐一转义防止 Mermaid 源码被当作 HTML 解析注入脚本块转义escapeForScriptBlocksrc/extension.ts对反斜杠、引号、回车换行及/script进行转义防止源码闭合 script 标签逃逸CSP 策略Webview HTML 中显式声明default-src none; script-src ${cspSource} nonce-${nonce}; style-src self unsafe-inline——只允许来自cspSource且带 nonce 的脚本杜绝未知来源脚本执行nonce 随机数getNoncesrc/extension.ts生成 64 位随机字符串脚本标签通过nonce${nonce}与 CSP 配合形成一次性执行许可localResourceRoots 白名单Webview 只能访问扩展内node_modules/mermaid/dist下的资源缩小了本地文件暴露面。健壮性方面所有涉及模型请求的异步流程都贯穿CancellationToken检查token.isCancellationRequested一旦用户中断立即抛出Operation cancelled避免悬挂请求。八、把这套模式迁移到自己的扩展以本示例为模板接入自定义聊天组件只需四步改常量替换 src/extension.ts 中的viewType与mime为你的命名空间如my-ext.chart/application/vnd.my-ext.chart改声明在 package.json 的contributes.chatOutputRenderers同步viewType/mimeTypes并按需补充languageModelTools中的工具定义与inputSchema改渲染逻辑在renderChatOutput中解码value、配置webview.options、注入你的前端资源可参考localResourceRoots与asWebviewUri的用法保安全底线保留 CSP nonce HTML 转义三板斧尤其是渲染模型生成的用户内容时。九、总结chat-output-renderer-sample 完整展示了 VS Code Chat Output Renderer API 从声明、注册到渲染的整条链路package.json贡献点声明 MIME 与 viewTypevscode.lm.registerTool提供模型可调用的工具toolResultDetails2携带自定义 MIME 的二进制数据完成路由vscode.chat.registerChatOutputRenderer基于 Webview 完成最终渲染。示例在工程细节上同样值得借鉴——JSDOM 打补丁实现 Node 侧 Mermaid 解析、基于语言模型的三次自修复循环、CSPnonce转义的安全防线以及贯穿始终的取消令牌处理。结合 chat-output-renderer-sample/src/extension.ts 与 chat-output-renderer-sample/package.json 对照阅读即可在自己的扩展中落地同样能力为 VS Code 聊天界面定制任意类型的富交互组件。赞分享示例工程【免费下载链接】vscode-extension-samplesSample code illustrating the VS Code extension API.项目地址https://gitcode.com/gh_mirrors/vs/vscode-extension-samples点击查看免费下载相关推荐Panasonic S5 RAW偏色darktable加载相机配置文件一步还原Panasonic S5 RAW偏色darktable加载相机配置文件一步还原 周日晚上把S5拍的一卷片子导入电脑缩略图一排看过去肤色泛绿、天空发灰相机屏示例工程CopilotKit Headless Chat 完整演示深度解析手写 React 聊天界面与全量渲染 Hook 面CopilotKit Headless Chat 完整演示深度解析手写 React 聊天界面与全量渲染 Hook 面 导读 headless complete人工智能AI AgentAgent 框架前端后端A2UI Lit Renderer 深度指南基于 Lit Web Components 的 Agent 声明式界面渲染架构与自定义组件实践A2UI Lit Renderer 深度指南基于 Lit Web Components 的 Agent 声明式界面渲染架构与自定义组件实践 本篇指南围绕 A2人工智能AI AgentAI 应用前端UI组件上一篇Vant Rate 评分组件完全指南从基础用法到源码级交互原理下一篇Cilium 实战用 cilium-dbg fqdn cache list 检视 FQDN 代理 DNS 缓存创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考