Positron 扩展安装与 Posit Assistant 配置指南

与 Cursor/VS Code 的差异、内置扩展策略及 Assistant 生效检查清单

Positron
扩展
Assistant
Windows
工作流
Author

Harness 技术文档

Published

May 23, 2026

1. 核心结论（先读）

Positron 与 Cursor 虽然都基于 Code-OSS，但扩展市场、预装扩展、R/Python 栈、AI 助手均不同：

维度 Cursor Positron
扩展市场 Microsoft VS Code Marketplace 默认 P3M（Posit Public Package Manager），目录与 Open VSX 一致
本机扩展目录 %APPDATA%\Cursor\ %APPDATA%\Positron\（与 Cursor/VS Code 完全隔离）
R 语言 需安装 REditorSupport.r（vscode-R） 内置 R Console / LSP；勿装 vscode-R
Quarto 需安装 quarto.quarto Bootstrapped 预装 quarto.quarto
AI 助手 Cursor 内置 Agent/Chat Posit Assistant（扩展 ID：posit.assistant，新版 Positron Bootstrapped）

因此：在 Cursor 里装好的扩展不会自动出现在 Positron；settings.json 里写了某扩展的配置项，也不等于该扩展已在 Positron 中安装或生效。

Posit Assistant 的配置分两层：

  1. Positron 核心设置（positron.assistant.*）——写在用户 settings.json，控制是否启用 Assistant、开放哪些 Provider。
  2. Posit Assistant 扩展（posit.assistant）——由 Positron 预装或从 P3M/Open VSX 安装；Provider 的 API Key / Base URL 通过命令面板配置，不应提交到 harness 仓库。

2. 扩展从哪来：P3M、Open VSX 与 Cursor Marketplace

2.1 为什么不能直接用 VS Code Marketplace

Microsoft 许可限制：VS Code Marketplace 仅面向官方 VS Code 及其衍生构建。Cursor 与 Positron 均不能合法地默认接入该市场。

  • Cursor：使用 Cursor 自有扩展渠道（兼容 VS Code 扩展格式）。
  • Positron：默认从 P3M 浏览与安装；目录与 Open VSX 相同，由 Posit 基础设施分发（见 Positron Extensions 官方说明）。

若 P3M 上某扩展版本滞后，可临时切换画廊源：

"positron.extensions.gallerySource": "openvsx"

切换后执行 Developer: Reload Window。P3M 与 Open VSX 之间可能存在数小时镜像延迟；若更新列表异常，可尝试切换源后再查（参见 Positron Discussion #13383）。

2.2 离线或受限网络：VSIX 手动安装

在无法访问 P3M/Open VSX 时：

  1. 从 open-vsx.org 下载扩展 .vsix；
  2. 命令面板 → Extensions: Install from VSIX…，或扩展视图右上角 … 菜单。

3. Positron 的三类扩展（安装策略）

flowchart TB
  subgraph gallery [画廊可安装]
    P3M[P3M / Open VSX]
    VSIX[.vsix 手动安装]
  end

  subgraph positron [Positron 预置]
    Builtin["Built-in\n@builtin positron"]
    Bootstrap["Bootstrapped\nposit.assistant / quarto / air …"]
  end

  P3M --> UserExt[用户自行安装的扩展]
  VSIX --> UserExt
  Builtin --> Core[核心 R/Python/Console]
  Bootstrap --> DS[数据科学默认栈]

3.1 Built-in（@builtin）

管理 Positron 核心能力（R/Python 运行时桥接、Console 等），不在 Open VSX 上架，随 Positron 版本更新。扩展视图中搜索 @builtin positron 可查看。

无需、也无法从市场重复安装。

3.2 Bootstrapped（自动预装）

Positron 首次启动时会从 P3M/Open VSX 自动安装一批扩展；行为与用户手动安装类似（可卸载、可自动更新）。与 R / Quarto / Assistant 相关的主要包括：

扩展 ID 用途 Cursor 中是否需单独安装
posit.air-vscode R 语法、补全、Air 格式化 是（vscode-R 替代方案）
quarto.quarto Quarto / .qmd 是
posit.shiny Shiny 应用开发 通常否
posit.assistant Posit Assistant（统一 AI 聊天/补全） N/A（Cursor 自有 AI）
charliermarsh.ruff Python 格式化/lint 视需要
meta.pyrefly Python LSP 视需要

验证是否已安装：扩展视图搜索 @installed posit.assistant 或 posit.assistant。

3.3 禁止或不建议安装（与内置冲突）

扩展 ID 原因
REditorSupport.r Positron 原生 R 栈已替代 vscode-R；并存会导致行为冲突。若 .Rprofile 有为 VS Code 终端写的段落，需加 Sys.getenv("POSITRON") == "" 判断（官方说明）。
ms-python.python Positron 内置 fork 版 Python 扩展；请用内置 Console/Help，勿再装官方 Python 扩展。

4. 与 Cursor settings.json 的扩展依赖对照

本仓库 Cursor 配置 中的设置依赖以下扩展——迁移到 Positron 时应对照下表，不要照搬安装清单：

