知識關聯圖

把散落在多份文件裡的概念畫成一張可以探索的圖：丟進一段 Markdown，# 標題成為文件節點、## 標題成為概念、[[雙括號連結]] 把概念串起來、#標籤 自成一類；也可以直接給結構化的 nodes 與 links。暗色星座畫布上，節點大小依關聯數、顏色依類型，可拖曳平移、滾輪以游標為中心縮放、即時搜尋；點選節點時鏡頭把它平移到中央，右側出處面板列出摘要、每則引用的來源檔名與位置，以及可一鍵跳轉的相鄰節點。力模擬為自寫版本，不依賴 d3。

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<KnowledgeGraph/>

    </div>
  );
}

安裝

使用

import { KnowledgeGraph, parseMarkdownGraph } from "@/components/ui/knowledge-graph";

const notes = `# 部署流程
從合併到上線的標準步驟，每一步都要能 [[回滾]]。 #維運

## 回滾
保留最近三個版本的建置產物，一鍵切回並清除 [[快取策略]]。 #維運
`;

// 直接給 markdown
<KnowledgeGraph markdown={notes} onCitationClick={(c) => console.log(c.source, c.location)} />;

// 或先轉換、再自行補上人物節點等結構資料
const graph = parseMarkdownGraph(notes);
<KnowledgeGraph
  nodes={[...graph.nodes, { id: "小周", label: "小周", type: "person" }]}
  links={[...graph.links, { source: "小周", target: "回滾", weight: 2 }]}
  defaultSelectedId="回滾"
/>;

Props

KnowledgeGraphNode

KnowledgeCitation

KnowledgeGraphLink

另外具名匯出 parseMarkdownGraph(md: string): KnowledgeGraphData，以及 KnowledgeGraphProps、KnowledgeGraphData、KnowledgeNodeType 型別。

CSS 變數

細節

• Markdown 規則：# 標題 → 文件節點；## 標題 → 概念節點並連到所屬文件，### 以下掛在最近的 ## 底下；[[名稱]]（或 [[名稱|顯示文字]]）連到同名節點，不存在時自動建立概念；#標籤 前面須是行首、空白或中文標點，網址裡的 a#b 不會被當成標籤。每段文字成為一則引用，location 是「文件 › 標題 · 第 N 行」，同一段被連到的概念與標籤也會收到這則引用；同一對節點重複出現時權重累加
• 自寫力模擬：初始位置以 id 的 hash 決定性地放在圓盤內（SSR 與 client 一致）；每個 tick 計算 O(n²) 斥力（強度 -120）、連線彈力（理想長度 linkDistance，權重越大越短）、向中心引力 0.02 與 0.85 的速度阻尼；alpha 從 1 以 0.97 衰減，低於 0.005 停止 requestAnimationFrame。建議 300 個節點以內
• 只在結構改變時重排：節點 id 與連線沒變時，呼叫端每次 render 傳新陣列不會讓佈局重來；新增節點時既有節點保留目前位置
• 鏡頭：平移與縮放走 spring（stiffness 300、damping 35），縮放範圍 0.3–3；使用者動過鏡頭之前，佈局穩定過程中會自動框住整張圖。畫布離開視窗時暫停模擬
• 拖曳與釘住：拖曳節點時它跟隨指標、整張圖重新加熱到 alpha 0.3，放手後解除固定；雙擊節點釘住位置（畫虛線外環），再雙擊解除；「重新排版」清除所有釘選並從初始位置重跑
• 搜尋：輸入時符合的節點保持亮、其他淡化到 0.2，按 Enter 選取第一個符合者並置中；IME 組字中的 Enter 不會觸發

可及性

• 外層為 role="application"，以 aria-describedby 連到一段 sr-only 操作說明；另有一份 sr-only 清單列出每個節點與它的關聯，螢幕閱讀器不必操作畫布也能讀到整張圖
• 每個節點是可聚焦的 role="button"，aria-label 形如「概念：快取策略，6 個關聯」，選取中帶 aria-pressed；Tab 依關聯數由高到低走訪，聚焦時與 hover 一樣高亮鄰居並自動把節點帶進畫面
• 畫布聚焦時方向鍵平移、+／- 縮放；Enter 或空白鍵選取節點、Esc 取消選取；選取結果以 aria-live 播報
• 工具列按鈕都有 aria-label，類型篩選 chips 以 aria-pressed 表示開關，所有控制項都有 focus-visible 外框
• 使用者系統開啟「減少動態效果」時，模擬同步預跑 300 tick 後直接靜態呈現，不顯示沿線流動的光點，鏡頭移動直接跳位，出處面板只淡入不滑動；拖曳節點只移動該節點、不重新加熱整張圖