mocode-ai 0.2.1 → 0.2.2

package/dist/agent/index.js

@@ -10,6 +10,7 @@ import * as layout from '../ui/layout.js';
 import { beginTurn } from '../rollback/index.js';
 import { config } from '../config/index.js';
 import { runAgentCore, isMutationTool, } from './core.js';
+import { createPetHooks } from '../pet/state.js';
 /** 工具调用 ● 头:工具名 + 参数摘要(按 tool_calls 原顺序打印,让用户看到本轮跑哪些工具)。 */
 function writeToolHeader(tc) {
     const summary = summarizeToolCall(tc.name, tc.arguments);
@@ -104,16 +105,36 @@ onContextUpdate) {
         },
         onDone: (elapsedMs) => layout.contentWrite(`  ${ui.dim}✻ Worked for ${fmtElapsed(elapsedMs)}${ui.reset}\n`),
     };
+    // 桌宠状态广播:与 TUI hooks 并列注入,互不干扰(petHooks 只调 bridge.sendState,不写屏;
+    // 未 /pet 连接时 sendState 内部 no-op)。仅主 agent 走这里——子 agent(spawn.ts)不引用 createPetHooks,
+    // 故子 agent 永不广播桌宠状态。
+    const petHooks = createPetHooks();
+    const combinedHooks = mergeHooks(hooks, petHooks);
     try {
         await runAgentCore({
             history,
             userInput,
             signal,
             onContextUpdate,
-            hooks,
+            hooks: combinedHooks,
         });
     }
     finally {
         spinner.stop();
     }
 }
+/** 把两组 AgentHooks 合并为一组:每个方法依次调用两侧已定义的实现(顺序不保证跨方法一致,
+ *  但同一事件内先 a 后 b)。用于把桌宠状态广播 hooks 与 TUI 渲染 hooks 并列挂载,互不影响。 */
+function mergeHooks(a, b) {
+    const merged = {};
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+        const fa = a[key];
+        const fb = b[key];
+        merged[key] = (...args) => {
+            fa?.(...args);
+            fb?.(...args);
+        };
+    }
+    return merged;
+}

package/dist/pet/bridge.js

