feat(mcp): 知识图谱 MCP 工具与应用内演示剧本——learning_memory.knowledge_graph+三步引导+访问审计+快照事件同步（阶段C）

Author: Aparencia

client/electron/mcp/memoryQueries.ts

@@ -181,6 +181,53 @@ export function queryDiscoveries(db: Database.Database): Record<string, unknown>
   };
 }
 
+/** learning_memory.knowledge_graph — 知识图谱摘要（节点档位 + 关联数，无卡片背面原文） */
+export function queryKnowledgeGraph(db: Database.Database, limitRaw: unknown): Record<string, unknown> {
+  const limit = clampLimit(limitRaw);
+
+  // 节点一：概念卡（摘要级：concept 截断 60 字 + 掌握档位 + 同源簇大小）
+  const cards = db.prepare(`
+    SELECT id, front, ease_factor, "interval", source_ref
+    FROM flashcards ORDER BY updated_at DESC LIMIT ?
+  `).all(limit) as Array<{
+    id: string; front: string; ease_factor: number; interval: number; source_ref: string | null;
+  }>;
+  const refRows = db.prepare(`
+    SELECT source_ref, COUNT(*) AS n FROM flashcards
+    WHERE source_ref IS NOT NULL AND source_ref != '' GROUP BY source_ref
+  `).all() as Array<{ source_ref: string; n: number }>;
+  const refSize = new Map(refRows.map((r) => [r.source_ref, r.n]));
+
+  // 节点二：费曼薄弱点（in_progress，关联卡片数 = 概念精确匹配）
+  const feynman = db.prepare(`
+    SELECT f.id, f.concept,
+      (SELECT COUNT(*) FROM flashcards c WHERE c.front = f.concept) AS linkedCards
+    FROM feynman_notes f WHERE f.status = 'in_progress'
+    ORDER BY f.updated_at DESC LIMIT ?
+  `).all(limit) as Array<{ id: string; concept: string; linkedCards: number }>;
+
+  const nodes: Array<Record<string, unknown>> = [
+    ...cards.map((c) => ({
+      id: `card:${c.id}`,
+      concept: c.front.slice(0, 60),
+      tier: hazeTier(c.ease_factor, c.interval),
+      sourceLinks: c.source_ref ? (refSize.get(c.source_ref) ?? 1) : 0,
+    })),
+    ...feynman.map((f) => ({
+      id: `feynman:${f.id}`,
+      concept: f.concept.slice(0, 60),
+      tier: '成长中',
+      weakLinks: f.linkedCards,
+    })),
+  ];
+
+  return {
+    total: nodes.length,
+    nodes,
+    note: '图谱摘要：概念前 60 字 + 掌握档位 + 关联数；原始数据始终保留在用户本地',
+  };
+}
+
 /** learning_memory.recent_sessions — 最近学习会话摘要 */
 export function queryRecentSessions(db: Database.Database, limitRaw: unknown): Record<string, unknown> {
   const limit = clampLimit(limitRaw);

client/electron/mcpMemoryServer.ts

@@ -93,6 +93,7 @@ async function main(): Promise<void> {
   const {
     queryProfile, queryMastery, queryReviewCandidates, queryFocusStats,
     queryStreak, queryDiscoveries, queryRecentSessions, queryWorldState,
+    queryKnowledgeGraph,
   } = await import('./mcp/memoryQueries.js');
 
   /** 工具表：name → 描述 + JSON Schema + 处理函数（全部只读摘要） */
@@ -139,7 +140,7 @@ async function main(): Promise<void> {
       run: () => queryStreak(db),
     },
     discoveries: {
-      description: '深海发现图鉴（跨进程接线建设中，当前返回占位）',
+      description: '深海发现图鉴：累计发现数量（跨进程快照同步，明细存于客户端本地）',
       inputSchema: { type: 'object', properties: {}, additionalProperties: false },
       run: () => queryDiscoveries(db),
     },
@@ -157,6 +158,15 @@ async function main(): Promise<void> {
       inputSchema: { type: 'object', properties: {}, additionalProperties: false },
       run: () => queryWorldState(db),
     },
+    knowledge_graph: {
+      description: '知识图谱摘要：概念节点（掌握档位+同源关联数）与费曼薄弱点（关联卡片数），无卡片背面原文',
+      inputSchema: {
+        type: 'object',
+        properties: { limit: { type: 'number', description: '返回上限（1-100，默认 20）' } },
+        additionalProperties: false,
+      },
+      run: (a) => queryKnowledgeGraph(db, a.limit),
+    },
   };
 
   // SDK 低层 Server API（避免对传递依赖 zod 的直接引用）

client/electron/memoryServerConsent.ts

@@ -16,11 +16,28 @@ import * as fs from 'fs';
 import { logger } from './logger.js';
 
 const CONSENT_MARKER = 'memory-server-consent';
+const ACCESS_LOG_FILE = 'memory-server-access.log';
+/** 审计列表长度上限（最近 50 条，倒序） */
+const ACCESS_LOG_MAX = 50;
 
 function markerPath(): string {
   return path.join(app.getPath('userData'), CONSENT_MARKER);
 }
 
+/** 读取访问审计日志（最近 50 条，倒序；日志行格式：ISO8601 learning_memory.<tool>） */
+function readAccessLog(): { entries: Array<{ at: string; tool: string }>; total: number } {
+  const p = path.join(app.getPath('userData'), ACCESS_LOG_FILE);
+  if (!fs.existsSync(p)) return { entries: [], total: 0 };
+  const text = fs.readFileSync(p, 'utf-8');
+  const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+  const entries = lines.slice(-ACCESS_LOG_MAX).reverse().map((line) => {
+    const idx = line.indexOf(' ');
+    if (idx <= 0) return { at: line, tool: '' };
+    return { at: line.slice(0, idx), tool: line.slice(idx + 1) };
+  });
+  return { entries, total: lines.length };
+}
+
 export function registerMemoryServerConsentHandlers(): void {
   ipcMain.handle('memory_server:get_consent', () => {
     try {
@@ -51,4 +68,24 @@ export function registerMemoryServerConsentHandlers(): void {
       return { success: false, error: message };
     }
   });
+
+  // 访问审计：谁在何时读过你的记忆（计划 C2：最近 50 条）
+  ipcMain.handle('memory_server:get_access_log', () => {
+    try {
+      return readAccessLog();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error('[MemoryServer] read access log failed:', message);
+      return { entries: [], total: 0, error: message };
+    }
+  });
+
+  // 宿主配置：三步引导第一步「复制配置」的素材（供 Claude Desktop 等粘贴）
+  ipcMain.handle('memory_server:get_host_config', () => {
+    return {
+      command: process.execPath,
+      env: { ELECTRON_RUN_AS_NODE: '1' },
+      args: [path.join(__dirname, 'mcpMemoryServer.js')],
+    };
+  });
 }

client/electron/preload.ts

@@ -125,6 +125,9 @@ const ALLOWED_CHANNELS = [
   // MCP 学习记忆服务器应用内授权开关
   'memory_server:get_consent',
   'memory_server:set_consent',
+  // 阶段 C：访问审计（最近 50 条）+ 宿主配置（三步引导第一步）
+  'memory_server:get_access_log',
+  'memory_server:get_host_config',
   // 知识入籍 IPC channel（阶段 A：PDF 解析/URL 抓取/入籍记录）
   'import:parse-pdf',
   'import:fetch-url',

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

@@ -3,16 +3,20 @@
  * 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'）。
+ * sqlite——本 hook 是两者间的单向桥：数据变化防抖 2s 后把摘要快照 upsert
+ * 到 world_snapshots 表（单行 id='latest'）。阶段 C 新增事件驱动：订阅
+ * useWorldEvents 签名时刻（掌握/创世/入籍，含 knowledge_settled 语义）
+ * 立即同步——AI 在签名时刻后马上读到新世界，不等防抖窗口。
  * 失败静默（快照是增强项，不影响主流程）。
  *
  * @ai-context: One-way bridge from renderer retention stores to the
- * world_snapshots sqlite row consumed by the MCP memory server.
+ * world_snapshots sqlite row. Debounced 2s on data change; immediate on
+ * signature moments (mastery/genesis/settling) via the world event bus.
  */
-import { useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { useEcosystemStore } from '../store/useEcosystemStore';
 import { useDiscoveryStore } from '../store/useDiscoveryStore';
+import { useWorldEvents } from '../store/useWorldEvents';
 
 const SNAPSHOT_ID = 'latest';
 const DEBOUNCE_MS = 2000;
@@ -21,42 +25,54 @@ export function useWorldSnapshotSync(): void {
   const corals = useEcosystemStore((s) => s.corals);
   const totalDepth = useEcosystemStore((s) => s.totalDepth);
   const discoveriesCount = useDiscoveryStore((s) => s.totalCount);
+  // 签名时刻序列号（宪法第三条：掌握/创世/入籍）——事件驱动同步信号
+  const signatureSeq = useWorldEvents((s) => s.signatureSeq);
   const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  useEffect(() => {
+  /** 写快照（幂等 upsert，失败静默）——防抖与事件驱动共用 / Shared upsert */
+  const write = useCallback(async () => {
     if (!window.electronAPI?.db) return;
+    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 桥查询方法白名单为 getAll/getById/count）
+      const existing = await window.electronAPI.db.query('worldSnapshots', 'getById', [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 { /* 快照失败静默降级 */ }
+  }, [corals, totalDepth, discoveriesCount]);
 
-    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 桥查询方法白名单为 getAll/getById/count）
-        const existing = await window.electronAPI.db.query('worldSnapshots', 'getById', [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 { /* 快照失败静默降级 */ }
-    };
-
+  // 数据变化：防抖 2s 后写（批量小变化合并为一次）
+  useEffect(() => {
     if (timer.current) clearTimeout(timer.current);
     timer.current = setTimeout(() => { void write(); }, DEBOUNCE_MS);
-  }, [corals, totalDepth, discoveriesCount]);
+  }, [write]);
 
+  // 事件驱动：签名时刻立即同步（取消挂起防抖，避免重复写）
+  useEffect(() => {
+    if (signatureSeq === 0) return;
+    if (timer.current) clearTimeout(timer.current);
+    void write();
+  }, [signatureSeq, write]);
+
+  // 卸载清理
   useEffect(() => () => {
     if (timer.current) clearTimeout(timer.current);
   }, []);
 }
+