iCloud 配置同步 mkoalade/dsh-icloud-sync

dsh-icloud-sync

通过 iCloud Drive 让多台 Mac 上的 DeepSeek Harness 配置保持一致——配置档、插件清单、技能——提供 Settings → Integrations 面板、任务 / 频道旁边的 云端 标签页（按需推送和拉取单个会话快照），以及打包在插件内的命令行。新 Mac 无需终端：安装插件，打开面板，点 从云端接入。

同步内容

同步范围：~/.dsh/profiles/<profile>/ 加上技能：

- cordis.patch.yml、package.json、pnpm-lock.yaml、pnpm-workspace.yaml、.dsh-market/state.json
- ~/.agents/skills/*

会话日志不在这个包内：从对话自身的操作条上传（上传到 iCloud，位于 复制 / 好的回答 / 有问题的回答 旁边），在 云端 标签页下载或删除（见下文）。

项目工作区也走同一条路，但整体传输：上传项目 会发送项目的每个会话，外加整个目录树（文件、子文件夹、符号链接、权限位，按 SHA-256 增量传输），下载项目 会在记录的路径上逐字节还原该目录树——另一台 Mac 能打开同一个文件夹继续工作，而不只是重读对话。

永不同步：node_modules、运行时、缓存、存储的凭据、DSH 应用本身。插件在每台 Mac 上根据 package.json + pnpm-lock.yaml 重新安装。

安全保障

- 云端只存一个包：DSH-Sync/current/（文件加 manifest.tsv）。
- 每台 Mac 在 ~/.dsh/.icloud-sync/base/ 保留一份 base 副本，即双方上次一致的状态。
- 每次运行都比较本地 / 云端 / base，因此能区分「只有本地变了」「只有云端变了」「两边都变了」。两边都变时拒绝覆盖；用 dsh-sync diff 查看，然后 push --force 或 pull --force。
- manifest.tsv 最后写入，所以下载到一半的 iCloud 文件永远不会被当成删除。
- 每次推送/拉取都先备份：本地 20 份，云端 30 份。

会话同步（对话操作条 + 云端 标签页）

会话栏有四个标签页：任务、频道、云端、日程。同步是手动的，分两步。上传从对话内部发起：打开会话，助手操作条（带 复制 / 好的回答 / 有问题的回答 的那一行）上有 上传到 iCloud 按钮，项目不在运行时即可用。云端 标签页是 iCloud 一侧：只列出 iCloud 中存在的会话，提供 下载 和 删除云端。只存在于本机的会话不会出现在那里。

同样的上传也在项目的右键菜单里（在侧边栏右键项目 → 上传项目到 iCloud）；它在后台运行，用小提示报告结果。

行按项目分组，每个组标题都带 上传项目 和 下载项目：

- 上传项目 上传本机该项目的每个会话，包括 iCloud 从未见过的（标题会显示有多少个 未上传），然后上传项目目录本身：每个文件、子文件夹、符号链接和权限位，按 SHA-256 增量比对（跳过 .DS_Store，超过 4 GB 的文件会报告并排除）。运行中的会话会贡献已经持久化的消息。
- 下载项目 会下载该项目所有比本地更新的云端副本；已经完全相同的副本保持不动，运行中的会话跳过，而不是让整批失败。然后从 manifest.json 恢复项目树（相同的文件保持不动，被替换的内容先归档到 DSH-Sync/history/projects/）。如果另一台 Mac 使用不同的用户名，/Users/<them>/… 会重映射到这台 Mac 的主目录。

- 每一行显示标题、项目、最后活动时间、大小，以及四种状态之一：已上传 / 未上传 / 云端更新 / 仅云端。
- 上传到 iCloud 会覆盖该会话的云端快照；之前的快照移到 DSH-Sync/history/sessions/<timestamp>-<machine>/，永不删除。上传仍在打开的会话时，只快照已经写入磁盘的消息。
- 下载 会覆盖本地副本；本地之前的副本移到 ~/.dsh/.icloud-sync/backups/sessions/<timestamp>/。刷新后，会话会重新出现在任务下，并从停止的地方继续。下载绝不会写入 iCloud 文件夹内部。
- 删除云端 只删除 iCloud 副本，将其归档到 DSH-Sync/history/sessions/<timestamp>-<machine>/；本地日志和其他所有 Mac 保持完好。
- 会话打开时（运行中）下载被禁用——请先关闭它。不会自动上传或下载，无论是否定时。
- 不再有冲突状态：覆盖就是约定，落败的副本会被归档。
- 附件暂不随会话一起传输；粘贴的图片在另一台 Mac 上可能缺失。

云端布局：DSH-Sync/cloud/sessions/<project-key>/session-<uuid>/ 存放 session.v4.jsonl.zstd 和 meta.json；被覆盖的副本落在 DSH-Sync/history/sessions/。

云端标签页需要一个小型 codex-ui 补丁

侧边栏由 @michengai/dsh-codex-ui 绘制，它硬编码了任务 / 频道 / 日程标签页，所以第三方插件无法通过公开的 slot API 添加标签页。因此，首次启动时本插件会对该包（lib/codex-sidebar-tab.js）应用一个小型、可逆的本地补丁：它声明一个 sidebar.cloud slot，并将其占用者渲染为又一个伴随标签页。codex-ui 中其他内容不受影响，打补丁后的 bundle 在写入前会做语法检查，未改动的原始文件保留在 lib/client.js.before-dsh-cloud。

- codex-ui 升级后补丁会自动重新应用；如果锚点变了则跳过（并给出警告）——跳过补丁只会丢失标签页，绝不会丢失插件。
- dsh-sync codex-tab status 显示补丁是否已应用；dsh-sync codex-tab revert 恢复原始文件。两者都无需重启 DSH 即可生效。
- 要完全停止使用补丁，运行 revert 命令或移除 index.js 中的调用；设置面板和命令行两种方式都能继续用。

安装

dsh plugin --profile desktop add github:mkoalade/dsh-icloud-sync

包直接从 GitHub 发布（github:mkoalade/dsh-icloud-sync），所以上面的 github: 写法就是标准形式——配置档里的 pnpm 会原样接受 git 说明符。把 desktop 换成你的配置档名。如果面板没出现，重启 DSH；面板位置在 Settings → Integrations → iCloud 同步。

包自带补丁行，安装时就会挂载插件——没有第二步，也不要求 ~/.local/bin，因为命令行已经打包为 bin/dsh-sync。

第一台 Mac：发布你的配置

先完全退出 DSH，然后用面板（创建同步包 / 立即同步）或命令行：

dsh-sync init # create DSH-Sync/current in iCloud from this Mac
dsh-sync status # confirm the bundle exists
dsh-sync agent on # optional: sync on login and every 15 minutes

init 还会把脚本复制到 DSH-Sync/bin/dsh-sync，这样另一台 Mac 不用装这个包，也能从 iCloud 引导启动。

另一台 Mac：加入

1. 安装 DSH（版本相同或相近），启动一次，让配置档目录生成，然后退出。
2. 等 iCloud 下载完 DSH-Sync。
3. 安装这个插件（pull 步骤不会替你装它——它只写配置档文件）：

dsh plugin --profile desktop add github:mkoalade/dsh-icloud-sync

4. 运行云端那份命令行，或在面板里点 Pull from cloud：

bash "$HOME/Library/Mobile Documents/com~apple~CloudDocs/DSH-Sync/bin/dsh-sync" pull

第一次 pull 会先备份本地配置档，写入云端文件，然后按 package.json / pnpm-lock.yaml 重装插件（--no-install 跳过这一步）。之后重启 DSH——云端标签页和它的 codex-ui 补丁会在插件下次启动时生效。

想让加入过程自动完成，就在插件行配置里设 autoPull: true：启动时，如果这台 Mac 还没加入，但看到了已初始化的云端同步包，它会自己跑一次 pull。

- insert:
- id: dsh-icloud-sync
name: 'dsh-icloud-sync'
config:
autoPull: true

配置

| 键 | 类型 | 默认值 | 含义 |
| autoPull | boolean | false | 启动时，如果云端同步包存在且这台 Mac 还没加入，就跑一次 pull。 |
| syncBin | string | "" | 另一个 dsh-sync 脚本的绝对路径，覆盖打包的那份。 |

DSH_ICLOUD_SYNC_BIN 的优先级高于这两项。解析顺序：环境变量、syncBin、打包的 bin/dsh-sync、~/.local/bin/dsh-sync、iCloud 里的 DSH-Sync/bin/dsh-sync。

命令行

dsh-sync status compare local, cloud, and base
dsh-sync push [--force] upload local changes
dsh-sync pull [--force] download cloud changes
dsh-sync sync push, then pull
dsh-sync init create the cloud bundle from this Mac
dsh-sync diff <path> show the textual diff for one file
dsh-sync doctor 检查 iCloud、包完整性和状态 dsh-sync open 在 Finder 中显示 DSH-Sync dsh-sync agent on|off|status 登录并开启 15 分钟后台同步

--dry-run 预览，--quiet 精简输出，--no-install 跳过插件安装。后台代理只上传本地改动；DSH 运行期间它从不下载。会话日志完全不归命令行处理——在对话的操作条里上传，在「云端」页签里下载或删除。

环境要求

macOS，已启用 iCloud Drive；DSH 配置档至少启动过一次；每台 Mac 上的 DSH 版本相同或相近。命令行兼容 bash 3.2，不需要运行时。

已知限制

- 面板目前只有中文；locale/en.json 和 locale/zh.json 存放插件的市场标题和描述。
- DSH 运行期间下载配置档，要等 DSH 重启后才生效。
- 凭据留在本地：~/.dsh/.credentials 从不上传。
- 会话传输不含附件。上传仍在打开的会话，只捕获已经落盘的消息。

许可证

MIT。

dsh-icloud-sync（中文）

通过 iCloud Drive 在多台 Mac 之间同步 DeepSeek Harness 的配置、插件清单和 Skills，并在 设置 → 集成 里提供面板、在侧栏「任务 / 频道」之后多一个「云端」页签，按需手动上传/下载单个会话快照。命令行工具随包分发，新电脑装完插件即可在界面里一键接入，不需要先开终端。

同步范围

- ~/.dsh/profiles/desktop/ 下的 cordis.patch.yml、package.json、pnpm-lock.yaml、 pnpm-workspace.yaml、.dsh-market/state.json
- ~/.agents/skills/*

会话记录不在这个同步包里：它们只在「云端」页签里点「上传 / 下载」时才移动（见下文）。

项目目录走同一套手动通道，但是整棵目录：上传项目除了会话，还会把项目文件夹里的所有文件、子目录、符号链接、权限位按 SHA-256 增量传上去；下载项目按清单逐字节还原到原路径，另一台 Mac 拿到的不是「只能看历史」，而是能直接接着跑的同一个目录。

不同步：node_modules、运行时、缓存、登录凭据、DSH 本体。插件在每台 Mac 上按 package.json + pnpm-lock.yaml 各自安装。

会话同步（会话操作条 + 云端页签）

侧栏现在是「任务 / 频道 / 云端 / 日程」四个页签。同步完全手动，分为两半：上传在对话里发起——打开会话后，助手消息操作条（也就是「复制 / 好的回答 / 有问题的回答」那一行）最右边有「上传到 iCloud」按钮，项目没在运行时就能点；云端页签是 iCloud 侧，只列出 iCloud 里真实存在的会话，负责「下载」和「删除云端」。只在本机、还没上传过的会话不会在这里单独成行。

同样的上传也在项目右键菜单里（侧栏右键项目 → 上传项目到 iCloud），后台执行，结果用右下角提示条汇报。

行按项目分组，每组标题右侧有 上传项目 / 下载项目：

- 上传项目：把这个项目在本机的所有会话一起传上去（包括从没上传过的，组标题会标「未上传 N」），然后是项目目录本身——所有文件、子目录、符号链接、权限位，按 SHA-256 增量上传（.DS_Store 跳过，超过 4GB 的文件会列在失败里不上传）；运行中的会话传它已经落盘的部分。
- 下载项目：把这个项目所有比本机新的云端副本一起拉下来；已经一致的不动，运行中的会话跳过、不会让整批失败。随后按 manifest.json 还原项目目录：内容相同的文件不动，被覆盖的文件先归档到 DSH-Sync/history/projects/；如果另一台 Mac 的用户名不同，/Users/<对方>/… 会换成本机家目录。

- 每行显示标题、项目、最后活动时间、大小，以及四种状态之一：已上传 / 未上传 / 云端更新 / 仅云端。
- 上传到 iCloud（在会话操作条里）：用本机版本覆盖这个会话的云端快照；上一版移入 DSH-Sync/history/sessions/<时间>-<机器>/，不会删。会话还开着时上传，只包含已经落盘的消息。
- 下载（云端页签）：用云端版本覆盖本机会话；本机上一版移入 ~/.dsh/.icloud-sync/backups/sessions/<时间>/。刷新后任务列表里能看到它，接着上次的对话继续。
下载不会写云端任何文件。
- 删除云端：只移除 iCloud 里的这份副本，并归档到 DSH-Sync/history/sessions/<时间>-<机器>/；本机和其它 Mac 不受影响。
- 已归档的会话（侧栏「归档会话」）不参与同步：不会出现在云端列表里，上传时直接跳过，也不会被下载回来。归档状态记在 ~/.dsh/storages/workspace.json，取消归档后下一轮列表就会出现。
- 会话运行中（「运行中」）时不能下载——先结束或关闭它。没有定时上传、自动导入或后台扫描。
- 不再有冲突概念：覆盖就是约定，落选的那份一定备份。
- 附件暂时不随会话传输；另一台机器上，会话里粘贴过的图片可能缺失。

云端布局：

DSH-Sync/cloud/sessions/<项目key>/session-<uuid>/ session.v4.jsonl.zstd + meta.json DSH-Sync/cloud/projects/<项目key>/manifest.json 原始绝对路径 + 每个文件的相对路径/大小/权限/SHA-256 DSH-Sync/cloud/projects/<项目key>/files/<相对路径> 文件本体、符号链接的目标（.dsh-link） DSH-Sync/history/sessions|projects/<时间>-<机器>/ 被覆盖的旧副本

「云端」页签需要对 codex-ui 打一个小补丁

侧栏是 @michengai/dsh-codex-ui 画的，它把「任务 / 频道 / 日程」三个页签写死了，第三方插件无法通过公开插槽自己加页签。因此插件首次启动时会给这个包打一处小而可还原的本地补丁（lib/codex-sidebar-tab.js）：声明一个 sidebar.cloud 插槽，并把插槽里的组件渲染成第四个伙伴页签。
codex-ui 的其它代码一行没动；补丁写盘前会做语法检查，原始文件保留在 lib/client.js.before-dsh-cloud。

- codex-ui 升级后补丁会自动重打；如果锚点变了就跳过并打警告——跳过只会少一个页签，不会弄坏插件。
- dsh-sync codex-tab status 查看补丁状态，dsh-sync codex-tab revert 还原原文件，都不用重启 DSH。
- 想彻底不用补丁：执行 revert，或删掉 index.js 里的调用；设置面板和命令行照常工作。

安装

dsh plugin --profile desktop add github:mkoalade/dsh-icloud-sync

包直接从 GitHub 安装（没有发布到 npm），所以用上面的 github: 形式。装好后打开 设置 → 集成 → iCloud 同步。插件自带 cordis.patch.yml，装包时自动挂载，不需要再跑 install.sh，也不要求 ~/.local/bin 里有脚本——命令行就在包内的 bin/dsh-sync。

第一台 Mac：发布

先完全退出 DSH，然后在面板里点「创建同步包」，或：

dsh-sync init
dsh-sync agent on # 可选：登录时 + 每 15 分钟自动同步

新电脑：接入

1. 装好 DSH 并启动一次，让 profile 目录生成，然后完全退出 DSH。
2. 等 iCloud 下载完 DSH-Sync。
3. 先装本插件（pull 只写 profile 文件，不会替你装它）：

dsh plugin --profile desktop add github:mkoalade/dsh-icloud-sync

4. 在面板里点「从云端接入」，或直接运行云端脚本：

bash "$HOME/Library/Mobile Documents/com~apple~CloudDocs/DSH-Sync/bin/dsh-sync" pull

首次 pull 会先备份本机配置，再写入云端内容，并按清单安装插件（含 codex-ui）。完成后完全重启 DSH——云端页签和 codex-ui 补丁在插件下一次启动时才生效。若想全自动，在插件配置里加 autoPull: true，启动时检测到「云端有包、本机未接入」就自动拉一次。

配置项

| 键 | 类型 | 默认 | 说明 |
| autoPull | boolean | false | 启动时若云端已有同步包而本机未接入，自动 pull 一次。 |
| syncBin | string | "" | 指定另一个 dsh-sync 脚本的绝对路径。 |

脚本查找顺序：DSH_ICLOUD_SYNC_BIN 环境变量 → syncBin → 包内 bin/dsh-sync → ~/.local/bin/dsh-sync → iCloud 里的 DSH-Sync/bin/dsh-sync。

会话记录由插件自己的后台循环同步（即「云端」页签），不走 dsh-sync 脚本。

常见问题

- 面板里「从云端下载」在 DSH 运行时不会即时生效，重启后才是新配置。
- 冲突时界面不会自动覆盖：先 dsh-sync diff 看清差异，再决定 push --force 还是 pull --force。
- ~/.local/bin/dsh-sync 是可选的终端入口；在面板里点「安装到 ~/.local/bin」即可复制。

许可

MIT。