@@ -0,0 +1,418 @@
+// 桌宠 WS 客户端 + 生命周期管理(mocode 主包侧,不 import electron)。
+// /pet 命令(src/repl/index.ts)调 togglePet();主 agent hooks(src/pet/state.ts createPetHooks)
+// 调 sendState() 广播状态。所有失败路径均静默降级——桌宠是可选增强,绝不能拖垮/中断主 agent 循环。
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import WebSocket from 'ws';
+import { parseServerMessage } from './protocol.js';
+/** 默认端口;MOCODE_PET_PORT 环境变量覆盖(design.md 默认假设)。 */
+export const DEFAULT_PET_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_PET_PORT;
+}
+/** 探测端口超时(ms)。 */
+const PROBE_TIMEOUT_MS = 300;
+/** spawn 拉起后的退避重试序列(ms),design.md 默认假设。 */
+const RETRY_DELAYS_MS = [200, 400, 800, 1600, 3200];
+/** 心跳间隔 / 超时(design.md 默认假设)。 */
+const HEARTBEAT_INTERVAL_MS = 15000;
+const HEARTBEAT_TIMEOUT_MS = 10000;
+/** 本进程稳定的 clientId(进程存活期间不变)。 */
+const clientId = `${process.pid}-${randomUUID()}`;
+let socket = null;
+let lastSentState = null;
+let heartbeatTimer = null;
+let heartbeatTimeoutTimer = null;
+/** list_skins 请求的等待队列(先进先出;桌宠单连接场景下不会有并发歧义)。 */
+let pendingSkinListResolvers = [];
+function clearHeartbeat() {
+    if (heartbeatTimer)
+        clearInterval(heartbeatTimer);
+    if (heartbeatTimeoutTimer)
+        clearTimeout(heartbeatTimeoutTimer);
+    heartbeatTimer = null;
+    heartbeatTimeoutTimer = null;
+}
+/** 心跳超时未收到 pong → 视为死连接,清理本地状态(不重连;下次 /pet 触发时重新探测)。 */
+function startHeartbeat(ws) {
+    clearHeartbeat();
+    heartbeatTimer = setInterval(() => {
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            ws.send(JSON.stringify({ type: 'ping', ts: Date.now() }));
+        }
+        catch {
+            // 发送失败:静默,等超时定时器兜底清理
+        }
+        heartbeatTimeoutTimer = setTimeout(() => {
+            try {
+                ws.terminate();
+            }
+            catch {
+                // no-op
+            }
+        }, HEARTBEAT_TIMEOUT_MS);
+    }, HEARTBEAT_INTERVAL_MS);
+    heartbeatTimer.unref?.();
+}
+/**
+ * 探测本地端口是否已有 WS server 监听并可完成一次 WS 握手。
+ * 前置条件:port 为合法端口号。
+ * 后置条件:返回 true 表示 <timeoutMs> 内握手成功(桌宠已在跑);false 表示超时/拒绝连接。
+ * 无副作用(探测用的临时连接在返回前关闭)。
+ */
+export function probePort(port, timeoutMs = PROBE_TIMEOUT_MS) {
+    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);
+        }, timeoutMs);
+        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);
+        });
+    });
+}
+/**
+ * 拉起独立 Electron 桌宠进程(detached,不随当前 mocode 进程退出而杀死)。
+ * 前置条件:调用方已确认端口未被占用(避免重复 spawn)。
+ * 后置条件:
+ *   - resolve() 表示 spawn 系统调用成功发出(不代表桌宠已可连接,调用方需配合 connectWithBackoff)。
+ *   - reject(err) 表示可执行文件不可解析(mocode-pet-app 未安装/安装失败)——降级路径。
+ */
+export function spawnPetProcess() {
+    return new Promise((resolve, reject) => {
+        let binPath;
+        try {
+            const require = createRequire(import.meta.url);
+            binPath = require.resolve('mocode-pet-app/bin/pet-app.js');
+        }
+        catch (e) {
+            reject(new Error('mocode-pet-app 未安装,请运行 npm install mocode-pet-app'));
+            return;
+        }
+        try {
+            const child = spawn(process.execPath, [binPath], {
+                detached: true,
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            child.once('error', (err) => reject(err));
+            child.unref();
+            resolve();
+        }
+        catch (e) {
+            reject(e instanceof Error ? e : new Error(String(e)));
+        }
+    });
+}
+/**
+ * 按退避序列重试连接,直到成功或耗尽重试次数。
+ * 前置条件:retryDelaysMs 非空、单调(本设计取 [200,400,800,1600,3200])。
+ * 后置条件:
+ *   - resolve(ws) 表示某次尝试内 probePort/connect 成功。
+ *   - reject(err) 表示所有尝试均失败,err 汇总最后一次失败原因。
+ * 循环不变量:每次尝试前 attempts < retryDelaysMs.length;每次失败后 attempts 严格 +1。
+ */
+export async function connectWithBackoff(port, retryDelaysMs = RETRY_DELAYS_MS) {
+    let lastErr = new Error('连接失败');
+    for (let attempts = 0; attempts < retryDelaysMs.length; attempts++) {
+        await sleep(retryDelaysMs[attempts]);
+        const ok = await probePort(port, PROBE_TIMEOUT_MS);
+        if (ok) {
+            try {
+                return await openConnection(port);
+            }
+            catch (e) {
+                lastErr = e instanceof Error ? e : new Error(String(e));
+                continue;
+            }
+        }
+        lastErr = new Error('桌宠尚未就绪(端口未监听)');
+    }
+    throw lastErr;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** 真正建立并返回一条打开的 WS 连接(不做探测,假定端口已确认可连)。 */
+function openConnection(port) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+        const timer = setTimeout(() => {
+            try {
+                ws.terminate();
+            }
+            catch {
+                // no-op
+            }
+            reject(new Error('连接超时'));
+        }, PROBE_TIMEOUT_MS * 2);
+        ws.once('open', () => {
+            clearTimeout(timer);
+            resolve(ws);
+        });
+        ws.once('error', (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+}
+/** 连接建立后的公共收尾:发 hello、挂消息/关闭监听、起心跳。 */
+function wireConnection(ws) {
+    socket = ws;
+    lastSentState = null;
+    const hello = {
+        type: 'hello',
+        clientId,
+        pid: process.pid,
+        cwd: process.cwd(),
+        ts: Date.now(),
+    };
+    try {
+        ws.send(JSON.stringify(hello));
+    }
+    catch {
+        // 静默:hello 发送失败不影响后续状态广播尝试(sendState 内部会再检查连接状态)
+    }
+    ws.on('message', (data) => {
+        const msg = parseServerMessage(String(data));
+        if (!msg)
+            return; // 解析失败静默丢弃(协议层已保证不抛错)
+        if (msg.type === 'pong' && heartbeatTimeoutTimer) {
+            clearTimeout(heartbeatTimeoutTimer);
+            heartbeatTimeoutTimer = null;
+            return;
+        }
+        if (msg.type === 'skin_list') {
+            const resolver = pendingSkinListResolvers.shift();
+            resolver?.(msg);
+            return;
+        }
+    });
+    ws.once('close', () => {
+        if (socket === ws) {
+            socket = null;
+            clearHeartbeat();
+        }
+    });
+    ws.once('error', () => {
+        // 连接异常:不自动重连(避免用户已关闭桌宠窗口时无限重连刷日志);下次 /pet 触发时重新走探测/拉起流程。
+        if (socket === ws) {
+            socket = null;
+            clearHeartbeat();
+        }
+    });
+    startHeartbeat(ws);
+}
+/**
+ * 发送一次状态消息(经节流:与上次发送状态相同则跳过)。
+ * 前置条件:无(未连接时静默 no-op,不抛错、不阻塞 agent 主循环)。
+ * 后置条件:若 state !== lastSentState,构造并发送一条合法 StateMessage;否则无副作用。
+ */
+export function sendState(state, meta) {
+    if (!socket || socket.readyState !== WebSocket.OPEN)
+        return; // 未连接:no-op,不缓冲不报错
+    if (state === lastSentState)
+        return; // 节流:状态未变化不重发
+    lastSentState = state;
+    const msg = { type: 'state', clientId, state, meta, ts: Date.now() };
+    try {
+        socket.send(JSON.stringify(msg));
+    }
+    catch {
+        // 静默:发送失败不影响 agent 主循环
+    }
+}
+/** 当前是否已建立活跃连接。 */
+export function isConnected() {
+    return !!socket && socket.readyState === WebSocket.OPEN;
+}
+/** 主动断开连接(best-effort 发 bye 后 close code=1000)。 */
+export function disconnect() {
+    clearHeartbeat();
+    if (!socket)
+        return;
+    const ws = socket;
+    socket = null;
+    try {
+        ws.send(JSON.stringify({ type: 'bye', clientId, ts: Date.now() }));
+    }
+    catch {
+        // no-op
+    }
+    try {
+        ws.close(1000);
+    }
+    catch {
+        // no-op
+    }
+}
+/**
+ * 请求桌宠进程整体退出(方案C:CLI 侧退出入口;托盘图标是桌面侧的另一入口,见 packages/pet-app/src/main.ts)。
+ * 不要求本连接是活跃连接——任何已连接的 mocode 进程都可以关闭桌宠。
+ * 前置条件:当前进程已建立连接(未连接则先尝试探测端口直连,再发 shutdown)。
+ * 后置条件:发送 shutdown 消息后主动断开本地连接;不等待桌宠进程确认退出(best-effort,不阻塞 REPL)。
+ */
+export async function killPetProcess() {
+    const port = petPort();
+    let ws = socket;
+    let owned = false; // 是否为本函数临时建立的连接(需要负责关闭)
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+        const already = await probePort(port, PROBE_TIMEOUT_MS);
+        if (!already) {
+            return { ok: false, reason: '桌宠未运行' };
+        }
+        try {
+            ws = await openConnection(port);
+            owned = true;
+        }
+        catch (e) {
+            return { ok: false, reason: e instanceof Error ? e.message : '无法连接桌宠' };
+        }
+    }
+    try {
+        ws.send(JSON.stringify({ type: 'shutdown', clientId, ts: Date.now() }));
+    }
+    catch {
+        // 静默:发送失败不影响后续清理
+    }
+    try {
+        ws.close(1000);
+    }
+    catch {
+        // no-op
+    }
+    if (!owned && socket === ws) {
+        // 本连接原本就是活跃连接:同步清理本地状态(桌宠进程退出后 WS 也会被动关闭,这里主动先清)。
+        socket = null;
+        clearHeartbeat();
+    }
+    return { ok: true };
+}
+/**
+ * 请求当前可用皮肤列表(供 /pet skin 菜单展示)。
+ * 前置条件:当前进程已建立连接(未连接则先尝试探测端口直连;若桌宠未运行则失败)。
+ * 后置条件:resolve 桌宠回复的 SkinListMessage;超时(2s 内无回复)reject。
+ */
+export async function listSkins() {
+    const port = petPort();
+    let ws = socket;
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+        const already = await probePort(port, PROBE_TIMEOUT_MS);
+        if (!already)
+            throw new Error('桌宠未运行,请先 /pet 打开');
+        ws = await openConnection(port);
+        wireConnection(ws);
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            const idx = pendingSkinListResolvers.indexOf(onMsg);
+            if (idx >= 0)
+                pendingSkinListResolvers.splice(idx, 1);
+            reject(new Error('桌宠未响应皮肤列表请求'));
+        }, 2000);
+        const onMsg = (msg) => {
+            clearTimeout(timer);
+            resolve(msg);
+        };
+        pendingSkinListResolvers.push(onMsg);
+        try {
+            ws.send(JSON.stringify({ type: 'list_skins', ts: Date.now() }));
+        }
+        catch (e) {
+            clearTimeout(timer);
+            const idx = pendingSkinListResolvers.indexOf(onMsg);
+            if (idx >= 0)
+                pendingSkinListResolvers.splice(idx, 1);
+            reject(e instanceof Error ? e : new Error(String(e)));
+        }
+    });
+}
+/**
+ * 请求桌宠切换皮肤(选宠物)。
+ * 前置条件:当前进程已建立连接(未连接则静默 no-op,与 sendState 的降级策略一致)。
+ * 后置条件:已连接时发送 set_skin 消息;未连接时不抛错、无副作用。
+ */
+export function setSkin(skinId) {
+    if (!socket || socket.readyState !== WebSocket.OPEN)
+        return;
+    try {
+        socket.send(JSON.stringify({ type: 'set_skin', clientId, skinId, ts: Date.now() }));
+    }
+    catch {
+        // 静默:发送失败不影响 REPL 主流程
+    }
+}
+/**
+ * /pet 命令入口。
+ * 前置条件:REPL 主循环已初始化(不要求 agent 正在运行)。
+ * 后置条件:
+ *   - 若调用前无活跃连接:调用后 either 已建立连接(connected=true)
+ *     或已尝试 spawn+重试全部失败(connected=false,附错误原因)。
+ *   - 若调用前有活跃连接:调用后连接已关闭(connected=false)。
+ * 不抛异常(所有失败路径转为返回值,供 REPL 渲染提示行)。
+ */
+export async function togglePet() {
+    if (isConnected()) {
+        disconnect();
+        return { connected: false, reason: '已断开桌宠连接' };
+    }
+    const port = petPort();
+    try {
+        const already = await probePort(port, PROBE_TIMEOUT_MS);
+        if (already) {
+            const ws = await openConnection(port);
+            wireConnection(ws);
+            return { connected: true };
+        }
+        try {
+            await spawnPetProcess();
+        }
+        catch (e) {
+            return {
+                connected: false,
+                reason: e instanceof Error ? e.message : '无法启动桌宠进程',
+            };
+        }
+        const ws = await connectWithBackoff(port, RETRY_DELAYS_MS);
+        wireConnection(ws);
+        return { connected: true };
+    }
+    catch (e) {
+        return {
+            connected: false,
+            reason: e instanceof Error ? e.message : '桌宠启动超时,请手动检查',
+        };
+    }
+}

