dsh-reload-buttons 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-reload-buttons contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,83 @@
+# dsh-reload-buttons
+
+<img src="assets/icon-180.png" width="96" align="right" alt="dsh-reload-buttons">
+
+[中文](README.md) | **English**
+
+Two icon buttons in the top-left corner of the DSH header: **reload the UI** and **restart the app**. No more closing the whole application by hand after changing a plugin or a config.
+
+## What each button does
+
+| Button | Desktop app | `dsh web` |
+|---|---|---|
+| Reload | Manifest still valid → full page reload; manifest stale → re-align client plugins in place against the host's current graph, no reload, no closing the app | Same |
+| Restart | Close the shell (the Electron main process) → the kernel shuts down cleanly when its IPC disconnects → a detached script relaunches the exe, retrying once if it does not stay up | End the kernel process; bring-up is up to your process manager |
+
+### Why reload has two paths
+
+On the desktop app, a page reload uses the client-plugin manifest **snapshotted when the kernel started** — the main process only knows that copy. After a client plugin changes, the bundle URLs in that snapshot 404, so a full reload ends in a blank page plus a recovery dialog.
+
+The button therefore probes every bundle in the snapshot first: if all of them still resolve, it reloads; if not, it re-aligns the client plugin entries in place — it takes the current graph from the first frame of the host's `/plugins/events` and calls `entries.sync`, without any prompt and without closing the app (only a failed re-sync tells you to use Restart). A full teardown still goes through Restart.
+
+### Why restart closes the shell first
+
+The desktop app treats any kernel exit as a fatal failure: if the kernel exits on its own, the main process shows the "app is unusable" dialog. The other direction works — once the Electron main process is gone, the kernel's IPC disconnect triggers its own graceful shutdown, and nothing is left to show a dialog; the detached script then relaunches the exe.
+
+## Install
+
+```sh
+dsh plugin --profile desktop add github:taoziliyouchong/dsh-reload-buttons
+```
+
+Once published to npm, this also works:
+
+```sh
+dsh plugin --profile desktop add dsh-reload-buttons
+```
+
+Restart DSH afterwards. Replace `desktop` with your own profile name if you use another one.
+
+Requirements: the DSH desktop app (the restart button needs the shell to close and relaunch). On `dsh web` the reload button works and restart just ends the kernel process. Node follows DSH; no extra runtime is needed.
+
+Compatible with DSH 0.2.1-rc.5 (tested); 0.3 and later are not guaranteed.
+
+## Where the buttons live
+
+They are mounted at `conversation.header.leading` — the left-most slot of the conversation header, a `single` slot currently owned by this plugin. Registering the same slot twice at the same priority throws, so this plugin cannot be installed alongside another one that claims that exact slot. To move them, see the comment at the top of `src/entry.jsx` (`conversation.session.header.utilities` is a `list` slot).
+
+## How it works
+
+- The host half registers `POST /dsh-reload-buttons/api/restart`: loopback addresses only (`127.*`, `::1`, `::ffff:127.*`) and POST only. On a DSH reachable from other machines, the restart call is rejected with 403.
+- On the desktop app the restart is handed to `assets/restart-app.mjs` (detached spawn): wait 1.2 s so the HTTP response reaches the browser → close the Electron main process → wait for the port to be released (kill the kernel if it is not, after 12 s) → launch the exe and watch its new process pid (retry once if it does not stay up for 8 s).
+- The desktop app uses a different port on every start, so liveness is checked by process pid, never by port.
+- The restart log is written to `$DSH_HOME/logs/dsh-reload-buttons-restart.log`.
+- The reload button is purely client-side; it needs no host support.
+- No network access, nothing uploaded.
+
+## Known limits
+
+- Non-desktop installs have no shell to close: restart only ends the kernel process, and bringing it back depends on how you start it.
+- The window closes during a restart and comes back a few seconds later. If a recovery dialog with a "Restart" button shows up at the same time, using it works too.
+- Local only: requests from anything other than loopback are not handled.
+
+## Development
+
+The source has two halves:
+
+- `index.js` — host side (route, hand-off, shutdown)
+- `src/entry.jsx` — browser side (the two buttons, the reload probes, the in-place re-sync)
+
+Editing `src/entry.jsx` requires rebuilding. `lib/client.js` is a build artifact committed to the repository; without it the UI does not load:
+
+```sh
+npm install
+npm run build:client    # regenerate lib/client.js
+npm run check:client    # verify the committed artifact matches the source
+npm run smoke           # structure / registration / authorization / artifact
+```
+
+Build rules: keep `react` and `react/jsx-runtime` external (the DSH client module table provides them); the `id` inside the `window.__ModuleLoader__.load({ id, factory })` envelope must equal the package name.
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# dsh-reload-buttons
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/icon-180.png" width="96" align="right" alt="dsh-reload-buttons">
+
+**中文** | [English](README.en.md)
+
+在 DSH 界面左上角放两个图标按钮：**刷新界面**、**重启应用**。改完插件或配置不用再手动关掉整个应用。
+
+## 两个按钮各自做什么
+
+| 按钮 | 桌面端 | `dsh web` |
+|---|---|---|
+| 刷新 | 清单没过期 → 整页重载；清单过期 → 就地按宿主当前图对齐客户端插件，不重载、不关应用 | 同左 |
+| 重启 | 关掉界面壳（Electron 主进程）→ 内核随 IPC 断开优雅收尾 → 独立脚本把 exe 拉起来，起不来再试一次 | 结束内核进程，重开交给你的启动方式 |
+
+### 刷新为什么分两路
+
+桌面端重载页面用的是**内核启动那一刻**拍的客户端插件清单快照（主进程只认那一份）。改过客户端插件后，快照里的 bundle 地址已经 404，整页重载就是白屏加恢复框。
+
+按钮的做法：先探一遍快照里的 bundle 是否都还取得到。全都取得到就真重载；取不到就改为就地重同步——从宿主 `/plugins/events` 首帧取当前图，用 `entries.sync` 对齐客户端插件条目，成功时不提示、不关应用（重同步本身失败才会提示改用「重启」）。彻底重来仍走「重启」。
+
+### 重启为什么先关界面壳
+
+桌面端把内核退出一律当致命故障：内核自己 exit，主进程会弹「应用无法使用」。反过来，Electron 主进程一消失，内核的 IPC 断开会触发它自己的优雅收尾，此时也没有进程能弹框；随后独立脚本把 exe 重新拉起。
+
+## 安装
+
+```sh
+dsh plugin --profile desktop add github:taoziliyouchong/dsh-reload-buttons
+```
+
+发布到 npm 之后也可以：
+
+```sh
+dsh plugin --profile desktop add dsh-reload-buttons
+```
+
+装完重启 DSH。用别的 profile 就把 `desktop` 换成你的 profile 名。
+
+要求：DSH 桌面端（重启按钮要关壳重开）。`dsh web` 下刷新可用，重启等于结束内核进程。Node 版本跟随 DSH，不需要额外运行时。
+
+兼容：DSH 0.2.1-rc.5 实测通过；0.3 起不保证。
+
+## 界面位置
+
+按钮挂在会话头部最左的 `conversation.header.leading`——一个 single 槽，当前由本插件占用。同优先级二次注册会抛错，不能和同样占这个座位的插件一起装。要换位置见 `src/entry.jsx` 顶部注释（`conversation.session.header.utilities` 是 list 槽）。
+
+## 机制
+
+- 宿主半边注册一条 `POST /dsh-reload-buttons/api/restart`：只接受回环地址（`127.*`、`::1`、`::ffff:127.*`），只接受 POST。远程访问的 DSH 上点重启会被 403 拒绝。
+- 桌面端把重启交棒给 `assets/restart-app.mjs`（detached spawn）：等 1.2 秒让 HTTP 响应交回浏览器 → 关掉 Electron 主进程 → 等端口释放（12 秒不放就结束内核）→ 拉起 exe 并按新进程 pid 探活（8 秒不稳就再试一次）。
+- 桌面端每次启动端口都不同，探活只看进程 pid，不看端口。
+- 重启日志写在 `$DSH_HOME/logs/dsh-reload-buttons-restart.log`。
+- 刷新按钮是纯浏览器侧行为，不需要宿主。
+- 不联网、不上传任何内容。
+
+## 已知限制
+
+- 非桌面端没有界面壳可关，重启按钮只结束进程，重开取决于你的启动方式。
+- 重启时界面会关掉，几秒后自动回来；若同时弹出带「重启」按钮的恢复框，点它也可以。
+- 只对单机有效：回环地址以外的请求不处理。
+
+## 开发
+
+源码分两半：
+
+- `index.js` —— 宿主半边（路由、交棒、退出）
+- `src/entry.jsx` —— 浏览器半边（两个按钮、刷新自检、就地重同步）
+
+改过 `src/entry.jsx` 必须重新打包。`lib/client.js` 是提交进仓库的构建产物，缺了它界面不会加载：
+
+```sh
+npm install
+npm run build:client    # 重新生成 lib/client.js
+npm run check:client    # 比对新产物与已提交产物是否一致
+npm run smoke           # 结构 / 注册 / 鉴权 / 产物 四关
+```
+
+打包要求：`react` 与 `react/jsx-runtime` 保持 external（由 DSH 客户端模块表提供）；产物外壳 `window.__ModuleLoader__.load({ id, factory })` 里的 `id` 必须等于包名。
+
+## 许可
+
+MIT

