# DSH Sync
### 换台电脑，接着聊、接着做。
把 DeepSeek Harness（DSH）的**会话、附件、设置和项目文件**同步到你的其他电脑。
数据放在你自己的 GitHub 私有仓库中，由你掌握。
[](https://www.npmjs.com/package/dsh-sync-plugin)
[](LICENSE)
[第一次使用](#第一次使用) · [换到另一台电脑](#换到另一台电脑) · [遇到问题](#遇到问题) · [English](README.en.md)
**装好后，平时只需要点「⟳ 同步」。** 第一次需要安装两个辅助工具、登录一次账号；下面按操作顺序带你完成，不需要会写代码。
它适合你自己的多台电脑交替使用。模型的 API 密钥不会跟随专用凭据文件同步，新电脑需要单独配置。
## 第一次使用
### 1. 先准备好这几样东西
先确认你能正常打开 DSH 的网页界面。如果还没装 DSH，请先完成[DSH 官方安装步骤](https://github.com/deepseek-ai/deepseek-harness)，能打开网页后再回来继续。安装过程中如果需要 Node.js，可从[官网下载](https://nodejs.org/en/download)，建议使用 24。
| 需要什么 | 你需要做什么 |
| --- | --- |
| GitHub 账号 | 用来存放同步数据。没有账号就[先注册](https://github.com/signup)；记住这个账号，其他电脑也要用 |
| Git | 帮插件传输和保存文件。[下载 Git](https://git-scm.com/downloads/)，选择你的系统并完成安装 |
| GitHub CLI | 帮这台电脑登录 GitHub。[下载 GitHub CLI](https://cli.github.com/)，选择你的系统并完成安装 |
Git 和 GitHub CLI 是两个不同的工具，都要安装。**GitHub CLI 没有需要你单独打开的登录窗口**，下一步会在终端里用 `gh` 命令调用它。
### 2. 打开终端，装上插件
工具安装完成后，打开一个**新的终端窗口**：
- **Windows：** 打开开始菜单，搜索「PowerShell」并打开，不需要选「以管理员身份运行」。
- **macOS：** 打开「终端」应用。
- **Linux：** 打开系统自带的终端。
下面的命令都粘贴到这个窗口里，**不是 DSH 的聊天输入框，也不是浏览器地址栏**。每次复制代码框里的整行，粘贴后按一次 Enter（回车），等它执行结束再继续；不用输入代码框外面的标题。
先安装同步插件：
```text
dsh plugin --profile web add dsh-sync-plugin
```
等终端显示安装结果、重新出现可输入命令的提示符。若出现错误，先看下方[常见问题](#遇到问题)，不要接着往下做。
### 3. 让这台电脑登录你的账号
仍在刚才的终端里，复制这一整行并按 Enter。它会发起浏览器登录，命令已经替你选好了 GitHub.com 和 HTTPS：
```text
gh auth login --hostname github.com --git-protocol https --web
```
接下来按提示完成登录：
1. 如果终端问是否让 Git 使用此账号（`Authenticate Git ...`），选择 `Yes`，按 Enter。
2. 终端会显示一次性验证码；记下它，按提示按 Enter 打开浏览器。没有自动打开时，打开终端给出的网址。
3. 在浏览器登录你准备好的 GitHub 账号，按页面要求输入**终端里的验证码**，确认授权 GitHub CLI。这个验证码不是你的模型 API 密钥。
4. 浏览器提示授权完成后，**回到终端**，等它显示登录完成并重新出现输入提示符。
然后单独运行下面这一行，检查登录是否成功。这条命令只检查状态，不会重新登录：
```text
gh auth status
```
输出中应能看到 `Logged in to github.com account` 和你的用户名。确认是你想用的账号，再继续。仅仅在浏览器里登录了 GitHub，并不代表这个步骤已经完成。
### 4. 回到 DSH，完成第一次同步
关闭并重新启动 DSH，再刷新网页。**只刷新网页不等于重启 DSH**；如果你原来用终端启动它，就回到那个启动窗口停止进程，再按原来的方式启动。
打开 **设置 → 同步**：
1. **先选同步范围。** 找到「同步偏好」。默认会上传工作区内的项目文件；如果你只想同步聊天、附件和设置，关闭「同步工作区文件」并点「保存偏好」。工作区就是你在 DSH 中打开的项目文件夹。
2. **第一次用，连接设置先不用填。** 保持默认的自动建仓选项，点「立即同步」（侧栏「⟳ 同步」也可以）。插件会尝试在你的账号下创建或复用名为 `dsh-sync` 的私有仓库。仓库可以理解为存放同步数据的云端空间，不需要你先手动创建。
3. **检查结果。** 设置页应出现仓库地址；等待同步结束，确认没有失败提示，也没有工作区同步失败。第一次传输耗时取决于文件数量和网络。
**看到「本地快照」还不算完成：它表示只存在这台电脑上，没有上传。** 如果上传失败，在同步页展开错误详情，按[排障说明](#遇到问题)处理后再试。
已有指定仓库的用户，可以在「连接同步仓库」填写地址与分支；不确定这些是什么，先使用上面的默认流程即可。[已有仓库的连接方法](docs/getting-started.md#手动连接仓库)
## 换到另一台电脑
**先在原电脑同步成功，再到新电脑操作。**
1. 在新电脑重复上面的第 1～3 步：安装工具和插件，登录**同一个 GitHub 账号**。
2. 重启新电脑上的 DSH，检查「同步偏好」，再点「立即同步」。原电脑使用默认仓库时，插件会尝试自动复用它。
3. 如果原电脑用了自定义仓库，从原电脑 **设置 → 同步** 复制仓库地址和分支，填写到新电脑的「连接同步仓库」，保存后再同步。**保存地址本身不会传输数据。**
4. 等同步成功，再重启新电脑上的 DSH。打开一条原电脑的会话、检查附件或项目文件，确认确实取回来了。
5. 在新电脑配置模型的 API 密钥；需要的其他插件和项目依赖也要在本机安装。聊天记录到了但模型不能用，先检查密钥，不必重复同步。
不用删除新电脑原有的会话，也不用手动克隆数据目录；已有内容会参与双向合并。需要换项目存放位置或恢复依赖时，查看[换机详细说明](docs/getting-started.md#第二台电脑)。
## 以后怎么用？
**开工前同步一下，收工后同步一下。** 确认上一台已上传，再换到下一台。
想省去手动操作，可以在 **设置 → 同步 → 同步偏好** 选择「自动同步」并保存，立即生效。默认每 5 分钟同步，也会响应会话活动；DSH 必须保持运行，网络也要可用。
## 哪些会带走，哪些要重新准备？
| 会同步 | 新电脑要单独处理 |
| --- | --- |
| 会话、附件、会话所属工作区 | 模型的 API 密钥 |
| 模型与界面设置、插件清单 | 其他插件的安装与项目依赖 |
| 工作区里的实际文件（可以关闭） | 必要时调整项目的存放路径 |
专用凭据文件不上传，但会话、附件或项目文件中仍可能含有你写进去的密钥。首次上传前检查同步范围；不想上传的文件可设置排除规则。同步也会传播删除和错误修改，重要资料请另留备份。[范围、排除规则与冲突处理](docs/sync-content.md)
## 遇到问题
| 你看到的情况 | 先这样做 |
| --- | --- |
| 「无法识别 dsh / git / gh」或 `command not found` | 对应工具没有装好，或终端没读到新安装的工具。安装后关闭这个终端，重新打开再试；`gh` 对应 GitHub CLI |
| 浏览器已经登录，终端却说没登录 | 回到第 3 步，完成命令发起的授权，再运行 `gh auth status` 检查 |
| 设置里找不到「同步」 | 确认安装命令执行成功；重启 DSH 进程后再刷新网页 |
| 只有本地快照 / 上传失败 | 先检查第 3 步的登录状态，再看同步页的错误详情；自动建仓失败后可等约一分钟重试 |
| 新电脑没有原来的会话 | 先原电脑同步，再新电脑同步，核对仓库地址和分支一致；完成后重启新电脑上的 DSH |
| 网络错误、需要代理，或仍然失败 | 查看[完整排障](docs/getting-started.md#常见问题)；需要反馈时[提交问题](https://github.com/dpskk2/dsh-sync-plugin/issues/new/choose)，附错误提示，隐藏密钥与私人内容 |
版本要求与更多资料
插件用于 DSH 的 `web` profile，声明支持 DSH ≥ `0.1.5-rc.3`。Node.js 声明要求 ≥20，建议使用 24 来处理压缩会话。不同系统和宿主版本的测试范围见[验证记录](docs/release-0.12.5-validation.md)。
[配置参考](docs/configuration.md) · [更新记录](CHANGELOG.md) · [开发与验证](CONTRIBUTING.md)
需要升级插件时，在终端运行下面这一行，完成后重启 DSH：
```text
dsh plugin --profile web update dsh-sync-plugin
```