症状：升级后会话列表还在，但无法续跑；工作区路径错了，Agent 甚至可能写入另一个仓库。
最快解法：把备份拆成可重建环境、会话状态、工作区产物、敏感凭据四层，并在隔离环境完成一次真实任务恢复，而不是只检查文件是否存在。
截至当前官方仓库说明，DeepSeek Harness 仍处于开发者预览阶段，明确存在兼容性破坏性变更；官方持久化目录还把 SESSION_FORMAT_VERSION 标为 0，并说明这属于预发布格式，不代表跨版本兼容。(github.com) 因此，DeepSeek Harness 数据备份的通过标准不是“复制成功”，而是新环境能否在不泄露凭据、不串用工作区的前提下恢复一条真实任务链。
这篇文章适合三类人：准备升级候选版、担心会话丢失的现有用户；需要执行本地到云端 Mac 迁移的开发者；以及负责环境交接、验收和采购签收的运维人员。
SECTION 01先建立四层资产边界
重装前最容易犯的错误，是把所有文件都当成同等重要，最后得到一个体积庞大、权限混乱、无法判断内容来源的备份包。你应先建立资产清单，再决定哪些内容复制、哪些内容记录、哪些内容重新安装。
✅ 可重建环境层：记录 DeepSeek Harness 的安装来源、提交版本或发布版本、运行模式、Node.js、包管理器、系统版本及关键依赖版本。官方开发文档目前列出 Node.js 22.19+ 或 24+、pnpm 11.7.0 以及 Git 2.26+ 等开发环境要求，具体版本仍应以你实际使用的仓库提交为准。(github.com)
✅ 必须保留的状态层：保存会话持久化日志、会话索引或元数据，以及恢复会话所需的状态文件。不要默认聊天文本就是全部内容。
✅ 工作区产物层：保存未提交代码、补丁、生成文件、项目指令文件、本地脚本和外部依赖说明。Git 仓库只能覆盖已提交或已纳入版本控制的内容。
⚠️ 敏感凭据层：只记录凭据名称、引用位置、用途和轮换状态，不把可直接使用的 API Key 混入普通备份包。
源码缓存、临时构建产物和能够通过锁文件重新安装的软件，不应与关键会话状态混在一起。它们可以单独保留一份用于排障，但不应被误认为恢复成功的必要条件。
SECTION 02会话持久化：只复制 DSH_HOME 够不够
如果你准备把 DSH_HOME 整个复制到新机器，答案是：不能直接把它当成完整恢复方案。DSH_HOME 是否包含当前版本所需的全部会话、设置、插件资产和运行时状态，必须根据当前仓库版本与运行模式核验；官方资料没有授权你把一个固定目录当作跨版本备份接口。
官方持久化目录说明显示，SessionEvent 不是单纯的聊天文本。事件信封包含事件类型、单调递增的序号、时间、数据以及可选的未知事件跳过标记；其中还可能出现用户消息、助手消息、工具结果、审批、权限策略、模型请求上下文、压缩和重试等事件。(github.com)
这会带来三个现实限制：
- 只备份导出的聊天记录，可能丢失工具调用、审批决定、模型选择和可重放状态。
- 只复制某个事件目录，可能缺少会话索引、设置、插件配置或运行环境信息。
- 直接跨版本加载未知事件时，官方规则要求读取方在无法识别必需事件时拒绝重建，而不是静默丢弃。(github.com)
因此，备份前应形成一份“会话状态证据”：
- 当前 DeepSeek Harness 版本、提交号和运行模式。
- 会话总数，以及准备重点验收的会话 ID。
- 会话日志所在位置和实际文件格式。
- 是否存在正在运行的任务、未完成工具调用或审批请求。
- 复制前的停止写入时间点、文件清单和校验值。
会话日志与工作区必须一起迁移吗
如果目标是“继续执行原任务”，通常必须一起迁移，但不是把两者混成一个目录。会话日志回答“Agent 做到了哪一步”，工作区回答“那一步对应的是哪份代码和文件”。缺少任意一侧，都可能出现会话能打开却无法安全续跑的情况。
你至少要为每个重点会话建立对应关系：
- 会话 ID；
- 原工作区绝对路径；
- 仓库远程地址；
- 当前分支；
- 当前提交；
- 未提交改动是否存在；
- 本地独有文件和外部依赖；
- 恢复后的目标路径。
官方 Web UI 指南也要求先选择工作区，之后才能开始会话；Agent 可读取、编辑工作区文件并执行命令，涉及权限的操作还会触发审批。(github.com) 这意味着恢复时不能先给 Agent 写权限，再慢慢确认仓库路径。
SECTION 03工作区一致性：先证明不会写错仓库
云端 Mac 迁移最危险的故障，不一定是会话消失，而是会话恢复到了错误的工作区。比如本地有两个相似项目，迁移后目录名被改动，Agent 仍然读取旧的会话上下文，却把补丁写入另一个仓库。
建议你在备份证据包中加入以下内容：
git remote -v的输出；git branch --show-current的输出；git rev-parse HEAD的输出；git status --short的输出；- 未被 Git 跟踪但会影响构建的文件清单；
- 项目级指令文件、脚本和环境变量名称；
- 外部服务、数据库、模拟器或本地端口依赖说明。
恢复顺序应固定为：
- 创建全新的隔离工作区，不直接覆盖原目录。
- 先恢复仓库或检出目标提交。
- 核对远程地址、分支、提交和未提交差异。
- 再放入本地独有产物。
- 确认路径与会话映射正确。
- 最后才允许 Agent 获得写权限。
✅ 通过标准：Agent 读取到的项目根目录、分支和提交状态与迁移前证据一致。
❌ 拒收标准：会话可以打开，但无法证明它对应哪个仓库；或者恢复后工作区出现来源不明的文件。
如果你还没有把会话迁移流程固定下来，可以先参考 DeepSeek Harness 云端环境的使用入口，把“路径确认、权限确认、任务签收”作为同一条交付链处理，而不是分别找人补救。
SECTION 04配置、模型与插件：可复用不等于兼容
配置文件通常比会话日志更容易被忽略，因为复制后界面可能仍然能够启动。但启动成功只证明程序能够运行，不代表模型、工具、插件和项目指令都恢复正确。
你应分别核对：
- 用户级设置；
- 项目级设置；
- Provider 标识和模型路由；
- 插件启用列表；
- 插件配置；
- Skills；
- 项目指令文件；
- 沙箱、权限和审批策略；
- Node.js、包管理器及插件依赖版本。
官方文档把配置目录、持久化目录和插件架构分开描述；官方仓库还明确说明“所有内容都是插件”，并警告开发者预览阶段会发生兼容性破坏性变更。(github.com) 所以，不要因为旧版配置文件仍能被读取，就推断第三方插件可以直接复用。
可以使用下面的对照列表做决定：
- 重新安装软件：适合源码缓存、构建目录、可由锁文件恢复的依赖。优点是干净；缺点是需要重新核对版本和补丁。
- 复制配置后人工复核：适合设置、Provider 标识、插件参数和项目指令。优点是保留工作习惯；缺点是旧字段可能被新版本忽略。
- 直接复制插件资产：只有在当前版本文档和实际运行模式都确认兼容时才采用。否则应记录安装来源，在新环境重新安装并逐项启用。
- 整目录覆盖：不建议作为首选。它可能带入旧缓存、权限、临时状态和凭据残留，出问题后很难判断是哪一层导致失败。
SECTION 05凭据隔离：API Key 不应进入普通备份
API Key 不应放进普通备份文件，也不应为了方便把它写进项目压缩包、会话导出、插件配置快照或共享云盘。
你可以保存：
- 凭据引用名；
- 对应 Provider；
- 使用账号或责任人；
- 创建时间与轮换时间；
- 恢复时需要重新授权的位置；
- 恢复后如何验证调用成功。
你不应保存：
- 明文 API Key；
- 包含 Key 的
.env文件； - Shell 历史中的完整命令；
- 带 Key 的调试日志；
- 未清理的临时压缩包；
- 会话中由 Agent 读取并回显的密钥内容。
恢复时，先在隔离环境注入短期或已限制权限的凭据，再执行一次低风险模型调用。随后搜索备份目录、日志、脚本、终端历史和临时文件，确认没有残留。若密钥曾经进入普通备份包，应立即撤销并轮换，而不是仅仅删除压缩包。
SECTION 06六步恢复验收流程
下面这套流程适合升级、重装、云端 Mac 迁移和长期 Agent 工作区交接。每一步都要留下证据，不要只口头确认。
第 1 步：冻结写入
停止正在运行的会话、后台任务、插件进程和自动同步。记录停止时间，并确认没有新的事件继续写入。
如果无法完全停止，就建立明确的一致性边界，例如记录最后一个事件序号、文件修改时间和进程状态；无法建立边界时，备份只能标记为“非一致快照”。
第 2 步：建立资产清单
把四层资产分开列出：环境记录、会话状态、工作区产物、敏感凭据。对每个资产标注来源、用途、是否可重建、是否含敏感信息以及目标恢复位置。
不要在这一阶段追求固定目录全集。当前版本发生变化时，应以 官方持久化事件目录 和 官方配置目录说明 为准。
第 3 步：制作分离备份
普通备份包只放可重建环境记录、会话状态、工作区产物和脱敏配置。凭据单独加密传递，并使用不同权限控制。
为备份包生成文件清单和校验值，同时记录创建工具、创建时间、源环境和目标环境，避免交接人员拿到一个无法追溯来源的压缩包。
第 4 步：恢复到隔离副本
不要直接覆盖生产工作区。新建独立目录，安装与原环境匹配的运行时，再按“工作区 → 配置 → 会话 → 凭据”的顺序恢复。
官方 Web UI 默认监听 127.0.0.1:3080，该端口只说明服务入口，不代表会话、插件或工作区已恢复。(github.com)
第 5 步：执行三类检查
- 文件检查：重点会话文件可读取，事件顺序连续，配置和插件清单与证据包一致。
- 安全检查：普通备份中没有明文 Key，日志和脚本没有密钥残留，审批策略不是意外放宽。
- 关联检查：会话 ID、工作区路径、仓库远程地址、分支和提交状态全部对应。
第 6 步：执行一条可逆真实任务
选择不会破坏生产数据的任务，例如读取项目结构、运行只读测试、生成补丁但不自动提交。验收时必须同时证明：
- 会话可以打开；
- 模型可以调用；
- 工具可以执行；
- 工作区路径正确；
- Agent 只能执行授权范围内的操作；
- 审批仍然生效；
- 任务结果能在日志和工作区中互相对应。
只有文件检查和端到端任务都通过，才能把升级、迁移或云端 Mac 交付标记为“通过”。
SECTION 07验收签收边界与方案选择
交接时，建议把下面三类结果分开写入签收单：
✅ 通过：重点会话可恢复，工作区映射正确，模型与工具可调用，审批有效，凭据未进入普通备份。
⚠️ 有条件通过：会话可读取，但某些插件需重新安装，或部分非关键历史只能归档查看；必须写明限制和责任人。
❌ 拒收：只证明文件存在，没有真实任务；会话与仓库无法对应；出现明文凭据；或者恢复依赖未经验证的跨版本兼容性。
如果你当前设备没有足够空间、权限或隔离窗口来做恢复演练，临时使用一台云端 Mac 作为验证环境，往往比直接在原机升级更稳。自购 Mac 适合长期固定负载和需要物理接口的团队；现有 Windows、Linux 或共享云主机方案则常见路径差异、权限边界和环境漂移问题，尤其不适合把未经验证的长期 Agent 工作区直接当作生产资产。
对需要短期升级验证、迁移演练或交接测试的团队，租赁 MACNOX 的 Mac 环境可以把“新机器安装、隔离恢复、真实任务验收”拆成独立窗口，减少在现有设备上边升级边冒险的情况。你可以先查看 MACNOX 的 Mac 方案，再根据任务周期决定是临时验证、短期迁移，还是继续维护自己的长期环境。