package/assets/restart-app.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * 一键重启的「接手脚本」——被宿主进程 detached 起来，独立于 dsh 活着。
+ *
+ * 背景：桌面端把内核（宿主）退出一律当致命故障（main.js 里 child.once('close') 无条件 fail），
+ * 所以内核自己退出必然弹「应用无法使用」那张框，插件侧绕不过去。
+ * 但反方向可行：**先关掉界面壳（Electron 主进程）**，内核会收到 IPC 断开并走自己的优雅收尾
+ * （dsh-desktop-host/lib/index.js 里 process.once('disconnect', () => stop())），
+ * 主进程一死也没有任何东西会弹框；随后本脚本把 exe 重新拉起来。
+ *
+ * 参数：node restart-app.mjs <主进程PID> <exe路径> <宿主PID> <端口> <日志文件>
+ */
+
+import { spawn } from 'node:child_process'
+import { connect } from 'node:net'
+import { appendFileSync } from 'node:fs'
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+const [parentPid, exePath, hostPid, portArg, logPath] = process.argv.slice(2)
+const port = Number(portArg || 19387)
+
+function log(line) {
+  try {
+    appendFileSync(logPath, `${new Date().toISOString()} ${line}\n`)
+  } catch {
+    /* 日志写不进去不影响重启 */
+  }
+}
+
+function portOpen() {
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port })
+    const done = (value) => {
+      socket.destroy()
+      resolve(value)
+    }
+    socket.once('connect', () => done(true))
+    socket.once('error', () => done(false))
+    setTimeout(() => done(false), 800)
+  })
+}
+
+function kill(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return
+  try {
+    process.kill(pid)
+  } catch (error) {
+    log(`kill ${pid} failed: ${error.message}`)
+  }
+}
+
+log(`start parent=${parentPid} host=${hostPid} exe=${exePath}`)
+
+// 1) 等宿主把 HTTP 响应交回浏览器（否则按钮会看到连接被掐断）
+await sleep(1200)
+
+// 2) 关掉界面壳。主进程一没有，内核的 IPC 断开会自动走优雅收尾，也没有东西能弹恢复框。
+kill(Number(parentPid))
+
+// 3) 等端口释放（内核收尾 + 退出）；12 秒还不放就补一刀内核，避免新实例撞端口起不来
+let released = false
+for (let i = 0; i < 24; i += 1) {
+  await sleep(500)
+  if (!(await portOpen())) {
+    released = true
+    break
+  }
+}
+if (!released) {
+  log('port still busy after 12s, killing host')
+  kill(Number(hostPid))
+  for (let i = 0; i < 12; i += 1) {
+    await sleep(500)
+    if (!(await portOpen())) {
+      released = true
+      break
+    }
+  }
+}
+log(`port ${released ? 'released' : 'STILL BUSY'}`)
+
+// 4) 重新拉起应用
+if (!exePath) {
+  log('no exe path, stop')
+  process.exit(1)
+}
+/**
+ * 拉起应用。**必须把 ELECTRON_RUN_AS_NODE 从环境里摘掉**：
+ * 本脚本自己就是靠这个变量跑在 Electron 的 Node 模式下的，直接继承下去，
+ * 被拉起的 exe 也会以 Node 模式启动（没有脚本参数 → 立刻退出），
+ * 症状是「应用关掉了、但一直没回来」。
+ */
+function launchApp(label) {
+  const env = { ...process.env }
+  delete env.ELECTRON_RUN_AS_NODE
+  const child = spawn(exePath, [], { detached: true, stdio: 'ignore', windowsHide: false, env })
+  child.unref()
+  log(`${label} spawned exe pid=${String(child.pid)}`)
+  return child
+}
+
+/** 进程还在不在。桌面端每次启动都是**新端口**，用旧端口探活只会得到假失败。 */
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** 等进程稳定活着：先等 2.5 秒（撞单实例锁的实例这时已经退了），再等到总时限复查一次。 */
+async function waitAlive(pid, ms) {
+  const early = Math.min(2500, ms)
+  await sleep(early)
+  if (!alive(pid)) return false
+  await sleep(Math.max(0, ms - early))
+  return alive(pid)
+}
+
+const first = launchApp('first launch')
+
+// 5) 起来了吗？起不来就再试一次（第二次失败只能让用户手动开）
+if (await waitAlive(first.pid, 8000)) {
+  log(`ok: app is back (pid ${first.pid} alive)`)
+  process.exit(0)
+}
+log('first launch did not stay alive, retry once')
+const retry = launchApp('retry')
+await sleep(8000)
+log(alive(retry.pid) ? `ok after retry (pid ${retry.pid} alive)` : 'FAILED: app did not come back')

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-reload-buttons
+      name: dsh-reload-buttons

