Fix/home tutorial reset backend state (Project-N-E-K-O#1291)

* fix: reset home tutorial prompt state

* fix: make tutorial reset remote frontend friendly

* fix: secure tutorial reset request

* fix: retry tutorial reset after csrf refresh

* fix: signal tutorial teardown without completion

Author: wuyehan

main_routers/system_router.py

@@ -158,6 +158,7 @@
     record_tutorial_prompt_decision,
     record_tutorial_started,
     record_tutorial_completed,
+    reset_tutorial_prompt_state,
 )
 from utils.storage_location_bootstrap import build_storage_location_bootstrap_payload
 from utils.config_manager import get_config_manager as get_runtime_config_manager
@@ -1097,6 +1098,16 @@ async def post_tutorial_prompt_decision(request: Request):
         return JSONResponse(status_code=400, content={"ok": False, "error": str(exc)})
 
 
+@router.post("/tutorial-prompt/reset")
+async def post_tutorial_prompt_reset(request: Request):
+    """重置主页新手引导状态，供记忆浏览的手动重置入口调用。"""
+    validation_error = _validate_local_mutation_request(request)
+    if validation_error is not None:
+        return validation_error
+
+    return reset_tutorial_prompt_state(config_manager=get_config_manager())
+
+
 @router.get("/autostart-prompt/state")
 async def get_autostart_prompt_state():
     """返回开机自启动提示状态快照。"""

static/app-tutorial-prompt.js

@@ -871,6 +871,34 @@
         return state.tutorialRunToken;
     }
 
+    async function persistHomeTutorialCompletion(event, flowStep, persistedStep) {
+        const source = event.detail.source || 'manual';
+        const tutorialRunToken = await waitForTutorialRunToken(2000);
+        logFlow(flowStep, {
+            source: source,
+            promptToken: shortPromptToken(state.promptDrivenTutorialToken),
+            tutorialRunToken: shortTutorialRunToken(tutorialRunToken),
+        });
+
+        if (!tutorialRunToken) {
+            logFlow(`${flowStep}-skipped`, {
+                source: source,
+                reason: 'missing_run_token',
+            });
+            state.promptDrivenTutorialToken = null;
+            return;
+        }
+
+        await persistTutorialLifecycle('/api/tutorial-prompt/tutorial-completed', {
+            page: 'home',
+            source: source,
+            tutorial_run_token: tutorialRunToken,
+        }, persistedStep, {
+            clearRunTokenOnSuccess: true,
+        });
+        state.promptDrivenTutorialToken = null;
+    }
+
     function takeHeartbeatSnapshot() {
         const snapshot = {
             foregroundMsDelta: consumeForegroundDelta(),
@@ -1334,31 +1362,11 @@
             endHomeTutorialFeatureSuppression('tutorial-completed');
             emitHomeTutorialLockIfChanged('tutorial-completed');
             void (async function () {
-                const source = event.detail.source || 'manual';
-                const tutorialRunToken = await waitForTutorialRunToken(2000);
-                logFlow('tutorial-completed', {
-                    source: source,
-                    promptToken: shortPromptToken(state.promptDrivenTutorialToken),
-                    tutorialRunToken: shortTutorialRunToken(tutorialRunToken),
-                });
-
-                if (!tutorialRunToken) {
-                    logFlow('tutorial-completed-skipped', {
-                        source: source,
-                        reason: 'missing_run_token',
-                    });
-                    state.promptDrivenTutorialToken = null;
-                    return;
-                }
-
-                await persistTutorialLifecycle('/api/tutorial-prompt/tutorial-completed', {
-                    page: 'home',
-                    source: source,
-                    tutorial_run_token: tutorialRunToken,
-                }, 'tutorial-completed-persisted', {
-                    clearRunTokenOnSuccess: true,
-                });
-                state.promptDrivenTutorialToken = null;
+                await persistHomeTutorialCompletion(
+                    event,
+                    'tutorial-completed',
+                    'tutorial-completed-persisted'
+                );
             })();
             scheduleFastHeartbeat();
         });
@@ -1416,8 +1424,19 @@
             }
             state.tutorialRunning = false;
             state.tutorialStartRequested = false;
+            state.tutorialStarted = true;
+            state.homeTutorialCompleted = true;
+            markHomeTutorialStorageSeen();
             endHomeTutorialFeatureSuppression('tutorial-skipped');
             emitHomeTutorialLockIfChanged('tutorial-skipped');