settings.json 能力 Cursor 依赖扩展 Positron 做法
R 路径 / Rterm / httpgd / LSP REditorSupport.r 使用 positron.r.interpreters.default；不装 vscode-R
Quarto / .Rmd 大纲 quarto.quarto 已 Bootstrapped；保留 files.associations 即可
LaTeX 编译 / PDF / 结构树 James-Yu.latex-workshop 需在 P3M/Open VSX 手动安装（本仓库 settings.json 已预留 latex-workshop.* 键）
AI 聊天 / 补全 Cursor 内置 见下文 Posit Assistant

5. Posit Assistant：扩展 + 设置如何配合才生效

5.1 产品演进（避免配错对象）

Positron 曾试验多种 AI 入口（Positron Assistant、Databot 等）。自 2026.05 起统一为与 RStudio 同款的 Posit Assistant：

  • 扩展 ID：posit.assistant（Bootstrapped，新版 Positron 通常已预装）。
  • 旧扩展/设置（如 positron.positron-assistant、纯 databot.*）属于遗留；仅保留 databot.researchPreviewAcknowledgment 等键不能替代 Posit Assistant 的 Provider 配置。

5.2 生效检查清单（Windows）

按顺序自检：

  1. 扩展存在
    扩展 → 搜索 Posit Assistant 或 @installed posit.assistant。
    若缺失：确认 Positron ≥ 2026.05，或从 P3M 安装 posit.assistant，然后 Developer: Reload Window。

  2. 启用 Assistant（Positron 核心设置）
    用户 settings.json：

    "positron.assistant.enable": true

    修改后 Reload Window。

  3. 至少启用一个 Provider
    默认已开放 Anthropic、OpenAI、GitHub Copilot、Bedrock、Snowflake 等（见官方 Provider 表）。
    Custom Provider（OpenAI 兼容 API，如 MiniMax） 为实验功能，须额外：

    "positron.assistant.provider.customProvider.enable": true

  4. 配置凭据（命令面板，非仓库）
    命令面板 → Positron Assistant: Configure Language Model Providers
    选择 Provider → 填写 API Key、Base URL 等。
    API Key 由 Positron Authentication 扩展托管，通常不会出现在可分享的 settings.json 里。

  5. Provider 不支持 /models 列表时：手动声明模型
    与 OpenAI 兼容但无模型列表端点时，使用 positron.assistant.models.overrides.customProvider（仅结构可入库，无密钥）：

    "positron.assistant.models.overrides.customProvider": [
  {
    "name": "MiniMax M2.5",
    "identifier": "MiniMax-M2.5",
    "maxInputTokens": 128000,
    "maxOutputTokens": 4096
  }
]

  6. 验证 UI
    活动栏应出现 Assistant（机器人）图标；或命令 Chat: Open Chat。
    Console 中 Explain / Fix 在 positron.assistant.enable: false 时会降级为内置 quick chat（见 Positron 2026.05 发行说明）。

5.3 本仓库提供的 Assistant 结构模板

ide/positron/settings-assistant.example.json 给出可分享的配置形状（无 API Key）。请复制到本机 %APPDATA%\Positron\User\settings.json 并与 Positron 工作流设置 合并，再在 Positron 内完成 Provider 登录。

5.4 切勿提交到 Git 的内容

类型 示例
API Key / Token OpenAI、Anthropic、Custom Provider 密钥
Provider 会话 Authentication 扩展写入的 secret storage
本机绝对路径 若出现在 diff 中需脱敏
完整本机 settings.json 归档 -ArchiveToHarness 前须剔除 Assistant 凭据

6. 控制 Bootstrapped 扩展：extensions.allowed

若不需要 Python 栈或某些预装扩展，可在用户设置中禁止安装或激活（参见 VS Code allowed extensions 文档）：

"extensions.allowed": {
  "posit.air-vscode": true,
  "quarto.quarto": true,
  "posit.assistant": true,
  "charliermarsh.ruff": false,
  "meta.pyrefly": false,
  "ms-python.python": false,
  "REditorSupport.r": false,
  "*": true
}

注意：将 posit.assistant 设为 false 会导致 Posit Assistant 无法安装/启用，与 positron.assistant.enable: true 矛盾。

7. 推荐扩展（在 P3M/Open VSX 手动安装）

在 Bootstrapped 栈之外，与本仓库 ide/positron/settings.json 配套的常见扩展：

扩展 ID 用途 说明
James-Yu.latex-workshop LaTeX 编译、PDF、结构树 Cursor 侧同样依赖；Positron 需单独在市场安装
mechatroner.rainbow-csv CSV 高亮 可选
oderwat.indent-rainbow 缩进彩虹线 可选

安装后若设置项无效果：确认扩展在 Positron（非 Cursor）扩展视图中为 Enabled，必要时 Reload Window。

8. 从 Cursor 迁移时的实操顺序

  1. 安装 Positron，完成首次启动（等待 Bootstrapped 扩展装完）。
  2. 确认 未安装 REditorSupport.r、ms-python.python。
  3. 合并 harness/ide/positron/settings.json 到本机 Positron 用户设置（保留 Assistant 段）。
  4. 按 §5.2 检查清单 配置 Posit Assistant。
  5. 在 P3M 安装 LaTeX Workshop（若写 .tex）。
  6. 运行 Distribute-PositronSettings.ps1 做 diff，勿用 -Apply 覆盖含密钥的本机文件。

9. 关联文档与官方链接