package/index.js

@@ -0,0 +1,130 @@
+/**
+ * 重启与刷新：宿主侧提供一条「重启应用 / 结束内核」的路由。
+ * 刷新按钮是纯浏览器侧的事（重载页面即重拉客户端产物），不需要宿主。
+ *
+ * 落点：客户端半边把两个图标按钮挂进 `conversation.header.leading`（网页界面左上角空位）。
+ * 安全：只接受回环请求；POST 才受理。
+ *
+ * 桌面端为什么要「先关界面壳」而不是自己退出：
+ * 桌面端把内核退出一律当致命故障（main.js 里 child.once('close') 无条件 fail → 弹恢复框），
+ * 内核自己 exit 就必然弹那张框。反过来，Electron 主进程一消失，
+ * 内核的 IPC 断开会触发它自己的优雅收尾（dsh-desktop-host 里 process.once('disconnect')），
+ * 且没有任何进程会弹框；随后由 assets/restart-app.mjs 把 exe 重新拉起。
+ * 非桌面端（dsh web 等）没有这一层，直接走内核自己的 shutdown。
+ */
+
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { mkdirSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** Cordis 插件名。 */
+export const name = 'dsh-reload-buttons'
+/** 需要的服务（路由在 apply 期靠 ctx.inject 等 webServer 到位）。 */
+export const inject = []
+
+const ROUTE = '/dsh-reload-buttons/api/restart'
+const WORKER = fileURLToPath(new URL('./assets/restart-app.mjs', import.meta.url))
+
+/** 桌面端＝宿主跑在 Electron 的 Node 模式里。 */
+function isDesktop() {
+  return typeof process.versions?.electron === 'string' && process.versions.electron !== ''
+}
+
+function logPath() {
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const dir = join(home, 'logs')
+  try {
+    mkdirSync(dir, { recursive: true })
+  } catch {
+    return join(tmpdir(), 'dsh-reload-buttons-restart.log')
+  }
+  return join(dir, 'dsh-reload-buttons-restart.log')
+}
+
+/** 内核自己的 shutdown（宿主 index.js 监听的就是这条消息），跑完进程自然退出。 */
+function shutdownAndExit() {
+  let exited = false
+  const hardExit = () => {
+    if (exited) return
+    exited = true
+    process.exit(0)
+  }
+  try {
+    process.emit('message', { type: 'shutdown' }, null)
+  } catch {
+    hardExit()
+    return
+  }
+  setTimeout(hardExit, 3000)
+}
+
+/**
+ * 桌面端：把重启交给独立脚本（先关界面壳，再拉起 exe）。
+ * 本进程不退出——界面壳一走，宿主会收到 IPC 断开并自行优雅收尾。
+ */
+function handOffRestart(port) {
+  const exe = process.execPath
+  const parentPid = process.ppid
+  const child = spawn(process.execPath, [
+    WORKER,
+    String(parentPid),
+    exe,
+    String(process.pid),
+    String(port ?? ''),
+    logPath(),
+  ], {
+    env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  })
+  child.unref()
+  return child.pid !== undefined
+}
+
+function isLocal(req) {
+  const addr = req.socket && req.socket.remoteAddress
+  return typeof addr === 'string' && /^(::1|127\.|::ffff:127\.)/.test(addr)
+}
+
+function sendJson(res, code, value) {
+  res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify(value))
+}
+
+/** 注册重启路由。 */
+export function apply(ctx) {
+  const mount = (hostCtx) => {
+    const webServer = hostCtx
+      && (hostCtx.webServer || (typeof hostCtx.get === 'function' ? hostCtx.get('webServer') : undefined))
+    if (!webServer || typeof webServer.register !== 'function') return
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: ROUTE,
+      handler: (req, res) => {
+        if (!isLocal(req)) return sendJson(res, 403, { ok: false, error: '只接受本机请求' })
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: '只支持 POST' })
+        if (isDesktop()) {
+          let handedOff = false
+          try {
+            handedOff = handOffRestart(webServer.port)
+          } catch {
+            handedOff = false
+          }
+          sendJson(res, 200, { ok: true, mode: handedOff ? 'relaunch' : 'exit' })
+          // 脚本没起来就别干等：退回内核自己退出（会弹恢复框，但至少不会卡死）
+          if (!handedOff) setTimeout(shutdownAndExit, 400)
+          return
+        }
+        sendJson(res, 200, { ok: true, mode: 'exit' })
+        setTimeout(shutdownAndExit, 400)
+      },
+    }), 'dsh-reload-buttons: restart route')
+  }
+  // apply 期直接取 ctx.get('webServer') 往往还没就绪，优先放进 inject 回调等它到位；
+  // 桩 ctx（冒烟、测试）没有 inject，退回直接取（拿不到就什么也不做，不影响加载）。
+  if (typeof ctx.inject === 'function') ctx.inject(['webServer'], mount)
+  else mount(ctx)
+}