+            void (async function () {
+                await persistHomeTutorialCompletion(
+                    event,
+                    'tutorial-skipped',
+                    'tutorial-skipped-persisted'
+                );
+            })();
+            scheduleFastHeartbeat();
         });
 
         // Keep this recovery bridge paired with handlePromptAcceptance:

static/js/character_personality_onboarding.js

@@ -239,6 +239,7 @@
                 const cleanup = () => {
                     window.removeEventListener('neko:tutorial-completed', handleCompleted);
                     window.removeEventListener('neko:tutorial-skipped', handleSkipped);
+                    window.removeEventListener('neko:tutorial-ended-without-completion', handleEndedWithoutCompletion);
                 };
                 const finish = () => {
                     if (settled) {
@@ -250,8 +251,10 @@
                 };
                 const handleCompleted = () => finish();
                 const handleSkipped = () => finish();
+                const handleEndedWithoutCompletion = () => finish();
                 window.addEventListener('neko:tutorial-completed', handleCompleted, { once: true });
                 window.addEventListener('neko:tutorial-skipped', handleSkipped, { once: true });
+                window.addEventListener('neko:tutorial-ended-without-completion', handleEndedWithoutCompletion, { once: true });
             });
         }
 

static/universal-tutorial-manager.js

@@ -29,6 +29,61 @@ function logTutorialPromptFlow(step, details = {}) {
     console.log(TUTORIAL_PROMPT_FLOW_PREFIX + ' ' + step, details);
 }
 
+async function getTutorialMutationHeaders() {
+    const headers = { 'Content-Type': 'application/json' };
+    const helper = window.nekoLocalMutationSecurity;
+    if (helper && typeof helper.getMutationHeaders === 'function') {
+        try {
+            return Object.assign(headers, await helper.getMutationHeaders());
+        } catch (error) {
+            console.warn('[Tutorial] 获取本地写入安全头失败，尝试直接读取页面配置:', error);
+        }
+    }
+
+    try {
+        const response = await fetch('/api/config/page_config', { cache: 'no-store' });
+        if (!response.ok) {
+            return headers;
+        }
+        const data = await response.json();
+        if (data && typeof data.autostart_csrf_token === 'string' && data.autostart_csrf_token) {
+            headers['X-CSRF-Token'] = data.autostart_csrf_token;
+        }
+    } catch (error) {
+        console.warn('[Tutorial] 读取页面配置失败，继续使用基础请求头:', error);
+    }
+    return headers;
+}
+
+async function postTutorialPromptReset(reason) {
+    const body = JSON.stringify({ reason });
+    const sendResetRequest = async () => fetch('/api/tutorial-prompt/reset', {
+        method: 'POST',
+        headers: await getTutorialMutationHeaders(),
+        body,
+    });
+
+    let response = await sendResetRequest();
+    if (response.status === 403 && window.nekoLocalMutationSecurity &&
+        typeof window.nekoLocalMutationSecurity.refreshToken === 'function') {
+        let shouldRetry = false;
+        try {
+            const payload = await response.clone().json();
+            shouldRetry = payload && payload.error_code === 'csrf_validation_failed';
+        } catch (_) {
+            shouldRetry = false;
+        }
+        if (shouldRetry) {
+            await window.nekoLocalMutationSecurity.refreshToken();
+            response = await sendResetRequest();
+        }
+    }
+    if (!response.ok) {
+        throw new Error(`tutorial prompt reset failed: ${response.status}`);
+    }
+    return response.json();
+}
+
 window.getTutorialStorageKeyForPage = getTutorialStorageKeyForPage;
 window.getTutorialManualIntentKeyForPage = getTutorialManualIntentKeyForPage;
 window.logTutorialPromptFlow = logTutorialPromptFlow;
