Jeong-jin-Han/NodeGraph

利用 AI 将研究论文转化为可验证的知识图谱。

将 AI agent（Claude Code、Codex、Cursor、Antigravity）指向一个 PDF，它就会阅读论文并自行构建整个图谱，将每个论断链接回其出处原文。更愿意自己动手构建？创建一个空白的 `.nodegraph.json` 文件，手动使用同样互动的画布，完全无需 agent。

不要盲信 AI 摘要。一键针对原始论文验证每一个论断。

## 快速一览

An agent reading a paper it had never seen before and building the full nodegraph end to end, sped up — see Benchmark below for the real numbers

**只需四个步骤即可完成：** 1. 从 VS Code Marketplace 安装 **NodeGraph** 2. 右键点击你的论文所在文件夹，并运行 `NodeGraph: Copy Agent Spec to Workspace` 3. 将生成的 `.prompt/english.md`（或 `korean.md`）粘贴到你的 agent 中，并填入 PDF 的路径 4. 打开生成的 `.nodegraph.json` 文件 ## 适用场景 - **真正理解一篇论文**，而不是走马观花，通过将论证过程还原为其所收敛自的发散思想 - **没有幻觉风险的 AI 辅助笔记**，因为每一个论断都可以追溯到确切的来源引文 - **充满公式和表格的论文**，其他笔记工具会搞乱表格内的 LaTeX，而本工具不会 - **在 VS Code 之外分享笔记**，因为每个图谱都可以导出为一个独立的 HTML 文件，无需安装扩展 ## 动机 写论文意味着首先**发散**（探索分支、死胡同、替代框架），然后将其**收敛**成一个干净、线性的叙述。真正剖析一篇论文，理解*为什么*做出了这个选择而不是另一个，意味着反向执行这个过程：将收敛后的文本重新拆解回它所源自的发散思想。这天然就应该是**一个节点图，而不是线性文档**。这也正是最初采用这种思维导图形式的原因。 现有工具并不能完全胜任。Obsidian 风格的 Markdown 笔记非常适合关联想法，但 **LaTeX 无法在表格中渲染**，这对于那些对比表格中充满符号的论文来说是个真正的阻碍。NodeGraph 将这些工具的优势融合到一个单独的节点中：GFM 表格、LaTeX（通过 KaTeX 渲染）和内联图片都可以在同一张卡片中一起渲染。 它还围绕**使用 agent 而非鼠标操作**而设计。在阅读时手动放置每个节点非常繁琐，足以打断思维的连贯性。相反，将 agent 指向内置的 `.agent/NODEGRAPH_SPEC.md` 文件，它就能（基于你当前向它提出的问题）决定新想法应归属于图谱的哪个位置，并自行在那里写入节点，因此与 agent 的对话可以直接转化为结构，而不必停下来手动归档每个笔记。 由 agent 代写笔记会引发一个显而易见的担忧：幻觉。这正是 **Original 标签**存在的意义所在。每个论断都可以承载其所依据的确切源文本引文，点击它即可直接跳转到源 PDF 并高亮匹配的句子，这样你就可以**一键针对论文验证 agent 的论断**，而不是盲目信任它。 既然你并不总是希望在 VS Code 中重温自己的笔记，因此每个图谱都可以**导出为一个独立的 HTML 文件**。在任何浏览器中打开它，无需安装扩展。 ## 截图

Editor and exported HTML side by side — same layout, same content

Debug grid and Ctrl+F search
hop-level/main-topic-cluster boundaries, plus in-canvas search with matching nodes highlighted, in both the editor and the export

PDF quote-jump
right-click an original-text quote to open the source PDF and highlight the matching sentence (red box/arrow added for illustration)

