@deepseek-harness-tui/dsh-tui 0.11.2 → 0.13.0

package/lib/types/components/sidePanel/companion/SplashMascot.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 启动页吉祥物（LogoV2 艺术槽，2026-10 复用轮）。
+ *
+ * 吉祥物跟随 companion.skin：deepy → 字母格动画；whaleGirl → 鲸娘动画
+ * （经 WhaleGirlSkin 内部的图像协议自适应：kitty/sixel 走 img/ 帧管线，
+ * 无协议回退字母格帧包——首帧字母格同步可画，图像异步解码完成后替换，
+ * 绝不让启动帧等 IO）。whale 皮肤不进本组件（LogoV2 维持原分层鲸路径）。
+ *
+ * 动画/互动语义与侧栏宠物同源（零复制），但按 2026-10 用户拍板收窄：
+ * 启动页是瞬时门面——**不做空闲轮换**，稳态恒播单一 idle 动画（循环）；
+ * 点击 = poke（左/右半判定，播 poke-left/right 头段；鲸娘在 poke 后接一段
+ * smile-hearts 爱心——同面板「亲昵互动」语义，deepy 帧包无爱心键故只 poke）；
+ * 连点 = 900ms 内 ≥3 次触发 tickle（复用 mood.ts 的 TICKLE_WINDOW_MS/
+ * TICKLE_MIN_CLICKS 判定）；播完自然回稳态 idle。不做拖拽。
+ * active=false（第一个任务后冻结，照鲸鱼的 whaleFrozen 契约）或卸载后零
+ * 时钟：定格 idle 帧 0，interval 清空。
+ *
+ * 欢迎语/求星标语不在本组件——按 2026-10 用户拍板保持原「艺术下方居中」
+ * 渲染路径（LogoV2 底部块，welcomePad 缩进）。
+ */
+import React from 'react';
+import { Box } from '../../../ui.js';
+import { getCompanionSkin, subscribeCompanionSkin } from '../../../tuiDisplayPrefs.js';
+import { TICKLE_MIN_CLICKS, TICKLE_WINDOW_MS } from './mood.js';
+import { DeepySkin, WhaleGirlSkin } from './skins.js';
+import { initialCompanionPoseState, nextCompanionPoseStep } from './pose.js';
+/** 点击反应档时长：poke 帧表一轮 2100ms，取头段（同 CompanionPanel 的口径）。 */
+const SPLASH_POKE_MS = 1400;
+/** poke 后鲸娘的爱心档时长（smile-hearts 一轮 ~1.9s，取一轮多的头段）。 */
+const SPLASH_HEART_MS = 2400;
+/** 吉祥物动画 tick（同 CompanionPanel 的 TICK_MS）。 */
+const SPLASH_TICK_MS = 160;
+/** 吉祥物字母格宽（与侧栏宠物同包同宽；艺术槽盒 40 列居中容纳）。 */
+const SPLASH_MASCOT_COLUMNS = 42;
+/** 读 companion.skin（LogoV2 的测试缝 prop 优先）；非吉祥物皮肤返回
+ *  undefined（LogoV2 走原鲸鱼/女仆娘路径，零改动）。 */
+export function useSplashMascotSkin(pinned) {
+    const setting = React.useSyncExternalStore(subscribeCompanionSkin, getCompanionSkin);
+    const id = pinned ?? setting;
+    return id === 'deepy' || id === 'whaleGirl' ? id : undefined;
+}
+/** 启动页吉祥物本体：按 skin 渲染动画，点击交互（poke/连点）在内层盒。 */
+export function SplashMascot({ skin, active }) {
+    const [, setBump] = React.useState(0);
+    // 稳态 idle 从挂载起循环；冻结时 now 钉在挂载值 → elapsed 恒 0 → 帧 0。
+    const mountedAtRef = React.useRef(Date.now());
+    const clicksRef = React.useRef([]);
+    // 覆盖档：poke / tickle / poke 后的爱心（鲸娘），到期在渲染期自回收并
+    // 链到下一档（poke → smile-hearts），全部播完自然回稳态 idle。
+    const overrideRef = React.useRef(undefined);
+    const heartAfterOverrideRef = React.useRef(false);
+    // 姿态是常量：吉祥物的动画全走 animationSemantic（deepy 规范键），
+    // 皮肤在 semantic 有效时不读 mood/heart 层——只需一个合法 pose 形状。
+    const [pose] = React.useState(() => nextCompanionPoseStep(initialCompanionPoseState(Date.now()), { mood: 'idle', heart: false }, Date.now()).pose);
+    React.useEffect(() => {
+        if (!active)
+            return;
+        const id = setInterval(() => { setBump(previous => previous + 1); }, SPLASH_TICK_MS);
+        id.unref?.();
+        return () => { clearInterval(id); };
+    }, [active]);
+    const now = active ? Date.now() : mountedAtRef.current;
+    if (overrideRef.current !== undefined && overrideRef.current.until <= now) {
+        const heartNext = heartAfterOverrideRef.current;
+        overrideRef.current = undefined;
+        heartAfterOverrideRef.current = false;
+        if (heartNext) {
+            overrideRef.current = { semantic: 'smile-hearts', since: now, until: now + SPLASH_HEART_MS };
+        }
+    }
+    const override = overrideRef.current;
+    const animationSemantic = override?.semantic ?? 'idle';
+    const animSince = override?.since ?? mountedAtRef.current;
+    const input = {
+        pose,
+        moodSince: animSince,
+        now,
+        width: SPLASH_MASCOT_COLUMNS,
+        animationSemantic,
+    };
+    return (_jsx(Box, { flexDirection: "column", alignItems: "center", flexShrink: 0, children: _jsx(Box, { onClick: (event) => {
+                event.stopImmediatePropagation();
+                if (!active)
+                    return;
+                const at = Date.now();
+                // 连点判定与面板同源（TICKLE_WINDOW_MS/TICKLE_MIN_CLICKS）：
+                // 窗口内 ≥3 次 → tickle；否则按左/右半 poke（鲸娘再链一段爱心）。
+                clicksRef.current = [...clicksRef.current.filter(ts => ts > at - TICKLE_WINDOW_MS), at];
+                const rapid = clicksRef.current.length >= TICKLE_MIN_CLICKS;
+                if (rapid)
+                    clicksRef.current = [];
+                overrideRef.current = rapid
+                    ? { semantic: 'tickle', since: at, until: at + TICKLE_WINDOW_MS }
+                    : {
+                        semantic: event.localCol < SPLASH_MASCOT_COLUMNS / 2 ? 'poke-left' : 'poke-right',
+                        since: at,
+                        until: at + SPLASH_POKE_MS,
+                    };
+                heartAfterOverrideRef.current = !rapid && skin === 'whaleGirl';
+                setBump(previous => previous + 1);
+            }, children: skin === 'deepy' ? DeepySkin.render(input) : WhaleGirlSkin.render(input) }) }));
+}

