mocode-pet-app 0.1.0

package/assets/mascot.svg

@@ -0,0 +1,58 @@
+<svg id="pet-svg-root" width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bodyGrad" x1="48" y1="48" x2="208" y2="220" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#1b263b"/>
+      <stop offset="1" stop-color="#0d1b2a"/>
+    </linearGradient>
+    <linearGradient id="cyanGrad" x1="60" y1="90" x2="196" y2="170" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#2afadf"/>
+      <stop offset="1" stop-color="#42a5f5"/>
+    </linearGradient>
+    <filter id="glow" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="3" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Antenna (id 供各状态切换灯光颜色/闪烁速率,不改变原始视觉/动画) -->
+  <line x1="128" y1="30" x2="128" y2="50" stroke="#2afadf" stroke-width="4" stroke-linecap="round"/>
+  <circle id="pet-antenna" cx="128" cy="24" r="7" fill="#2afadf" filter="url(#glow)">
+    <animate attributeName="opacity" values="1;0.3;1" dur="1.6s" repeatCount="indefinite"/>
+  </circle>
+
+  <!-- Body / terminal head(id 供 tool_call/error 状态的抖动/摆动变换) -->
+  <g id="pet-body-group">
+    <rect id="pet-body" x="40" y="50" width="176" height="150" rx="28" fill="url(#bodyGrad)" stroke="url(#cyanGrad)" stroke-width="3"/>
+
+    <!-- Screen face -->
+    <rect x="60" y="72" width="136" height="90" rx="14" fill="#0a1420" stroke="#2afadf" stroke-opacity="0.4" stroke-width="1.5"/>
+
+    <!-- Eyes (blinking) -->
+    <g filter="url(#glow)">
+      <rect x="86" y="104" width="14" height="26" rx="6" fill="url(#cyanGrad)">
+        <animate attributeName="height" values="26;2;26" keyTimes="0;0.5;1" dur="3.2s" repeatCount="indefinite"/>
+        <animate attributeName="y" values="104;117;104" keyTimes="0;0.5;1" dur="3.2s" repeatCount="indefinite"/>
+      </rect>
+      <rect x="156" y="104" width="14" height="26" rx="6" fill="url(#cyanGrad)">
+        <animate attributeName="height" values="26;2;26" keyTimes="0;0.5;1" dur="3.2s" repeatCount="indefinite"/>
+        <animate attributeName="y" values="104;117;104" keyTimes="0;0.5;1" dur="3.2s" repeatCount="indefinite"/>
+      </rect>
+    </g>
+
+    <!-- Mouth: simple dash(id 供 speaking 状态开合动画) -->
+    <rect id="pet-mouth" x="112" y="147" width="32" height="6" rx="3" fill="#2afadf" fill-opacity="0.8" filter="url(#glow)"/>
+  </g>
+
+  <!-- Arms(id 供 tool_call 状态的摆动动画) -->
+  <path id="pet-arm-left" d="M40 120 Q16 130 20 158" stroke="url(#cyanGrad)" stroke-width="8" stroke-linecap="round" fill="none"/>
+  <path id="pet-arm-right" d="M216 120 Q240 130 236 158" stroke="url(#cyanGrad)" stroke-width="8" stroke-linecap="round" fill="none"/>
+
+  <!-- Legs / feet -->
+  <rect x="76" y="200" width="20" height="26" rx="8" fill="url(#bodyGrad)" stroke="url(#cyanGrad)" stroke-width="2.5"/>
+  <rect x="160" y="200" width="20" height="26" rx="8" fill="url(#bodyGrad)" stroke="url(#cyanGrad)" stroke-width="2.5"/>
+  <rect x="66" y="222" width="40" height="10" rx="5" fill="#2afadf" fill-opacity="0.6"/>
+  <rect x="150" y="222" width="40" height="10" rx="5" fill="#2afadf" fill-opacity="0.6"/>
+</svg>

