dsh-plugin-maoxuan-pet 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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 最小化甚至关掉界面，她都站在原地。

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,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/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,7 +8,11 @@
 //     绕开 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
@@ -19,9 +23,18 @@ import WebKit
 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")!
@@ -75,8 +88,16 @@ 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
@@ -84,10 +105,45 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
     /// 所以素材也由原生层拉取后转 base64 注入，WebKit 全程零网络请求。
     private var spriteDataURLs: [String: 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 }
+        return kill(pid, 0) == 0 ? pid : nil
+    }
+
+    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(),
@@ -144,10 +200,15 @@ 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))
     }
 
     func applicationWillTerminate(_ notification: Notification) {
+        clearPid()
         persistFrame()
     }
 
@@ -206,6 +267,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.__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.__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 +320,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"
@@ -229,6 +339,9 @@ final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelega
                 if let http = response as? HTTPURLResponse, http.statusCode != 200 {
                     Shell.log("state HTTP \(http.statusCode)")
                     self.evaluate("window.__petOffline && window.__petOffline();")
+                    // 401 = jar 里的 cookie 失效了（宿主重启换了 launch token、或 30 天过期）：
+                    // 置回未鉴权，下一轮先用 --token 重新换一次 cookie 再拉。
+                    if http.statusCode == 401, Shell.token != nil { self.authed = false }
                     self.schedulePoll(after: 8)
                     return
                 }
@@ -261,7 +374,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
             }
@@ -303,6 +420,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
@@ -405,12 +524,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/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,7 +16,7 @@
  * node_modules without resolving any DSH-internal module.
  */
 import { readFile, writeFile, rename, mkdir, stat } from 'node:fs/promises';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -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,160 @@ 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);
+      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:\d{2,5}$/.test(origin)) {
+        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 +1321,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.1",
   "description": "DSH 悬浮宠物「鲸鱼娘·小毛」：每小时读一篇毛选，给创业中的你说一句能动手的督促；内置毛选公开语料与 maoxuan-pet preset。",
   "keywords": [
     "dsh",