Zed portable configuration

一行安装

Windows PowerShell：

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

macOS / Linux：

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 gh。向导使用浏览器完成 GitHub 授权，不需要手工创建或粘贴 Personal Access Token。

完整的新机器、日常同步、自动同步和冲突处理说明见 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。

本地开发

从仓库安装到当前机器：

.\install.ps1

从当前 Zed 配置重新生成仓库配置和单文件：

.\export.ps1

运行隔离测试：

node --test tests/settings-sync.test.mjs

测试使用模拟 gh 和临时 Zed 目录，不会访问或创建真实 Gist。