@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/llm-wiki/packages/graph-engine/src/types.ts

@@ -0,0 +1,313 @@
+export type NodeId = string;
+export type EdgeId = string;
+export type CommunityId = string;
+export type WikiPath = string;
+
+export type ThemeId = "shan-shui" | "mo-ye";
+
+export type GraphNodeType =
+  | "entity"
+  | "topic"
+  | "source"
+  | "comparison"
+  | "synthesis"
+  | "query"
+  | string;
+
+export type Confidence = "EXTRACTED" | "INFERRED" | "AMBIGUOUS" | "UNVERIFIED" | string;
+export type GraphRelationType = "实现" | "依赖" | "对比" | "矛盾" | "衍生" | string;
+
+export interface GraphData {
+  meta: GraphMeta;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  insights?: GraphInsights;
+  learning?: GraphLearning;
+}
+
+export interface GraphMeta {
+  build_date: string;
+  wiki_title: string;
+  total_nodes: number;
+  total_edges: number;
+  initial_view?: NodeId[];
+  degraded?: boolean;
+  insights_degraded?: boolean;
+}
+
+export interface GraphNode {
+  id: NodeId;
+  label: string;
+  type: GraphNodeType;
+  community?: CommunityId | null;
+  content?: string;
+  source_path?: string;
+  source?: string;
+  path?: string;
+  summary?: string;
+  confidence?: Confidence;
+  type_confidence?: Confidence;
+  weight?: number;
+  score?: number;
+  x?: number | string | null;
+  y?: number | string | null;
+  [key: string]: unknown;
+}
+
+export interface GraphEdge {
+  id: EdgeId;
+  from: NodeId;
+  to: NodeId;
+  confidence?: Confidence;
+  relation_type?: GraphRelationType;
+  type: Confidence;
+  weight?: number;
+  source_signal_available?: boolean;
+  signals?: GraphEdgeSignals;
+  [key: string]: unknown;
+}
+
+export interface GraphEdgeSignals {
+  co_citation?: number;
+  source_overlap?: number | null;
+  type_affinity?: number;
+  [key: string]: number | boolean | string | null | undefined;
+}
+
+export interface GraphInsights {
+  surprising_connections: SurprisingConnection[];
+  isolated_nodes: IsolatedNodeInsight[];
+  bridge_nodes: BridgeNodeInsight[];
+  sparse_communities: SparseCommunityInsight[];
+  meta: GraphInsightsMeta;
+}
+
+export interface GraphInsightsMeta {
+  degraded: boolean;
+  node_count: number;
+  edge_count: number;
+  max_insight_nodes: number;
+  max_insight_edges: number;
+}
+
+export interface SurprisingConnection {
+  from: NodeId;
+  to: NodeId;
+  weight: number;
+  from_community: CommunityId | null;
+  to_community: CommunityId | null;
+}
+
+export interface IsolatedNodeInsight {
+  id: NodeId;
+  label: string;
+  degree: number;
+  community: CommunityId | null;
+}
+
+export interface BridgeNodeInsight {
+  id: NodeId;
+  label: string;
+  community: CommunityId | null;
+  connected_communities: CommunityId[];
+  community_count: number;
+}
+
+export interface SparseCommunityInsight {
+  id: CommunityId;
+  label: string;
+  node_count: number;
+  density: number;
+  members: NodeId[];
+  internal_edges: number;
+}
+
+export interface GraphLearning {
+  version?: 1;
+  entry: GraphLearningEntry;
+  views: GraphLearningViews;
+  communities: Community[];
+  degraded?: {
+    path_to_community: boolean;
+    community_to_global: boolean;
+  };
+}
+
+export interface GraphLearningEntry {
+  recommended_start_node_id: NodeId | null;
+  recommended_start_reason: string | null;
+  default_mode: GraphLearningMode;
+}
+
+export type GraphLearningMode = "path" | "community" | "global";
+
+export interface GraphLearningViews {
+  path: GraphLearningPathView;
+  community: GraphLearningCommunityView;
+  global: GraphLearningGlobalView;
+}
+
+export interface GraphLearningPathView {
+  enabled: boolean;
+  start_node_id: NodeId | null;
+  node_ids: NodeId[];
+  degraded: boolean;
+}
+
+export interface GraphLearningCommunityView {
+  enabled: boolean;
+  community_id: CommunityId | null;
+  label: string | null;
+  node_ids: NodeId[];
+  is_weak: boolean;
+  degraded: boolean;
+}
+
+export interface GraphLearningGlobalView {
+  enabled: boolean;
+  node_ids: NodeId[];
+  degraded: boolean;
+}
+
+export interface Community {
+  id: CommunityId;
+  label: string;
+  node_count: number;
+  source_count?: number;
+  internal_edge_weight?: number;
+  is_primary?: boolean;
+  is_weak?: boolean;
+  recommended_start_node_id?: NodeId | null;
+  color_index?: number;
+  members?: NodeId[];
+}
+
+export interface PinPosition {
+  x: number;
+  y: number;
+}
+
+export type PinMap = Record<WikiPath, PinPosition>;
+
+export interface GraphLayoutFile {
+  version: 1;
+  pins: PinMap;
+  updatedAt: string;
+}
+
+export interface GraphDiff {
+  addedNodes: NodeId[];
+  removedNodes: NodeId[];
+  recoloredNodes: Array<{ id: NodeId; from: CommunityId; to: CommunityId }>;
+  addedEdges: EdgeId[];
+  removedEdges: EdgeId[];
+  newCommunities: CommunityId[];
+  stats: {
+    nodeCount: number;
+    edgeCount: number;
+    communityCount: number;
+  };
+}
+
+export interface SelectionFacts {
+  pageCount: number;
+  internalLinkCount: number;
+  communityCount: number;
+  isolatedCount: number;
+}
+
+export type SelectionActionId =
+  | "summarize_page"
+  | "find_related_pages"
+  | "quote_page"
+  | "summarize_cluster"
+  | "summarize_group"
+  | "explore_group_relationships"
+  | "find_knowledge_gaps"
+  | "create_topic_page"
+  | "why_no_connection"
+  | "find_potential_bridges"
+  | "compare_communities"
+  | "explore_potential_links"
+  | "compare_differences"
+  | "link_island";
+
+export type SelectionActionTone = "digest" | "lint" | "write" | "bridge" | "compare" | "repair";
+
+export interface SelectionAction {
+  id: SelectionActionId;
+  label: string;
+  tone: SelectionActionTone;
+}
+
+export interface Selection {
+  id: string;
+  nodeIds: NodeId[];
+  communityIds: CommunityId[];
+  facts: SelectionFacts;
+  actions?: SelectionAction[];
+}
+
+export type SelectionInput =
+  | { kind: "node"; id: NodeId }
+  | { kind: "community"; id: CommunityId }
+  | { kind: "neighbors"; id: NodeId }
+  | { kind: "nodes"; ids: NodeId[] };
+
+export type GraphFocusInput =
+  | { kind: "community"; id: CommunityId }
+  | null;
+
+export type GraphTypeFilters = Record<GraphNodeType, boolean>;
+
+export interface GraphOpenPageNode {
+  id: NodeId;
+  title: string;
+  type: GraphNodeType;
+  typeLabel: string;
+  sourcePath: WikiPath;
+  community?: CommunityId | null;
+  date?: string | null;
+  source?: string | null;
+  isolated: boolean;
+}
+
+export interface GraphOpenPagePayload {
+  path: WikiPath;
+  node: GraphOpenPageNode;
+}
+
+export interface GraphEngineCapabilities {
+  persistPins?: (pins: PinMap) => Promise<void>;
+  onAsk?: (selection: Selection) => void;
+  onOpenPage?: (payload: GraphOpenPagePayload) => void;
+  onSelectionChange?: (selection: Selection) => void;
+  onSelectionClear?: () => void;
+  onDragStateChange?: (dragging: boolean) => void;
+}
+
+export interface GraphEngineOptions {
+  data: GraphData;
+  pins?: PinMap;
+  theme: ThemeId;
+  focus?: GraphFocusInput;
+  typeFilters?: GraphTypeFilters;
+  toolbarContainer?: HTMLElement | null;
+  capabilities?: GraphEngineCapabilities;
+}
+
+export interface GraphEngine {
+  applyDiff(diff: GraphDiff, options?: { reducedMotion?: boolean; durationMs?: number }): Promise<void>;
+  isDragging(): boolean;
+  focusNode(path: WikiPath): void;
+  focusCommunity(id: CommunityId): Selection;
+  setTypeFilters(filters: GraphTypeFilters): void;
+  resetView(): void;
+  select(selector: SelectionInput): Selection;
+  clearSelection(): void;
+  clearInteraction(): void;
+  setTheme(theme: ThemeId): void;
+  setPins(pins: PinMap): void;
+  resetLayout(): void;
+  destroy(): void;
+}

