feat(analytics): track suggestion refresh and acceptance events

- Add a AGENTS.md for faster vibe coding
- 数据埋点测试

Author: hhh2210

desktop/AGENTS.md

@@ -0,0 +1,38 @@
+# Repository Guidelines
+For vibe-coding models
+## Project Structure & Module Organization
+- `src/main.js` is the Electron main process entry; preload lives in `src/preload.js` and core modules in `src/core/`.
+- Renderer UI is React under `src/renderer/` (pages, components, styles).
+- ASR and audio tooling live in `src/asr/` and `src/native/` (native system audio capture).
+- Python-related assets and backends live in `python-env/`, `python-bootstrap/`, and `backend/`.
+- Build outputs go to `dist/` (renderer) and `release/` (packaged apps).
+- Helper scripts are in `scripts/` (dev, build, model download, test utilities).
+
+## Build, Test, and Development Commands
+- `pnpm install` installs dependencies and runs `postinstall` (rebuilds `better-sqlite3`).
+- `pnpm dev` starts the full desktop dev flow (Electron + Vite).
+- `pnpm run prepare:python` prepares the local ASR Python environment (`PREPARE_PYTHON_MODE=bundle` for portable builds).
+- `pnpm run build` runs prebuild + Vite build + Electron Builder packaging.
+- `pnpm run build:mac` / `pnpm run build:win` build platform-specific installers.
+- `pnpm run preview` serves the built renderer for inspection.
+
+## Coding Style & Naming Conventions
+- JavaScript/TypeScript uses ESM imports, semicolons, and 2-space indentation; follow existing file style.
+- React components are PascalCase (`CharacterModal.jsx`), utilities/modules are kebab or camel case (`asr-cache-env.js`).
+- Keep Electron main/preload logic in `src/` and avoid mixing UI concerns into main process modules.
+
+## Testing Guidelines
+- Automated tests are mostly script-driven: `pnpm run test:asr`, `pnpm run test:settings-logs`, `pnpm run test:audio`.
+- Additional utilities live in `scripts/test-*.{js,py}`; run them directly when validating audio/ASR flows.
+- Name new tests with clear `test-` prefixes and document any required hardware or model downloads.
+
+## Commit & Pull Request Guidelines
+- Commit messages generally follow Conventional Commits (`feat(scope):`, `fix(scope):`, `refactor(scope):`). Use a short, scoped summary.
+- Git history shows these common types/scopes: `feat`, `fix`, `refactor`, `chore`, `security` with scopes like `main`, `ci`, `python-env`, `asr`, `ui`, `docs`, `review`, `prompt`, `tests`.
+- Messages may be bilingual (English/中文); keep them concise and consistent with existing history.
+- PRs should describe user-facing behavior changes, note platform impact (macOS/Windows), and include screenshots/GIFs for UI updates.
+- If the change touches ASR or model caches, mention any new env vars or migration steps.
+
+## Configuration & Security Notes
+- Local ASR caches can be redirected via `ASR_CACHE_BASE`; keep sensitive paths out of logs.
+- Avoid widening IPC surface area without validation (see `src/core/modules/`).

desktop/src/preload.js