package/invariant.js

@@ -0,0 +1,10 @@
+const PACKAGE_NAME = 'dsh-reload-buttons'
+
+/** Cordis companion plugin name. */
+export const name = 'dsh-reload-buttons-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+const install = () => {}
+
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

package/lib/client.js

@@ -0,0 +1,270 @@
+window.__ModuleLoader__.load({
+	id: "dsh-reload-buttons",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/entry.jsx
+var entry_exports = {};
+__export(entry_exports, {
+  apply: () => apply,
+  inject: () => inject
+});
+module.exports = __toCommonJS(entry_exports);
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var ROUTE = "/dsh-reload-buttons/api/restart";
+function api(path) {
+  const relative = String(path).replace(/^\/+/, "");
+  if (typeof document === "undefined") return "/" + relative;
+  return new URL(relative, document.baseURI).pathname;
+}
+var wrap = { display: "inline-flex", alignItems: "center", gap: "2px" };
+var btn = {
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  width: "24px",
+  height: "24px",
+  padding: 0,
+  border: 0,
+  borderRadius: "6px",
+  background: "transparent",
+  color: "inherit",
+  cursor: "pointer",
+  opacity: 0.65
+};
+function IconRefresh() {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    "svg",
+    {
+      width: "14",
+      height: "14",
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M21 12a9 9 0 1 1-2.64-6.36" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M21 3v6h-6" })
+      ]
+    }
+  );
+}
+function IconPower() {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    "svg",
+    {
+      width: "14",
+      height: "14",
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M12 3v9" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M18.36 6.64a9 9 0 1 1-12.72 0" })
+      ]
+    }
+  );
+}
+async function probeBootBundles() {
+  const boot = globalThis.__DSH_BOOT__;
+  const batches = boot && Array.isArray(boot.batches) ? boot.batches : [];
+  const urls = batches.map((batch) => batch && typeof batch.url === "string" ? batch.url : "").filter((url) => url !== "");
+  if (urls.length === 0) return { ok: true, total: 0, bad: [] };
+  const results = await Promise.all(urls.map(async (url) => {
+    try {
+      const res = await fetch(new URL(url, document.baseURI), { cache: "no-store" });
+      return { url, ok: res.ok, status: res.status };
+    } catch {
+      return { url, ok: false, status: 0 };
+    }
+  }));
+  return { ok: results.every((r) => r.ok), total: results.length, bad: results.filter((r) => !r.ok) };
+}
+async function requestRestart() {
+  try {
+    await fetch(api(ROUTE), { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
+  } catch (e) {
+  }
+}
+function overlay(text, ms) {
+  if (typeof document === "undefined" || document.body === null) return () => {
+  };
+  const box = document.createElement("div");
+  box.textContent = text;
+  box.style.position = "fixed";
+  box.style.top = "16px";
+  box.style.left = "50%";
+  box.style.transform = "translateX(-50%)";
+  box.style.zIndex = "2147483647";
+  box.style.padding = "8px 16px";
+  box.style.borderRadius = "8px";
+  box.style.background = "rgba(24, 24, 27, 0.88)";
+  box.style.color = "#fff";
+  box.style.fontSize = "13px";
+  box.style.lineHeight = "18px";
+  box.style.pointerEvents = "none";
+  box.style.fontFamily = "inherit";
+  document.body.appendChild(box);
+  const remove = () => {
+    box.remove();
+  };
+  if (ms) setTimeout(remove, ms);
+  return remove;
+}
+var REFRESH_FLAG = "dsh-reload-buttons:refreshed";
+function announceRefreshed() {
+  let stamp = 0;
+  try {
+    stamp = Number(sessionStorage.getItem(REFRESH_FLAG) ?? 0);
+    sessionStorage.removeItem(REFRESH_FLAG);
+  } catch {
+    return;
+  }
+  if (!stamp || Date.now() - stamp > 2e4) return;
+  overlay("\u754C\u9762\u5DF2\u5237\u65B0", 1800);
+}
+var modulesRef;
+function moduleSystem() {
+  return modulesRef;
+}
+function freshGraph() {
+  return new Promise((resolve) => {
+    let source;
+    let timer;
+    const finish = (value) => {
+      clearTimeout(timer);
+      try {
+        source?.close();
+      } catch {
+      }
+      resolve(value);
+    };
+    try {
+      source = new EventSource(new URL("plugins/events", document.baseURI));
+    } catch {
+      resolve(null);
+      return;
+    }
+    timer = setTimeout(() => finish(null), 3e3);
+    source.addEventListener("message", (event) => {
+      try {
+        const frame = JSON.parse(event.data);
+        if (frame && frame.type === "graph" && frame.graph) finish(frame.graph);
+      } catch {
+      }
+    });
+  });
+}
+async function resyncPlugins() {
+  const modules = moduleSystem();
+  const entries = modules && modules.entries;
+  if (!entries || typeof entries.sync !== "function") return false;
+  const graph = await freshGraph();
+  if (!graph) return false;
+  await entries.sync(graph);
+  return true;
+}
+function HeaderButtons() {
+  const [restarting, setRestarting] = (0, import_react.useState)(false);
+  const [checking, setChecking] = (0, import_react.useState)(false);
+  async function reload() {
+    if (checking) return;
+    setChecking(true);
+    let probe = { ok: true, total: 0, bad: [] };
+    try {
+      probe = await probeBootBundles();
+    } catch {
+      probe = { ok: true, total: 0, bad: [] };
+    }
+    if (probe.ok) {
+      try {
+        sessionStorage.setItem(REFRESH_FLAG, String(Date.now()));
+      } catch {
+      }
+      overlay("\u6B63\u5728\u5237\u65B0\u2026");
+      await new Promise((resolve) => {
+        setTimeout(resolve, 180);
+      });
+      window.location.reload();
+      return;
+    }
+    const hide = overlay("\u6B63\u5728\u5237\u65B0\u2026");
+    let resynced = false;
+    try {
+      resynced = await resyncPlugins();
+    } catch {
+      resynced = false;
+    }
+    hide();
+    overlay(resynced ? "\u754C\u9762\u5DF2\u5237\u65B0" : "\u5237\u65B0\u5931\u8D25\uFF1A\u6E05\u5355\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u7528\u300C\u91CD\u542F\u300D", 2200);
+    setChecking(false);
+  }
+  async function restart() {
+    if (restarting) return;
+    if (!window.confirm("\u91CD\u542F\u5E94\u7528\uFF1F\u754C\u9762\u4F1A\u5173\u6389\uFF0C\u51E0\u79D2\u540E\u81EA\u52A8\u91CD\u5F00\uFF1B\u82E5\u5F39\u51FA\u300C\u5E94\u7528\u65E0\u6CD5\u4F7F\u7528\u300D\u7A97\u53E3\uFF0C\u70B9\u5176\u4E2D\u7684\u300C\u91CD\u542F\u300D\u5373\u53EF\u3002")) return;
+    setRestarting(true);
+    await requestRestart();
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { style: wrap, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        type: "button",
+        style: Object.assign({}, btn, checking ? { opacity: 0.35, cursor: "default" } : null),
+        title: "\u5237\u65B0\u754C\u9762",
+        "aria-label": "\u5237\u65B0\u754C\u9762",
+        onClick: () => void reload(),
+        children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(IconRefresh, {})
+      }
+    ),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        type: "button",
+        style: Object.assign({}, btn, restarting ? { opacity: 0.35, cursor: "default" } : null),
+        title: "\u91CD\u542F\u5E94\u7528\uFF08\u5173\u6389\u754C\u9762\uFF0C\u51E0\u79D2\u540E\u81EA\u52A8\u91CD\u5F00\uFF09",
+        "aria-label": "\u91CD\u542F\u5E94\u7528",
+        onClick: () => void restart(),
+        children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(IconPower, {})
+      }
+    )
+  ] });
+}
+var inject = ["slots", "modules"];
+var SLOT = "conversation.header.leading";
+function apply(ctx) {
+  modulesRef = ctx.modules;
+  ctx.slots.inject(SLOT, () => ctx.slots.register({ name: SLOT }, HeaderButtons));
+  if (typeof setTimeout === "function") setTimeout(announceRefreshed, 600);
+}
+
+		return module.exports;
+	}
+});

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "dsh-reload-buttons",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "在界面左上角放两个按钮：刷新界面与重启应用——刷新按需整页重载或就地重同步插件，不给白屏；重启在桌面端关掉界面壳后自动重开，在 dsh web 下结束内核交给你的守护进程。",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./invariant": "./invariant.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "invariant.js",
+    "cordis.patch.yml",
+    "src",
+    "lib/client.js",
+    "assets",
+    "scripts",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.1-rc.5 <0.3.0-0"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": []
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "reload",
+    "refresh",
+    "restart",
+    "ui"
+  ],
+  "scripts": {
+    "build:client": "node scripts/build-client.mjs",
+    "check:client": "node scripts/build-client.mjs --check",
+    "smoke": "node scripts/smoke.mjs",
+    "check": "node --check index.js && node --check invariant.js && node --check assets/restart-app.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/taoziliyouchong/dsh-reload-buttons"
+  },
+  "homepage": "https://github.com/taoziliyouchong/dsh-reload-buttons#readme",
+  "bugs": {
+    "url": "https://github.com/taoziliyouchong/dsh-reload-buttons/issues"
+  }
+}