package/bin/pet-app.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// mocode-pet-app 可执行入口:用 electron 运行 dist/main.js。
+// mocode 主包的 src/pet/bridge.ts 通过 require.resolve('mocode-pet-app/bin/pet-app.js')
+// 定位本文件路径,再以 electron 可执行文件 spawn 它(而不是直接 node 运行——
+// electron 的 main 进程需要 electron 自带的运行时,不能用纯 node 跑)。
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import electronPath from 'electron';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const mainScript = path.join(__dirname, '..', 'dist', 'main.js');
+
+const child = spawn(String(electronPath), [mainScript], {
+  stdio: 'ignore',
+  detached: true,
+  windowsHide: true,
+});
+child.unref();

package/dist/assets/mascot.svg

@@ -0,0 +1,58 @@
+<svg id="pet-svg-root" width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bodyGrad" x1="48" y1="48" x2="208" y2="220" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#1b263b"/>
+      <stop offset="1" stop-color="#0d1b2a"/>
+    </linearGradient>
+    <linearGradient id="cyanGrad" x1="60" y1="90" x2="196" y2="170" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#2afadf"/>
+      <stop offset="1" stop-color="#42a5f5"/>
+    </linearGradient>
+    <filter id="glow" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="3" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Antenna (id 供各状态切换灯光颜色/闪烁速率,不改变原始视觉/动画) -->
+  <line x1="128" y1="30" x2="128" y2="50" stroke="#2afadf" stroke-width="4" stroke-linecap="round"/>
+  <circle id="pet-antenna" cx="128" cy="24" r="7" fill="#2afadf" filter="url(#glow)">
+    <animate attributeName="opacity" values="1;0.3;1" dur="1.6s" repeatCount="indefinite"/>
+  </circle>
+
+  <!-- Body / terminal head(id 供 tool_call/error 状态的抖动/摆动变换) -->
+  <g id="pet-body-group">
+    <rect id="pet-body" x="40" y="50" width="176" height="150" rx="28" fill="url(#bodyGrad)" stroke="url(#cyanGrad)" stroke-width="3"/>
+
+    <!-- Screen face -->
+    <rect x="60" y="72" width="136" height="90" rx="14" fill="#0a1420" stroke="#2afadf" stroke-opacity="0.4" stroke-width="1.5"/>
+
+    <!-- Eyes (blinking) -->
+    <g filter="url(#glow)">
+      <rect x="86" y="104" width="14" height="26" rx="6" fill="url(#cyanGrad)">
+        <animate attributeName="height" values="26;2;26" keyTimes="0;0.5;1" dur="3.2s" repeatCount="indefinite"/>
+        <animate attributeName="y" values="104;117;104" keyTimes="0;0.5;1" dur="3.2s" repeatCount="indefinite"/>
+      </rect>
+      <rect x="156" y="104" width="14" height="26" rx="6" fill="url(#cyanGrad)">
+        <animate attributeName="height" values="26;2;26" keyTimes="0;0.5;1" dur="3.2s" repeatCount="indefinite"/>
+        <animate attributeName="y" values="104;117;104" keyTimes="0;0.5;1" dur="3.2s" repeatCount="indefinite"/>
+      </rect>
+    </g>
+
+    <!-- Mouth: simple dash(id 供 speaking 状态开合动画) -->
+    <rect id="pet-mouth" x="112" y="147" width="32" height="6" rx="3" fill="#2afadf" fill-opacity="0.8" filter="url(#glow)"/>
+  </g>
+
+  <!-- Arms(id 供 tool_call 状态的摆动动画) -->
+  <path id="pet-arm-left" d="M40 120 Q16 130 20 158" stroke="url(#cyanGrad)" stroke-width="8" stroke-linecap="round" fill="none"/>
+  <path id="pet-arm-right" d="M216 120 Q240 130 236 158" stroke="url(#cyanGrad)" stroke-width="8" stroke-linecap="round" fill="none"/>
+
+  <!-- Legs / feet -->
+  <rect x="76" y="200" width="20" height="26" rx="8" fill="url(#bodyGrad)" stroke="url(#cyanGrad)" stroke-width="2.5"/>
+  <rect x="160" y="200" width="20" height="26" rx="8" fill="url(#bodyGrad)" stroke="url(#cyanGrad)" stroke-width="2.5"/>
+  <rect x="66" y="222" width="40" height="10" rx="5" fill="#2afadf" fill-opacity="0.6"/>
+  <rect x="150" y="222" width="40" height="10" rx="5" fill="#2afadf" fill-opacity="0.6"/>
+</svg>