package/dist/skills/llm-wiki/packages/graph-engine/test/anim.test.ts

@@ -0,0 +1,100 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { GraphDiffQueue, mergeGraphDiffs } from "../src/anim";
+import type { GraphDiff } from "../src/types";
+
+describe("GraphDiffQueue", () => {
+  it("consumes immediately when graph is visible", () => {
+    const queue = new GraphDiffQueue({ visible: true });
+    const decision = queue.push(diff({ addedNodes: ["n1"] }));
+
+    assert.equal(decision.action, "consume");
+    assert.deepEqual(decision.diff?.addedNodes, ["n1"]);
+    assert.equal(decision.snapshot.isAnimating, true);
+
+    const done = queue.finishAnimation();
+    assert.equal(done.action, "queue");
+    assert.equal(done.snapshot.isAnimating, false);
+  });
+
+  it("queues while hidden and consumes the net diff when shown", () => {
+    const queue = new GraphDiffQueue({ visible: false });
+
+    const queued = queue.push(diff({ addedNodes: ["n1"], addedEdges: ["e1"] }));
+    assert.equal(queued.action, "queue");
+    assert.deepEqual(queued.snapshot.pending?.addedNodes, ["n1"]);
+
+    const shown = queue.setVisible(true);
+    assert.equal(shown.action, "consume");
+    assert.deepEqual(shown.diff?.addedNodes, ["n1"]);
+    assert.deepEqual(shown.diff?.addedEdges, ["e1"]);
+    assert.equal(shown.snapshot.pending, null);
+  });
+
+  it("holds diffs during drag and consumes after release", () => {
+    const queue = new GraphDiffQueue({ visible: true });
+
+    queue.setDragging(true);
+    const queued = queue.push(diff({ addedNodes: ["n1"] }));
+    assert.equal(queued.action, "queue");
+    assert.equal(queued.reason, "dragging");
+
+    const released = queue.setDragging(false);
+    assert.equal(released.action, "consume");
+    assert.deepEqual(released.diff?.addedNodes, ["n1"]);
+  });
+
+  it("folds multiple pending diffs into one net replay", () => {
+    const queue = new GraphDiffQueue({ visible: false });
+
+    queue.push(diff({
+      addedNodes: ["create-then-delete", "stay-new"],
+      addedEdges: ["edge-create-then-delete"],
+      recoloredNodes: [{ id: "color", from: "old", to: "mid" }],
+      stats: { nodeCount: 3, edgeCount: 1, communityCount: 2 }
+    }));
+    queue.push(diff({
+      removedNodes: ["create-then-delete"],
+      removedEdges: ["edge-create-then-delete"],
+      recoloredNodes: [{ id: "color", from: "mid", to: "new" }],
+      newCommunities: ["fresh"],
+      stats: { nodeCount: 2, edgeCount: 0, communityCount: 3 }
+    }));
+
+    const shown = queue.setVisible(true);
+
+    assert.equal(shown.action, "consume");
+    assert.deepEqual(shown.diff, diff({
+      addedNodes: ["stay-new"],
+      recoloredNodes: [{ id: "color", from: "old", to: "new" }],
+      newCommunities: ["fresh"],
+      stats: { nodeCount: 2, edgeCount: 0, communityCount: 3 }
+    }));
+  });
+});
+
+describe("mergeGraphDiffs", () => {
+  it("cancels add-then-remove nodes and keeps latest stats", () => {
+    const merged = mergeGraphDiffs(
+      diff({ addedNodes: ["a", "b"], stats: { nodeCount: 2, edgeCount: 0, communityCount: 1 } }),
+      diff({ removedNodes: ["a"], stats: { nodeCount: 1, edgeCount: 0, communityCount: 1 } })
+    );
+
+    assert.deepEqual(merged.addedNodes, ["b"]);
+    assert.deepEqual(merged.removedNodes, []);
+    assert.equal(merged.stats.nodeCount, 1);
+  });
+});
+
+function diff(partial: Partial<GraphDiff> = {}): GraphDiff {
+  return {
+    addedNodes: partial.addedNodes ?? [],
+    removedNodes: partial.removedNodes ?? [],
+    recoloredNodes: partial.recoloredNodes ?? [],
+    addedEdges: partial.addedEdges ?? [],
+    removedEdges: partial.removedEdges ?? [],
+    newCommunities: partial.newCommunities ?? [],
+    stats: partial.stats ?? { nodeCount: 0, edgeCount: 0, communityCount: 0 }
+  };
+}

