mocode-pet-app 1.4.0 → 1.6.0

package/dist/mood-tracker-timing.test.js

@@ -0,0 +1,70 @@
+// createMoodTracker().evaluate() 的"立即求值"与"定时刷新文案"时序单测。
+// 覆盖 mood-tracker.ts 的四条分支(见该文件 evaluate 内部逻辑):
+//   1) mood 从 null → 非 null(“进入”新 mood):立即返回 {mood, quip}(不等 ticker)。
+//   2) mood 不变且非 null,未到 QUIP_REFRESH_MS(15000ms):返回 null(不重复推送)。
+//   3) mood 不变且非 null,达到 QUIP_REFRESH_MS(>=):返回新的 {mood(不变), quip(新文案)}。
+//   4) mood 从非 null → null(“退出”mood):立即返回 {mood: null}(不等 ticker);
+//      之后 mood 仍为 null 与上次一致 → 直接 return null(mood 为 null 时不进入文案刷新判断分支)。
+// pickQuip 内部用 Math.random() 挑文案,内容不可预测,只断言"是否有新结果"与 mood/quip 类型。
+// 运行:npx tsx packages/pet-app/src/mood-tracker-timing.test.ts
+import { createMoodTracker } from './mood-tracker.js';
+let passed = 0;
+const assert = (cond, msg) => {
+    if (!cond) {
+        console.error('✗ ' + msg);
+        process.exit(1);
+    }
+    passed++;
+    console.log('✓ ' + msg);
+};
+// ── 场景1:mood “进入”立即产生推送(不必等 ticker)───────────────────────
+// 注:flustered 判定是"滑动窗口"(见 mood.ts countInWindow,toolWindowMs 默认 10000ms),
+// 不是"状态持续不变"型判定(那类是 tired/urging/bored,用 currentStateSince,天然会随时间推移
+// 一直保持成立)。若只记 5 条 ts=0..4000 的 tool_call,窗口会在 now 推进过程中把早期事件滑出去
+// (例如 now=10001 时窗口 [1,10001] 只剩 4 条,已跌破阈值 5,mood 会提前变回 null,
+// 与场景2/3"mood 在 4000~19001 期间应保持 flustered 不变"的前提矛盾)。
+// 因此这里持续每隔 1000ms 记一条 tool_call 直到 ts=19000,以确保 flustered 的滑动窗口在
+// 整个测试所需的时间跨度内始终 ≥5 条,从而让 mood 保持不变、只测"文案刷新"这一件事。
+const tracker = createMoodTracker();
+for (let t = 0; t <= 19000; t += 1000) {
+    tracker.recordState('tool_call', t);
+}
+{
+    const r = tracker.evaluate(4000);
+    assert(r !== null && r.mood === 'flustered' && typeof r.quip === 'string', '场景1: 5 次 tool_call(10s 窗口内达阈值)→ evaluate 立即返回 {mood: "flustered", quip: string}');
+}
+// ── 场景2:mood 保持不变,未到 QUIP_REFRESH_MS(15000ms)→ 应返回 null ──────
+{
+    const r = tracker.evaluate(4001);
+    assert(r === null, '场景2a: mood 不变(仍 flustered),仅过 1ms(远小于 15000ms)→ evaluate 返回 null');
+}
+{
+    const r = tracker.evaluate(4000 + 15000 - 1); // 18999
+    assert(r === null, '场景2b: mood 不变,距上次推文案差 1ms 未到 15000ms 刷新阈值 → evaluate 返回 null');
+}
+// ── 场景3:mood 不变但达到 QUIP_REFRESH_MS(>=)→ 应重新推送新文案 ──────────
+{
+    const r = tracker.evaluate(4000 + 15000); // 19000,刚好达到刷新阈值(>=)
+    assert(r !== null && r.mood === 'flustered' && typeof r.quip === 'string', '场景3a: mood 不变,刚好达到 15000ms 刷新阈值(>=)→ evaluate 返回新的 {mood: "flustered", quip: string}');
+}
+{
+    const r = tracker.evaluate(19001);
+    assert(r === null, '场景3b: 刚刚才刷新过文案,立即再 evaluate(仅过 1ms)→ 返回 null');
+}
+// ── 场景4:mood 消失时也应立即推送一次 {mood: null},不等定时器 ────────────
+const tracker2 = createMoodTracker();
+tracker2.recordState('error', 0);
+tracker2.recordState('error', 100);
+{
+    const r = tracker2.evaluate(100);
+    assert(r !== null && r.mood === 'frustrated', '场景4a: 60s 窗口内 2 次 error(达阈值)→ evaluate 返回 {mood: "frustrated", ...}');
+}
+{
+    const r = tracker2.evaluate(100 + 60001); // 两次 error 事件均已滑出 60000ms 窗口
+    assert(r !== null && r.mood === null, '场景4b: error 事件滑出窗口,mood 从 frustrated 变为 null → evaluate 立即返回 {mood: null}(不等定时器)');
+}
+{
+    const r = tracker2.evaluate(100 + 60002);
+    assert(r === null, '场景4c: mood 仍为 null(与上次推送一致)→ evaluate 直接返回 null(mood 为 null 时不检查文案刷新)');
+}
+console.log(`\nOK: ${passed} passed, 0 failed`);

