Joplin Graph 插件问题与本地优化记录

日期：2026-06-26

背景

当前使用的 Joplin 图谱插件：

  • 插件名：Graph
  • 插件 ID：joplin-plugin-knowledge-graph
  • 版本：1.1.0
  • 插件包路径：<LOCAL_PATH>

原插件中，打开笔记的交互不是双击，而是：

  • 普通单击：选中节点
  • Shift + 单击：多选节点
  • Ctrl/Meta + 单击：打开对应 note

已实现的本地优化

在当前本机插件包中增加了以下功能：

  1. 双击打开 note

    • 双击普通 note 节点会打开对应 Joplin 文档。
    • 原来的 Ctrl + 单击 打开逻辑仍保留。
    • tag 节点不会按 note 打开。

  2. 悬浮预览

    • 鼠标悬浮节点时，右上角显示节点信息。
    • 显示内容包括：标题、类型、出入链数量、标签、ID。

  3. 搜索定位节点

    • 图左上角新增 Search note... 输入框。
    • 输入标题关键字后会定位并高亮匹配节点。
    • 回车也可触发定位。

  4. 当前 note 局部图 / 全局图切换

    • 图左上角新增 Local 按钮。
    • 开启后只显示当前选中 note 及其一跳邻居。
    • 再次点击恢复全局图。

  5. 保存节点布局

    • 新增 Save layout 和 Reset layout 按钮。
    • 拖动节点结束时会自动保存位置。
    • 下次打开图谱会尝试复用保存的位置。

后续修复：普通点击不再触发布局重跑

问题现象：

  • 每点击一次节点，Layout Status 都会重新运行。

原因：

  • 初版补丁中，普通点击节点时调用了 GraphEnhance_syncLocalFilter()。
  • 该函数内部无条件执行 didGraphDataUpdate(buildGraphData())。
  • 这会把图数据重新喂给 force-graph，导致 force simulation 重新启动。

修复后逻辑：

  • 普通单击：只选中/高亮节点，不重跑 layout。
  • 双击打开：只打开 note，不重跑 layout。
  • 搜索定位：只居中/缩放到节点，不重跑 layout。
  • Local 开启：会重建局部图，重跑 layout，这是正常的。
  • Local 关闭：会恢复全局图，重跑 layout，这是正常的。
  • Joplin 数据变化、过滤条件变化、Reset layout：仍会重跑 layout，这是正常的。

Layout Status 的含义

Layout Status 是 force-graph 的力导向布局进度条。

当节点或连线集合发生变化时：

1
2
3
4
节点/连线数据变化
  -> force simulation 重新启动
  -> Layout Status 开始变化
  -> 引擎停止后变成 100%

因此以下操作触发布局重跑是正常的：

  • 初次打开图谱
  • 切换过滤条件
  • 显示/隐藏 tag 节点
  • 切换局部图/全局图
  • Reset layout
  • Joplin 笔记或链接数据变化

普通点击节点不应该触发布局重跑，已修复。

连线颜色含义

插件里的连线颜色主要表达“关系状态”，不是严格的关系类型。

常见含义：

  • 普通蓝色/淡蓝色线：普通 note link，表示笔记之间的链接关系。
  • 高亮蓝色/亮色线：当前选中或悬浮节点相关的一跳关系。
  • 变淡/透明线：当前不是焦点关系，被弱化显示。
  • 橙色/深橙线：tag 节点相关关系。
  • 流动粒子/小点：点击或悬浮节点时显示的方向提示，不是新增关系。

Joplin note 链接本质上有方向：

1
A 笔记里写了 [B](Joplin note id)

图上对应：

1
A -> B

粒子动画可用于观察链接方向。

插件包与备份

活动插件包：

1
<LOCAL_PATH>

重要备份：

1
2
<LOCAL_PATH>
<LOCAL_PATH>

其中：

  • bak-graph-enhance-20260626_102539：添加五个增强功能之前的备份。
  • bak-no-layout-on-click-20260626_105417：修复“普通点击触发布局重跑”之前的备份。

验证记录

执行过的验证：

  • 补丁前测试确认增强功能标记不存在。
  • 补丁后测试确认五类功能标记存在。
  • node --check 检查 webview.js 和 index.js 语法通过。
  • 解包活动 .jpl 后确认补丁内容已写入。
  • 针对“普通点击不应重建图”增加回归测试。
  • 回归测试先失败，修复后通过。

使用注意

每次修改插件包后，需要：

  • 重启 Joplin；或
  • 禁用再启用 Graph 插件。

否则 Joplin 可能仍使用旧的已加载插件代码。

后续可扩展方向

可以继续考虑：

  • 右键菜单：打开、复制 note 链接、复制标题、复制 Joplin 内链。
  • 节点颜色按 notebook/tag/status 区分。
  • 边类型增强：区分 note link、tag link、backlink、双向链接。
  • 更好的 hover 预览：加入 note 摘要、更新时间、notebook 路径。
  • 保存布局导入/导出，便于迁移。
  • 孤立节点隐藏。
  • 最近修改节点高亮。
  • 断链检查。
  • 两个 note 之间的路径查找。