## 功能 | | | |---|---| | **丰富的节点内容** | Markdown (GFM) 表格、通过 KaTeX 渲染的 LaTeX、内联图片以及可折叠的展开/收起部分 — 全都使用同样强大的渲染器 | | **无重叠的层级布局** | 以每个主要主题的层级树为键的自下而上/自上而下自动布局 — 展开一个节点只会扩展其自身的分支，绝不会干扰同级节点 | | **智能连线布线** | A* 算法布线的骨干连线，避开节点边界，并在多条连线共享端点时自动分散；层级子节点的连线为锚定在正确侧边的笔直直线 | | **PDF 引文跳转** | 右键点击原文引文，即可打开源 PDF、跳转到相应页面并高亮匹配的句子 | | **Ctrl+F 搜索** | 以下拉菜单形式对标题、内容、原文和展开/收起部分进行 BFS 顺序排序，并带有内联匹配高亮 | | **调试网格** | 一键显示层级和主要主题集群边界的网格覆盖，便于直观地发现布局问题 | | **HTML 导出** | 一个独立、互动的独立查看器 — 包含搜索、高亮和布局功能 | | **Agent 友好** | 一份机器可读的规范 (`.agent/NODEGRAPH_SPEC.md`)，使 AI agent 能够直接读取和生成图谱 | 有关按 编辑 / 布局与连线 / 查找与聚焦 / 图片 / 文件与导出 分类的完整功能列表，请参阅 **[FEATURES.md](https://github.com/Jeong-jin-Han/NodeGraph/blob/main/docs/FEATURES.md)**。 ## Agent / AI 编辑 文件 `.agent/NODEGRAPH_SPEC.md`（包含在扩展中）是为 AI agent 准备的机器可读规范。它记录了完整的 JSON schema、ID 约定、KaTeX/Markdown 语法规则、各字段的渲染支持，以及如何从 PDF 生成 nodegraph 的分步工作流程。 扩展内置了五个完全由 agent 构建的图谱，因此你可以在自己构建之前先查看一个已完成的结果：`demo/ex1`（"Attention Is All You Need"）、`demo/ex2`（"Point Transformer"）、`demo/ex3`（"Mooncake"）、`demo/ex4`（"3D Gaussian Splatting"）和 `demo/ex5`（"Mental Illness Terms and Hermeneutic Hijacking"，这是一篇哲学论文，而不仅限于计算机/机器学习）— 它们涵盖了 KaTeX 公式、Markdown 表格、展开/收起部分以及深度问题节点。 **典型的 agent 工作流程：** 1. 在资源管理器中右键点击项目文件夹，并运行 `NodeGraph: Copy Agent Spec to Workspace`（每个文件夹仅需一次）。如果你将该文件夹本身作为工作区根目录打开，VS Code 将不会在其上直接显示右键菜单，请改为右键点击文件列表下方的空白处 2. 告诉你的 agent 读取 `.agent/NODEGRAPH_SPEC.md` 和 `.agent/ENVIRONMENT.md` 3. 读取或创建目标 `.nodegraph.json` 文件 4. 直接编辑 JSON 5. 点击工具栏中的 **Reload**，无需关闭/重新打开文件即可查看更新后的图谱 ### 示例 prompt 英文 | 한국어 在包含你 PDF 的文件夹（即上文的第 1 步）上运行 `NodeGraph: Copy Agent Spec to Workspace` 后，将此内容粘贴到你的 agent 中 — 填入路径，它会完成剩下的工作：读取规范、阅读论文并构建图谱，无需进一步的反复沟通。同样的命令也会将此内容作为 `.prompt/english.md`（以及韩语版本的 `.prompt/korean.md`）写入该文件夹中，因此你可以直接打开该文件，而无需从这里复制。 ``` PDF_ABSOLUTE_PATH = PROJECT_FOLDER = dirname(PDF_ABSOLUTE_PATH) PROJECT_FOLDER/.agent/NODEGRAPH_SPEC.md and PROJECT_FOLDER/.agent/ENVIRONMENT.md are already prepared for you — read both in full. Based on the paper and those two files, briefly explain what kind of nodegraph you can build from it. This extension ships a worked example at demo/ex1/attention-is-all-you-need.nodegraph.json (inside its own install folder) as a reference for depth/structure — check it if useful, then build ours the same way for this paper. Write all node content in English. Follow the spec exactly, save the result inside PROJECT_FOLDER, and run end to end without asking me anything. Tell me when done. ```

