purp1e/zed-sync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Redesign Zed Gist sync workflow

Browse Source
This commit is contained in:
purp1e
2026-07-30 12:53:31 +08:00
parent f19466a5df
commit 4263d6a25d
14 changed files with 1490 additions and 792 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+77 -61
View File
@@ -1,102 +1,118 @@
# Zed portable configuration
This directory is the portable source for Zed settings, keybindings, tasks, extension installation preferences, and the file-exclusion toggle.
## 一行安装
前置依赖：已安装 Node.js 和 GitHub CLI `gh`。
Windows PowerShell：
```powershell
irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.ps1 | iex
irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.ps1 | iex
```
macOS/Linux：
macOS / Linux：
```sh
curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.sh | sh
curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.sh | sh
```
脚本会处理 GitHub 登录并询问 Gist URL/ID。输入已有 Gist 会下载其配置；直接留空会从本仓库种子配置自动创建新的 Secret Gist。随后脚本会备份当前 Zed 配置并完成安装，安装后重启 Zed。
安装只需要 Node.js，会先备份并安装本地 Zed 配置，不要求 GitHub 登录，也不要求预先创建 Gist。安装完成后可以立即进入同步向导，也可以稍后在 Zed Task Picker 中运行 `Zed Settings: Set Up / Reconfigure Sync...`。
For first-machine setup, new-machine onboarding, daily Gist synchronization, and conflict handling, see [`SYNC-MANUAL.zh-CN.md`](./SYNC-MANUAL.zh-CN.md).
GitHub 同步额外需要 [GitHub CLI](https://cli.github.com/) `gh`。向导使用浏览器完成 GitHub 授权，不需要手工创建或粘贴 Personal Access Token。
## Files
完整的新机器、日常同步、自动同步和冲突处理说明见 [SYNC-MANUAL.zh-CN.md](./SYNC-MANUAL.zh-CN.md)。
- `settings.json`: editor settings and extension installation list. Provider secrets are not stored here.
- `keymap.json`: cross-platform bindings using `secondary-` for Command/Ctrl.
- `tasks.json`: task template. Script-path placeholders are rendered during installation.
- `scripts/file-exclusions.json`: the only file to edit when changing permanent or toggleable exclusion rules.
- `scripts/toggle-file-scan-exclusions.mjs`: updates `file_scan_exclusions` in the active Zed settings.
- `scripts/settings-sync.json`: machine-local Gist ID and last synchronized hash. Export and import never overwrite it.
- `scripts/zed-settings-sync.mjs`: single-JSON import, export, hashing, and Gist synchronization.
- `bootstrap-from-gist.ps1` / `bootstrap-from-gist.sh`: standalone one-line installers for a fresh machine. They download the single JSON directly from Gist and do not need the rest of this directory.
## 同步体验
## Zed Task Picker commands
- 云端始终只有一个扁平的 `zed-settings-sync.json`。
- 首次设置会自动发现当前 GitHub 账号中已有的 Zed 设置 Gist。
- 没有可用 Gist 时，可直接创建新的 Secret Gist 并上传本机设置。
- Gist ID、同步基线和自动同步状态只保存在当前机器，不会上传。
- `GH_TOKEN` 有效时会正常使用；无效时自动回退到 GitHub CLI 凭据存储。
- Push、Pull、Setup 和 Status 都在可见终端中运行，不会再静默失败。
- 自动同步默认关闭，可选择每 15 分钟检测一次。
Open the Task Picker and search for `Zed Settings`:
Secret Gist 不会列在公开资料和搜索中，但它不是严格私有存储：任何拿到链接的人都可以读取。同步包不会包含 API Key，但仍应避免在 Zed 配置和代码片段中保存秘密。
- `Export JSON...` and `Import JSON...` show a native file picker.
- `Configure GitHub Gist...` accepts an existing Gist ID or complete URL and remembers it on this machine.
- `Show GitHub Gist Status` compares the current, remote, and last synchronized SHA-256 hashes.
- `Push to GitHub Gist` creates a new Secret Gist when none is configured; later Push/Pull operations use the remembered Gist and ask before overwriting divergent settings.
- `Authenticate GitHub...` runs `gh auth login` in the terminal.
## Zed Tasks
GitHub CLI (`gh`) must be installed and authenticated. An existing Gist may contain other files; synchronization only creates or replaces `zed-settings-sync.json` inside it.
打开 Task Picker，搜索 `Zed Settings`：
The synchronized JSON is deliberately flat. Its top-level keys are paths such as `settings.json`, `keymap.json`, and `scripts/file-exclusions.json`, whose values are the complete file contents. No version, metadata, `files` wrapper, or hash is embedded. SHA-256 values are calculated at runtime and only the last synchronized value is retained locally.
| Task | 用途 |
|---|---|
| `Set Up / Reconfigure Sync...` | 浏览器登录 GitHub，发现、创建或更换 Gist |
| `Show Sync Status` | 查看本地、远端、同步基线和自动同步状态 |
| `Push Now` | 手动上传本机设置；覆盖远端前确认 |
| `Pull Now` | 手动下载远端设置；覆盖本机前确认并备份 |
| `Enable Automatic Sync` | 安装用户级 15 分钟定时任务 |
| `Disable Automatic Sync` | 删除定时任务并关闭自动同步 |
| `Export JSON...` | 用系统文件选择器导出单个 JSON |
| `Import JSON...` | 从单个 JSON 导入并先备份当前配置 |
A secret Gist is unlisted, not access-controlled: anyone who obtains its URL can read it. This bundle deliberately excludes API keys, but a synchronized folder or private Git repository is the safer choice for configuration that contains sensitive paths or identifiers.
快捷键：
## Installed keybindings
- `Mod+R`：打开 Task Picker。
- `Mod+; U`：运行 `Push Now`。
- `Mod+; D`：运行 `Pull Now`。
- `Mod+9` / `Mod+0`：当前编辑器区域的上一个 / 下一个 Tab。
- `Alt+1` 至 `Alt+5`：切换编辑器区域。
- `Mod+Shift+R`：切换最近项目。
- `Mod+; K`：重载 Zed。
- `Mod+; C`：打开 Git Panel；再次按下聚焦 Commit Message。
- `Mod+R`: open the Task Picker; search for `Zed Settings` to import, export, push, or pull.
- `Mod+; U`: upload the current single JSON to the configured Gist.
- `Mod+; D`: download and import the single JSON from the configured Gist.
- `Mod+9` / `Mod+0`: activate the previous / next tab in the current pane.
- `Alt+1` through `Alt+5`: activate editor pane 1 through 5.
- `Mod+Shift+R`: switch to a recent project.
- `Mod+; K`: reload Zed.
- `Mod+; C`: focus the Git panel; press it again to focus the commit-message editor.
`Mod` 在 macOS 是 Command，在 Windows/Linux 是 Ctrl；配置通过 Zed 的 `secondary-` 语法跨平台复用。
`Mod` is Command on macOS and Ctrl on Windows/Linux because the keymap uses Zed's `secondary-` syntax. `Alt` maps to Option on macOS.
## 自动同步规则
## Windows
自动同步使用当前用户级系统调度器：
Install this copy into Zed:
- Windows：Task Scheduler 的 `ZedSettingsSync`。
- macOS：`~/Library/LaunchAgents/cool.okk.zed-settings-sync.plist`。
- Linux：优先使用 systemd user timer，不可用时回退到带标记的 crontab。
状态处理：
| 状态 | 自动行为 |
|---|---|
| 本地和远端一致 | 不修改 |
| 只有本地变化 | Push |
| 只有远端变化 | 备份后 Pull |
| 两边都变化 | 停止并通知，不覆盖 |
| 没有同步基线 | 停止并通知，不猜测方向 |
| 网络或认证失败 | 记录错误，不改变配置或基线 |
日志位于 Zed 配置目录的 `logs/settings-sync.log`，超过 1 MB 后自动轮换。自动同步要求 GitHub CLI 凭据保存在系统凭据存储中；仅存在于某个进程内的 `GH_TOKEN` 不足以供后台任务长期使用。
## 仓库文件
- `settings.json`：Zed 设置和扩展安装清单，不包含 Provider 密钥。
- `keymap.json`：跨平台键位。
- `tasks.json`：Zed Tasks 模板，安装时替换脚本路径占位符。
- `scripts/file-exclusions.json`：修改常驻和可切换的文件排除规则。
- `scripts/toggle-file-scan-exclusions.mjs`：切换 Project Panel 文件显隐。
- `scripts/settings-sync.json`：机器本地状态，不进入同步包。
- `scripts/zed-settings-sync.mjs`：导入、导出、Gist 和自动同步核心。
- `bootstrap.ps1` / `bootstrap.sh`：新机器非阻塞安装器。
- `zed-settings-sync.json`：可以上传到 Gist 的单个扁平同步文件。
AI / Codex ACP 设置见 [AI-SETUP.md](./AI-SETUP.md)。
## 本地开发
从仓库安装到当前机器：
```powershell
.\install.ps1
```
Export later changes from Zed back into this directory:
从当前 Zed 配置重新生成仓库配置和单文件：
```powershell
.\export.ps1
```
## macOS and Linux
Node.js is required for the exclusion toggle and task-template rendering.
运行隔离测试：
```sh
sh ./install.sh
sh ./export.sh
node --test tests/settings-sync.test.mjs
```
## Private Git synchronization
Initialize this directory once and push it to a private remote:
```sh
git init
git add .
git commit -m "Add portable Zed configuration"
git remote add origin <private-repository-url>
git push -u origin main
```
On another machine, clone the repository and run the platform installer. After changing Zed settings, run the export script, review `git diff`, then commit and push. On other machines, pull and run the installer again.
Zed account login does not currently synchronize these files. API keys remain in each machine's system keychain or environment variables and must not be committed.
测试使用模拟 `gh` 和临时 Zed 目录，不会访问或创建真实 Gist。