前言¶
项目里的说明、代码和 PDF 越积越多，靠全文搜索很难看出概念之间的关系。手工画脑图或往图数据库里灌数据，要么维护成本高，要么要单独搭一套工具链。下面介绍 SkillHub 上的社区 Skill「通用知识图谱构建器」：在 Agent 里按固定流程检查环境、扫描文档、调用 LLM 抽取图谱，并生成本地可双击打开的 HTML 页面。
这是什么¶
通用知识图谱构建器（坐标 @user_19a6d235/knowledge-graph-builder，当前版本 1.0.6，来源 community，分类 knowledge-management）由发布者 user_19a6d235 维护。它是一套基于通用 SKILL.md 的 Agent 工作流，不是独立桌面应用：启用后由 Agent 按文档执行 Bash、读写文件，把「文档目录 → 知识图谱 → 静态页面」串成可复现步骤。
官方简介概括为四步：检查环境 → 分析文档 → 构建知识图谱 → 生成交互式 HTML 页面。支持对任意目录下的 Markdown、代码、PDF、图片等做分析；LLM 侧走 OpenAI 兼容 API，配置可写入本地文件并在后续构建中复用。SkillHub 标签标明 requires_api_key=true，使用前需自备 API Key 与端点。
核心功能¶
环境与依赖¶
- 校验 Python 3.10+，必要时按平台给出安装指引。
- 检测系统或环境变量中的代理；若存在代理，后续执行 graphify 相关命令时可配合
NO_PROXY="*"，避免 httpx 与系统代理冲突（Skill 文档中说明了常见报错场景）。 - 在
~/.knowledge-graph-builder/venv创建或复用虚拟环境，安装固定版本依赖：graphifyy 0.7.13、openai 2.36.0。 - 将 LLM 的 Base URL、API Key、模型名写入
~/.knowledge-graph-builder/env.sh（权限600），并通过一次连通性请求验证配置。
文档分析与用户确认¶
对目标目录做文件类型统计（如 md、代码、pdf、图片、txt 等），估算 token 规模与推荐 token budget、是否开启聚类（节点少于 20 时默认建议 --no-cluster）。在真正调用构建 API 之前，Skill 要求展示分析报告与费用粗算，并等待用户明确确认；用户也可选择仅生成空页面或取消。
图谱构建¶
通过内联 Python 脚本调用 graphify 的 extract 子命令，对 OpenAI 后端做 base_url 的 monkey-patch，以适配 DeepSeek、OpenAI 等兼容服务。产出写在文档目录下的 graphify-out/graph.json，包含节点、边及 token 统计；构建前另有配置摘要确认检查点。
交互式 HTML¶
读取 Skill 包内的 template.html，将标题占位符 {{TITLE}} 与图谱 JSON 占位符 {{GRAPH_JSON}} 替换后，写出 <知识库名称>-知识图谱.html。页面内联 D3.js v7，图谱数据内联在单文件中，本机双击即可浏览；字体依赖 Google Fonts，无网时会回退到系统等宽字体。
增量更新¶
当用户表达「更新/刷新知识库」等意图时，Skill 会检测 graphify-out 与 .knowledge-graph-history/last_build.json，对比新增/删除文件，在增量更新与全量重建之间让用户选择，并复用已有 env.sh 配置。
触发方式¶
除自然语言外，官方列出的触发词包括：知识图谱、建知识库、知识库页面、graphify、生成知识库、文档图谱化、知识管理、知识库工具。示例话术如「把我的文档做成知识库」「生成知识图谱」等。
安装与启用¶
SkillHub 页面给出的安装方式是：让 Agent 阅读 SkillHub 安装说明，并安装坐标 @user_19a6d235/knowledge-graph-builder。
若本机已有 skillhub CLI，安装时需用 --dir 指向当前 Agent 的 skills 目录，否则默认装到 ./skills/ 可能不会被识别。官方文档中的常用路径示例：
| Agent / 客户端 | skills 目录（示例） |
|---|---|
| Cursor | ~/.cursor/skills/ |
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.codex/skills/ 或项目下 .agents/skills/ |
命令行安装示例（将 <skills 目录> 换成你环境中的实际路径）：
skillhub install knowledge-graph-builder --namespace user_19a6d235 --dir <skills 目录>
首次使用 CLI 可按 skillhub.cn/install/skillhub.md 检查或安装 skillhub 本身。Skill 声明允许使用的工具为 Bash、Read、Write、Edit，需在支持 Skill 的 Agent 中启用。
典型用法¶
经过上面的安装步骤后，在对话中说明意图即可，Agent 会按 Skill 从 Step 0 开始收集信息。
1、准备输入
- 提供文档目录的绝对路径（可选：知识库显示名称）。
- 若尚未配置 LLM，需提供 OpenAI 兼容的 Base URL（需以
/v1结尾）、API Key、模型 ID（如 DeepSeek 或 OpenAI 系列）。若~/.knowledge-graph-builder/env.sh已存在，可跳过重复询问。
2、确认分析报告
Agent 展示目录内文件分布与预估 token、推荐 budget 与聚类策略后，回复「继续」才会进入构建；可说「调整参数」或「取消」。
3、构建与打开页面
确认构建配置后，在文档父目录执行 graphify 抽取；成功后得到 graphify-out/graph.json 与同目录或工作区内的 *-知识图谱.html。本机使用可直接双击 HTML；内网共享可用：
cd <页面所在目录> && python3 -m http.server <端口>
4、文档变更后
说明「更新知识库」等，走增量流程：对比文件变更，选择增量或全量重建，HTML 会覆盖更新。
典型 LLM 配置会写入如下结构（值为用户实际填写）：
# ~/.knowledge-graph-builder/env.sh
LLM_BASE_URL="https://api.deepseek.com/v1"
LLM_API_KEY="sk-..."
LLM_MODEL="deepseek-v4-flash"
适用场景与注意¶
适合谁： 想把本地或仓库内的技术文档、产品说明、论文 PDF、代码注释等整理成可浏览的概念关系图，且愿意用自有 LLM API 完成抽取；需要单文件 HTML 分发、离线查看图谱（不部署 Neo4j 等图数据库）的团队或个人。
限制与注意：
- 必须配置有效的 OpenAI 兼容 API；构建过程会产生按 token 计费的开销，Skill 在检查点会做粗算，实际以服务商账单为准。
- 依赖本机 Python 3.10+ 及 pip 安装 graphifyy；网络受限环境需自行处理代理（见 Skill 常见问题）。
- 大目录或限流（HTTP 429）时可能需要降低并发（如
--max-concurrency 2）或调整 token budget；若graph.json节点数为 0，需按 Skill 排查 Key、URL、模型名与文档格式。 - SkillHub 元数据：评分 100000，下载 2023（以 SkillHub 页面抓取为准）；与个别转载线索中的数字不一致时，以商店页为准。
结尾¶
通用知识图谱构建器把「环境检查、文档扫描、graphify 抽取、D3 页面打包」写进一套 Agent 可执行流程，适合从杂乱文件夹快速得到可交互的知识图谱 HTML，并在文档迭代时做增量更新。官方 Skill 页与安装坐标：
- SkillHub：https://www.skillhub.cn/skills/user_19a6d235/knowledge-graph-builder
- API 资源页：https://api.skillhub.cn/user_19a6d235/knowledge-graph-builder