package/dist/mood-tracker.js

@@ -0,0 +1,41 @@
+// Mood 求值调度器:维护"当前活跃连接生命周期内的 state 事件缓冲" + "上次推送结果",
+// 提供 reset/recordState/evaluate 三个方法供 main.ts 在合适时机调用。
+// 不 import electron——只依赖 mood.ts(纯函数判定)与 quips.ts(文案选择),
+// 使这部分逻辑可以脱离真实 Electron 运行时被单元测试覆盖(main.ts 顶层的
+// electron import 与模块加载期 ipcMain.on/handle 副作用会导致该文件无法在测试里被直接 import)。
+import { deriveMood } from './mood.js';
+import { pickQuip } from './quips.js';
+/** 文案刷新间隔:mood 保持不变且非 null 时,每隔此时长重新挑一条新文案推送(design.md 默认假设)。 */
+export const QUIP_REFRESH_MS = 15_000;
+/**
+ * 创建一个独立的 MoodTracker 实例。用工厂函数而非模块级共享状态,
+ * 便于单测里每个用例创建互不干扰的实例。
+ */
+export function createMoodTracker() {
+    const events = [];
+    let lastPushedMood = null;
+    let lastQuipPushedAt = -Infinity;
+    function reset() {
+        events.length = 0;
+    }
+    function recordState(state, ts = Date.now()) {
+        events.push({ state, ts });
+    }
+    function evaluate(now = Date.now(), skinQuips) {
+        const mood = deriveMood(events, now);
+        if (mood !== lastPushedMood) {
+            lastPushedMood = mood;
+            if (mood === null) {
+                return { mood: null };
+            }
+            lastQuipPushedAt = now;
+            return { mood, quip: pickQuip(mood, skinQuips) };
+        }
+        if (mood !== null && now - lastQuipPushedAt >= QUIP_REFRESH_MS) {
+            lastQuipPushedAt = now;
+            return { mood, quip: pickQuip(mood, skinQuips) };
+        }
+        return null;
+    }
+    return { reset, recordState, evaluate };
+}

package/dist/mood-tracker.test.js