package/lib/types/components/sidePanel/companion/deepy.d.ts

@@ -0,0 +1,75 @@
+import type { CompanionMood } from './mood.js';
+type Rgb = readonly [number, number, number];
+export interface DeepyFrame {
+    readonly dur: number;
+    readonly rows: readonly string[];
+}
+export interface DeepyAnimation {
+    readonly key: string;
+    readonly title: string;
+    readonly frames: readonly DeepyFrame[];
+    /** 全部帧的 dur 总和（循环周期）。 */
+    readonly totalMs: number;
+}
+export interface DeepyKit {
+    /** 素材包身份（'deepy' / 'whaleGirl'）：预渲染缓存按它分命名空间。 */
+    readonly id: string;
+    readonly columns: number;
+    readonly rows: number;
+    readonly palette: Record<string, Rgb | undefined>;
+    readonly byKey: Readonly<Record<string, DeepyAnimation>>;
+}
+export declare const DEEPY_CELLS: Readonly<{
+    columns: 42;
+    rows: 15;
+}>;
+/** kit 加载缓存：null = 尚未尝试；undefined = 已尝试但素材缺失/校验
+ *  失败（皮肤回退）；DeepyKit = 已加载。测试可直接改写以模拟缺失。 */
+export interface SpriteKitCache {
+    kit: DeepyKit | undefined | null;
+}
+export declare const deepyKitCache: SpriteKitCache;
+export declare const whaleGirlKitCache: SpriteKitCache;
+/** 按候选相对路径（相对本模块）依次尝试「读取 + parseKit 校验」，第一个
+ *  通过校验的胜出并记入 cache；全部失败 → undefined。抽自 loadDeepyKit，
+ *  deepy 与鲸娘共用。 */
+export declare function loadSpriteKit(candidates: readonly string[], cache: SpriteKitCache, id: string): DeepyKit | undefined;
+/** 加载并缓存 deepy 素材包；素材缺失或校验失败返回 undefined（皮肤回退）。 */
+export declare function loadDeepyKit(): DeepyKit | undefined;
+/** 鲸娘素材包（用户提供，assets/whaleGirl/frames.json：22 动画，与 deepy
+ *  同 schema 的 42×30 字母格，构建见 scripts/build-whale-girl-kit.mjs）。 */
+export declare function loadWhaleGirlKit(): DeepyKit | undefined;
+/** mood → deepy 动画（素材包 README 的状态对应表；显示语义经
+ *  CompanionPanel 的平滑层后映射到这里）。 */
+export declare const DEEPY_MOOD_ANIMATION: Readonly<Record<CompanionMood, string>>;
+/** 并行上下文 → 动画（官方表：conducting=2+ 子代理、building=3+ 会话、
+ *  music=1 子代理或 2 会话、compacting=上下文压缩）。 */
+export declare const DEEPY_CONTEXT_ANIMATION: Readonly<Record<string, string>>;
+/** 互动/悬停/闪现 → 动画（官方表 reaction 档）：look=idle-look（东张西望，
+ *  追踪面板内指针），notice=idle-spout（指针碰到宠物本体，开心喷水），
+ *  waking=被吵醒（官方 trigger：睡眠中移动鼠标/来信号），carrying=顶箱子
+ *  （gitBranch 变更闪现）。 */
+export declare const DEEPY_INTERACTION_ANIMATION: Readonly<Record<string, string>>;
+/** 通知气泡反应 → 动画：error 色 → 出错啦；success → 任务完成；
+ *  warning → 需要你确认；无色（默认档）→ idle-look。 */
+export declare const DEEPY_NOTIFICATION_REACTION: Readonly<Record<string, string>>;
+/** idle 族的随机轮换池（官方表：空闲待机，后三个随机插播；idle-look 同时
+ *  兼任悬停追踪档）。按 IDLE_ROTATE_MS 时间轮换，不跟信号边沿。 */
+export declare const DEEPY_IDLE_ROTATION: readonly string[];
+/** 显示语义（mood.ts 平滑层的输出）→ kit 动画键。注意 thinking/typing/
+ *  notification/happy 是显示语义不是 CompanionMood——mood 表的键是
+ *  waiting/thinking/working/responding/attention/celebrate，语义表必须单列。 */
+export declare const DEEPY_SEMANTIC_ANIMATION: Readonly<Record<string, string>>;
+/** 语义 → kit 动画键的统一查找；DEEPY_IDLE_ROTATION 的成员本身就是
+ *  kit 键，不需要映射。 */
+export declare function deepyAnimationFor(semantic: string): string;
+/** elapsed 时刻应显示第几帧（按 dur 累加取模，确定性、可单测）。 */
+export declare function frameAt(animation: DeepyAnimation, elapsedMs: number): number;
+/** 一个动画全部帧的预渲染 ANSI 行（15 行/帧），惰性生成并缓存。多套
+ *  素材包（deepy / whaleGirl）共用本缓存：键必须带 kit.id，否则同名
+ *  动画会串包（鲸娘读到 deepy 的行，调色板错乱）。 */
+export declare function renderedDeepyAnimation(kit: DeepyKit, key: string): readonly string[][] | undefined;
+/** 测试接缝：清掉加载与渲染缓存（deepy 与 whaleGirl 一起复位）。 */
+export declare function resetDeepyCacheForTests(): void;
+export {};
+//# sourceMappingURL=deepy.d.ts.map

