Positron 教程6 — 动态文档和应用程序-夜雨聆风

Positron 教程6 — 动态文档和应用程序

写在前面

Positron 是 Posit 公司开发的新一代数据科学 IDE，为 Python 和 R 语言提供了全方位数据科学支持，同时还提供了 AI 辅助功能。本系列推文为 Positron IDE 官方文档的中文笔记，软件可能随时更新，建议配合官方文档一起阅读。

官网教程：https://positron.posit.co/quarto.html

1 Quarto

Quarto 是一个开源的科学和技术出版系统，用于创建结合叙述性文字和可执行代码的可复现文档。

Positron 在几个重要方面增强了您使用 Quarto 的方式：

Quarto 在 Positron 中可以开箱即用。Quarto CLI 捆绑在 Positron 中，Quarto 扩展作为引导扩展包含在内。
语句执行等功能可在 Positron 的控制台中无缝工作，并且 Positron 支持 Quarto 文档的集成渲染和预览。
Positron 通过自定义操作栏提供丰富的 UI，用于预览 Quarto 文档、控制渲染行为以及在源代码模式和可视化模式之间切换。

在 Quarto 文档中了解更多关于 Quarto 和 Positron 入门的信息，或使用 Positron 作为 Quarto 工作工具的详细信息。

注意
Quarto 的可视化编辑器在 Positron 中的支持有限。它非常适合富文本创作，但不支持语句执行和其他语言功能。当您需要这些功能时，请考虑切换到源代码模式，并关注 GitHub 以获取此支持更新的信息。

1.1 R Markdown 支持

Quarto 提供了 Positron 对 R Markdown 的支持；除了 Quarto 提供的内容之外，对 R Markdown 的专门 IDE 支持有限。某些高级 .Rmd 功能（如使用 params）不支持交互式使用。

Positron 的命令面板确实提供了使用 R Markdown 的命令：

R: Render Document With R Markdown：使用 R 包 rmarkdown 渲染 .Rmd 文件，而不是使用 Quarto。此方法支持所有 .Rmd 功能，但不会自动打开渲染输出的预览。
R: New R Markdown from Template：从已安装的 R 包中可用的 R Markdown 模板（例如 GitHub 风格的 markdown 模板或 flexdashboard 模板）创建新的 .Rmd 文件。

1.2 使用 Quarto 扩展

Quarto 扩展作为引导扩展包含在 Positron 中。这意味着它的行为就像您自己安装的一样；当扩展画廊中有新版本可用时，此扩展会自动更新，并且如果需要，可以将其卸载。

1.3 管理 Quarto 安装

Positron 捆绑了一个版本的 Quarto CLI，但您也可以使用自己安装的 Quarto CLI 版本。这通常会自动工作，但您可以通过 quarto.path 设置精确管理要使用的 Quarto。检查底部状态栏以查看当前正在使用的 Quarto 版本。

2 Jupyter Notebooks

2.1 概述

Jupyter Notebooks 提供了一个灵活、交互式的 UI，用于结合代码、文本和可视化。

Positron 在几个关键方面增强了 Jupyter Notebooks：

Notebooks 可以开箱即用。您无需在 Python 或 R 环境中安装任何额外的依赖项。
Notebooks 集成到 IDE 中。您可以在连接窗格中管理数据源，在变量窗格中一目了然地查看数据，使用数据资源管理器深入探索数据，并在帮助窗格中浏览文档。
自动补全和转到定义等语言功能可以在 notebooks 和纯文本文件之间无缝工作。

Notebook 编辑器

Positron 提供了两种用于处理 Jupyter Notebooks 的编辑器：处于测试阶段的 Positron Notebook Editor，以及默认的基于 VS Code 的传统 Notebook 编辑器。

Positron Notebook Editor

Positron Notebook Editor 是为 Positron 专门构建的原生 notebook 体验。它提供了具备 notebook 感知能力的 AI 辅助、集成的数据探索以及改进的数据科学工作流用户体验。查看发布文章了解更多详情。

阅读发布博文，了解我们构建 Positron Notebook Editor 的更多原因。

要启用 Positron Notebook Editor，请参阅设置说明。

传统 Notebook 编辑器

传统 Notebook 编辑器是基于 Code OSS 的默认 notebook 编辑器。如果您熟悉 VS Code 中的 Jupyter Notebooks，那么对这个编辑器会感到熟悉。

2.2 Positron Notebook Editor

注意
Positron Notebook Editor 处于公开测试阶段。我们正在积极努力改进 Positron 中的 Notebook 体验，并希望听到您的反馈！在此 Github 讨论中分享您的想法，或与我们的产品和工程团队安排通话。

Positron Notebook Editor 为 Jupyter（.ipynb）文件提供了熟悉的 notebook 体验。IDE 功能在 notebooks 中可以开箱即用，包括 AI 辅助、数据探索和调试。

2.2.1 主要功能