@@ -0,0 +1,56 @@
+// createMoodTracker() 的"连接切换/断开清空 events"单元测试。
+// events 是模块闻包私有变量,测试无法直接读取,只能通过行为观察验证 reset() 是否真的
+// 清空了内部事件缓冲——利用 deriveMood 里 tired/bored/urging/flustered 判定依赖
+// "事件缓冲"这一特性:先喂够触发某个 mood 的事件,evaluate 确认命中,再 reset() 后
+// 立即 evaluate(几乎同一时刻),若 mood 变回 null 则说明 events 已被真正清空
+// (deriveMood 对空数组必然返回 null)。
+//
+// 覆盖 tasks.md 4.1:
+//   场景1:新连接建立覆盖旧连接(main.ts onConnection 里的 reset() 时机)
+//   场景2:活跃连接断开(main.ts onDisconnect 里的 reset() 时机)
+//   场景3:reset 后重新 recordState 走出全新判定,不受 reset 前残留事件干扰
+//
+// 运行:npx tsx packages/pet-app/src/mood-tracker.test.ts
+import { createMoodTracker } from './mood-tracker.js';
+let passed = 0;
+const assert = (cond, msg) => {
+    if (!cond) {
+        console.error('✗ ' + msg);
+        process.exit(1);
+    }
+    passed++;
+    console.log('✓ ' + msg);
+};
+// ── 场景1:新连接建立覆盖旧连接 → reset() 清空 events ──────────────────────
+{
+    const tracker = createMoodTracker();
+    // 10s 窗口(默认 toolWindowMs=10000)内连续 5 次 tool_call(默认 toolCount=5)→ flustered。
+    tracker.recordState('tool_call', 1000);
+    tracker.recordState('tool_call', 2000);
+    tracker.recordState('tool_call', 3000);
+    tracker.recordState('tool_call', 4000);
+    tracker.recordState('tool_call', 5000);
+    const r1 = tracker.evaluate(6000);
+    assert(r1 !== null && r1.mood === 'flustered', '场景1步骤1:10s 内 5 次 tool_call → evaluate 判定为 flustered');
+    tracker.reset();
+    // 几乎同一时刻再 evaluate,若 events 真被清空,deriveMood 对空数组必返回 null,
+    // 且上次推送是 'flustered' → null 属于变化,应推送 {mood: null}。
+    const r2 = tracker.evaluate(6001);
+    assert(r2 !== null && r2.mood === null, '场景1步骤2:reset() 后立即 evaluate → mood 变为 null(证明 events 已清空)');
+    // ── 场景3(复用场景1已 reset 过的 tracker):reset 后重新 recordState 走出全新判定 ──
+    tracker.recordState('waiting_human', 10000);
+    const r3 = tracker.evaluate(10000 + 30000); // 默认 urgingMs=30000
+    assert(r3 !== null && r3.mood === 'urging', '场景3:reset 后重新 recordState(waiting_human)→ evaluate 判定为 urging(不受 reset 前残留 tool_call 事件干扰)');
+}
+// ── 场景2:活跃连接断开 → reset() 清空 events ────────────────────────────
+{
+    const tracker = createMoodTracker();
+    // idle 保持 300000ms(默认 boredMs=300000)→ bored。
+    tracker.recordState('idle', 0);
+    const r1 = tracker.evaluate(300_000);
+    assert(r1 !== null && r1.mood === 'bored', '场景2步骤1:idle 保持 boredMs(300000ms)→ evaluate 判定为 bored');
+    tracker.reset();
+    const r2 = tracker.evaluate(300_001);
+    assert(r2 !== null && r2.mood === null, '场景2步骤2:reset() 后立即 evaluate → mood 变为 null(证明 events 已清空,不残留 bored 判定)');
+}
+console.log(`\nOK: ${passed} passed, 0 failed`);

package/dist/mood.js