package/lib/types/components/sidePanel/companion/deepy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepy.d.ts","sourceRoot":"","sources":["../../../../../src/components/sidePanel/companion/deepy.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAE9C,KAAK,GAAG,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAE5C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;IACtC,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,SAAS,CAAC,CAAA;IACjD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAA;CACzD;AAED,eAAO,MAAM,WAAW;;;EAA2C,CAAA;AAsEnE;4CAC4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAA;CACjC;AAED,eAAO,MAAM,aAAa,EAAE,cAA8B,CAAA;AAC1D,eAAO,MAAM,iBAAiB,EAAE,cAA8B,CAAA;AAE9D;;mBAEmB;AACnB,wBAAgB,aAAa,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAapH;AAED,mDAAmD;AACnD,wBAAgB,YAAY,IAAI,QAAQ,GAAG,SAAS,CAEnD;AAED;kEACkE;AAClE,wBAAgB,gBAAgB,IAAI,QAAQ,GAAG,SAAS,CAEvD;AAED;kCACkC;AAClC,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAUxE,CAAA;AAED;2CAC2C;AAC3C,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKpE,CAAA;AAED;;;wBAGwB;AACxB,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxE,CAAA;AAED;0CAC0C;AAC1C,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxE,CAAA;AAED;6CAC6C;AAC7C,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAgD,CAAA;AAEjG;;uEAEuE;AACvE,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWrE,CAAA;AAED;mBACmB;AACnB,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,4CAA4C;AAC5C,wBAAgB,OAAO,CAAC,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAS5E;AAID;;kCAEkC;AAClC,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAAE,GAAG,SAAS,CAUlG;AAED,8CAA8C;AAC9C,wBAAgB,uBAAuB,IAAI,IAAI,CAI9C"}

