dsh-quick-restart-desktop

Readme

# dsh-quick-restart-desktop

DSH Desktop「快速重启」插件，两个能力：

1. **重启 DSH Desktop 应用本体**（当前 profile 不变，应用 relaunch）—— 走 launcher
   的 `desktopRuntime.requestRestart()`（与桌面「安装更新后重启」同一条安全路径：
   标记 relaunch → 干净关停 generation → `app.relaunch()`）。
2. **切换 profile 并重启** —— 走官方 `desktopProfiles.select()` 契约。

## 功能

| 入口 | 说明 |
| --- | --- |
| 设置 →「快速重启」面板 | 当前 profile 行 = 「重启 DSH Desktop」主按钮（重启本体）；其他行 = 「切换并重启到此 profile」 |
| 独立页面 `/desktop-restart` | 同样的面板 + 「重启 DSH Desktop」主按钮（浏览器直接打开） |
| 命令 `/desktop-restart` | **重启 DSH Desktop 应用本体**（无参，profile 不变） |
| 命令 `/desktop-restart <profile>` | 切换并重启到指定 profile |
| 命令 `/desktop-profiles` | 列出当前 profile 与全部可发现 profile（含可选择性） |

## 契约说明（重要）

两条路径、两套契约：

- **重启应用本体**：`desktopRuntime.requestRestart()`。`desktopRuntime` 在
  [`plugin-development.md`](https://github.com/anywhere-labs/deepseek-harness-desktop/blob/master/docs/plugin-development.md)
  中被列为**内部接口**（不属于第三方兼容 contract，升级可能有变化）——但它是当前版本下
  「重启应用本身」的唯一路径（同 profile 的 `desktopProfiles.select()` 被服务层刻意
  定义为 no-op）。插件做了降级：若未来版本移除该服务，重启本体路径如实报错，
  切换重启不受影响。
- **切换 profile 并重启**：`desktopProfiles.select(name)`，官方契约。
  只接受**可选** profile（存在、`webCapable`、无 `problem`），非法目标明确报错。
- 重启请求一旦受理，进程立即退出 —— 插件在受理后马上返回响应，不等待进程结束。

## 与系统托盘的关系

DSH Desktop 托盘**已内置** profile 切换：托盘菜单 `Profile: <当前 profile>` 子菜单
（launcher 自带的 `desktop-profiles` 插件）选中其他 profile 即安全重启。托盘
注册表本身（`desktopRuntime.registerTrayItem`）是内部接口，第三方插件不应注册
托盘条目——本插件不碰托盘，入口统一在设置页 / 独立页面 / 命令。

## 兼容性

在普通 `dsh web`（无 `desktopProfiles`）中，本插件**正常加载但不挂载任何功能**
（满足 [`plugin-development.md`](https://github.com/anywhere-labs/deepseek-harness-desktop/blob/master/docs/plugin-development.md)
的测试要求：没有 Desktop service 时仍能加载）。

## 安装（官方装配路径）

```bash
# 在 DSH Desktop 终端（或任何 dsh CLI）中，针对 desktop profile：
dsh plugin --profile desktop add "link:D:/workspace/dsh-quick-restart-desktop"
# 或等价的 pnpm 写法（会自动加入 dsh.profile.bundles 并应用 cordis.patch.yml）
```

然后**重启 DSH Desktop**，插件随下一次 Loader 组合激活
（插件变更后需要重启才能进入组合 —— 这正是本插件解决的场景）。

等效的手动装配（不经过 CLI 时的最终状态）：

1. `pnpm --dir ~/.dsh/profiles/desktop add "link:D:/workspace/dsh-quick-restart-desktop"`
2. 在 `~/.dsh/profiles/desktop/package.json` 的 `dsh.profile.bundles` 追加
   `"dsh-quick-restart-desktop"`。

## 卸载

```bash
dsh plugin --profile desktop remove dsh-quick-restart-desktop
```

## 开源协议

[MIT License](./LICENSE)。版权归 dsh-quick-restart-desktop contributors 所有；
如需署名自己的名字/组织，修改 `LICENSE` 文件顶部的 Copyright 行即可。

## 包结构

```
package.json         # dsh.bundle.patch（cordis.patch.yml）+ dsh.client（设置页）
cordis.patch.yml     # 向组合插入一行宿主插件
index.js             # Host：命令 + /desktop-restart 路由 + JSON API（ESM，零依赖）
client.js            # Client：设置页「快速重启」面板（__ModuleLoader__ 格式，零依赖）
README.md
test/harness.mjs     # 24 项逻辑自检（node test/harness.mjs）
```

## 行为细节

- `POST /desktop-restart/api/restart`：body `{ profile?: string }`。
  无 profile 或 = 当前 profile → 重启应用本体（`desktopRuntime.requestRestart`）；
  其他 profile → 校验后 `select()` 切换重启。均 fire-and-forget 立即返回「已受理」，
  错误路径返回 400 + 原因；body 超过 64 KiB 返回 413。
- `GET /desktop-restart/api/state` 返回 `{ current, profiles[] }`，供面板轮询。
- 所有命令与路由均通过 `ctx.effect` 注册，插件卸载即全部释放。
- **安全边界**：API 无鉴权，但 webServer 仅绑定回环（127.0.0.1），且重启请求要求
  JSON content-type（跨源表单无法触发，CSRF 免疫）；本机进程本可自行结束桌面，
  不构成新增攻击面。

## 客户端组件契约（踩坑记录）

`ctx.slots.register(options, Component)` 的 **Component 必须是 React 函数组件**
（渲染器直接 `jsx(Comp, props)` 渲染）。早期版本把组件写成
`options.component = () => ({ render(){} })` 的普通 DOM 工厂——渲染器拿到
`undefined` 组件导致渲染崩溃，slot 系统把条目标记为 **abdicated**（退休），
表现就是「设置卡片存在但内容空白」。`client.js` 现按要求使用
`React.createElement` 构建的 React 函数组件（`require("react")`）。