feat(constellation): 知识星座双轨渲染——纯函数派生图谱+DOM/SVG轨与3D轨按性能档切换（阶段B）

Author: Aparencia

client/electron/db/knowledgeQueries.ts

@@ -0,0 +1,101 @@
+/**
+ * 知识图谱查询层 + IPC（knowledge:*，阶段 B 深度问题）
+ * Knowledge graph query layer + IPC (read-only)
+ *
+ * @ai-context: 只读 SELECT 聚合三路数据（flashcards / feynman_notes /
+ * flashcard_reviews），上限复用 MAX_LIMIT=100（粒度上限防整库抽取，
+ * 与 MCP 记忆层同一约束）。不做图谱派生——派生规则在渲染进程
+ * features/constellation/lib/knowledgeGraph.ts 纯函数层（单测覆盖）。
+ * SQL 全部参数绑定；limit 经 clampLimit 封顶；失败抛错由 safeHandle
+ * 的 Result 语义传导给渲染进程（星座是外壳增强项，hook 侧静默降级）。
+ *
+ * @ai-context: Read-only aggregation feeding the renderer's pure graph
+ * derivation layer. Limit is clamped to MAX_LIMIT=100; all SQL is
+ * parameter-bound.
+ */
+import { safeHandle } from '../ipcUtils.js';
+import { logger } from '../logger.js';
+import { getConnection } from './sqliteService.js';
+import { clampLimit } from '../mcp/memoryQueries.js';
+import type { KnowledgeGraphData } from '../../src/features/constellation/types.js';
+
+/** flashcards 行（snake_case，SQLite 边界） / Flashcard row */
+interface CardRow {
+  id: string;
+  front: string;
+  ease_factor: number;
+  interval: number;
+  source_ref: string | null;
+  created_at: string;
+}
+
+/** feynman_notes 行 / Feynman row */
+interface FeynmanRow {
+  id: string;
+  concept: string;
+  status: string;
+}
+
+/** flashcard_reviews 行 / Review row */
+interface ReviewRow {
+  card_id: string;
+  reviewed_at: string;
+}
+
+/**
+ * 聚合三路学习数据（只读，limit 封顶 100）
+ * Aggregate flashcards, in-progress feynman notes and recent reviews.
+ */
+export function queryKnowledgeGraph(limitRaw: unknown): KnowledgeGraphData {
+  const limit = clampLimit(limitRaw);
+  const db = getConnection();
+
+  const cards = db.prepare(`
+    SELECT id, front, ease_factor, "interval", source_ref, created_at
+    FROM flashcards ORDER BY updated_at DESC LIMIT ?
+  `).all(limit) as CardRow[];
+
+  const feynman = db.prepare(`
+    SELECT id, concept, status FROM feynman_notes
+    WHERE status = 'in_progress' ORDER BY updated_at DESC LIMIT ?
+  `).all(limit) as FeynmanRow[];
+
+  // 最近 limit 条复习（纯函数层会再按时间升序取窗口）
+  const reviews = db.prepare(`
+    SELECT card_id, reviewed_at FROM flashcard_reviews
+    ORDER BY reviewed_at DESC LIMIT ?
+  `).all(limit) as ReviewRow[];
+
+  return {
+    cards: cards.map((c) => ({
+      id: c.id,
+      front: c.front,
+      easeFactor: c.ease_factor,
+      interval: c.interval,
+      sourceRef: c.source_ref ?? undefined,
+      createdAt: new Date(c.created_at),
+    })),
+    feynman: feynman.map((f) => ({
+      id: f.id,
+      concept: f.concept,
+      status: f.status as KnowledgeGraphData['feynman'][number]['status'],
+    })),
+    reviews: reviews.map((r) => ({
+      cardId: r.card_id,
+      reviewedAt: new Date(r.reviewed_at),
+    })),
+  };
+}
+
+/** 注册 knowledge:* IPC handlers（app ready 后调用一次） */
+export function registerKnowledgeIpcHandlers(): void {
+  safeHandle('knowledge:get-graph', async () => {
+    try {
+      return queryKnowledgeGraph(undefined);
+    } catch (err) {
+      // 查询失败记日志后向上抛——hook 侧会静默降级，不影响主流程
+      logger.warn(`[knowledge] get-graph failed: ${err instanceof Error ? err.message : String(err)}`);
+      throw err;
+    }
+  });
+}

client/electron/main.ts

@@ -38,6 +38,7 @@ import { loadEnvironment } from './envLoader.js';
 import { installCspPolicy } from './cspPolicy.js';
 import { registerDisplayMediaHandler } from './displayMediaHandler.js';
 import { registerDbIpcHandlers } from './db/dbIpcHandlers.js';
+import { registerKnowledgeIpcHandlers } from './db/knowledgeQueries.js';
 import { registerStorageIpcHandlers } from './storageIpcHandlers.js';
 import { registerKeyframeScheme, registerKeyframeIpcHandlers } from './ipc/keyframeStorage.js';
 import { loadPerformanceMode, registerPerformanceHandlers } from './performanceMode.js';