package/lib/types/components/sidePanel/companion/deepy.js

@@ -0,0 +1,222 @@
+/**
+ * Deepy 小鲸鱼素材包接入（assets/deepy/frames.json，非官方粉丝作品，
+ * 见 assets/deepy/README.md）：20 个动画，每帧 42×30 像素字母格——
+ * 与开屏鲸鱼同一套半块渲染管线（renderSpriteRows），显示为 42 列 ×
+ * 15 行。
+ *
+ * 设计要点：
+ * - 帧选择是纯函数 frameAt(animation, elapsedMs)：按帧表 dur 累加取模，
+ *   不持定时器；mood 切换时 CompanionPanel 换动画并从 0 计 elapsed。
+ * - 预渲染在首次使用时按动画惰性生成（RLE + erase-to-EOL 由
+ *   renderSpriteRows 保证），缺素材（包未带 frames.json）时返回
+ *   undefined，皮肤层回退到 WhaleSkin。
+ *
+ * 加载/校验/缓存抽成 loadSpriteKit（deepy 与鲸娘 assets/whaleGirl 共用，
+ * 同 schema：22 动画，构建脚本 scripts/build-whale-girl-kit.mjs）。
+ */
+import { readFileSync } from 'node:fs';
+import { renderSpriteRows } from '../../Whale.js';
+export const DEEPY_CELLS = Object.freeze({ columns: 42, rows: 15 });
+/**
+ * Asset locations, tried in order. The depth differs by what is running:
+ * - `src/components/sidePanel/companion/` (tsx harnesses) needs four levels;
+ * - the COMPILED tree `lib/types/components/sidePanel/companion/` — what the
+ *   installed package and every real session actually loads — sits one level
+ *   deeper, so it needs five. Getting this wrong is silent: loadDeepyKit()
+ *   falls back to the whale skin and the pet simply never shows the kit.
+ */
+const DEEPY_ASSET_CANDIDATES = [
+    '../../../../assets/deepy/frames.json',
+    '../../../assets/deepy/frames.json',
+    '../../../../../assets/deepy/frames.json',
+];
+/** 鲸娘素材包（用户提供，见 assets/whaleGirl/README.md）：同一套层级
+ *  教训——源码层 4 层 + 编译层 5 层。 */
+const WHALE_GIRL_ASSET_CANDIDATES = [
+    '../../../../assets/whaleGirl/frames.json',
+    '../../../../../assets/whaleGirl/frames.json',
+];
+/** 校验即拒绝：尺寸不符 / 未知调色板字符 / 帧 dur 非正数，任一失败整份
+ *  视为不可用（皮肤回退），不渲染半成品。id 是素材包身份（缓存用）。 */
+function parseKit(raw, id) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const data = raw;
+    if (!Array.isArray(data.size) || data.size[0] !== 42 || data.size[1] !== 30)
+        return undefined;
+    if (data.palette === null || typeof data.palette !== 'object')
+        return undefined;
+    const palette = { '.': undefined };
+    for (const [key, value] of Object.entries(data.palette)) {
+        if (key.length !== 1 || typeof value !== 'string' || !/^#[0-9a-fA-F]{6}$/.test(value))
+            return undefined;
+        palette[key] = [
+            Number.parseInt(value.slice(1, 3), 16),
+            Number.parseInt(value.slice(3, 5), 16),
+            Number.parseInt(value.slice(5, 7), 16),
+        ];
+    }
+    if (!Array.isArray(data.animations))
+        return undefined;
+    const byKey = {};
+    for (const animation of data.animations) {
+        if (typeof animation.key !== 'string' || !Array.isArray(animation.frames))
+            return undefined;
+        const frames = [];
+        for (const frame of animation.frames) {
+            if (typeof frame.dur !== 'number' || frame.dur <= 0 || !Array.isArray(frame.rows))
+                return undefined;
+            if (frame.rows.length !== 30)
+                return undefined;
+            const rows = frame.rows;
+            for (const row of rows) {
+                if (typeof row !== 'string' || row.length !== 42)
+                    return undefined;
+                for (const char of row) {
+                    if (!(char in palette))
+                        return undefined;
+                }
+            }
+            frames.push({ dur: frame.dur, rows: rows });
+        }
+        byKey[animation.key] = {
+            key: animation.key,
+            title: typeof animation.title === 'string' ? animation.title : animation.key,
+            frames,
+            totalMs: frames.reduce((sum, frame) => sum + frame.dur, 0),
+        };
+    }
+    return { id, columns: 42, rows: 30, palette, byKey };
+}
+export const deepyKitCache = { kit: null };
+export const whaleGirlKitCache = { kit: null };
+/** 按候选相对路径（相对本模块）依次尝试「读取 + parseKit 校验」，第一个
+ *  通过校验的胜出并记入 cache；全部失败 → undefined。抽自 loadDeepyKit，
+ *  deepy 与鲸娘共用。 */
+export function loadSpriteKit(candidates, cache, id) {
+    if (cache.kit !== null)
+        return cache.kit;
+    for (const candidate of candidates) {
+        try {
+            const url = new URL(candidate, import.meta.url);
+            cache.kit = parseKit(JSON.parse(readFileSync(url, 'utf8')), id);
+            if (cache.kit !== undefined)
+                return cache.kit;
+        }
+        catch {
+            // 下一个候选路径
+        }
+    }
+    cache.kit = undefined;
+    return undefined;
+}
+/** 加载并缓存 deepy 素材包；素材缺失或校验失败返回 undefined（皮肤回退）。 */
+export function loadDeepyKit() {
+    return loadSpriteKit(DEEPY_ASSET_CANDIDATES, deepyKitCache, 'deepy');
+}
+/** 鲸娘素材包（用户提供，assets/whaleGirl/frames.json：22 动画，与 deepy
+ *  同 schema 的 42×30 字母格，构建见 scripts/build-whale-girl-kit.mjs）。 */
+export function loadWhaleGirlKit() {
+    return loadSpriteKit(WHALE_GIRL_ASSET_CANDIDATES, whaleGirlKitCache, 'whaleGirl');
+}
+/** mood → deepy 动画（素材包 README 的状态对应表；显示语义经
+ *  CompanionPanel 的平滑层后映射到这里）。 */
+export const DEEPY_MOOD_ANIMATION = {
+    sleeping: 'sleeping',
+    idle: 'idle',
+    waiting: 'thinking',
+    thinking: 'thinking',
+    working: 'typing',
+    responding: 'typing',
+    attention: 'notification',
+    celebrate: 'happy',
+    error: 'error',
+};
+/** 并行上下文 → 动画（官方表：conducting=2+ 子代理、building=3+ 会话、
+ *  music=1 子代理或 2 会话、compacting=上下文压缩）。 */
+export const DEEPY_CONTEXT_ANIMATION = {
+    music: 'music',
+    conducting: 'conducting',
+    building: 'building',
+    compacting: 'compacting',
+};
+/** 互动/悬停/闪现 → 动画（官方表 reaction 档）：look=idle-look（东张西望，
+ *  追踪面板内指针），notice=idle-spout（指针碰到宠物本体，开心喷水），
+ *  waking=被吵醒（官方 trigger：睡眠中移动鼠标/来信号），carrying=顶箱子
+ *  （gitBranch 变更闪现）。 */
+export const DEEPY_INTERACTION_ANIMATION = {
+    'poke-left': 'poke-left',
+    'poke-right': 'poke-right',
+    tickle: 'tickle',
+    drag: 'drag',
+    look: 'idle-look',
+    notice: 'idle-spout',
+    waking: 'waking',
+    carrying: 'carrying',
+};
+/** 通知气泡反应 → 动画：error 色 → 出错啦；success → 任务完成；
+ *  warning → 需要你确认；无色（默认档）→ idle-look。 */
+export const DEEPY_NOTIFICATION_REACTION = {
+    error: 'error',
+    warning: 'notification',
+    success: 'happy',
+    default: 'idle-look',
+};
+/** idle 族的随机轮换池（官方表：空闲待机，后三个随机插播；idle-look 同时
+ *  兼任悬停追踪档）。按 IDLE_ROTATE_MS 时间轮换，不跟信号边沿。 */
+export const DEEPY_IDLE_ROTATION = ['idle', 'idle-look', 'idle-spout', 'swim'];
+/** 显示语义（mood.ts 平滑层的输出）→ kit 动画键。注意 thinking/typing/
+ *  notification/happy 是显示语义不是 CompanionMood——mood 表的键是
+ *  waiting/thinking/working/responding/attention/celebrate，语义表必须单列。 */
+export const DEEPY_SEMANTIC_ANIMATION = {
+    thinking: 'thinking',
+    typing: 'typing',
+    notification: 'notification',
+    error: 'error',
+    happy: 'happy',
+    sleeping: 'sleeping',
+    idle: 'idle',
+    ...DEEPY_CONTEXT_ANIMATION,
+    ...DEEPY_INTERACTION_ANIMATION,
+    ...DEEPY_NOTIFICATION_REACTION,
+};
+/** 语义 → kit 动画键的统一查找；DEEPY_IDLE_ROTATION 的成员本身就是
+ *  kit 键，不需要映射。 */
+export function deepyAnimationFor(semantic) {
+    return DEEPY_SEMANTIC_ANIMATION[semantic] ?? 'idle';
+}
+/** elapsed 时刻应显示第几帧（按 dur 累加取模，确定性、可单测）。 */
+export function frameAt(animation, elapsedMs) {
+    if (animation.frames.length === 0 || animation.totalMs <= 0)
+        return 0;
+    let remainder = Math.max(0, elapsedMs) % animation.totalMs;
+    for (let index = 0; index < animation.frames.length; index += 1) {
+        const frame = animation.frames[index];
+        if (remainder < frame.dur)
+            return index;
+        remainder -= frame.dur;
+    }
+    return animation.frames.length - 1;
+}
+const renderedCache = new Map();
+/** 一个动画全部帧的预渲染 ANSI 行（15 行/帧），惰性生成并缓存。多套
+ *  素材包（deepy / whaleGirl）共用本缓存：键必须带 kit.id，否则同名
+ *  动画会串包（鲸娘读到 deepy 的行，调色板错乱）。 */
+export function renderedDeepyAnimation(kit, key) {
+    const animation = kit.byKey[key];
+    if (animation === undefined)
+        return undefined;
+    const cacheKey = kit.id + ':' + key;
+    let rendered = renderedCache.get(cacheKey);
+    if (rendered === undefined) {
+        rendered = Object.freeze(animation.frames.map(frame => renderSpriteRows(frame.rows, kit.palette)));
+        renderedCache.set(cacheKey, rendered);
+    }
+    return rendered;
+}
+/** 测试接缝：清掉加载与渲染缓存（deepy 与 whaleGirl 一起复位）。 */
+export function resetDeepyCacheForTests() {
+    deepyKitCache.kit = null;
+    whaleGirlKitCache.kit = null;
+    renderedCache.clear();
+}

