# 配置与恢复

配置写入 DSH 数据目录下的 `dsh-sync.json`，宿主显式配置覆盖文件中的同名值。设置页显示最终有效配置，不能仅凭文件声明判断是否生效。

## 常用选择

| 字段 | 新连接默认值 | 作用 |
| --- | --- | --- |
| `showSidebarSync` | `true` | 是否在侧边栏显示同步入口；标题旁即时切换，隐藏后仍可从设置进入，不关闭同步。 |
| `remote` | 空 | 不含凭据的私有 Git 仓库 HTTPS / SSH 地址：GitHub、Gitee、GitLab 等托管站均可。明文 `http://`、带令牌或密码的地址、本地路径停止传输，原地址不自动改写。 |
| `branch` | `main` | 两台电脑使用相同分支。 |
| `enabled` | `true` | 启动/退出自动同步总开关；关闭仍能手动同步。 |
| `autoPullOnStart` | `true` | 总开关开启后，启动时后台同步；不阻塞进入，失败后台重试。旧会话未核对或未完成写入时仅拦截发送。 |
| `autoPushOnExit` | `true` | 总开关开启后，从菜单完全退出，等待落盘后上传。 |
| `contentScope` | 全选 | `sessions`、`attachments`、`settings` 三类主数据，两台电脑共用这项选择。 |
| `syncInstructions` | `false` | 界面名称为「指令与技能」：是否同步全局 `AGENTS.md` 与 `skills/` 文件夹。每台电脑各自开关，不随同步偏好共享。 |
| `workspaceSync` | `true` | 项目文件两个方向的同步。 |
| `workspaceBase` | 空 | 可选的本机项目根目录映射。 |
| `proxy` | 空（自动） | 空或 `auto`：优先使用启动环境的代理变量，否则在 Windows 读取当前系统代理，未启用代理则直连。填写 URL 则使用指定代理。本机保留，不随数据覆盖另一台电脑。 |
| `autoRepo` | `true` | 未填写地址时，手动同步可创建或复用自己的 GitHub 私有仓库。其他托管站不自动建仓。 |
| `autoRestartAfterRepair` | `true` | 界面名称为「同步后自动检查分组（实验性）」，位于「修复会话问题」。正常未分组和归档会话不自动修复；仅项目登记不一致或存在同步归属丢失证据时提示检查。后台启动与发送保护模式不会自动关闭编辑器，修复需预览、确认后完全退出执行。关闭此项仍可手动检查。 |

启动/退出选项勾选不代表总开关已开启。未连接仓库时不执行启动/退出自动建仓。旧 `mode`、`intervalSeconds`、`eventDebounceSeconds` 为迁移兼容字段，不建立周期、空闲或编辑事件任务。

自动代理每轮同步及仓库检查前重新读取，因此修改 Windows 系统代理端口后无需重启 DSH。已填写的代理 URL 保持手动模式；要跟随系统代理，将 `proxy` 改为空字符串或 `auto`。环境变量优先于系统代理；若启动环境明确设置了旧代理，也需要更新该环境变量。Windows 自动检测支持静态 HTTP、HTTPS 和 SOCKS 代理，不执行 PAC 脚本；仅使用 PAC 的网络需通过环境变量或手动 URL 指定代理。其他系统沿用环境变量或直连。

## 同步仓库

首次设置点击「使用默认仓库」，首次手动同步时自动创建或复用当前 GitHub 账号下的 `dsh-sync` 私有仓库，无需填写地址或勾选建仓。生成的地址仍保存在本机配置中，界面显示连接状态与「在 GitHub 查看仓库」。

需要使用 `dsh-sync2` 等其他仓库时，先在 GitHub 创建私有仓库，再点击「使用其他仓库」或「更换同步仓库」填写 HTTPS / SSH 地址。也支持组织或其他账号下当前登录账号有写入权限的私有仓库。界面保存时联网检查是否可访问、是否私有及写入权限；不存在、权限不足、网络失败或无法确认时保留原地址。GitHub 对不存在与无权访问的私有仓库可能返回相同错误，界面不把两者误作确定结论。

更换页面留空并保存会改用当前账号的默认 `dsh-sync`，原仓库保留；「取消」不保存输入。保存不建仓或传输，首次同步才创建默认仓库。自定义仓库不会自动创建。旧配置接口保留兼容性，其地址保存只检查格式；上述联网检查由界面的连接保存接口执行，每轮同步上传前仍重新确认私有状态。