package/dist/pet/protocol.js

@@ -0,0 +1,112 @@
+// 桌宠 WS 协议:mocode 主包侧的类型定义与消息校验。
+// 与 packages/pet-app/src/protocol.ts 字段保持一致,但两处各自维护副本——
+// 主包不 import 子包源码(子包是 optionalDependency,可能未安装;设计上刻意解耦)。
+/** 全部合法状态值(供运行时校验,如 Set 成员判断)。 */
+export const PET_STATES = [
+    'idle',
+    'thinking',
+    'speaking',
+    'tool_call',
+    'done',
+    'aborted',
+    'error',
+    'waiting_human',
+];
+/** 判断值是否为合法 PetState(供消息校验,非法值丢弃不崩)。 */
+export function isValidPetState(v) {
+    return typeof v === 'string' && PET_STATES.includes(v);
+}
+/** 校验并解析一条原始 JSON 字符串为 ClientMessage;失败(JSON 非法/缺字段/type 未知)返回 null。
+ *  永不抛错——调用方(bridge/server)据此静默丢弃畸形消息,不断开连接。 */
+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 };
+        case 'shutdown':
+            if (typeof m.clientId !== 'string')
+                return null;
+            return { type: 'shutdown', clientId: m.clientId, ts: m.ts };
+        case 'set_skin':
+            if (typeof m.clientId !== 'string' || typeof m.skinId !== 'string')
+                return null;
+            return { type: 'set_skin', clientId: m.clientId, skinId: m.skinId, ts: m.ts };
+        case 'list_skins':
+            return { type: 'list_skins', 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 };
+        case 'skin_list': {
+            if (!Array.isArray(m.skins) || typeof m.currentSkinId !== 'string')
+                return null;
+            const skins = [];
+            for (const s of m.skins) {
+                if (!s || typeof s !== 'object')
+                    continue;
+                const ss = s;
+                if (typeof ss.id === 'string' && typeof ss.name === 'string') {
+                    skins.push({ id: ss.id, name: ss.name });
+                }
+            }
+            return { type: 'skin_list', skins, currentSkinId: m.currentSkinId, ts: m.ts };
+        }
+        default:
+            return null;
+    }
+}

