Positron IDE 的 settings 配置方案

settings.json 仓库备份、分发工作流与 Positron 原生 R 栈说明

本目录存放 Positron IDE 的用户级配置备份，并提供在「本机全局设置」与「harness 中央备份」之间安全对齐的脚本与检查记录约定。

Positron 与 Cursor 同属 VS Code/Code-OSS 变体，但 R 集成方式不同：Positron 使用内置 Console、ARK 语言服务与 Packages 面板，不依赖 REditorSupport.r（vscode-R）。因此本备份与 ide/cursor-settings/ 共享编辑器/Quarto/LaTeX 偏好，但 R 相关键使用 positron.r.* 等 Positron 原生项。

仓库内文件

文件 / 目录 说明
settings.json 适合 R 4.4.3 / Quarto / 长文档写作的可分享用户设置备份（提交前请确认无敏感 Token）。
settings-assistant.example.json Posit Assistant 配置形状示例（无 API Key）；须与本机 Authentication 凭据配合。
distribution-logs/README.md 分发日志目录说明。
distribution-logs/backups/ 分发备份
distribution-logs/checks/ 每次对比生成的 diff 与元数据

当前 settings.json 要点

类别 键（示例） 说明
R 解释器 positron.r.interpreters.default 默认 R 4.4.3（与 Cursor 备份一致）
包管理 positron.packages.enable 启用 Packages 侧栏（支持 renv / pak）
Quarto positron.quarto.inlineOutput.enabled 默认 false；改为 true 可启用 RStudio 式行内输出
文档大纲 files.associations + [quarto] .Rmd → Quarto，配合 Outline / breadcrumbs
刻意不含 positron.assistant.*、databot.* 本机 AI 提供商与模型，不应进入可分享备份
刻意不含 r.rpath.*、r.lsp.* 等 Cursor / vscode-R 专用；Positron 无需

与 Cursor 备份的分工

场景 推荐 IDE R 版本 配置来源
日常 Quarto / AI 辅助编码 Cursor 4.4.3 ide/cursor-settings/settings.json
R Console、Data Explorer、Notebook 调试 Positron 4.4.3 ide/positron/settings.json
renv 锁定项目 二者均可 以 renv.lock 为准 工作区或项目级设置

扩展与 Posit Assistant（必读）

Positron 与 Cursor 不共享扩展安装目录，也不能使用 VS Code Marketplace。Bootstrapped 扩展（含 posit.assistant、quarto.quarto）随 Positron 预装；切勿再装 REditorSupport.r 或官方 ms-python.python。

主题 文档
P3M / Open VSX、Built-in vs Bootstrapped、禁止列表 Positron 扩展与 Assistant 指南
Assistant 检查清单、Custom Provider、MiniMax 类 API 同上 §5.2
Assistant 可入库配置形状 settings-assistant.example.json

Posit Assistant 生效要点（详见专题文档）：

  1. 扩展 posit.assistant 已安装（Bootstrapped 或 P3M）。
  2. positron.assistant.enable: true → Reload Window。
  3. 至少一个 Provider 已 enable；Custom Provider 需 positron.assistant.provider.customProvider.enable: true。
  4. 命令面板 Positron Assistant: Configure Language Model Providers 完成 API Key / Base URL（不入库）。
  5. 遗留 databot.* 不能替代 Posit Assistant；请迁移到 positron.assistant.* + posit.assistant 扩展。

扩展依赖对照（相对 Cursor）

能力 Cursor Positron
R 安装 REditorSupport.r 内置 + posit.air-vscode；禁装 vscode-R
Quarto 安装 quarto.quarto Bootstrapped，一般无需再装
LaTeX 安装 James-Yu.latex-workshop 须在 P3M/Open VSX 单独安装
AI Cursor 内置 posit.assistant + positron.assistant.* 设置

Positron 内置能力（通常无需从市场重复安装）

能力 说明
R Console / 变量视图 内置；Interpreter 选择器可切换多版本 R
R LSP（补全、诊断） 内置 ARK / Air；在 R 中安装 languageserver 包（与 Cursor 相同）
Quarto Bootstrapped quarto.quarto
Shiny 调试 Bootstrapped posit.shiny；positron.runApp.previewMode 等
Posit Assistant Bootstrapped posit.assistant；须按上文启用 Provider

LaTeX：本仓库 settings.json 已写入 latex-workshop.*，但扩展须在 Positron 扩展视图中从 P3M 安装 LaTeX Workshop（非 Cursor 市场）。

首次同步前的重要提醒

本机 Positron 用户设置（%APPDATA%\Positron\User\settings.json）若已配置 Positron Assistant、自定义 LLM 等，切勿直接 -Apply：脚本会整文件覆盖本机设置，导致 AI 相关配置丢失。

推荐首次流程：

  1. 无参数运行脚本，阅读 checks/check-*.txt 中的 diff。
  2. 手动将 harness 中需要的键合并进本机 settings.json，保留 positron.assistant.* 等个人块；或先 -Prepare 备份再 -Apply，再从备份中拷回 Assistant 段。
  3. 稳定后，若希望仓库成为「可分享子集」的真理源，仅将脱敏后的片段维护在 ide/positron/settings.json（勿 -ArchiveToHarness 含 API Key 的完整本机文件）。

配置分发：方案选择（摘要）

与 Cursor 配置方案 相同：先 diff、再决定是否覆盖。

场景 使用的模式
harness 已更新，希望本机与之一致 -Prepare / -Apply（harness → 本机）
本机已迭代好可分享配置 审阅 diff 后 -ArchiveToHarness（本机 → 仓库）

详见 配置文件分发机制。

分发脚本：scripts/powershell/Distribute-PositronSettings.ps1

在仓库根目录执行（需 Git 与 PowerShell）。
Diff 约定：左侧 = 本机 %APPDATA%\Positron\User\settings.json，右侧 = harness/ide/positron/settings.json。

1. 仅对比（默认）

cd D:\github\harness
.\scripts\powershell\Distribute-PositronSettings.ps1

2. 准备：备份本机 + 对比

.\scripts\powershell\Distribute-PositronSettings.ps1 -Prepare

3. 应用：备份本机 + 用仓库覆盖本机（harness → user）

.\scripts\powershell\Distribute-PositronSettings.ps1 -Apply

预览：

.\scripts\powershell\Distribute-PositronSettings.ps1 -Apply -WhatIf

4. 回灌仓库（user → harness）

.\scripts\powershell\Distribute-PositronSettings.ps1 -ArchiveToHarness

注意：-ArchiveToHarness 会写入本机完整 settings；提交 Git 前必须剔除 Assistant Token、本机路径等敏感内容。

参数说明

参数 含义
-HarnessRoot harness 根路径；省略时按脚本位置推断。
-UserSettingsPath 本机 Positron 用户 settings.json；默认 %APPDATA%\Positron\User\settings.json。
-ArchiveToHarness 本机 → 仓库回灌；不可与 -Apply / -Prepare 同用。

R 4.4.3 安装后建议

在 Positron 中选定 R 4.4.3 Console 后，于 R 终端执行：

install.packages(c("languageserver", "httpgd", "pak"))
  • languageserver：增强跨文件跳转与诊断（Positron 内置 LSP 会调用）。
  • httpgd：可选；Positron 有内置 Plots 面板，不强制 httpgd。
  • pak：与 Packages 面板协作安装 CRAN/GitHub 包。

renv 项目：Positron 会自动识别项目库；与 Cursor 相同，确保项目内已 renv::restore()。

关联文档