# Zed 设置同步手册

本方案把 Zed 的设置、键位、Tasks、文件排除规则、代码片段和主题整理为一个扁平的 `zed-settings-sync.json`，通过 GitHub Gist 在机器间同步。同步文件内部不保存哈希、Gist ID、账号或 token。

## 准备工作

本地安装需要：

- Node.js
- Windows PowerShell，或 macOS/Linux 的 `curl`

启用 GitHub Gist 同步还需要 GitHub CLI `gh`：

```powershell
# Windows
winget install GitHub.cli
```

```sh
# macOS
brew install gh
```

Linux 安装方式见 <https://github.com/cli/cli/blob/trunk/docs/install_linux.md>。

无需提前创建 Gist，也无需手工生成 Personal Access Token。设置向导会调用 GitHub CLI 的浏览器登录流程，并请求 Gist 权限。

## 第一台机器

### 1. 安装配置

Windows PowerShell：

```powershell
irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.ps1 | iex
```

macOS / Linux：

```sh
curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.sh | sh
```

安装器先完成以下工作：

1. 从公开 Gitea 仓库下载默认 `zed-settings-sync.json`。
2. 把当前 Zed 配置备份到 `backups/bootstrap-<时间>`。
3. 安装设置、键位、Tasks 和同步脚本。
4. 创建空的机器本地同步状态。

这四步不访问 GitHub。没有 `gh`、没有登录或没有 Gist 都不会造成安装失败。

### 2. 连接 GitHub

安装结束时可以选择立即运行向导。稍后操作时：

1. 重启或 Reload Zed。
2. 按 `Mod+R` 打开 Task Picker。
3. 运行 `Zed Settings: Set Up / Reconfigure Sync...`。
4. 如果尚未登录，终端会显示一次性代码并打开 GitHub 浏览器授权页面。

脚本按以下顺序选择凭据：

1. 验证当前 `GH_TOKEN` / `GITHUB_TOKEN`，包括 Gist 权限。
2. 环境 token 无效时，移除它们后验证 GitHub CLI 凭据存储。
3. 都不可用时启动浏览器登录。

同步脚本本身不会读取、打印或保存 token。

### 3. 创建首个 Gist

登录后向导会搜索当前账号下包含 `zed-settings-sync.json` 的 Gist。第一台机器通常没有结果：

1. 选择 `N. Create a new Secret Gist from this machine`。
2. 向导创建 Secret Gist 并上传当前 Zed 设置。
3. Gist ID 和当前 SHA-256 被记录到本机 `scripts/settings-sync.json`。
4. 自动同步保持默认关闭，除非明确选择开启。

Secret Gist 不会出现在公开列表或搜索中，但知道链接的人仍可读取它。

## 新机器

1. 安装 Node.js；需要同步时再安装 `gh`。
2. 执行与第一台机器相同的一行安装命令。
3. 运行 `Set Up / Reconfigure Sync...`。
4. 使用同一个 GitHub 账号完成浏览器登录。
5. 向导会自动列出已有的 Zed 设置 Gist；通常只有一个，直接选择即可。
6. 初始同步方向选择 `P. Pull remote settings onto this machine`。
7. Pull 前默认安装产生的本地配置会被再次备份，然后替换为云端设置。
8. Reload Zed。

只有在使用其他账号、别人共享的 Gist 或自动发现失败时，才需要选择 `M` 并粘贴 Gist URL/ID。

## 日常手动同步

推荐默认使用手动同步，方向明确：

- 修改设置、键位、Tasks、代码片段或主题后，在当前机器运行 `Push Now`。
- 切换到另一台机器后运行 `Pull Now`。
- 不确定状态时先运行 `Show Sync Status`。

快捷键：

| 键位 | 操作 |
|---|---|
| `Mod+; U` | Push Now |
| `Mod+; D` | Pull Now |
| `Mod+R` | 打开 Task Picker |

Push 发现远端已经变化时会显示本地、远端和同步基线哈希，并在覆盖前确认。Pull 发现本地已经变化时同样确认，并始终先创建备份。

## 自动同步

运行 `Zed Settings: Enable Automatic Sync`：

1. 验证已经配置 Gist。
2. 验证 GitHub CLI 的系统凭据存储，而不是依赖临时环境 token。
3. 安装当前用户级的 15 分钟定时任务。
4. 把 `auto_sync` 写为 `true`。