### 其他 Git 托管站

地址不是 `github.com` 时，按通用 Git 仓库处理，不需要 GitHub CLI：

1. 先在托管站网页创建**空的私有**仓库，不要勾选用 README 等文件初始化。
2. 每台电脑各登录一次：HTTPS 地址在终端运行 `git ls-remote 仓库地址`，在弹出的 Git 登录窗口输入该站的账号和密码或访问令牌，凭据由 Git 凭据管理器保存；SSH 地址先为这台电脑生成 SSH 密钥，把公钥添加到托管站的「SSH 公钥」设置，再用 `git ls-remote 仓库地址` 确认能读取。同步时不会弹出登录窗口，所以这一步要先在终端完成。
3. 在「使用其他仓库」或「更换同步仓库」填写地址，例如 `https://gitee.com/用户名/dsh-sync.git`、`git@gitee.com:用户名/dsh-sync.git` 或自建 GitLab 的 `ssh://git@git.example.com:2222/组/子组/dsh-sync.git`。

这些托管站没有统一的仓库可见性接口，私有状态这样确认：关闭本机保存的凭据、密码提示和系统集成登录，用同一站点的 HTTPS 地址匿名读取一次分支列表。

- 站点要求登录（HTTP 401）才算私有；无需登录就能读取的视为公开，拒绝上传。
- 回答找不到仓库、拒绝访问（403）、限流、网络或证书失败都无法证明私有，本次停止，不上传。
- 界面保存时还会用这台电脑自己的登录读取一次，确认地址正确、凭据可用；托管站没有通用的写入权限查询，写入权限在首次上传时确认。
- 每轮同步上传前都会重新检查。

已知边界：

- SSH 地址通过同一站点、同一路径的 HTTPS 地址检查。站点只开放 SSH、网页地址与 SSH 主机名不同，或部署在子路径下时，检查连不上或对不上，会停止同步，请改用 HTTPS 地址。
- 匿名检查只能区分「任何人可读」和「需要登录」。GitLab 等的「内部」可见性（同一站点所有登录用户可读）、组织内共享仓库无法与私有仓库区分，请自行确认仓库只有自己可以访问。
- 本机 `_netrc` 等 Git 以外的凭据来源可能让匿名检查读到仓库，此时会按公开仓库拒绝上传，需要移除这类凭据。
- 自动创建仓库、「本机另存旧历史」中向 GitHub 查询历史等功能只用于 GitHub；其他托管站只回收本机副本能证明远端仍保有的旧备份。

### 更换到另一个托管站

「更换同步仓库」可以从 GitHub 改到 Gitee 或反过来，做法与换到同一站点的另一个仓库相同：这台电脑下次同步时为新地址建立新的同步副本，并把当前内容按正常合并规则上传；原仓库保持不变。

界面不提供一键搬迁，原因是：

- 每台电脑只下载同步分支的当前快照和在用的项目分支。同步前备份、历史归档、其他电脑的回执和未登记的项目分支都不在本机，搬到空仓库时不会带过去。
- 同步地址保存在各电脑的本机配置中，不随数据同步。多台电脑无法同时切换；还没切换的电脑会继续写入旧仓库。插件也不会根据仓库里的内容自动跟随新地址，否则可能被引导上传到未经你确认的仓库。
- 各站的单文件、单仓库容量上限不同（例如 GitHub 拒绝超过 100 MB 的单个文件），带完整历史推送可能被目标站拒绝。

以两台电脑 A、B 从 GitHub 换到 Gitee 为例。

**只带当前内容（推荐）：**

1. A、B 在原仓库各完成最后一次同步，然后关闭自动同步。
2. 在 Gitee 网页创建空的私有仓库。
3. A、B 各自按上文登录 Gitee。
4. A 在同步页点「更换同步仓库」，填写 Gitee 地址并保存；保存时检查仓库是否私有、A 能否读取。然后点「立即同步」，A 的当前内容上传到 Gitee。
5. B 同样更换为同一地址并「立即同步」：取回 A 的内容，并按正常合并规则上传 B 自己的新内容。
6. 确认两台电脑内容一致后，重新打开自动同步。

原仓库保持不变，可以作为备份；确认不再需要后可在原站点设为归档。原仓库的旧历史、同步前备份和归档分支不会带到新仓库。

**连全部分支和历史一起搬：** 在上面第 2、3 步之间，由一台电脑把原仓库的全部分支复制到新建的空仓库（只对空仓库执行；历史很大时可能被新站点的容量限制拒绝，可先在原仓库「清除历史版本」）：

