Joffoo's blog

The ethereal flight, oft rehearsed in the theater of one's dreams...

从一个想法到上架 Obsidian 官方社区:我用 AI 做了一款“知识地貌”插件

今年 4 月,看到 flomo 作者少楠在小红书分享了“笔记向量化后做成知识地图”的思路。当时受到启发,便抢先做了一版 Skill,供 Agent 在本地笔记库中使用。

最近,我更新了几种视觉风格,顺便把它做成了原生的 Obsidian 插件。目前插件已经上架至 Obsidian 官方社区插件市场,搜索 Knowledge Topography 即可下载使用。

阅读指引
本文兼顾普通笔记用户的使用与开发者的制作复盘:

  • 如果你想了解实际视觉效果与交互功能,请看第一部分;
  • 如果你需要安装与模型配置步骤,请跳至第二部分;
  • 如果你对如何借助 AI 从零写插件并上架官方社区感兴趣,请直接阅读第三部分。

一、 效果与交互:知识库的另一种展开方式

进入使用界面,这是完整构造出知识地貌图后的效果:

目前插件支持 7 种视觉风格的切换:

在节点生长动画模式下,可以看到笔记随着时间推移逐步点亮整张地貌:

1. 和官方“关系图谱”的区别

严格来说,它并非不可或缺的高频生产力工具,和官方核心插件“关系图谱”类似,最大的作用更接近于“美化您的生活”。

但两者在组织逻辑上有明显区别:

  • 官方关系图谱基于你手动添加的“双向链接”,呈现的是点与点之间的连线;
  • 知识地貌基于文本的嵌入向量(Embedding),把语义相近的笔记自动聚拢成一座座“山峰”。哪怕有些笔记之间你从未手动建立双链,只要讨论的主题接近,它们就会在地貌上成为邻居。

另外,官方核心插件“关系图谱”在笔记变多后往往不够美观。

如果既想看语义分布,又想保留双链关联,可以点击面板中间的“显示双链网络”,直接在山峦之上叠加连线:

2. 细节检索与局部观察

在左上角搜索框输入关键词,可以做模糊检索。点击某篇笔记后,地图会自动聚焦并放大局部地貌。右侧面板会联动展示该笔记所属的聚类主题、语义相近的邻近笔记,以及已有的双向链接。


二、 如何配置

在 Obsidian 内安装插件后,进入 设置 - 第三方插件 - Knowledge Topography。插件主要依赖两项 AI 能力:向量嵌入模型(Embedding) 与 大语言模型(LLM)。

1. 向量模型配置

  • 注重隐私:选择本地运行模式,填入本地 ONNX 离线模型的存放路径即可,数据全程不离开本地设备。

  • 追求快捷:选择在线服务模式,直接填写服务地址与 API Key。比如可以使用硅基流动等平台上免费提供的 bge-m3 模型,无需本地显卡算力。

2. 大语言模型配置

向量模型负责计算笔记坐标与聚类。聚类完成后,插件会调用一次大语言模型,为地图上的各个“知识山峰”提炼并生成领域名称:

3. 其他配置

在常规配置中,还可以设置:

  • 排除目录:建议排除模板文件夹(如 _templates)或附件文件夹(_attachments),避免无意义文件干扰聚类;
  • 读取字数:控制每篇笔记参与向量计算的字数,在扫描速度与语义精度之间取得平衡。


三、 如何借助 AI 编写并发布 Obsidian 社区插件

整个制作与上架过程主要借助了 AI Coding Agent,大致流程如下:

1
2
3
4
5
6
7
8
9
[已有 Python Skill]
↓
[Agent 原型转换] 借助 qiaomu-obsidian-dev 规范,将逻辑转写为 Obsidian 插件 TypeScript 原型
↓
[增量迭代交互] 逐步补充 UI、7种视觉风格切换、搜索与双链图层
↓
[GitHub Release] 打包发布构建产物(main.js / manifest.json / styles.css)
↓
[Obsidian 社区提审] 在 community.obsidian.md 提交仓库链接,根据自动化检查结果由 Agent 修复

1. 从 Skill 到插件原型

在开发初期,我主要参考了“向阳乔木”的插件开发经验,为 Agent 加载了他编写的技能 qiaomu-obsidian-dev。

先让 Agent 根据之前写好的 Skill 核心逻辑跑出一个插件最小可行版本(MVP),验证视图挂载与渲染是否正常;随后再通过日常体验,把想到的交互细节(如局部聚焦、双链图层、多风格切换)逐项追加并调试。

2. 准备仓库与 Release

插件调试稳定后,新建一个公开的 GitHub 仓库,让 Agent 将代码同步上去并发布正式的 Release。

发布 Release 时需要注意包含构建打包好的 main.js、manifest.json 与 styles.css,并确保 Release 的 tag 版本号与 manifest.json 中的 version 完全一致。

3. 提交社区审核

登录 Obsidian 社区开发者平台,点击 New plugin,按提示填入 GitHub 仓库地址:

提交后,平台的自动化流水线会进行第一轮静态检测(例如检查文件遍历方式、网络请求合规性、文件命名与打包完整度等)。

初次检测往往会出现提示或校验未通过的情况。解决方法很简单:直接把报错和建议信息原样复制给 Agent,让其按规范修复代码后重新打 Release。

4. 后续版本更新

后续迭代新功能时,提醒 Agent 递增版本号并重新打 tag,在 Obsidian 社区插件管理后台点击 Check for new releases,系统便会自动检测并拉取最新版本。


四、 项目开源地址

本插件的完整源码与最初的 Skill 版本均已开源,欢迎体验与交流。

文章目录

  1. 一、 效果与交互:知识库的另一种展开方式
    1. 1. 和官方“关系图谱”的区别
    2. 2. 细节检索与局部观察
  2. 二、 如何配置
    1. 1. 向量模型配置
    2. 2. 大语言模型配置
    3. 3. 其他配置
  3. 三、 如何借助 AI 编写并发布 Obsidian 社区插件
    1. 1. 从 Skill 到插件原型
    2. 2. 准备仓库与 Release
    3. 3. 提交社区审核
    4. 4. 后续版本更新
  4. 四、 项目开源地址

Proudly powered by Hexo and Theme by Hacker
© 2026 Fengyukongzhou