VSCode Notebook 插件的核心载体是 Notebook API，需注册 NotebookProvider 并实现 resolveNotebookContent、saveNotebook 等方法，返回结构化 NotebookData；必须在 package.json 中声明 "notebooks" 字段，且 cell language 需提前注册。
什么是 VSCode Notebook 插件的核心载体
VSCode 的 Notebook 功能不是靠传统 WebView 或 WebviewPanel 实现的，而是依赖一套专用的 Notebook API：你需要注册一个 NotebookProvider，并实现 resolveNotebookContent、saveNotebook 等关键方法。它不渲染 HTML，而是把 notebook 文件（如 .ipynb）解析为结构化的 NotebookData —— 包含 cells 数组，每个 cell 有 kind（Markup / Code）、source 和可选的 language。
-
NotebookProvider必须在package.json中通过"notebooks"字段声明，否则 VSCode 根本不会加载你的 provider - 不支持直接操作 DOM；cell 渲染由 VSCode 内置编辑器负责，你只提供数据和执行逻辑
- 所有 cell 的 language id 必须提前在
contributes.languages中注册，否则代码 cell 无法高亮或触发语法检查
如何让自定义 Notebook 支持运行单元格
运行能力不是自动附带的，必须显式注册 NotebookKernel 并关联到你的 notebook 类型。VSCode 不会帮你执行代码 —— 你得自己启动进程、通信、返回输出。
- 在
activate阶段调用vscode.notebooks.registerNotebookKernel，传入 kernel 对象，其中executeCell是必填方法 -
executeCell接收cell和notebook，你需要：- 判断
cell.kind === vscode.NotebookCellKind.Code - 提取
cell.source，发给后端（比如子进程、HTTP 服务、WS 连接） - 用
controller.updateNotebookCellOutput返回notebookCellOutputItem（如text/plain、application/json）
- 判断
- 常见错误：忘记调用
controller.clearOutput导致旧输出残留；或返回的 MIME type 不被 VSCode 内置渲染器识别（例如用text/html但没配outputMimeTypes）
为什么保存后打开内容变空或格式错乱
VSCode 默认把 notebook 当作二进制文件处理，如果你的 saveNotebook 方法只是简单写字符串，很可能被当作 UTF-8 BOM 污染或换行符不一致导致解析失败。
-
saveNotebook必须返回Uint8Array，而不是string；推荐用new TextEncoder().encode(jsonString) -
resolveNotebookContent返回的NotebookData中，cells的source字段必须是 string 数组（每行一项），不能是单个字符串（即使带\n） - 如果你用 JSON 序列化 cell 输出（比如
stdout），确保outputItems的mime和data类型匹配；data是Uint8Array，不是 base64 或 string - Windows 下尤其要注意：VSCode 期望换行符为
\n，不是\r\n；用split(/\r?\n/)处理输入，再用.join('\n')组装
调试 Notebook 插件时最常卡住的三个点
Notebook 插件的生命周期比普通插件更隐晦，控制台日志容易丢失，很多行为只有在真实 notebook 文件打开后才触发。
- 启动调试前务必确认：工作区已打开一个匹配
fileNamePattern的文件（如*.mybook），否则resolveNotebookContent根本不会被调用 -
console.log在executeCell里可能不显示——改用vscode.window.showInformationMessage或写入临时文件验证执行流 - 修改
package.json的notebooks配置后，必须完全重启 VSCode（仅重载扩展无效），因为 notebook 类型注册发生在主进程初始化阶段
Notebook 插件的本质是“数据协议 + 执行契约”，不是 UI 开发。多数问题出在数据结构不符合约定，而不是逻辑写错了。