package/dist/main.js

@@ -0,0 +1,284 @@
+// 桌宠 Electron 主进程:WS Server 单例 + 最新连接覆盖 + BrowserWindow 生命周期。
+// 不感知 mocode CLI 内部逻辑,只是纯粹的状态转发枢纽:接收 WS state 消息 → IPC 推给渲染进程。
+import { app, BrowserWindow, screen } from 'electron';
+import { WebSocketServer, WebSocket } from 'ws';
+import { createServer as createHttpServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { parseClientMessage, } from './protocol.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** 默认端口;MOCODE_PET_PORT 环境变量覆盖(与 mocode 主包 src/pet/bridge.ts 保持一致的默认假设)。 */
+const DEFAULT_PORT = 47821;
+function petPort() {
+    const v = process.env.MOCODE_PET_PORT;
+    const n = v ? Number(v) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_PORT;
+}
+/** 心跳:每 15s 检查一次,10s 内无 pong 视为死连接(design.md 默认假设)。 */
+const HEARTBEAT_CHECK_INTERVAL_MS = 15000;
+const HEARTBEAT_TIMEOUT_MS = 10000;
+/** 状态展示超时后自动回落(design.md 默认假设:done/aborted/error 短暂展示 1500ms)。 */
+const TRANSIENT_STATE_TIMEOUT_MS = 1500;
+/** 全局连接表 + 唯一活跃连接引用("最新连接覆盖"算法的状态载体,见 design.md Low-Level)。 */
+const connections = new Map();
+let activeSocket = null;
+let mainWindow = null;
+let transientTimer = null;
+/** 把状态推给渲染进程(IPC)。渲染进程窗口未就绪时静默丢弃(下次状态到达会重推)。 */
+function broadcastToRenderer(state, meta) {
+    if (!mainWindow || mainWindow.isDestroyed())
+        return;
+    try {
+        mainWindow.webContents.send('pet:state', { state, meta });
+    }
+    catch {
+        // 渲染进程尚未加载完毕或已崩溃:静默,不影响 Server 侧状态机
+    }
+    if (transientTimer) {
+        clearTimeout(transientTimer);
+        transientTimer = null;
+    }
+    if (state === 'done' || state === 'aborted' || state === 'error') {
+        transientTimer = setTimeout(() => {
+            // 展示超时:done/aborted → idle;error → thinking(工具报错后 agent 通常还会继续跑)。
+            // 简化实现:统一回 idle,若 agent 仍在跑,下一个 hook 事件会立即覆盖为正确状态。
+            broadcastToRenderer('idle');
+        }, TRANSIENT_STATE_TIMEOUT_MS);
+    }
+}
+/**
+ * 新连接建立时的处理:注册 ConnectionRecord,立即成为唯一 active(覆盖之前的 active)。
+ * 见 design.md "最新连接覆盖"算法:不断开旧连接,只是把它降级为非活跃(isActive=false)。
+ */
+function onConnection(socket) {
+    // 步骤 1:把之前的 active 连接降级(至多一条为 active,核心不变量)
+    if (activeSocket && connections.has(activeSocket)) {
+        connections.get(activeSocket).isActive = false;
+    }
+    // 步骤 2:新连接成为唯一 active(clientId 在收到 hello 前先留空,占位用连接本身作 key)
+    const record = {
+        socket,
+        clientId: '',
+        connectedAt: Date.now(),
+        lastPongAt: Date.now(),
+        isActive: true,
+    };
+    connections.set(socket, record);
+    activeSocket = socket;
+    send(socket, { type: 'welcome', isActive: true, ts: Date.now() });
+    broadcastToRenderer('idle'); // 新连接刚建立还没收到它的第一条 state,先归 idle 兜底
+    socket.on('message', (data) => onMessage(socket, String(data)));
+    socket.once('close', () => onDisconnect(socket));
+    socket.once('error', () => onDisconnect(socket));
+}
+/**
+ * 连接断开处理。若断开的是活跃连接:立即广播 idle,且不提升任何"次新"连接为新的活跃状态源
+ * (design.md Requirement 3.2 的核心约束)。
+ */
+function onDisconnect(socket) {
+    const wasActive = socket === activeSocket;
+    connections.delete(socket);
+    if (wasActive) {
+        activeSocket = null; // 强制清空,不回退到任何仍 open 的连接
+        broadcastToRenderer('idle');
+    }
+    // wasActive = false:该连接原本就被忽略,断开对当前状态源无影响
+}
+function onMessage(socket, raw) {
+    touchAlive(socket); // 收到任意消息即视为存活,刷新心跳超时判定基准
+    const msg = parseClientMessage(raw);
+    if (!msg)
+        return; // 畸形消息:静默丢弃,连接不断开(Requirement 6.1)
+    const record = connections.get(socket);
+    if (!record)
+        return;
+    switch (msg.type) {
+        case 'hello':
+            record.clientId = msg.clientId;
+            return;
+        case 'ping':
+            send(socket, { type: 'pong', ts: Date.now() });
+            return;
+        case 'bye':
+            onDisconnect(socket);
+            try {
+                socket.close(1000);
+            }
+            catch {
+                // no-op
+            }
+            return;
+        case 'state':
+            if (socket !== activeSocket)
+                return; // 非活跃连接的状态消息静默丢弃
+            broadcastToRenderer(msg.state, msg.meta);
+            return;
+        default:
+            return;
+    }
+}
+function send(socket, msg) {
+    try {
+        socket.send(JSON.stringify(msg));
+    }
+    catch {
+        // 静默:发送失败不影响 Server 主循环
+    }
+}
+/** 心跳巡检:每 HEARTBEAT_CHECK_INTERVAL_MS 检查所有连接,超时未 pong 的视为死连接并清理。 */
+function startHeartbeatSweep() {
+    const timer = setInterval(() => {
+        const now = Date.now();
+        for (const [socket, record] of connections) {
+            if (now - record.lastPongAt > HEARTBEAT_TIMEOUT_MS + HEARTBEAT_CHECK_INTERVAL_MS) {
+                try {
+                    socket.terminate();
+                }
+                catch {
+                    // no-op
+                }
+                onDisconnect(socket);
+            }
+        }
+    }, HEARTBEAT_CHECK_INTERVAL_MS);
+    timer.unref?.();
+    return timer;
+}
+/** pong 到达时更新 lastPongAt(客户端主动发 ping,这里作为 server 收 ping 后回 pong 的对端确认;
+ *  同时 server 也可能主动关心 client 是否存活——此处简化为"收到任意消息即视为存活"，
+ *  在 onMessage 里对每条消息更新，避免额外维护 ping/pong 状态机的复杂度)。 */
+function touchAlive(socket) {
+    const record = connections.get(socket);
+    if (record)
+        record.lastPongAt = Date.now();
+}
+/**
+ * 启动 WS Server;若端口已被占用则尝试 WS 握手验证占用方是否为桌宠自身。
+ * 验证通过(是桌宠)→ 静默退出(exit 0,已有实例在跑,不重复常驻)。
+ * 验证失败(端口被别的服务占用)→ 退出并附带诊断信息(exit 非 0)。
+ */
+async function startServer(port) {
+    return new Promise((resolve, reject) => {
+        const httpServer = createHttpServer();
+        const wss = new WebSocketServer({ server: httpServer });
+        httpServer.once('error', async (err) => {
+            if (err.code === 'EADDRINUSE') {
+                const isPet = await probeIsPetServer(port);
+                if (isPet) {
+                    console.log('[pet-app] 端口已有桌宠实例在运行,本进程退出。');
+                    process.exit(0);
+                }
+                else {
+                    console.error(`[pet-app] 端口 ${port} 被非桌宠进程占用,无法启动。`);
+                    process.exit(1);
+                }
+            }
+            else {
+                reject(err);
+            }
+        });
+        wss.on('connection', (socket) => {
+            touchAlive(socket);
+            onConnection(socket);
+        });
+        httpServer.listen(port, '127.0.0.1', () => {
+            resolve(wss);
+        });
+    });
+}
+/** 探测占用端口的服务是否是桌宠自身(能完成一次 WS 握手并收到 welcome)。 */
+function probeIsPetServer(port) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                ws.terminate();
+            }
+            catch {
+                // no-op
+            }
+            resolve(false);
+        }, 500);
+        ws.once('open', () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                ws.close();
+            }
+            catch {
+                // no-op
+            }
+            resolve(true);
+        });
+        ws.once('error', () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(false);
+        });
+    });
+}
+/** 跨平台悬浮窗配置(design.md 跨平台 BrowserWindow 配置差异表)。 */
+function createPetWindow() {
+    const { width } = screen.getPrimaryDisplay().workAreaSize;
+    const winSize = 220;
+    const margin = 24;
+    const win = new BrowserWindow({
+        width: winSize,
+        height: winSize,
+        x: width - winSize - margin,
+        y: screen.getPrimaryDisplay().workAreaSize.height - winSize - margin,
+        transparent: true,
+        frame: false,
+        alwaysOnTop: true,
+        skipTaskbar: true,
+        hasShadow: false,
+        resizable: false,
+        fullscreenable: false,
+        minimizable: false,
+        maximizable: false,
+        focusable: false,
+        webPreferences: {
+            preload: path.join(__dirname, 'renderer', 'preload.js'),
+            contextIsolation: true,
+            nodeIntegration: false,
+        },
+    });
+    if (process.platform === 'darwin') {
+        win.setAlwaysOnTop(true, 'floating');
+        app.dock?.hide();
+    }
+    else {
+        win.setAlwaysOnTop(true);
+    }
+    // 鼠标穿透:允许用户点击桌面下层内容,不遮挡操作。悬浮窗本身仍可接收自身渲染的动画更新。
+    win.setIgnoreMouseEvents(true);
+    win.loadFile(path.join(__dirname, 'renderer', 'index.html'));
+    win.webContents.on('render-process-gone', () => {
+        // 渲染进程崩溃但主进程(WS Server)存活:重建一次窗口,不重启 WS Server、不断开现有客户端连接。
+        console.error('[pet-app] 渲染进程崩溃,尝试重建窗口。');
+        if (mainWindow && !mainWindow.isDestroyed()) {
+            mainWindow.destroy();
+        }
+        mainWindow = createPetWindow();
+    });
+    return win;
+}
+app.whenReady().then(async () => {
+    const port = petPort();
+    await startServer(port);
+    startHeartbeatSweep();
+    mainWindow = createPetWindow();
+});
+app.on('window-all-closed', () => {
+    // 用户关闭悬浮窗:整个桌宠进程退出(WS Server 一并关闭,已连 mocode 客户端会收到 close 事件,
+    // 按 bridge.ts 的"连接异常不自动重连"策略,下次 /pet 会重新探测并拉起新实例)。
+    app.quit();
+});

