# 安装、升级与卸载

项目已采用 **DSH Sessivra / DSH Sessivra 协作空间** 名称。当前版本使用 `dsh-plugin-sessivra`，其安装和跨包名迁移见 [改名与迁移](RENAMING.md)。本文命令用于已发布的新包；已安装dev.19 scoped 包、原信使包或 Agent Hub 包时，先按迁移说明移除对应旧包。

当前分发版本 0.3.0-dev.26，宿主固定为 DSH 0.2.1-rc.5。Node.js 24+；桌面版优先使用其安装目录下的 `resources/runtime/cli/bin/dsh.cmd`。先运行 `dsh --version` 核对；全局旧版 CLI 不应代替桌面程序自带的 CLI。

## 安装

### DSH 界面安装

在「插件 → 添加插件」输入框中，选择 npm 官方源，只填写包名，不加引号：

```text
dsh-plugin-sessivra@0.3.0-dev.26
```

DSH rc.5 自带 pnpm 的默认发布时间保护为 24 小时。新版本发布首日，仅填裸包名可能仍安装较旧版本；使用上面的固定版本可明确选择 dev.26，安装后核对版本。无需关闭全局保护。

点击「安装」，完成后按界面提示重启或重新加载。若出现 `not a package name the registry accepts`，先检查是否误把整条 `dsh plugin ...` 终端命令粘贴到了输入框。

### 终端安装

以下命令在 PowerShell、CMD 或其他终端中执行，不能整行填入「添加插件」窗口。

正常退出使用目标 profile 的 DSH。安装命令使用官方 bundle 机制：

```sh
dsh plugin --profile desktop add "dsh-plugin-sessivra@0.3.0-dev.26"
```

或者安装 Release 压缩包：

```sh
dsh plugin --profile desktop add "https://github.com/leoan698-tom/dsh-sessivra/releases/download/v0.3.0-dev.26/dsh-plugin-sessivra-0.3.0-dev.26.tgz"
```

已有本地压缩包时，把来源换成 `file:/绝对路径/dsh-plugin-sessivra-0.3.0-dev.26.tgz`。Web profile 使用 `--profile web`。自定义 DSH_HOME 应与实际宿主一致。CLI 会交给包管理器安装依赖，并在 profile 的 bundle 清单中注册插件。包包含 `dsh.manifestVersion: 1`、`dsh.bundle.patch`、`./client` 和编译产物。

安装后启动 DSH，在插件列表确认版本及启用状态。正常入口是输入框原生 `@` 和原生工作区列表。工作区标题、搜索、视图选项和添加工作区由宿主管理，主会话有子节点时直接显示展开箭头。

## 使用与自查

在 A 的输入框 `@` 选择 B，并明确说明参考、派任务或发送结论。仅参考不会唤醒 B；多引用时明确收件对象。关联回复来自接收对象显式调用消息回复工具。实际发送仍复核归属、工作目录、拒收设置、时效及去重。

- 找不到插件：检查 CLI 版本、DSH_HOME、profile 名称、安装命令退出状态及插件启用状态。
- 看不到子节点：展开对应工作区，确认插件启用并等待一次刷新。宿主须为 rc.5；其原生行结构不匹配时保留原生列表，不覆盖工作区栏。
- 只有上下文、没有发送：检查是否明确要求通信；一次性对象及其他主会话的子智能体只能引用。
- 引用失效：重新 `@` 对象；不从摘要里的名称猜测 ID。
- `uncertain`：先核查目标及原消息状态，不自动换 ID 重发。
- 版本不兼容：使用匹配版本，不通过版本豁免绕过本项目的宿主约束。

## 升级和回退

dev.25 包含受管任务协议，沿用 dev.24 的独立 `dsh_sessivra_tasks` 域。更新保留任务、共同决定和会话关系；启动不自动唤醒模型。回退到 dev.20 前须结束或暂停受管任务并备份新域，旧版不能继续新任务协议。详见[任务协作恢复说明](MANAGED_TASKS.md)。

升级前正常退出宿主，备份目标 profile 配置及对应的 Messenger 存储，并保留旧安装包。备份含消息正文和工作目录，留在本地。安装新版本后重启，并核对插件版本。

dev.20 npm 安装名及 dev.19 改名均不改变持久 schema，可回退至保存的 dev.19、dev.18 或 dev.17 包。dev.17 调整原生侧栏集成，通信功能及数据 schema 沿用 dev.15；可用原 dev.15 包回退。dev.14/dev.15 同样无新增持久字段。dev.13 新增 child 通信字段，回退 dev.12 或更早版本需要与旧包匹配的升级前存储备份，不能直接让旧版读取新字段。回退不撤回已经进入会话历史的消息。

## 禁用和卸载

在宿主插件列表禁用本插件可保留数据。卸载时正常退出目标宿主，再执行：

```sh
dsh plugin --profile desktop remove dsh-plugin-sessivra
```

重启后插件工具和会话树入口移除。卸载包不会主动删除 Messenger 存储，也不会删除宿主会话历史。重新安装可能继续读到此前的消息和许可。若确需删除数据，先备份并退出宿主，再定位实际存储后端里的 `dsh_session_messenger` 单元；不得删除整个 profile 或其他会话数据。