开箱即用的体验：核心功能无需扩展
改进的用户体验：针对数据科学工作流进行优化
具备 notebook 感知能力的 AI 辅助：AI 理解您的 notebook 上下文、执行历史和执行顺序
集成的数据探索：变量窗格和数据资源管理器无缝工作
调试：开箱即用，无需额外设置
改进的版本控制：控制保存哪些元数据，以获得更好的差异比较和版本控制

2.2.2 启用 Positron Notebook Editor

要使 Positron Notebook Editor 成为默认的 Jupyter Notebook 编辑器，请启用 positron.notebook.enabled 设置。启用后，所有 .ipynb 文件将在 Positron Notebook Editor 中打开，而不是在传统 Notebook Editor 中打开。

2.2.3 快速入门

您可以在 Positron 中像在其他编辑器中一样创建和编辑 .ipynb 文件。要学习如何使用 Positron Notebook Editor，请查看我们的 demo notebook。

Notebook 布局

为获得最佳体验，请使用 Ctrl+Shift+P 打开命令面板并运行 View: Notebook Layout 命令。此布局将 IDE 窗格排列成 notebook 友好的设置，让您可以快速访问变量、图表以及其他数据科学工具，并与 notebook 并排显示。

要了解有关自定义 Positron 界面的更多信息，请阅读布局文档。

设置环境

Positron 为 R 和 Python 捆绑了 Jupyter 内核支持。一旦您为 Positron 配置了 Python 或 R 环境，在使用 notebook 之前无需在环境中安装任何额外的依赖项。

如果计算机上安装的环境在 Positron 中不可用，您可能需要阅读更多关于 Positron 如何发现 Python 安装和 R 安装的内容。

选择 Notebook 内核

当您首次打开 Jupyter Notebook 时，Positron 将根据 notebook 的语言、当前工作区和您的配置自动选择一个解释器。notebook 使用的解释器在 notebook 编辑器操作栏的内核选择器中可见。

注意
我们建议将 notebook 解释器与 IDE 的活动解释器匹配，但它们是独立可控的。请参阅管理解释器了解更多信息。

您可以通过选择 notebook 编辑器操作栏中的 Kernel Selector 为 notebook 选择不同的解释器。Change Kernel… 选项将显示所有已注册解释器的列表。从列表中选择一个解释器。

或者，您可以从命令面板运行 Positron Notebook: Change Kernel… 命令。

2.2.4 版本控制

Positron Notebook Editor 控制保存到 notebook 文件的元数据。这使得 notebooks 对版本控制更友好。默认情况下，单元格输出被保存，但执行计数不被保存。您可以使用下面的保存设置调整此行为。

2.2.5 Positron Assistant 集成

Positron Notebook Editor 与 Positron Assistant 集成，提供具备 notebook 感知能力的 AI 辅助：

上下文感知：Assistant 可以访问有关 notebook 的丰富上下文，包括单元格状态、执行历史、代码和输出（包括图像和表格）
动态建议：Assistant 跟随您的工作并动态建议操作以改进您的 notebook
可操作的编辑：在您的许可下，Assistant 可以直接编辑和运行 notebook 中的单元格
透明性：您可以检查和控制 Assistant 正在使用的特定上下文
协作性：使用“跟随 Assistant”在单元格被编辑时自动滚动和高亮显示单元格

启用 Positron Assistant

要使用集成的 notebook AI 功能，您需要设置 Positron Assistant。请参阅 Positron Assistant 快速入门了解设置说明。为获得最佳体验，我们建议使用 Anthropic 作为模型提供商。

启用后，您将在 notebook 编辑器操作栏中看到 Assistant 特定的操作。

Notebook Assistant 面板

Notebook Assistant 面板提供了一种直接从 notebook 与 Assistant 交互的快捷方式。要打开它，请选择 notebook 编辑器操作栏中的 Assistant 图标按钮。

在面板中，您可以：

查看上下文：查看哪些单元格包含在 Assistant 上下文中
快速操作：运行常见操作，如解释 notebook 内容或修复 notebook 中的错误
生成建议：根据 notebook 的当前状态查看动态生成的建议

从面板中选择一个选项将打开一个新的聊天窗格，其中已附加 notebook 上下文。

幽灵单元格建议（实验性）

幽灵单元格建议使用 AI 在执行单元格后预测您的下一步。当前单元格下方会出现一个幽灵单元格，其中包含您可以接受、编辑或关闭的建议操作。

要启用幽灵单元格建议，请将 positron.assistant.notebook.ghostCellSuggestions.enabled 设置为 true。默认情况下，建议在单元格执行后自动出现。要改为手动触发它们，请禁用 positron.assistant.notebook.ghostCellSuggestions.automatic，然后点击“获取建议”或按 Ctrl+Shift+G。

跟随 Assistant

当 Assistant 正在积极编辑 notebook 中的单元格时，您可能希望观察其进度。选择 notebook 编辑器操作栏中的“跟随 Assistant”使 notebook 在单元格被编辑时自动滚动到这些单元格。这使您可以实时查看更改。

