Cursor IDE的settings配置方案

settings.json 仓库备份、分发工作流与依赖说明

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

仓库内文件

文件 / 目录 说明
settings.json 适合 R / Quarto / 长文档写作的可分享用户设置备份（提交前请确认无敏感 Token）。
distribution-logs/README.md 分发日志目录说明。
distribution-logs/backups/ 分发备份：settings-user-*.bak（-Prepare/-Apply）、settings-harness-*.bak（-ArchiveToHarness 覆盖仓库前）
distribution-logs/checks/ 每次对比生成的 check-<时间戳>.txt（git diff 全文）与 check-<时间戳>.md（元数据 + 指向 txt）。可能含本机用户名路径，提交到 Git 前请人工审查或脱敏。

依赖扩展（与 settings.json 对应）

当前 settings.json 中的选项依赖以下扩展（在 Cursor 扩展市场安装即可；扩展 ID 便于在 settings.json 或 CLI 中引用）：

能力 扩展（示例 ID）
R 语言、R Markdown、与 R 终端交互 REditorSupport.r
Quarto（.qmd、与 Rmd 大纲等） quarto.quarto

若你为 LaTeX（如 .tex、.bib）配置 files.associations、编译或正向/反向搜索，请同时安装 LaTeX Workshop（扩展 ID：James-Yu.latex-workshop）。否则仅写 files.associations 可能出现缺少语法高亮、无构建命令、无 PDF 预览集成等问题。

示例（按需合并进 settings.json，勿与现有 files.associations 键冲突）：

"files.associations": {
  "*.tex": "latex",
  "*.bib": "bibtex"
}

安装 LaTeX Workshop 后，可在该扩展的设置中配置 latex-workshop.latex.tools 等；本仓库不绑定特定 TeX 发行版路径，以免泄漏本机目录。

与 Positron 的扩展差异（交叉引用）

Cursor 使用 VS Code Marketplace；Positron 使用 P3M / Open VSX，且 R/Quarto/Assistant 多为 Bootstrapped 预装。在 Cursor 安装的扩展不会出现在 Positron。若同时使用 Positron，请勿在 Positron 中安装 REditorSupport.r；Posit Assistant 依赖扩展 posit.assistant 与 positron.assistant.* 设置，详见 Positron 扩展与 Assistant 指南。

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

目标 推荐方式 说明
本机全局与 harness 长期一致、少副本 符号链接（Symlink）或反复 -Apply Symlink 需 Windows 开发人员模式或管理员权限，见 配置文件分发机制。
课程 / 课题 仓库内自带一份设置 复制 settings.json 到项目 .vscode/settings.json 与 Git 协作友好；迭代后通过「归档」回灌 harness。

脚本支持 两个方向的受控同步，共同步骤是：先对比（diff）并落盘检查记录，再根据模式决定是否备份、以及覆盖哪一侧。

场景 典型情况 使用的模式
仓库为准 harness 已更新，希望本机与之一致 -Prepare / -Apply（harness → 本机）
本机为准 日常工程里已改本机 settings.json，harness 中备份落后 先默认运行看 diff，再 -ArchiveToHarness（本机 → 仓库）

推荐节奏（本机领先时）：① 无参数运行一次，阅读 checks/check-*.txt；② 确认要把本机新配置写回仓库后，再执行 -ArchiveToHarness；③ 脱敏后 git add ide/cursor-settings/settings.json 并提交。

安装到业务项目（工作区级）

若希望在课程 / 课题仓库内放置 .vscode/settings.json，可在 harness 根执行：

.\scripts\powershell\Install-Harness.ps1 -InstallProfile cursor -ProjectRoot "D:\work\my-course"

说明见 Install-Harness 指南。本机用户级与 harness 中央备份的双向对齐仍使用下文 Distribute-CursorSettings.ps1。

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

在仓库根目录执行（需已安装 Git（用于 git diff --no-index）与 PowerShell）。 Diff 约定：git diff --no-index 的左侧为 本机用户 settings.json，右侧为 harness/ide/cursor-settings/settings.json。

1. 仅对比（默认）

不写备份、不覆盖任一侧；在 distribution-logs/checks/ 下生成 check-<时间戳>.txt（完整 diff）与 check-<时间戳>.md（元数据；含 sync_direction 与备份路径字段，在所有步骤结束后写入，以便 -ArchiveToHarness 能记录 harness_backup_path）。

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

2. 准备：备份本机 + 对比（仍不向任一侧同步）

在可能用仓库覆盖本机之前，先把当前本机 settings.json 复制到 distribution-logs/backups/settings-user-<时间戳>.json.bak，并生成检查记录。不要与 -ArchiveToHarness 同时使用。

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

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

先备份本机（若存在）、再写 diff 与检查记录、最后将 ide/cursor-settings/settings.json 复制到 %APPDATA%\Cursor\User\settings.json。

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

预览而不写入：

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

与 -ArchiveToHarness -WhatIf 相同：对目标路径的覆盖为预览；生成 diff 所需的 %TEMP% 临时副本仍会实际写入并在结束时删除。

4. 回灌仓库：本机领先时（user → harness）

当工程实践已在本机迭代好配置，而 harness/ide/cursor-settings/settings.json 已过时时：在 审阅 diff 并确认要把本机版本作为新的「中央备份」之后执行：

  1. （建议）先无参数运行一遍，只看 checks/ 中的 diff。
  2. 执行 -ArchiveToHarness：先生成 diff 的 .txt；若你确认执行（非 -WhatIf），则再将仓库内当前 settings.json 备份为 distribution-logs/backups/settings-harness-<时间戳>.json.bak，并用本机用户 settings.json 覆盖 ide/cursor-settings/settings.json；最后写入同时间戳的 .md 检查记录（含 harness_backup_path 等字段）。
.\scripts\powershell\Distribute-CursorSettings.ps1 -ArchiveToHarness

预览：

.\scripts\powershell\Distribute-CursorSettings.ps1 -ArchiveToHarness -WhatIf

-WhatIf 下不会备份或覆盖 ide/cursor-settings/settings.json 与本机用户文件；为生成 diff，脚本仍会将本机 settings.json 实际复制到 %TEMP% 下的临时文件（供 git diff 读取），该临时文件在运行结束时会删除。

注意：-ArchiveToHarness 不可与 -Apply 或 -Prepare 同用（脚本会报错退出）。回灌后务必检查 diff 中是否含不宜入库的路径或 Token，再执行 git commit。

参数说明

参数 含义
-HarnessRoot harness 根路径；省略时按脚本位置自动推断。
-UserSettingsPath 本机 Cursor 用户 settings.json；默认 %APPDATA%\Cursor\User\settings.json。
-ArchiveToHarness 本机 → 仓库回灌（见上文第 4 节）。

检查记录与 Git 提交建议

  • .txt：完整 unified diff，便于 git diff 风格审阅。编码为 UTF-8 带 BOM，以便在 Windows 记事本等默认按系统 ANSI 解码的工具中也能正确显示中文注释。
  • .md：YAML 头含 sync_direction、user_backup_path、harness_backup_path 等；UTF-8 带 BOM，与 .txt 一致便于 Windows 下阅读。

若 diff 中出现 C:\Users\... 等路径，提交前请自行判断是否脱敏；backups/ 目录已被 .gitignore 忽略，切勿强行 git add -f 备份文件（以免将个人环境完整快照推送到远端）。

关联文档