dsh-plugin-maoxuan-pet 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # CHANGELOG
 
+## 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 子进程，新装机基本零配置。
+
+### 修复
+- **新装机必踩的 `MISSING_CREDENTIAL`**：插件每小时调用 `dsh --profile headless` 生成气泡，而随包 `headless` profile 是一个没有任何模型配置的空壳——官方 DeepSeek、中转线路的用户第一次安装都会生成失败，只能看到「离线摘录 + 报错」。
+- 现在**每次生成前自动把宿主 profile patch 里的 llm 条目**（`agent-default-model`、`dsh-llm-pi-ai`、`dsh-llm-deepseek-api-key`）**原样搬到** `$DSH_HOME/storages/dsh-maoxuan-pet.headless-overlay.yml`，并以 `dsh --profile headless --patch <overlay>` 启动子进程：宿主 GUI 能用什么模型（官方 / wocheng 之类任意中转），气泡子进程就能用什么，官方与中转线路零配置可用。
+- 待机行为：宿主 patch 没有 llm 条目（如机器确实没配过模型）时不写 overlay，`MISSING_CREDENTIAL` 报错会转成一句可操作的中文指引（保留原始错误摘要）写入 `state.lastError`；`dsh` 找不到（ENOENT）同样给出指引，其他报错原样透传。
+- overlay 内容变化才落盘（tmp + rename 原子写）；文件可随时手动删除，插件每次生成都会重写。子进程 llm 桥接失败不影响正常降级。
+
+### 升级行为
+- `profile` 配置默认仍是 `headless`。显式改 `profile` / `dshBin` 的老配置完全不受影响（此时不做桥接桥外干扰，`--patch` 只在 overlay 存在时追加）。
+- 新增并导出纯函数 `headlessOverlayPath` / `hostPatchPath` / `extractLlmPatchEntries` / `syncHeadlessOverlay` / `friendlyHeadlessError`；`verify/contract.mjs` 增加 llm 抽取与友好报错用例（40 断言全绿）。
+
 ## 0.2.2 — 2026-11-01
 
 展示层维护版：README 从技术说明改成安装页，npm 页面的介绍随之更新。

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)
@@ -55,7 +71,8 @@ fan-made character; not affiliated with DeepSeek.
     maxBubbles: 40
     headless: true          # false = only local excerpts, zero model calls
     dshBin: dsh
-    profile: headless
+    profile: headless       # since v0.2.3 the host GUI's model config is
+                            # bridged in automatically (official/relay, no setup)
     timeoutMs: 180000
     businessContext: "40, indie developer, small-tool SaaS"
 ```
@@ -69,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,17 @@ 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 最小化甚至关掉界面她都站着；毛选的灵魂（每小时读一篇）仍由插件负责，壳只把「显示器」搬了出来。
+
+```bash
+npm run pet:build   # swiftc 编译，几秒
+npm run pet         # 她就站在屏幕右下角了
+```
+
+点她开合红皮书卡片、拖她换位置（下次还在那儿）、右键她 = 复位位置 / 退出。详见 [desktop/README.md](desktop/README.md)。
+
 ## 界面
 
 ![红皮书气泡](https://raw.githubusercontent.com/yuna78/dsh-maoxuan-pet/main/docs/screenshot-hero.png)
@@ -51,7 +62,8 @@ dsh plugin --profile web add dsh-plugin-maoxuan-pet
     maxBubbles: 40
     headless: true          # false = 只用本地摘录，不花模型调用
     dshBin: dsh
-    profile: headless
+    profile: headless       # v0.2.3 起会自动把宿主 GUI 的模型配置桥接进来
+                            # （官方/中转线路通用，无需手动配置）
     timeoutMs: 180000
     businessContext: |-
       用户是一位正在创业的独立开发者……
@@ -66,7 +78,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/cordis.patch.yml

@@ -16,7 +16,8 @@
         quietHours: [2, 8]
         maxBubbles: 40
         headless: true
-        profile: headless
+        # 不写死 profile：插件默认跟随宿主的 DSH_PROFILE（宿主能用什么模型，
+        # 子进程就能用什么模型）。想强制某个 profile 再显式写 profile: xxx。
         timeoutMs: 180000
         businessContext: |-
           用户是一位正在创业的独立开发者/小团队创始人，关心客户获取、现金流、

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,74 @@
+# 桌面壳：让小毛跑出 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` |
+| `--reset` | 忽略保存的位置，回到屏幕右下 |
+| `--verbose` | 向 stderr 打轮询/POST/输入区日志 |
+
+无 Dock 图标、不进 Cmd-Tab（`NSActivationPolicy.accessory`）。窗口位置存在
+`UserDefaults`（suite `dsh-maoxuan-pet.window`），拖到哪儿下次就在哪儿。
+
+## 交互
+
+- **点小毛**：开合红皮书卡片；新气泡照样自动弹出、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] [--reset] [--verbose]"