package/scripts/build-client.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * 构建浏览器半边：src/entry.jsx → lib/client.js
+ *
+ * 客户端模块表按「入口名 == 包名」索引，所以产物必须套上 DSH 的模块外壳：
+ *   window.__ModuleLoader__.load({ id: <package.json 的 name>, factory })
+ * 外壳里的 id 与包名对不上，界面就静默不加载。
+ *
+ * 用法：
+ *   node scripts/build-client.mjs           重新生成 lib/client.js
+ *   node scripts/build-client.mjs --check   只比对新产物与已提交产物，不一致即退出码 1
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'esbuild'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const entry = join(root, 'src', 'entry.jsx')
+const out = join(root, 'lib', 'client.js')
+const check = process.argv.includes('--check')
+
+if (!existsSync(entry)) {
+  console.error('找不到浏览器半边源码：' + entry)
+  process.exit(2)
+}
+
+const bundled = await build({
+  entryPoints: [entry],
+  bundle: true,
+  format: 'cjs',
+  platform: 'browser',
+  jsx: 'automatic',
+  target: ['chrome120'],
+  // react 由 DSH 客户端模块表提供，不能打进产物
+  external: ['react', 'react/jsx-runtime'],
+  write: false,
+  logLevel: 'warning',
+  legalComments: 'none',
+})
+
+const code = bundled.outputFiles[0].text.replace(/\s*\/\/# sourceMappingURL=.*$/m, '')
+const envelope = 'window.__ModuleLoader__.load({\n'
+  + '\tid: ' + JSON.stringify(pkg.name) + ',\n'
+  + '\tfactory: (require) => {\n'
+  + '\t\tvar module = { exports: {} };\n'
+  + '\t\tvar exports = module.exports;\n'
+  + '\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: "Module" });\n'
+  + code
+  + '\n\t\treturn module.exports;\n'
+  + '\t}\n'
+  + '});\n'
+
+// 语法自检：只解析不执行（new Function 不跑函数体）
+try {
+  // eslint-disable-next-line no-new-func
+  new Function(envelope)
+} catch (error) {
+  console.error('产物语法检查失败：' + error.message)
+  process.exit(1)
+}
+
+if (check) {
+  if (!existsSync(out)) {
+    console.error('缺少已提交的产物：' + out + '（先跑 node scripts/build-client.mjs）')
+    process.exit(1)
+  }
+  if (readFileSync(out, 'utf8') !== envelope) {
+    console.error('lib/client.js 与 src/entry.jsx 不一致：先跑 node scripts/build-client.mjs 再提交')
+    process.exit(1)
+  }
+  console.log('ok  lib/client.js 与源码一致（' + Buffer.byteLength(envelope, 'utf8') + ' 字节）')
+  process.exit(0)
+}
+
+mkdirSync(dirname(out), { recursive: true })
+writeFileSync(out, envelope, 'utf8')
+console.log('ok  已写出 ' + out + '（' + Buffer.byteLength(envelope, 'utf8') + ' 字节，id=' + pkg.name + '）')

package/scripts/smoke.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * 本机冒烟：不起应用、不发网络请求、不改任何东西。
+ *
+ * 四关：
+ *   1. 包结构      —— files 声明的必需文件都在（含已提交的 lib/client.js）
+ *   2. 宿主半边    —— 桩 ctx 跑 apply，确认注册了一条路由、且路由路径与包名一致
+ *   3. 路由鉴权    —— 非回环请求 403、非 POST 405
+ *   4. 客户端产物  —— 外壳 id == 包名，且带上了源码里的路由与刷新标记
+ *
+ * 用法：node scripts/smoke.mjs   （任一条失败退出码 1）
+ */
+
+import { readFileSync, existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const problems = []
+
+const ok = (label, extra = '') => console.log('ok   ' + label + (extra ? '  ' + extra : ''))
+const fail = (label, why) => {
+  problems.push(label + ': ' + why)
+  console.log('FAIL ' + label + '  ' + why)
+}
+
+/** 1. 包结构 */
+const REQUIRED = [
+  'index.js',
+  'invariant.js',
+  'cordis.patch.yml',
+  'assets/restart-app.mjs',
+  'src/entry.jsx',
+  'lib/client.js',
+  'README.md',
+  'README.en.md',
+  'LICENSE',
+]
+const missing = REQUIRED.filter((rel) => !existsSync(join(root, rel)))
+if (missing.length > 0) fail('结构', '缺 ' + missing.join('、'))
+else ok('结构', REQUIRED.length + ' 个必需文件齐全')
+
+/** 2. 宿主半边：桩 ctx 跑 apply */
+const mod = await import(pathToFileURL(join(root, 'index.js')).href)
+if (mod.name !== pkg.name) fail('宿主半边', 'index.js 导出的 name 是 ' + mod.name + '，不等于包名 ' + pkg.name)
+else ok('宿主半边', "name = " + mod.name)
+
+const routes = []
+const effects = []
+const webServer = {
+  port: 0,
+  register(route) {
+    routes.push(route)
+    return () => {}
+  },
+}
+// inject 回调收到的是宿主 ctx（webServer 挂在它上面），不是服务本身
+const hostCtx = { webServer }
+const ctx = {
+  inject(names, fn) {
+    if (!Array.isArray(names) || !names.includes('webServer')) throw new Error('宿主半边要求注入 webServer')
+    fn(hostCtx)
+  },
+  effect(fn) {
+    effects.push(typeof fn === 'function' ? fn() : fn)
+  },
+}
+
+try {
+  mod.apply(ctx)
+} catch (error) {
+  fail('宿主半边', 'apply 抛错：' + error.message)
+}
+
+const ROUTE = '/' + pkg.name + '/api/restart'
+if (routes.length !== 1) fail('宿主半边', '应注册 1 条路由，实际 ' + routes.length)
+else if (routes[0].path !== ROUTE) fail('宿主半边', '路由路径是 ' + routes[0].path + '，应为 ' + ROUTE)
+else if (routes[0].kind !== 'exact') fail('宿主半边', '路由 kind 是 ' + routes[0].kind + '，应为 exact')
+else if (effects.length !== 1) fail('宿主半边', '应登记 1 个 effect，实际 ' + effects.length)
+else ok('宿主半边', 'POST ' + ROUTE + ' 已注册（kind=exact）')
+
+/** 3. 路由鉴权 */
+function call(handler, req) {
+  const res = {
+    status: 0,
+    headers: null,
+    body: '',
+    writeHead(code, headers) {
+      res.status = code
+      res.headers = headers
+    },
+    end(body) {
+      res.body = String(body ?? '')
+    },
+  }
+  handler(req, res)
+  return res
+}
+
+if (routes.length === 1) {
+  const handler = routes[0].handler
+  const cases = [
+    { label: '非回环地址被拒', req: { socket: { remoteAddress: '10.1.2.3' }, method: 'POST' }, want: 403 },
+    { label: 'GET 被拒', req: { socket: { remoteAddress: '127.0.0.1' }, method: 'GET' }, want: 405 },
+    { label: '::1 本机照常走 POST 分支', req: { socket: { remoteAddress: '::1' }, method: 'GET' }, want: 405 },
+    { label: 'IPv4 映射地址被认作本机', req: { socket: { remoteAddress: '::ffff:127.0.0.1' }, method: 'GET' }, want: 405 },
+  ]
+  let passed = 0
+  for (const item of cases) {
+    let res
+    try {
+      res = call(handler, item.req)
+    } catch (error) {
+      fail('路由鉴权', item.label + '：handler 抛错 ' + error.message)
+      continue
+    }
+    if (res.status !== item.want) fail('路由鉴权', item.label + '：返回 ' + res.status + '，应为 ' + item.want)
+    else passed += 1
+  }
+  if (passed === cases.length) ok('路由鉴权', passed + ' 条全部符合')
+}
+
+/** 4. 客户端产物 */
+const client = readFileSync(join(root, 'lib', 'client.js'), 'utf8')
+const idMatch = /^\s*id:\s*"([^"]+)"/m.exec(client)
+if (!idMatch) fail('客户端产物', '外壳里找不到 id')
+else if (idMatch[1] !== pkg.name) fail('客户端产物', '外壳 id 是 ' + idMatch[1] + '，应等于包名 ' + pkg.name)
+else if (!client.includes(ROUTE)) fail('客户端产物', '产物里没有路由 ' + ROUTE + '（源码改了但没重新构建）')
+else if (!client.includes(pkg.name + ':refreshed')) fail('客户端产物', '产物里没有刷新标记（源码改了但没重新构建）')
+else ok('客户端产物', 'id=' + pkg.name + '，' + Buffer.byteLength(client, 'utf8') + ' 字节')
+
+console.log('')
+if (problems.length > 0) {
+  console.error('冒烟失败 ' + problems.length + ' 项')
+  process.exit(1)
+}
+console.log('冒烟通过')

