4分鐘閱讀

Graphify 知識圖譜指南

介紹如何將專案的文件、原始碼與標籤視覺化為 3D 知識圖譜，並探索節點之間的關聯。

🚀 前往 Graphify 頁面 →

📋 概述

Graphify 是將所選專案（csn）中的文件、原始碼與標籤，以由節點和連線組成的 3D 知識圖譜形式呈現的頁面。節點依類型著色，並依重要度（加權連接數）排序顯示。

🔍 主要元素說明

1. 頂部頁首

以 已顯示 / 總計 nodes · N links 的格式，顯示目前已算繪的節點數、節點總數以及連線數。

2. 節點搜尋

在頁首搜尋框中輸入標籤或路徑（path）的一部分，即可在所有節點中尋找相符的節點，並在左側以清單形式顯示結果。點擊結果後，該節點會出現在圖譜中並被選取。

3. 3D 圖譜畫布

節點依類型進行顏色區分，如左下角圖例所示：Doc / Spec（琥珀色）、Code / Source（天藍色）、Tag（綠色）。點擊節點會將其選取並開啟檢視器；點擊背景則取消選取。

4. 節點檢視器（右側面板）

顯示所選節點的類型徽章、連接數與路徑，並提供兩種關係清單:

Backlinks: 指向（連入）該節點的節點清單
Outgoing links: 該節點所指向（連出）的節點清單

點擊清單中的項目可跳轉（下鑽）到該節點；使用面板左上角的返回按鈕可回到上一個節點。

5. 文件內文彈出視窗

點擊檢視器中的節點標題會開啟一個圖層彈出視窗。若該節點為 KB 文件（路徑為 kb/<編號>），則以 Markdown 顯示其完整內文。其他節點則顯示無內文可展示的提示。按 Esc 鍵可關閉彈出視窗。

🛠️ 使用技巧

載入更多: 基於效能考量，圖譜一開始僅顯示重要度前 50 個節點。可透過底部中央的 [Load N more] 按鈕載入接下來的 50 個。
同步: 點擊頁首右側的 [Sync] 按鈕可重新載入圖譜資料。

💡 注意事項

若未選擇專案，將顯示 "No Project Selected" 畫面。請從頂部導覽選擇專案。
檢視圖譜無需登入，但 KB 文件的內文需要登入（驗證權杖）才能檢視。

🔌 透過 API 管理圖譜（新增·修改·刪除·重建）

Graphify 圖譜衍生自 KB 項目（tKB）。透過 API 新增、修改或刪除項目後，呼叫重建即可反映到圖譜中。連結（邊）並非手動繪製，而是由重建從項目中自動產生。

主機: https://giipfaw.azurewebsites.net
驗證: 所有寫入 API 都需要在請求標頭 x-api-key 中提供登入使用者的 AK 或專案範圍的 SK。金鑰只能在其自身 csn 範圍內新增/修改/刪除/重建。
工作流程: 新增/修改/刪除（giipKb） → 重建（giipGraphifyRebuild） → 確認（giipGraphify）

1) 新增節點 — `giipKb` POST

curl -X POST "https://giipfaw.azurewebsites.net/api/giipKb" \
  -H "x-api-key: <AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"csn":47,"title":"OAuth 回呼 500","content":"## 原因\ntoken 交換逾時","tags":"auth,oauth,timeout","refType":"ISSUE","extRefId":"ISSUE-1001"}'

title 成為圖譜的節點標籤，content 在點擊節點時作為內文彈出視窗（Markdown）呈現。
指定 extRefId 即為冪等 upsert —— 以相同值再次傳送會更新而非建立重複項。
回應: { "success": true, "kbSn": 844, "message": "..." }

2) 修改節點 — `giipKb` PUT

curl -X PUT "https://giipfaw.azurewebsites.net/api/giipKb" \
  -H "x-api-key: <AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"kbSn":844,"title":"OAuth 回呼 500（已解決）","content":"## 處理\n逾時 30s->90s","tags":"auth,oauth,resolved"}'

以 kbSn 指定要修改的項目。

3) 刪除節點 — `giipKb` DELETE

curl -X DELETE "https://giipfaw.azurewebsites.net/api/giipKb?kbSn=844" \
  -H "x-api-key: <AK_OR_SK>"

4) 重建（產生連結）— `giipGraphifyRebuild` POST

新增/修改/刪除項目後必須呼叫，變更才會顯示。它會從 KB 項目重新產生該 csn 的節點與邊。

curl -X POST "https://giipfaw.azurewebsites.net/api/giipGraphifyRebuild" \
  -H "x-api-key: <AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"csn":47}'

回應: { "success": true, "csn": 47, "nodes": 838, "edges": 11, "message": "Graph rebuilt" }
選用參數（大型專案的效能調校）:
- maxNodes: 納入圖譜的最新項目上限（預設 400）
- scanLen: 尋找連結時掃描內文前綴的長度（預設 1500）
```
-d '{"csn":47,"maxNodes":800,"scanLen":2000}'
```

5) 讀取圖譜 — `giipGraphify` GET

頁面內部使用的讀取 API（無需驗證即可讀取）。如需直接查看:

curl "https://giipfaw.azurewebsites.net/api/giipGraphify?csn=47"

回應: { "nodes": [...], "links": [...] }

完整欄位規格請參閱 📘 API 參考概覽。

疑難排解

症狀	原因	解決方法
僅顯示 "No Project Selected"	未指定專案（csn）	從頂部導覽選擇專案。
文件彈出視窗顯示「需要登入」	取得 KB 內文缺少驗證權杖	登入後再次點擊節點標題。
節點顯示無內文	該節點並非 KB 文件（`kb/…`）	內文僅對 KB 文件節點提供。此為正常行為。
部分節點在圖譜中不可見	僅優先顯示重要度前 50 個節點	使用底部的 [Load N more] 載入更多，或透過搜尋使節點顯示。
`API Error` 或載入失敗	工作階段逾時或伺服器回應錯誤	點擊錯誤橫幅上的 [Retry]，或重新登入。

版本: 1.0 最後更新: 2026-07-22 原始檔: giipv3/public/help/graphify.zh-TW.md