dsh-chat-embed 0.5.4 → 0.6.1

package/README.md

@@ -20,7 +20,7 @@
 | `locale/{en,zh}.json` | 插件管理器里显示的标题与简介 |
 | `cordis.patch.yml` | 组合补丁：向 profile 插入 `id: chat-embed` 的 loader 行 |
 | `scripts/verify-bundle.mjs` | 门禁：语法 / 清单 / loader 契约 / 服务注册表 / 显示资源 |
-| `test/` | 纯 Node 契约测试（伪造 DOM + 伪造桌面桥），57 项 |
+| `test/` | 纯 Node 契约测试（伪造 DOM + 伪造桌面桥 + 伪造 asar），81 项 |
 | `docs/architecture.md` | 内嵌契约、席位架构、壳补丁、升级复验清单（**接到项目先读这份**） |
 | `tools/shell-patch/` | 可选的桌面壳补丁：持久分区（跨重启免登录）+ 关闭磁盘缓存 |
 | `清理聊天缓存.cmd` / `restore-shell-patch.cmd` | 缓存回收 / 还原原版壳 |
@@ -80,7 +80,7 @@
 > 仅桌面版可用（需要 Electron 的 `<webview>` 和 `window.dshDesktop.browser`）。
 > 当前实测版本：`@deepseek-ai/dsh-desktop 0.2.2-rc.1`；包声明了 `engines.dsh`，版本不符时插件管理器会拒绝安装。
 
-**方式一：npm（发布之后）**
+**方式一：npm（已发布 `0.5.4`）**
 
 ```jsonc
 // 在 dsh 会话里交给插件管理器执行
@@ -177,6 +177,23 @@ node tools/shell-patch/patch-asar.cjs --help                     # 查看参数
 
 > 通过 npm 安装时脚本位于 `<profile>/node_modules/<包名>/tools/shell-patch/`；也可以在「⚙ → 跨重启保持登录」里点「复制补丁说明」拿到步骤。
 
+### 补丁状态与自检（0.6.0 起）
+
+设置菜单里的「跨重启保持登录」有四种状态，**只有未开启时才出现风险提示与操作按钮**：
+
+| 状态 | 含义 | 菜单里提供 |
+| --- | --- | --- |
+| 已开启（`persist:` 分区） | 补丁生效，重启后仍登录 | —（已是最优） |
+| 未开启（内存分区） | 从没打过补丁 | 风险提示 + 复制补丁说明 + 检查补丁配置 |
+| **已失效**（升级覆盖） | **打过补丁，但桌面壳升级覆盖了 `app.asar`** | 同上；这一状态专门告诉你"该重打了" |
+| 尚未检测 | 还没打开过聊天页 | 同上 |
+
+「检查补丁配置」调用 Host 侧只读探针（`GET /dsh-chat-embed/patch-check`），报告安装目录、`app.asar` 是否可写、是否已打补丁、补丁点是否还在（壳版本是否兼容）、备份与待替换文件是否存在、`app.asar` 的大小与内容哈希；报告同时复制到剪贴板，方便直接贴出去。
+
+**不需要自己装 Node.js**：探针会找出桌面版自带的 Node 运行时（`~/.dsh/dsh-runtimes/*/dependencies/node/`），并把一条完整可复制的命令写进报告——含正确的 Node 路径、补丁脚本路径和 `--resources` 安装目录（自定义/便携安装也能用）。
+
+Host 侧还注册了只读工具 **`dsh_chat_embed_patch_check`**：可以直接问 agent「我的聊天为什么重启后要重新登录」，它会自己去查这些事实，而不是让你跑命令再贴输出。
+
 补丁做两件事：`persist:` 固定分区（登录落盘）+ `cache:false`（不落 Chromium 缓存）。
 没有补丁也能用，只是每次重启要重新登录。细节与风险见 [已知限制](#已知限制)。
 
@@ -196,8 +213,8 @@ node tools/shell-patch/patch-asar.cjs --help                     # 查看参数
 dsh-chat-embed/
 ├── package.json               # 包名/版本、dsh.bundle.patch、dsh.client、exports/files
 ├── cordis.patch.yml           # 组合补丁：插入 id=chat-embed 的 loader 行
-├── index.js                   # Host 半侧（空壳，扩展点）
-├── client.js                  # Client 半侧（约 3545 行，手写产物）
+├── index.js                   # Host 半侧：补丁探针（HTTP + agent 工具）
+├── client.js                  # Client 半侧（约 3912 行，手写产物）
 ├── locale/{en,zh}.json        # 插件管理器显示用 meta
 ├── icon.svg                   # 插件图标（插件管理器显示）
 ├── assets/
@@ -209,7 +226,8 @@ dsh-chat-embed/
 │   └── pack-dist.mjs          # 产出 dist/*.tgz（维护者）
 ├── test/
 │   ├── fake-env.mjs           # 伪造 DOM / 伪造桌面桥
-│   └── client.test.mjs        # 62 项契约测试
+│   ├── client.test.mjs        # 客户端契约测试
+│   └── host.test.mjs          # Host 探针与工具测试
 ├── docs/
 │   ├── architecture.md        # 架构与内嵌契约（先读这份）
 │   └── publishing.md          # 维护者：发版、分发与列表投稿
@@ -246,7 +264,7 @@ git clone <repo-url> dsh-chat-embed
 cd dsh-chat-embed
 
 # 无需安装依赖；直接跑门禁与测试
-npm run check     # 语法 + 清单 + 显示资源 + 服务注册表 + 62 项测试
+npm run check     # 语法 + 清单 + 显示资源 + 服务注册表 + 81 项测试
 npm test          # 只跑测试
 ```
 
@@ -297,6 +315,8 @@ plugin_manager { "action": "install_bundle", "target": "<本仓库克隆路径>"
 
 | 版本 | 变化 |
 | --- | --- |
+| `0.6.1` | 探针找出桌面版自带的 Node 运行时，自检报告与「复制补丁说明」直接给出可执行命令（含 `--resources`，支持自定义安装目录）；无需用户另装 Node |
+| `0.6.0` | 补丁可观测性：四态检测（未打 / 已开启 / **升级后失效** / 未检测）、未开启时的风险提示、菜单内「检查补丁配置」自检（Host 只读探针 `GET /dsh-chat-embed/patch-check`）、agent 工具 `dsh_chat_embed_patch_check`；Host 半侧改为读取真实 `app.asar`（`original-fs`，绕过 Electron 的 asar 目录拦截） |
 | `0.5.4` | 语言切换即时生效：翻译器改为 locale 绑定的单一来源，监听 `locale/change` 重渲染（不再依赖未注入的 `props.t`）；补语言切换测试 |
 | `0.5.3` | 修复 `locale` 探针（`t` 作用域错误）并补测试；诊断读数在测试环境下的 `<html lang>` 兼容 |
 | `0.5.2` | 面板文案跟随 DSH 语言设置（中文 / English 即时切换，缺翻译回落中文）；诊断读数一并本地化；新增 `locale` 探针 |

package/client.js

@@ -103,7 +103,7 @@ window.__ModuleLoader__.load({
     let openRightTabImpl = () => {}
 
     /** Build identity, surfaced in the panel so a packaged app can be diagnosed. */