@@ -0,0 +1,102 @@
+// 桌宠 Mood(衍生情绪)引擎:纯函数,输入 state 事件历史 + 当前时间,输出当前应呈现的情绪。
+// 设计意图(见 design.md "Mood 引擎"):
+//   - 不进入 WS 协议——完全是 Server(pet-app)侧基于已收到 state 消息的本地再加工,
+//     不新增/修改任何 Client ↔ Server 消息类型,mocode 主包侧无需感知 Mood 概念。
+//   - 不改变 PetState 广播——mood 与 state 是叠加关系(渲染进程用独立的 mood-<kind> class),
+//     本文件不修改、不影响现有 state class 切换逻辑。
+//   - 无状态纯函数:不持有任何模块级可变状态,不做 I/O,同输入必同输出,便于单测与 PBT。
+/** 读取一个正数环境变量,非法/缺失时回退默认值(与 main.ts petPort() 的校验写法一致)。 */
+function envNumber(name, defaultValue) {
+    const v = process.env[name];
+    const n = v ? Number(v) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : defaultValue;
+}
+/** 默认阈值(均为假设,可通过环境变量覆盖,见 design.md 默认值表)。 */
+export const DEFAULT_MOOD_THRESHOLDS = {
+    tiredMs: envNumber('MOCODE_PET_MOOD_TIRED_MS', 60_000),
+    boredMs: envNumber('MOCODE_PET_MOOD_BORED_MS', 300_000),
+    urgingMs: envNumber('MOCODE_PET_MOOD_URGING_MS', 30_000),
+    errorWindowMs: envNumber('MOCODE_PET_MOOD_ERROR_WINDOW_MS', 60_000),
+    errorCount: envNumber('MOCODE_PET_MOOD_ERROR_COUNT', 2),
+    toolWindowMs: envNumber('MOCODE_PET_MOOD_TOOL_WINDOW_MS', 10_000),
+    toolCount: envNumber('MOCODE_PET_MOOD_TOOL_COUNT', 5),
+};
+/** 固定优先级(高→低),同一时刻只呈现其中最高优先级的一种(Requirement 1.7)。 */
+export const MOOD_PRIORITY = [
+    'frustrated',
+    'flustered',
+    'urging',
+    'tired',
+    'bored',
+];
+/**
+ * 辅助纯函数:找出"当前状态"及其"从何时开始保持不变"(用于 tired/bored/urging 的时长判定)。
+ * 后置条件:events 为空返回 null;否则返回 events 中最后一个事件的 state,
+ *   以及从末尾往前扫描、状态连续相同的最早一条事件的 ts。
+ */
+export function currentStateSince(events) {
+    if (events.length === 0)
+        return null;
+    const last = events[events.length - 1];
+    let since = last.ts;
+    for (let i = events.length - 1; i >= 0; i--) {
+        if (events[i].state !== last.state)
+            break;
+        since = events[i].ts;
+    }
+    return { state: last.state, since };
+}
+/**
+ * 纯函数:给定完整事件历史(按到达顺序,ts 非降序)与当前时间,推导当前应呈现的 MoodKind。
+ * 前置条件:events 按 ts 非降序排列。
+ * 后置条件:
+ *   - 返回值 ∈ MoodKind ∪ {null}。
+ *   - 若返回非 null 的 kind K,则 MOOD_PRIORITY 中排在 K 之前的所有 kind 的判定条件均不成立
+ *     (优先级排他性,Property 1)。
+ * 不依赖调用历史之外的隐藏状态,任意次调用同输入同输出(确定性,Property 2)。
+ */
+export function deriveMood(events, now, thresholds = DEFAULT_MOOD_THRESHOLDS) {
+    for (const kind of MOOD_PRIORITY) {
+        if (matchesMood(kind, events, now, thresholds))
+            return kind;
+    }
+    return null;
+}
+/**
+ * 按单个 MoodKind 的判定条件检查是否命中(见 design.md 判定逻辑表)。
+ * 导出供测试(PBT)交叉验证 deriveMood 的优先级排他性,不改变 deriveMood 既有公开行为。
+ */
+export function matchesMood(kind, events, now, thresholds) {
+    switch (kind) {
+        case 'frustrated':
+            return countInWindow(events, now, thresholds.errorWindowMs, 'error') >= thresholds.errorCount;
+        case 'flustered':
+            return countInWindow(events, now, thresholds.toolWindowMs, 'tool_call') >= thresholds.toolCount;
+        case 'urging': {
+            const cur = currentStateSince(events);
+            return cur !== null && cur.state === 'waiting_human' && now - cur.since >= thresholds.urgingMs;
+        }
+        case 'tired': {
+            const cur = currentStateSince(events);
+            return (cur !== null &&
+                (cur.state === 'thinking' || cur.state === 'tool_call') &&
+                now - cur.since >= thresholds.tiredMs);
+        }
+        case 'bored': {
+            const cur = currentStateSince(events);
+            return cur !== null && cur.state === 'idle' && now - cur.since >= thresholds.boredMs;
+        }
+        default:
+            return false;
+    }
+}
+/** 统计 events 中 ts ∈ [now - windowMs, now] 且 state 匹配的条数。 */
+function countInWindow(events, now, windowMs, state) {
+    const from = now - windowMs;
+    let count = 0;
+    for (const e of events) {
+        if (e.state === state && e.ts >= from && e.ts <= now)
+            count++;
+    }
+    return count;
+}

package/dist/mood.pbt.js

@@ -0,0 +1,52 @@
+// PBT(属性测试):deriveMood 的"Mood 优先级排他性"(spec: desktop-pet 任务 2.1,Property 1)。
+//   性质:若 deriveMood(events, now) 返回非 null 的 kind K,则 MOOD_PRIORITY 中排在 K 之前的
+//   所有 kind,用 matchesMood 单独判定都必须为 false——否则 deriveMood 就该返回那个更高优先级的
+//   kind 而不是 K(deriveMood 内部本就是按 MOOD_PRIORITY 顺序 first-match,这里做交叉验证)。
+// 用 fast-check 生成任意 MoodEvent[](按 ts 排序)与 now,跑 500 次样本。
+// 运行:npx tsx packages/pet-app/src/mood.pbt.ts
+import fc from 'fast-check';
+import { DEFAULT_MOOD_THRESHOLDS, MOOD_PRIORITY, deriveMood, matchesMood } from './mood.js';
+let passed = 0;
+const assert = (cond, msg) => {
+    if (!cond) {
+        console.error('✗ ' + msg);
+        process.exit(1);
+    }
+    passed++;
+};
+const petStateArb = fc.constantFrom('idle', 'thinking', 'speaking', 'tool_call', 'done', 'aborted', 'error', 'waiting_human');
+const moodEventArb = fc.record({
+    state: petStateArb,
+    ts: fc.nat({ max: 1_000_000 }),
+});
+// 生成 events(未排序)+ 一个 offset,now = 最后一条事件的 ts(排序后)+ offset。
+// offset 范围覆盖负值(now 落在历史事件之前/之间)到较大正值(触发 tired/bored/urging 的时长判定),
+// 以增加命中各优先级分支的概率。
+const sampleArb = fc
+    .tuple(fc.array(moodEventArb, { maxLength: 30 }), fc.integer({ min: -1000, max: 500_000 }))
+    .map(([rawEvents, offset]) => {
+    const events = [...rawEvents].sort((a, b) => a.ts - b.ts);
+    const now = events.length > 0 ? events[events.length - 1].ts + offset : Math.max(0, offset);
+    return { events, now };
+});
+(async () => {
+    fc.assert(fc.property(sampleArb, ({ events, now }) => {
+        const result = deriveMood(events, now, DEFAULT_MOOD_THRESHOLDS);
+        if (result === null)
+            return true; // 全不命中,排他性天然满足
+        const idx = MOOD_PRIORITY.indexOf(result);
+        for (let i = 0; i < idx; i++) {
+            const higherKind = MOOD_PRIORITY[i];
+            if (matchesMood(higherKind, events, now, DEFAULT_MOOD_THRESHOLDS)) {
+                return false; // 排在 result 之前的 kind 也命中了 → 违反排他性
+            }
+        }
+        return true;
+    }), { numRuns: 500 });
+    assert(true, 'Property 1 (Mood 优先级排他性):deriveMood 返回的 kind 之前无更高优先级命中(500 次样本)');
+    console.log(`\nOK: ${passed} passed, 0 failed`);
+    process.exit(0);
+})().catch((err) => {
+    console.error('✗ PBT 执行异常:', err);
+    process.exit(1);
+});

