快速开始

在浏览器里试试

Playground（在线试用）可以比较示例数据，也可以比较你自己的两个文件，全程在浏览器里完成，不会上传任何数据。想快速了解 kgdiff 能报告什么、查看器能做什么，这是最快的方式。

安装命令行工具

kgdiff 需要 Node.js 22 或更高版本。不安装也能直接运行：

npx @kgdiff/cli before.ttl after.ttl

也可以安装：

npm install --global @kgdiff/cli     # 全局可用的 kgdiff 命令
npm install --save-dev @kgdiff/cli   # 在项目里固定版本，用 npx @kgdiff/cli 运行

第一次 diff

本页的例子使用仓库示例数据里的企业信用知识图谱本体：v12 和 v13 两个版本，JSON 格式。你自己的图的任意两个版本用法完全一样：kgdiff 会根据文件名和内容判断格式（见格式）。

kgdiff before.json after.json

kgdiff  企业信用知识图谱本体 v12 → v13                                节点 74 · 关系 171

  +1 新增   −1 删除   ~6 修改   ⇄4 结构调整                            12 组共 23 处变化
  ++++−−−~~~~~~~⇄⇄⇄⇄⇄⇄⇄⇄⇄

  删除 1
  − 删除「抽查检查」及 2 条关系                                 删除 · 类型 事件 · 原关…
  结构调整 4
  ⊕ 「法人代表」合并入「法定代表人」                            身份 · 依据替代声明 ·…
  ⇄ 「股权出质」移至「股权投资」下                              结构 · 原属「经营风险」
  ⇄ 「十大股东」的「持股」改为指向「上市公司」（原为「企业」…   结构 · 关系改为指向新节…
  ⇄ 新增关系「实际控制」—穿透依据→「投资」                      结构 · 新关系
  修改 6
  ~ 修改「企业」                                                内容 · 属性 +2 −1 · 关…
  ~ 弃用「中外合资企业」                                        内容
  ~ 修改「商标」的属性                                          内容 · 属性 ~1
  ~ 修改「失信被执行人」的别名                                  内容 · 别名 +1 −1
  ~ 「高管任职」改名为「董监高任职」                            内容 · 别名 +1
  ~ 修改「限制高消费」的类型                                    内容 · 类型 +1 −1
  新增 1
  + 新增「受益所有人」及 3 条关系                               新增 · 类型 角色 · 关联…

从上往下看：

• 标题行：两张图的名称和版本（取自图的元数据，没有时用文件名），以及各自的节点数和关系数。

• 计数：每类变更组的数量；右侧是一共多少处变化、分成了多少组。下面的条形图显示同样的比例。

• 变更组：每行一个变化，用你描述它时会用的说法写出来。它们按最便于阅读的顺序分组（删除、结构调整、修改、新增），行首符号和右侧第一个词标明变化所属的类别：

  符号	类别	包括
  +	新增	新节点及其关系
  −	删除	删掉的节点及其关系
  ~	内容	改名、属性、类型、别名
  ⇄	结构	层级中的迁移、关系的变化
  ⊕ ⑂	身份	合并和拆分

为了放进终端，过长的行会被截断；--name-status 和下面其他输出会显示完整标题。

打开交互式报告

kgdiff before.json after.json -o report.html --open

这条命令会写出一个 HTML 文件并在浏览器中打开。查看器和 diff 都在这个文件里，所以报告可以离线使用，可以附在 issue 里、作为 CI 的工件保存，也可以当作静态页面发布。

在报告里：

• 用 1 到 4 切换四种视图：叠加（两个版本画在同一张图上）、滑动对比（拖动分隔线对比前后）、回放（旧图逐组变成新图）和仅看变更（用于大图）。
• 用 j 和 k 逐个浏览变化，用 x 标记已审阅，用 / 搜索。
• 选中一个变化，可以看到每个标签、属性和关系在变化前后的样子。
• 按 ? 查看全部快捷键。

查看器：交互与 API 介绍了查看器的全部功能。

其他输出

选项	输出
--stat	计数、节点 / 关系统计表，以及按节点类型的统计
--name-status	每组一行：字母、节点 id 和标题（输出到管道时为 TSV）
--markdown [file]	GitHub 风格的 Markdown，用于 PR 评论和作业摘要
--json [file]	完整的 diff，机器可读
--delta [file]	可反向应用的增量补丁，供 kgdiff apply 使用
-o, --html <file>	交互式 HTML 报告

kgdiff before.json after.json --stat

kgdiff  企业信用知识图谱本体 v12 → v13                节点 74 · 关系 171

  +1 新增   −1 删除   ~6 修改   ⇄4 结构调整            12 组共 23 处变化
  ++++−−−~~~~~~~⇄⇄⇄⇄⇄⇄⇄⇄⇄

        新增  删除  修改  未变
  节点     1     1     9    64
  关系     4     4     4   163

  按类型
  角色  4 +~~~
  主体  2 ~~
  事件  2 −~
  关系  1 ~
  措施  1 ~
  资产  1 ~

多种输出可以组合：kgdiff a.ttl b.ttl -o report.html --markdown summary.md 会写出两个文件，同时照常打印摘要。最多只能有一种输出写到标准输出。

选择节点的匹配方式

--match 决定新版本里的哪个节点和旧版本里的某个节点是“同一个”：

• auto（默认）：先按相同的 id，再按替代声明，剩下的节点按标签和邻居结构的相似度匹配。
• id：只按 id 和替代声明匹配。适合 id 有权威性的场合，比如本体，见本体。
• similarity：忽略 id。适合 id 是随机生成的场合，比如 LLM 抽取的结果，见没有稳定 id 的图。

在脚本中使用

--exit-code 让 kgdiff 在两张图不同时以 1 退出，和 git diff --exit-code 一样；-q 关闭标准输出：

kgdiff committed.ttl regenerated.ttl --exit-code -q && echo "没有变化"

退出码	含义
0	成功（带 --exit-code 时：两张图相同）
1	两张图不同（仅在带 --exit-code 时）
2	用法或输入错误，原因写在标准错误中

下一步

• 在 CI 中审阅变更：每个 PR 上都有摘要和评论，报告作为工件保存。
• 配合 git 使用：让 git diff 和 git difftool 用上 kgdiff。
• 命令行参考：全部选项。