package/desktop/maoxuan-pet.swift

@@ -0,0 +1,418 @@
+// desktop/maoxuan-pet.swift — 「鲸鱼娘·小毛」独立桌宠壳（macOS）
+//
+// 学 dsh-tauri-pet 的原生窗口思路，但**进程独立于 DSH**：
+//   - 透明、无边框、置顶、跨所有 Space 的 NSWindow + WKWebView
+//     （对应 Tauri 的 transparent / alwaysOnTop / visibleOnAllWorkspaces / skipTaskbar）；
+//   - 点击穿透用 hitTest 白名单矩形实现（等价 dsh-tauri 的 set_pet_input_region）；
+//   - 宿主数据由本进程 URLSession 轮询（等价宠物窗口的 session stream），
+//     绕开 WKWebView 的跨域限制，页面只管渲染；
+//   - DSH 主窗口最小化甚至退出都不影响她站着——她是自己的进程。
+//
+// 用法：maoxuan-pet [--origin=http://127.0.0.1:3081 | --port=3081] [--reset] [--verbose]
+// 退出：右键小毛 → 退出小毛。
+
+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"
+    static let windowWidth: CGFloat = 640
+    static let windowHeight: CGFloat = 720
+    static let defaults = UserDefaults(suiteName: "dsh-maoxuan-pet.window")!
+
+    static func log(_ message: String) {
+        guard verbose else { return }
+        FileHandle.standardError.write(Data("[maoxuan-pet] \(message)\n".utf8))
+    }
+
+    static func jsonString(_ value: Any) -> String {
+        guard JSONSerialization.isValidJSONObject([value]),
+              let data = try? JSONSerialization.data(withJSONObject: [value]),
+              let array = String(data: data, encoding: .utf8),
+              array.count > 1 else { return "{}" }
+        return String(array.dropFirst().dropLast())
+    }
+}
+
+// MARK: - 无边框窗口要显式声明可成为 key（Escape 关卡片需要键盘事件）
+
+final class PetWindow: NSWindow {
+    override var canBecomeKey: Bool { true }
+    override var canBecomeMain: Bool { true }
+}
+
+// MARK: - 点击穿透容器：白名单矩形之外，鼠标事件全部放行给桌面
+
+final class ClickThroughView: NSView {
+    weak var webView: WKWebView?
+    /// 容器本地坐标（左下原点）；矩形之外 hitTest 返回 nil → 点击落到下层窗口。
+    var passRects: [CGRect] = []
+
+    override func hitTest(_ aPoint: NSPoint) -> NSView? {
+        let local: NSPoint
+        if let superview {
+            local = convert(aPoint, from: superview)
+        } else {
+            local = aPoint
+        }
+        for rect in passRects where rect.contains(local) {
+            return webView
+        }
+        return nil
+    }
+}
+
+// MARK: - 主控制器
+
+final class ShellController: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKScriptMessageHandler {
+    private var window: PetWindow!
+    private var webView: WKWebView!
+    private var clickView: ClickThroughView!
+    private var pollItem: DispatchWorkItem?
+    /// ephemeral：无磁盘缓存/cookie，壳不写任何本地数据（也躲开 ~/Library/Caches 权限噪音）
+    private lazy var http: URLSession = URLSession(configuration: .ephemeral)
+    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] = [:]
+    private var spritePending = Set<String>()
+
+    // MARK 生命周期
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        let content = NSRect(x: 0, y: 0, width: Shell.windowWidth, height: Shell.windowHeight)
+        let window = PetWindow(
+            contentRect: restoredFrame() ?? defaultFrame(),
+            styleMask: [.borderless],
+            backing: .buffered,
+            defer: false
+        )
+        window.isOpaque = false
+        window.backgroundColor = .clear
+        window.hasShadow = false
+        window.level = .floating
+        window.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .ignoresCycle]
+        window.isMovableByWindowBackground = false
+        window.acceptsMouseMovedEvents = true
+        window.isReleasedWhenClosed = false
+        window.ignoresMouseEvents = false
+
+        let container = ClickThroughView(frame: content)
+        container.wantsLayer = true
+
+        let configuration = WKWebViewConfiguration()
+        // 壳不需要任何网站数据（位置持久化走原生 UserDefaults），用一次性存储免得碰 ~/Library/WebKit
+        configuration.websiteDataStore = .nonPersistent()
+        configuration.userContentController.add(self, name: "pet")
+        // __petEnv 必须在页面脚本运行前就位（didFinish 时内联脚本早已执行完）
+        let envScript = WKUserScript(
+            source: "window.__petEnv = \(Shell.jsonString(["origin": Shell.origin]));",
+            injectionTime: .atDocumentStart,
+            forMainFrameOnly: true
+        )
+        configuration.userContentController.addUserScript(envScript)
+
+        let webView = WKWebView(frame: container.bounds, configuration: configuration)
+        webView.autoresizingMask = [.width, .height]
+        webView.navigationDelegate = self
+        // WKWebView 画透明底的两件套
+        webView.setValue(false, forKey: "drawsBackground")
+        webView.underPageBackgroundColor = .clear
+
+        container.webView = webView
+        container.addSubview(webView)
+        window.contentView = container
+
+        self.window = window
+        self.webView = webView
+        self.clickView = container
+
+        if let html = locateHTML() {
+            webView.loadFileURL(html, allowingReadAccessTo: html.deletingLastPathComponent())
+        } else {
+            FileHandle.standardError.write(Data("[maoxuan-pet] 找不到 pet.html（应与可执行文件同目录）\n".utf8))
+            NSApp.terminate(nil)
+            return
+        }
+
+        window.orderFrontRegardless()
+        FileHandle.standardError.write(Data("[maoxuan-pet] 小毛已站上桌面 — \(Shell.origin)（独立进程，DSH 最小化不影响她）\n".utf8))
+    }
+
+    func applicationWillTerminate(_ notification: Notification) {
+        persistFrame()
+    }
+
+    /// pet.html 与可执行文件同目录（build.sh 负责拷贝）。
+    private func locateHTML() -> URL? {
+        let argv0 = CommandLine.arguments.first ?? "maoxuan-pet"
+        let executable = URL(fileURLWithPath: argv0).resolvingSymlinksInPath()
+        let candidate = executable.deletingLastPathComponent().appendingPathComponent("pet.html")
+        return FileManager.default.fileExists(atPath: candidate.path) ? candidate : nil
+    }
+
+    // MARK 窗口位置
+
+    private func defaultFrame() -> NSRect {
+        let visible = NSScreen.main?.visibleFrame
+            ?? NSRect(x: 0, y: 0, width: 1440, height: 900)
+        let origin = NSPoint(
+            x: visible.maxX - Shell.windowWidth - 28,
+            y: visible.minY + 96
+        )
+        return NSRect(origin: origin, size: NSSize(width: Shell.windowWidth, height: Shell.windowHeight))
+    }
+
+    private func restoredFrame() -> NSRect? {
+        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 }
+        return frame
+    }
+
+    private func persistFrame() {
+        guard let window else { return }
+        Shell.defaults.set(NSStringFromRect(window.frame), forKey: "frame")
+        Shell.log("frame saved: \(NSStringFromRect(window.frame))")
+    }
+
+    private func resetFrame() {
+        Shell.defaults.removeObject(forKey: "frame")
+        let frame = defaultFrame()
+        window.setFrame(frame, display: true)
+        persistFrame()
+    }
+
+    /// 拖拽落点收敛：至少留 140pt 在可见区域内，防止拖丢。
+    private func clampedOrigin(_ origin: NSPoint) -> NSPoint {
+        let size = window.frame.size
+        let center = NSPoint(x: origin.x + size.width / 2, y: origin.y + size.height / 2)
+        let screen = NSScreen.screens.first { $0.frame.contains(center) } ?? NSScreen.main
+        let visible = screen?.visibleFrame ?? NSRect(x: 0, y: 0, width: 1440, height: 900)
+        let clampedX = min(max(origin.x, visible.minX - size.width + 140), visible.maxX - 140)
+        let clampedY = min(max(origin.y, visible.minY - size.height + 140), visible.maxY - 40)
+        return NSPoint(x: clampedX, y: clampedY)
+    }
+
+    // MARK 轮询（原生层负责全部 HTTP，页面不跨域）
+
+    private func schedulePoll(after interval: TimeInterval) {
+        pollItem?.cancel()
+        let item = DispatchWorkItem { [weak self] in self?.pollNow() }
+        pollItem = item
+        DispatchQueue.main.asyncAfter(deadline: .now() + interval, execute: item)
+    }
+
+    private func pollNow() {
+        guard let url = URL(string: Shell.origin + Shell.statePath) else { return }
+        var request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 8)
+        request.httpMethod = "GET"
+        http.dataTask(with: request) { [weak self] data, response, error in
+            DispatchQueue.main.async {
+                guard let self else { return }
+                if let error {
+                    Shell.log("state failed: \(error.localizedDescription)")
+                    self.evaluate("window.__petOffline && window.__petOffline();")
+                    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();")
+                    self.schedulePoll(after: 8)
+                    return
+                }
+                guard let data, let text = String(data: data, encoding: .utf8) else {
+                    self.evaluate("window.__petOffline && window.__petOffline();")
+                    self.schedulePoll(after: 8)
+                    return
+                }
+                // 生成中的话 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)));")
+                self.schedulePoll(after: self.lastInterval)
+            }
+        }.resume()
+    }
+
+    /// 从 state 里拿 pet.sprites，逐张原生拉取并转 data URL 注入页面（一次性，之后命中缓存）。
+    private func ensureSprites(from stateData: Data) {
+        guard let obj = try? JSONSerialization.jsonObject(with: stateData),
+              let dict = obj as? [String: Any],
+              let pet = dict["pet"] as? [String: Any],
+              let sprites = pet["sprites"] as? [String: String] else { return }
+        var newlyNeeded: [(name: String, path: String)] = []
+        for (name, path) in sprites {
+            guard spriteDataURLs[name] == nil, !spritePending.contains(name) else { continue }
+            spritePending.insert(name)
+            newlyNeeded.append((name, path))
+        }
+        guard !newlyNeeded.isEmpty else { return }
+        for entry in newlyNeeded {
+            guard let url = URL(string: Shell.origin + entry.path) else {
+                spritePending.remove(entry.name)
+                continue
+            }
+            http.dataTask(with: URLRequest(url: url, timeoutInterval: 8)) { [weak self] data, response, error in
+                DispatchQueue.main.async {
+                    guard let self else { return }
+                    self.spritePending.remove(entry.name)
+                    if let error {
+                        Shell.log("sprite \(entry.name) failed: \(error.localizedDescription)")
+                    } else if let http = response as? HTTPURLResponse, http.statusCode == 200, let data {
+                        let mime = http.mimeType ?? "image/png"
+                        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)));")
+                }
+            }.resume()
+        }
+    }
+
+    /// JSON 文本直接内联为 JS 字面量；U+2028/2029 在旧解析器里会断行，换义掉。
+    private func sanitized(_ text: String) -> String {
+        text
+            .replacingOccurrences(of: "\u{2028}", with: "\\u2028")
+            .replacingOccurrences(of: "\u{2029}", with: "\\u2029")
+    }
+
+    private func evaluate(_ source: String) {
+        guard pageReady else { return }
+        webView.evaluateJavaScript(source, completionHandler: { result, error in
+            if let error { Shell.log("evaluate failed: \(error.localizedDescription)") }
+        })
+    }
+
+    // MARK POST 动作（再督促 / 收起）
+
+    private func postAction(path: String, body: String) {
+        guard let url = URL(string: Shell.origin + path) else { return }
+        var request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 200)
+        request.httpMethod = "POST"
+        request.setValue("application/json", forHTTPHeaderField: "content-type")
+        request.httpBody = body.data(using: .utf8)
+        Shell.log("POST \(path) \(body)")
+        http.dataTask(with: request) { [weak self] data, response, error in
+            DispatchQueue.main.async {
+                guard let self else { return }
+                if let error {
+                    Shell.log("POST failed: \(error.localizedDescription)")
+                } else if let http = (response as? HTTPURLResponse) {
+                    let bodyText = data.flatMap { String(data: $0, encoding: .utf8) } ?? ""
+                    Shell.log("POST \(path) → \(http.statusCode) \(String(bodyText.prefix(160)))")
+                }
+                self.evaluate("window.__petActionDone && window.__petActionDone();")
+                self.pollNow()
+            }
+        }.resume()
+    }
+
+    // MARK WKNavigationDelegate
+
+    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        pageReady = true
+        pollNow()
+    }
+
+    func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
+        Shell.log("page load failed: \(error.localizedDescription)")
+    }
+
+    // MARK WKScriptMessageHandler（页面 → 原生）
+
+    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
+        guard message.name == "pet",
+              let body = message.body as? [String: Any],
+              let type = body["type"] as? String else { return }
+        switch type {
+        case "input":
+            // 页面上报的可交互矩形（CSS px，左上原点）→ 容器本地坐标（左下原点）
+            guard let rects = body["rects"] as? [[String: Any]] else { return }
+            let contentHeight = webView.bounds.height
+            let converted: [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: contentHeight - (y + h), width: w, height: h)
+            }
+            clickView.passRects = converted
+            Shell.log("input rects: \(converted.count)")
+
+        case "dragstart":
+            dragBaseOrigin = window.frame.origin
+
+        case "dragto":
+            guard let base = dragBaseOrigin else { return }
+            let dx = (body["dx"] as? NSNumber)?.doubleValue ?? 0
+            let dy = (body["dy"] as? NSNumber)?.doubleValue ?? 0
+            let target = clampedOrigin(NSPoint(x: base.x + dx, y: base.y - dy))
+            window.setFrameOrigin(target)
+
+        case "dragend":
+            dragBaseOrigin = nil
+            persistFrame()
+
+        case "action":
+            let action = body["action"] as? String
+            if action == "generate" {
+                postAction(path: Shell.generatePath, body: "{}")
+            } else if action == "dismiss" {
+                let raw = body["id"] as? String ?? ""
+                let id = String(raw.filter { $0.isLetter || $0.isNumber || $0 == "-" || $0 == "_" })
+                let payload = id.isEmpty ? "{}" : "{\"id\":\"\(id)\"}"
+                postAction(path: Shell.dismissPath, body: payload)
+            }
+
+        case "config":
+            let action = body["action"] as? String
+            if action == "quit" {
+                NSApp.terminate(nil)
+            } else if action == "reset" {
+                resetFrame()
+            }
+
+        default:
+            break
+        }
+    }
+}
+
+// MARK: - 入口
+
+let arguments = ProcessInfo.processInfo.arguments
+var index = 1
+while index < arguments.count {
+    let argument = arguments[index]
+    if argument.hasPrefix("--origin=") {
+        var value = String(argument.dropFirst("--origin=".count))
+        while value.hasSuffix("/") { value.removeLast() }
+        Shell.origin = value
+    } else if argument.hasPrefix("--port=") {
+        let value = String(argument.dropFirst("--port=".count))
+        Shell.origin = "http://127.0.0.1:\(value)"
+    } else if argument == "--verbose" {
+        Shell.verbose = true
+    }
+    index += 1
+}
+
+let app = NSApplication.shared
+app.setActivationPolicy(.accessory) // 不占 Dock、不进 Cmd-Tab
+let controller = ShellController()
+app.delegate = controller
+app.run()