2.2.6 自定义与设置

常规

positron.notebook.enabled：使用 Positron Notebook Editor 作为 .ipynb 文件的默认编辑器
positron.notebook.experimental：启用实验性的 Positron Notebook 功能。实验性功能可能会在未来版本中更改或移除
要设置 notebook 的默认工作目录，请使用 notebook.workingDirectory 设置

保存

notebook.save.outputs：将输出保存到 notebook 文件（默认启用）
notebook.save.executionCounts：将执行计数保存到 notebook 文件，以便对版本控制更友好

内联数据资源管理器

positron.notebook.inlineDataExplorer.enabled：将数据框内联显示为交互式数据网格（默认启用）
positron.notebook.inlineDataExplorer.maxHeight：设置 notebook 和 Quarto 输出中内联数据资源管理器的最大高度（像素），默认 300 像素

Assistant

positron.assistant.notebookSuggestions.model：设置在 notebooks 中生成 AI 建议时使用的模型
positron.assistant.notebook.deletionSentinel.show：删除单元格时显示删除哨兵（默认启用）。禁用时，单元格立即删除，不保留撤销占位符
positron.assistant.notebook.deletionSentinel.timeout：删除哨兵自动消失前的超时时间（毫秒），设为 0 禁用自动消失
positron.assistant.notebook.showDiff：显示 AI 助手对 notebook 单元格编辑的差异视图（默认启用）。禁用时，更改直接应用，无需批准

幽灵单元格建议（实验性）

positron.assistant.notebook.ghostCellSuggestions.enabled：在成功执行单元格后显示 AI 生成的下一步建议。短暂延迟后将出现包含建议下一步操作的幽灵单元格
positron.assistant.notebook.ghostCellSuggestions.automatic：启用时，建议在单元格执行后自动出现。禁用时，会出现一个占位符，您可以通过点击“获取建议”或按 Ctrl+Shift+G 来请求建议
positron.assistant.notebook.ghostCellSuggestions.delay：单元格执行后等待显示幽灵单元格建议的时间（毫秒）
positron.assistant.notebook.ghostCellSuggestions.maxVariables：在幽灵单元格建议上下文中包含的最大会话变量数。变量按相关性排序（DataFrame 和表优先，然后是集合和标量）。设为 0 禁用变量上下文
positron.assistant.notebook.ghostCellSuggestions.model：幽灵单元格建议的模型模式。按顺序尝试模式直到找到匹配项（不区分大小写的部分匹配）。回退到当前聊天会话模型，然后是提供商的模型，最后是第一个可用模型

2.3 传统 Notebook 编辑器

您可以像在其他编辑器中一样，在 Positron 中创建和编辑 .ipynb 文件。

有关使用 Jupyter Notebooks 的一般介绍，请参阅 VS Code Jupyter Notebooks 文档。

设置环境

Positron 为 R 和 Python 捆绑了 Jupyter 内核支持。一旦您为 Positron 配置了 Python 或 R 环境，在使用 notebook 之前无需在环境中安装任何额外的依赖项。

如果计算机上安装的环境在 Positron 中不可用，您可能需要阅读更多关于 Positron 如何发现 Python 安装和 R 安装的内容。

选择 Notebook 内核

您可以通过选择 notebook 编辑器操作栏中的内核选择器按钮，或运行命令面板中的 Notebook: Select Notebook Kernel 命令，为 notebook 选择不同的解释器。

自定义

要设置 notebook 的默认工作目录，请使用 notebook.workingDirectory 设置。

3 开发数据应用程序

Positron 通过 Play 按钮提供了一种简化方法来运行交互式数据应用。您无需从终端运行应用，而是可以通过选择编辑器操作中的 Play 按钮来运行支持的应用。此外，您可以通过 Play 按钮的上下文菜单以调试模式启动支持的应用。

Positron App Launcher button in Editor Actions

3.1 支持的应用框架

目前，Positron 支持以下 Python 应用框架：

Dash
FastAPI
Flask
Gradio
Streamlit
Shiny（通过作为引导扩展包含的 Shiny 扩展）

3.2 运行数据应用

打开支持的应用框架的 .py 文件。
在编辑器操作中，选择 Play。

然后，Positron 会在专用的终端标签页中运行该应用，并在查看器窗格中打开应用的 URL。如果您的应用没有自动在查看器中打开，请检查设置 python.terminal.shellIntegration.enabled 和 terminal.integrated.shellIntegration.enabled 是否已启用。

要停止应用，您可以：

选择查看器窗格工具栏中的中断按钮
选择运行该应用的终端标签页，使用垃圾桶图标删除终端，或按 Ctrl+C 停止进程

3.3 选择应用的打开位置

默认情况下，应用在查看器窗格中打开。positron.runApp.previewMode 设置控制应用的打开位置：

值	行为
`viewer`	在查看器窗格中打开（默认）
`editor`	在编辑器标签页中打开
`external`	在默认的外部浏览器中打开
`none`	不自动打开应用