dsh-plugin-maoxuan-pet 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # CHANGELOG
 
+## 0.3.2（2026-11-01）
+
+### 桌宠壳
+
+- **新增：点击真穿透（窗口随内容收缩）**——原 hitTest 白名单只能在 AppKit 层丢事件，WindowServer 已把点击判给壳窗口（640×720 的透明玻璃），后面 App 点不到。曾试过 CGS 窗口形状（`CGSSetWindowShape`）：坐标约定对不上且**连渲染一起裁**（小毛活着但隐形），弃用。最终方案：壳窗口随页面报告的可点区域收缩（右下角锚定，stage 定位固定 ⇒ 小毛纹丝不动），卡片高度与视口解耦（固定 480px）防止窗口伸缩反馈回路；窗口外点击天然直达下层。
+- **修复：恢复的窗口位置会把小毛放回屏幕外**——保存的位置 {{1218,-19}} 挂在屏幕右缘外（屏幕 1512pt 宽，窗口右缘 1858pt），她本人活着但站在不可见区域，看起来就是「放出去没了」。现在恢复前校验小毛站立处（窗口右下 220×300）是否整块在屏内，不在就回退默认位置并留日志。
+- **新增：跟随宿主换端口**——桌面版重启会换 web 端口，壳还指着旧 origin 就是反复出现的「连接中断」。连续 3 次拉取失败后扫 `$DSH_HOME/agent-tree-dock-*.json`（文件名带端口，取最新），用公开路由探活成功即自动跟随；约 30 秒内自愈。`--token` 模式不自动跟随（token 按次发放），日志提示重新放她到桌面。
+- **修复：立绘「下载成功但画面不换装」（蓝色大脑袋）**——立绘/状态注入是单次 `evaluate`，若那一刻 WKWebView 还没加载完 `pet.html`，注入落在即将被丢弃的上下文里，数据永久丢失；而立绘只在下载完成时注入一次，错过就永远停在壳内置占位形象。0.3.1 的 `--public` 模式无鉴权流程、轮询极快，把窗口期放大成必现。现在：注入前先落页面全局 `__petSpriteData` / `__petStateData`（页面脚本就绪时自取），并且壳以页面 rects 上报为「活着」心跳，发现立绘/首份 state 尚未送达就补发——时序无论怎么排都能收敛。新增恒落盘诊断日志 `$DSH_HOME/storages/dsh-maoxuan-pet.shell.log`（256KB 自动截断；宿主按钮拉起时 stdio 被丢弃，这份日志是唯一黑盒透视）。
+
+## 0.3.1 — 2026-11-01
+
+修复：预设面板上 maoxuan-pet 显示「加载失败 / Failed to load」；桌宠壳补上宿主鉴权支持。
+
+### 修复
+- **preset 挂载必败的缺参**：`cordis.patch.yml` 里 preset 的 `tool-todo` 子项没有给 `allowParallelInProgress`，而宿主的 `@deepseek-ai/dsh-tool-todo` 从 rc.2 起就把它声明为 **required**（且无默认值可合并）。挂载时校验失败，注册表把该行标记为 `broken`，界面徽章显示「加载失败」，悬停可见原文：`tool-todo (@deepseek-ai/dsh-tool-todo): invalid config: $.allowParallelInProgress missing required value`。现在显式声明 `allowParallelInProgress: false`（本预设一次只推进一件事，与 `false` 语义一致）。
+- 用 dsh 0.2.1-rc.5 运行时在真实桌面同构环境里探测过 `agentPresets.list()`：修复前 maoxuan-pet 带 `broken` 字段，修复后消失（dev-assistant 的失败是 dsh-plugin-dev-workflow 自己的 `connection` 注入问题，与本插件无关）。
+
+### 桌宠壳
+- **壳不再被宿主鉴权卡死**：DSH `0.2.1-rc.2` 起 Web API 全部要鉴权（launch token 只在 `GET /` 换签名 cookie，`/api/*` 裸请求一律 401，且不接受 Authorization 头），而 token 只有 CLI 宿主会打印、桌面 App 从不外泄——壳此前在桌面 App 旁边永远是「连接中断」。现在两条路：
+  - **`--public`（默认推荐）**：插件在 web server 上直接注册一组 loopback 公开路由 `SHELL_ROUTES`（`/dsh-maoxuan-pet/pet.json`、`asset.png`、`generate`、`dismiss`），GET 只读、POST 强制 JSON + `x-dsh-maoxuan-pet: 1` 自定义头（跨站页面发不出来，非 CSRF 洞）、监听只绑 loopback；壳不需要 token 也不需要 cookie，桌面 App 旁边同样满血。可用 `publicRoutes: false` 关闭。
+  - **`--token=<TOKEN>`**：给 CLI 宿主用，`GET /?token=…` 换 `dsh-auth-*` 签名 cookie（URLSession 内存 jar、不落盘、遇 401 自动重换）。
+- **桌面模式互斥显示（新）**：壳在桌面上时，界面里的小毛自动隐身，右下角只留一枚「小毛在桌面上 · 点此收回」小徽章；收回（或右键壳退出）后界面宠物自动回来。避免「两只小毛同时显示」的困惑。
+- **界面开关（新）**：红皮书卡片页脚新增 **「放她到桌面 / 收回桌宠」**——宿主新增第六条路由 `GET|POST /api/dsh-maoxuan-pet.shell`（状态快照 + launch/quit，origin 只接受 `http://127.0.0.1:<port>` 防注入；产物缺失时先自动跑 `desktop/build.sh`，最长 120s）。壳写 pidfile（`$DSH_HOME/storages/dsh-maoxuan-pet.shell.pid`，读取方探活、退出清理）+ 自身单实例保护，手动双击与按钮互相认得，不会叠出两只。已对活宿主端到端验证：GET 状态 → launch 起进程并落 pidfile → 重复 launch 幂等 → quit 退净并清 pidfile。
+- **双击备用**：仓库根目录新增 `启动小毛.command`——自动编译（首次）、自动找最近写入的 `~/.dsh/agent-tree-dock-<port>.json` 得到宿主地址、自动 `--public` 起壳，重复双击不会叠出第二只。
+- 验证：13091（鉴权过、插件未装：404 非 401）、30888/30891（maoxuan 宿主：`--public` 下 state 200 + 四帧立绘原生拉取、POST 缺头 403 / 带头 200）；`verify/host.test.mjs` 新增 2 条公开路由用例（假 ctx 的 webServer 记录注册 + 走 node 风格 req/res 断言 200/403），全套 20/20。
+
+### 排查备注
+- 挂载失败只在客户端读取名册（打开预设面板）时可见，宿主启动日志默认不打印该警告，所以此前一直没暴露。
+
 ## 0.3.0 — 2026-11-01
 
 新能力：独立 macOS 桌宠壳——小毛从 DSH 界面里走出来，站到真正的桌面上；DSH 最小化甚至关掉界面，她都站在原地。

package/README.md

@@ -17,12 +17,16 @@ dsh plugin --profile web add dsh-plugin-maoxuan-pet
 
 Web 宠物住在 DSH 界面里，界面最小化她就跟着没了——这是浏览器沙箱的硬边界。`desktop/` 目录自带一个**独立进程的桌宠壳**（纯 Swift + 系统 WebKit，约 450 行、零依赖）：透明、置顶、跨所有桌面空间，DSH 最小化甚至关掉界面她都站着；毛选的灵魂（每小时读一篇）仍由插件负责，壳只把「显示器」搬了出来。
 
-```bash
-npm run pet:build   # swiftc 编译，几秒
-npm run pet         # 她就站在屏幕右下角了
-```
+**最省事：不用碰终端。** 打开小毛的红皮书卡片，页脚有一个 **「放她到桌面」** 按钮——点她一下，小毛就以独立窗口站上桌面（首次会自动编译，几秒）；再点一次「收回桌宠」她就回界面里。不需要 token，不需要双击任何文件。
+
+两条备用路：
+
+- 双击仓库根目录的 `启动小毛.command`（自动连当前 DSH、自动 `--public`，重复双击不会叠出第二只）；
+- 命令行：`./desktop/build/maoxuan-pet --public`。
+
+点她开合红皮书卡片、拖她换位置（下次还在那儿、能拖出 DSH 窗口）、右键她 = 复位位置 / 退出。详见 [desktop/README.md](desktop/README.md)。
 
-点她开合红皮书卡片、拖她换位置（下次还在那儿）、右键她 = 复位位置 / 退出。详见 [desktop/README.md](desktop/README.md)。
+> Windows / Linux：界面里的宠物照常可用，但「拖出窗口」的独立壳目前只有 macOS 实现；页面 `pet.html` 与路由是跨平台的，照 `desktop/README.md` 用 Tauri/Electron 包一层即可。
 
 ## 界面
 

package/client.js