package/dist/quips.js

@@ -0,0 +1,45 @@
+// 通用文案池:各 mood 对应的中文吐槽短句,以及随机选取逻辑。
+// 皮肤可提供自定义文案(skinQuips)覆盖某个 mood 的候选池;未覆盖或为空时回退到通用文案池。
+/** 每种 mood 的通用吐槽短句候选池,语气轻松幽默(赛博终端风机器人设定)。 */
+export const UNIVERSAL_QUIPS = {
+    frustrated: [
+        '又报错了…要不要歇一下?',
+        '这个 bug 有点顽固啊',
+        '报错第二次了,压力有点大',
+        '怎么又翻车了,深呼吸一下',
+    ],
+    flustered: [
+        '感觉在同时干好多件事…',
+        '工具切换得好快!',
+        '有点跟不上节奏了',
+        '脑子有点转不过来了',
+    ],
+    urging: [
+        '还在等你哦~',
+        '我等得有点无聊了',
+        '需要你看一下呢',
+        '别忘了我还在等呢',
+    ],
+    tired: [
+        '这个任务有点久,好累…',
+        '还在跑,坐等一下',
+        '累了累了,继续肝',
+        '电量有点低了,撑住',
+    ],
+    bored: [
+        '闲着没事,打个哈欠',
+        '东张西望中…',
+        '有什么新任务吗',
+        '好安静啊,有点无聊',
+    ],
+};
+/**
+ * 根据 mood 选一条吐槽文案。
+ * 若 skinQuips 里该 mood 有非空候选列表,优先从中随机选;否则回退到 pool(默认通用文案池)。
+ * 纯函数,唯一的非确定性来源是 Math.random()。
+ */
+export function pickQuip(mood, skinQuips, pool = UNIVERSAL_QUIPS) {
+    const skinList = skinQuips?.[mood];
+    const list = skinList && skinList.length > 0 ? skinList : pool[mood];
+    return list[Math.floor(Math.random() * list.length)];
+}

package/dist/quips.test.js

