Knowledge Graph Tool Free

SKILL.md

---
name: "knowledge-graph-tool-free"
description: "个人用户的嵌入式知识图谱,以JSON存储,提供基础增删查改与上下文摘要。"
license: Proprietary
allowed-tools: read exec
compatibility: "Requires LLM with tool-use capability"
metadata:
  displayName: "知识图谱工具(免费版)"
  version: "1.0.0"
  summary: "个人用户的嵌入式知识图谱,以JSON存储,提供基础增删查改与上下文摘要。"
  tags:
    - "Development"
    - "Knowledge"
    - "个人知识库"
    - "JSON"
  source: "SkillHub"
  converted_at: "2026-07-22T17:58:36"
---

# 知识图谱工具(免费版)

## 概述

知识图谱工具(免费版)为个人用户提供轻量级的嵌入式知识图谱能力。图谱以 JSON 文件存储,通过命令行脚本进行查询与维护,并在每次会话开始时生成一份紧凑的 KGML 摘要注入上下文,让 Agent 始终拥有结构化的长期记忆。

本版本聚焦单 Agent、单用户的本地知识管理,适合个人知识库、学习笔记结构化与会话记忆持久化。如需加密保险库、可视化、多Agent协作与内存导入等进阶能力,请升级至 PRO 版本。

## 核心能力

| 能力 | 说明 |
| --- | --- |
| 实体管理 | 增删改实体,支持类别、类型、属性、标签 |
| 关系管理 | 维护父子层级与跨分支关系 |
| 基础查询 | 子节点、按类型、按分类、孤立节点、统计、时间线 |
| KGML摘要 | 紧凑文本摘要,自动注入会话上下文 |
| 安装初始化 | 自动检测Agent平台并注入KG指令 |
**技术实现要点**：核心能力基于`input_params`参数与`output_format`配置实现,支持创建/查询/修改/删除等操作模式,通过`config_options`进行运行时配置。

### 核心功能执行
用`input_params`参数进行配置。

**输入**: 用户提供核心功能执行所需的指令和必要参数。
**处理**: 按照skill规范执行核心功能执行操作,遵循单一意图原则。
**输出**: 返回核心功能执行的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 参数配置与调用
用`config_options`参数进行配置。

**输入**: 用户提供参数配置与调用所需的指令和必要参数。
**处理**: 按照skill规范执行参数配置与调用操作,遵循单一意图原则。
**输出**: 返回参数配置与调用的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`config_options`参数,支持修改/重置/导入操作

### 结果处理与输出
用`output_format`参数进行配置。

**输入**: 用户提供结果处理与输出所需的指令和必要参数。
**处理**: 按照skill规范执行结果处理与输出操作,遵循单一意图原则。
**输出**: 返回结果处理与输出的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`output_format`参数,支持导出/保存/转换操作
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：个人用户的嵌入式、知识图谱、JSON、提供基础增删查改、与上下文摘要、知识图谱工具、免费版、为个人用户提供轻、量级的嵌入式知识、图谱能力、文件持久化、通过命令行脚本查、询与维护、实体与关系的增删、紧凑摘要、图谱统计与时间线等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

## 使用场景

### 场景一:整理学习笔记为结构化知识

用户读完一篇技术文章,希望把其中的概念与关系沉淀到知识图谱。

```bash
# 查看当前图谱统计
node scripts/query.mjs stats

# 查找已有相关实体
node scripts/query.mjs find "依赖注入"
```

Agent 会读取文章,提取实体与关系,写入图谱,并生成 KGML 摘要供下次会话使用。

```text
#KGML v2 | 12e 8r | depth:3 | 2026-07-18
[技术]
依赖注入(DI):pattern — 控制反转,松耦合
  构造器注入:pattern — 通过构造函数传入依赖
  属性注入:pattern — 通过setter传入依赖
%rels
依赖注入>实现>Spring 依赖注入>替代>服务定位器
```

### 场景二:会话间保持长期记忆

用户希望下次会话能记住之前讨论过的决策与上下文。

