# 一行安装与发布

## 给使用者

在 Windows 10/11 x64 的 PowerShell 中执行发布者提供的一行命令。无需 Git、.NET SDK 或源码编译。安装器会复用兼容的 Node/DSH；缺少环境时，在 `%LOCALAPPDATA%\DSHPet` 准备专用运行环境和 pnpm，不修改机器 PATH。

v0.3.0 的公开安装入口位于 GitHub Releases：

```powershell
& ([scriptblock]::Create((irm 'https://github.com/comfylies/dsh-png-pet/releases/download/v0.3.0/install.ps1')))
```

安装完成后，双击桌面的 `DSH Pet`。第一次使用，从桌宠菜单打开 DSH，按 DSH 界面配置自己的模型凭据、工作区和会话。安装器不处理模型密钥，不自动启动 Host，也不自动设置开机启动。已有 DSH Host 必须重启才会加载更新。

同一条命令可重复运行：已安装同版时修复启动入口；版本不同则下载、校验再安装。更新前正常退出 DSH 和桌宠；安装器不结束用户进程。下载失败不会先移除旧插件。有匹配且校验通过的旧安装包时，安装失败会尝试恢复；恢复失败会明确提示，不声称安装成功。

### 参数

下载 `install.ps1` 后也可以运行文件，不必使用在线脚本入口：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Manifest .\release.json
```

| 参数 | 用途 |
| --- | --- |
| `-Manifest` | HTTPS release.json 地址或本地文件路径；没有发布地址时必须提供 |
| `-InstallRoot` | 专用安装目录，默认 `%LOCALAPPDATA%\DSHPet` |
| `-DshEntry` | 指定已有 DSH 包的 `lib\bin.js`，用于非标准安装位置 |
| `-Profile` | 目标 DSH profile，只能是 `web`（默认）或 `desktop`；Desktop 模式安装后需完全退出再重新打开 DSH Desktop |
| `-UsePrivateDsh` | 显式使用专用 DSH 和独立 DSH_HOME；不升级已有不兼容 DSH |
| `-NoShortcut` | 不创建桌面快捷方式，仍生成 `launcher\launch.vbs` |
| `-Uninstall` | 经 DSH CLI 移除桌宠及本安装器的桌面快捷方式；保留 DSH、会话、凭据、运行环境和缓存 |

在线入口也可传参数：

```powershell
& ([scriptblock]::Create((irm 'https://github.com/comfylies/dsh-png-pet/releases/download/v0.3.0/install.ps1'))) -UsePrivateDsh -Profile desktop
```

如果此安装目录已关联另一套 DSH，选择新的 `-InstallRoot` 再创建独立环境，避免丢失原安装的管理入口。安装器只读写自身安装元数据；DSH profile 的插件变更全部通过 DSH CLI 完成。

## 给发布者

执行以下命令完成 Node/C# 测试、自包含 Helper 构建、打包测试和发布产物生成：

```powershell
npm run package:release
```

`dist\packages` 中会生成：

```text
install.ps1
release.json
dsh-png-pet-0.3.0.tgz
```

无发布地址时，先用本地清单在测试电脑安装：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\dist\packages\install.ps1 -Manifest .\dist\packages\release.json
```

本地清单只让桌宠包从本地读取；缺少 Node/DSH/pnpm 及安装插件依赖时仍需要网络，不是完全离线安装包。

确定发布目录后，传入 HTTPS 目录地址（示例地址需替换）：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\package-release.ps1 -BaseUrl https://example.com/dsh-pet/0.3.0
```

把生成的三个文件上传到该目录即可。生成器会把 `release.json` 地址写进发布版 `install.ps1`，并打印发布后可使用的一行命令。仓库源码中的安装器不写死域名。

如果包已验证，后续仅配置地址不需要重新编译：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\new-installer-release.ps1 -ArchivePath .\dist\packages\dsh-png-pet-0.3.0.tgz -Destination .\dist\packages -BaseUrl https://example.com/dsh-pet/0.3.0
```

使用固定版本目录；先上传包和清单，最后发布安装入口。更新到新版本时更换目录，不替换已经发布版本的包内容。发布目录访问者可以运行其中代码，因此发布者必须控制入口与清单；SHA-256 用来确认下载内容匹配清单，不能替代对发布源的信任。

依赖组合在 `scripts/installer-versions.json` 中声明，目前是 Node 24.15.0、DSH 0.2.0-rc.2、pnpm 11.23.0。仅复用 24.x 且不低于指定版本的 Node，DSH 则要求精确版本。新的组合应在测试电脑上验证后更新。DSH 的传递 npm 依赖仍按其包声明解析，不承诺完整依赖闭包锁定。

## 验证

`npm test` 包含 PowerShell 5.1 行为测试：清单/哈希拒绝、环境恢复、路径引用、重复安装、失败恢复、互斥及卸载保留缓存。测试对 DSH 变更使用替身，不触碰用户 profile。

需要真实 DSH/pnpm 的隔离路径测试时，给出所用 Node、DSH JS CLI 和 pnpm JS CLI：

```powershell
.\test\installer-dsh-smoke.ps1 -Node '<node.exe>' -Dsh '<DSH包>\lib\bin.js' -Pnpm '<pnpm包>\bin\pnpm.cjs'
```

该测试使用项目 `.dsh-test` 内的临时 DSH_HOME 和无依赖测试插件，覆盖中文、空格、括号、`&` 和 `%` 路径，测试后清理。最终公开发布前，还应在全新 Windows 10/11 x64 用户环境验证依赖下载、快捷方式启动、首次模型配置和升级恢复。