feat(mcp): 学习记忆接口闭环——应用内授权开关与世界快照跨进程桥

- memoryServerConsent.ts：设置页授权开关IPC（读写memory-server-consent标记文件，标记仍是唯一事实源），main/preload白名单接线
- MemoryServerSection：数据与存储页授权卡片，开启前披露将被读取的记忆清单，关闭即撤销
- world_snapshots表（schema v7）+白名单登记：渲染进程retention数据→sqlite的跨进程桥
- useWorldSnapshotSync：订阅珊瑚/发现store，防抖2s upsert快照行（失败静默）
- memoryQueries：discoveries/world_state优先读快照精确态，无则回退派生值并标注provenance

Author: Aparencia

client/electron/db/dbIpcHandlers.ts

@@ -34,6 +34,8 @@ const ALLOWED_TABLES = new Set([
   'assistant_messages',
   // assistant_triggers — AI 助手触发规则记录
   'assistant_triggers',
+  // world_snapshots — 世界状态快照（渲染进程 retention 数据→MCP 记忆服务器跨进程桥）
+  'world_snapshots',
   // crdt_docs — CRDT 同步引擎文档快照（v3 迁移新增）
   'crdt_docs',
   // crdt_changes — CRDT 同步引擎变更日志（v3 迁移新增）

client/electron/db/schema.ts

@@ -6,7 +6,7 @@
  */
 import type Database from 'better-sqlite3';
 
-export const SCHEMA_VERSION = 6;
+export const SCHEMA_VERSION = 7;
 
 export const SCHEMA_DDL = /* sql */ `
 CREATE TABLE IF NOT EXISTS pomodoro_sessions (
@@ -189,6 +189,10 @@ CREATE TABLE IF NOT EXISTS implementation_intentions (
   created_at TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS idx_impl_intention_status ON implementation_intentions(status, trigger_at);
+-- v7：世界状态快照（渲染进程 retention 数据→主进程 sqlite→MCP 记忆服务器的跨进程桥）
+CREATE TABLE IF NOT EXISTS world_snapshots (
+  id TEXT PRIMARY KEY, payload TEXT NOT NULL DEFAULT '{}', updated_at TEXT NOT NULL
+);
 `;
 
 /** v3 迁移 DDL：CRDT 同步引擎元数据表（条件执行） */
@@ -246,5 +250,8 @@ export function initializeSchema(db: Database.Database): void {
   // v6 迁移：A4 实施意图表 implementation_intentions
   // 表 DDL 已包含在 SCHEMA_DDL 中（CREATE IF NOT EXISTS 幂等），此处无需额外操作
 
+  // v7 迁移：世界状态快照表 world_snapshots
+  // 表 DDL 已包含在 SCHEMA_DDL 中（CREATE IF NOT EXISTS 幂等），此处无需额外操作
+
   db.pragma(`user_version = ${SCHEMA_VERSION}`);
 }

client/electron/main.ts

@@ -27,6 +27,7 @@ import { createMainWindow, saveCloseChoice, completeSyncBeforeQuit } from './win
 import { destroyTray } from './trayManager.js';
 import { registerCaptureHandlers, disposeCaptureHandlers } from './captureHandlers.js';
 import { mcpManager } from './mcpManager.js';
+import { registerMemoryServerConsentHandlers } from './memoryServerConsent.js';
 import { initialize, close as closeDb } from './db/sqliteService.js';
 import { initializeSchema } from './db/schema.js';
 import { initializeFTS, rebuildIndex, collectIndexableData } from './db/fts5Search.js';
@@ -172,6 +173,8 @@ if (!gotTheLock) {
     // 数据访问与存储/备份 IPC（详见 db/dbIpcHandlers.ts、storageIpcHandlers.ts）
     registerDbIpcHandlers();
     registerStorageIpcHandlers();
+    // MCP 学习记忆服务器应用内授权开关（详见 memoryServerConsent.ts）
+    registerMemoryServerConsentHandlers();
     // 课堂关键帧图片持久化 IPC + keyframe:// 协议（详见 ipc/keyframeStorage.ts）
     registerKeyframeIpcHandlers();
 

client/electron/mcp/memoryQueries.ts

@@ -148,12 +148,36 @@ export function queryStreak(db: Database.Database): Record<string, unknown> {
   };
 }
 
-/** learning_memory.discoveries — 深海发现（当前存于客户端 IndexedDB，sqlite 未接线） */
-export function queryDiscoveries(): Record<string, unknown> {
+/** 读取渲染进程同步过来的世界快照（useWorldSnapshotSync 写入，无则 null） */
+function readWorldSnapshot(db: Database.Database): {
+  corals?: { total: number; healthy: number; bleached: number; totalDepth: number };
+  discoveries?: { count: number };
+  capturedAt?: string;
+} | null {
+  try {
+    const row = db.prepare("SELECT payload FROM world_snapshots WHERE id = 'latest'").get() as
+      { payload: string } | undefined;
+    if (!row) return null;
+    return JSON.parse(row.payload);
+  } catch {
+    return null;
+  }
+}
+
+/** learning_memory.discoveries — 深海发现（优先读世界快照，无则占位） */
+export function queryDiscoveries(db: Database.Database): Record<string, unknown> {
+  const snap = readWorldSnapshot(db);
+  if (!snap?.discoveries) {
+    return {
+      count: null,
+      items: [],
+      note: '尚未获取到发现图鉴快照（应用启动并产生发现后自动同步）',
+    };
+  }
   return {
-    count: null,
-    items: [],
-    note: '发现图鉴暂存于客户端本地存储，跨进程接线将在后续批次完成',
+    count: snap.discoveries.count,
+    capturedAt: snap.capturedAt ?? null,
+    note: '图鉴明细存于客户端本地，此处为累计数量快照',
   };
 }
 
@@ -185,11 +209,12 @@ export function queryRecentSessions(db: Database.Database, limitRaw: unknown): R
 }
 
 /**
- * learning_memory.world_state — 世界状态快照（sqlite 派生版）
- * @ai-context 珊瑚/发现实体存于渲染进程 IndexedDB，此处以 sqlite 过程数据
- * 派生近似信号并显式标注 provenance，避免误导消费方。
+ * learning_memory.world_state — 世界状态快照
+ * @ai-context 优先消费渲染进程同步的精确快照（珊瑚健康度→雾与活力）；
+ * 无快照时回退 sqlite 过程数据派生值并显式标注 provenance。
  */
 export function queryWorldState(db: Database.Database): Record<string, unknown> {
+  const snap = readWorldSnapshot(db);
   const focus = db.prepare(`
     SELECT COALESCE(SUM(actual_duration), 0) AS totalSeconds FROM pomodoro_sessions WHERE interrupted = 0
   `).get() as { totalSeconds: number };
@@ -198,11 +223,31 @@ export function queryWorldState(db: Database.Database): Record<string, unknown>
   ).get() as { n: number }).n;
   const totalCards = (db.prepare('SELECT COUNT(*) AS n FROM flashcards').get() as { n: number }).n;
 
-  return {
+  const base = {
     depthMeters: Math.round(focus.totalSeconds / 60),
     depthNote: '以专注分钟折算的潜航深度（1 分钟 ≈ 1 米）',
     hazyShare: totalCards > 0 ? Math.round((due / totalCards) * 100) / 100 : 0,
     hazyNote: '朦胧知识占比（0-1）——雾的浓度，复习即拨开',
-    provenance: '由主库过程数据派生；珊瑚/发现等世界实体的精确状态以后续批次为准',
+  };
+
+  if (snap?.corals) {
+    const { total, healthy, bleached, totalDepth } = snap.corals;
+    return {
+      ...base,
+      ecosystem: {
+        coralTotal: total,
+        coralHealthy: healthy,
+        coralBleached: bleached,
+        vitality: total > 0 ? Math.round((healthy / total) * 100) / 100 : null,
+        accumulatedDepthMeters: totalDepth,
+      },
+      capturedAt: snap.capturedAt ?? null,
+      provenance: '珊瑚生态来自渲染进程同步快照（精确态）；潜航深度与朦胧占比由主库派生',
+    };
+  }
+
+  return {
+    ...base,
+    provenance: '由主库过程数据派生；珊瑚精确态待应用启动后同步',
   };
 }

client/electron/mcpMemoryServer.ts

@@ -141,7 +141,7 @@ async function main(): Promise<void> {
     discoveries: {
       description: '深海发现图鉴（跨进程接线建设中，当前返回占位）',
       inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-      run: () => queryDiscoveries(),
+      run: () => queryDiscoveries(db),
     },
     recent_sessions: {
       description: '最近学习会话摘要（深潜与费曼）',

client/electron/memoryServerConsent.ts

@@ -0,0 +1,54 @@
+/**
+ * MCP 学习记忆服务器 · 应用内授权开关
+ * MCP learning-memory server · in-app consent toggle
+ *
+ * @ai-context: 宪法 P2 内层防御的授权面：此前授权依赖手动创建
+ * memory-server-consent 标记文件，本模块把开关搬进应用设置页。
+ * 标记文件仍是唯一事实源（mcpMemoryServer 独立进程只认它），
+ * 本模块仅负责读写该文件——双端语义天然一致。
+ *
+ * @ai-context: In-app consent toggle for the memory server. The marker file
+ * remains the single source of truth; this module only reads/writes it.
+ */
+import { app, ipcMain } from 'electron';
+import * as path from 'path';
+import * as fs from 'fs';
+import { logger } from './logger.js';
+
+const CONSENT_MARKER = 'memory-server-consent';
+
+function markerPath(): string {
+  return path.join(app.getPath('userData'), CONSENT_MARKER);
+}
+
+export function registerMemoryServerConsentHandlers(): void {
+  ipcMain.handle('memory_server:get_consent', () => {
+    try {
+      return fs.existsSync(markerPath());
+    } catch {
+      return false;
+    }
+  });
+
+  ipcMain.handle('memory_server:set_consent', (_event, enabled: unknown) => {
+    try {
+      const p = markerPath();
+      if (enabled === true) {
+        fs.writeFileSync(
+          p,
+          `用户于 ${new Date().toISOString()} 在应用设置页显式开启学习记忆接口\n`,
+          'utf-8',
+        );
+        logger.info('[MemoryServer] consent granted via settings');
+      } else {
+        fs.rmSync(p, { force: true });
+        logger.info('[MemoryServer] consent revoked via settings');
+      }
+      return { success: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error('[MemoryServer] consent toggle failed:', message);
+      return { success: false, error: message };
+    }
+  });
+}

client/electron/preload.ts

@@ -120,6 +120,9 @@ const ALLOWED_CHANNELS = [
   'local_asr_stream_available',
   'local_asr_stream_start',
   'local_asr_stream_stop',
+  // MCP 学习记忆服务器应用内授权开关
+  'memory_server:get_consent',
+  'memory_server:set_consent',
 ] as const;
 
 /** 允许渲染进程监听的事件 channel 白名单（主进程 → 渲染进程推送） */

client/src/features/retention/hooks/useWorldSnapshotSync.ts

@@ -0,0 +1,62 @@
+/**
+ * 世界状态快照同步 Hook（宪法 P2 · discoveries/world_state 跨进程接线）
+ * World snapshot sync hook (cross-process bridge to the MCP memory server)
+ *
+ * @ai-context: 珊瑚/发现数据存于渲染进程 IndexedDB，MCP 记忆服务器读主进程
+ * sqlite——本 hook 是两者间的单向桥：订阅 retention store 变化，防抖 2s 后
+ * 把摘要快照 upsert 到 world_snapshots 表（单行 id='latest'）。
+ * 失败静默（快照是增强项，不影响主流程）。
+ *
+ * @ai-context: One-way bridge from renderer retention stores to the
+ * world_snapshots sqlite row consumed by the MCP memory server.
+ */
+import { useEffect, useRef } from 'react';
+import { useEcosystemStore } from '../store/useEcosystemStore';
+import { useDiscoveryStore } from '../store/useDiscoveryStore';
+
+const SNAPSHOT_ID = 'latest';
+const DEBOUNCE_MS = 2000;
+
+export function useWorldSnapshotSync(): void {
+  const corals = useEcosystemStore((s) => s.corals);
+  const totalDepth = useEcosystemStore((s) => s.totalDepth);
+  const discoveriesCount = useDiscoveryStore((s) => s.totalCount);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!window.electronAPI?.db) return;
+
+    const write = async () => {
+      const healthy = corals.filter((c) => c.health === 'healthy').length;
+      const payload = JSON.stringify({
+        corals: {
+          total: corals.length,
+          healthy,
+          bleached: corals.length - healthy,
+          totalDepth,
+        },
+        discoveries: { count: discoveriesCount },
+        capturedAt: new Date().toISOString(),
+      });
+      const row = { id: SNAPSHOT_ID, payload, updated_at: new Date().toISOString() };
+      try {
+        // 先查后写实现 upsert（db 桥无 put 语义）
+        const existing = await window.electronAPI.db.query('worldSnapshots', 'get', [SNAPSHOT_ID]);
+        if (existing) {
+          await window.electronAPI.db.update('worldSnapshots', SNAPSHOT_ID, {
+            payload, updated_at: row.updated_at,
+          });
+        } else {
+          await window.electronAPI.db.insert('worldSnapshots', row);
+        }
+      } catch { /* 快照失败静默降级 */ }
+    };
+
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => { void write(); }, DEBOUNCE_MS);
+  }, [corals, totalDepth, discoveriesCount]);
+
+  useEffect(() => () => {
+    if (timer.current) clearTimeout(timer.current);
+  }, []);
+}

client/src/pages/settings/DataSettings.tsx

@@ -11,13 +11,15 @@ import { StoragePathSection } from './StoragePathSection';
 import { ImportExportSection } from './ImportExportSection';
 import { EncryptedBackupSection } from './EncryptedBackupSection';
 import { ClearDataSection } from './ClearDataSection';
+import { MemoryServerSection } from './MemoryServerSection';
 
 export default function DataSettings() {
   return (
     <Card padding="md" className="flex flex-col gap-kb-md">
       <h2 className="text-b1 font-semibold text-text-primary">数据与存储</h2>
 
       <StoragePathSection />
+      <MemoryServerSection />
       <ImportExportSection />
       <EncryptedBackupSection />
       <ClearDataSection />