@@ -183,6 +183,7 @@ contextBridge.exposeInMainWorld('electronAPI', {
   // Memory Service (结构化画像/事件)
   memoryQueryProfiles: (payload) => ipcRenderer.invoke('memory-query-profiles', payload),
   memoryQueryEvents: (payload) => ipcRenderer.invoke('memory-query-events', payload),
+  memoryUpsertEvent: (payload) => ipcRenderer.invoke('memory-upsert-event', payload),
   onSuggestionStreamStart: (callback) => {
     const listener = (event, data) => callback(data);
     ipcRenderer.on('llm-suggestion-stream-start', listener);

desktop/src/renderer/hooks/useSuggestions.js

@@ -72,7 +72,7 @@ export const useSuggestions = (sessionInfo) => {
     } catch (err) {
       console.error('加载建议配置失败：', err);
     }
-  }, []);
+  }, [sessionInfo]);
 
   const updateSuggestionConfig = useCallback(async (updates = {}) => {
     try {
@@ -108,11 +108,11 @@ export const useSuggestions = (sessionInfo) => {
   const resetStreamState = useCallback((reason = 'unknown') => {
     console.log(`[useSuggestions] resetStreamState called (reason: ${reason}). Clearing active stream:`, activeStreamRef.current);
     activeStreamRef.current = { id: null, trigger: null, reason: null };
-  }, []);
+  }, [sessionInfo]);
 
   const logStreamCharacters = useCallback(() => {
     // Disabled: per-character logging is extremely noisy and can stall the renderer.
-  }, []);
+  }, [sessionInfo]);
 
   const startSuggestionStream = useCallback(
     ({ trigger, reason }) => {
@@ -163,6 +163,50 @@ export const useSuggestions = (sessionInfo) => {
     [sessionInfo, suggestionConfig, suggestions]
   );
 
+  const recordSuggestionSignal = useCallback(
+    ({ trigger, reason }) => {
+      if (trigger !== 'manual') return;
+      const api = window.electronAPI;
+      if (!api?.memoryUpsertEvent) return;
+
+      const action = reason === 'refresh' ? 'refresh' : 'manual_generate';
+      const userIdRaw =
+        sessionInfo?.userId ??
+        sessionInfo?.user_id ??
+        sessionInfo?.conversationId ??
+        'local-user';
+      const projectIdRaw =
+        sessionInfo?.projectId ??
+        sessionInfo?.project_id ??
+        sessionInfo?.characterId ??
+        null;
+      const payload = {
+        user_id: String(userIdRaw),
+        event_tip: action === 'refresh' ? '用户刷新建议' : '用户手动生成建议',
+        event_tags: ['suggestion', 'user_feedback', action],
+        profile_delta: {
+          action,
+          trigger,
+          reason,
+          conversation_id: sessionInfo?.conversationId || null,
+          character_id: sessionInfo?.characterId || null,
+          suggestion_count: suggestionConfig?.suggestion_count ?? null,
+          context_message_limit: suggestionConfig?.context_message_limit ?? null,
+          existing_suggestions: Array.isArray(suggestions) ? suggestions.length : 0
+        },
+        timestamp: Date.now()
+      };
+      if (projectIdRaw) {
+        payload.project_id = String(projectIdRaw);
+      }
+
+      api.memoryUpsertEvent(payload).catch((error) => {
+        console.warn('[useSuggestions] memoryUpsertEvent failed', error);
+      });
+    },
+    [sessionInfo, suggestionConfig, suggestions]
+  );
+
   /**
    * 生成建议
    */
@@ -183,6 +227,8 @@ export const useSuggestions = (sessionInfo) => {
         return;
       }
 
+      recordSuggestionSignal({ trigger, reason });
+
       if (window.electronAPI?.startSuggestionStream) {
         startSuggestionStream({ trigger, reason });
         return;
@@ -234,7 +280,14 @@ export const useSuggestions = (sessionInfo) => {
         setSuggestionStatus('idle');
       }
     },
-    [sessionInfo, suggestionConfig, suggestionStatus, startSuggestionStream, suggestions]
+    [
+      sessionInfo,
+      suggestionConfig,
+      suggestionStatus,
+      startSuggestionStream,
+      suggestions,
+      recordSuggestionSignal
+    ]
   );
 
   /**
@@ -259,7 +312,7 @@ export const useSuggestions = (sessionInfo) => {
     } catch (err) {
       console.error('复制建议失败：', err);
     }
-  }, []);
+  }, [sessionInfo]);
 
   /**
    * 显式确认“采用了哪个建议”（写入 DB，并在当前 UI 内高亮）
@@ -279,6 +332,44 @@ export const useSuggestions = (sessionInfo) => {
       });
       if (!ok) return false;
 
+      if (selected) {
+        const api = window.electronAPI;
+        if (api?.memoryUpsertEvent) {
+          const userIdRaw =
+            sessionInfo?.userId ??
+            sessionInfo?.user_id ??
+            sessionInfo?.conversationId ??
+            'local-user';
+          const projectIdRaw =
+            sessionInfo?.projectId ??
+            sessionInfo?.project_id ??
+            sessionInfo?.characterId ??
+            null;
+          const payload = {
+            user_id: String(userIdRaw),
+            event_tip: '用户采用建议',
+            event_tags: ['suggestion', 'user_feedback', 'accept'],
+            profile_delta: {
+              action: 'accept',
+              suggestion_id: suggestion.id,
+              suggestion_index: suggestion.suggestion_index ?? suggestion.index ?? null,
+              decision_point_id: suggestion.decision_point_id ?? null,
+              batch_id: suggestion.batch_id ?? null,
+              conversation_id: sessionInfo?.conversationId || null,
+              character_id: sessionInfo?.characterId || null
+            },
+            timestamp: Date.now()
+          };
+          if (projectIdRaw) {
+            payload.project_id = String(projectIdRaw);
+          }
+
+          api.memoryUpsertEvent(payload).catch((error) => {
+            console.warn('[useSuggestions] memoryUpsertEvent failed', error);
+          });
+        }
+      }
+
       // UI 侧按 batch_id（优先）互斥，保持与 DB 一致
       const scopeBatchId = suggestion.batch_id || null;
       const scopeDecisionPointId = suggestion.decision_point_id || null;
@@ -300,7 +391,7 @@ export const useSuggestions = (sessionInfo) => {
       console.error('[useSuggestions] Failed to select suggestion:', err);
       return false;
     }
-  }, []);
+  }, [sessionInfo]);
 
   /**
    * 情景判定（冷场/连发统一交由 LLM 评估）