关闭时运行 `Disable Automatic Sync`，它会删除对应的系统调度项并保留 Gist 关联和同步基线。

系统实现：

- Windows：Task Scheduler，任务名 `ZedSettingsSync`。
- macOS：LaunchAgent `cool.okk.zed-settings-sync.plist`。
- Linux：systemd user timer；没有 systemd 时使用带 `# zed-settings-sync` 标记的 crontab。

自动同步只处理方向明确的单边变化：

| 本地 | 远端 | 基线 | 结果 |
|---|---|---|---|
| 相同 | 相同 | 任意 | 无操作 |
| 已变 | 等于基线 | 存在 | 自动 Push |
| 等于基线 | 已变 | 存在 | 备份后自动 Pull |
| 已变 | 已变 | 存在 | 冲突，停止 |
| 不同 | 不同 | 不存在 | 无基线，停止 |

冲突、无基线、认证失效和网络错误不会触发覆盖。相同错误只通知一次，详细记录写入：

```text
Windows: %APPDATA%\Zed\logs\settings-sync.log
macOS/Linux: ~/.config/zed/logs/settings-sync.log
```

日志超过 1 MB 后保留最多三份历史文件。

## 冲突恢复

`Show Sync Status` 可能显示：

| 状态 | 含义 | 建议 |
|---|---|---|
| `synchronized` | 本地和远端一致 | 无需操作 |
| `local-changed` | 只有本地变化 | Push Now |
| `remote-changed` | 只有远端变化 | Pull Now |
| `conflict` | 两边都变化 | 先 Export JSON，再决定保留哪一边 |
| `no-baseline` | 机器没有可靠同步基线 | 检查内容后手动 Push 或 Pull |
| `remote-missing` | Gist 中缺少同步文件 | 重新配置或手动 Push |

发生冲突时不要连续试 Push/Pull。先运行 `Export JSON...` 保存本机单文件；需要保留远端时执行 Pull，需要保留本机时执行 Push。两个方向在覆盖前都会再次确认。

## 导入、导出与备份

`Export JSON...` 和 `Import JSON...` 会打开系统文件选择器。导出的 JSON 与 Gist 中的格式完全相同，顶层键直接是文件路径，例如：

```json
{
  "settings.json": "...",
  "keymap.json": "...",
  "tasks.json": "..."
}
```

没有 `files` 外壳，也没有内置哈希。Import 不会覆盖本机保存的 Gist ID、自动同步设置或上次同步哈希，但导入后的内容会被识别为新的本地变化。

Import 和 Pull 的备份目录：

```text
Windows: %APPDATA%\Zed\backups\sync-import-<时间>
macOS/Linux: ~/.config/zed/backups/sync-import-<时间>
```

## 修改文件排除规则

编辑：

```text
Windows: %APPDATA%\Zed\scripts\file-exclusions.json
macOS/Linux: ~/.config/zed/scripts/file-exclusions.json
```

- `defaults`：始终排除的 Zed 默认规则。
- `custom`：按 `Alt+Shift+-` 切换的自定义规则。

修改后先测试显隐，再运行 Push Now。其他机器 Pull 后会取得相同规则。

## 故障排查

### Task 没有反应

新版 Setup、Status、Push、Pull、启用和禁用自动同步都会打开并保留终端。先查看终端中的完整错误；确认 Zed 已 Reload，且 Task 名称不是旧版的 `Configure GitHub Gist`。

### 环境 token 导致认证异常

脚本会先验证环境 token。无效时会自动回退到凭据存储，并在终端说明。若希望清理环境变量，可检查系统、Shell Profile 和 Zed 的 terminal env 设置。

### GitHub 已登录但不能访问 Gist

运行 `Set Up / Reconfigure Sync...`。向导会调用 `gh auth refresh --scopes gist` 补充权限。

### 自动同步一直认证失败

后台任务不能依赖只存在于某个终端进程中的 `GH_TOKEN`。重新运行设置向导并完成浏览器登录，让 `gh` 把凭据保存到系统凭据存储，然后重新启用自动同步。

### Pull 后没有立即生效

先运行 `Show Sync Status` 确认哈希一致，再执行 `Mod+; K` Reload Zed。某些扩展和 UI 状态仍可能需要完整重启。

### 更换或删除 Gist

运行 `Set Up / Reconfigure Sync...` 重新选择、输入或创建 Gist。切换成功后会建立新的同步基线。删除远端 Gist 前建议先 Export JSON。