package/dist/protocol.js

@@ -0,0 +1,87 @@
+// 桌宠 WS 协议:pet-app 子包侧的类型定义与消息校验。
+// 与 src/pet/protocol.ts(mocode 主包侧)字段保持一致,但两处各自维护副本——
+// 子包不依赖主包源码(两者是独立发布单元,主包只在需要时 spawn 子包的可执行文件)。
+/** 全部合法状态值(供运行时校验)。 */
+export const PET_STATES = [
+    'idle',
+    'thinking',
+    'speaking',
+    'tool_call',
+    'done',
+    'aborted',
+    'error',
+];
+/** 判断值是否为合法 PetState(供消息校验,非法值丢弃不崩)。 */
+export function isValidPetState(v) {
+    return typeof v === 'string' && PET_STATES.includes(v);
+}
+/** 校验并解析一条原始 JSON 字符串为 ClientMessage;失败(JSON 非法/缺字段/type 未知)返回 null。
+ *  永不抛错——Server 据此静默丢弃畸形消息,不断开连接(Requirement 6.1)。 */
+export function parseClientMessage(raw) {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== 'object' || obj === null)
+        return null;
+    const m = obj;
+    if (typeof m.ts !== 'number')
+        return null;
+    switch (m.type) {
+        case 'hello':
+            if (typeof m.clientId !== 'string' || typeof m.pid !== 'number' || typeof m.cwd !== 'string') {
+                return null;
+            }
+            return { type: 'hello', clientId: m.clientId, pid: m.pid, cwd: m.cwd, ts: m.ts };
+        case 'state': {
+            if (typeof m.clientId !== 'string' || !isValidPetState(m.state))
+                return null;
+            let meta;
+            if (m.meta && typeof m.meta === 'object') {
+                const mm = m.meta;
+                meta = {};
+                if (typeof mm.toolName === 'string')
+                    meta.toolName = mm.toolName;
+                if (typeof mm.errorMessage === 'string')
+                    meta.errorMessage = mm.errorMessage;
+            }
+            return { type: 'state', clientId: m.clientId, state: m.state, meta, ts: m.ts };
+        }
+        case 'ping':
+            return { type: 'ping', ts: m.ts };
+        case 'bye':
+            if (typeof m.clientId !== 'string')
+                return null;
+            return { type: 'bye', clientId: m.clientId, ts: m.ts };
+        default:
+            return null;
+    }
+}
+/** 校验并解析一条原始 JSON 字符串为 ServerMessage;失败返回 null(同上,永不抛错)。 */
+export function parseServerMessage(raw) {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== 'object' || obj === null)
+        return null;
+    const m = obj;
+    if (typeof m.ts !== 'number')
+        return null;
+    switch (m.type) {
+        case 'welcome':
+            if (typeof m.isActive !== 'boolean')
+                return null;
+            return { type: 'welcome', isActive: m.isActive, ts: m.ts };
+        case 'pong':
+            return { type: 'pong', ts: m.ts };
+        default:
+            return null;
+    }
+}

