Obsidian XR

Obsidian XR 是一个本地运行的 Obsidian Markdown Vault 可视化项目。它会读取 Vault 中的 .md 文件，解析笔记之间的链接关系，并把这些关系渲染成可交互的 2D 图谱、3D 空间图谱，以及可进入 WebXR 的 VR/AR 场景。

项目目前保留两个可运行版本：

xr_node：当前主版本，包含最近优化过的 2D/3D/VR 体验、测试 Vault、桌面 3D 预览和自动化调试状态。
obsidian-xr：早期保留版本，适合对照原型结构、查看旧版单页实现，或在需要回退时参考。

核心功能

读取 Obsidian Vault：递归扫描 Vault 内的 Markdown 文件，并忽略 .obsidian 配置目录。
构建笔记关系图：将每个 Markdown 文件变成一个节点，根据笔记链接生成边。
解析 Obsidian 链接：支持 [[Note]]、[[Note|Alias]]、[[Note#Heading]] 这类常见 wikilink 写法。
解析 Markdown 链接：支持 [title](path.md) 形式的相对 Markdown 链接。
2D 图谱浏览：在桌面浏览器中查看节点、连线、文件树和笔记内容。
3D 空间图谱：使用 Three.js 渲染发光节点、空间标签、曲线连线、星空背景和地面空间参照。
WebXR 体验：在支持 WebXR 的设备上进入 VR/AR，会显示可交互的空间图谱和悬浮笔记面板。
Markdown 笔记预览：通过 marked 渲染笔记正文，桌面侧栏和 VR 面板都能查看内容。
本地服务：通过 Express 提供静态页面、图谱 API、笔记 API 和文件列表 API。
文件监听：通过 Chokidar 监听 Vault 文件变化，为后续实时刷新能力保留基础。
测试 Vault：xr_node/test-vault 内置一组测试笔记，可以不连接真实 Obsidian Vault 直接体验。

两个版本怎么选

版本	当前状态	推荐用途	Vault 选择方式	前端组织	3D / VR
`xr_node`	主版本 / 优化版	日常运行、继续开发、演示截图、验证新功能	支持 `OBSIDIAN_VAULT_PATH`、保存上次路径、也支持终端输入	拆分为 `main.js`、`graph-2d.js`、`graph-3d.js`、`vrui.js` 等模块	有桌面 3D 预览，VR 视觉效果已强化
`obsidian-xr`	早期保留版	对照旧实现、查看原型、回退参考	启动时终端交互输入	主要集中在单页 HTML 与少量服务端文件	保留早期 XR / 图谱实现

推荐策略：

新用户和演示使用 xr_node。
要看项目最初的组织方式，使用 obsidian-xr。
后续新增功能优先放到 xr_node。
obsidian-xr 建议保持为可运行参考版本，除非明确要同步升级。

演示截图

以下截图来自 xr_node 当前优化版。

3D / VR 预览

2D 图谱与笔记面板

节点聚焦与笔记阅读

项目结构

.
├── xr_node/
│   ├── public/
│   │   ├── api.js              # 前端 API 请求和文件树渲染
│   │   ├── graph-2d.js         # D3 2D 图谱
│   │   ├── graph-3d.js         # Three.js 3D / WebXR 图谱
│   │   ├── index.html          # 主页面
│   │   ├── main.js             # 应用入口、模式切换、状态调试钩子
│   │   ├── note-viewer.html    # 独立笔记查看页
│   │   ├── skybox/             # 3D 场景天空盒资源
│   │   ├── style.css           # 桌面 UI 样式
│   │   └── vrui.js             # VR 悬浮笔记面板
│   ├── server/
│   │   ├── graph.js            # Vault 扫描、链接解析、图谱构建
│   │   ├── index.js            # Express / HTTP / HTTPS / WebSocket 服务
│   │   ├── selectVault.js      # Vault 路径选择与保存
│   │   └── workspace.json      # 上次使用的 Vault 路径记录
│   ├── test-vault/             # 内置测试 Vault
│   ├── package.json
│   └── package-lock.json
├── obsidian-xr/
│   ├── public/
│   │   ├── index.html          # 早期单页前端
│   │   ├── note-viewer.html
│   │   └── skybox/
│   ├── server/
│   │   ├── graph.js
│   │   ├── index.js
│   │   ├── selectVault.js
│   │   └── workspace.json
│   ├── package.json
│   └── package-lock.json
├── docs/
│   └── screenshots/            # README 演示截图
├── .gitignore
└── README.md

环境要求

Node.js 18 或更新版本
npm
能访问 CDN 的浏览器网络环境
桌面预览推荐 Chrome / Edge / Safari 最新版本
VR 体验需要支持 WebXR 的浏览器和设备

前端库通过浏览器 import map 从 CDN 加载：

Three.js
D3
Marked
Tween.js

如果页面空白或控制台提示模块加载失败，通常是 CDN 网络访问问题。

快速启动 `xr_node`

xr_node 是当前主版本，推荐优先使用。

cd xr_node
npm install
npm start

启动后默认服务：

HTTP:  http://localhost:8080
HTTPS: https://localhost:8443  # 仅当 key.pem / cert.pem 存在时启用
WS:    ws://localhost:8081

如果没有指定 Vault，程序会按顺序尝试：

读取 OBSIDIAN_VAULT_PATH 环境变量。
读取 server/workspace.json 中的 lastVaultPath。
在终端提示你输入 Vault 文件夹路径。

使用内置测试 Vault

cd xr_node
OBSIDIAN_VAULT_PATH="$(pwd)/test-vault" XR_DISABLE_HTTPS=1 npm start

打开桌面版：

http://localhost:8080

直接打开 3D 预览：

http://localhost:8080/?mode=3d&layout=galaxy

使用 Stacks 布局预览：

http://localhost:8080/?mode=3d&layout=stacks

快速启动 `obsidian-xr`

obsidian-xr 是早期保留版本。它没有内置测试 Vault 流程，启动时会直接要求输入 Obsidian Vault 路径。

cd obsidian-xr
npm install
npm start

启动后按终端提示输入 Vault 文件夹路径，然后打开终端输出的地址。

两个版本默认端口相同。如果要同时运行，请至少修改其中一个版本的端口环境变量。

HTTP_PORT=8090 HTTPS_PORT=8444 WS_PORT=8091 npm start

使用真实 Obsidian Vault

`xr_node`

cd xr_node
OBSIDIAN_VAULT_PATH="/path/to/your/obsidian-vault" npm start

macOS 示例：

OBSIDIAN_VAULT_PATH="/Users/you/Documents/ObsidianVault" npm start

Windows 路径在终端输入时可以使用类似：

D:\Notes\ObsidianVault

`obsidian-xr`

cd obsidian-xr
npm start

随后在终端输入 Vault 文件夹路径。

链接解析规则

每个 Markdown 文件会成为一个图谱节点。节点字段主要包括：

{
  "id": "Ideas/Spatial Notes.md",
  "label": "Spatial Notes",
  "path": "Ideas/Spatial Notes.md",
  "type": "note",
  "degree": 2
}

支持的链接：

[[Home]]
[[Ideas/Spatial Notes]]
[[Spatial Notes|别名]]
[[Spatial Notes#Section]]
[Node Graphs](Ideas/Node Graphs.md)

当前限制：

wikilink 主要按文件 basename 匹配，例如 [[Home]] 匹配 Home.md。
Markdown 链接需要指向 .md 文件。
当前实现不会解析图片、PDF、Canvas 文件或非 Markdown 附件。
如果多个笔记 basename 相同，匹配结果可能不符合预期，建议保持 Vault 内 Markdown 文件名清晰唯一。

WebXR / VR / AR 使用说明

桌面浏览器可以用 3D / VR 模式预览空间图谱。真正进入 VR/AR 需要满足 WebXR 条件。

桌面调试

桌面调试可使用 HTTP：

http://localhost:8080/?mode=3d&layout=galaxy

此模式不会真的进入 VR 头显，但可以检查 3D 场景、布局、节点材质和视觉效果。

真机 VR

真机 VR 通常需要 HTTPS 或可信来源。项目会在 xr_node/ 或 obsidian-xr/ 目录下查找：

key.pem
cert.pem

存在这两个文件时，服务会尝试开启 HTTPS：

https://localhost:8443
https://<LAN-IP>:8443

如果只想进行 HTTP 调试，可以设置：

XR_DISABLE_HTTPS=1 npm start

局域网访问

服务启动后会打印局域网地址，例如：

http://192.168.x.x:8080
https://192.168.x.x:8443

VR 设备和电脑需要在同一局域网内。首次访问自签名 HTTPS 证书时，浏览器可能提示不安全，需要手动信任或继续访问。

界面操作

顶部工具栏

控件	作用
`进入 VR`	请求 `immersive-vr` 会话
`开启透视`	请求 `immersive-ar` 会话
`退出 XR`	结束当前 XR 会话并回到 2D
`2D`	桌面 2D 图谱
`3D / VR`	桌面 3D 图谱和 VR 准备视图
`Galaxy`	星系式图谱布局
`Stacks`	分层堆叠式图谱布局
`刷新图谱`	重新读取 Vault 文件和链接

2D 键盘操作

Arrow keys  切换聚焦节点
Enter       打开当前聚焦节点对应笔记
Space       清除 2D 聚焦
F           切换全屏
R           刷新图谱

VR 控制器操作

射线指向节点并选择：聚焦节点并打开空间笔记面板。
射线点空白区域并拖动：移动图谱。
双手控制器拖拽：缩放图谱。
点击 VR 面板按钮：固定、打开新标签页或关闭面板。

API 说明

服务端提供三个主要接口。

`GET /graph`

返回当前 Vault 的图谱。

示例响应：

{
  "nodes": [
    {
      "id": "Home.md",
      "label": "Home",
      "path": "Home.md",
      "type": "note",
      "order": 0,
      "degree": 3
    }
  ],
  "links": [
    {
      "source": "Home.md",
      "target": "Ideas/Node Graphs.md"
    }
  ]
}

`GET /files`

返回 Markdown 文件列表。

[
  {
    "path": "Home.md",
    "basename": "Home",
    "mtime": 1710000000000
  }
]

`GET /note?path=<relative-note-path>`

返回某篇笔记内容。

{
  "path": "Home.md",
  "content": "# Home\n\n..."
}

实现细节

服务端

server/index.js 启动 Express 静态服务、HTTP/HTTPS 服务和 WebSocket 服务。
server/selectVault.js 负责选择 Vault 路径。
server/graph.js 负责扫描 Markdown、缓存内容、解析链接并生成图谱数据。

前端

public/main.js 管理应用状态、模式切换、刷新、快捷键和调试钩子。
public/graph-2d.js 负责 D3 2D 图谱。
public/graph-3d.js 负责 Three.js 3D 场景、节点材质、连线、WebXR 控制器。
public/vrui.js 负责 VR 中的悬浮笔记面板。
public/api.js 负责请求服务端 API 和渲染左侧文件树。

调试状态

xr_node 暴露了自动化调试入口：

window.render_game_to_text()
window.advanceTime(ms)

render_game_to_text() 会返回当前模式、布局、节点数量、当前聚焦节点、笔记状态、XR 状态等信息，适合 Playwright 或其他浏览器自动化工具读取。

开发与验证

本地运行

cd xr_node
OBSIDIAN_VAULT_PATH="$(pwd)/test-vault" XR_DISABLE_HTTPS=1 npm start

验证页面

http://localhost:8080
http://localhost:8080/?mode=3d&layout=galaxy

输出截图

README 中的截图位于：

docs/screenshots/

运行时自动化输出和临时截图应放在：

xr_node/output/

output/ 已被 .gitignore 排除，不会进入仓库。

故障排查

`npm start` 后一直等待输入

说明没有找到 Vault 路径。可以直接设置环境变量：

OBSIDIAN_VAULT_PATH="/path/to/vault" npm start

页面打开但没有图谱

优先检查：

Vault 路径是否正确。
Vault 中是否有 .md 文件。
浏览器控制台是否有 CDN 加载失败。
终端是否打印了 /graph 或文件读取错误。

3D 模式空白

优先检查：

浏览器是否支持 WebGL。
Three.js CDN 是否加载成功。
是否打开了 http://localhost:8080/?mode=3d&layout=galaxy。

`进入 VR` 按钮不可用

常见原因：

当前浏览器不支持 WebXR。
没有连接或启用 VR 设备。
页面不是 HTTPS 或可信来源。
使用桌面浏览器时只能预览 3D，不能进入真实沉浸式 VR。

局域网 VR 设备无法访问

检查：

电脑和 VR 设备是否在同一网络。
防火墙是否拦截端口 8080 或 8443。
服务启动日志中的 LAN IP 是否正确。
HTTPS 自签名证书是否被浏览器接受。

端口被占用

修改端口环境变量：

HTTP_PORT=8090 HTTPS_PORT=8444 WS_PORT=8091 npm start

维护建议

新功能优先改 xr_node。
修改图谱数据结构时，同步检查 /graph API、graph-2d.js、graph-3d.js。
修改 VR 面板时，同步检查 vrui.js 中的点击目标和控制器射线逻辑。
添加 README 截图时，放入 docs/screenshots/，不要引用 output/。
不要提交真实 Vault 内容、私钥证书、node_modules/ 或运行输出。
如果公开仓库中出现私人 Vault 路径，检查并清理对应的 server/workspace.json。

Git 忽略规则

当前仓库会忽略：

node_modules/
output/
*.log
.DS_Store
*.pem
*.key
*.zip
.cache/
.tmp/

License

当前 package.json 使用 ISC 许可证声明。

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
docs/screenshots		docs/screenshots
obsidian-xr		obsidian-xr
xr_node		xr_node
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation