feat(mascot): 吉祥物「堇喵」形象实验室与展馆重构

[xunrua]

概要

新增 violet 吉祥物「堇喵」(Cat-Mochi) 形象实验室 /lab/mascot，并按人性化体验要求重构展馆排版。

• Mascot 引擎：参数化眼环几何（48 点闭合眼环库）、Catmull-Rom 身体轮廓、pose 合成（base/sequence/anims/过渡）、临界阻尼弹簧、自旋时间线（easeInOutCubic + 整圈位归零）、眨眼关键帧过冲、撒花粒子
• 36 套表情体系：生命周期 (00-07) / 情绪反应 (10-25) / 代理工作 (30-42)
• 展馆布局：桌面双栏——左侧深色剧场舞台 sticky 常驻视口（锥形顶光 + 台面光斑 + 台口线 + 暗角），右侧 Segmented 分段目录，hover 缩略图即实时预览、点击固定；移动端舞台在站点 header 下吸顶
• AI 消息协议落地：handleAIMessage({emotionId, tips})——舞台内 JSON 输入框可直接实测，未知 emotionId 平滑回退待机，tips 覆盖对白气泡；原生实例化示例与实际 API 一致（移除编造的 idle 参数）
• 组件架构拆分：MascotStage（引擎 React 宿主 + handle 桥）/ MascotTheater（剧场舞台卡）/ EmotionGridItem（陈列卡）/ MascotSdkSection（协议说明）/ useMascotExhibit（pinned+preview+巡演+台词代际状态机）

验证

• pnpm typecheck / biome lint / biome format 全绿
• 浏览器实测：AI 协议发送（合法 ID 切换、tips 覆盖气泡、未知 ID 回退待机）、目录点击固定同步高亮、sticky 舞台滚动常驻、聚光光效像素采样确认（光束内外 7.5 倍亮度差、光斑 4 倍、台口线清晰）

[github-actions]

AI Code Review · MiniMax-M3

评审结论

新增 agent-status 与 mascot 工作区包,协议/状态机/几何引擎整体实现质量较高,但 inject 行为与类级 docstring 描述的"独立 seq 轴"存在事实性冲突。

[github-actions]

[轻微] pointerMoveHandler 形参类型为 MouseEvent，但 addEventListener 监听的是 pointermove 事件，触发时实际传入 PointerEvent。PointerEvent 继承自 MouseEvent 故运行时无影响，但类型标注与监听事件不一致。

💡 修复计划 (Coding Plan)
将形参类型改为 PointerEvent：this.pointerMoveHandler = (e: PointerEvent) => {。

[github-actions]

[中等] handleCopyJson 内的 setTimeout 未保存 id、亦未在卸载时清理。1) 用户在 1.5s 内连续点击，第一次的 timeout 会提前把 copied 重置为 false，导致第二次点击的反馈时长被截断；2) 组件卸载后该 setTimeout 仍会触发 setState（React 18 静默忽略但仍是隐患）。

💡 修复计划 (Coding Plan)
用 useRef 保存 timeout id，并在新一轮点击与组件卸载时 clearTimeout：

const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const handleCopyJson = () => {
  if (timeoutRef.current) clearTimeout(timeoutRef.current);
  copyText(JSON.stringify({ emotionId: pinnedDef.id, tips: pinnedDef.desc }));
  setCopied(true);
  timeoutRef.current = setTimeout(() => setCopied(false), 1500);
};
useEffect(() => () => {
  if (timeoutRef.current) clearTimeout(timeoutRef.current);
}, []);

[github-actions]

[轻微] render() 中相邻两条注释属于「为什么这样做」的设计论证，违反仓库「注释只写代码无法自表达的信息」规则：

• // 脸部正面化:五官只随注视微移,不随自旋 yaw 滑动
• // 整脸统一淡出:转过侧面时脸渐隐、背面隐藏,杜绝「单眼+错位嘴」的残缺中间帧

💡 修复计划 (Coding Plan)
删除这两条设计意图注释；如确需保留请合并到模块顶部 JSDoc 或独立设计文档，避免在函数体内嵌入 why/历史决策说明。

[github-actions]

[中等] tipsRef 在 setEmotion/handleAIMessage 全流程中从未被读取，导致 onTips 回调永远不会触发；上方组件注释承诺的「onTips 在 handleAIMessage 带台词时回调」并未生效。

💡 修复计划 (Coding Plan)
在 handleAIMessage 内部通过 tipsRef 调用回调：
handleAIMessage: (msg) => {
const id = msg.emotionId?.trim();
const resolved = id && id.length > 0 ? id : "00";
mascotRef.current?.setEmotion(resolved);
tipsRef.current?.(msg.tips);
return { emotionId: resolved, ...(msg.tips !== undefined && { tips: msg.tips }) };
},
若不需要 onTips 则直接删除 tipsRef 相关两行。