```powershell
git clone --bare 旧仓库地址 dsh-sync-copy.git
git -C dsh-sync-copy.git push 新仓库地址 "refs/heads/*:refs/heads/*"
```

之后同样逐台更换地址并同步。

两种做法都要每台电脑亲手改一次地址；还没改的电脑会继续写入原仓库，改过来并同步一次后，它本机的内容才会到新仓库。

## 升级时的开关保留

明确保存的 `enabled: false` 保持暂停。已有启动/退出开关保持各自值；旧自动模式在没有明确暂停时保留启用。旧 `mode: manual` 且没有独立生命周期选择的配置继续手动使用，不因升级开启自动传输。宿主显式覆盖仍优先，读取配置不重写原文件。

设置页操作自动总开关会保存明确的生命周期选择。首次连接默认开启自动同步，先完成手动设置与首次同步；未连接仓库时不会自动建仓。已明确关闭或使用旧手动模式的配置保留原选择。

以上描述升级默认值的迁移规则；后续启用「设置」同步时，自动同步等普通偏好可以随另一台电脑更新。同步连接、代理和本机项目路径不随这份偏好传输。

## 项目文件与本机字段

关闭项目文件同步会同时暂停上传和取回；主数据内容选择同理，远端已有内容保留。项目目录不能与 DSH 数据目录相等、互相包含，以免绕过会话保护。

设置投影保留各机的密钥、代理和本机路径。含无法安全投影的 YAML 结构时停止设置同步并说明原因，不把原文件随意重写。同步连接、凭据、锁、缓存、运行状态、临时文件与本机恢复记录不参与传输。

## 后台启动、发送保护与错误

连接仓库并选择内容后，首次传输、内容范围及设置变化按所选范围自动处理，不再逐次确认。启动后台同步期间可以查看旧会话、编辑草稿、新建会话与工作区；向尚未核对远端或未完成安全写入的旧会话发送时才弹窗阻止，保留文字及附件。按钮发送、回车、附件和追加指令共用发送入口，宿主在消息入队前再次检查。核对完成后由用户查看最新历史并再次发送，不自动补发。

网络失败或写入占用时保留待处理状态，启动任务按退避间隔重试，最长间隔 60 秒；隐私检查不会因此自动绕过。已核对会话不受无关工作区上传失败影响。后台模式不自动关闭或重启正在编辑的应用；暂时不能热应用的更新留到正常退出并重新打开后处理。检查确认的是本轮取回的快照，不能阻止另一台设备在此后继续写同一会话。

上传前检查全部未上传历史，包括之后删除的敏感文件。Git 检查分批读取，每个原始或解码文件仍有容量上限；检查不完整时停止，不悄悄跳过。界面只显示类别和文件名，不返回命中的密钥值。

日常页与侧栏不再显示取消同步操作，后台同步自动完成或在失败后重试。侧栏「同步」打开独立页面，同步时图标旋转；详细进度与反馈显示在同步页内，不弹出遮挡账号菜单的气泡。上次详情保留总耗时、传输量、结果及待处理问题，重复等待记录合并。断网、权限失效、限流和仓库非私有分别提示；未确认私有状态不能上传。

上次详情的「本机同步副本（含历史）」包含已打包和未打包的 Git 对象，不是本次传输量，也不是新电脑下载量。「清除历史版本」检查最多等待 2 分钟，复用已经缓存且与远端一致的设备回执；分支查询超时、登录失败和本机提交读取失败分别提示。清除后回收当前副本中已归档的旧历史，本机独有分支保留；未归档的独有恢复提交会阻止清除。同步仓库的归档分支仍占用远端空间。早先版本清除后留在本机的同步前备份另列为「本机另存旧历史」，可在同步仓库明细中核对远端仍保有后回收。

## 运行中的会话

Git 在独立传输目录合并，宿主目录中的会话不参与检出。已有会话通过公开持久化写入接口取得写入权、重读并追加；忙碌、分叉、格式不支持或缺少接口时保留原件，记录待处理。

只选择一致的最高日志代际；原始无版本号日志为第 0 代，是否压缩不决定新旧。旧 v0/v1 打包事件按实际事件跨度检查，原件不展开重写。最高代不唯一、日志断层或压缩帧未完成时停止。能发现未来代际不代表宿主能够应用。

