119 lines
4.7 KiB
Markdown
119 lines
4.7 KiB
Markdown
# Zed portable configuration
|
||
|
||
## 一行安装
|
||
|
||
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
|
||
```
|
||
|
||
安装只需要 Node.js，会先备份并安装本地 Zed 配置，不要求 GitHub 登录，也不要求预先创建 Gist。安装完成后可以立即进入同步向导，也可以稍后在 Zed Task Picker 中运行 `Zed Settings: Set Up / Reconfigure Sync...`。
|
||
|
||
GitHub 同步额外需要 [GitHub CLI](https://cli.github.com/) `gh`。向导使用浏览器完成 GitHub 授权，不需要手工创建或粘贴 Personal Access Token。
|
||
|
||
完整的新机器、日常同步、自动同步和冲突处理说明见 [SYNC-MANUAL.zh-CN.md](./SYNC-MANUAL.zh-CN.md)。
|
||
|
||
## 同步体验
|
||
|
||
- 云端始终只有一个扁平的 `zed-settings-sync.json`。
|
||
- 首次设置会自动发现当前 GitHub 账号中已有的 Zed 设置 Gist。
|
||
- 没有可用 Gist 时，可直接创建新的 Secret Gist 并上传本机设置。
|
||
- Gist ID、同步基线和自动同步状态只保存在当前机器，不会上传。
|
||
- `GH_TOKEN` 有效时会正常使用；无效时自动回退到 GitHub CLI 凭据存储。
|
||
- Push、Pull、Setup 和 Status 都在可见终端中运行，不会再静默失败。
|
||
- 自动同步默认关闭，可选择每 15 分钟检测一次。
|
||
|
||
Secret Gist 不会列在公开资料和搜索中，但它不是严格私有存储：任何拿到链接的人都可以读取。同步包不会包含 API Key，但仍应避免在 Zed 配置和代码片段中保存秘密。
|
||
|
||
## Zed Tasks
|
||
|
||
打开 Task Picker，搜索 `Zed Settings`：
|
||
|
||
| 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 导入并先备份当前配置 |
|
||
|
||
快捷键：
|
||
|
||
- `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` 在 macOS 是 Command，在 Windows/Linux 是 Ctrl；配置通过 Zed 的 `secondary-` 语法跨平台复用。
|
||
|
||
## 自动同步规则
|
||
|
||
自动同步使用当前用户级系统调度器：
|
||
|
||
- 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
|
||
```
|
||
|
||
从当前 Zed 配置重新生成仓库配置和单文件：
|
||
|
||
```powershell
|
||
.\export.ps1
|
||
```
|
||
|
||
运行隔离测试：
|
||
|
||
```sh
|
||
node --test tests/settings-sync.test.mjs
|
||
```
|
||
|
||
测试使用模拟 `gh` 和临时 Zed 目录，不会访问或创建真实 Gist。
|