# 安装、配置与卸载

此说明对应 0.5.0-rc.1 公开测试版。新电脑可按步骤试装；已有个人安装不要直接覆盖。换机全流程尚需用户实测，已经通过的隔离配置与程序契约检查不代替真实环境验收。

## 环境

- Windows；DSH Desktop **0.2.0-rc.2**。`engines.dsh` 故意限定已核验版本。
- 后台使用 **Node 24.2+**（已测 24.21，包含 SQLite 和 Zstandard 支持）。
- Codex 来源需本机安装、登录 Codex，并可运行 `codex app-server`；程序路径不同可通过 `TASK_MAP_CODEX_EXE` 指定。
- WorkBuddy 目录来源需本机有效数据；状态需额外安装 `integrations/workbuddy`。

## 首次安装

从项目 GitHub Releases 取带校验值的 `.tgz`，在 DSH 插件安装入口选择本地包；或者使用官方 CLI：

```powershell
dsh plugin --profile desktop add "<下载位置>/dsh-runtime-map-0.5.0-rc.1.tgz"
```

尖括号为需要替换的值，不要原样运行。DSH 的 profile 与包路径以安装回执为准，不假定人人都在 `desktop`。官方安装器管理依赖和 bundle，勿手改 profile 或复制整套他人的 `.dsh`。

当前候选还需**一次后台配置**，这不是已经实现的市场零配置安装。先关闭 DSH 以完成新插件安装；用 Node 24.2+ 运行安装包内的配置脚本，明确指定已安装插件目录和一个全新的后台目录：

```powershell
node "<已安装插件>/scripts/setup-backend.mjs" --plugin "<已安装插件绝对路径>" --service "<用户数据目录绝对路径>/runtime-map-service"
```

默认只显示计划。核对路径后加 `--apply` 执行同一命令。脚本复制包内后台，记录当前 Node 路径，生成本机专用 `backend-runtime.json`；不启动应用、不读写画布/聊天、不修改来源应用配置。已有配置或后台目录一律拒绝覆盖，不能把旧安装当新安装重做。

重新打开 DSH 和 Runtime Map。以后打开地图由插件自动启动后台，无需 Codex 或手动 `start.cmd`。换 Node 路径后需检查本机配置；不要发布这个包含绝对路径的文件。

## 来源设置

配置进程可继承的环境变量，重启相关进程后生效：

| 配置 | 用途 | 默认 |
| --- | --- | --- |
| `CODEX_HOME` | 本机 Codex 元数据/日志目录 | 用户目录下 `.codex` |
| `TASK_MAP_CODEX_EXE` | Codex CLI 可执行路径 | PATH 中的 `codex` |
| `TASK_MAP_WORKBUDDY_HOME` | WorkBuddy 本机数据位置 | 用户目录下 `.workbuddy` |
| `TASK_MAP_WORKBUDDY_USER_ID` | 多账号目录明确选定一个账号 | 只有一个账号时自动采用；多账号不猜 |

`RUNTIME_MAP_STATUS_EVENT_DIR` 是隔离测试参数，正常安装不要设置。打开地图后“同步目录”，使用来源同步 Skill 的 `status` 回读接入情况。不要为了验收向真实会话发测试消息。

WorkBuddy 观察器及 Codex 可选 Hook 的安装说明各自在 `integrations/*/README.md`。地图插件不自动安装它们，也不会自动批准来源应用的 Hook 信任请求。

## 常见问题

- `BACKEND_NOT_CONFIGURED`：检查一次配置是否完成、Node 和后台目录是否仍存在。
- `BACKEND_PORT_CONFLICT`：43140 被其他服务占用；先确认占用者，不强杀进程，也不要把后台暴露到公网。
- `APP_SERVER_START_FAILED`：后台进程找不到 Codex CLI；核对环境路径，不影响 DSH 原生会话使用。
- `WORKBUDDY_ACCOUNT_REQUIRED`：明确选择账号后重试，不合并多个账号。
- “状态未接入”：目录存在不等于状态接入；先读状态诊断，云端 ChatGPT/Work 当前无法接入。
- Hook 已装但未显示：需来源原生应用加载它、正常产生匹配身份的事件；安装文件存在不等于 Hook 生效。
- Skill 通道未连接：先打开 DSH 并加载插件。不要打印 `.dsh/runtime-map/control.json` 的令牌。

## 升级、回滚与卸载

首次配置脚本**不是升级器**。RC 阶段升级先备份：插件包版本、后台代码/本机配置、后台 `data`，以及 DSH 对应 profile 的 Runtime Map 存储。聊天历史另外备份；升级程序不得覆盖它。

插件代码更新通常需 DSH 重新加载；仅改画布或同步目录不需要。后台更新只停止经过本机所有权核验的实例，等待写入结束，再换代码并保留 `data/work`，禁止按任意 PID 强杀。当前没有公共自动迁移/升级脚本，须完成发布清单中的升级演练后才能宣称支持一键升级。

出现问题时恢复上一份插件及后台代码，保留当前数据；若涉及数据结构迁移，按版本对应备份恢复，不能让旧程序盲写新格式。

通过 DSH 官方插件管理器移除插件即可停用入口；附属 Hook 在原生应用单独停用。本地后台可能独立存活，需通过已认证的服务控制通道停止。卸载不主动删除画布、登记或原生历史；不提供“清空全部应用数据”的命令。

[DSH 官方插件发布/安装说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)