Add portable Zed Gist sync configuration

2026-07-29 17:11:18 +08:00
commit 13cf327f48
17 changed files with 1749 additions and 0 deletions
@@ -0,0 +1,256 @@
+# Zed 设置同步使用手册
+
+本方案使用 GitHub Gist 中的单个 `zed-settings-sync.json` 同步 Zed 设置。JSON 顶层直接保存各配置文件的路径和完整内容；SHA-256 只在运行时计算，不写入同步文件。
+
+## 1. 同步内容
+
+会同步：
+
+- `settings.json`：界面、字体、主题、编辑器行为及扩展自动安装清单。
+- `keymap.json`：自定义键位。
+- `tasks.json`：文件显隐和设置同步任务。
+- `scripts/` 中的文件显隐及同步脚本。
+- 非空的 `snippets/` 和 `themes/` 目录。
+
+不会同步：
+
+- GitHub 登录凭据、API Key 和系统环境变量。
+- 本机保存的 Gist ID 和上次同步哈希。
+- Zed 数据库、缓存、聊天记录、项目文件及扩展二进制。
+
+扩展 ID 位于 `settings.json` 的 `auto_install_extensions` 中。导入后由 Zed 在目标平台重新安装扩展。
+
+## 2. 准备 Gist
+
+1. 登录 GitHub，打开 <https://gist.github.com/>。
+2. 创建一个 Secret Gist。GitHub 不允许创建完全空白的 Gist，可以先放一个 `README.md`。
+3. 复制完整 Gist URL 或末尾的 Gist ID。
+
+Gist ID 不是访问令牌。身份认证由 GitHub CLI `gh` 管理。
+
+Secret Gist 只是不出现在公开搜索中，获得链接的人仍然可以读取其内容。同步 JSON 不包含 API Key，但仍应妥善保管 Gist URL。
+
+## 3. 主机器首次上传
+
+### 3.1 安装和认证 GitHub CLI
+
+当前 Windows 机器已经安装 `gh`。其他机器可以使用系统包管理器安装：
+
+```powershell
+winget install GitHub.cli
+```
+
+macOS：
+
+```sh
+brew install gh
+```
+
+安装后，在 Zed 中按 `Mod+R` 打开 Task Picker，运行：
+
+```text
+Zed Settings: Authenticate GitHub...
+```
+
+也可以在终端执行：
+
+```sh
+gh auth login
+```
+
+### 3.2 保存 Gist
+
+1. 按 `Mod+R`。
+2. 运行 `Zed Settings: Configure GitHub Gist...`。
+3. 粘贴 Gist URL 或 Gist ID。
+4. 运行 `Zed Settings: Push to GitHub Gist`。
+5. 运行 `Zed Settings: Show GitHub Gist Status`，确认状态为 `Synchronized`。
+
+Push 只会在该 Gist 中创建或更新 `zed-settings-sync.json`，不会删除 Gist 中的其他文件。
+
+Gist ID 和上次同步哈希保存在本机：
+
+```text
+Windows: %APPDATA%\Zed\scripts\settings-sync.json
+macOS/Linux: ~/.config/zed/scripts/settings-sync.json
+```
+
+此文件不参与导入导出，所以其他机器不会覆盖当前机器记录。
+
+## 4. 新机器首次接入
+
+第一次接入只需要运行仓库里的独立 bootstrap 脚本。它会询问 Gist URL/ID，直接读取 Gist 单 JSON，再安装全部设置和同步工具；不需要下载或解压便携目录。
+
+### 4.1 安装前置程序
+
+新机器需要：
+
+- Zed 或 ZedG。
+- Node.js。
+- GitHub CLI `gh`。
+
+bootstrap 仓库本身不保存设置或凭据，只需要包含：
+
+```text
+bootstrap-from-gist.ps1
+bootstrap-from-gist.sh
+```
+
+因此这个仓库可以公开；真正的设置仍只存放在指定 Gist 中。
+
+### 4.2 一行安装
+
+Windows PowerShell：
+
+```powershell
+irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.ps1 | iex
+```
+
+macOS/Linux：
+
+```sh
+curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.sh | sh
+```
+
+迁移到其他 Gitea 仓库时，Raw URL 的常见形式是：
+
+```powershell
+irm https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.ps1 | iex
+```
+
+```sh
+curl -fsSL https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.sh | sh
+```
+
+执行过程中脚本会：
+
+1. 检查 Node.js 和 `gh`。
+2. 在尚未登录时运行 `gh auth login`。
+3. 询问 Gist URL 或 ID。
+4. 从 GitHub API 读取 `zed-settings-sync.json`。
+5. 验证顶层文件路径，防止写出 Zed 配置目录。
+6. 备份新机器已有配置。
+7. 安装设置、键位、Tasks、snippets、themes 和辅助脚本。
+8. 保存 Gist ID 和远端整文件 SHA-256 作为首次同步基线。
+
+安装完成后重启 Zed，运行 `Zed Settings: Show GitHub Gist Status`，状态应为 `Synchronized`。
+
+为了降低执行远程脚本的供应链风险，可以把 URL 中的 `main` 换成审核过的 commit SHA。bootstrap 仓库不应加入访问令牌或其他秘密。
+
+### 4.3 便携目录备用安装
+
+不能访问 Raw URL 时，仍可复制完整 `zed-config-portable` 目录并运行：
+
+```powershell
+.\install.ps1
+```
+
+```sh
+sh ./install.sh
+```
+
+然后在 Task Picker 中认证 GitHub、配置 Gist 并执行首次 Pull。
+
+## 5. 之后的日常使用
+
+开始在一台机器工作前：
+
+1. 按 `Mod+R`。
+2. 运行 `Zed Settings: Show GitHub Gist Status`。
+3. 如果显示 `Remote changes available`，执行 Pull。
+
+修改设置、键位、Tasks、排除规则或 snippets 后：
+
+1. 执行 Push。
+2. 确认状态变为 `Synchronized`。
+3. 再到其他机器执行 Pull。
+
+常用快捷键：
+
+| 快捷键 | 操作 |
+|---|---|
+| `Mod+R` | 打开 Task Picker |
+| `Mod+; U` | Push 到 Gist |
+| `Mod+; D` | 从 Gist Pull |
+| `Mod+; K` | Reload Zed |
+
+`Mod` 在 Windows/Linux 是 Ctrl，在 macOS 是 Command。
+
+## 6. 哈希和冲突处理
+
+系统比较三个 SHA-256：
+
+- 当前机器实时生成的单 JSON 哈希。
+- Gist 中单 JSON 的哈希。
+- 当前机器上次成功 Push/Pull 时保存的哈希。
+
+Status 可能显示：
+
+| 状态 | 含义 | 建议操作 |
+|---|---|---|
+| `Synchronized` | 本地和 Gist 一致 | 无需操作 |
+| `Local changes pending upload` | 只有本机有变化 | Push |
+| `Remote changes available` | 只有 Gist 有变化 | Pull |
+| `Conflict` | 本机和 Gist 都有变化 | 先导出本地备份，再决定 Push 或 Pull |
+| `Not synchronized on this machine` | 这台机器尚无同步基线 | 首次接入通常选择 Pull |
+
+Push 覆盖远端前、Pull 覆盖本地前都会显示哈希并要求确认。Pull 会自动备份本地配置；系统不会尝试逐字段自动合并。
+
+## 7. 离线 JSON 导入导出
+
+不使用 Gist 时，也可以使用完全相同的单 JSON 格式：
+
+```text
+Zed Settings: Export JSON...
+Zed Settings: Import JSON...
+```
+
+两个命令都会弹出系统文件选择窗口。直接 Import 不会修改已保存的 Gist ID 和上次同步哈希；导入内容会被视为新的本地变化，可以随后 Push 到 Gist。
+
+## 8. 修改文件排除规则
+
+只编辑本机配置中的 `custom` 数组：
+
+```text
+Windows: %APPDATA%\Zed\scripts\file-exclusions.json
+macOS/Linux: ~/.config/zed/scripts/file-exclusions.json
+```
+
+修改后按 `Alt+Shift+-` 测试显隐，再 Push 到 Gist。其他机器 Pull 后会取得相同规则。
+
+## 9. 备份位置
+
+每次 Import 或 Pull 前的备份位于：
+
+```text
+Windows: %APPDATA%\Zed\backups\sync-import-<时间>
+macOS/Linux: ~/.config/zed/backups/sync-import-<时间>
+```
+
+便携安装器产生的备份使用 `portable-install-<时间>` 名称。
+
+## 10. 常见问题
+
+### Task Picker 中没有 Zed Settings
+
+重新运行一行 bootstrap 命令，或运行便携目录中的 `install.ps1` / `install.sh`，然后 Reload Zed。
+
+### 提示找不到 gh
+
+安装 GitHub CLI 后完全退出并重启 Zed，使编辑器读取更新后的 PATH。
+
+### Gist 返回 404
+
+检查 Gist URL/ID、当前 GitHub 账号以及 Gist 是否仍然存在。重新运行 `Configure GitHub Gist...` 可以更换记录。
+
+### Gist 中没有 zed-settings-sync.json
+
+先在已经配置好的主机器上执行一次 Push。
+
+### Pull 后键位或界面没有立即变化
+
+执行 `Mod+; K` Reload Zed；如果扩展仍在安装，等待完成后再重启一次。
+
+### 换了另一个 Gist
+
+运行 `Configure GitHub Gist...` 并输入新 ID。系统会保留新 ID，同时清空旧 Gist 对应的上次同步哈希，下一次 Push/Pull 会重新确认覆盖方向。