package/dist/renderer/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'self'; script-src 'self'; img-src 'self' data:; connect-src 'self' file:;" />
+  <title>mocode pet</title>
+  <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+  <div id="pet-container" class="pet-idle"></div>
+  <script src="renderer.js" type="module"></script>
+</body>
+</html>

package/dist/renderer/preload.js

@@ -0,0 +1,10 @@
+// Electron preload:通过 contextBridge 把主进程 IPC 推送的状态安全暴露给渲染进程(contextIsolation=true,
+// 不给渲染进程任何 Node/Electron API 访问权限,只转发一个只读回调注册接口)。
+import { contextBridge, ipcRenderer } from 'electron';
+contextBridge.exposeInMainWorld('petBridge', {
+    onState: (callback) => {
+        ipcRenderer.on('pet:state', (_event, payload) => {
+            callback(payload.state, payload.meta);
+        });
+    },
+});

package/dist/renderer/renderer.js

@@ -0,0 +1,46 @@
+// 渲染进程:纯展示逻辑,不含业务判断。接收 preload 暴露的 petBridge.onState 回调,
+// 按 PetState 切换外层容器的 CSS class,驱动 style.css 里定义的 @keyframes 动画。
+// mascot.svg 本身的呼吸灯/眨眼动画(inline <animate>)始终运行,不受这里的 class 切换影响。
+const ALL_STATE_CLASSES = [
+    'pet-idle',
+    'pet-thinking',
+    'pet-speaking',
+    'pet-tool',
+    'pet-done',
+    'pet-aborted',
+    'pet-error',
+];
+/** PetState → CSS class 映射表(design.md 动画映射表)。 */
+const STATE_CLASS = {
+    idle: 'pet-idle',
+    thinking: 'pet-thinking',
+    speaking: 'pet-speaking',
+    tool_call: 'pet-tool',
+    done: 'pet-done',
+    aborted: 'pet-aborted',
+    error: 'pet-error',
+};
+function applyState(container, state) {
+    container.classList.remove(...ALL_STATE_CLASSES);
+    container.classList.add(STATE_CLASS[state] ?? 'pet-idle');
+}
+window.addEventListener('DOMContentLoaded', async () => {
+    const container = document.getElementById('pet-container');
+    if (!container)
+        return;
+    applyState(container, 'idle');
+    // inline mascot.svg(而非 <img>/<object>)以保留其内部 id,供 style.css 的
+    // #pet-antenna / #pet-body-group / #pet-mouth / #pet-arm-left / #pet-arm-right 选择器生效
+    // (外部引用的 SVG 内容不可被外部 CSS 选中,必须 inline 进同一文档)。
+    try {
+        // 构建后 assets/ 与 renderer/ 同级复制到 dist/(见 scripts/copy-static.mjs),故用 ../assets。
+        const res = await fetch('../assets/mascot.svg');
+        const svgText = await res.text();
+        container.insertAdjacentHTML('afterbegin', svgText);
+    }
+    catch {
+        // 素材加载失败:容器保持空白,不影响状态机/IPC 正常工作(降级为无形象但仍可运行)
+    }
+    window.petBridge.onState((state) => applyState(container, state));
+});
+export {};