package/dist/pet/state.js

@@ -0,0 +1,67 @@
+// AgentHooks → PetState 映射(mocode 主包侧)。
+// createPetHooks 产出的 hooks 只在 src/agent/index.ts(主 agent hooks 组装处)使用,
+// 与既有 TUI hooks 并列注入——两组 hooks 各自独立触发,互不干扰,不修改 core.ts 的任何行为。
+// 子 agent(src/agent/spawn.ts 的 spawnAgent)不引用本模块,故子 agent 永不广播桌宠状态。
+import * as bridge from './bridge.js';
+/**
+ * 纯函数:给定当前 hook 事件与其参数,推导下一个 PetState。
+ * 前置条件:event 是 AgentHooks 定义的方法名之一。
+ * 后置条件:返回值 ∈ PetState 枚举;对同一 (event, args) 输入,任意调用时刻返回值相同(确定性,可测)。
+ * 不依赖调用历史之外的隐藏状态——纯函数式转移表。
+ */
+export function deriveState(event, args) {
+    switch (event) {
+        case 'onStepStart':
+            return 'thinking';
+        case 'onText':
+            return 'speaking';
+        case 'onToolCall':
+        case 'onToolStart':
+            return 'tool_call';
+        case 'onToolResult':
+            if (args?.toolOutput && args.toolOutput.startsWith('错误'))
+                return 'error';
+            return 'tool_call';
+        case 'onDone':
+            return 'done';
+        case 'onAbort':
+            return 'aborted';
+        case 'onMaxSteps':
+            return 'error';
+        case 'onChatDone':
+        case 'onToolBatchEnd':
+            return 'thinking';
+        case 'onNoReply':
+            return 'idle';
+        default:
+            return 'idle';
+    }
+}
+/**
+ * 把 AgentHooks 事件流映射为 PetState 变化并调用 bridge.sendState。
+ * 前置条件:传入的 sender 已存在(可能尚未连接,sendState 内部自行处理未连接情形——no-op)。
+ * 后置条件:返回的 AgentHooks 对象的每个方法都是纯粹的"状态推导 + 转发",
+ *   不修改 core.ts 的任何行为、不影响现有 TUI hooks 的调用结果。
+ */
+export function createPetHooks(sender = bridge) {
+    return {
+        onStepStart: () => sender.sendState(deriveState('onStepStart')),
+        onText: () => sender.sendState(deriveState('onText')),
+        onToolCall: (name) => sender.sendState(deriveState('onToolCall', { toolName: name }), { toolName: name }),
+        onToolStart: (name) => sender.sendState(deriveState('onToolStart', { toolName: name }), { toolName: name }),
+        onToolResult: (tc, output) => {
+            const state = deriveState('onToolResult', { toolOutput: output });
+            if (state === 'error') {
+                sender.sendState(state, { errorMessage: output.slice(0, 200) });
+            }
+            else {
+                sender.sendState(state, { toolName: tc.name });
+            }
+        },
+        onToolBatchEnd: () => sender.sendState(deriveState('onToolBatchEnd')),
+        onDone: () => sender.sendState(deriveState('onDone')),
+        onAbort: () => sender.sendState(deriveState('onAbort')),
+        onMaxSteps: () => sender.sendState(deriveState('onMaxSteps')),
+        onNoReply: () => sender.sendState(deriveState('onNoReply')),
+    };
+}