@@ -0,0 +1,57 @@
+// 单测:pickQuip 的回退逻辑(皮肤池覆盖 / 未覆盖 / 空数组 / 未传皮肤池)。
+// 覆盖 5 种 MoodKind,并验证多次随机调用不会跑出候选池范围。
+// 运行:npx tsx packages/pet-app/src/quips.test.ts
+import { pickQuip, UNIVERSAL_QUIPS } from './quips.js';
+let passed = 0;
+const assert = (cond, msg) => {
+    if (!cond) {
+        console.error('✗ ' + msg);
+        process.exit(1);
+    }
+    passed++;
+    console.log('✓ ' + msg);
+};
+const ALL_MOODS = ['frustrated', 'flustered', 'urging', 'tired', 'bored'];
+// ── 1) 皮肤池覆盖该 mood(单条)→ 必然返回皮肤池里的那条 ──────────────────
+{
+    const skinQuips = { tired: ['猫猫要趴一下…'] };
+    const r = pickQuip('tired', skinQuips);
+    assert(r === '猫猫要趴一下…', `皮肤池覆盖 tired(单条)→ 返回皮肤池文案(实际:"${r}")`);
+}
+// ── 1b) 皮肤池覆盖该 mood(多条)→ 返回值必在皮肤池数组内 ─────────────────
+{
+    const skinList = ['猫猫要趴一下…', '电量告急,先眯一会'];
+    const skinQuips = { tired: skinList };
+    for (let i = 0; i < 20; i++) {
+        const r = pickQuip('tired', skinQuips);
+        assert(skinList.includes(r), `皮肤池覆盖 tired(多条)→ 返回值 ∈ 皮肤池(实际:"${r}")`);
+    }
+}
+// ── 2) 皮肤池未覆盖该 mood(skinQuips 里没有 tired 这个 key)→ 回退通用池 ──
+{
+    const skinQuips = { bored: ['无所事事'] };
+    const r = pickQuip('tired', skinQuips);
+    assert(UNIVERSAL_QUIPS.tired.includes(r), `皮肤池未覆盖 tired → 回退 UNIVERSAL_QUIPS.tired(实际:"${r}")`);
+}
+// ── 3) 皮肤池对应 mood 是空数组 → 视为未覆盖,回退通用池 ─────────────────
+{
+    const skinQuips = { tired: [] };
+    const r = pickQuip('tired', skinQuips);
+    assert(UNIVERSAL_QUIPS.tired.includes(r), `皮肤池 tired 为空数组 → 回退 UNIVERSAL_QUIPS.tired(实际:"${r}")`);
+}
+// ── 4) 未传皮肤池 → 回退通用池 ──────────────────────────────────────────
+{
+    const r = pickQuip('tired');
+    assert(UNIVERSAL_QUIPS.tired.includes(r), `未传皮肤池(tired)→ 回退 UNIVERSAL_QUIPS.tired(实际:"${r}")`);
+}
+// ── 5) 5 种 MoodKind 各跑一次"未传皮肤池"场景 → 都能返回该 mood 池里的某一条 ──
+for (const mood of ALL_MOODS) {
+    const r = pickQuip(mood);
+    assert(typeof r === 'string' && UNIVERSAL_QUIPS[mood].includes(r), `未传皮肤池(${mood})→ 返回值 ∈ UNIVERSAL_QUIPS.${mood}(实际:"${r}")`);
+}
+// ── 6) 多次调用同一场景(20 次 pickQuip('tired'))→ 每次都不跑出通用池范围 ──
+for (let i = 0; i < 20; i++) {
+    const r = pickQuip('tired');
+    assert(UNIVERSAL_QUIPS.tired.includes(r), `第 ${i + 1} 次调用 pickQuip('tired')→ 返回值 ∈ UNIVERSAL_QUIPS.tired(实际:"${r}")`);
+}
+console.log(`\nOK: ${passed} passed, 0 failed`);

package/dist/renderer/dom-mood.js

@@ -0,0 +1,53 @@
+// Mood class 切换 / 气泡淡出 / 皮肤动作覆盖 <link> 回退——纯逻辑部分,从 renderer.ts 抽出。
+// 不 import 'electron',不引用真实的全局 window/document,只操作调用方传入的、符合
+// "最小 DOM 元素形状"接口(ElementLike/LinkElementLike)的对象,使这部分逻辑可以脱离真实浏览器
+// 环境(本项目未安装 jsdom)被单元测试覆盖——与任务 4 里 main.ts → mood-tracker.ts 的抽取方式同构。
+/** 气泡文案自动淡出隐藏前的展示时长(design.md "情绪 → 演出的驱动"默认假设)。 */
+export const QUIP_VISIBLE_MS = 3000;
+export const ALL_MOOD_CLASSES = [
+    'mood-tired',
+    'mood-bored',
+    'mood-urging',
+    'mood-frustrated',
+    'mood-flustered',
+];
+/** MoodKind → CSS class 映射表(与 state class 独立叠加,不互相替换,见 renderer.ts STATE_CLASS 同一写法风格)。 */
+export const MOOD_CLASS = {
+    frustrated: 'mood-frustrated',
+    flustered: 'mood-flustered',
+    urging: 'mood-urging',
+    tired: 'mood-tired',
+    bored: 'mood-bored',
+};
+/** 应用 mood class:mood 为 null 时移除全部 mood class(五种互斥,批量移除后按需添加一个)。 */
+export function applyMood(container, mood) {
+    container.classList.remove(...ALL_MOOD_CLASSES);
+    if (mood !== null) {
+        container.classList.add(MOOD_CLASS[mood]);
+    }
+}
+/** 设置/清空皮肤个性化动作覆盖 <link> 的 href:有 motionFile 则指向该皮肤的个性化动作覆盖 CSS,
+ *  否则清空(浏览器 <link> 加载失败/空 href 本身不抛异常,天然静默回退到通用样式,见 design.md)。 */
+export function applySkinMotion(link, motionFile) {
+    link.href = motionFile ? `../assets/pets/${motionFile}` : '';
+}
+const defaultSetTimeout = (callback, ms) => setTimeout(callback, ms);
+const defaultClearTimeout = (handle) => clearTimeout(handle);
+/**
+ * 创建一个独立的气泡淡出控制器。用工厂函数注入 setTimeout/clearTimeout 而非依赖模块级
+ * 共享的定时器句柄变量,便于测试里传入模拟定时器(不必真实等待 QUIP_VISIBLE_MS)。
+ */
+export function createBubbleController(setTimeoutFn = defaultSetTimeout, clearTimeoutFn = defaultClearTimeout) {
+    let hideTimer = null;
+    function showQuip(bubbleEl, quip, visibleMs) {
+        bubbleEl.textContent = quip;
+        bubbleEl.classList.add('pet-bubble-visible');
+        if (hideTimer !== null) {
+            clearTimeoutFn(hideTimer);
+        }
+        hideTimer = setTimeoutFn(() => {
+            bubbleEl.classList.remove('pet-bubble-visible');
+        }, visibleMs);
+    }
+    return { showQuip };
+}