@@ -4735,6 +4790,24 @@ class UniversalTutorialManager {
 
         this._teardownTutorialUI();
 
+        if (endMeta.reason === 'destroy') {
+            window.dispatchEvent(new CustomEvent('neko:tutorial-ended-without-completion', {
+                detail: {
+                    page: this.currentPage,
+                    source: completedSource,
+                    reason: endMeta.rawReason
+                }
+            }));
+            this.logPromptFlow('tutorial-ended-without-completion', {
+                page: this.currentPage,
+                source: completedSource,
+                reason: endMeta.reason,
+                rawReason: endMeta.rawReason
+            });
+            console.log('[Tutorial] 引导未完成即结束，页面:', this.currentPage, 'reason:', endMeta.rawReason);
+            return;
+        }
+
         // 标记用户已看过该页面的引导
         const storageKey = this.getStorageKey();
         localStorage.setItem(storageKey, 'true');
@@ -4744,6 +4817,24 @@ class UniversalTutorialManager {
             console.log('[Tutorial] 已标记模型管理通用步骤为已看过');
         }
 
+        if (endMeta.reason === 'skip') {
+            window.dispatchEvent(new CustomEvent('neko:tutorial-skipped', {
+                detail: {
+                    page: this.currentPage,
+                    source: completedSource,
+                    reason: endMeta.rawReason
+                }
+            }));
+            this.logPromptFlow('tutorial-skipped', {
+                page: this.currentPage,
+                source: completedSource,
+                reason: endMeta.reason,
+                rawReason: endMeta.rawReason
+            });
+            console.log('[Tutorial] 引导已跳过并标记看过，页面:', this.currentPage);
+            return;
+        }
+
         window.dispatchEvent(new CustomEvent('neko:tutorial-completed', {
             detail: {
                 page: this.currentPage,
@@ -5145,7 +5236,12 @@ class UniversalTutorialManager {
     /** 
      * 重置所有页面的引导状态 
      */ 
-    resetAllTutorials() {
+    async resetHomeTutorialPromptState(reason = 'manual_home_tutorial_reset') {
+        return postTutorialPromptReset(reason);
+    }
+
+    async resetAllTutorials() {
+        await this.resetHomeTutorialPromptState('manual_all_tutorial_reset');
         TUTORIAL_PAGES.forEach(page => {
             this.getStorageKeysForPage(page).forEach(key => localStorage.removeItem(key));
         });
@@ -5157,12 +5253,16 @@ class UniversalTutorialManager {
     /**
      * 重置指定页面的引导状态
      */
-    resetPageTutorial(pageKey) {
+    async resetPageTutorial(pageKey) {
         if (pageKey === 'all') {
-            this.resetAllTutorials();
+            await this.resetAllTutorials();
             return;
         }
 
+        if (pageKey === 'home') {
+            await this.resetHomeTutorialPromptState('manual_home_tutorial_reset');
+        }
+
         this.getStorageKeysForPage(pageKey).forEach((storageKey) => {
             const oldVal = localStorage.getItem(storageKey);
             localStorage.removeItem(storageKey);
@@ -5295,11 +5395,12 @@ async function initUniversalTutorialManager() {
  * 全局函数：重置所有引导
  * 供 HTML 按钮调用
  */
-function resetAllTutorials() {
+async function resetAllTutorials() {
     if (window.universalTutorialManager) {
-        window.universalTutorialManager.resetAllTutorials();
+        await window.universalTutorialManager.resetAllTutorials();
     } else {
         // 如果管理器未初始化，直接清除 localStorage
+        await postTutorialPromptReset('manual_all_tutorial_reset');
         TUTORIAL_PAGES.forEach(page => { localStorage.removeItem(getTutorialStorageKeyForPage(page)); });
         localStorage.setItem(getTutorialManualIntentKeyForPage('home'), 'true');
     }
@@ -5310,12 +5411,12 @@ function resetAllTutorials() {
  * 全局函数：重置指定页面的引导
  * 供下拉菜单调用
  */
-function resetTutorialForPage(pageKey) {
+async function resetTutorialForPage(pageKey) {
     if (!pageKey) return;
     console.log('%c[Tutorial] resetTutorialForPage 被调用, pageKey:', 'color: red; font-weight: bold', pageKey);
 
     if (pageKey === 'all') {
-        resetAllTutorials();
+        await resetAllTutorials();
         return;
     }
 
@@ -5351,8 +5452,11 @@ function resetTutorialForPage(pageKey) {
     }
 
     if (window.universalTutorialManager) {
-        window.universalTutorialManager.resetPageTutorial(pageKey);
+        await window.universalTutorialManager.resetPageTutorial(pageKey);
     } else {
+        if (pageKey === 'home') {
+            await postTutorialPromptReset('manual_home_tutorial_reset');
+        }
         if (pageKey === 'model_manager') {
             localStorage.removeItem(getTutorialStorageKeyForPage('model_manager'));
             localStorage.removeItem(getTutorialStorageKeyForPage('model_manager_live2d'));