fix: Simplify the tutorial & add tutorial reset function (#300)

* correct the driver's introduction's element

* Simplify the tutorial & add tutorial reset function

* Simplify the tutorial & add tutorial reset function & bug fix

* Moved localStorage side effect from getter and replaced hardcoded Chinese page names.

* preserved original body overflow, moved drag listeners to manager object to prevent leaks, changed forEach to block-body arrow, and added driver.destroy() before restart.

---------

Co-authored-by: Hongzhi Wen <wenguanjung@aliyun.com>

Author: Tonnodoubt

static/css/live2d_parameter_editor.css

@@ -48,7 +48,7 @@ pointer-events: auto;
 display: block;
 width: 100%;
 height: 100%;
-background: transparent;
+background: rgba(255, 255, 255, 0.7);
 cursor: grab;
 pointer-events: auto;
 }

static/css/memory_browser.css

@@ -162,10 +162,17 @@ body {
     min-height: 500px;
 }
 
-.file-list {
+/* 左侧列：包含两个框 */
+.left-column {
     width: 240px;
     min-width: 220px;
     flex-shrink: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+}
+
+.file-list {
     border: 2px solid #b3e5fc;
     border-radius: 20px;
     padding: 20px;
@@ -335,6 +342,75 @@ body {
     font-weight: 500;
 }
 
+/* 新手引导重置区域 */
+.tutorial-section {
+    margin-top: 0;
+}
+
+.tutorial-reset-wrapper {
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+}
+
+/* 下拉框 - 胶囊形状，与猫娘按钮一致 */
+.tutorial-reset-wrapper select {
+    width: 100%;
+    padding: 10px 15px;
+    background: #fff;
+    border: 2px solid #e3f4ff;
+    border-radius: 50px;
+    color: #40C5F1;
+    font-size: 0.95rem;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    text-align: center;
+    appearance: none;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath fill='%2340C5F1' d='M6 9L1 4h10z'/%3E%3C/svg%3E");
+    background-repeat: no-repeat;
+    background-position: right 15px center;
+}
+
+.tutorial-reset-wrapper select:hover {
+    border-color: #40C5F1;
+    background-color: #f0f9ff;
+    transform: translateY(-1px);
+}
+
+.tutorial-reset-wrapper select:focus {
+    outline: none;
+    border-color: #40C5F1;
+}
+
+/* 重置按钮 - 胶囊形状，与猫娘按钮一致 */
+.tutorial-reset-wrapper .tutorial-reset-btn {
+    width: 100%;
+    padding: 10px 15px;
+    background: #fff;
+    border: 2px solid #e3f4ff;
+    border-radius: 50px;
+    color: #40C5F1;
+    font-size: 0.95rem;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    text-align: center;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+}
+
+.tutorial-reset-wrapper .tutorial-reset-btn:hover {
+    border-color: #40C5F1;
+    background: #f0f9ff;
+    transform: translateY(-1px);
+}
+
+.tutorial-reset-wrapper .tutorial-reset-btn:active {
+    transform: translateY(0);
+}
+
 /* 编辑器区域 */
 .editor {
     flex: 1;

static/live2d-interaction.js

@@ -284,6 +284,14 @@ Live2DManager.prototype.setupDragAndDrop = function (model) {
     let isDragging = false;
     let dragStartPos = new PIXI.Point();
 
+    // 点击检测相关变量
+    let clickStartTime = 0;
+    let clickStartX = 0;
+    let clickStartY = 0;
+    let hasMoved = false;
+    const CLICK_THRESHOLD_DISTANCE = 10; // 移动距离阈值（像素）
+    const CLICK_THRESHOLD_TIME = 300; // 时间阈值（毫秒）
+
     // 使用 live2d-ui-drag.js 中的共享工具函数（按钮 pointer-events 管理）
     const disableButtonPointerEvents = () => {
         if (window.DragHelpers) {
@@ -297,6 +305,164 @@ Live2DManager.prototype.setupDragAndDrop = function (model) {
         }
     };
 
+    const playTutorialMotion = async () => {
+        if (!this.currentModel || !this.currentModel.motion) {
+            return false;
+        }
+
+        const fileRefMotions = this.fileReferences && this.fileReferences.Motions;
+        let motionGroups = [];
+
+        if (fileRefMotions && typeof fileRefMotions === 'object') {
+            motionGroups = Object.keys(fileRefMotions)
+                .filter(group => Array.isArray(fileRefMotions[group]) && fileRefMotions[group].length > 0);
+        }
+
+        if (motionGroups.length === 0 &&
+            this.currentModel.internalModel &&
+            this.currentModel.internalModel.motionManager &&
+            this.currentModel.internalModel.motionManager.definitions) {
+            const defs = this.currentModel.internalModel.motionManager.definitions;
+            motionGroups = Object.keys(defs)
+                .filter(group => Array.isArray(defs[group]) && defs[group].length > 0);
+        }
+
+        if (motionGroups.length === 0) {
+            return false;
+        }
+
+        const group = this.getRandomElement(motionGroups);
+        if (!group) return false;
+
+        const groupList =
+            (fileRefMotions && fileRefMotions[group]) ||
+            (this.currentModel.internalModel &&
+                this.currentModel.internalModel.motionManager &&
+                this.currentModel.internalModel.motionManager.definitions &&
+                this.currentModel.internalModel.motionManager.definitions[group]) ||
+            [];
+
+        if (!Array.isArray(groupList) || groupList.length === 0) {
+            return false;
+        }
+
+        const index = Math.floor(Math.random() * groupList.length);
+
+        try {
+            const motion = await this.currentModel.motion(group, index);
+            if (motion) {
+                console.log(`[Interaction] 教程模式 - 播放动作: ${group}[${index}]`);
+                return true;
+            }
+        } catch (error) {
+            console.warn('[Interaction] 教程模式 - 动作播放失败:', error);
+        }
+
+        return false;
+    };
+
+    // 点击触发随机表情和动作
+    const triggerRandomEmotion = async () => {
+        // 教程模式：直接随机播放表情
+        if (window.isInTutorial) {
+            console.log('[Interaction] 教程模式 - 随机播放表情');
+            try {
+                // 获取表情列表
+                let expressionNames = [];
+                if (this.fileReferences && Array.isArray(this.fileReferences.Expressions)) {
+                    expressionNames = this.fileReferences.Expressions.map(e => e.Name).filter(Boolean);
+                }
+
+                // 随机播放表情
+                if (expressionNames.length > 0) {
+                    const randomExpression = expressionNames[Math.floor(Math.random() * expressionNames.length)];
+                    console.log(`[Interaction] 教程模式 - 播放表情: ${randomExpression}`);
+                    await this.currentModel.expression(randomExpression);
+
+                    const playedMotion = await playTutorialMotion();
+
+                    if (!playedMotion) {
+                        // 动作不可用时，回退到参数动画模拟效果
+                        const model = this.currentModel.internalModel;
+                        if (model && model.coreModel) {
+                            // 随机晃动头部
+                            const angleXIndex = model.coreModel.getParameterIndex('ParamAngleX');
+                            const angleYIndex = model.coreModel.getParameterIndex('ParamAngleY');
+                            const bodyAngleXIndex = model.coreModel.getParameterIndex('ParamBodyAngleX');
+
+                            const duration = 1000 + Math.random() * 1000; // 1-2秒
+                            const startTime = Date.now();
+
+                            const setParamByIndex = (index, value) => {
+                                if (index < 0) return;
+                                if (typeof model.coreModel.setParameterValueByIndex === 'function') {
+                                    model.coreModel.setParameterValueByIndex(index, value);
+                                } else {
+                                    model.coreModel.setParameterValueById(index, value);
+                                }
+                            };
+
+                            const animate = () => {
+                                const elapsed = Date.now() - startTime;
+                                const progress = Math.min(elapsed / duration, 1);
+                                const t = progress * Math.PI * 2; // 一个完整周期
+
+                                setParamByIndex(angleXIndex, Math.sin(t) * 15); // -15 到 15 度
+                                setParamByIndex(angleYIndex, Math.cos(t) * 10); // -10 到 10 度
+                                setParamByIndex(bodyAngleXIndex, Math.sin(t * 0.5) * 5); // 更慢的身体晃动
+
+                                if (progress < 1) {
+                                    requestAnimationFrame(animate);
+                                } else {
+                                    // 动画结束，恢复默认值
+                                    setParamByIndex(angleXIndex, 0);
+                                    setParamByIndex(angleYIndex, 0);
+                                    setParamByIndex(bodyAngleXIndex, 0);
+                                }
+                            };
+
+                            animate();
+                            console.log('[Interaction] 教程模式 - 播放参数动画');
+                        }
+                    }
+                }
+            } catch (error) {
+                console.warn('[Interaction] 教程模式播放表情失败:', error);
+            }
+            return;
+        }
+
+        // 正常模式：使用情感系统
+        if (!this.emotionMapping) {
+            console.log('[Interaction] 没有情感映射配置，跳过点击触发');
+            return;
+        }
+
+        // 获取可用的情感列表
+        let availableEmotions = [];
+
+        // 从 emotionMapping 中获取可用情感
+        if (this.emotionMapping.expressions) {
+            availableEmotions = Object.keys(this.emotionMapping.expressions).filter(e => e !== '常驻');
+        }
+
+        // 如果没有配置情感，使用默认列表
+        if (availableEmotions.length === 0) {
+            availableEmotions = ['happy', 'sad', 'angry', 'neutral'];
+        }
+
+        // 随机选择一个情感
+        const randomEmotion = availableEmotions[Math.floor(Math.random() * availableEmotions.length)];
+        console.log(`[Interaction] 点击触发随机情感: ${randomEmotion}`);
+
+        // 触发情感
+        try {
+            await this.setEmotion(randomEmotion);
+        } catch (error) {
+            console.warn('[Interaction] 触发情感失败:', error);
+        }
+    };
+
     model.on('pointerdown', (event) => {
         if (this.isLocked) return;
 
@@ -312,6 +478,13 @@ Live2DManager.prototype.setupDragAndDrop = function (model) {
         const globalPos = event.data.global;
         dragStartPos.x = globalPos.x - model.x;
         dragStartPos.y = globalPos.y - model.y;
+
+        // 记录点击开始信息
+        clickStartTime = Date.now();
+        clickStartX = globalPos.x;
+        clickStartY = globalPos.y;
+        hasMoved = false;
+
         document.getElementById('live2d-canvas').style.cursor = 'grabbing';
 
         // 开始拖动时，临时禁用按钮的 pointer-events
@@ -326,6 +499,15 @@ Live2DManager.prototype.setupDragAndDrop = function (model) {
             // 拖拽结束后恢复按钮的 pointer-events
             restoreButtonPointerEvents();
 
+            // 检测是否为点击（非拖拽）
+            const clickDuration = Date.now() - clickStartTime;
+            if (!hasMoved && clickDuration < CLICK_THRESHOLD_TIME) {
+                // 这是一个点击，触发随机表情和动作
+                console.log(`[Interaction] 检测到点击（时长: ${clickDuration}ms）`);
+                await triggerRandomEmotion();
+                return; // 点击不需要保存位置
+            }
+
             // 检测是否需要切换屏幕（多屏幕支持）
             // _checkAndSwitchDisplay returns true if a display switch occurred (and saved internally)
             const displaySwitched = await this._checkAndSwitchDisplay(model);
@@ -359,6 +541,14 @@ Live2DManager.prototype.setupDragAndDrop = function (model) {
             const x = event.clientX;
             const y = event.clientY;
 
+            // 检测是否移动超过阈值
+            const moveDistance = Math.sqrt(
+                Math.pow(x - clickStartX, 2) + Math.pow(y - clickStartY, 2)
+            );
+            if (moveDistance > CLICK_THRESHOLD_DISTANCE) {
+                hasMoved = true;
+            }
+
             model.x = x - dragStartPos.x;
             model.y = y - dragStartPos.y;
         }
@@ -1242,4 +1432,3 @@ Live2DManager.prototype.destroy = function () {
 
     console.log('[Live2D] Live2DManager 实例已销毁');
 };
-

static/locales/en.json

@@ -941,7 +941,21 @@
     "enabled": "Enabled",
     "disabled": "Disabled",
     "autoReviewNote": "When enabled, the system will automatically organize and optimize memory content to improve conversation quality",
-    "saveFailedStatus": "Save failed"
+    "saveFailedStatus": "Save failed",
+    "tutorialReset": "Tutorial Guide",
+    "tutorialSelectPage": "-- Select Page --",
+    "tutorialAllPages": "All Pages",
+    "tutorialPageHome": "Home",
+    "tutorialPageModelManager": "Model Settings",
+    "tutorialPageParameterEditor": "Face Editor",
+    "tutorialPageEmotionManager": "Emotion Manager",
+    "tutorialPageCharaManager": "Character Manager",
+    "tutorialPageSettings": "API Settings",
+    "tutorialPageVoiceClone": "Voice Clone",
+    "tutorialPageMemoryBrowser": "Memory Browser",
+    "resetTutorialBtn": "Reset Tutorial",
+    "tutorialResetSuccess": "All tutorials have been reset. They will be shown again when you visit each page.",
+    "tutorialPageResetSuccess": "Tutorial for this page has been reset. It will be shown again when you visit."
   },
   "character": {
     "manager": "Character Manager",
@@ -1309,7 +1323,19 @@
   "tutorial": {
     "step1": {
       "title": "👋 Welcome to N.E.K.O",
-      "desc": "Your virtual companion. Click her to trigger different expressions and actions~"
+      "desc": "This is your virtual companion! Let me guide you through the features~"
+    },
+    "step1a": {
+      "title": "🎭 Click to Experience Expressions",
+      "desc": "Try clicking on the model! Each click triggers different expressions and actions. Click Next when you're done~"
+    },
+    "step1b": {
+      "title": "🖱️ Drag & Zoom",
+      "desc": "You can drag the model to move it, and use mouse wheel to zoom in/out. Give it a try~"
+    },
+    "step1c": {
+      "title": "🔒 Lock Model",
+      "desc": "Click this lock to lock the model position, preventing accidental moves. Click again to unlock~"
     },
     "step2": {
       "title": "💬 Chat Area",
@@ -1380,6 +1406,10 @@
       "desc": "Access Steam Workshop page and manage subscriptions~"
     },
     "completed": "✨ Tutorial complete! Enjoy~",
+    "resetHint": {
+      "title": "✨ Tutorial Complete",
+      "desc": "To view this tutorial again, go to \"Memory Browser\" and reset it in the \"Tutorial Guide\" section."
+    },
     "model_manager": {
       "common": {
         "step1": {