# INSTALL — dsh-cross-session-bridge

一句话：`scripts/install.ps1` 一条命令装配；`scripts/uninstall.ps1` 对称卸载即净。
环境自包含：仅依赖 pnpm 与 dsh 自身，绝不修改系统环境；脚本只装配已有产物（含下载已有
Release 资产），绝不自动发布。

## 用户操作 = 一条命令

安装（release 模式需显式装配源；个人/验收最常用本地预编译 tgz）：

```powershell
# 本地预编译 tgz 装配（离线/验收首选）
.\scripts\install.ps1 -Mode release -ReleaseTgz .\dsh-cross-session-bridge-0.1.0.tgz
# 从 -ReleaseUrl 下载后装配（真实联网端用户）
.\scripts\install.ps1 -Mode release -ReleaseUrl https://<release>/dsh-cross-session-bridge-0.1.0.tgz
# 源码装配（构建本地 checkout 后链接注册）
.\scripts\install.ps1 -Mode source
```

卸载（对称，清理依赖/层表/dev-注入残留，幂等；交互询问是否清理用户配置与数据，默认保留）：

```powershell
.\scripts\uninstall.ps1
# 始终打印配置文件路径（settings.yaml 的 bridge 分区 + storages/bridge_state.json）；
# 交互询问"是否清理"，默认保留（输入 y 清理，回车保留）。
# 显式清理（无人值守/自动化）：
.\scripts\uninstall.ps1 -ForceClean
```

等价 pnpm 快捷入口：`pnpm plugin:install` / `pnpm plugin:uninstall`。

> 注：release 装配源 = `-ReleaseTgz`（本地）或 `-ReleaseUrl`（下载），脚本不自动推导 GitHub Releases
> 地址（插件仓库不在脚本中硬编码 ORG/REPO，避免不可达默认）——缺省必须显式给源。

## 模式与参数

| 参数 | 默认 | 说明 |
|---|---|---|
| `-Mode` | `release` | `source`=本地 checkout 链接装配（含构建）；`release`=装配预编译 tgz |
| `-Profile` | `web` | 目标 dsh profile 名 |
| `-ReleaseTgz` | `` | release：本地预编译 tgz 路径（离线/验收首选） |
| `-ReleaseUrl` | `` | release：下载 URL；脚本下载到临时目录后装配，用完即清（S2） |
| `-SourceDir` | 包根 | source：插件 checkout 目录 |
| `-SourceDshDir` | `` | 显式指定 dsh 源码版 harness checkout 根（经 `pnpm dsh`；优先于 PATH） |
| `-DshHome` | 继承 | 覆盖 DSH_HOME（仅作用于本次读取/子进程，不改用户全局） |
| `-SkipVerify` | off | 跳过装配后验证 |

安装用例：

```powershell
# 源码装配（构建 lib/ 后链接注册）
.\scripts\install.ps1 -Mode source
# release：本地 tgz 装配（验收/离线）
.\scripts\install.ps1 -Mode release -ReleaseTgz .\dsh-cross-session-bridge-0.1.0.tgz
```

## 依赖

- **pnpm**：必须可用；缺失时报错并提示安装。release 装配要求 pnpm（`dsh plugin` 内部经 pnpm 管理 profile）。
- **dsh**：发布版需 `dsh` 在 PATH；源码版需 `-SourceDshDir <harness checkout>`（经 `pnpm dsh`）。脚本自检两者并引导。
- source 模式构建工具（tsc/tsdown）**只读复用 dsh 自带运行时**（源码版 checkout 或发布版安装的 node_modules/.bin），不向系统全局安装。

## 底层机制

配套脚本复用 harness `dsh plugin --profile <name> <pnpm-verb>`：它负责 profile 初始化、pnpm 装配
（`add` 本地 checkout / tgz / 下载 URL），并按已安装包是否声明 `dsh.bundle` 自动对账 `dsh.profile.bundles`
层表；`remove` 同时移除依赖与层。脚本在其上做构建、装配源解析、幂等判定与验证。

## 验证 / 排查

- 安装后用 `dsh --profile web --dump-config` 应看到本插件的补丁行；工具 `bridge_send` 可用 = 装配成功。
- `bridge_send` 返回拒绝回执 = 目标离线；工具缺失 = 装配未成功 / fiber 未加载。
- 重复安装/卸载均为幂等无副作用；插件残留排查（依赖/层表/disabled 条目）见
  `tests/regression/scripts.spec.ts`。