| 示例 | 论文 | Agent | 时间 | Token | |---|---|---|---|---| | `demo/ex2` | [Point Transformer](https://arxiv.org/abs/2012.09164) | Opus 5 | ~16 分钟 | ~65k | | `demo/ex3` | [Mooncake](https://arxiv.org/abs/2407.00079) | Opus 5 | ~10 分钟 | ~40k | | `demo/ex4` | [3D Gaussian Splatting](https://arxiv.org/abs/2308.04079) | Opus 5 | ~11 分钟 | ~45k | | `demo/ex5` | [Mental Illness Terms and Hermeneutic Hijacking](https://philarchive.org/rec/KEIMIT) | Opus 5 | ~11 分钟 | ~40k | `demo/ex5` 是一篇哲学论文，而非计算机/机器学习论文，包含它是为了展示该工作流程不仅限于具有方法/结果结构的实证论文 — agent 使用了相同的默认节点模板，并且效果依然很好。 上面的 `demo/ex4` 运行记录于 **v0.6.3** 版本，完全按照上述四个步骤中的说明使用了 `NodeGraph: Copy Agent Spec to Workspace` — 无需复制粘贴 README，无需手动设置。 [观看完整的 demo/ex4 运行过程（59秒，无声）](https://github.com/Jeong-jin-Han/NodeGraph/blob/main/resources/demo-ex4.mp4) ## 鼠标与键盘控制

完整控制参考（画布、节点、工具栏、搜索）

### 画布 | 操作 | 控制 | |--------|---------| | 平移画布 | 在背景上左键拖拽 | | 取消选择 / 关闭搜索 | 在背景上左键点击 | | 缩放 (0.05×–8×) | 滚轮 — 以光标为中心 | | 框选节点和图片 | 在背景上右键拖拽 | | 选择节点 | 左键点击节点上的任意位置 | | 添加到选区 | `Shift`/`Ctrl`+点击 | | **拖拽节点** | **左键拖拽标签徽章**（例如 "Gap / Idea"）— 放下后会根据其落点在具有相同父节点、相同侧边的同级节点中重新排序，而不是仅仅将其放置在自由位置；如果是多选，所有选中的节点将一起移动（不进行单个节点放下时的重新排序） | | 固定生成高亮 | 点击标签徽章 — 节点 + 父节点 + 子节点 + 连线变红 | | 清除高亮 / 选区 | `Escape`（点击背景会保持高亮） | | 删除所选内容 | `Delete` 或 `Backspace` — 优先删除画布图片，然后是选中的连线，最后是节点 | | 选择连线 | 左键点击连线（变蓝） | | 绘制边缘 | 从一个端口圆点（悬停时出现）拖拽到另一个节点的主体上，方向不限 — 仅在两个 Main topic 节点之间会变成箭头，其他情况则为普通线条 | ### 节点 | 操作 | 控制 | |--------|---------| | **折叠 / 展开内容** | **点击节点标题** | | **编辑节点标题** | **右键点击节点标题** | | 编辑内容 / 原文 | 点击文本区域 | | **在 PDF 中搜索原文引用** | **右键点击原文引文**（需要 `source.pdf`） | | 添加图片 | 复制一张图片，然后在选中或悬停节点时按 `Ctrl+V` — 作为 `[[IMG:...]]` token 插入；在背景上粘贴会创建一个浮动的画布图片，可以将其拖拽到节点或表格单元格中 | | 添加折叠项 / 原文 / 链接 | 展开节点底部的 `+ Toggle` · `+ Original` · `+ Link` 按钮 | | 调整节点大小 | 拖拽展开节点的右侧 / 底部 / 角落手柄（最小 160×60） | ### 工具栏 工具栏分为两行 — 顶部是编辑控制，下方是视图/图谱导航控制： | 行 | 控制 | 描述 | |-----|---------|-------------| | Edit | Undo / Redo | 历史记录（也可使用 `Ctrl+Z` / `Ctrl+Y` / `Ctrl+Shift+Z`） | | Edit | 模板下拉菜单 + `+ Add Node` | 当恰好选中一个节点时，向其添加所选类型的子节点（自动定位到层级布局中）；当未选中或选中多个节点时，在视图中心最近的空白处创建一个无父节点的节点 | | Edit | Delete | 删除所有选中的节点（一旦选中多个节点，会显示实时计数，例如 `Delete (3)`） | | Edit | 类型和字体控制 | 选中节点时显示 — 切换节点的模板；通过输入数字或选择预设来设置字体大小 (8–72) | | View | Collapse / Expand | 折叠/展开选中的子树，未选中任何内容时则应用于所有节点 — 折叠*所有内容*时还会自动执行 Fit View | | View | 节点类型过滤器（位于 Collapse/Expand 旁边） | 当设置为某种类型而非 `None` 时：`Collapse` 会关闭所有内容，`Expand` 仅打开该类型的节点并关闭其余节点 | | View | Fit View | 缩放以适应所有节点 | | View | Grid | 切换布局调试网格（层级垂直线，主要主题集群水平线） | | View | Export HTML | 在 JSON 文件旁写入 `.html` | | View | Reload | 从磁盘重新读取 JSON | | View | Help | 在编辑器旁边的 Markdown 预览中打开内置 README 的 Features 部分 | 当窗口比工具栏内容更窄时，两行会一起水平滑动（`Shift`+滚轮或滑动） — 按钮位置绝不会改变。 ### 搜索 (Ctrl+F) | 操作 | 控制 | |--------|---------| | 打开搜索 | `Ctrl+F`（或在 Mac 上使用 `Cmd+F`） | | 关闭搜索 | `Escape` 或 ✕ 按钮 | | 导航结果 | `↑` / `↓` — 移动下拉菜单高亮显示**并**将视口飞至该节点 | | 选择节点 | `Enter` — 展开选中的节点，折叠其他匹配项 | | 选择后重新打开 | 点击搜索输入框 — 从上次选中的位置继续 | 每个节点内匹配的文本都会被额外标记（模板颜色的反色 + 下划线），因此你可以看到查询出现在节点的*什么位置* — 无论是在编辑器中还是在导出的 HTML 中。

## 安装说明 从 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=JeongjinHan.nodegraph) 安装 **NodeGraph**，或者在 VS Code 的 Extensions 视图 (`Ctrl+Shift+X`) 中搜索 "NodeGraph" 并点击 Install。如果你更愿意直接安装，本仓库内也提供了一个打包好的 `.vsix` 文件 (`packages/nodegraph-.vsix`)。

入门指南

1. 运行 **NodeGraph: New Graph** (`Ctrl+Shift+P`) 创建一个 `.nodegraph.json` 文件 — 或者打开一个现有的文件，自定义编辑器会自动打开 2. 通过彩色的标签徽章**拖拽节点**；**点击标题**进行折叠/展开；**右键点击标题**进行重命名 3. 使用工具栏 — **Expand / Collapse / Fit View / Export HTML / Reload / Help** — 以及 **Ctrl+F** 进行搜索 直接从 `.vsix` 安装： ``` code --install-extension packages/nodegraph-.vsix ``` 自行构建 `.vsix`： ``` npm install node esbuild.js --production npx vsce package -o packages/nodegraph-.vsix ```

## 节点内容语法 | 功能 | 语法 | |---------|--------| | Markdown 表格 | `\| col \| col \|` (GFM 样式) | | 行内 LaTeX | `$formula$` | | 块级 LaTeX | `$$formula$$` | | 粗体 | `**text**`（渲染时隐藏标记） | | 字面美元符号（货币） | `\$` — 单个 `$` 会开启一个行内数学公式区域（在 JSON 字符串中写为 `\\$`） | | 图片 token | `[[IMG:filename.png:400x300]]` | 图片存储在 JSON 文件旁的 `.-imgs/` 文件夹中。 ## 文件格式

完整 JSON schema 示例

``` { "version": "1.0.0", "title": "My Research Graph", "created": "2026-07-06T00:00:00.000Z", "modified": "2026-07-06T00:00:00.000Z", "source": { // optional — omit entirely if there's no source PDF "pdf": "paper.pdf", "authors": "Author et al.", "venue": "NeurIPS 2017", "doi": "arXiv:1706.03762", "pages": 15 }, "nodeTemplates": { "main_topic": { "label": "Main topic", "color": "#4B8BBE", "icon": "file-text", "shape": "sharp" }, "question": { "label": "Question", "color": "#E5A835", "icon": "help-circle", "shape": "rounded" } }, "nodes": [ { "id": "node_001", "template": "main_topic", "title": "Introduction", "content": "Summary text with $\\LaTeX$ and\n[[IMG:figure1.png:500x300]]", "original": { "title": "Optional custom label", "text": "Exact quote from paper.", "location": "§1, p.1" }, "toggleItems": [ // optional — omit if the node has no toggle sections { "id": "toggle_001", "title": "Table 1", "content": "| Col | Val |\n|-----|-----|\n| A | 1 |", "expanded": false } ], "contentExpanded": true, "originalExpanded": false, "childrenExpanded": false, "position": { "x": 0, "y": 0 }, "children": ["node_002"], "links": [], // { type: 'url'|'pdf'|'obsidian'|'internal', target, label }[] "fontSize": 14, // optional — per-node title font size override "nodeWidth": 432, // optional — persisted card width after a manual resize "nodeHeight": 220, // optional — persisted card height after a manual resize "nodeNaturalY": 0 // optional — Y position as last set by dragging; leave this to the editor } ], "edges": [ { "id": "edge_001", "source": "node_001", "target": "node_002", "type": "arrow", "label": "" }, { "id": "edge_002", "source": "node_002", "target": "node_003", "type": "line", "label": "" } ], "viewport": { "x": 0, "y": 0, "zoom": 1 }, "canvasImages": [] // optional — floating images pasted onto the background, not into a node } ```

## 命令 | 命令 | 快捷键 | 描述 | |---------|----------|-------------| | `NodeGraph: New Graph` | — | 创建一个新的空白图谱。在资源管理器中右键点击文件夹可直接将其作为目标；从命令面板调用时，它将以工作区唯一的文件夹为目标，如果有多个文件夹，则会提示你选择一个 | | `NodeGraph: Search Nodes` | `Ctrl+F` / `Cmd+F` | 打开搜索下拉菜单 | | `NodeGraph: Copy Agent Spec to Workspace` | — | 将 `.agent/NODEGRAPH_SPEC.md`、`.agent/ENVIRONMENT.md` 和 `.prompt/{korean,english}.md` 写入文件夹，以便 AI agent 读取。其文件夹定位方式与上面的 New Graph 相同 | ## 技术栈 | 层级 | 技术 | |---|---| | 平台 | VS Code Extension (Custom Editor API) | | UI | React + TypeScript | | 数学 / 渲染 | KaTeX，自定义 Markdown-lite 渲染器，SVG 连线布线 (A* 算法) | | PDF | `pdfjs-dist`（自定义最小渲染器，而非预构建的查看器工具包） | | 构建 | esbuild | | 存储 | 磁盘上的纯 JSON 文件 (`.nodegraph.json`) — 无需账户，无需外部服务 | ## 隐私 NodeGraph **不会**收集、存储或向外部服务器传输任何数据。 - 所有内容都位于 `.nodegraph.json` 文件及其旁边的本地图片资产中 — 没有账户，没有遥测，没有数据分析 - 编辑器从扩展自身内置的资产中加载 KaTeX（无 CDN，无网络连接） - 唯一的例外：在浏览器中打开**导出的 HTML 文件**时会从 CDN 加载 KaTeX，因为该文件旨在 VS Code 之外查看 — 编辑器本身绝不会这样做

标签：AI 辅助阅读, Homebrew安装, SOC Prime, VS Code 扩展, 多模态安全, 学术研究, 开发工具, 文档解析, 自动化攻击, 防御加固