需要停机取回时使用界面明确的关闭后取回流程，等待所有相关宿主退出并核对原件，再应用和重新打开。远端删除不会直接删除本机会话。存在待处理更新时不把“已传输”描述成“全部已应用”。

## 冲突原件与项目文件恢复

「查看冲突内容」按文件列出双方原件。项目文件预览绑定当前内容，恢复前备份，只处理选定文件；期间被其他程序修改或原件校验失败则停止。恢复前备份可用于回滚。

每条记录显示文件路径、时间和当时的处理结果。点击「查看内容」打开独立大窗口：会话以用户和助手消息呈现，隐藏自动注入的指令、上下文及内部事件；设置、项目登记和会话列表信息按字段显示，图片可直接预览，其他二进制文件显示文件信息。这是只读预览，不会继续对话或修改保存的原件。长会话可继续加载消息。

需要排查时，点击「查看原始记录」进入红绿差异行、同步滚动和差异导航；关闭或 Esc 返回列表。项目文件的恢复操作放在对比窗口底部。[常见文件说明](dsh-file-catalog.md)

普通文件恢复不能直接覆盖会话日志。受支持的会话分叉通过宿主接口另存为新身份，核对附件、项目归属和读回；重试不重复创建。支持范围受宿主及格式限制，不承诺任意历史子树都能导入。

## 未完成会话导入的停机修复

更一般的旧数据问题，可在同步页「会话与数据修复」中点击「打开处理页面」，检查归属错误、残缺日志、登记表和配置损坏。未分组提醒的「去处理」直接进入「处理未分组会话」，选择会话、查看方案，再选择本机项目确认恢复。处理工具直接显示，原件保留；修改项目文件的本机同步位置不会迁移会话。[操作和边界](data-repair-0.20.1.md)。下面的命令专用于已有导入种子的旧修复流程。

迁移方案仅在映射路径唯一匹配可用项目时预选该项目，仍需确认。迁移完成、新会话读回且旧会话归档后，恢复原件可在本机存储中按保留规则手动清理；未完成处理和旧仓库的独有提交仍受保护。

仅适用于已保存修复材料、且部分日志与已知种子构成完整前缀的导入。未知损坏或期间出现其他编辑时不覆盖。

先在源码目录查看只读材料：

```powershell
node lib/cli.mjs --session-repair-list
node lib/cli.mjs --session-repair-preview <原件记录ID> <local或remote>
```

需要修复时，先从菜单完全退出所有使用同一数据目录的 DSH，再运行：

```powershell
node lib/cli.mjs --session-repair-apply <预览计划ID> --offline-dsh-closed
```

命令会核对宿主、原件和种子，先备份再修复。重启后仍须由公开接口读回同一身份与归属，通过前保持同步暂停。可用 `--session-repair-rollback <备份ID> --offline-dsh-closed` 撤销未验收且未被其他程序修改的修复。

## 状态、诊断与更新

只读工具 `sync_status`、`sync_preview`、`sync_doctor` 和命令行 `--status`、`--preview`、`--doctor` 不初始化仓库、不取回、不上传，也不授权恢复。预览只反映本机已知内容。

设备回执按对应主数据和项目提交核对，30 天后过期；不表示另一台电脑界面已经可用。更新提醒可关闭，只复制对应宿主的更新命令，不自动安装。此次本地 0.20.1 没有发布，市场更新命令不能代替安装本批本地包。

本版没有 WebDAV 连接、备份或恢复入口，也不支持 GitCode。旧本地扩展资料保留在维护输出归档，不参与当前运行。

## 会话正文中包含密钥

凭据文件被排除，不代表过去读取该文件的工具输出也不含密钥。敏感检查会扫描完整待上传历史，不能通过删除当前文件或忽略一条错误绕过。

需要保留对话时，应保留本机完整原件，另建独立身份的脱敏副本，并经宿主读回验证。完整原件和含密钥的备份应放在本机数据目录的 `.chatsync-local/` 下，不放入 OneDrive 中的源码或交付目录。原件可使用 `.gitignore` 精确排除；范围同步会在导出、导入及预览时遵守本机规则，保留本机原件。既有传输副本中的已跟踪文件和未上传历史仍需单独、可恢复地处理；忽略规则本身不会抹去历史。

如果含密钥的内容已经到过远端，生成脱敏副本或从当前文件列表移除原件都不能让旧密钥失效，仍需在所属服务更换密钥或重新授权相关凭据。改写远端历史需另行明确授权。