dsh-plugin-maoxuan-pet 0.2.3 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # CHANGELOG
 
+## 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 最小化甚至关掉界面，她都站在原地。
+
+### 桌宠壳（`desktop/`）
+- **为什么需要它**：Web 宠物是 `position:fixed` 的 DOM，永远画不出浏览器视口之外——DSH 最小化她就没。DSH 自带宠物能「跑出去」，是因为壳层进程建了第二个原生窗口（透明、置顶、跨所有 Space）。本壳用纯 Swift + 系统 WebKit（单文件约 450 行、零第三方依赖）给小毛配了同款独立窗口，进程独立于 DSH。
+- **窗口参数对照**（从 DSH Tauri 壳层二进制核实的参数 → 本壳实现）：`transparent`/`alwaysOnTop`/`visibleOnAllWorkspaces`/`skipTaskbar` → 透明无边框 `NSWindow` + `.floating` + `canJoinAllSpaces` + accessory 策略（不占 Dock、不进 Cmd-Tab）；`set_pet_input_region`/`set_pet_ignore_cursor_events` → 容器 `hitTest` 白名单矩形，矩形外鼠标事件全部穿透回桌面。
+- **数据通道**：`URLSession`（ephemeral）原生轮询既有同源路由——state 平时 20s、生成中 3s、离线 8s；`再督促`/`收起` POST 同源接口；宿主 `index.js` 零改动，Web 宠物照常并存。
+- **素材也走原生层**：WebKit 的 ATS 不认 loopback 豁免，`file://` 页面直挂 `http://127.0.0.1` 的图会被拦（只剩占位鲸），所以精灵图由 URLSession 拉取后转 data URL 注入（`window.__petSprites`）；WebKit 零网络请求，壳零磁盘写入（`nonPersistent` 数据存储 + ephemeral 会话）。
+- **交互语义与 Web 宠物一致**：红皮书卡片、新气泡自动弹出、打开 600ms 后标已读、翻书中状态、倒计时标签、`‹ ›` 回翻、Esc 收起；右键小毛 = 复位位置 / 退出；拖小毛或卡片标题栏 = 整窗移动（`screenX/screenY` 差值，无反馈回环），位置存 `UserDefaults`（suite `dsh-maoxuan-pet.window`）跨启动记忆。
+- **构建与运行**：`npm run pet:build`（swiftc 约几秒，模块缓存收进项目内）/ `npm run pet`；参数 `--origin=` / `--port=` / `--reset` / `--verbose`；详见 `desktop/README.md`。
+
+### 打包
+- `package.json` `files` 收录 `desktop/` 五个源码文件（Info.plist/README/build.sh/maoxuan-pet.swift/pet.html），源码随 npm 包分发；`desktop/build/` 构建产物（二进制 + Swift 模块缓存，约 70MB）不进包体——`.gitignore` 只拦 git 不拦 `npm pack`，files 白名单目录内的产物必须逐文件点名（0.3.0 发布前实测修正）。
+
 ## 0.2.3 — 2026-11-01
 
 首次安装修复：模型配置自动从宿主 profile 桥接进 headless 子进程，新装机基本零配置。

package/README.en.md

@@ -14,6 +14,22 @@ dsh plugin --profile web add dsh-plugin-maoxuan-pet
 Requirements: DSH `>=0.2.1-rc.2 <0.3.0`, Node `^22.19.0 || >=24.0.0`. Web shell only.
 Source install / uninstall / troubleshooting: [docs/INSTALL.md](docs/INSTALL.md).
 
