# 安装、换机与排障

[返回 README](../README.md) · [配置参考](configuration.md)

## 环境准备

**第一次接触终端或 GitHub？先按 [README 的第一次使用步骤](../README.md#第一次使用)操作。** 那里从下载工具、打开终端开始，逐步说明粘贴命令、浏览器授权和成功检查。本页补充安装检查、已有仓库连接和排障。

插件界面用于 DSH 的 `web` profile，包声明宿主 DSH ≥ `0.1.5-rc.3`。已在该版本完成本地安装、bundle 组合和 Web 启动检查；这是保守的发布下限，尚未完成所有更高版本的双机兼容验证。请先确认 DSH Web 能正常打开。包声明 Node.js ≥ 20，但压缩会话的解析和合并还依赖运行时的 Zstandard 支持；建议使用 Node.js 24。跨操作系统路径组合尚无完整兼容矩阵。

如果工具还没装，优先用 README 中的下载入口。已熟悉 Windows 终端的用户，也可以在 PowerShell 中逐行执行以下安装命令，每行按 Enter，等待完成后再执行下一行：

```powershell
winget install --id Git.Git -e
winget install --id GitHub.cli -e
```

安装后关闭并重新打开终端。先分别运行以下命令，每行都应返回版本号。若提示找不到命令，先解决对应工具的安装问题：

```sh
git --version
gh --version
dsh --version
```

检查通过后，回到 README 完成插件安装和账号登录。登录命令启动的是一次授权流程，要完成浏览器中的验证码和授权，再回终端检查结果；不能在它等待输入时直接粘贴下一条命令。所有安装和登录操作都应在运行 DSH 的同一个系统用户下完成。

重启 DSH 是停止并重新启动应用进程，然后刷新网页；不是只关掉网页标签。用终端启动时，可回到运行 DSH 的窗口按 Ctrl+C 停止，再使用原来的启动命令；使用启动器时按启动器的退出和启动方式操作。请先结束正在生成的回复。

## 第一台电脑

1. 检查要上传的[同步范围](sync-content.md)。只需要会话与设置时，先关闭「同步工作区文件」。
2. 默认自动建仓使用登录账号下的 `dsh-sync`。已有同名仓库时，插件会确认它是私有仓库；公开仓库或可见性无法确认时不会连接或上传。
3. 点「⟳ 同步」。插件尝试创建或复用仓库，成功后把地址写入配置。
4. 确认设置页显示仓库地址、同步成功，且工作区没有失败。首次上传时间取决于数据量和网络，不保证两分钟内完成。

自动建仓失败时会退回本地快照。**本地快照成功不等于上传成功。**登录或网络问题修复后再试；自动建仓尝试之间至少间隔约 60 秒。

## 手动连接仓库

适用于自定义 GitHub 仓库或 SSH。请先创建一个私有仓库（新建时可不添加 README、许可证或 `.gitignore`），安装并登录 `gh` 以便插件确认私有状态，再配置可用的 Git 凭据。其他 Git 服务和不安装 `gh` 的远端暂不支持云端上传。

**推荐直接在设置页完成：** 打开「设置 → 同步 → 连接同步仓库」，填写仓库地址与同步分支（默认 `main`），点「保存连接设置」，再点「立即同步」。保存只写入配置，实际同步时才检查仓库权限与私有状态。同步进行中不能保存配置，请等待完成后再试。

[新建 GitHub 仓库](https://github.com/new) · [GitHub CLI 登录帮助](https://cli.github.com/manual/gh_auth_login)

只做本地快照时，清空仓库地址并关闭「地址留空时自动创建或复用私有仓库」。这不会删除云端已有的数据。

下列文件配置方式供高级用户使用：

配置文件是 DSH 数据目录里的 `dsh-sync.json`：

| 环境 | 默认路径 |
| --- | --- |
| Windows | `%USERPROFILE%\.dsh\dsh-sync.json`，通常为 `C:\Users\你的用户名\.dsh\dsh-sync.json` |
| macOS / Linux | `~/.dsh/dsh-sync.json` |
| 自定义数据目录 | `$DSH_HOME/dsh-sync.json` |

文件不存在时创建；已有配置时只合并需要的字段，保留其他设置：

```json
{
  "remote": "https://github.com/你的用户名/dsh-sync.git",
  "autoRepo": false,
  "mode": "manual"
}
```

SSH 地址示例：`git@github.com:你的用户名/dsh-sync.git`。需先自行配置 SSH 密钥与主机信任。不要把访问令牌写进仓库 URL；同步配置本身也在同步范围内。

保存并重启 DSH，再点同步。两台电脑的 `remote` 和 `branch` 必须一致。手工指定地址也会在上传前查询 GitHub 仓库可见性；查不到或不是私有仓库时同步报错，不上传。

## 第二台电脑

1. 安装相同的工具和插件，在该机器上登录 GitHub。登录必须在运行 DSH 的同一系统用户下完成。
2. 第一台使用默认仓库时，同账号可自动复用；使用自定义仓库时，在「连接同步仓库」填写完全相同的地址与分支并保存。
3. 点同步并检查结果，完成后重启 DSH。
4. 单独配置 API 密钥。已同步的模型配置只是配置，不代表凭据也已配置。
5. 按需重新安装所需插件及项目依赖。插件同步清单和锁文件，不传输 `node_modules`。
6. 同步结果出现「本机新创建的工作区」时，检查路径，必要时点「换位置」。跨系统、不同盘符等场景尤其需要确认。

已有本地会话的第二台电脑会参与双向合并，并非只下载。重要资料建议先另存副本。

### 依赖如何恢复

会话和附件无需安装依赖。模型需要在 DSH 中重新配置本机的 API 密钥；插件按原插件的安装说明重新安装，例如 `dsh plugin --profile web add 插件包名`。项目依赖请进入实际工作区文件夹，按项目 README 和锁文件选择安装工具；不要在所有项目中统一运行同一种安装命令。

### 换机完成检查表

- [ ] 两台设置页的仓库地址和分支一致，上次同步没有失败。
- [ ] A 的测试会话、附件能在 B 打开；B 新建的测试会话也能同步回 A。
- [ ] 启用工作区同步时，B 能打开项目文件；修改测试文件后能同步回 A。
- [ ] B 重启后会话归属正确，模型可用，所需插件和项目依赖已安装。

无需先把仓库克隆到 `.dsh`，也无需删除第二台已有的数据目录。

## 常见问题

| 现象 | 下一步 |
| --- | --- |
| 安装后没有按钮 | 确认安装到 `web` profile；重启 DSH 并刷新浏览器；检查启动日志中插件是否加载 |
| 未检测到 Git | 在 DSH 所用的系统用户下运行 `git --version`；安装后重启 DSH，刷新 PATH |
| 显示“本地快照”，没有仓库地址 | 执行 `gh auth status`；检查同名仓库；约 60 秒后重试，或手动填写 `remote` |
| 认证失败 | 按 [README 登录步骤](../README.md#第一次使用)重新授权并检查用户名；自定义 Git / SSH 地址检查对应凭据。插件不会替你弹登录窗口 |
| 网络超时 / 无法连接 GitHub | 检查网络；需要代理时在配置里设置 `proxy`，见[配置参考](configuration.md) |
| A 有会话，B 看不到 | 先 A 同步，再 B 同步；核对仓库与分支；检查工作区错误；重启 B 的 DSH 加载索引 |
| 会话在“未分组”里 | 同步后重启 DSH；自动重启修复是高级选项，依赖本机环境，不能保证所有环境可用 |
| 切换自动模式后没自动同步 | 设置页保存后立即生效，默认等待最多 300 秒；可先点立即同步；确认 `enabled` 没设为 `false`，宿主加载参数没有覆盖模式 |
| 新电脑模型无法使用 / 插件缺失 | 重新配置该机器的 API 密钥，安装插件或项目依赖；配置同步不等于依赖安装 |
| 工作区文件太多 / 不想上传代码 | 首次同步前关闭「同步工作区文件」，或设置工作区排除规则；关闭不会删除远端已有分支 |

仍未解决时，[提交问题](https://github.com/dpskk2/dsh-sync-plugin/issues/new/choose)，附插件版本、DSH / Node.js 版本、系统、复现步骤和脱敏后的错误。不要贴完整会话、凭据、私有仓库内容或带令牌的 URL。