@@ -22,6 +22,7 @@ window.__ModuleLoader__.load({
       state: '/api/dsh-maoxuan-pet.state',
       generate: '/api/dsh-maoxuan-pet.generate',
       dismiss: '/api/dsh-maoxuan-pet.dismiss',
+      shell: '/api/dsh-maoxuan-pet.shell',
     };
     const POLL_MS = 20000;
     const POLL_BUSY_MS = 3000;
@@ -195,6 +196,8 @@ window.__ModuleLoader__.load({
       const [data, setData] = useState(null);
       const [error, setError] = useState(null);
       const [busy, setBusy] = useState(false);
+      const [shell, setShell] = useState(null);
+      const [shellBusy, setShellBusy] = useState(false);
       const [open, setOpen] = useState(false);
       const [pos, setPos] = useState(readPos);
       const [spriteBroken, setSpriteBroken] = useState(false);
@@ -228,8 +231,12 @@ window.__ModuleLoader__.load({
 
       const refresh = useCallback(async () => {
         try {
-          const next = await fetchState();
+          const [next, shellState] = await Promise.all([
+            fetchState(),
+            fetch(`${API.shell}?t=${Date.now()}`).then((r) => (r.ok ? r.json() : null)).catch(() => null),
+          ]);
           setData(next);
+          setShell(shellState);
           setError(null);
           return next;
         } catch (failure) {
@@ -342,6 +349,32 @@ window.__ModuleLoader__.load({
         }
       }, [refresh]);
 
+      // 独立桌宠壳：macOS 上把小毛请出 DSH 窗口（再点一次收回）。
+      const toggleShell = useCallback(async () => {
+        if (shellBusy) return;
+        setShellBusy(true);
+        try {
+          const response = await fetch(API.shell, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+              action: shell?.running ? 'quit' : 'launch',
+              origin: window.location.origin,
+            }),
+          });
+          const result = await response.json().catch(() => null);
+          // 400/500 的 error 也值得说人话：编译失败、平台不支持都会带中文指引
+          if (result && result.error) {
+            setShell((prev) => ({ ...(prev || {}), error: result.error }));
+          }
+          await refresh();
+        } catch (failure) {
+          setShell((prev) => ({ ...(prev || {}), error: String(failure?.message || failure) }));
+        } finally {
+          setShellBusy(false);
+        }
+      }, [shell, shellBusy, refresh]);
+
       const startDrag = useCallback((event) => {
         if (event.button !== 0) return;
         suppress.current = false;
@@ -427,6 +460,17 @@ window.__ModuleLoader__.load({
                     : '内置语料',
                   // 离线摘录不再用 chip 抢眼位，改成页脚一行小字，诚实但不喧宾夺主。
                   current.mode === 'offline' ? h('span', { className: 'mp-offline' }, ' · 离线摘录') : null),
+                shell?.supported
+                  ? h('button', {
+                      className: 'mp-btn', type: 'button',
+                      disabled: shellBusy || shell?.building,
+                      title: shell?.running
+                        ? '关掉独立桌宠窗口（她回到 DSH 界面里）'
+                        : '让她作为一个独立窗口站到桌面上——可以拖到 DSH 窗口外面，关掉 DSH 也还在',
+                      onClick: toggleShell,
+                      'aria-label': shell?.running ? '收回独立桌宠' : '放她到桌面',
+                    }, shellBusy || shell?.building ? '开关中…' : shell?.running ? '收回桌宠' : '放她到桌面')
+                  : null,
                 h('button', { className: 'mp-btn', type: 'button', onClick: dismiss, 'aria-label': '收起这条督促' }, '收起'),
                 h('button', {
                   className: 'mp-btn', type: 'button', 'data-primary': 'on',
@@ -438,6 +482,7 @@ window.__ModuleLoader__.load({
                 className: 'mp-btn', type: 'button', 'data-primary': 'on',
                 disabled: running, onClick: regenerate, 'aria-label': '让小毛现在读一篇',
               }, running ? '翻书中…' : '现在读一篇')),
+          shell?.error ? h('p', { className: 'mp-warn' }, `桌宠壳：${String(shell.error).slice(0, 90)}`) : null,
           data?.lastError ? h('p', { className: 'mp-warn' }, `上次生成没成功：${String(data.lastError.message || '').slice(0, 90)}`) : null,
           error ? h('p', { className: 'mp-warn' }, '连接中断，重试中…') : null)));
 
@@ -480,6 +525,31 @@ window.__ModuleLoader__.load({
       // dragged close to the left edge does it flip to the right side.
       const side = pos && pos.x < 380 ? 'right' : 'left';
 
+      // 桌面模式：独立壳已经站在真桌面上了，界面里的小毛就隐身，
+      // 只留一枚收回徽章——两只同时显示只会让人困惑「哪只才是她」。
+      if (shell?.running) {
+        return h('button', {
+          className: 'mp-dock-chip', type: 'button', onClick: toggleShell,
+          title: '收回桌面上的小毛',
+          style: {
+            position: 'fixed', right: 16, bottom: 16, zIndex: 2147483000,
+            display: 'flex', alignItems: 'center', gap: 5,
+            border: '1px solid rgba(255,217,168,.35)', borderRadius: 999, cursor: 'pointer',
+            padding: '3px 8px 3px 4px', font: '11px/1.4 -apple-system, sans-serif',
+            color: '#ffe9c8', background: 'rgba(109,20,24,.92)',
+            boxShadow: '0 2px 8px rgba(0,0,0,.24)',
+          },
+          'aria-label': '收回桌面上的小毛',
+        },
+          h('svg', { width: 14, height: 14, viewBox: '0 0 512 512', 'aria-hidden': true },
+            h('rect', { x: 0, y: 0, width: 512, height: 512, rx: 116, fill: '#FFF6E9' }),
+            h('rect', { x: 120, y: 104, width: 232, height: 304, rx: 26, fill: '#B3271E' }),
+            h('rect', { x: 120, y: 104, width: 46, height: 304, rx: 22, fill: '#8F1E17' }),
+            h('polygon', { fill: '#E8C36A', points: '263,150 273.32,181.76 306.72,181.76 279.7,201.74 289.02,234.5 263,214.25 236.98,234.5 246.3,201.74 219.28,181.76 252.68,181.76' }),
+            h('rect', { x: 215, y: 272, width: 96, height: 16, rx: 8, fill: '#E8C36A' })),
+          shellBusy ? '收回中…' : '收回');
+      }
+
       return h('div', { style, 'data-maoxuan-pet': true },
         h('style', { dangerouslySetInnerHTML: { __html: CSS } }),
         h('div', { className: 'mp-anchor', 'data-side': side }, pet, open ? card : null));

package/cordis.patch.yml

@@ -63,6 +63,12 @@
             name: '@deepseek-ai/dsh-tool-skill'
           - id: tool-todo
             name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              # @deepseek-ai/dsh-tool-todo 把 allowParallelInProgress 声明为
+              # required（rc.2 起如此），缺省不会合并默认值；不写这里 preset
+              # 挂载就会以 “$.allowParallelInProgress missing required value”
+              # 失败，预设面板上表现为「加载失败 / Failed to load」。
+              allowParallelInProgress: false
           - id: tool-ask-user
             name: '@deepseek-ai/dsh-tool-ask-user'
           - id: tool-web

package/desktop/README.md

@@ -47,12 +47,49 @@ npm run pet            # 编译并前台运行（Ctrl-C 或右键小毛→退出
 | --- | --- |
 | `--origin=URL` | 宿主地址，默认 `http://127.0.0.1:3081` |
 | `--port=N` | 等价 `--origin=http://127.0.0.1:N` |
+| `--public` | **推荐**：走插件注册的 cookie-less 公开路由（`/dsh-maoxuan-pet/…`），不需要 token |
+| `--token=TOKEN` | 备选：宿主 launch token，先换签名 cookie 再走 `/api` |
 | `--reset` | 忽略保存的位置，回到屏幕右下 |
 | `--verbose` | 向 stderr 打轮询/POST/输入区日志 |
 
 无 Dock 图标、不进 Cmd-Tab（`NSActivationPolicy.accessory`）。窗口位置存在
 `UserDefaults`（suite `dsh-maoxuan-pet.window`），拖到哪儿下次就在哪儿。
 
+## 鉴权（DSH 0.2.1-rc.2+ 宿主必读）
+
+从 DSH `0.2.1-rc.2` 起宿主 Web API 全部要鉴权：launch token 只在 `GET /` 换签名
+cookie（`dsh-auth-*`），`/api/*` 不带 cookie 一律 401，也不接受 Authorization 头。
+而 token 只有 CLI 宿主（`dsh web`）会打印，桌面 App 从不外泄——所以壳不能只依赖 `/api`。
+
+本插件因此自己开了一组 **loopback 公开路由**（`SHELL_ROUTES`，默认开启）：
+
+| 路由 | 方法 | 说明 |
+| --- | --- | --- |
+| `/dsh-maoxuan-pet/pet.json` | GET | 与 `/api/dsh-maoxuan-pet.state` 同一份快照 |
+| `/dsh-maoxuan-pet/asset.png?name=idle` | GET | 立绘（idle/talk/blink/read） |
+| `/dsh-maoxuan-pet/generate` | POST | 同「再督促」（要 `x-dsh-maoxuan-pet: 1` 头） |
+| `/dsh-maoxuan-pet/dismiss` | POST | 同「收起」（要 `x-dsh-maoxuan-pet: 1` 头） |
+
+安全性：监听只绑 loopback，公网到不了；GET 只有毛选快照与立绘；POST 强制 JSON
+content-type + 自定义头，跨站页面发不出这样的请求（需要 CORS 预检），因此不是 CSRF 洞。
+不需要时可用 `publicRoutes: false` 在插件配置里关掉。
+
+两条路怎么选：
+
+- **`--public`（默认推荐）**：不需要 token，桌面 App 旁边也能满血。
+- **`--token=<TOKEN>`**：CLI 宿主会打印 `dsh web: http://127.0.0.1:<port>/?token=<TOKEN>`，
+  复制给壳即可；壳用它换签名 cookie 后走 `/api`（cookie 失效会自动重换）。
+
+日常最省事：双击仓库根目录的 `启动小毛.command`——它自动找最近一次写入的
+`~/.dsh/agent-tree-dock-<port>.json` 得到宿主地址，然后用 `--public` 起壳。
+
+## 界面开关（不用双击）
+
+打开 Web 界面里小毛的红皮书卡片，页脚有 **「放她到桌面」/「收回桌宠」** 按钮：
+宿主插件通过 `POST /api/dsh-maoxuan-pet.shell` 拉起/结束本进程（见 `docs/API-CONTRACT.md`）。
+状态读 pidfile，所以无论壳是按钮起的还是双击 `启动小毛.command` 起的，按钮都认得出；
+壳自己还有单实例保护（已有活着的实例时新实例直接退出），不会叠出两只。
+
 ## 交互
 
 - **点小毛**：开合红皮书卡片；新气泡照样自动弹出、600ms 后自动标记已读——与 web 版同语义。

package/desktop/build.sh

@@ -14,4 +14,4 @@ swiftc -O \
 cp desktop/pet.html desktop/build/pet.html
 
 echo "built: desktop/build/maoxuan-pet"
-echo "run:   ./desktop/build/maoxuan-pet [--origin=http://127.0.0.1:3081] [--reset] [--verbose]"
+echo "run:   ./desktop/build/maoxuan-pet [--origin=http://127.0.0.1:3081] [--token=…] [--reset] [--verbose]"

package/desktop/maoxuan-pet.swift

@@ -8,29 +8,78 @@
 //     绕开 WKWebView 的跨域限制，页面只管渲染；
 //   - DSH 主窗口最小化甚至退出都不影响她站着——她是自己的进程。
 //
-// 用法：maoxuan-pet [--origin=http://127.0.0.1:3081 | --port=3081] [--reset] [--verbose]
+// 用法：maoxuan-pet [--origin=http://127.0.0.1:3081 | --port=3081] [--token=… | --public] [--reset] [--verbose]
+//       --token= 宿主 launch token（dsh web 启动日志 URL 里的 ?token=…）；开了鉴权的宿主（0.2.1-rc.2+）
+//       必须带，否则 API 全 401。先用它 GET /?token= 换签名 cookie，之后所有请求自动携带。
+//       --public 走插件自己的 loopback 公开路由（/dsh-maoxuan-pet/…）：不需要 token，
+//       桌面 App（不打印 token）旁边也能满血——这是日常推荐用法。
 // 退出：右键小毛 → 退出小毛。
 
 import AppKit
 import WebKit
 
+
 // MARK: - 配置
 
 enum Shell {
     static var origin = "http://127.0.0.1:3081"
     static var verbose = false
-    static let statePath = "/api/dsh-maoxuan-pet.state"
-    static let generatePath = "/api/dsh-maoxuan-pet.generate"
-    static let dismissPath = "/api/dsh-maoxuan-pet.dismiss"
+    /// 宿主 launch token（`dsh web` 启动时打印在 URL 的 ?token=…）。给了 token 就先走一次
+    /// `GET /?token=` 换回签名 cookie（dsh-auth-*，绑定 127.0.0.1:端口，30 天），之后
+    /// state/sprite/POST 全部自带 cookie——0.2.1-rc.2 起宿主 API 有鉴权，无 cookie 一律 401。
+    static var token: String?
+    /// 公开路由模式（`--public`）：走插件注册的 loopback 公开路由（/dsh-maoxuan-pet/…），
+    /// 不要 token、不要 cookie。宿主的 /api 有鉴权且拿不到 launch token 时（典型：桌面 App）
+    /// 用这个。POST 仍带 `x-dsh-maoxuan-pet: 1` 头，宿主据此拒绝跨站请求。
+    static var publicRoutes = false
+    static var statePath = "/api/dsh-maoxuan-pet.state"
+    static var generatePath = "/api/dsh-maoxuan-pet.generate"
+    static var dismissPath = "/api/dsh-maoxuan-pet.dismiss"
+    static var assetPath = "/api/dsh-maoxuan-pet.asset"
     static let windowWidth: CGFloat = 640
     static let windowHeight: CGFloat = 720
     static let defaults = UserDefaults(suiteName: "dsh-maoxuan-pet.window")!
 
     static func log(_ message: String) {
+        let line = "[maoxuan-pet] \(message)\n"
+        if verbose {
+            FileHandle.standardError.write(Data(line.utf8))
+        }
+        // 恒落文件：按钮拉起的壳 stdio 被宿主丢弃（stdio: 'ignore'），
+        // 没有这份日志，出问题就是黑盒。256KB 自动截断。
+        Self.appendToFile(line)
+    }
+
+    /// 高频日志（每秒多次的 input rects 等）只进 stderr，不刷文件。
+    static func debug(_ message: String) {
         guard verbose else { return }
         FileHandle.standardError.write(Data("[maoxuan-pet] \(message)\n".utf8))
     }
 
+    /// 关键诊断恒落一份到文件：按钮拉起的壳 stdio 被宿主丢弃（stdio: 'ignore'），
+    /// 没有这份日志，出问题就是黑盒。超过 256KB 从头截断，避免无限增长。
+    private static func appendToFile(_ line: String) {
+        let home = ProcessInfo.processInfo.environment["DSH_HOME"] ?? NSHomeDirectory() + "/.dsh"
+        let path = home + "/storages/dsh-maoxuan-pet.shell.log"
+        let dir = (path as NSString).deletingLastPathComponent
+        try? FileManager.default.createDirectory(atPath: dir, withIntermediateDirectories: true)
+        let formatter = DateFormatter()
+        formatter.dateFormat = "HH:mm:ss"
+        let stamped = "[" + formatter.string(from: Date()) + "] " + line
+        guard let data = stamped.data(using: .utf8) else { return }
+        if let handle = FileHandle(forWritingAtPath: path) {
+            if let attrs = try? FileManager.default.attributesOfItem(atPath: path),
+               let size = attrs[.size] as? NSNumber, size.intValue > 262_144 {
+                try? handle.truncate(atOffset: 0)
+            }
+            try? handle.seekToEndOfFile()
+            try? handle.write(contentsOf: data)
+            try? handle.close()
+        } else {
+            FileManager.default.createFile(atPath: path, contents: data)
+        }
+    }
+
     static func jsonString(_ value: Any) -> String {
         guard JSONSerialization.isValidJSONObject([value]),
               let data = try? JSONSerialization.data(withJSONObject: [value]),
@@ -75,19 +124,137 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
     private var webView: WKWebView!
     private var clickView: ClickThroughView!
     private var pollItem: DispatchWorkItem?
-    /// ephemeral：无磁盘缓存/cookie，壳不写任何本地数据（也躲开 ~/Library/Caches 权限噪音）
-    private lazy var http: URLSession = URLSession(configuration: .ephemeral)
+    /// ephemeral：无磁盘缓存，壳不写任何本地数据（也躲开 ~/Library/Caches 权限噪音）。
+    /// cookie 用内存 jar：--token 换回的 dsh-auth cookie 存在这里，每个请求自动携带，
+    /// 进程退出即消失，不落盘。
+    private lazy var httpConfig: URLSessionConfiguration = {
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.httpCookieAcceptPolicy = .always
+        configuration.httpShouldSetCookies = true
+        return configuration
+    }()
+    private lazy var http: URLSession = URLSession(configuration: httpConfig)
     private var dragBaseOrigin: NSPoint?
     private var pageReady = false
     private var lastInterval: TimeInterval = 20
     /// 精灵图 name → data URL：WebKit 的 ATS 会拦 file:// 页面直挂的 http 图，
     /// 所以素材也由原生层拉取后转 base64 注入，WebKit 全程零网络请求。
     private var spriteDataURLs: [String: String] = [:]
+    /// 页面就绪回放：WKWebView 加载完成前 evaluate 会落在将被丢弃的上下文里
+    /// （立绘/状态一次性注入从此丢失，页面永远停在占位形象）。页面第一次上报
+    /// rects 即「活着」，此时把手里已有的 state 与立绘重放一次，时序就无关紧要了。
+    private var replayedSpriteCount = 0
+    private var consecutiveFailures = 0
+    private var everSucceeded = false
+    private var rediscoveryCooldown = Date.distantPast
+    private var rediscoverHintShown = false
+    private var lastRegionDesc = ""
+    /// 穿透问题的釜底抽薪：窗口收缩到只有小毛（+展开的卡片）那么大，
+    /// 挡住后面 App 的区域天然就只有那一块——不用任何私有 API，渲染永远完整。
+    /// 右下角锚定缩放：stage 定位 right:44 bottom:56 固定，小毛本人纹丝不动。
+    private func syncWindowFrame(to union: CGRect) {
+        guard let window, union.width > 0 else { return }
+        // 只用 union 的「尺寸」、不用它的「位置」：位置随窗口高度 relayout 漂移，
+        // 尺寸稳定——这样窗口缩放没有反馈回路。右下角锚定 + stage right:44
+        // bottom:56 固定 ⇒ 小毛的屏幕位置纹丝不动。
+        let pad: CGFloat = 14
+        let width = max(union.width + 44 + pad, 160)
+        let height = max(union.height + 56 + pad, 220)
+        let frame = window.frame
+        guard abs(frame.width - width) > 1 || abs(frame.height - height) > 1 else { return }
+        window.setFrame(NSRect(x: frame.maxX - width, y: frame.minY, width: width, height: height), display: true)
+        Shell.log("window → \(Int(width))x\(Int(height)) @右下角锚定")
+    }
+
+
+    /// 宿主重启会换端口，壳却还指着旧 origin——这正是「连接中断」反复出现的原因。
+    /// 连续失败后扫 ~/.dsh/agent-tree-dock-*.json（文件名带端口，取最新修改的那个），
+    /// 用公开路由探活成功就跟随过去。--token 模式不自动跟随（token 是按次发放的）。
+    private func tryRediscover() {
+        guard Shell.token == nil else {
+            if !rediscoverHintShown {
+                rediscoverHintShown = true
+                Shell.log("宿主可能换了端口；token 模式不自动跟随——请点「收回」后重新放她到桌面")
+            }
+            return
+        }
+        let home = ProcessInfo.processInfo.environment["DSH_HOME"] ?? NSHomeDirectory() + "/.dsh"
+        guard let names = try? FileManager.default.contentsOfDirectory(atPath: home) else { return }
+        let newest = names
+            .filter { $0.hasPrefix("agent-tree-dock-") && $0.hasSuffix(".json") }
+            .compactMap { name -> (port: String, mtime: Date)? in
+                guard let start = name.range(of: "agent-tree-dock-")?.upperBound,
+                      let end = name.range(of: ".json")?.lowerBound, start < end else { return nil }
+                let port = String(name[start..<end])
+                let path = home + "/" + name
+                guard let attrs = try? FileManager.default.attributesOfItem(atPath: path),
+                      let mtime = attrs[.modificationDate] as? Date else { return nil }
+                return (port, mtime)
+            }
+            .max { $0.mtime < $1.mtime }
+        guard let newest, let port = Int(newest.port), (1024..<65536).contains(port) else { return }
+        let candidate = "http://127.0.0.1:\(port)"
+        guard candidate != Shell.origin, let url = URL(string: candidate + Shell.statePath) else { return }
+        var request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 4)
+        request.httpMethod = "GET"
+        http.dataTask(with: request) { [weak self] _, response, _ in
+            guard let http = response as? HTTPURLResponse, http.statusCode == 200 else { return }
+            DispatchQueue.main.async {
+                guard let self, Shell.origin != candidate else { return }
+                Shell.log("DSH 换了端口 → 跟随 \(candidate)（公开路由探活 200）")
+                Shell.origin = candidate
+                self.consecutiveFailures = 0
+                self.pollNow()
+            }
+        }.resume()
+    }
+    private var stateReplayed = false
+    private var lastStateJSON: String?
     private var spritePending = Set<String>()
+    private var authed = false
+    private var authInFlight = false
+
+    // MARK 壳的单实例与 pidfile
+
+    /// pidfile：让宿主插件（界面里的开关）认得出「壳是否活着」，包括手动起的。
+    /// 崩溃留下的陈旧 pid 由读取方用 kill(pid,0) 探活过滤，不依赖正常退出清理。
+    private func pidFilePath() -> String {
+        let home = ProcessInfo.processInfo.environment["DSH_HOME"] ?? NSHomeDirectory() + "/.dsh"
+        return home + "/storages/dsh-maoxuan-pet.shell.pid"
+    }
+
+    private func readLivePid() -> Int32? {
+        guard let raw = try? String(contentsOfFile: pidFilePath(), encoding: .utf8),
+              let pid = Int32(raw.trimmingCharacters(in: .whitespacesAndNewlines)), pid > 1 else { return nil }
+        guard kill(pid, 0) == 0 else { return nil }
+        // pid 会被系统复用：文件里的编号活着 ≠ 还是我们的小毛。校验进程身份。
+        var buffer = [CChar](repeating: 0, count: Int(MAXPATHLEN))
+        guard proc_pidpath(pid, &buffer, UInt32(MAXPATHLEN)) > 0,
+              String(cString: buffer).hasSuffix("maoxuan-pet") else { return nil }
+        return pid
+    }
+
+    private func writePid() {
+        let path = pidFilePath()
+        let dir = (path as NSString).deletingLastPathComponent
+        try? FileManager.default.createDirectory(atPath: dir, withIntermediateDirectories: true)
+        try? String(ProcessInfo.processInfo.processIdentifier.description)
+            .write(toFile: path, atomically: true, encoding: .utf8)
+    }
+
+    private func clearPid() {
+        try? FileManager.default.removeItem(atPath: pidFilePath())
+    }
 
     // MARK 生命周期
 
     func applicationDidFinishLaunching(_ notification: Notification) {
+        // 单实例：屏幕上已经有一只就不重复出来（宿主开关和手动双击都可能触发）
+        if let existing = readLivePid(), existing != ProcessInfo.processInfo.processIdentifier {
+            FileHandle.standardError.write(Data("[maoxuan-pet] 已有一只小毛在跑（pid \(existing)），这次就不重复出现了\n".utf8))
+            exit(0)
+        }
+        writePid()
         let content = NSRect(x: 0, y: 0, width: Shell.windowWidth, height: Shell.windowHeight)
         let window = PetWindow(
             contentRect: restoredFrame() ?? defaultFrame(),
@@ -135,6 +302,21 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
         self.webView = webView
         self.clickView = container
 
+        // 被谁杀的要有案底：SIGTERM/SIGINT/SIGHUP 落日志再走（SIGKILL 无法捕获）。
+        for name in [SIGTERM, SIGINT, SIGHUP] {
+            signal(name) { code in
+                Shell.log("收到信号 \(code)，退出")
+                exit(0)
+            }
+        }
+        DispatchQueue.main.async { [weak self] in
+            guard let self else { return }
+            let start = Date()
+            Timer.scheduledTimer(withTimeInterval: 30, repeats: true) { _ in
+                Shell.log("heartbeat up=\(Int(-start.timeIntervalSinceNow))s origin=\(Shell.origin)")
+            }
+        }
+
         if let html = locateHTML() {
             webView.loadFileURL(html, allowingReadAccessTo: html.deletingLastPathComponent())
         } else {
@@ -144,10 +326,16 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
         }
 
         window.orderFrontRegardless()
-        FileHandle.standardError.write(Data("[maoxuan-pet] 小毛已站上桌面 — \(Shell.origin)（独立进程，DSH 最小化不影响她）\n".utf8))
+        let authNote: String
+        if Shell.publicRoutes { authNote = "，公开路由模式（不需要 token）" }
+        else if Shell.token != nil { authNote = "，带 launch token（自动换 dsh-auth cookie）" }
+        else { authNote = "，无 token（宿主开鉴权时会是离线模式）" }
+        FileHandle.standardError.write(Data("[maoxuan-pet] 小毛已站上桌面 — \(Shell.origin)\(authNote)（独立进程，DSH 最小化不影响她）\n".utf8))
+        Shell.log("started pid=\(ProcessInfo.processInfo.processIdentifier) ppid=\(getppid()) origin=\(Shell.origin) auth=\(Shell.token == nil ? "public" : "token")")
     }
 
     func applicationWillTerminate(_ notification: Notification) {
+        clearPid()
         persistFrame()
     }
 
@@ -175,8 +363,14 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
         guard ProcessInfo.processInfo.arguments.contains("--reset") == false,
               let raw = Shell.defaults.string(forKey: "frame") else { return nil }
         let frame = NSRectFromString(raw)
-        let onScreen = NSScreen.screens.contains { $0.visibleFrame.intersects(frame) }
-        guard onScreen, frame.width > 100, frame.height > 100 else { return nil }
+        guard frame.width > 100, frame.height > 100 else { return nil }
+        // 小毛站在窗口右下角（stage right:44 bottom:56）：那一块必须在屏内。
+        // 只判「窗口与屏幕相交」会恢复出人在屏外的幽灵窗口——看起来就是丢了。
+        let petCorner = NSRect(x: frame.maxX - 220, y: frame.minY, width: 220, height: 300)
+        guard NSScreen.screens.contains(where: { $0.visibleFrame.intersection(petCorner) == petCorner }) else {
+            Shell.log("保存的位置会让小毛站在屏幕外（\(NSStringFromRect(frame))），改用默认位置")
+            return nil
+        }
         return frame
     }
 
@@ -206,6 +400,51 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
 
     // MARK 轮询（原生层负责全部 HTTP，页面不跨域）
 
+    /// 用 launch token 换签名 cookie：`GET /?token=…` → 303 + Set-Cookie（dsh-auth-*，
+    /// Max-Age 30 天，绑定 127.0.0.1:端口）。与浏览器打开 GUI 走的是同一条路；cookie 落在
+    /// URLSession 内存 jar 里，之后的 state / sprite / POST 每个请求自动携带。
+    /// token 来源：`dsh web`（CLI 宿主）启动日志第一行；桌面 App 不打印，拿不到就只能离线模式。
+    private func authenticate(_ token: String) {
+        if authInFlight { return }
+        authInFlight = true
+        guard var components = URLComponents(string: Shell.origin + "/") else {
+            authInFlight = false
+            return
+        }
+        components.queryItems = [URLQueryItem(name: "token", value: token)]
+        guard let url = components.url else {
+            authInFlight = false
+            return
+        }
+        var request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 8)
+        request.httpMethod = "GET"
+        Shell.log("auth: 用 launch token 换 cookie…")
+        http.dataTask(with: request) { [weak self] _, response, error in
+            DispatchQueue.main.async {
+                guard let self else { return }
+                self.authInFlight = false
+                if let error {
+                    Shell.log("auth failed: \(error.localizedDescription)")
+                    self.evaluate("window.__petOfflineSeen=true;if (window.__petOffline) window.__petOffline();")
+                    self.schedulePoll(after: 30)
+                    return
+                }
+                let status = (response as? HTTPURLResponse)?.statusCode ?? 0
+                let jar = self.httpConfig.httpCookieStorage
+                let hasAuthCookie = jar?.cookies?.contains { $0.name.hasPrefix("dsh-auth-") } ?? false
+                guard (200..<400).contains(status), hasAuthCookie else {
+                    Shell.log("auth HTTP \(status)，没换到 dsh-auth cookie——token 要来自同一个宿主进程（dsh web 启动日志里的 ?token=）")
+                    self.evaluate("window.__petOfflineSeen=true;if (window.__petOffline) window.__petOffline();")
+                    self.schedulePoll(after: 30)
+                    return
+                }
+                self.authed = true
+                Shell.log("auth ok：dsh-auth cookie 已入 jar，开始拉取 state")
+                self.pollNow()
+            }
+        }.resume()
+    }
+
     private func schedulePoll(after interval: TimeInterval) {
         pollItem?.cancel()
         let item = DispatchWorkItem { [weak self] in self?.pollNow() }
@@ -214,6 +453,10 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
     }
 
     private func pollNow() {
+        if let token = Shell.token, !authed {
+            authenticate(token)
+            return
+        }
         guard let url = URL(string: Shell.origin + Shell.statePath) else { return }
         var request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 8)
         request.httpMethod = "GET"
@@ -222,26 +465,44 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
                 guard let self else { return }
                 if let error {
                     Shell.log("state failed: \(error.localizedDescription)")
-                    self.evaluate("window.__petOffline && window.__petOffline();")
+                    self.evaluate("window.__petOfflineSeen=true;if (window.__petOffline) window.__petOffline();")
+                    self.consecutiveFailures += 1
+                    if self.consecutiveFailures >= 3 || (self.consecutiveFailures >= 1 && !self.everSucceeded), Date() >= self.rediscoveryCooldown {
+                        self.rediscoveryCooldown = Date().addingTimeInterval(20)
+                        self.tryRediscover()
+                    }
                     self.schedulePoll(after: 8)
                     return
                 }
                 if let http = response as? HTTPURLResponse, http.statusCode != 200 {
-                    Shell.log("state HTTP \(http.statusCode)")
-                    self.evaluate("window.__petOffline && window.__petOffline();")
+                    let snippet = String(data: (data ?? Data()).prefix(160), encoding: .utf8) ?? "-"
+                    Shell.log("state HTTP \(http.statusCode) url=\(url.absoluteString) body=\(snippet)")
+                    self.evaluate("window.__petOfflineSeen=true;if (window.__petOffline) window.__petOffline();")
+                    // 401 = jar 里的 cookie 失效了（宿主重启换了 launch token、或 30 天过期）：
+                    // 置回未鉴权，下一轮先用 --token 重新换一次 cookie 再拉。
+                    if http.statusCode == 401, Shell.token != nil { self.authed = false }
+                    self.consecutiveFailures += 1
+                    if self.consecutiveFailures >= 3 || (self.consecutiveFailures >= 1 && !self.everSucceeded), Date() >= self.rediscoveryCooldown {
+                        self.rediscoveryCooldown = Date().addingTimeInterval(20)
+                        self.tryRediscover()
+                    }
                     self.schedulePoll(after: 8)
                     return
                 }
                 guard let data, let text = String(data: data, encoding: .utf8) else {
-                    self.evaluate("window.__petOffline && window.__petOffline();")
+                    self.evaluate("window.__petOfflineSeen=true;if (window.__petOffline) window.__petOffline();")
                     self.schedulePoll(after: 8)
                     return
                 }
+                self.consecutiveFailures = 0
+                self.everSucceeded = true
                 // 生成中的话 3s 后紧跟下一条，让气泡尽快落地
                 let running = (text.contains("\"running\":true") || text.contains("\"running\" : true"))
                 self.lastInterval = running ? 3 : 20
                 self.ensureSprites(from: data)
-                self.evaluate("window.__petState && window.__petState(\(self.sanitized(text)));")
+                let payload = self.sanitized(text)
+                self.lastStateJSON = payload
+                self.evaluate("window.__petStateData=\(payload);if (window.__petState) window.__petState(window.__petStateData);")
                 self.schedulePoll(after: self.lastInterval)
             }
         }.resume()
@@ -261,7 +522,11 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
         }
         guard !newlyNeeded.isEmpty else { return }
         for entry in newlyNeeded {
-            guard let url = URL(string: Shell.origin + entry.path) else {
+            // 公开路由模式下 state 里的 sprite 路径仍是 /api/…，换到公开素材路由
+            let path = Shell.publicRoutes
+                ? entry.path.replacingOccurrences(of: "/api/dsh-maoxuan-pet.asset", with: "/dsh-maoxuan-pet/asset.png")
+                : entry.path
+            guard let url = URL(string: Shell.origin + path) else {
                 spritePending.remove(entry.name)
                 continue
             }
@@ -276,7 +541,7 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
                         self.spriteDataURLs[entry.name] = "data:\(mime);base64,\(data.base64EncodedString())"
                         Shell.log("sprite \(entry.name) ready (\(data.count) bytes)")
                     }
-                    self.evaluate("window.__petSprites && window.__petSprites(\(Shell.jsonString(self.spriteDataURLs)));")
+                    self.evaluate("window.__petSpriteData=\(Shell.jsonString(self.spriteDataURLs));if (window.__petSprites) window.__petSprites(window.__petSpriteData);")
                 }
             }.resume()
         }
@@ -303,6 +568,8 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
         var request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 200)
         request.httpMethod = "POST"
         request.setValue("application/json", forHTTPHeaderField: "content-type")
+        // 公开路由的 POST 要求这个头（跨站页面发不出来，宿主据此挡 CSRF）；/api 模式忽略它
+        request.setValue("1", forHTTPHeaderField: "x-dsh-maoxuan-pet")
         request.httpBody = body.data(using: .utf8)
         Shell.log("POST \(path) \(body)")
         http.dataTask(with: request) { [weak self] data, response, error in
@@ -341,6 +608,15 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
         case "input":
             // 页面上报的可交互矩形（CSS px，左上原点）→ 容器本地坐标（左下原点）
             guard let rects = body["rects"] as? [[String: Any]] else { return }
+            // 原始页面坐标（top-left）正是 CGS 形状要的坐标系
+            let raw: [CGRect] = rects.compactMap { dict in
+                guard let x = (dict["x"] as? NSNumber)?.doubleValue,
+                      let y = (dict["y"] as? NSNumber)?.doubleValue,
+                      let w = (dict["w"] as? NSNumber)?.doubleValue,
+                      let h = (dict["h"] as? NSNumber)?.doubleValue,
+                      w > 0, h > 0 else { return nil }
+                return CGRect(x: x, y: y, width: w, height: h)
+            }
             let contentHeight = webView.bounds.height
             let converted: [CGRect] = rects.compactMap { dict in
                 guard let x = (dict["x"] as? NSNumber)?.doubleValue,
@@ -351,7 +627,30 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
                 return CGRect(x: x, y: contentHeight - (y + h), width: w, height: h)
             }
             clickView.passRects = converted
-            Shell.log("input rects: \(converted.count)")
+            Shell.debug("input rects: \(converted.count)")
+            // 可点区域的并集写进日志：用户体感「隐形区域大」时，拿这行对账
+            let union = converted.reduce(CGRect.null) { $0.union($1) }
+            syncWindowFrame(to: union)
+            let desc = String(format: "input region: x=%.0f y=%.0f w=%.0f h=%.0f（窗口 %.0fx%.0f）",
+                              union.minX, union.minY, union.width, union.height,
+                              webView.bounds.width, webView.bounds.height)
+            if desc != lastRegionDesc {
+                lastRegionDesc = desc
+                Shell.log(desc)
+            }
+            // 页面就绪补发：立绘/首份 state 可能比页面加载完成更晚/更早到达，
+            // 一次性 evaluate 会落在将被丢弃的上下文里。rects 是页面「活着」的
+            // 心跳，数据比上次补发多就再补一轮——最终一定补齐。
+            if !stateReplayed, let payload = lastStateJSON {
+                stateReplayed = true
+                self.evaluate("window.__petStateData=\(payload);if (window.__petState) window.__petState(window.__petStateData);")
+                Shell.log("page ready → 补发 state")
+            }
+            if spriteDataURLs.count > replayedSpriteCount {
+                replayedSpriteCount = spriteDataURLs.count
+                self.evaluate("window.__petSpriteData=\(Shell.jsonString(spriteDataURLs));if (window.__petSprites) window.__petSprites(window.__petSpriteData);")
+                Shell.log("page ready → 补发立绘 \(replayedSpriteCount) 张")
+            }
 
         case "dragstart":
             dragBaseOrigin = window.frame.origin
@@ -405,12 +704,27 @@ while index < arguments.count {
     } else if argument.hasPrefix("--port=") {
         let value = String(argument.dropFirst("--port=".count))
         Shell.origin = "http://127.0.0.1:\(value)"
+    } else if argument.hasPrefix("--token=") {
+        // 容错：允许把「?token=xxx」整段或「token=xxx」一起粘进来
+        var value = String(argument.dropFirst("--token=".count)).trimmingCharacters(in: .whitespaces)
+        if value.hasPrefix("token=") { value = String(value.dropFirst("token=".count)) }
+        while value.hasSuffix("/") { value.removeLast() }
+        Shell.token = value.isEmpty ? nil : value
+    } else if argument == "--public" {
+        Shell.publicRoutes = true
     } else if argument == "--verbose" {
         Shell.verbose = true
     }
     index += 1
 }
 
+if Shell.publicRoutes {
+    Shell.statePath = "/dsh-maoxuan-pet/pet.json"
+    Shell.generatePath = "/dsh-maoxuan-pet/generate"
+    Shell.dismissPath = "/dsh-maoxuan-pet/dismiss"
+    Shell.assetPath = "/dsh-maoxuan-pet/asset.png"
+}
+
 let app = NSApplication.shared
 app.setActivationPolicy(.accessory) // 不占 Dock、不进 Cmd-Tab
 let controller = ShellController()

package/desktop/pet.html

@@ -21,12 +21,12 @@
   .mp-pet:hover{transform:translateY(-3px)}
   .mp-img{display:block;height:132px;width:auto;max-width:140px;object-fit:contain;filter:drop-shadow(0 10px 16px #050b14aa)}
   .mp-img[data-talking="on"]{animation:mp-bob 1.6s ease-in-out infinite}
-  .mp-fallback{height:132px;width:100px;filter:drop-shadow(0 10px 16px #050b14aa)}
+  .mp-fallback{height:118px;width:118px;filter:drop-shadow(0 10px 16px #050b14aa)}
   .mp-tag{margin-top:2px;font-size:10px;font-weight:700;letter-spacing:.06em;color:#ffe2bd;background:#5c0f0fd9;border:1px solid #ffd9a833;border-radius:999px;padding:2px 8px;white-space:nowrap;backdrop-filter:blur(8px)}
   .mp-dot{display:inline-block;width:6px;height:6px;border-radius:50%;margin-right:5px;background:#f6cf9a;box-shadow:0 0 6px #f6cf9aaa;vertical-align:1px}
   .mp-dot[data-off="off"]{background:#fca5a5;box-shadow:0 0 6px #fca5a5aa}
   .mp-bubble{position:absolute;z-index:2;right:calc(100% + 12px);bottom:30px;width:340px;animation:mp-in .16s ease-out}
-  .mp-card{position:relative;max-height:min(58vh,480px);overflow-y:auto;overflow-x:hidden;overscroll-behavior:contain;scrollbar-width:thin;scrollbar-color:#f6cf9a #5f1010dd;color:#fff3e4;border:1px solid #8f1616;border-radius:12px;background:linear-gradient(155deg,#b32323 0%,#941a1a 46%,#771111 100%);box-shadow:0 22px 54px #35040466,0 0 0 1px #ffd9a814 inset}
+  .mp-card{position:relative;max-height:480px;overflow-y:auto;overflow-x:hidden;overscroll-behavior:contain;scrollbar-width:thin;scrollbar-color:#f6cf9a #5f1010dd;color:#fff3e4;border:1px solid #8f1616;border-radius:12px;background:linear-gradient(155deg,#b32323 0%,#941a1a 46%,#771111 100%);box-shadow:0 22px 54px #35040466,0 0 0 1px #ffd9a814 inset}
   .mp-card::-webkit-scrollbar{width:8px;height:8px}
   .mp-card::-webkit-scrollbar-track{background:#5f1010cc;border-radius:8px}
   .mp-card::-webkit-scrollbar-thumb{background:linear-gradient(180deg,#f7d9a4,#d09a3f);border-radius:8px;border:1px solid #5f1010}
@@ -147,13 +147,21 @@ function current() {
 }
 
 // --- 渲染：宠物本体（一次性搭好，之后只改动态位） ----------------------------
-const FALLBACK_SVG = `<svg class="mp-fallback" viewBox="0 0 104 112" role="img" aria-label="鲸鱼娘占位图">
-  <ellipse cx="52" cy="62" rx="34" ry="30" fill="#2f6fd0"/><ellipse cx="43" cy="82" rx="22" ry="14" fill="#dbeafe"/>
-  <circle cx="41" cy="55" r="5" fill="#0b1220"/><circle cx="63" cy="55" r="5" fill="#0b1220"/>
-  <circle cx="43" cy="53" r="1.6" fill="#fff"/><circle cx="65" cy="53" r="1.6" fill="#fff"/>
-  <path d="M46 68 q6 5 12 0" stroke="#0b1220" stroke-width="2" fill="none" stroke-linecap="round"/>
-  <path d="M52 24 C 74 14, 92 26, 90 44 C 82 34, 68 34, 52 40 Z" fill="#2f6fd0"/>
-  <path d="M78 6 l4 10 10 4 -10 4 -4 10 -4 -10 -10 -4 10 -4 z" fill="#ef4444"/></svg>`;
+const FALLBACK_SVG = `<svg class="mp-fallback" viewBox="0 0 512 512" role="img" aria-label="鲸鱼娘·小毛 图标：红皮书《毛泽东选集》">
+  <rect x="0" y="0" width="512" height="512" rx="116" fill="#FFF6E9"/>
+  <rect x="14" y="14" width="484" height="484" rx="104" fill="none" stroke="#C1342B" stroke-width="6" stroke-opacity="0.16"/>
+  <g opacity="0.22"><rect x="132" y="112" width="286" height="308" rx="28" fill="#7A1410"/></g>
+  <g transform="translate(252,256) scale(1.08) translate(-258,-256)">
+    <path d="M330 118 h78 a14 14 0 0 1 14 14 v248 a14 14 0 0 1 -14 14 h-78 z" fill="#EFDFC4"/>
+    <path d="M356 138 v236 M382 138 v236" stroke="#D9C4A2" stroke-width="5" stroke-linecap="round" fill="none"/>
+    <rect x="120" y="104" width="232" height="304" rx="26" fill="#B3271E"/>
+    <rect x="120" y="104" width="46" height="304" rx="22" fill="#8F1E17"/>
+    <path d="M143 148 v216" stroke="#E8C36A" stroke-width="7" stroke-linecap="round" opacity="0.9" fill="none"/>
+    <rect x="192" y="126" width="142" height="260" rx="14" fill="none" stroke="#E8C36A" stroke-width="5" stroke-opacity="0.55"/>
+    <polygon fill="#E8C36A" points="263,150 273.32,181.76 306.72,181.76 279.7,201.74 289.02,234.5 263,214.25 236.98,234.5 246.3,201.74 219.28,181.76 252.68,181.76"/>
+    <g fill="#E8C36A"><rect x="215" y="272" width="96" height="16" rx="8"/><rect x="232" y="304" width="62" height="13" rx="6.5" opacity="0.78"/></g>
+  </g>
+</svg>`;
 
 PET_TAG.innerHTML = `
   <span id="pet-visual"></span>
@@ -381,6 +389,8 @@ window.__petSprites = (map) => {
   renderPetVisual();
   reportRects();
 };
+// 壳可能在当前脚本执行前就注入了立绘（--public 模式轮询极快）——这里回放
+if (window.__petSpriteData) window.__petSprites(window.__petSpriteData);
 window.__petState = (json) => {
   offline = false;
   state = json;
@@ -402,6 +412,9 @@ window.__petState = (json) => {
   renderAll();
 };
 window.__petOffline = () => { offline = true; busy = false; renderMeta(); renderCard(); };
+// 状态/离线标记可能早于本脚本到达（--public 轮询极快）——回放
+if (window.__petStateData) window.__petState(window.__petStateData);
+else if (window.__petOfflineSeen) window.__petOffline();
 window.__petActionDone = () => { busy = false; cardKey = ''; renderCard(); renderMeta(); };
 
 // 时钟：倒计时文案每秒刷新

package/docs/API-CONTRACT.md

@@ -143,6 +143,20 @@
 
 `{ "articles": [ { "id", "title", "year", "tags", "quote", "summary" } ] }`（不含全文，供 Client 展示“这小时读了哪篇”）。
 
+### `GET|POST /api/dsh-maoxuan-pet.shell`
+
+独立桌宠壳（macOS）的界面开关。
+
+- `GET`：状态快照 `{ "supported": true, "running": false, "pid": null, "building": false, "error": null }`。
+  `running` 读壳自己写的 pidfile（`$DSH_HOME/storages/dsh-maoxuan-pet.shell.pid`，读取方用
+  `kill(pid,0)` 探活），因此手动用 `启动小毛.command` 起的壳同样被认出。
+- `POST`：请求体 `{ "action": "launch" | "quit", "origin"?: "http://127.0.0.1:<port>" }`。
+  `launch` 时若产物缺失会先跑一次 `desktop/build.sh`（swiftc，最长 120s），随后以
+  `detached` 方式拉起 `desktop/build/maoxuan-pet --public [--origin=…]`——壳独立于宿主进程，
+  宿主重启不影响她。`origin` 必须匹配 `http://127.0.0.1:<port>` 才会透传（防注入）。
+  响应统一 `{ "ok": boolean, "supported", "running", "pid", "building", "error"? }`；
+  `action` 非法时 400。壳已活着时 `launch` 幂等返回 `{ ok: true, running: true }`。
+
 ## 4. 语料契约（`corpus/`）
 
 `corpus/index.json`：

package/index.js

@@ -16,8 +16,8 @@
  * node_modules without resolving any DSH-internal module.
  */
 import { readFile, writeFile, rename, mkdir, stat } from 'node:fs/promises';
-import { readFileSync } from 'node:fs';
-import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn, execFileSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -37,11 +37,30 @@ export const ROUTES = {
   dismiss: '/api/dsh-maoxuan-pet.dismiss',
   asset: '/api/dsh-maoxuan-pet.asset',
   corpus: '/api/dsh-maoxuan-pet.corpus',
+  shell: '/api/dsh-maoxuan-pet.shell',
+};
+
+/**
+ * Public (loopback, cookie-less) routes for the standalone macOS shell.
+ *
+ * `/api` is auth-gated from DSH 0.2.1-rc.2 on: a bare URLSession gets 401, and
+ * the launch token is only obtainable from a CLI-launched host (the desktop app
+ * never prints it). The native shell therefore needs its own door. These routes
+ * are registered straight on the web server (like static assets) and are
+ * deliberately narrow: GETs are read-only public data; POSTs additionally demand
+ * a JSON content-type plus `x-dsh-maoxuan-pet: 1` — a cross-site page cannot
+ * send that without a CORS preflight, so it is not a CSRF hole. The listener
+ * itself only binds loopback, so this is not reachable from the network.
+ */
+export const SHELL_ROUTES = {
+  state: '/dsh-maoxuan-pet/pet.json',
+  asset: '/dsh-maoxuan-pet/asset.png',
+  generate: '/dsh-maoxuan-pet/generate',
+  dismiss: '/dsh-maoxuan-pet/dismiss',
 };
 
 /** Sprite name -> file under assets/. */
-const SPRITES = {
-  idle: 'pet-idle.png',
+const SPRITES = {  idle: 'pet-idle.png',
   talk: 'pet-talk.png',
   blink: 'pet-blink.png',
   read: 'pet-read.png',
@@ -89,6 +108,10 @@ export function normaliseConfig(config) {
     timeoutMs: int(raw.timeoutMs, 180000, 10000, 900000),
     businessContext: typeof raw.businessContext === 'string' ? raw.businessContext.trim() : '',
     modelHint: typeof raw.modelHint === 'string' ? raw.modelHint.trim() : '',
+    // Loopback-public routes for the standalone desktop shell (see SHELL_ROUTES).
+    // On by default — without them the shell cannot show content next to the
+    // desktop app, which is auth-gated and never reveals its launch token.
+    publicRoutes: raw.publicRoutes !== false,
   };
 }
 
@@ -1135,82 +1158,166 @@ export function apply(ctx, config) {
     void ready.then(install).catch((error) => log('warn', `skill 注册失败：${error?.message ?? error}`));
   });
 
+  // --- desktop shell (macOS) supervisor -------------------------------------
+  // 独立桌宠壳是个单独的 Swift 进程；界面里的开关只负责 spawn / SIGTERM。
+  // 运行状态读壳自己写的 pidfile，所以用 启动小毛.command 手动起的壳也认得出，
+  // 不会出现「按钮说她没出来、其实她就在屏幕上」。
+  const shellBin = join(here, 'desktop', 'build', 'maoxuan-pet');
+  const shellScript = join(here, 'desktop', 'build.sh');
+  const shellPidPath = join(resolveDshHome(), 'storages', 'dsh-maoxuan-pet.shell.pid');
+  let shellChild = null;
+  let shellBusy = false;
+  let shellError = null;
+  const shellPlatform = process.platform === 'darwin';
+
+  const shellPid = () => {
+    try {
+      const pid = Number(readFileSync(shellPidPath, 'utf8').trim());
+      if (!Number.isInteger(pid) || pid <= 1) return null;
+      process.kill(pid, 0);
+      // pid 会被系统复用：编号活着 ≠ 还是小毛。校验进程名，防止徽章状态失真。
+      if (shellPlatform) {
+        const comm = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], { encoding: 'utf8' });
+        if (!comm.trim().endsWith('maoxuan-pet')) return null;
+      }
+      return pid;
+    } catch { return null; }
+  };
+
+  const shellStatus = () => {
+    const pid = shellPid();
+    return {
+      supported: shellPlatform,
+      running: Boolean(pid),
+      pid: pid ?? null,
+      building: shellBusy,
+      error: shellError,
+    };
+  };
+
+  /** 首次启动：产物不存在就先编（swiftc 几秒钟），编完再起。 */
+  const buildShell = () => new Promise((resolve, reject) => {
+    const child = spawn('bash', [shellScript], { cwd: here, stdio: 'ignore' });
+    const timer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+      reject(new Error('编译超时（120s）'));
+    }, 120000);
+    child.on('error', (error) => { clearTimeout(timer); reject(error); });
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      if (code === 0 && existsSync(shellBin)) resolve();
+      else reject(new Error(`编译失败（exit ${code}）——终端里跑一次 npm run pet:build 看报错`));
+    });
+  });
+
+  const launchShell = async (origin) => {
+    if (!shellPlatform) return { ok: false, supported: false, error: '独立桌宠壳目前只支持 macOS' };
+    const pid = shellPid();
+    if (pid) return { ok: true, ...shellStatus() };
+    if (shellBusy) return { ok: false, ...shellStatus(), error: '正在编译桌宠壳，等几秒' };
+    shellError = null;
+    try {
+      if (!existsSync(shellBin)) {
+        shellBusy = true;
+        await buildShell();
+      }
+      const args = ['--public'];
+      // 只接受 loopback origin：这个值来自浏览器 location.origin，别让它带去别处
+      if (typeof origin === 'string' && /^http:\/\/(127\.0\.0\.1|localhost|\[::1\]):\d{2,5}$/.test(origin)) {
+        origin = origin.replace('localhost', '127.0.0.1').replace('[::1]', '127.0.0.1');
+        args.push(`--origin=${origin}`);
+      }
+      const child = spawn(shellBin, args, { detached: true, stdio: 'ignore' });
+      child.unref();
+      shellChild = child;
+      return { ok: true, ...shellStatus() };
+    } catch (error) {
+      shellError = String(error?.message || error);
+      return { ok: false, ...shellStatus(), error: shellError };
+    } finally {
+      shellBusy = false;
+    }
+  };
+
+  const quitShell = () => {
+    const pid = shellPid();
+    if (pid) {
+      try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+    }
+    if (shellChild) {
+      try { shellChild.kill(); } catch { /* already gone */ }
+      shellChild = null;
+    }
+    shellError = null;
+    return { ok: true, ...shellStatus() };
+  };
+
   // --- transport -----------------------------------------------------------
+  // The same five handlers serve both doors: the authenticated `/api` routes the
+  // Web client uses, and the loopback-public routes the native shell uses.
+  const handlers = {
+    state: async () => { await ready; return json(snapshot()); },
+    corpus: async () => {
+      await ready;
+      return json({
+        articles: corpus.articles.map((a) => ({
+          id: a.id, title: a.title, year: a.year, tags: a.tags, quote: a.quote, summary: a.summary,
+        })),
+      });
+    },
+    generate: async () => {
+      await ready;
+      if (running) return json({ ok: true, running: true, bubble: null }, 202);
+      const result = await runOnce('manual');
+      if (!result.ok) return json(result, 500);
+      return json(result, 200);
+    },
+    dismiss: async (request) => {
+      await ready;
+      const body = await readBody(request);
+      const target = typeof body.id === 'string' && body.id
+        ? state.bubbles.find((b) => b.id === body.id)
+        : state.bubbles.find((b) => !b.read);
+      if (target && !target.read) {
+        target.read = true;
+        await persist();
+      }
+      return json({ ok: true, unread: state.bubbles.filter((b) => !b.read).length });
+    },
+    shell: async (request) => {
+      if (request.method !== 'POST') return json(shellStatus());
+      const body = await readBody(request);
+      const action = String(body.action || '');
+      if (action === 'launch') return json(await launchShell(body.origin));
+      if (action === 'quit') return json(quitShell());
+      return json({ ok: false, error: 'action 必须是 launch 或 quit' }, 400);
+    },
+    asset: async (request) => {
+      let sprite = 'idle';
+      try { sprite = new URL(request.url).searchParams.get('name') || 'idle'; } catch { sprite = 'idle'; }
+      const file = SPRITES[sprite] || SPRITES.idle;
+      try {
+        const [bytes, info] = await Promise.all([readFile(join(assetsDir, file)), stat(join(assetsDir, file))]);
+        if (!info.size) throw new MaoxuanPetError('空文件');
+        return new Response(bytes, {
+          headers: { 'content-type': 'image/png', 'cache-control': 'public, max-age=3600' },
+        });
+      } catch {
+        return text(`缺少素材：assets/${file}`, 404);
+      }
+    },
+  };
+
   ctx.inject?.(['connection'], (scope) => {
     const routes = [
-      {
-        path: ROUTES.state,
-        methods: ['GET'],
-        // Required: without an explicit body mode the bridge builds a GET request
-        // with a stream body and Node throws, which the Host surfaces as 400.
-        requestBody: 'buffered',
-        fetch: async () => { await ready; return json(snapshot()); },
-      },
-      {
-        path: ROUTES.corpus,
-        methods: ['GET'],
-        // Required: without an explicit body mode the bridge builds a GET request
-        // with a stream body and Node throws, which the Host surfaces as 400.
-        requestBody: 'buffered',
-        fetch: async () => {
-          await ready;
-          return json({
-            articles: corpus.articles.map((a) => ({
-              id: a.id, title: a.title, year: a.year, tags: a.tags, quote: a.quote, summary: a.summary,
-            })),
-          });
-        },
-      },
-      {
-        path: ROUTES.generate,
-        methods: ['POST'],
-        requestBody: 'buffered',
-        fetch: async () => {
-          await ready;
-          if (running) return json({ ok: true, running: true, bubble: null }, 202);
-          const result = await runOnce('manual');
-          if (!result.ok) return json(result, 500);
-          return json(result, 200);
-        },
-      },
-      {
-        path: ROUTES.dismiss,
-        methods: ['POST'],
-        requestBody: 'buffered',
-        fetch: async (request) => {
-          await ready;
-          const body = await readBody(request);
-          const target = typeof body.id === 'string' && body.id
-            ? state.bubbles.find((b) => b.id === body.id)
-            : state.bubbles.find((b) => !b.read);
-          if (target && !target.read) {
-            target.read = true;
-            await persist();
-          }
-          return json({ ok: true, unread: state.bubbles.filter((b) => !b.read).length });
-        },
-      },
-      {
-        path: ROUTES.asset,
-        methods: ['GET'],
-        // Required: without an explicit body mode the bridge builds a GET request
-        // with a stream body and Node throws, which the Host surfaces as 400.
-        requestBody: 'buffered',
-        fetch: async (request) => {
-          let sprite = 'idle';
-          try { sprite = new URL(request.url).searchParams.get('name') || 'idle'; } catch { sprite = 'idle'; }
-          const file = SPRITES[sprite] || SPRITES.idle;
-          try {
-            const [bytes, info] = await Promise.all([readFile(join(assetsDir, file)), stat(join(assetsDir, file))]);
-            if (!info.size) throw new MaoxuanPetError('空文件');
-            return new Response(bytes, {
-              headers: { 'content-type': 'image/png', 'cache-control': 'public, max-age=3600' },
-            });
-          } catch {
-            return text(`缺少素材：assets/${file}`, 404);
-          }
-        },
-      },
+      // Required: without an explicit body mode the bridge builds a GET request
+      // with a stream body and Node throws, which the Host surfaces as 400.
+      { path: ROUTES.state, methods: ['GET'], requestBody: 'buffered', fetch: () => handlers.state() },
+      { path: ROUTES.corpus, methods: ['GET'], requestBody: 'buffered', fetch: () => handlers.corpus() },
+      { path: ROUTES.generate, methods: ['POST'], requestBody: 'buffered', fetch: () => handlers.generate() },
+      { path: ROUTES.dismiss, methods: ['POST'], requestBody: 'buffered', fetch: (request) => handlers.dismiss(request) },
+      { path: ROUTES.asset, methods: ['GET'], requestBody: 'buffered', fetch: (request) => handlers.asset(request) },
+      { path: ROUTES.shell, methods: ['GET', 'POST'], requestBody: 'buffered', fetch: (request) => handlers.shell(request) },
     ];
     const disposers = routes.map((route) => scope.connection.fetch.register(route));
     scope.effect(() => () => {
@@ -1220,6 +1327,68 @@ export function apply(ctx, config) {
     }, 'maoxuan-pet.routes');
   });
 
+  // --- cookie-less transport for the standalone macOS shell -----------------
+  if (cfg.publicRoutes) {
+    ctx.inject?.(['webServer'], (webCtx) => {
+      // 只认真正的 webServer 服务：没有它（测试里的假 ctx、或非 web 宿主）就安静跳过，
+      // 可选增强绝不该把插件主体挂掉。
+      const server = webCtx?.webServer;
+      if (typeof server?.register !== 'function') {
+        log('debug', '公开路由不可用（宿主无 webServer），桌宠壳请改用 --token 走 /api');
+        return;
+      }
+      const register = (path, methods, handler) => {
+        const dispose = server.register({
+          kind: 'exact',
+          path,
+          handler: async (req, res) => {
+            if (!methods.includes(req.method)) {
+              res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8' });
+              res.end('method not allowed');
+              return;
+            }
+            if (req.method === 'POST') {
+              const type = String(req.headers['content-type'] || '');
+              if (!type.includes('application/json') || req.headers['x-dsh-maoxuan-pet'] !== '1') {
+                res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+                res.end('forbidden');
+                return;
+              }
+            }
+            try {
+              const chunks = [];
+              for await (const chunk of req) chunks.push(chunk);
+              const body = chunks.length ? Buffer.concat(chunks).toString('utf8') : '';
+              const request = new Request(`http://127.0.0.1${req.url || path}`, {
+                method: req.method,
+                headers: req.headers,
+                body: body || undefined,
+              });
+              const response = await handler(request);
+              res.writeHead(response.status, Object.fromEntries(response.headers));
+              res.end(Buffer.from(await response.arrayBuffer()));
+            } catch (error) {
+              res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+              res.end(String(error?.message || error));
+            }
+          },
+        });
+        return dispose;
+      };
+      const disposers = [
+        register(SHELL_ROUTES.state, ['GET'], () => handlers.state()),
+        register(SHELL_ROUTES.asset, ['GET'], (request) => handlers.asset(request)),
+        register(SHELL_ROUTES.generate, ['POST'], () => handlers.generate()),
+        register(SHELL_ROUTES.dismiss, ['POST'], (request) => handlers.dismiss(request)),
+      ];
+      webCtx.effect(() => () => {
+        for (const dispose of disposers) {
+          try { dispose?.(); } catch { /* already gone */ }
+        }
+      }, 'maoxuan-pet.shell-routes');
+    });
+  }
+
   // Start the clock only after the persisted snapshot is loaded.
   void ready.then(() => {
     if (!cfg.enabled) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-maoxuan-pet",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "DSH 悬浮宠物「鲸鱼娘·小毛」：每小时读一篇毛选，给创业中的你说一句能动手的督促；内置毛选公开语料与 maoxuan-pet preset。",
   "keywords": [
     "dsh",