+## Stand on the real desktop (macOS, optional)
+
+The web pet lives inside the DSH window and disappears when it is minimized — a hard browser
+sandbox boundary. `desktop/` ships a **standalone-process pet shell** (pure Swift + system
+WebKit, ~450 lines, zero dependencies): transparent, always-on-top, visible on all Spaces.
+Minimize DSH or close the window entirely — she stays. The plugin still owns the brain (the
+hourly essay reading); the shell only relocates the display.
+
+```bash
+npm run pet:build   # swiftc build, a few seconds
+npm run pet         # she stands at the bottom-right of your screen
+```
+
+Click to open the red-book card, drag to move (position is remembered), right-click for
+reset/quit. See [desktop/README.md](desktop/README.md) for details.
+
 ## Screenshot
 
 ![red-book bubble](https://raw.githubusercontent.com/yuna78/dsh-maoxuan-pet/main/docs/screenshot-hero.png)
@@ -70,7 +86,10 @@ fan-made character; not affiliated with DeepSeek.
 
 ## Known limitations
 
-- web shell only (`dsh.client.platform: web`) — no pet in the terminal / TUI;
+- web pet only (`dsh.client.platform: web`) — no pet in the terminal / TUI; on macOS use the
+  desktop shell above to leave the window;
+- the desktop shell is macOS-only (system WebKit); Windows / Linux need a Tauri 2 / Electron
+  shell — `pet.html` can be reused as-is;
 - the timer only runs while this `dsh web` process is alive; a stopped process does not catch up,
   and on restart `nextRunAt` decides whether to run once more;
 - each headless generation is a fresh session (no shared context): stable, but she "doesn't

package/README.md

@@ -1,4 +1,4 @@
-# 鲸鱼娘 · 小毛 —— 住在 DSH 右下角、每小时陪你读一篇毛选的桌宠
+# 鲸鱼娘 · 小毛 —— 每小时陪你读一篇毛选的桌宠，macOS 上还能站上真正的桌面
 
 红皮书气泡 + 四帧立绘；每条内容 = 原文引文（带来源日期）＋ 一句说给你听的督促 ＋ 一条能当天验证的启示，整条 ≤ 200 字。
 
@@ -13,6 +13,21 @@ dsh plugin --profile web add dsh-plugin-maoxuan-pet
 - 要求：DSH `>=0.2.1-rc.2 <0.3.0`、Node `^22.19.0 || >=24.0.0`，仅 Web 界面；
 - 从源码安装、卸载、排错：[docs/INSTALL.md](docs/INSTALL.md)。
 
+## 让她站上真正的桌面（macOS，可选）
+
+Web 宠物住在 DSH 界面里，界面最小化她就跟着没了——这是浏览器沙箱的硬边界。`desktop/` 目录自带一个**独立进程的桌宠壳**（纯 Swift + 系统 WebKit，约 450 行、零依赖）：透明、置顶、跨所有桌面空间，DSH 最小化甚至关掉界面她都站着；毛选的灵魂（每小时读一篇）仍由插件负责，壳只把「显示器」搬了出来。
+
+**最省事：不用碰终端。** 打开小毛的红皮书卡片，页脚有一个 **「放她到桌面」** 按钮——点她一下，小毛就以独立窗口站上桌面（首次会自动编译，几秒）；再点一次「收回桌宠」她就回界面里。不需要 token，不需要双击任何文件。
+
+两条备用路：
+
+- 双击仓库根目录的 `启动小毛.command`（自动连当前 DSH、自动 `--public`，重复双击不会叠出第二只）；
+- 命令行：`./desktop/build/maoxuan-pet --public`。
+
+点她开合红皮书卡片、拖她换位置（下次还在那儿、能拖出 DSH 窗口）、右键她 = 复位位置 / 退出。详见 [desktop/README.md](desktop/README.md)。
+
+> Windows / Linux：界面里的宠物照常可用，但「拖出窗口」的独立壳目前只有 macOS 实现；页面 `pet.html` 与路由是跨平台的，照 `desktop/README.md` 用 Tauri/Electron 包一层即可。
+
 ## 界面
 
 ![红皮书气泡](https://raw.githubusercontent.com/yuna78/dsh-maoxuan-pet/main/docs/screenshot-hero.png)
@@ -67,7 +82,8 @@ dsh plugin --profile web add dsh-plugin-maoxuan-pet
 
 ## 已知限制
 
-- 只支持 Web 界面（`dsh.client.platform: web`），终端 / TUI 里没有宠物；
+- Web 宠物只支持 Web 界面（`dsh.client.platform: web`），终端 / TUI 里没有宠物；macOS 想让她离开界面，用上面的桌宠壳；
+- 桌宠壳仅 macOS（系统 WebKit）；Windows / Linux 需要 Tauri 2 / Electron 起同款壳，`pet.html` 可直接复用；
 - 定时器只在这个 `dsh web` 进程活着时走；进程停了不会补跑，重启后按 `nextRunAt` 决定是否补一次；
 - headless 生成每次是独立会话（不复用上下文）：稳定，但「不记得昨天说过什么」——所以 prompt 里带最近 6 条督促来避免重复。
 

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,22 @@ 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,
+          style: {
+            position: 'fixed', right: 18, bottom: 18, zIndex: 2147483000,
+            border: '1px solid #ffd9a855', borderRadius: 999, cursor: 'pointer',
+            padding: '6px 14px', font: '12px/1.6 -apple-system, sans-serif',
+            color: '#ffe9c8', background: 'linear-gradient(180deg,#8f1d22,#6d1418)',
+            boxShadow: '0 4px 14px rgba(0,0,0,.28)',
+          },
+          'aria-label': '收回桌面上的小毛',
+        }, 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/Info.plist

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleIdentifier</key>
+	<string>dev.yuna.dsh-maoxuan-pet.shell</string>
+	<key>CFBundleName</key>
+	<string>maoxuan-pet</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<!-- 透明窗要画的宿主数据走 http://127.0.0.1，必须放开 ATS -->
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoads</key>
+		<true/>
+	</dict>
+	<key>NSHighResolutionCapable</key>
+	<true/>
+</dict>
+</plist>

package/desktop/README.md

@@ -0,0 +1,111 @@
+# 桌面壳：让小毛跑出 DSH 窗口（macOS）
+
+DSH 自带宠物之所以能「跑出去」，是因为它**根本不在网页里**——壳层 Rust 进程建了第二个
+原生窗口（透明、置顶、跨所有 Space）。网页（无论浏览器还是 iframe）永远画不出视口之外，
+这是浏览器沙箱的硬边界。
+
+本目录给「鲸鱼娘·小毛」配了一个**独立的原生壳**：进程独立于 DSH，DSH 主窗口最小化、
+甚至 Web 界面整个关掉，她都站在桌面上。毛选的灵魂（每小时一篇的 headless 生成）
+仍由 `index.js` 宿主插件负责，壳只是把「显示器」搬了出来。
+
+## 架构
+
+```
+┌─ DSH 宿主（照旧，什么都不用改） ─────────────┐
+│ index.js 插件：每小时 headless 读毛选 →     │
+│ GET  /api/dsh-maoxuan-pet.state             │
+│ POST /api/dsh-maoxuan-pet.generate|dismiss  │
+│ GET  /api/dsh-maoxuan-pet.asset?name=…      │
+└──────────────┬──────────────────────────────┘
+               │  URLSession 原生轮询（绕开 WKWebView 跨域）
+┌──────────────┴──────────────────────────────┐
+│ maoxuan-pet（独立 Swift 进程）               │
+│ · 透明无边框 NSWindow，.floating 置顶，      │
+│   canJoinAllSpaces（所有桌面/全屏旁可见）    │
+│ · WKWebView 渲染 pet.html（宠物+红皮书卡片） │
+│ · hitTest 白名单矩形 = 点击穿透              │
+│   （等价 dsh-tauri 的 set_pet_input_region） │
+│ · 拖拽/位置持久化/右键菜单/退出              │
+└─────────────────────────────────────────────┘
+```
+
+对照 DSH 自带宠物窗口（从壳层二进制里核实到的参数）：
+`transparent` / `alwaysOnTop` / `visibleOnAllWorkspaces` / `skipTaskbar` /
+`set_pet_input_region` / `set_pet_ignore_cursor_events` / 位置持久化到 store——
+本壳一一对应，只是把宿主从 Tauri 换成了一个几十 KB 的独立进程。
+
+## 构建与运行
+
+```sh
+npm run pet:build      # swiftc 编译（约几秒，产物 desktop/build/maoxuan-pet）
+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 版同语义。
+- **拖小毛或卡片标题栏**：整窗移动；原地松手才算点击（>4px 判定为拖拽）。
+- **右键小毛**：复位位置 / 退出小毛。
+- **Esc**：收起卡片。
+- 宿主不在时：圆点变红、卡片内提示「连接中断，重试中…」，人继续站着。
+
+## 已知边界
+
+- 仅 macOS（用系统 WebKit，零第三方依赖）。Windows/Linux 想要同款，
+  照 `docs/` 里 dsh-tauri 的窗口参数用 Tauri 2 或 Electron 起一个同样的壳即可，
+  页面（pet.html）不用改——它只依赖 `__petState/__petSprites/__petOffline/__petActionDone`
+  几个注入点和 `webkit.messageHandlers.pet` 一个消息通道。
+- **精灵图走原生层转 data URL**：WebKit 的 ATS 不认 loopback 豁免，
+  `file://` 页面直挂 `http://127.0.0.1` 的图会被拦（表现为只剩占位鲸），
+  所以素材由 URLSession 拉取后 base64 注入，WebKit 全程零网络请求。
+- 宿主关掉后她只是「待机」并不会死——离线轮询 8s 一次，开销可忽略。
+- 本壳不上传任何东西；全部数据都来自本机 harness 端口。

package/desktop/build.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# 构建独立桌宠壳：纯 Swift + 系统 WebKit，无第三方依赖。
+# 产物：desktop/build/maoxuan-pet（单文件可执行，pet.html 同目录随行）。
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+mkdir -p desktop/build
+# 模块缓存放进项目内：系统默认缓存目录（/var/folders/.../C/clang）可能不可写
+swiftc -O \
+  -module-cache-path desktop/build/.module-cache \
+  -o desktop/build/maoxuan-pet \
+  desktop/maoxuan-pet.swift \
+  -Xlinker -sectcreate -Xlinker __TEXT -Xlinker __info_plist -Xlinker desktop/Info.plist
+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] [--token=…] [--reset] [--verbose]"