package/lib/types/components/sidePanel/companion/mood.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Companion 情绪管线（设计分文档 §2 + v2.1 + 2026-10 防闪烁平滑层）。
+ *
+ * 分四层，前两层纯派生、后两层近纯步进，全部可脱离组件单测：
+ *
+ *   信号 ──deriveCompanionMood──▶ 目标心情（瞬时信号直读：审批/失败/工作/庆祝/睡眠）
+ *       ──deriveCompanionContext──▶ 并行上下文（music/conducting/building/compacting）
+ *       ──resolveTargetSemantic──▶ 目标显示语义
+ *       ──stepCompanionDisplay──▶ 显示语义（平滑器：防抖 + 最短停留 + 抢占）
+ *   互动（戳/挠/拖拽/悬停）与通知气泡反应是独立覆盖层，由 CompanionPanel
+ *   接线；演完回到**平滑后**的显示语义，不重新派生。
+ *
+ * 防闪烁五规则（用户实测：快速短工具调用让动画在 typing/idle/happy 间闪跳）：
+ * 1. 派生与显示分离（本文件即实现，组件不外挂补丁层）。
+ * 2. 优先级 attention > error > working > celebrate > idle 族；只有
+ *    notification/error 语义允许立刻打断当前动画；happy 是回合完成的
+ *    边沿一次性事件（只在 working→false 时由 Panel 触发一次），自带
+ *    CELEBRATE_DWELL_MS 停留窗——若再过闸门会被截短，故同样立即切换。
+ * 3. 离开活跃族（working/上下文）进 idle 族要 LEAVE_WORKING_SETTLE_MS 的
+ *    稳定期；连发短工具的间隙典型 200–800ms，1500ms 覆盖住抖动又不至于
+ *    让"停下来了"的反馈显得迟钝。进入 working 族不防抖（立刻切，有信息量）。
+ * 4. 非抢占切换要 MIN_MOOD_DWELL_MS 最短停留（人眼对终端动画的感知下限
+ *    量级，低于它就是闪）；同语义重派生**不重置**动画时钟（since 保留，
+ *    elapsed 连续、不跳帧）。
+ * 5. 互动层独立；idle 族（idle/idle-look/idle-spout/swim）按
+ *    IDLE_ROTATE_MS 时间轮换，不跟信号边沿走。
+ */
+import type { ActivityView } from '../../../dsh-adapter/activity-store.js';
+import type { SpinnerMode } from '../../../adapter/ports/channel-display.js';
+/** 离开活跃族的防抖窗：目标稳定非工作这么久才切走（规则 3）。 */
+export declare const LEAVE_WORKING_SETTLE_MS = 1500;
+/** 任何非抢占切换后的最短停留（规则 4）。 */
+export declare const MIN_MOOD_DWELL_MS = 1000;
+/** 回合完成庆祝（happy）的停留窗；由 Panel 在 working→false 边沿armed。 */
+export declare const CELEBRATE_DWELL_MS = 2500;
+/** idle 族动画的轮换周期（规则 5）。 */
+export declare const IDLE_ROTATE_MS = 8000;
+/** 狂点判定窗口：窗口内 ≥TICKLE_MIN_CLICKS 次点击 → tickle。 */
+export declare const TICKLE_WINDOW_MS = 900;
+export declare const TICKLE_MIN_CLICKS = 3;
+/** 通知气泡的展示时长（约数，按动画 tick 粒度收回）。 */
+export declare const NOTIFICATION_BUBBLE_MS = 5000;
+/** 醒来（waking）反应的闪现时长。 */
+export declare const WAKING_FLASH_MS = 1800;
+/** 顶箱子（carrying，gitBranch 变更闪现）时长。 */
+export declare const CARRYING_FLASH_MS = 2500;
+/** Enter 戳一戳时完整活动行气泡的时长。 */
+export declare const POKE_MS = 3000;
+export type CompanionMood = 
+/** 空闲超过 sleepAfter 且无未读事项。 */
+'sleeping'
+/** 空闲。 */
+ | 'idle'
+/** 请求已发、首 token 未到。 */
+ | 'waiting'
+/** 推理中。 */
+ | 'thinking'
+/** 工具运行中。 */
+ | 'working'
+/** 正文流式中。 */
+ | 'responding'
+/** 有待处理的审批 / 问卷（失败任务不再折进来——那是 error）。 */
+ | 'attention'
+/** 回合完成 / goal 完成 / star / 节日彩蛋（短暂）。 */
+ | 'celebrate'
+/** 工具失败：后台任务失败未读或子代理 failed（官方素材表 error=工具失败）。 */
+ | 'error';
+export interface CompanionMoodInputs {
+    readonly working: boolean;
+    readonly spinnerMode: SpinnerMode;
+    /** workingActivity 投影（activity 插件未装时缺省，退回 working +
+     *  spinnerMode 也能给出 waiting / thinking / working / responding）。 */
+    readonly activity: ActivityView | undefined;
+    /** 需要用户处理的事（审批/问卷）→ attention。 */
+    readonly attention: {
+        readonly approvalPending: boolean;
+        readonly questionPending: boolean;
+    };
+    /** 失败信号（后台任务失败未读 + failed 子代理数）→ error。 */
+    readonly failures: {
+        readonly failedJobsUnread: number;
+        readonly failedSubagents: number;
+    };
+    readonly lastInputAt: number;
+    readonly celebration: {
+        readonly kind: 'star' | 'holiday' | 'turn-done' | 'goal-done';
+        readonly until: number;
+    } | undefined;
+    /** 0 = 不入睡。 */
+    readonly sleepAfterMs: number;
+}
+export interface DerivedCompanionMood {
+    readonly mood: CompanionMood;
+    /** 皮肤气泡文案（activity.phrase ?? label+detail；宽截断在皮肤侧）。
+     *  非工作/注意态为 undefined。 */
+    readonly bubble?: string;
+}
+/** 纯派生（规则 1 的第一层）：attention > error > working > celebrate >
+ *  sleeping > idle。 */
+export declare function deriveCompanionMood(inputs: CompanionMoodInputs, now: number): DerivedCompanionMood;
+export type CompanionContextKind = 'music' | 'conducting' | 'building' | 'compacting';
+/** 结构化最小信号面：测试可用裸对象伪造，运行时来自 ChannelUi。 */
+export interface CompanionContextInputs {
+    readonly working: boolean;
+    readonly subagents: readonly {
+        readonly status: string;
+    }[];
+    readonly backgroundJobs: readonly {
+        readonly status: string;
+    }[];
+    /** ChannelUi.compaction：非空表示压缩进行中。 */
+    readonly compaction: unknown;
+}
+/** 子代理在跑数（starting/running）。 */
+export declare function countRunningSubagents(subagents: readonly {
+    readonly status: string;
+}[]): number;
+/** 后台任务在跑数（running/stopping 都算活着）。 */
+export declare function countRunningJobs(jobs: readonly {
+    readonly status: string;
+}[]): number;
+/** 「会话」口径：主回合（working 计 1）+ 在跑子代理 + 在跑后台任务。 */
+export declare function countSessionsRunning(working: boolean, runningSubagents: number, runningJobs: number): number;
+/** 素材包官方表：conducting=2+ 子代理；building=3+ 会话；music=1 子代理或
+ *  2 会话；compacting=上下文压缩进行中（ChannelUi.compaction 是现成信号）。
+ *  优先级：compacting > conducting > building > music（子代理专属动画最具体）。
+ *  carrying（新建工作树/分支）没有推送信号，走 gitBranch 变更闪现（Panel 接线）。 */
+export declare function deriveCompanionContext(inputs: CompanionContextInputs): CompanionContextKind | undefined;
+export type CompanionDisplaySemantic = 'thinking' | 'typing' | 'notification' | 'error' | 'happy' | 'sleeping' | 'idle' | CompanionContextKind;
+export interface CompanionDisplayState {
+    readonly semantic: CompanionDisplaySemantic;
+    /** 显示语义进入的时刻 = 动画时钟锚点；同语义重派生保留（不跳帧）。 */
+    readonly since: number;
+    /** 目标最后一次离开活跃族的时刻；0 = 目标仍在活跃族。 */
+    readonly activeLeftAt: number;
+}
+export declare const initialCompanionDisplayState: CompanionDisplayState;
+/** 目标心情 + 上下文 → 目标显示语义（纯函数）。attention/error/happy 直通；
+ *  working 细分与 idle/sleeping 在有并行上下文时让位（music=官方表的
+ *  juggling：主回合 + 子代理同时在跑时宠物该演"分身"而不是敲代码）。 */
+export declare function resolveTargetSemantic(mood: CompanionMood, context: CompanionContextKind | undefined): CompanionDisplaySemantic;
+/** 平滑器（规则 2/3/4，近纯步进）：输入目标语义流 + 时钟，输出显示语义流。
+ *
+ * - 目标 == 当前显示：什么都不动（since 保留 → 动画 elapsed 连续）。
+ * - 抢占（notification/error/happy）或进入 working 族：立刻切。
+ * - 其余切换：settle（离开活跃族进 idle 族需 LEAVE_WORKING_SETTLE_MS 稳定）
+ *   与 dwell（显示语义已停留 MIN_MOOD_DWELL_MS）双闸全开才切。
+ * - realign：visible=false→true 时跳过闸门对齐当前目标（隐藏期间没走 tick）。
+ */
+export declare function stepCompanionDisplay(prev: CompanionDisplayState, target: CompanionDisplaySemantic, now: number, opts?: {
+    readonly realign?: boolean;
+}): CompanionDisplayState;
+/** idle 显示语义下的动画轮换槽序号：由进入 idle 的时刻与当前时钟决定，
+ *  与信号无关；同一 idle 期内确定，跨 idle 期自然错开。 */
+export declare function idleRotationIndex(idleSince: number, now: number, length: number): number;
+export type CompanionReactionKind = 'error' | 'warning' | 'success' | 'default';
+/** NotificationItem.color → 反应档（error/warning/success/default）。
+ *  没有更多语义字段可判（如"已打断"），default 档用 idle-look——见交付说明。 */
+export declare function notificationReactionKind(color: string | undefined): CompanionReactionKind;
+export interface CompanionNotification {
+    readonly text: string;
+    readonly color?: string;
+}
+export interface CompanionNotificationTracker {
+    readonly seen: Set<object>;
+    armed: boolean;
+}
+export declare function createNotificationTracker(): CompanionNotificationTracker;
+/** 渲染期步进：从尾部扫描未见过的条目（notify 追加在最后），返回最新一条
+ *  （旧的让位——气泡同时只留最新）；首次调用只记账不发射（不弹历史旧账）。
+ *  重建数组（slice/filter）但条目对象同引用时不会误报；条目被摘除时顺手
+ *  清理 seen，防泄漏。 */
+export declare function stepNotificationTracker(tracker: CompanionNotificationTracker, notifications: readonly CompanionNotification[], opts?: {
+    readonly silent?: boolean;
+}): CompanionNotification | undefined;
+//# sourceMappingURL=mood.d.ts.map

package/lib/types/components/sidePanel/companion/mood.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mood.d.ts","sourceRoot":"","sources":["../../../../../src/components/sidePanel/companion/mood.ts"],"names":[],"mappings":"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"}