# StoreSync

Shared plugin store for Obsidian: all your vaults use one copy of every community plugin, and new vaults connect automatically. Desktop only.

> 解决 Obsidian 打开新仓库(vault)时插件不跟随、每次都要重新下载插件的问题。
> 所有仓库的 `.obsidian/plugins` 指向同一个本地目录:任一仓库安装/更新插件,
> 所有仓库立即可见,磁盘上只有一份文件,零重复下载。(另附清单模式,用于跨机器/移动端迁移。)

## English

**StoreSync** keeps your Obsidian community plugins in sync across all your vaults on one computer. Every vault's `.obsidian/plugins` folder is linked to a single shared store, so a plugin you install or update in any vault is instantly available in all of them — one copy on disk, no repeated downloads. New vaults (or folders opened as vaults) are connected automatically within seconds.

### Installation

1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/likangjie110/obsidian-plugin-sync/releases).
2. Put them in `<your-vault>/.obsidian/plugins/plugin-sync/`.
3. In Obsidian, open **Settings → Community plugins**, turn off restricted mode, and enable **StoreSync**.

Or install with [BRAT](https://github.com/TfTHacker/obsidian42-brat): *Add Beta plugin* → enter this repository's URL.

### Usage

- In your main vault, open the StoreSync panel (ribbon icon) and click **Link to shared store**. Your plugin folders move into a shared store (default `~/.obsidian-plugin-store`), and the vault's plugin folder becomes a symlink to it.
- Create a new vault, or open any folder as a vault: it is connected automatically within seconds. Turn off restricted mode once, and all plugins are there.
- Install or update a plugin in any vault: it appears in every other vault.
- **Unlink from shared store** restores regular per-vault plugin files at any time.

### Network access

The plugin uses the network **only** in manifest mode (exporting/importing your plugin list for another computer or mobile):

- `raw.githubusercontent.com` — to download the public Obsidian community plugin index;
- `github.com` and `api.github.com` — to download plugin release files (`main.js`, `manifest.json`, `styles.css`).

The shared-store features work fully offline. The plugin has no telemetry and never sends any data about you or your vaults.

### Files outside your vaults

To share plugins between vaults, the plugin reads and writes files outside the current vault on your computer:

- it creates and links a shared store folder (default `~/.obsidian-plugin-store`);
- it reads Obsidian's own vault list (`~/Library/Application Support/obsidian/obsidian.json`) and may connect other vaults you have opened, so they get plugins automatically.

All of this happens locally on your machine.

### Requirements

Desktop only: it uses symlinks and Node.js APIs. Tested on macOS; Linux should work. Windows is untested; mobile is not supported.

---

## 问题背景

Obsidian 的社区插件按仓库隔离,存放在每个仓库的 `.obsidian/plugins/` 下。
打开新仓库后,插件一个都不会跟过来,只能逐个重新下载、配置;
插件有更新时,每个仓库还要各更新一遍。

## 安装与接入仓库

**从 GitHub 安装:** 在本仓库 [Releases](https://github.com/likangjie110/obsidian-plugin-sync/releases)
下载 `main.js`、`manifest.json`、`styles.css`,放入目标仓库的
`.obsidian/plugins/plugin-sync/`,然后在 Obsidian 设置 → 第三方插件 → 关闭安全
模式并启用「StoreSync」。也可以配合 [BRAT](https://github.com/TfTHacker/obsidian42-brat)
安装(Add Beta plugin,填入本仓库地址)。已提交 Obsidian 官方社区目录审核,
通过后可在 Obsidian 内直接搜索安装。

**第一个仓库(建库):** 把上面三个文件复制到该仓库的
`.obsidian/plugins/plugin-sync/`(或本地构建:`npm install && npm run build`),
在 Obsidian 里启用「StoreSync」,然后点面板「Link to shared store」建立共享库。

**之后的新仓库:自动接入(推荐,实时)**

只要任意一个已接入的仓库正在 Obsidian 中打开,插件会**实时监听** Obsidian 的
仓库列表(文件监听,秒级触发,轮询仅作兜底):**新建仓库、或把任意文件夹
「作为仓库打开」,几秒内就会被自动接入**共享库(软链接 + 预启用),并弹一条
提示。你只需在新仓库里关一次「受限模式」——这一次点击是 Obsidian 的安全
设计(该开关不落在仓库文件里,任何方案都无法预置)。

自动接入的护栏:位于 iCloud/Dropbox 等云同步目录的仓库跳过;`/tmp`、`/Volumes`
等系统路径跳过;在仓库根目录放一个 `.no-plugin-sync` 文件即可豁免该仓库。
(为什么不放系统后台服务:macOS 会拦截后台进程访问桌面/下载等受保护目录,
藏在 Obsidian 内运行反而是最稳的。)

**备用方式(Obsidian 未运行时,或想手动控制):**

1. **模板文件夹**:复制 `~/Desktop/Obsidian 新仓库模板` 一份
   (里面已接好共享库),用 Obsidian 打开即用;
2. **一条命令**(在本项目目录下执行):

   ```bash
   npm run link-vault -- "/要接入的仓库路径" --enable-all
   ```

   `--enable-all` 适合全新仓库(自动预启用共享库里的全部插件);已用过的仓库
   去掉该参数,保留原有启用列表;
3. **手动**:复制本插件到新仓库并点「Link to shared store」。

> 每个新仓库第一次打开时,Obsidian 会要求关闭一次「受限模式」(第三方插件)——
> 这是 Obsidian 的安全设计,任何方案都绕不过这一次点击。

## 使用

### 建立共享(每个仓库只需做一次)

1. 打开第一个仓库,点击左侧功能区图标 →「Link to shared store」→ 确认;
2. 插件会把本仓库的插件文件夹移入共享库(默认 `~/.obsidian-plugin-store`,
   可在设置里改),然后把 `.obsidian/plugins` 替换为指向共享库的软链接;
3. 按提示重载 Obsidian;
4. 其他仓库按上一节的三种方式之一接入。链接时自动合并:两边都有的插件保留
   较新的一份,一边独有的插件并入共享库。

### 日常自动跟随

- **在任一仓库新装/更新插件** → 写进共享库 → 其他仓库打开时自动出现
  (每 30 秒轮询一次,期间也会提示);
- 新插件在别的仓库默认不启用——面板里点「Enable N new plugin(s)」一键启用,
  或在设置里打开「Auto-enable new plugins」全自动;
- 启用状态(`.obsidian/community-plugins.json`)仍按仓库隔离,
  所以「哪些插件在这个仓库启用」由每个仓库自己决定。

### 断开共享

面板「Unlink from shared store」:把共享库的完整副本写回本仓库,
恢复独立文件。其他仓库不受影响。

### 跨机器 / 移动端(清单模式)

软链接只能在同一台电脑的仓库之间共享。换机器或移动端时:

1. 导出仓库执行「Export installed plugins」→ 生成 `plugin-manifest.json`;
2. 把该文件放进目标仓库根目录;
3. 目标仓库执行「Import plugins from manifest」→ 自动从 GitHub 官方 releases
   下载全部插件并恢复设置,重载后生效。

### 云同步仓库(iCloud/Dropbox)自动清单模式

同步盘(iCloud Drive、Dropbox、OneDrive、Google Drive 等)会重写或丢弃软链接,
所以放在云同步目录里的仓库不能链接共享库。插件会自动识别这类仓库,改用清单模式:

- **自动检测**:打开仓库时,插件先解析仓库的真实路径(realpath,因此能识破
  软链接,也能识破开着「桌面与文稿同步」时被同步进 iCloud 的 `~/Desktop`),
  再依次与 `~/Library/Mobile Documents`(iCloud Drive 整个容器)、
  `~/Library/CloudStorage` 下实际存在的各个云盘目录(Dropbox、OneDrive-*、
  GoogleDrive-*、Box…… 按目录枚举,不写死名字),以及 `~/Dropbox`、
  `~/OneDrive`、`~/Google Drive` 比对;仓库**等于**该目录或位于其下即算命中
  (路径按 macOS 约定,其他平台检测不到则不触发);
- **拒绝链接**:在云同步仓库里执行「Link to shared store」不会链接,只提示
  改用清单 Export/Import 流程;面板里也以提示文字代替「Link to shared store」
  按钮(若仓库是链接后才被移进云目录,面板顶部同样给出该提示);
- **打开时自动补装**:仓库打开时,若仓库根目录存在 `plugin-manifest.json`,
  且清单里有插件尚未安装,就自动执行一次清单导入——下载缺失插件、恢复设置、
  按设置启用,并照常给出提示与重载按钮;清单里的插件都已装齐时完全静默
  (不弹提示、不显示进度)。因此该动作是幂等的:清单可以长期留在仓库里,
  每次打开只补装缺的那部分。自动导入若一个插件都没装上(例如清单里只有
  社区市场没有的 beta 插件),同样不弹提示,只在控制台记一行 skipped。

## 设置

| 设置 | 说明 |
| --- | --- |
| Store path | 共享库路径(绝对路径,`~` 开头表示用户目录),默认 `~/.obsidian-plugin-store` |
| Auto-enable new plugins | 共享库出现新插件时,在本仓库自动启用(默认关) |
| Include plugin settings | 清单模式:导出时打包各插件 data.json(注意可能含敏感信息,勿公开分享清单) |
| Overwrite existing settings | 清单模式:导入时覆盖已装插件的设置(默认关) |
| Enable plugins after install | 清单模式:导入后自动启用插件(默认开) |

## 工作原理

- **链接**:把 `.obsidian/plugins` 下各插件文件夹移入共享库(冲突时按 main.js
  修改时间保留较新者),删除原目录并创建软链接指向共享库;
- **跟随**:插件启动与每 30 秒轮询时,对比共享库目录与
  `.obsidian/community-plugins.json`,发现未启用的新插件则提示/自动启用;
- **清单导入**:从 `obsidianmd/obsidian-releases` 的 community-plugins.json 把插件
  id 解析为 GitHub 仓库,按版本(缺省取最新 release)下载 main.js / manifest.json /
  styles.css 写入 `.obsidian/plugins/<id>/`;
- 新装/新启用的插件都需要重载一次 Obsidian 才会加载(插件提供一键重载按钮)。

## ⚠️ 需在真实仓库验证的事项

文件系统逻辑(合并、软链接、断开恢复、云同步目录识别)已由 `npm run verify`
在 macOS 上实测通过。但以下两点只有真实 Obsidian 里能验证,第一次使用前请检查:

1. **Obsidian 插件更新器对软链接目录的行为**:在共享库里更新某个插件,
   确认更新写入的是共享库(而不是把链接替换成真实目录)。
   若链接被替换,重新执行一次「Link to shared store」即可恢复;
2. **云同步仓库的自动识别**:插件会解析仓库真实路径,命中 iCloud Drive /
   Dropbox / OneDrive / Google Drive 等同步目录时自动拒绝链接,并改用清单模式
   (打开仓库时自动补装 `plugin-manifest.json` 里缺失的插件)。
   首次在真实云盘仓库里使用时,请确认:①链接命令确实被拒绝并给出提示;
   ②把 `plugin-manifest.json` 放进仓库根目录后重开仓库,缺失插件会被自动补装。

## 网络与文件访问说明

- **网络**:仅在清单模式(导出/导入插件列表)下访问网络——`raw.githubusercontent.com`
  获取社区插件索引,`github.com` / `api.github.com` 下载插件发行文件。共享库功能
  完全离线可用;插件无遥测,不会向任何服务器发送你的数据;
- **仓库外的文件**:为实现跨仓库共享,插件会在本机创建/读写共享库目录
  (默认 `~/.obsidian-plugin-store`),并读取 Obsidian 的仓库列表
  (`~/Library/Application Support/obsidian/obsidian.json`),以便自动接入你打开过
  的其他仓库。全部在本机完成。

## 已知限制与路线图

- 插件设置(data.json)在共享库中也是共享的:多数插件无影响,
  少数把仓库相关路径存进设置的插件可能出现异常;
- 未上架社区市场的插件(如 BRAT 装的 beta 版)在清单模式中无法自动下载,会跳过;
- 计划:主题(外观)同步、设置按仓库隔离模式、「源仓库直接读取」免清单迁移。

## 开发

```bash
npm install
npm run verify      # 软链接/合并/断开 + 云同步检测 + 多语言 + 自动接入测试(node,macOS)
npm run dev         # 监听构建
npm run build       # 类型检查 + 生产构建
npm run link-vault -- "/仓库路径" --enable-all   # 把仓库接入共享库(见上文)
```

界面文案支持简体中文 / 繁體中文 / English 三语,跟随 Obsidian 的界面语言,
字符串集中在 `i18n.ts`。

将构建产物放入测试仓库 `.obsidian/plugins/plugin-sync/` 即可;推荐配合
[hot-reload](https://github.com/pjeby/hot-reload) 插件调试。