package/dist/renderer/style.css

@@ -0,0 +1,131 @@
+/* 桌宠渲染进程样式:状态驱动 CSS 动画,叠加在 mascot.svg 之上(不修改素材文件本身的结构)。
+ * 容器 #pet-container 承载 mascot.svg 的 <object>/inline 内容;通过外层 class 切换驱动
+ * transform / filter 变换,SVG 内置的呼吸灯(#pet-antenna)/眨眼动画始终独立运行不受影响。 */
+
+html, body {
+  margin: 0;
+  padding: 0;
+  width: 100%;
+  height: 100%;
+  background: transparent;
+  overflow: hidden;
+  -webkit-app-region: drag; /* 允许拖拽悬浮窗(鼠标穿透关闭区域外);实际穿透行为由主进程 setIgnoreMouseEvents 控制 */
+}
+
+#pet-container {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+#pet-container svg {
+  width: 90%;
+  height: 90%;
+}
+
+/* ── idle:轻微上下浮动呼吸,机身静止 ── */
+@keyframes pet-float {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-6px); }
+}
+.pet-idle #pet-body-group {
+  animation: pet-float 3s ease-in-out infinite;
+}
+
+/* ── thinking:天线灯加速闪烁 + 头部左右轻摆 ── */
+@keyframes pet-think-nod {
+  0%, 100% { transform: rotate(0deg); }
+  50% { transform: rotate(-4deg); }
+}
+@keyframes pet-antenna-fast-blink {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.25; }
+}
+.pet-thinking #pet-body-group {
+  animation: pet-think-nod 0.9s ease-in-out infinite;
+  transform-origin: 128px 125px;
+}
+.pet-thinking #pet-antenna {
+  animation: pet-antenna-fast-blink 0.6s ease-in-out infinite;
+}
+
+/* ── speaking:嘴部开合模拟说话 ── */
+@keyframes pet-mouth-talk {
+  0%, 100% { transform: scaleY(1); }
+  50% { transform: scaleY(2.4); }
+}
+.pet-speaking #pet-mouth {
+  animation: pet-mouth-talk 0.3s ease-in-out infinite;
+  transform-origin: 128px 150px;
+}
+
+/* ── tool_call:双臂交替摆动,天线灯常亮不闪 ── */
+@keyframes pet-arm-swing-left {
+  0%, 100% { transform: rotate(0deg); }
+  50% { transform: rotate(-12deg); }
+}
+@keyframes pet-arm-swing-right {
+  0%, 100% { transform: rotate(0deg); }
+  50% { transform: rotate(12deg); }
+}
+.pet-tool #pet-arm-left {
+  animation: pet-arm-swing-left 0.5s ease-in-out infinite;
+  transform-origin: 40px 120px;
+}
+.pet-tool #pet-arm-right {
+  animation: pet-arm-swing-right 0.5s ease-in-out infinite 0.25s;
+  transform-origin: 216px 120px;
+}
+.pet-tool #pet-antenna {
+  animation: none;
+  opacity: 1;
+}
+
+/* ── done:短暂放大弹回 + 眼睛描边变绿(用滤镜近似) ── */
+@keyframes pet-done-bounce {
+  0% { transform: scale(1); }
+  40% { transform: scale(1.1); }
+  100% { transform: scale(1); }
+}
+.pet-done #pet-body-group {
+  animation: pet-done-bounce 0.4s ease-out 1;
+  transform-origin: 128px 125px;
+}
+.pet-done #pet-antenna {
+  filter: drop-shadow(0 0 6px #4ade80);
+}
+
+/* ── aborted:头部短暂低垂 + 天线灯熄灭 ── */
+@keyframes pet-aborted-droop {
+  0% { transform: rotate(0deg); }
+  50% { transform: rotate(8deg); }
+  100% { transform: rotate(0deg); }
+}
+.pet-aborted #pet-body-group {
+  animation: pet-aborted-droop 0.3s ease-in-out 1;
+  transform-origin: 128px 125px;
+}
+.pet-aborted #pet-antenna {
+  animation: none;
+  opacity: 0;
+}
+
+/* ── error:机身横向抖动 + 天线灯变红闪烁 ── */
+@keyframes pet-error-shake {
+  0%, 100% { transform: translateX(0); }
+  25% { transform: translateX(-6px); }
+  75% { transform: translateX(6px); }
+}
+@keyframes pet-error-blink-red {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.3; }
+}
+.pet-error #pet-body-group {
+  animation: pet-error-shake 0.3s ease-in-out 1;
+}
+.pet-error #pet-antenna {
+  fill: #f87171;
+  animation: pet-error-blink-red 0.3s ease-in-out 2;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "mocode-pet-app",
+  "version": "0.1.0",
+  "description": "mocode 桌宠:独立 Electron 悬浮窗,展示 agent 执行状态动画。作为 mocode-ai 的可选子包,不随主包安装强制拉取。",
+  "private": false,
+  "type": "module",
+  "main": "dist/main.js",
+  "bin": {
+    "mocode-pet-app": "bin/pet-app.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "assets"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-static.mjs",
+    "start": "electron dist/main.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "electron": "43.0.0",
+    "ws": "8.21.0"
+  },
+  "devDependencies": {
+    "@types/ws": "8.5.13",
+    "typescript": "5.7.2"
+  },
+  "author": "wxy",
+  "license": "MIT"
+}