[github-actions]

[轻微] destroy() 仅从 DOM 移除 svg 与事件监听，未清空 confettiPieces 数组；数组中保存的 SVGElement 引用阻止 GC，导致脱离 DOM 的节点引用残留形成内存泄漏。

💡 修复计划 (Coding Plan)
在 destroy() 中先移除并清空粒子再继续清理：
destroy(): void {
this.stop();
for (const p of this.confettiPieces) p.el.remove();
this.confettiPieces.length = 0;
if (this.clickHandler) this.svg.removeEventListener("click", this.clickHandler);
if (this.pointerMoveHandler) this.svg.removeEventListener("pointermove", this.pointerMoveHandler);
this.svg.remove();
this.destroyed = true;
}

[github-actions]

[轻微] 构造 useEffect 依赖数组为空，闭包内的 frozen/onClick/onPet 仅在挂载时生效。biome-ignore 注释解释了 emotion 走 setEmotion，但 frozen/onClick/onPet 同样存在陈旧闭包问题，父组件后续 prop 变更不会反映到 Mascot 实例。

💡 修复计划 (Coding Plan)
要么在 Mascot 类上新增 setFrozen/setOnClick/setOnPet 等 setter 后用独立 effect 驱动；要么把 frozen/onClick/onPet 加入依赖数组并在清理时 destroy 旧实例重建：
useEffect(() => {
if (!hostRef.current) return;
mascotRef.current?.destroy();
const m = new Mascot(hostRef.current, { emotion, frozen, onClick, onPet });
mascotRef.current = m;
return () => { m.destroy(); mascotRef.current = null; };
}, [frozen, onClick, onPet]);

[github-actions]

[轻微] setEmotion() 切换 emotion 时不清空 blinkQ，前一个 emotion 排队的眨眼关键帧仍按原 at 时间触发；切换到 blinkMs 为 null 的 emotion（如 Sleep/Standby）后仍可能出现不合时机的眨眼。

💡 修复计划 (Coding Plan)
在 setEmotion 起始处清空 blinkQ：
setEmotion(id: string): void {
const def = EMOTION_MAP.get(id) ?? Mascot.FALLBACK;
const now = performance.now();
const prevId = this.def.id;
this.blinkQ.length = 0;
// ...existing code
}

[github-actions]

[轻微] initInteractions 中 lastPointerPos 初始为 {0,0}、lastPetCheck 初始为 0；用户首次将指针移入头部区域 (vx 75-185, vy 30-125) 的 pointermove 会以原点计算出超过 35 的累计距离，并因 now - 0 > 250 恒为真触发一次计划外的 pet() 与 onPet 回调。

💡 修复计划 (Coding Plan)
在构造时初始化 lastPetCheck 为当前时间，阻止首次 move 命中阈值；或者在 handler 中跳过首帧：
// 构造里
this.lastPetCheck = performance.now();
// 或在 handler 起始：
if (this.lastPetCheck === 0) { this.lastPetCheck = now; this.lastPointerPos = { x: vx, y: vy }; return; }

[github-actions]

[中等] inject() 调用 this.lastSeqByAgent.set(agent, msg.seq),把注入 seq 写入 accept 的去重轴,与类级 docstring(第 123 行)"(内部独立 seq 轴,不与任何 agent 的外部 seq 冲突)"的事实描述相矛盾:同 agent 下,先 inject 再 accept 的真实消息若 seq <= injectSeq 会被 stale-seq 拒绝。现有测试 "inject 不阻塞其他 agent 的 v2 消息" 仅覆盖不同 agent 路径,未覆盖同 agent 场景,留给调用方一个与文档不符的陷阱。

💡 修复计划 (Coding Plan)
两种修法任选其一,先与作者确认意图:

1. 若 inject 真要独立 seq 轴(只跟自己争、不污染 accept),删掉第 190 行 this.lastSeqByAgent.set(agent, msg.seq),lastSeqByAgent.set 只在 accept 路径里更新;同时为 inject 单独加一个 'agent 已被 inject 占用,后续 accept 同 agent 且 seq < injectSeq 走 stale-seq' 的单元测试,确认预期。
2. 若 inject 故意要"占用"同 agent 的去重轴,把第 123 行的类级 docstring 改为"inject 与同 agent 的 accept 共享去重轴,会拒绝 seq <= injectSeq 的真实消息",同时把 inject 方法级 JSDoc 的 "@PARAM agent" 提示调用者使用默认 "manual" agent 以避免冲突,并补一个 store.test.ts 用例:先 inject({emotionId:"x"}, "codex"),再 accept({agent:"codex", seq:1, ...}) 必须返回 {applied:false, reason:"stale-seq"}。