SuperAPI AI 工具集

sync-local

编程与开发

查看项目

更新于 10-26 21:40

技能介绍

【用途】 sync-local 用于解决 Cursor 插件市场更新滞后、版本被固定,或需要离线/本地覆盖插件的问题。它把插件以真实目录副本的形式放到 Cursor 的本地插件目录 ~/.cursor/plugins/local(Windows 下为 %USERPROFILE%.cursor\plugins\local),供本地测试或使用。来源可以是当前仓库、任意插件市场 URL,或单插件仓库;支持从本地 git 检出或远程 URL 获取。

【主要能力】

  • 以真实复制而非 junction 链接的方式同步插件目录,每个插件目录需包含 .cursor-plugin/plugin.json 清单。
  • 支持按插件名过滤(当来源为多插件市场时只复制指定子集)。
  • 支持为 URL 来源指定分支、标签或 SHA(--ref / -Ref)。
  • 对本地 git 检出会先 fetch 并快进干净的跟踪分支,成功后更新子模块;不处理脏工作区、rebase 或分叉分支,会打印一行说明并按当前 HEAD 复制。
  • 支持 --no-update / -NoUpdate 跳过 fetch,--keep-clone / -KeepClone 在 URL 来源时保留临时克隆,--dry-run / -DryRun 只打印计划不写入。
  • 演练模式按插件输出 [dry-run] <name> -> <dst>,结尾为 Would sync (n);真实运行时输出 Synced (n)。
  • 对来源路径不存在、pluginRoot 逃逸仓库、插件过滤后无结果、未解析到任何插件等情况返回退出码 1 且不复制;bash 版参数错误退出码为 2,PowerShell 版由参数绑定器在脚本执行前报错并退出 1。

【使用方式】 Windows: pwsh -File <cursor-plugins>/scripts/sync-local.ps1 [-Source <path-or-url>] [-Plugin a,b] [-Ref main] [-KeepClone] [-NoUpdate] [-DryRun] Unix: bash <cursor-plugins>/scripts/sync-local.sh [--dry-run] [--no-update] [--ref main] [--keep-clone] [<path-or-url>] [plugin ...] 来源参数可省略:默认使用包含脚本的仓库(若其看起来像市场或插件)、一组已知检出路径,否则克隆 https://github.com/melodic-software/cursor-plugins。脚本不可用时,仍可手动将每个含 .cursor-plugin/plugin.json 的插件目录复制到 ~/.cursor/plugins/local/<name>/。同步完成后在 Cursor 中执行 Developer: Reload Window。

【适用场景】 需要本地测试插件、使用被固定版本的插件市场、离线复制选定插件,或排查市场更新未生效问题的开发者。

【限制】 不负责团队市场仪表盘导入(应使用 install-marketplace / update-plugins),也不应将密钥提交进插件。Enterprise 默认关闭本地插件导入,需管理员在 Dashboard → Settings → Security & Identity → Marketplace and Plugins 中开启 Allow Local Plugin Imports。若已安装同名市场插件,市场安装优先于本地副本,需先卸载市场版本。脚本禁止在 $HOME、OneDrive、Documents、AppData 下递归搜索,以免卡顿。