@@ -176,6 +177,8 @@ if (!gotTheLock) {
     registerStorageIpcHandlers();
     // 知识入籍 IPC（PDF 解析/URL 抓取/入籍记录，详见 importHandlers.ts）
     registerImportHandlers();
+    // 知识星座 IPC（只读图谱聚合，详见 db/knowledgeQueries.ts）
+    registerKnowledgeIpcHandlers();
     // MCP 学习记忆服务器应用内授权开关（详见 memoryServerConsent.ts）
     registerMemoryServerConsentHandlers();
     // 课堂关键帧图片持久化 IPC + keyframe:// 协议（详见 ipc/keyframeStorage.ts）

client/electron/preload.ts

@@ -130,6 +130,8 @@ const ALLOWED_CHANNELS = [
   'import:fetch-url',
   'import:get-settling-records',
   'import:add-settling-record',
+  // 知识星座 IPC channel（阶段 B：只读图谱聚合）
+  'knowledge:get-graph',
 ] as const;
 
 /** 允许渲染进程监听的事件 channel 白名单（主进程 → 渲染进程推送） */

client/src/features/constellation/components/KnowledgeConstellation.tsx

@@ -0,0 +1,120 @@
+/**
+ * 知识星座 · DOM/SVG 轨（medium/low 档）
+ * Knowledge constellation · DOM/SVG track
+ *
+ * @ai-context: 宪法第一条映射（概念掌握度→发光体亮度：牢固=清冽明亮、
+ * 朦胧=朦胧）与第四条知识星座预算（medium/low：L1 每档 ≤15 节点、
+ * SVG line/circle）。朦胧节点施加雾色滤镜：外圈雾晕 opacity ≤0.4
+ * （第二条 §1：雾永远可拨开——雾晕可被点击拨开，露出节点本体）。
+ * 冷启动（宪法第七条：世界未点亮）显示引导文案而非空画布。
+ * 纯静态 SVG 无帧循环，low 档核显安全。
+ *
+ * @ai-context: SVG track for medium/low tiers. Hazy nodes get a fog
+ * halo capped at 40% opacity; cold start shows guidance copy.
+ */
+import { useMemo } from 'react';
+import type { KnowledgeGraph } from '../lib/knowledgeGraph';
+import { layoutKnowledgeGraph, type LayoutNode } from '../lib/knowledgeLayout';
+
+/** 宪法映射：tier → 节点色（牢固=清冽明亮蓝白） / Tier colors */
+const TIER_COLOR: Record<LayoutNode['tier'], string> = {
+  牢固: '#7dd3fc',
+  成长中: '#60a5fa',
+  朦胧: '#94a3b8',
+};
+
+/** 雾色滤镜强度上限（宪法第二条 §1：雾 ≤40% 视觉强度） */
+const FOG_OPACITY_MAX = 0.4;
+
+/** 链类型 → 颜色（同源=溯源青、复习=暖金、薄弱点=微紫） */
+const LINK_COLOR: Record<string, string> = {
+  'shared-note': 'rgba(103, 232, 249, 0.5)',
+  'review-chain': 'rgba(251, 191, 36, 0.45)',
+  weakpoint: 'rgba(196, 181, 253, 0.45)',
+};
+
+interface KnowledgeConstellationProps {
+  /** 派生图谱；null 表示尚未获取到数据（loading/error 分支） */
+  graph: KnowledgeGraph | null;
+  loading?: boolean;
+  error?: string | null;
+}
+
+/** 冷启动引导文案（宪法第七条：世界未点亮） / Cold-start copy */
+const COLD_START_COPY = '世界还未点亮——第一次学习之后，这里会升起你的知识星座';
+
+/** 知识星座 · DOM/SVG 轨 / Knowledge constellation (SVG track) */
+export function KnowledgeConstellation({ graph, loading, error }: KnowledgeConstellationProps) {
+  const layout = useMemo(() => (graph ? layoutKnowledgeGraph(graph) : null), [graph]);
+
+  if (loading && !graph) {
+    return <div className="h-56 rounded-kb-xl bg-bg-elevated/30 animate-pulse-skeleton" role="status" aria-label="知识星座加载中" />;
+  }
+  if (error && !graph) {
+    return (
+      <div className="h-40 flex items-center justify-center rounded-kb-xl border border-border/15 bg-bg-elevated/20">
+        <p className="text-c1 text-text-tertiary">知识星座暂时无法点亮（{error}）</p>
+      </div>
+    );
+  }
+  if (!layout || (layout.nodes.length === 0 && graph?.coldStart)) {
+    return (
+      <div className="h-40 flex items-center justify-center rounded-kb-xl border border-dashed border-border/25 bg-bg-elevated/10">
+        <p className="text-c1 text-text-tertiary text-center px-6">{COLD_START_COPY}</p>
+      </div>
+    );
+  }
+
+  return (
+    <svg
+      viewBox="0 0 100 100"
+      className="w-full h-56 rounded-kb-xl bg-gradient-to-b from-bg-elevated/20 to-transparent"
+      role="img"
+      aria-label="知识星座：概念掌握度空间化（牢固近中心明亮，朦胧在外围雾中）"
+    >
+      {/* 链（先画，节点覆盖其上） */}
+      {layout.links.map((link, i) => {
+        const s = layout.nodes.find((n) => n.id === link.source);
+        const t = layout.nodes.find((n) => n.id === link.target);
+        if (!s || !t) return null;
+        return (
+          <line
+            key={`${link.kind}-${i}`}
+            x1={s.x} y1={s.y} x2={t.x} y2={t.y}
+            stroke={LINK_COLOR[link.kind] ?? 'rgba(148, 163, 184, 0.3)'}
+            strokeWidth={0.25}
+            opacity={0.55}
+          />
+        );
+      })}
+
+      {/* 节点 */}
+      {layout.nodes.map((n) => {
+        const base = TIER_COLOR[n.tier];
+        const radius = n.tier === '牢固' ? 2.2 : n.tier === '成长中' ? 1.8 : 1.4;
+        // 朦胧节点：雾晕（≤40%）+ 本体亮度乘 glow
+        const opacity = 0.35 + n.glow * 0.65;
+        return (
+          <g key={n.id}>
+            {n.dimmed && (
+              <circle
+                cx={n.x} cy={n.y} r={radius * 2.6}
+                fill={base}
+                opacity={FOG_OPACITY_MAX * n.glow}
+                className="kb-fog-halo"
+              />
+            )}
+            <circle
+              cx={n.x} cy={n.y} r={radius}
+              fill={base}
+              opacity={opacity}
+              className="kb-star-node"
+            >
+              <title>{n.concept}（{n.tier}）</title>
+            </circle>
+          </g>
+        );
+      })}
+    </svg>
+  );
+}

client/src/features/constellation/hooks/useKnowledgeGraph.ts

@@ -0,0 +1,70 @@
+/**
+ * 知识星座数据 Hook（30s 轮询 + 焦点事件失效）
+ * Knowledge constellation data hook
+ *
+ * @ai-context: 阶段 B 数据接线。经 knowledge:get-graph 获取三路原始
+ * 数据（主进程只读聚合，limit 封顶 100），在渲染进程用纯函数层
+ * buildKnowledgeGraph 派生图谱（派生规则单测覆盖）。轮询 30s 一档；
+ * 窗口重新聚焦/页面回到可见时立即刷新（事件驱动失效的轻量实现）。
+ * 失败静默降级：保留旧图不闪断，星座是外壳增强项不影响主流程。
+ *
+ * @ai-context: Polls the read-only graph aggregate every 30s and
+ * refreshes on window focus. Failures keep the previous graph.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { buildKnowledgeGraph, type KnowledgeGraph } from '../lib/knowledgeGraph';
+import type { KnowledgeGraphData } from '../types';
+
+/** 轮询间隔（毫秒） / Poll interval */
+const POLL_MS = 30_000;
+
+export interface UseKnowledgeGraphResult {
+  /** 派生图谱；首载失败或尚无数据时为 null（组件自行降级展示） */
+  graph: KnowledgeGraph | null;
+  /** 仅首载为 true；后台刷新不闪烁 */
+  loading: boolean;
+  /** 最近一次失败原因（成功或首载前为 null） */
+  error: string | null;
+  /** 手动触发一次刷新 */
+  refresh: () => Promise<void>;
+}
+
+/** 知识星座数据 Hook / Knowledge constellation data hook */
+export function useKnowledgeGraph(pollMs: number = POLL_MS): UseKnowledgeGraphResult {
+  const [graph, setGraph] = useState<KnowledgeGraph | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    if (!window.electronAPI?.invoke) return;
+    try {
+      // IPC 返回形状见 features/constellation/types.ts（结构化类型断言）
+      const data = await window.electronAPI.invoke('knowledge:get-graph') as KnowledgeGraphData;
+      setGraph(buildKnowledgeGraph(data));
+      setError(null);
+    } catch (err) {
+      // 失败静默：保留旧图避免星座闪断
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+    const timer = setInterval(() => { void load(); }, pollMs);
+    const onFocus = () => { void load(); };
+    const onVisibility = () => {
+      if (document.visibilityState === 'visible') void load();
+    };
+    window.addEventListener('focus', onFocus);
+    document.addEventListener('visibilitychange', onVisibility);
+    return () => {
+      clearInterval(timer);
+      window.removeEventListener('focus', onFocus);
+      document.removeEventListener('visibilitychange', onVisibility);
+    };
+  }, [load, pollMs]);
+
+  return { graph, loading, error, refresh: load };
+}