package/dist/renderer/dom-mood.test.js

@@ -0,0 +1,105 @@
+// dom-mood.ts 的单元测试(tasks.md 6.1):mood class 切换、气泡淡出、皮肤动作覆盖 <link> 回退。
+// 不依赖 jsdom——用手写的最小 stub 对象(ElementLike/LinkElementLike 形状)覆盖场景,
+// 气泡淡出场景额外用手写假定时器替代真实 setTimeout/clearTimeout,避免测试真实等待 3000ms。
+//
+// 运行:npx tsx packages/pet-app/src/renderer/dom-mood.test.ts
+import { applyMood, applySkinMotion, createBubbleController, ALL_MOOD_CLASSES, } from './dom-mood.js';
+let passed = 0;
+const assert = (cond, msg) => {
+    if (!cond) {
+        console.error('✗ ' + msg);
+        process.exit(1);
+    }
+    passed++;
+    console.log('✓ ' + msg);
+};
+/** 基于 Set<string> 实现的最小 classList stub,不依赖 jsdom/真实 DOMTokenList。 */
+function createStubElement() {
+    const classes = new Set();
+    return {
+        classList: {
+            add(...tokens) {
+                for (const t of tokens)
+                    classes.add(t);
+            },
+            remove(...tokens) {
+                for (const t of tokens)
+                    classes.delete(t);
+            },
+            contains(token) {
+                return classes.has(token);
+            },
+        },
+        textContent: null,
+    };
+}
+// ── 场景A:mood class 切换,始终只有一个 ──────────────────────────────────
+{
+    const el = createStubElement();
+    const assertOnlyMoodClass = (activeClass, label) => {
+        for (const cls of ALL_MOOD_CLASSES) {
+            const shouldContain = cls === activeClass;
+            assert(el.classList.contains(cls) === shouldContain, `${label}:class ${cls} ${shouldContain ? '应存在' : '应不存在'}`);
+        }
+    };
+    applyMood(el, 'tired');
+    assertOnlyMoodClass('mood-tired', "applyMood(el, 'tired') 后");
+    applyMood(el, 'frustrated');
+    assertOnlyMoodClass('mood-frustrated', "applyMood(el, 'frustrated') 后(上一个 mood class 应已被移除)");
+    applyMood(el, 'bored');
+    assertOnlyMoodClass('mood-bored', "applyMood(el, 'bored') 后");
+    applyMood(el, null);
+    assertOnlyMoodClass(null, 'applyMood(el, null) 后(全部 mood class 应被移除)');
+}
+// ── 场景B:气泡文案自动淡出,不影响 mood class ────────────────────────────
+{
+    let nextId = 1;
+    let queue = [];
+    let clearCallCount = 0;
+    const fakeSetTimeout = (fn, ms) => {
+        const id = nextId++;
+        queue.push({ id, fn, ms });
+        return id;
+    };
+    const fakeClearTimeout = (handle) => {
+        clearCallCount++;
+        queue = queue.filter((t) => t.id !== handle);
+    };
+    const flush = () => {
+        const toRun = queue;
+        queue = [];
+        for (const t of toRun)
+            t.fn();
+    };
+    const bubbleController = createBubbleController(fakeSetTimeout, fakeClearTimeout);
+    const bubbleEl = createStubElement();
+    const stageEl = createStubElement();
+    applyMood(stageEl, 'tired');
+    bubbleController.showQuip(bubbleEl, '测试文案', 3000);
+    assert(bubbleEl.textContent === '测试文案', 'showQuip 后 bubbleEl.textContent 应为传入的文案');
+    assert(bubbleEl.classList.contains('pet-bubble-visible') === true, 'showQuip 后 bubbleEl 应带有 pet-bubble-visible class(淡入)');
+    flush();
+    assert(bubbleEl.classList.contains('pet-bubble-visible') === false, 'flush 假定时器后 bubbleEl 应移除 pet-bubble-visible class(淡出)');
+    assert(bubbleEl.textContent === '测试文案', 'flush 假定时器后 bubbleEl.textContent 仍保留原文案(淡出不清空文本)');
+    assert(stageEl.classList.contains('mood-tired') === true, '气泡淡出不影响舞台元素的 mood class(两者互不干扰)');
+    // 额外验证:连续调用两次 showQuip,第一次的定时器应被 clearTimeoutFn 正确清除。
+    bubbleController.showQuip(bubbleEl, '第一条', 3000);
+    const clearCountBefore = clearCallCount;
+    const queueLenAfterFirst = queue.length;
+    bubbleController.showQuip(bubbleEl, '第二条', 3000);
+    assert(clearCallCount === clearCountBefore + 1, '第二次 showQuip 调用应触发一次 clearTimeoutFn(清除第一次的定时器)');
+    assert(queue.length === queueLenAfterFirst, '第二次 showQuip 后队列里第一次的定时器已被移除,队列长度不因残留旧定时器而增长');
+    assert(bubbleEl.textContent === '第二条', '第二次 showQuip 后文案应更新为最新一次的内容');
+}
+// ── 场景C:皮肤动作覆盖 link 回退 ─────────────────────────────────────────
+{
+    const link = { href: '' };
+    applySkinMotion(link, '01-robo-cat.motion.css');
+    assert(link.href === '../assets/pets/01-robo-cat.motion.css', "applySkinMotion(link, '01-robo-cat.motion.css') 应设置对应路径的 href");
+    applySkinMotion(link, undefined);
+    assert(link.href === '', 'applySkinMotion(link, undefined) 应清空 href(回退通用样式)');
+    applySkinMotion(link, '02-robo-dog.motion.css');
+    applySkinMotion(link);
+    assert(link.href === '', '再次设置后不传第二参数调用 applySkinMotion(link),最终 href 应被清空');
+}
+console.log(`\nOK: ${passed} passed, 0 failed`);

