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-CN.md