package/dist/repl/index.js

@@ -5,6 +5,7 @@ import { config, PLAN_MODE_SUFFIX, updateModelConfig, isModelConfigured } from '
 import { updateConfigKey, writeConfigKeys, CONFIG_PATH } from '../config/file.js';
 import { runAgent } from '../agent/index.js';
 import { getAgentMode, setAgentMode, onModeChange } from '../agent/mode.js';
+import { togglePet, killPetProcess, listSkins, setSkin, sendState } from '../pet/bridge.js';
 import { setSandboxRoot } from '../sandbox/root.js';
 import { ui, setTheme, getTheme, listThemes, themeExists } from '../ui/theme.js';
 import { bannerString, displayWidth, padEndDisplay, summarizeToolCall, summarizeToolResult } from '../ui/render.js';
@@ -39,6 +40,9 @@ const SLASH_COMMANDS = [
     { name: '/model', desc: '配置大模型(baseURL/key/model/窗口)' },
     { name: '/plan', desc: '切到 plan 模式(只读探查+产出计划)' },
     { name: '/auto', desc: '切回 auto 模式(全工具执行)' },
+    { name: '/pet', desc: '开关桌宠(独立悬浮窗,展示 agent 状态动画)' },
+    { name: '/pet skin', desc: '选择桌宠皮肤(↑↓·Enter)' },
+    { name: '/pet quit', desc: '完全关闭桌宠进程(而非仅断开本连接)' },
 ];
 /** 主题名 → 一句描述(供 /theme 菜单 / 列表显示)。新增主题时在 src/ui/theme.ts THEMES 加键后于此补一句。 */
 const THEME_DESCRIPTIONS = {
@@ -164,6 +168,8 @@ function runningStateFor(cmd) {
             return { status: '切主题', placeholder: '选择主题…' };
         case '/model':
             return { status: '配模型', placeholder: '配置中…' };
+        case '/pet':
+            return { status: '桌宠', placeholder: '处理中…' };
         default:
             // 输入框留空(运行中可 typeahead 打字,dim 回显);运行状态由内联 spinner 承载(思考中/执行…),
             // 状态行只显走时——故常态 status 留空,不塞「处理」这种与内联重复的泛标签。
@@ -632,6 +638,57 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             }
             continue;
         }