```bash
# 列出最近7天创建/更新的实体
node scripts/query.mjs recent --days 7

# 查看时间线
node scripts/query.mjs timeline --from 2026-07-01 --to 2026-07-18
```

每次会话开始时,Agent 会自动读取 `kg-summary.md`,把关键实体与关系带入上下文,避免重复解释背景。

### 场景三:发现孤立知识并补全关系

用户想找出图谱中尚未建立关联的知识点。

```bash
# 列出孤立实体(没有任何关系)
node scripts/query.mjs orphans

# 按类型筛选
node scripts/query.mjs type concept
node scripts/query.mjs cat 技术
```

Agent 会建议如何把这些孤立实体挂到合适的父节点或建立跨分支关系。

## 不适用场景

以下场景知识图谱工具(免费版)不适合处理：

- 实时流数据处理
- 小规模数据手动分析
- 非结构化文本情感分析

## 触发条件

需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。

## 快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

### 依赖详情

```bash
node scripts/install.mjs --workspace /path/to/workspace --platform skill-platform
```

安装脚本会自动检测平台类型(skill-platform / claude / gemini),并对应修改 `AGENTS.md`、`CLAUDE.md` 或 `GEMINI.md`,注入 KG 指令与图谱摘要。脚本是幂等的,可重复运行。

### 2. 基础查询

```bash
node scripts/query.mjs children <id>      # 直接子节点
node scripts/query.mjs type <type>         # 按类型查询所有实体
node scripts/query.mjs cat <category>      # 按分类查询
node scripts/query.mjs orphans             # 孤立实体
node scripts/query.mjs stats               # 图谱统计
node scripts/query.mjs recent [--days 7]   # 最近创建/更新
node scripts/query.mjs timeline           # 时间线
```

### 3. KGML格式速览

```text
#KGML v2 | <实体数>e <关系数>r | depth:<层级> | <日期>
[分类]
标签(别名):类型 — 属性1,属性2
  子标签(CA):类型 — 属性          ← 缩进表示父子关系
%rels
A>动词>B C>动词>D                ← 跨分支关系(使用别名)
%vault key1,key2                 ← 保险库键名(不显示值)
```

**结果处理**: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,查阅错误处理章节获取恢复步骤。


## 示例

### 基础配置查看与修改

```bash
node scripts/config.mjs                       # 列出所有设置及当前值
node scripts/config.mjs get summary.tokenBudget
node scripts/config.mjs set summary.tokenBudget 4000
node scripts/config.mjs reset summary.tokenBudget
node scripts/config.mjs --json                 # 完整配置JSON
```

### 常用设置

| 模块 | 键 | 默认值 | 说明 |
| --- | --- | --- | --- |
| summary | tokenBudget | 5000 | kg-summary.md 最大token数 |
| summary | maxAttrLen | 40 | 属性值最大字符数 |
| summary | maxPerRoot | 4 | 每个根子树最大关系数 |
| validation | minEntities | 30 | 提取通过的最小实体数 |
| validation | minDepth | 3 | 通过的最小层级深度 |
| consolidation | autoNest | true | 自动嵌套单关系孤儿 |
| consolidation | mergeSuggestions | true | 相似标签合并建议 |

配置文件位置:`data/kg-config.json`(按Agent隔离,建议加入gitignore)。

## 最佳实践

### 1. 复杂内容先评估深度

添加复杂内容(论文、报告、系统说明)前,先用深度评估脚本判断应提取多少层。

```bash
node scripts/depth-check.mjs "粘贴文本或摘要"
echo "文章全文" | node scripts/depth-check.mjs
node scripts/depth-check.mjs --file /path/to/article.txt
node scripts/depth-check.mjs --json    # 机器可读格式
```

关键规则:复杂内容不要只提取2层。评分≥4时,应提取所有命名组织、事件、策略与跨关系。

### 2. 区分声明式与过程式知识

`knowledge` 类型同时覆盖声明式与过程式知识,用标签与属性区分:

