# 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。