package/dist/skills/llm-wiki/packages/graph-engine/test/diff.test.ts

@@ -0,0 +1,133 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { diffGraphData } from "../src/diff";
+import type { GraphData, GraphEdge, GraphNode } from "../src/types";
+
+describe("graph diff with community alignment", () => {
+  it("does not report recolors or new communities when community ids are shuffled", () => {
+    const previous = graph([
+      node("a", "old-alpha"),
+      node("b", "old-alpha"),
+      node("c", "old-beta"),
+      node("d", "old-beta")
+    ]);
+    const next = graph([
+      node("a", "new-1"),
+      node("b", "new-1"),
+      node("c", "new-2"),
+      node("d", "new-2")
+    ]);
+
+    const diff = diffGraphData(previous, next);
+
+    assert.deepEqual(diff.recoloredNodes, []);
+    assert.deepEqual(diff.newCommunities, []);
+  });
+
+  it("reports added and removed nodes and edges", () => {
+    const previous = graph(
+      [node("a", "alpha"), node("b", "alpha"), node("removed", "alpha")],
+      [edge("a-b", "a", "b"), edge("removed-edge", "b", "removed")]
+    );
+    const next = graph(
+      [node("a", "alpha"), node("b", "alpha"), node("added", "alpha")],
+      [edge("a-b", "a", "b"), edge("added-edge", "b", "added")]
+    );
+
+    const diff = diffGraphData(previous, next);
+
+    assert.deepEqual(diff.addedNodes, ["added"]);
+    assert.deepEqual(diff.removedNodes, ["removed"]);
+    assert.deepEqual(diff.addedEdges, ["added-edge"]);
+    assert.deepEqual(diff.removedEdges, ["removed-edge"]);
+    assert.equal(diff.stats.nodeCount, 3);
+    assert.equal(diff.stats.edgeCount, 2);
+  });
+
+  it("reports real recolors after aligned community matching", () => {
+    const previous = graph([
+      node("a", "alpha"),
+      node("b", "alpha"),
+      node("c", "beta"),
+      node("d", "beta")
+    ]);
+    const next = graph([
+      node("a", "alpha-renamed"),
+      node("b", "alpha-renamed"),
+      node("c", "beta-renamed"),
+      node("d", "alpha-renamed")
+    ]);
+
+    const diff = diffGraphData(previous, next);
+
+    assert.deepEqual(diff.recoloredNodes, [{ id: "d", from: "beta", to: "alpha-renamed" }]);
+    assert.deepEqual(diff.newCommunities, []);
+  });
+
+  it("reports unmatched new communities", () => {
+    const previous = graph([node("a", "alpha"), node("b", "alpha")]);
+    const next = graph([
+      node("a", "alpha"),
+      node("b", "alpha"),
+      node("c", "gamma"),
+      node("d", "gamma")
+    ]);
+
+    const diff = diffGraphData(previous, next);
+
+    assert.deepEqual(diff.addedNodes, ["c", "d"]);
+    assert.deepEqual(diff.newCommunities, ["gamma"]);
+    assert.equal(diff.stats.communityCount, 2);
+  });
+
+  it("treats a real community color change as recolored", () => {
+    const previous = graph([node("a", "alpha"), node("b", "alpha"), node("c", "beta"), node("d", "beta")]);
+    const next = graph([node("a", "alpha"), node("b", "alpha"), node("c", "beta"), node("d", "alpha")]);
+
+    const diff = diffGraphData(previous, next);
+
+    assert.deepEqual(diff.recoloredNodes, [{ id: "d", from: "beta", to: "alpha" }]);
+  });
+
+  it("handles a community split by preserving the larger overlap and marking the smaller half as new", () => {
+    const previous = graph([
+      node("a", "alpha"),
+      node("b", "alpha"),
+      node("c", "alpha"),
+      node("d", "alpha")
+    ]);
+    const next = graph([
+      node("a", "alpha-main"),
+      node("b", "alpha-main"),
+      node("c", "alpha-main"),
+      node("d", "alpha-split")
+    ]);
+
+    const diff = diffGraphData(previous, next);
+
+    assert.deepEqual(diff.recoloredNodes, []);
+    assert.deepEqual(diff.newCommunities, ["alpha-split"]);
+  });
+});
+
+function graph(nodes: GraphNode[], edges: GraphEdge[] = []): GraphData {
+  return {
+    meta: {
+      build_date: "2026-06-12T00:00:00.000Z",
+      wiki_title: "Diff Fixture",
+      total_nodes: nodes.length,
+      total_edges: edges.length
+    },
+    nodes,
+    edges
+  };
+}
+
+function node(id: string, community: string): GraphNode {
+  return { id, label: id.toUpperCase(), type: "entity", community, source_path: `wiki/entities/${id}.md` };
+}
+
+function edge(id: string, from: string, to: string): GraphEdge {
+  return { id, from, to, type: "EXTRACTED", weight: 1 };
+}