package/dist/renderer/index.html

@@ -5,11 +5,13 @@
   <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" />
+  <link id="pet-skin-motion" rel="stylesheet" href="" />
 </head>
 <body>
   <div id="pet-stage" class="pet-idle">
     <div id="pet-container"></div>
     <div id="signal-light-container"></div>
+    <div id="pet-bubble"></div>
   </div>
   <script src="renderer.js" type="module"></script>
 </body>

package/dist/renderer/preload.js

@@ -9,14 +9,21 @@ electron_1.contextBridge.exposeInMainWorld('petBridge', {
             callback(payload.state, payload.meta);
         });
     },
-    /** 主进程推来的皮肤切换通知(运行期切换:托盘菜单选择 或 CLI set_skin 消息触发)。 */
+    /** 主进程推来的皮肤切换通知(运行期切换:托盘菜单选择 或 CLI set_skin 消息触发)。
+     *  motionFile 有值时指向该皮肤的个性化动作覆盖 CSS(见 renderer.ts applySkinMotion),缺失表示回退通用样式。 */
     onSkin: (callback) => {
         electron_1.ipcRenderer.on('pet:skin', (_event, payload) => {
-            callback(payload.assetPath);
+            callback(payload);
         });
     },
     /** 启动时主动拉取当前皮肤(避免 did-finish-load 推送与监听器注册之间的时序竞争)。 */
     getInitialSkin: () => electron_1.ipcRenderer.invoke('pet:get-skin'),
+    /** 主进程推来的 mood 求值结果(见 main.ts pushMoodEvaluation),mood 为 null 表示当前无需展示情绪演出。 */
+    onMood: (callback) => {
+        electron_1.ipcRenderer.on('pet:mood', (_event, payload) => {
+            callback(payload.mood, payload.quip);
+        });
+    },
     /** 转发鼠标穿透状态请求(拖拽放置功能:悬停/拖拽时取消穿透,离开后恢复穿透)。 */
     setIgnoreMouseEvents: (ignore) => {
         electron_1.ipcRenderer.send('pet:set-ignore-mouse-events', ignore);