| 类型 | 标签 | 关键属性 | 示例 |
| --- | --- | --- | --- |
| 事实 | `#fact`, `#til` | source, field, summary | "LLM约4字符/token" |
| 研究 | `#paper`, `#research` | source, field, summary, author | AI对齐论文发现 |
| 想法 | `#idea` | summary, status | "做一个KG查询CLI" |
| 方法 | `#howto`, `#procedure` | steps, context, summary | "如何部署到树莓派" |
| 心智模型 | `#mental-model`, `#framework` | steps, context, summary | "排障:ping→DNS→防火墙" |
| 工作流 | `#workflow` | steps, context, summary | "代码审查:先测试再实现" |

过程式知识属性建议:

- `steps`:有序步骤,用 `→` 或编号(如 `"1.查日志 → 2.复现 → 3.修复 → 4.测试"`)
- `context`:何时何地应用(如 `"网络中断时"`、`"代码审查时"`)
- `summary`:简短说明

### 3. 定期整理

实体数超过80时,运行整理脚本并重新生成摘要。

```bash
node scripts/consolidate.mjs
node scripts/summarize.mjs
```

### 4. 安全原则

- 绝不在聊天中打印保险库值,也不写入 memory 或日志文件
- `vault.enc.json` 与 `.vault-key` 永不进入上下文
- 个人图谱数据建议加入 gitignore,避免泄露

### 5. KGML字段速查

| 字段 | 含义 | 示例 |
| --- | --- | --- |
| `#KGML v2` | 版本标识 | `#KGML v2` |
| `12e 8r` | 实体数与关系数 | `12e 8r` |
| `depth:3` | 最大层级 | `depth:3` |
| `[分类]` | 分类标签 | `[技术]` |
| `标签(别名):类型` | 实体声明 | `依赖注入(DI):pattern` |
| `→` 或缩进 | 父子关系 | 缩进表示子节点 |
| `%rels` | 跨分支关系区 | `A>动词>B` |
| `— 属性` | 属性分隔 | `— 控制反转` |

## 常见问题

### Q1:免费版支持哪些查询?

支持子节点、按类型、按分类、孤立节点、统计、最近、时间线、变更、低置信度等基础查询。合并、保险库、可视化、跨Agent访问等进阶能力需PRO版。

### Q2:KGML摘要会占用多少token?

默认预算5000 token,可通过 `summary.tokenBudget` 调整。实体数超过400时自动进入紧凑模式。

### Q3:免费版能否多Agent共享?

免费版主要面向单Agent。多Agent只读访问(reader.mjs)与跨Agent写入需PRO版支持。

### Q4:免费版与PRO版差异?

| 维度 | 免费版 | PRO版 |
| --- | --- | --- |
| 用户规模 | 单用户 | 团队/多租户 |
| 保险库 | 不支持 | 加密存储与权限 |
| 可视化 | 不支持 | 离线HTML可视化 |
| 多Agent | 单Agent | 跨Agent只读+写入 |
| 内存导入 | 不支持 | 自动导入与低置信度审查 |
| 整理合并 | 基础整理 | 高级合并模式 |
| 支持 | 社区支持 | 优先支持 |

### Q5:数据存储在哪里?

默认存储在 `data/` 目录下的 JSON 文件,按Agent隔离。配置文件为 `data/kg-config.json`,建议加入gitignore避免泄露个人知识。

## 依赖说明

### 运行环境

- **Agent平台**: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
- **操作系统**: Windows / macOS / Linux
- **Node.js版本**: 建议 18 LTS 及以上(用于运行 `.mjs` 脚本)

### 第三方依赖

| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent内置LLM提供 |
| Node.js | 运行时 | 必需 | nodejs.org 下载 |
| npm | 包管理器 | 必需 | 随Node.js安装 |

### API Key 配置

- 本skill基于Markdown指令规范,无需额外API Key(除内容中明确标注的外部API)。
- 个人知识图谱数据本地存储,不上传任何外部服务。

### 可用性分类

- **分类**: MD+EXEC(纯Markdown指令,部分功能需exec命令行执行)
- **说明**: 基于Markdown的AI Skill,通过自然语言指令驱动Agent完成操作。免费版聚焦个人单Agent的本地知识图谱管理。

## 错误处理


| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |

## 已知限制

- 本地运行，不支持多设备同步