-    const BUILD = '0.5.4'
+    const BUILD = '0.6.1'
 
     /** Where a re-applied instance finds the one it must take over from. */
     const INSTANCE_KEY = '__DSH_CHAT_EMBED_INSTANCE__'
@@ -257,9 +257,16 @@ window.__ModuleLoader__.load({
         persistLabel: 'Login across restarts',
         persistOn: 'on (persist: partition)',
         persistOff: 'off (memory partition)',
+        persistLost: 'lost (the shell update replaced the patch)',
         persistUnknown: 'not detected yet',
         persistHint: 'Needs the shell patch; a plugin cannot change how the shell names partitions.',
+        persistRisk:
+          'Experimental: the patch rewrites the app.asar of the desktop shell and needs write access to its install folder. A shell update replaces it, so the patch has to be applied again.',
         persistCopy: 'Copy the patch instructions',
+        persistCheck: 'Check the patch setup',
+        persistCheckRunning: 'Checking…',
+        persistReportCopied: 'Self-check copied',
+        persistReportTitle: 'Shell patch self-check',
         copyDiag: 'Copy diagnostics',
         copied: 'Copied',
         copyFailed: 'Copy failed',
@@ -332,9 +339,15 @@ window.__ModuleLoader__.load({
         persistLabel: '跨重启保持登录',
         persistOn: '已开启（persist: 分区）',
         persistOff: '未开启（内存分区）',
+        persistLost: '已失效（桌面壳升级覆盖了补丁）',
         persistUnknown: '尚未检测',
         persistHint: '需要桌面壳补丁；插件无法改变壳的分区命名。',
+        persistRisk: '实验性功能：补丁会改写桌面壳的 app.asar，需要安装目录的写权限；桌面壳升级会覆盖补丁，需要重新打一次。',
         persistCopy: '复制补丁说明',
+        persistCheck: '检查补丁配置',
+        persistCheckRunning: '正在检查…',
+        persistReportCopied: '自检报告已复制',
+        persistReportTitle: '壳补丁自检报告',
         copyDiag: '复制诊断信息',
         copied: '已复制',
         copyFailed: '复制失败',
@@ -646,6 +659,13 @@ window.__ModuleLoader__.load({
     /** localStorage key remembering how the last guest was partitioned. */
     const PERSIST_KEY = 'dsh-chat-embed:persist'
 
+    /**
+     * localStorage key remembering that a persistent partition was seen once.
+     * A shell update replaces the patch, so "was on, now off" is a lost patch
+     * rather than a first run: the difference is what the settings row reports.
+     */
+    const PERSIST_SEEN_KEY = 'dsh-chat-embed:persist-seen'
+
     /** How many entries the ring buffer keeps. */
     const LOG_LIMIT = 200
 
@@ -2327,26 +2347,67 @@ window.__ModuleLoader__.load({
      * case, anything else is memory-only. The answer is remembered so the
      * settings menu can show it right after a restart, before any guest mounts.
      *
-     * @returns {'on' | 'off' | 'unknown'}
+     * `lost` reports the specific case that needs an action: a persistent
+     * partition was seen before, and this run does not get one — the desktop
+     * shell was updated and replaced the patch.
+     *
+     * @returns {'on' | 'off' | 'lost' | 'unknown'}
      */
     function persistenceState() {
-      for (const provider of PROVIDERS) {
-        const record = guests.get(provider.id)
-        if (record === undefined || typeof record.partition !== 'string' || record.partition === '') continue
-        const state = record.partition.startsWith('persist:') ? 'on' : 'off'
-        storePersistence(state)
-        return state
+      const live = livePartitionState()
+      if (live === 'on') {
+        storePersistence('on')
+        storePersistenceSeen(true)
+        return 'on'
+      }
+      if (live === 'off') {
+        storePersistence('off')
+        return readPersistedSeen() ? 'lost' : 'off'
       }
       try {
         if (typeof localStorage === 'undefined' || localStorage === null) return 'unknown'
         const stored = localStorage.getItem(PERSIST_KEY)
-        return stored === 'on' || stored === 'off' ? stored : 'unknown'
+        if (stored === 'on') return 'on'
+        if (stored === 'off') return readPersistedSeen() ? 'lost' : 'off'
+        return readPersistedSeen() ? 'lost' : 'unknown'
       } catch (error) {
         void error
         return 'unknown'
       }
     }
 
+    /** @returns {'on' | 'off' | 'unknown'} what the mounted guests actually received */
+    function livePartitionState() {
+      for (const provider of PROVIDERS) {
+        const record = guests.get(provider.id)
+        if (record === undefined || typeof record.partition !== 'string' || record.partition === '') continue
+        return record.partition.startsWith('persist:') ? 'on' : 'off'
+      }
+      return 'unknown'
+    }
+
+    /** @returns {boolean} whether a persistent partition was ever observed */
+    function readPersistedSeen() {
+      try {
+        if (typeof localStorage === 'undefined' || localStorage === null) return false
+        return localStorage.getItem(PERSIST_SEEN_KEY) === '1'
+      } catch (error) {
+        void error
+        return false
+      }
+    }
+
+    /** @param {boolean} seen */
+    function storePersistenceSeen(seen) {
+      try {
+        if (typeof localStorage === 'undefined' || localStorage === null) return
+        if (seen) localStorage.setItem(PERSIST_SEEN_KEY, '1')
+        else localStorage.removeItem(PERSIST_SEEN_KEY)
+      } catch (error) {
+        void error
+      }
+    }
+
     /** @param {'on' | 'off'} state */
     function storePersistence(state) {
       try {
@@ -2357,6 +2418,148 @@ window.__ModuleLoader__.load({
       }
     }
 
+    /** @param {(key: string) => string} t @param {string} state @returns {string} */
+    function persistenceText(t, state) {
+      if (state === 'on') return t('persistOn')
+      if (state === 'off') return t('persistOff')
+      if (state === 'lost') return t('persistLost')
+      return t('persistUnknown')
+    }
+
+    /**
+     * The clipboard copy behind "copy the patch instructions": what to run,
+     * where the tool is, and how to replace the archive safely.
+     *
+     * @param {(key: string) => string} t
+     * @returns {string}
+     */
+    /**
+     * The clipboard copy behind "copy the patch instructions".
+     *
+     * The Host's probe supplies the exact command — including the Node binary
+     * that ships with the desktop app, so the user is not asked to install one.
+     *
+     * @param {(key: string) => string} t
+     * @param {any} [probe]
+     * @returns {string}
+     */
+    function patchInstructions(t, probe) {
+      const info = probe !== undefined && probe !== null ? probe : {}
+      const command =
+        typeof info.patchCommand === 'string' && info.patchCommand !== ''
+          ? info.patchCommand
+          : 'node tools/shell-patch/patch-asar.cjs build'
+      const lines = [t('persistLabel') + '：' + t('persistHint'), '']
+      lines.push('1) 执行下面这条命令（Desk 自带的 Node 运行时；无需另装 Node）：')
+      lines.push('   ' + command)
+      lines.push('   脚本会自动探测安装目录并逐字节校验，生成 app.asar.new。')
+      lines.push('')
+      lines.push('2) 完全退出 DSH 后替换（任选其一）：')
+      lines.push('   - 运行 tools/shell-patch/watchdog.ps1，退出瞬间自动替换；')
+      lines.push('   - 手动把 resources\\app.asar.new 改名为 app.asar。')
+      lines.push('')
+      lines.push('3) 重启 DSH，回到这里应显示「' + t('persistOn') + '」。')
+      lines.push('')
+      lines.push('回滚：restore-shell-patch.cmd（把 app.asar.orig 换回去）。')
+      lines.push('Windows 之外的安装目录请用 --resources 指定。')
+      return lines.join('\n')
+    }
+
+    /**
+     * Host-side probe state for the "check the patch setup" button. The Host
+     * half answers, so a renderer without Node access can still report where
+     * the shell lives and whether the archive is writable.
+     *
+     * @type {{ running: boolean, report: string }}
+     */
+    const patchCheck = { running: false, report: '' }
+
+    /** One-shot cache of the Host probe, so both actions read the same facts. */
+    const patchProbe = { loaded: false, value: undefined }
+
+    /**
+     * Ask the Host half for the shell facts and render a copyable report.
+     * Nothing here writes: the button only inspects.
+     *
+     * @param {(key: string) => string} t
+     * @returns {Promise<void>}
+     */
+    /**
+     * Ask the Host for the shell facts once per session. Both the copy action
+     * and the self-check read it, so the instructions never disagree with the
+     * report.
+     *
+     * @returns {Promise<any>} the probe, or undefined when the route is absent
+     */
+    async function fetchProbe() {
+      if (patchProbe.loaded) return patchProbe.value
+      try {
+        // The Host half serves this route; a relative fetch therefore works in
+        // both the desktop app and the Web GUI, under any deployment prefix.
+        const response = await fetch('./dsh-chat-embed/patch-check', {
+          method: 'GET',
+          headers: { accept: 'application/json' },
+          cache: 'no-store',
+        })
+        patchProbe.value = response.ok ? await response.json() : undefined
+      } catch (error) {
+        patchProbe.value = undefined
+        void error
+      }
+      patchProbe.loaded = true
+      return patchProbe.value
+    }
+
+    async function runPatchCheck(t) {
+      if (patchCheck.running) return
+      patchCheck.running = true
+      notify()
+      let report = ''
+      try {
+        patchProbe.loaded = false
+        const probe = await fetchProbe()
+        report = formatPatchReport(t, probe)
+      } catch (error) {
+        report = formatPatchReport(t, undefined) + '\n' + t('copyFailed') + ': ' + messageOf(error)
+      }
+      patchCheck.running = false
+      patchCheck.report = report
+      notify()
+      void copyText(report)
+    }
+
+    /**
+     * @param {(key: string) => string} t
+     * @param {any} probe
+     * @returns {string}
+     */
+    function formatPatchReport(t, probe) {
+      const lines = [t('persistReportTitle')]
+      lines.push(t('persistLabel') + ': ' + persistenceText(t, persistenceState()))
+      if (probe === undefined || probe === null) {
+        lines.push(t('persistHint'))
+        return lines.join('\n')
+      }
+      const row = (label, value) => {
+        if (value === undefined || value === null || value === '') return
+        lines.push(label + ': ' + String(value))
+      }
+      row('resources', probe.resources)
+      row('app.asar', probe.asar)
+      row('app.asar.orig', probe.backup === true ? '有' : '无')
+      row('app.asar.new', probe.staged === true ? '有（待替换）' : '无')
+      row('可写', probe.writable === true ? '是' : '否')
+      row('补丁点', probe.patchSite === true ? '存在' : probe.patchSite === false ? '不存在（壳版本不匹配）' : '未知')
+      row('已打补丁', probe.patched === true ? '是' : probe.patched === false ? '否' : '未知')
+      row('node', probe.node)
+      row('补丁命令', probe.patchCommand)
+      if (probe.nodeBinary === undefined) {
+        lines.push('（没有找到可用的 Node 运行时，需要先安装 Node.js 22 或更新）')
+      }
+      row('说明', probe.detail)
+      return lines.join('\n')
+    }
+
     /** @returns {{ state: string, detail: string, seats: any[] }} */
     function rightSidebarStatus() {
       return { state: rightTypeState.state, detail: rightTypeState.detail, seats: rightSeatAttempts.slice() }
@@ -2579,6 +2782,9 @@ window.__ModuleLoader__.load({
       '.dce-menu-label{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
       '.dce-menu-value{flex:0 0 auto;font-size:12px;color:var(--dsw-alias-label-tertiary,#9aa0a6)}',
       '.dce-menu-sep{margin:5px 0 3px;border-top:1px solid var(--dsw-alias-border-l1,rgba(127,127,127,.24))}',
+      '.dce-menu-note{margin:4px 8px 6px;font-size:11.5px;line-height:1.5;color:var(--dsw-alias-label-tertiary,#9aa0a6);white-space:pre-wrap;word-break:break-word}',
+      '.dce-menu-note[data-persist-risk="true"]{color:var(--dsw-alias-label-warning,#c98b16)}',
+      '.dce-menu-note[data-patch-report="true"]{max-height:180px;overflow:auto;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11px}',
       '.dce-menu-item{display:flex;align-items:center;justify-content:flex-start;gap:8px;width:100%;box-sizing:border-box;padding:6px 8px;border:0;border-radius:6px;background:transparent;color:inherit;font-size:13px;text-align:left;cursor:pointer}',
       '.dce-menu-item:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(127,127,127,.12))}',
       '.dce-right-title{display:inline-flex;align-items:center;gap:6px;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
@@ -3236,28 +3442,42 @@ window.__ModuleLoader__.load({
                   h(
                     'span',
                     { className: 'dce-menu-value', title: t('persistHint') },
-                    persistenceState() === 'on'
-                      ? t('persistOn')
-                      : persistenceState() === 'off'
-                        ? t('persistOff')
-                        : t('persistUnknown'),
+                    persistenceText(t, persistenceState()),
                   ),
                 ),
-                persistenceState() === 'off'
-                  ? h(
+                persistenceState() === 'on'
+                  ? null
+                  : h('div', { className: 'dce-menu-note', 'data-persist-risk': 'true' }, t('persistRisk')),
+                persistenceState() === 'on'
+                  ? null
+                  : h(
                       'button',
                       {
                         type: 'button',
                         className: 'dce-menu-item',
+                        'data-patch-help': 'true',
                         onClick: () => {
-                          void copyText(
-                            '跨重启保持登录需要可选的桌面壳补丁（在插件包目录或仓库根目录执行）：\n  node tools/shell-patch/patch-asar.cjs build\n关闭 DSH 后替换 resources\\app.asar，watchdog 会在退出时自动完成。\n详见 README「已知限制 §1」。',
-                          )
+                          void fetchProbe().then((probe) => copyText(patchInstructions(t, probe)))
                         },
                       },
                       h('span', { className: 'dce-menu-label' }, t('persistCopy')),
-                    )
-                  : null,
+                    ),
+                h(
+                  'button',
+                  {
+                    type: 'button',
+                    className: 'dce-menu-item',
+                    'data-patch-check': 'true',
+                    disabled: patchCheck.running,
+                    onClick: () => {
+                      void runPatchCheck(t)
+                    },
+                  },
+                  h('span', { className: 'dce-menu-label' }, patchCheck.running ? t('persistCheckRunning') : t('persistCheck')),
+                ),
+                patchCheck.report === ''
+                  ? null
+                  : h('div', { className: 'dce-menu-note', 'data-patch-report': 'true' }, patchCheck.report),
                 h(
                   'button',
                   {
@@ -3528,6 +3748,15 @@ window.__ModuleLoader__.load({
         updateSurface,
         getLogging,
         persistenceState,
+        readPersistedSeen,
+        storePersistenceSeen,
+        livePartitionState,
+        patchInstructions,
+        fetchProbe,
+        patchProbe,
+        formatPatchReport,
+        runPatchCheck,
+        patchCheck,
         setLogging,
         clearLog,
         readLogEntries,

package/docs/architecture.md

@@ -3,7 +3,7 @@
 本文记录 `client.js` 里每一条**反直觉**的实现决策、支撑它的证据，以及升级桌面壳时必须重新验证的清单。
 
 目标运行环境：**`@deepseek-ai/dsh-desktop 0.2.2-rc.1`（Electron / Chromium）**。
-当前实现：**v0.5.4**（`client.js` 约 3545 行，62 项契约测试）。
+当前实现：**v0.6.1**（`client.js` 约 3912 行，81 项契约测试）。
 
 > **架构一句话**：聊天页直接渲染在**席位的布局盒**里（`.dce-panel.dce-inline`，`width/height:100%`），几何完全交给 CSS；席位只有两个 —— 中央主面板（`main`）和右栏聊天 tab —— 二者互斥，**哪边点哪边接管**，切换时 guest 重建一次并回到上次会话。
 
@@ -325,6 +325,15 @@ idle → acquiring → navigating → ready
 | `layout` | `layout` 服务的键、`hasMainPanel('chat-embed')`、左栏导航 DOM 条目 |
 | `log` | 调试日志开关与最近 50 条环形缓冲；`{ enabled: true/false }` 开关，`{ clear: true }` 清空。默认关闭，关闭时不打印也不缓冲 |
 | `locale` | 当前活跃语言（`active`）、可用语言列表、`<html lang>`，以及面板文案当前解析出的样例（`sample` / `zhSample` / `enSample`） |
+
+Host 半侧另有两条只读通道，专门用来回答"为什么重启后要重新登录"：
+
+| 通道 | 内容 |
+| --- | --- |
+| `GET /dsh-chat-embed/patch-check` | 安装目录、`app.asar` 是否可写、是否已打补丁、补丁点是否还存在、备份与待替换文件、大小与内容哈希、**可执行的补丁命令**（含自带 Node 运行时路径与 `--resources`） |
+| agent 工具 `dsh_chat_embed_patch_check` | 同一份读数，供模型直接查询（只读，无需审批） |
+
+> 读取 `app.asar` 必须走 Electron 的 `original-fs`：被补丁过的 `node:fs` 会把以 `.asar` 结尾的路径当成目录，`readFileSync` 直接 ENOENT。探针优先用 `original-fs`，普通 Node 下回落到 `node:fs`。
 | `openPanel` | 选中中央面板（等价于点左栏图标；探针路径不等于真实点击，见下） |
 | `openRight` | 展开右栏并打开聊天 tab，报告每一步的错误 |
 | `prefer` | 把席位偏好切到 `main` / `right`，返回解析后的席位与宿主 |

package/docs/publishing.md

@@ -5,13 +5,13 @@
 ## 版本与提交约定
 
 - 同时改 `package.json` 的 `version` 与 `client.js` 的 `BUILD`，两者必须一致；
-- 门禁必须绿：`npm run check`（`verify-bundle` + 62 项契约测试）；
+- 门禁必须绿：`npm run check`（`verify-bundle` + 81 项契约测试）；
 - 代码注释/提交信息英文，文档中文。
 
 ## 发版步骤
 
 ```powershell
-npm run check            # 门禁：verify-bundle + 62 项测试（prepublishOnly 也会跑）
+npm run check            # 门禁：verify-bundle + 81 项测试（prepublishOnly 也会跑）
 npm run pack:dist        # 产出 dist\dsh-chat-embed-<版本>.tgz
 gh release create v0.5.0 dist\dsh-chat-embed-0.5.0.tgz --title "v0.5.0" --notes-file dist\release-notes.md
 ```
@@ -31,7 +31,8 @@ Get-FileHash $env:TEMP\check\dsh-chat-embed-0.5.0.tgz -Algorithm SHA256
 | --- | --- |
 | 仓库 | <https://github.com/poluce/dsh-chat-embed> |
 | Release | <https://github.com/poluce/dsh-chat-embed/releases> |
-| 分发包 | `dsh-chat-embed-0.5.0.tgz`（15 个文件，约 60 kB） |
+| 分发包 | `dsh-chat-embed-0.6.1.tgz`（16 个文件，约 70 kB） |
+| npm | `dsh-chat-embed@0.6.1`（<https://www.npmjs.com/package/dsh-chat-embed>，维护者 `poluce_auto`） |
 | 商店图标 | `assets/icon-180.png`（180×180 PNG） |
 | 商店截图 | `assets/screenshots/` + 仓库根 `screenshots.json`（6 张） |
 
@@ -50,7 +51,7 @@ dsh plugin --profile desktop add git+https://github.com/poluce/dsh-chat-embed.gi
 
 1. 注册账号并完成邮箱验证：<https://www.npmjs.com/signup>；
 2. 本机登录：`npm login`（浏览器确认或一次性密码；开了 2FA 输入验证码）；
-3. 发布：`npm publish`（`prepublishOnly` 自动跑门禁；包名 `dsh-chat-embed` 已确认可用）；
+3. 发布：`npm publish`（`prepublishOnly` 自动跑门禁；包名 `dsh-chat-embed` 已发布 `0.5.4`）；
 4. 使用者随后只需：`dsh plugin --profile desktop add dsh-chat-embed`。
 
 ## 发布前后检查项
@@ -59,7 +60,10 @@ dsh plugin --profile desktop add git+https://github.com/poluce/dsh-chat-embed.gi
 - 改包名（例如加 npm 作用域）必须同步改 `cordis.patch.yml` 里 loader 行的 `name`（必须等于包名）；`id` 保持唯一即可；
 - `repository` / `homepage` / `bugs` 当前指向 `github.com/poluce/dsh-chat-embed`；换账号或换仓库时改这三处；
 - 发布后用一份干净 profile 验证：`dsh plugin --profile <新名字> add <包名>`，然后打开左栏入口；
-- 可选壳补丁（跨重启免登录）不是安装必需项；不装补丁时功能完整，只是重启后要重新登录。
+- 可选壳补丁（跨重启免登录）不是安装必需项；不装补丁时功能完整，只是重启后要重新登录；
+- npm 首次发布新包时会出现 `0.0.0-stage` 占位版本（staged publishing 机制），审核/发布完成后 `latest` 指向正式版本；占位版本可忽略；
+- 账号 2FA 使用通行密钥（passkey），CLI 发布需要交互式终端完成 WebAuthn，或在 npm 网页创建 **Bypass 2FA 的 Granular Token** 后用 `npm publish --//registry.npmjs.org/:_authToken=<token>`；
+- 带 Bypass 2FA 的直接发布能力 npm 计划 2027 年 1 月收紧，届时改用 trusted publishing 或 staged 流程。
 
 ## 提交到插件列表（awesome-dsh-plugin）
 

package/index.js

@@ -1,25 +1,419 @@
 /**
  * dsh-chat-embed — Host half.
  *
- * The whole feature lives in the Client half (`client.js`): the desktop
- * webview, the lease handshake, the panel UI. This half only has to exist so
- * the loader row named by `cordis.patch.yml` has a Node-side export to mount;
- * `dsh.client` in `package.json` publishes the browser half beside it.
+ * The feature itself lives in the Client half (`client.js`): the desktop
+ * webview, the lease handshake, the panel UI. This half exists for two
+ * reasons, and nothing else:
  *
- * Keep this module inert. It must not import browser globals, and anything it
- * registers must be cleaned up through `ctx.effect` so uninstalling the bundle
- * leaves the Host process exactly as it was.
+ *   1. the loader row named by `cordis.patch.yml` needs a Node-side export;
+ *   2. the optional shell patch needs a **Host-side** answer, because the
+ *      patched archive lives on the Host's disk and only the Host can read
+ *      and test it. The panel asks over the exposed channel, so a user can
+ *      see why cross-restart login is off without being told to run a
+ *      command and read its output.
+ *
+ * Keep this module inert beyond that probe. It must not import browser
+ * globals, and anything it registers must be cleaned up through `ctx.effect`
+ * so uninstalling the bundle leaves the Host process exactly as it was.
  */
 
+import { createHash } from 'node:crypto'
+import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
 export const name = 'dsh-chat-embed'
 
-/** @param {import('@deepseek-ai/cordis').Context} ctx */
+/** Route the panel fetches for the read-only shell probe. */
+const PROBE_PATH = '/dsh-chat-embed/patch-check'
+
+/** Strings that identify the patch in a rebuilt archive. */
+const PATCH_MARK = 'persist:dsh-sidebar-'
+const CACHE_MARK = '{ cache: false }'
+
+/** Strings that identify an unpatched archive's patch sites. */
+const PATCH_SITE_MARK = 'partition = `dsh-sidebar-browser-'
+const CACHE_SITE_MARK = 'this.configureSession(session.fromPartition(partition))'
+
+/**
+ * Candidate `resources` directories. `DSH_RESOURCES` wins so a custom install
+ * or a non-Windows layout can be pointed at explicitly.
+ *
+ * @returns {string[]} absolute candidates, most specific first
+ */
+function resourcesCandidates() {
+  const candidates = []
+  // Electron hands the running app its own resources directory: the exact
+  // answer, and the only one that works for a non-standard install location.
+  if (typeof process.resourcesPath === 'string' && process.resourcesPath !== '') {
+    candidates.push(process.resourcesPath)
+  }
+  // A plain Node process started beside the app binary can derive it.
+  if (typeof process.execPath === 'string' && process.execPath !== '') {
+    candidates.push(join(dirname(process.execPath), 'resources'))
+  }
+  candidates.push(process.env.DSH_RESOURCES)
+  if (process.platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA
+    if (localAppData !== undefined && localAppData !== '') {
+      candidates.push(join(localAppData, 'Programs', 'DeepSeek Harness', 'resources'))
+    }
+    candidates.push('C:\\Program Files\\DeepSeek Harness\\resources')
+    candidates.push('C:\\Program Files (x86)\\DeepSeek Harness\\resources')
+  } else if (process.platform === 'darwin') {
+    candidates.push('/Applications/DeepSeek Harness.app/Contents/Resources')
+  } else {
+    candidates.push('/opt/DeepSeek Harness/resources')
+    candidates.push(join(homedir(), 'DeepSeek Harness', 'resources'))
+  }
+  return candidates.filter((entry) => typeof entry === 'string' && entry !== '')
+}
+
+/** @returns {string | undefined} the directory that actually holds app.asar */
+function detectResources() {
+  for (const candidate of resourcesCandidates()) {
+    if (existsSync(join(candidate, 'app.asar'))) return candidate
+  }
+  return undefined
+}
+
+/** @param {string} file @returns {boolean} */
+function isWritable(file) {
+  try {
+    accessSync(file, constants.W_OK)
+    return true
+  } catch (error) {
+    void error
+    return false
+  }
+}
+
+/**
+ * Read a file with the real Node implementation.
+ *
+ * Inside Electron the `node:fs` binding is patched to treat a path ending in
+ * `.asar` as a directory, so `readFileSync('<install>/app.asar')` raises ENOENT
+ * even though the bytes are all there. `original-fs` is Electron's unpatched
+ * copy; outside Electron the ordinary binding is already literal and is used.
+ *
+ * @param {string} file
+ * @returns {Buffer}
+ */
+function readRealFile(file) {
+  const fallback = () => readFileSync(file)
+  try {
+    const original = createRequire(import.meta.url)('original-fs')
+    if (original !== undefined && original !== null && typeof original.readFileSync === 'function') {
+      return original.readFileSync(file)
+    }
+  } catch (error) {
+    void error
+  }
+  return fallback()
+}
+
+/** @param {string} file @returns {number} the real byte length */
+function statRealSize(file) {
+  try {
+    const original = createRequire(import.meta.url)('original-fs')
+    if (original !== undefined && original !== null && typeof original.statSync === 'function') {
+      return original.statSync(file).size
+    }
+  } catch (error) {
+    void error
+  }
+  return statSync(file).size
+}
+
+/**
+ * Read one entry out of an asar archive.
+ *
+ * The container is `u32 @0 = 4`, `u32 @4 = headerLen + 8`, `u32 @8 = headerLen + 4`,
+ * `u32 @12 = headerLen`, then the JSON header, padding, then the file data.
+ *
+ * @param {string} file
+ * @param {string} entry slash-separated path inside the archive
+ * @returns {string | undefined} the entry as UTF-8, or undefined when absent
+ */
+function readAsarEntry(file, entry) {
+  const buffer = readRealFile(file)
+  const headerLength = buffer.readUInt32LE(12)
+  const header = JSON.parse(buffer.toString('utf8', 16, 16 + headerLength))
+  const padding = (4 - (headerLength % 4)) % 4
+  const dataStart = 16 + headerLength + padding
+  let node = header
+  for (const segment of entry.split('/')) {
+    if (node === undefined || node.files === undefined) return undefined
+    node = node.files[segment]
+  }
+  if (node === undefined || node.files !== undefined) return undefined
+  if (node.unpacked === true) return undefined
+  const offset = dataStart + Number(node.offset)
+  return buffer.toString('utf8', offset, offset + Number(node.size))
+}
+
+/**
+ * Locate a Node binary that can run the patch tool.
+ *
+ * DSH runs every profile on its own packaged runtime, so the archive can be
+ * patched without the user installing Node. The order is: the runtime this
+ * Host is already running on, the managed runtime directory, then a system
+ * `node` on PATH.
+ *
+ * @returns {string | undefined} an absolute path, or undefined when none exists
+ */
+function findNodeBinary() {
+  const candidates = []
+  // A Node-hosted dsh reports its own executable.
+  if (typeof process.execPath === 'string' && process.execPath !== '' && /node(.exe)?$/i.test(process.execPath)) {
+    candidates.push(process.execPath)
+  }
+  // The managed runtime the desktop app installs beside its own data.
+  const home = process.env.DSH_HOME !== undefined && process.env.DSH_HOME !== '' ? process.env.DSH_HOME : join(homedir(), '.dsh')
+  const runtimes = join(home, 'dsh-runtimes')
+  try {
+    for (const entry of readdirSync(runtimes)) {
+      const base = join(runtimes, entry, 'dependencies', 'node', 'bin')
+      candidates.push(join(base, process.platform === 'win32' ? 'node.exe' : 'node'))
+    }
+  } catch (error) {
+    void error
+  }
+  if (process.platform === 'win32' && process.env.ProgramFiles !== undefined) {
+    candidates.push(join(process.env.ProgramFiles, 'nodejs', 'node.exe'))
+  } else {
+    candidates.push('/usr/local/bin/node')
+    candidates.push('/usr/bin/node')
+  }
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate !== '' && existsSync(candidate)) return candidate
+  }
+  return undefined
+}
+
+/**
+ * @param {string} node absolute path to a Node binary
+ * @param {string} script absolute path to patch-asar.cjs
+ * @param {string} [resources] install directory, so a non-standard location works
+ * @returns {string} a copy-pasteable command line
+ */
+function patchCommand(node, script, resources) {
+  const quote = (value) => (value.includes(' ') ? '"' + value + '"' : value)
+  const parts = [quote(node), quote(script), 'build']
+  // The tool only searches the usual install locations. When the Host found the
+  // shell somewhere else (a portable or custom install), it must say where.
+  if (typeof resources === 'string' && resources !== '') parts.push('--resources', quote(resources))
+  return parts.join(' ')
+}
+
+/**
+ * Locate the patch tool inside this package, so the reported command points at
+ * a file that actually exists on the user's disk.
+ *
+ * @returns {string | undefined}
+ */
+function findPatchScript() {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const candidate = join(here, 'tools', 'shell-patch', 'patch-asar.cjs')
+  return existsSync(candidate) ? candidate : undefined
+}
+
+/**
+ * Inspect the desktop shell and the optional patch. Read-only: no file here is
+ * written, so this is safe to call from a diagnostics button.
+ *
+ * @param {string} [resources]
+ * @returns {object} a report the panel formats and copies
+ */
+function inspectShell(resources) {
+  const explicit = typeof resources === 'string' && resources !== ''
+  const resolved = explicit ? resources : detectResources()
+  if (resolved === undefined) {
+    return {
+      found: false,
+      platform: process.platform,
+      node: process.version,
+      detail: '没有找到 DSH 安装目录；用 DSH_RESOURCES 或 --resources 指定',
+    }
+  }
+  const asar = join(resolved, 'app.asar')
+  if (!existsSync(asar)) {
+    return {
+      found: false,
+      platform: process.platform,
+      node: process.version,
+      resources: resolved,
+      asar,
+      detail: '该目录下没有 app.asar；路径不对，或桌面壳安装不完整',
+    }
+  }
+  const staged = join(resolved, 'app.asar.new')
+  const backup = join(resolved, 'app.asar.orig')
+  const report = {
+    found: true,
+    platform: process.platform,
+    node: process.version,
+    resources: resolved,
+    asar,
+    exists: true,
+    writable: existsSync(asar) ? isWritable(asar) : isWritable(resolved),
+    backup: existsSync(backup),
+    staged: existsSync(staged),
+    patched: undefined,
+    patchSite: undefined,
+    detail: '',
+  }
+  try {
+    report.asarBytes = statRealSize(asar)
+    report.asarHash = createHash('sha256').update(readRealFile(asar)).digest('hex').slice(0, 16)
+  } catch (error) {
+    report.detail = '读取 app.asar 失败：' + firstLine(error)
+    return report
+  }
+  try {
+    const main = readAsarEntry(asar, 'lib/main.js')
+    if (main === undefined) {
+      report.detail = 'app.asar 中找不到 lib/main.js；壳结构已变化'
+      return report
+    }
+    report.patched = main.includes(PATCH_MARK)
+    report.cachePatch = main.includes(CACHE_MARK)
+    report.patchSite = main.includes(PATCH_SITE_MARK) || main.includes(PATCH_MARK)
+    if (report.patched !== true && report.patchSite === false) {
+      report.detail = '补丁点不存在：当前桌面壳版本的分区写法与补丁预期不一致，需要更新补丁'
+    } else if (report.patched !== true && report.cachePatch !== true) {
+      report.detail = '尚未打补丁'
+    }
+  } catch (error) {
+    report.detail = '解析 app.asar 失败：' + firstLine(error)
+  }
+  // The user needs a Node binary to run the patch tool. The desktop app ships
+  // its own runtime, so nobody has to install one — report the exact command
+  // instead of telling them to install Node first.
+  report.patchScript = findPatchScript()
+  report.nodeBinary = findNodeBinary()
+  report.patchCommand =
+    report.nodeBinary === undefined ? undefined : patchCommand(report.nodeBinary, report.patchScript, resolved)
+  return report
+}
+
+/** @param {unknown} error @returns {string} */
+function firstLine(error) {
+  const text = error instanceof Error ? error.message : String(error)
+  return text.split('\n')[0].slice(0, 200)
+}
+
+/**
+ * Serve the read-only probe over the Web GUI's HTTP carrier, so the panel can
+ * read it with a plain relative `fetch` — no Remote RPC endpoint, no shell
+ * bridge, and the same code path in the desktop app and the Web GUI.
+ *
+ * The route is GET-only and writes nothing; it reports where the shell is and
+ * what the archive contains, which is what a user needs to file a useful bug
+ * report when cross-restart login stops working.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {(() => void) | undefined} a disposer, or undefined without a webserver
+ */
+function installHttpProbe(ctx) {
+  const server = typeof ctx.get === 'function' ? ctx.get('webServer') : undefined
+  if (server === undefined || server === null || typeof server.register !== 'function') return undefined
+  const route = {
+    kind: 'exact',
+    path: PROBE_PATH,
+    resource(request) {
+      if (request.method !== 'GET' && request.method !== 'HEAD') {
+        return new Response('method not allowed', { status: 405 })
+      }
+      let body
+      try {
+        body = JSON.stringify(inspectShell())
+      } catch (error) {
+        body = JSON.stringify({ found: false, detail: firstLine(error) })
+      }
+      return new Response(request.method === 'HEAD' ? null : body, {
+        status: 200,
+        headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+      })
+    },
+  }
+  try {
+    const dispose = server.register(route)
+    return typeof dispose === 'function' ? dispose : () => {}
+  } catch (error) {
+    // Another composition already claimed the path, or the carrier rejected the
+    // shape. The probe is optional: the panel still reports the local state.
+    void error
+    return undefined
+  }
+}
+
+/**
+ * Register the patch checker as an agent tool, so the model can answer
+ * "why does my login not survive a restart?" by looking instead of asking the
+ * user to run a command and paste its output.
+ *
+ * The tool is read-only and needs no approval: it reports paths, byte counts
+ * and whether the patch marks are present, which the user could read off the
+ * disk themselves.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {(() => void) | undefined} a disposer, or undefined without a tool registry
+ */
+function installTool(ctx) {
+  const tools = typeof ctx.get === 'function' ? ctx.get('tools') : undefined
+  if (tools === undefined || tools === null || typeof tools.register !== 'function') return undefined
+  const definition = {
+    name: 'dsh_chat_embed_patch_check',
+    description:
+      'Report whether the DSH desktop shell has the optional patch that keeps embedded chat logins across restarts: the install directory, whether app.asar is writable, whether it is already patched, whether the patch can still be applied to this shell version, and whether a backup exists. Read-only.',
+    parameters: {
+      resources: {
+        type: 'string',
+        description:
+          'Optional install directory that contains app.asar. Omit to let the plugin detect the running shell.',
+      },
+    },
+    output: {
+      schema: { type: 'object' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args) {
+      const requested = args !== undefined && args !== null && typeof args.resources === 'string' ? args.resources : undefined
+      return inspectShell(requested)
+    },
+  }
+  try {
+    const dispose = tools.register(definition)
+    return typeof dispose === 'function' ? dispose : () => {}
+  } catch (error) {
+    void error
+    return undefined
+  }
+}
+
+/**
+ * Register the Host-side patch probe and the agent tool.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
 export function apply(ctx) {
-  // Nothing to bind on the Host side yet.
-  //
-  // Extension point: if a later version needs to persist settings (chat URL,
-  // user-agent mode), declare `export const Config` here and read it in the
-  // Client half through its own `dsh.client` declaration. Secrets belong to
-  // `ctx.credentials`, never to this plugin's configuration.
-  void ctx
+  if (ctx === undefined || ctx === null || typeof ctx.effect !== 'function') return
+  ctx.effect(() => installHttpProbe(ctx), 'dsh-chat-embed: shell patch probe')
+  ctx.effect(() => installTool(ctx), 'dsh-chat-embed: shell patch tool')
+}
+
+/** Exposed for tests and for the patch checker to reuse without a Context. */
+export const internals = {
+  inspectShell,
+  detectResources,
+  readAsarEntry,
+  readRealFile,
+  resourcesCandidates,
+  findNodeBinary,
+  findPatchScript,
+  patchCommand,
+  PROBE_PATH,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-chat-embed",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "author": "poluce <fishsummer@126.com>",
   "description": "Multi-tab AI chat embed for the DeepSeek Harness desktop app: DeepSeek, 豆包, ChatGPT, MiniMax, Kimi, Gemini and Grok, each signed in separately.",
   "type": "module",