package/src/entry.jsx

@@ -0,0 +1,248 @@
+/**
+ * 重启与刷新：会话头部最左两个图标按钮（浏览器半边源码）。
+ *
+ * 落点 `conversation.header.leading`——single 槽，当前由本插件占用（注册者显示为客户端运行时名）。
+ * 如果哪天这个座位被别的插件先占住（single 槽同优先级二次注册会抛错），
+ * 换到 `conversation.session.header.utilities`（list 槽，自带 id 追加即可）。
+ *
+ * 刷新＝重载页面；重载会用内核启动时拍的清单快照，改了客户端插件后快照会过期（404 → 白屏 +
+ * 恢复框）。所以刷新前先探一遍清单资源：全都取得到就 reload；取不到就说明必须重启，直接走重启，
+ * 不再弹一句「先点重启」把人堵住。
+ * 重启＝POST 宿主路由 → 桌面端交 assets/restart-app.mjs 关壳再拉起。
+ *
+ * 打包：npm run build:client（scripts/build-client.mjs）；产物外壳 id 必须等于包名。
+ */
+import { useState } from 'react'
+
+const ROUTE = '/dsh-reload-buttons/api/restart'
+
+/** 把路由拼成当前页面挂载点下的路径（锚 document.baseURI，兼容子路径部署）。 */
+function api(path) {
+  const relative = String(path).replace(/^\/+/, '')
+  if (typeof document === 'undefined') return '/' + relative
+  return new URL(relative, document.baseURI).pathname
+}
+
+const wrap = { display: 'inline-flex', alignItems: 'center', gap: '2px' }
+const btn = {
+  display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
+  width: '24px', height: '24px', padding: 0, border: 0, borderRadius: '6px',
+  background: 'transparent', color: 'inherit', cursor: 'pointer', opacity: 0.65,
+}
+
+function IconRefresh() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"
+      strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M21 12a9 9 0 1 1-2.64-6.36" />
+      <path d="M21 3v6h-6" />
+    </svg>
+  )
+}
+
+function IconPower() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"
+      strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M12 3v9" />
+      <path d="M18.36 6.64a9 9 0 1 1-12.72 0" />
+    </svg>
+  )
+}
+
+/**
+ * 刷新前自检：启动快照里的 bundle 是否都还取得到。
+ *
+ * 桌面端把客户端插件清单在**内核启动那一刻**拍一次快照（主进程 `dshDesktopBoot.ready()` 返回的
+ * injections 就是它），之后改插件产物快照不会跟着变；这时刷新会请求到已下线的旧 rev（404），
+ * web boot 整批失败 → 白屏 + 恢复对话框。所以刷之前先把快照里的组合脚本取一遍，取不到就不刷。
+ */
+async function probeBootBundles() {
+  const boot = globalThis.__DSH_BOOT__
+  const batches = boot && Array.isArray(boot.batches) ? boot.batches : []
+  const urls = batches
+    .map((batch) => (batch && typeof batch.url === 'string' ? batch.url : ''))
+    .filter((url) => url !== '')
+  if (urls.length === 0) return { ok: true, total: 0, bad: [] }
+  const results = await Promise.all(urls.map(async (url) => {
+    try {
+      const res = await fetch(new URL(url, document.baseURI), { cache: 'no-store' })
+      return { url, ok: res.ok, status: res.status }
+    } catch {
+      return { url, ok: false, status: 0 }
+    }
+  }))
+  return { ok: results.every((r) => r.ok), total: results.length, bad: results.filter((r) => !r.ok) }
+}
+
+/** 请求宿主重启。界面随壳一起关掉，所以连接断掉是预期，不当错误。 */
+async function requestRestart() {
+  try {
+    await fetch(api(ROUTE), { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' })
+  } catch (e) { /* 界面壳被关掉时连接会断，属预期 */ }
+}
+
+/** 顶部浮层：先提示「正在刷新…」，重载回来后再给一句「界面已刷新」，让人知道这一下确实生效了。 */
+function overlay(text, ms) {
+  if (typeof document === 'undefined' || document.body === null) return () => {}
+  const box = document.createElement('div')
+  box.textContent = text
+  box.style.position = 'fixed'
+  box.style.top = '16px'
+  box.style.left = '50%'
+  box.style.transform = 'translateX(-50%)'
+  box.style.zIndex = '2147483647'
+  box.style.padding = '8px 16px'
+  box.style.borderRadius = '8px'
+  box.style.background = 'rgba(24, 24, 27, 0.88)'
+  box.style.color = '#fff'
+  box.style.fontSize = '13px'
+  box.style.lineHeight = '18px'
+  box.style.pointerEvents = 'none'
+  box.style.fontFamily = 'inherit'
+  document.body.appendChild(box)
+  const remove = () => { box.remove() }
+  if (ms) setTimeout(remove, ms)
+  return remove
+}
+
+/** 刷新标记：重载前写下，重载后本插件加载时读到它就报一句「已刷新」。 */
+const REFRESH_FLAG = 'dsh-reload-buttons:refreshed'
+
+/** 重载回来后确认一句（20 秒内有效，避免误报）。 */
+function announceRefreshed() {
+  let stamp = 0
+  try {
+    stamp = Number(sessionStorage.getItem(REFRESH_FLAG) ?? 0)
+    sessionStorage.removeItem(REFRESH_FLAG)
+  } catch {
+    return
+  }
+  if (!stamp || Date.now() - stamp > 20000) return
+  overlay('界面已刷新', 1800)
+}
+
+/** 客户端模块系统（就地重载插件条目用）；apply 时取，声明成依赖保证一定在。 */
+let modulesRef
+
+/** 客户端模块系统句柄。 */
+function moduleSystem() {
+  return modulesRef
+}
+
+/** 从宿主 SSE 抓当前启动图（一连接就推全量图）。 */
+function freshGraph() {
+  return new Promise((resolve) => {
+    let source
+    let timer
+    const finish = (value) => {
+      clearTimeout(timer)
+      try { source?.close() } catch { /* 已关就算了 */ }
+      resolve(value)
+    }
+    try {
+      source = new EventSource(new URL('plugins/events', document.baseURI))
+    } catch {
+      resolve(null)
+      return
+    }
+    timer = setTimeout(() => finish(null), 3000)
+    source.addEventListener('message', (event) => {
+      try {
+        const frame = JSON.parse(event.data)
+        if (frame && frame.type === 'graph' && frame.graph) finish(frame.graph)
+      } catch { /* 坏帧忽略，等超时 */ }
+    })
+  })
+}
+
+/** 清单过期时：按宿主当前图就地对齐插件条目——不重载整页、不关应用。 */
+async function resyncPlugins() {
+  const modules = moduleSystem()
+  const entries = modules && modules.entries
+  if (!entries || typeof entries.sync !== 'function') return false
+  const graph = await freshGraph()
+  if (!graph) return false
+  await entries.sync(graph)
+  return true
+}
+
+/** 左上一行两个按钮。 */
+function HeaderButtons() {
+  const [restarting, setRestarting] = useState(false)
+  const [checking, setChecking] = useState(false)
+
+  async function reload() {
+    if (checking) return
+    setChecking(true)
+    let probe = { ok: true, total: 0, bad: [] }
+    try {
+      probe = await probeBootBundles()
+    } catch {
+      probe = { ok: true, total: 0, bad: [] }
+    }
+    if (probe.ok) {
+      try { sessionStorage.setItem(REFRESH_FLAG, String(Date.now())) } catch { /* 隐私模式忽略 */ }
+      overlay('正在刷新…')
+      // 留一帧让浮层看得见，再整页重载
+      await new Promise((resolve) => { setTimeout(resolve, 180) })
+      window.location.reload()
+      return
+    }
+    // 清单过期：整页重载会白屏（旧 rev 已 404）。改为就地重载插件，同行样给可见反馈。
+    const hide = overlay('正在刷新…')
+    let resynced = false
+    try {
+      resynced = await resyncPlugins()
+    } catch {
+      resynced = false
+    }
+    hide()
+    overlay(resynced ? '界面已刷新' : '刷新失败：清单已过期，请用「重启」', 2200)
+    setChecking(false)
+  }
+
+  async function restart() {
+    if (restarting) return
+    if (!window.confirm('重启应用？界面会关掉，几秒后自动重开；若弹出「应用无法使用」窗口，点其中的「重启」即可。')) return
+    setRestarting(true)
+    await requestRestart()
+  }
+
+  return (
+    <span style={wrap}>
+      <button
+        type="button"
+        style={Object.assign({}, btn, checking ? { opacity: 0.35, cursor: 'default' } : null)}
+        title="刷新界面"
+        aria-label="刷新界面"
+        onClick={() => void reload()}
+      >
+        <IconRefresh />
+      </button>
+      <button
+        type="button"
+        style={Object.assign({}, btn, restarting ? { opacity: 0.35, cursor: 'default' } : null)}
+        title="重启应用（关掉界面，几秒后自动重开）"
+        aria-label="重启应用"
+        onClick={() => void restart()}
+      >
+        <IconPower />
+      </button>
+    </span>
+  )
+}
+
+/** 需要的客户端服务。 */
+export const inject = ['slots', 'modules']
+
+/** 左上角全局面包屑前的空位（single 槽）。 */
+const SLOT = 'conversation.header.leading'
+
+/** 把两个按钮挂进左上角。 */
+export function apply(ctx) {
+  modulesRef = ctx.modules
+  ctx.slots.inject(SLOT, () => ctx.slots.register({ name: SLOT }, HeaderButtons))
+  // 如果是「刷新」刚把页面重载回来的，晚一点给一句「界面已刷新」
+  if (typeof setTimeout === 'function') setTimeout(announceRefreshed, 600)
+}