+        if (line === '/pet quit') {
+            // /pet quit:完全关闭桌宠进程(区别于 /pet 的仅断开本连接)。方案C的 CLI 侧退出入口,
+            // 另一入口是桌宠托盘菜单"退出桌宠"(见 packages/pet-app/src/main.ts)。
+            const { ok, reason } = await killPetProcess();
+            layout.contentWrite(`${ui.dim}(${ok ? '已关闭桌宠进程' : reason ?? '关闭失败'})${ui.reset}\n`);
+            continue;
+        }
+        if (line === '/pet skin') {
+            // /pet skin:菜单选皮(↑↓ 选,Enter 切换,Esc 取消),仿 /theme 的交互。要求桌宠已在运行
+            // (未运行则先提示 /pet 打开;不在此处自动 spawn,避免选皮命令产生"顺带开桌宠"的意外副作用)。
+            let skinList;
+            try {
+                skinList = await listSkins();
+            }
+            catch (e) {
+                layout.contentWrite(`${ui.dim}(${e instanceof Error ? e.message : '获取皮肤列表失败'})${ui.reset}\n`);
+                continue;
+            }
+            const items = [
+                { id: 'default', title: '默认(mascot)', subtitle: skinList.currentSkinId === 'default' ? '当前' : '' },
+                ...skinList.skins.map((s) => ({
+                    id: s.id,
+                    title: s.name,
+                    subtitle: skinList.currentSkinId === s.id ? '当前' : '',
+                })),
+            ];
+            let pick;
+            try {
+                pick = await promptThemePicker(items);
+            }
+            catch {
+                continue; // Ctrl+C(SIGINT)→ 取消
+            }
+            if (pick === null)
+                continue; // Esc / Ctrl+D 取消
+            setSkin(pick.id);
+            layout.contentWrite(`${ui.dim}(已切换桌宠皮肤:${pick.title})${ui.reset}\n`);
+            continue;
+        }
+        if (line === '/pet') {
+            // /pet:开关桌宠。已连接→断开;未连接→探测端口(已有实例则直连)或 spawn 拉起 + 退避重试连接。
+            // togglePet 不抛异常,所有失败路径转为返回值——桌宠是可选增强,任何异常都不能影响 REPL 主流程。
+            const { connected, reason } = await togglePet();
+            if (connected) {
+                layout.contentWrite(`${ui.dim}(桌宠已连接)${ui.reset}\n`);
+            }
+            else {
+                layout.contentWrite(`${ui.dim}(${reason ?? '桌宠已断开'})${ui.reset}\n`);
+            }
+            continue;
+        }
         if (line === '/clear') {
             history.length = 1; // 保留 system 提示
             resetState(); // 同步清空回滚轮次/快照
@@ -983,12 +1040,16 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
         //  - 仍 plan:LLM 没自切(只产计划就 STOP)→ 弹审批面板(原行为)。
         //  - 已 auto:LLM 调了 switch_mode('auto') 在同轮自主执行了 → 跳过审批,不重复打扰。
         if (initialPlan && ok && getAgentMode() === 'plan') {
+            // 桌宠:计划审批面板弹出期间广播 waiting_human(红灯闪烁);面板不在 runAgent/hooks 体系内,
+            // 需在此单独广播——用户响应后由下一次 /pet 状态事件(或 idle 兜底)覆盖。
+            sendState('waiting_human');
             const res = await promptIntervention({
                 type: 'choice',
                 title: '计划已就绪',
                 detail: '切换到 auto 模式按上述计划执行?(plan 模式只读探查,执行需切 auto)',
                 options: ['切 auto 执行', '留 plan 细化'],
             });
+            sendState('idle');
             if (res.action === 'selected' && res.value === '切 auto 执行') {
                 // setAgentMode('auto') 由 runTurn 入口做(listener 重写 history[0] 回 auto);这里只切运行态 + 合成执行轮。
                 layout.enterRunningMode('执行', '按计划执行…');

package/dist/tools/builtins/ask-human.js

@@ -1,4 +1,5 @@
 import { promptIntervention } from '../../ui/intervention.js';
+import { sendState } from '../../pet/bridge.js';
 // ---------- ask_human ----------
 export const askHumanTool = {
     name: 'ask_human',
@@ -33,6 +34,9 @@ export const askHumanTool = {
             ? args.options.map((o) => String(o))
             : [];
         const context = args.context ? String(args.context) : undefined;
+        // 桌宠:面板弹出期间广播 waiting_human(红灯闪烁,提示需要人工介入);拿到响应后 sendState 会被
+        // 下一个 hook 事件(如 onToolDone→tool_call)覆盖,这里不用手动切回——与其它工具状态转移逻辑一致。
+        sendState('waiting_human');
         const result = await promptIntervention({
             type: options.length > 0 ? 'choice' : 'input',
             title: question,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 16 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {
@@ -24,10 +24,16 @@
     "cli-highlight": "^2.1.11",
     "dotenv": "^16.0.0",
     "fast-glob": "^3.0.0",
-    "openai": "^4.0.0"
+    "openai": "^4.0.0",
+    "ws": "8.21.0"
+  },
+  "optionalDependencies": {
+    "mocode-pet-app": "0.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/ws": "8.5.13",
+    "fast-check": "3.23.1",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
   },