Obsidian Connector for VS Code

一个专业级的 VS Code 插件，实现 Shadow Vault（影子库）架构，自动将项目的文档目录挂载到 Obsidian 中心库，提供多位置的一键跳转功能。

✨ 核心特性

🚀 自动化挂载

• 智能检测：插件启动时自动检测并挂载现有的 docs 目录
• 实时监听：监听文件创建和重命名事件，自动挂载新建的 docs 文件夹
• Windows 兼容：使用 junction 类型软连接，无需管理员权限
• 幂等性保护：避免重复创建链接，确保系统稳定

📚 智能跳转

提供 5 种跳转方式，满足不同使用场景：

方式	位置	触发方式
📖 状态栏	底部右侧	点击
📖 资源管理器标题	左侧顶部工具栏	点击
📖 侧边栏行内	文件列表中	鼠标悬停后点击
📖 编辑器右上角	编辑器标签页右侧	点击（仅 .md 文件）
⌨️ 快捷键	任意位置	Alt + O

🔧 智能配置

• 支持自定义 Obsidian 中心库路径
• 状态栏按钮智能显示（仅编辑 Markdown 文件时显示）
• 自动创建 .keep 文件确保 Git 能追踪空目录

📦 安装

从源码安装

# 克隆项目
git clone <repository-url>
cd obs

# 安装依赖
bun install

# 构建插件
bun run build

在 VS Code 中运行

1. 按 F5 启动扩展开发主机
2. 新窗口会打开，插件已自动加载

⚙️ 配置

基础配置

在 VS Code 设置中搜索 Obsidian Connector，配置以下选项：

配置项	默认值	说明
obsidianConnector.centralVaultPath	H:\main\ObsidianNotes	Obsidian 中心库的绝对路径

在 settings.json 中配置

{
  "obsidianConnector.centralVaultPath": "D:\\Obsidian\\MyNotes"
}

📖 使用指南

1. 初始化 Obsidian 中心库

# 创建中心库目录
mkdir "H:\main\ObsidianNotes"

# 在 Obsidian 中打开这个目录作为 Vault

2. 自动挂载 docs 目录

方式一：新建 docs 目录

1. 在 VS Code 项目中创建 docs 文件夹
2. 插件自动检测并挂载到 Obsidian 中心库
3. Obsidian 侧自动显示 [项目名]-Docs 文件夹

方式二：重命名现有文件夹

1. 将任意文件夹重命名为 docs
2. 插件自动检测并执行挂载

3. 跳转到 Obsidian

打开任意 Markdown 文件，使用以下任一方式跳转：

方式一：状态栏按钮

• 点击底部状态栏的 📖 Obsidian 按钮

方式二：资源管理器标题栏

• 点击左侧资源管理器顶部的 📖 图标

方式三：侧边栏行内按钮

• 鼠标悬停在侧边栏的 .md 文件上
• 点击文件名右侧出现的 📖 图标

方式四：编辑器右上角

• 点击编辑器标签页右侧的 📖 图标（仅 Markdown 文件）

方式五：快捷键

• 按 Alt + O 快速跳转

🔍 调试功能

插件提供调试命令，帮助排查问题：

使用调试命令

1. 按 Ctrl+Shift+P 打开命令面板
2. 输入 Debug: Obsidian Path
3. 选择该命令查看当前文件的详细信息

调试信息包括：

• 原始路径
• 真实物理路径
• 规范化路径（正斜杠）
• 中心库配置路径
• 项目名称
• 完整的 Obsidian URI

可执行操作：

• 复制：将调试信息复制到剪贴板
• 打开路径：用默认程序打开文件
• 测试 URI：直接测试生成的 Obsidian URI

查看开发者控制台

1. 按 Ctrl+Shift+I 打开 VS Code 开发者工具
2. 切换到 Console 标签页
3. 查看插件的日志输出

🛠️ 技术实现

架构设计

项目结构
├── extension/
│   ├── index.ts          # 主入口，包含挂载和跳转逻辑
│   ├── utils.ts          # 工具函数（mountDocsToObsidian）
│   └── views/
│       ├── panel.ts      # React Webview 面板
│       └── helper.ts     # 辅助函数
└── src/
    └── utils/
        └── vscode.ts     # VS Code 工具函数

核心功能

1. 自动挂载 (extension/utils.ts)

export async function mountDocsToObsidian(
  projectDocsPath: string,
  centralVaultProjectsPath: string
)

功能：

• 检测并创建软连接（Windows 使用 junction）
• 幂等性保护，避免重复创建
• 自动创建 .keep 文件
• 完善的错误处理和用户提示

2. 文件监听 (extension/index.ts)

启动时检测：

const checkAndMount = async () => {
  // 检测 docs 目录并执行挂载
}
checkAndMount();

文件创建监听：

const createWatcher = workspace.onDidCreateFiles(async (event) => {
  // 监听 docs 目录创建
});

文件重命名监听：

const renameWatcher = workspace.onDidRenameFiles(async (event) => {
  // 监听文件夹重命名为 docs
});

3. 智能跳转 (extension/index.ts)

commands.registerCommand('obsidianConnector.jumpToObsidian', async () => {
  // 1. 获取当前文件路径
  // 2. 解析真实物理路径
  // 3. 构建 Obsidian URI
  // 4. 唤起外部应用
});

URI 格式：

• 方案 A（推荐）：obsidian://open?vault=<库名>&file=<相对路径>
• 方案 B（备用）：obsidian://open?file=<完整路径>

Windows 软连接技术

为什么使用 Junction？

特性	Symlink	Junction
权限要求	需要管理员权限	不需要
支持平台	文件 + 目录	仅目录
跨盘符支持	❌	✅
Obsidian 兼容性	⚠️ 可能有问题	✅ 完美兼容

实现代码：

const type = process.platform === 'win32' ? 'junction' : 'dir';
await fs.symlink(projectDocsPath, linkPathInObsidian, type);

❓ 常见问题

1. 挂载失败：Windows 权限不足

解决方案：

• 开启 Windows 开发者模式
• 或者以管理员身份运行 VS Code

2. Obsidian 提示 "Unable to find a vault for the URL"

原因：

• Obsidian URI 格式错误
• 路径未在已打开的 Obsidian 库中

解决方案：

1. 确保在 VS Code 设置中正确配置了 obsidianConnector.centralVaultPath
2. 确保 Obsidian 已打开该库
3. 使用调试命令检查生成的 URI

3. 软连接创建成功但 Obsidian 中看不到文件

可能原因：

• Obsidian 需要重新加载库
• 文件索引未完成

解决方案：

• 在 Obsidian 中按 Ctrl+R 重新加载
• 等待文件索引完成

4. Git 不追踪空 docs 目录

解决方案：

• 插件已自动在 docs 目录中创建 .keep 文件
• 确保 .gitignore 未忽略 .keep 文件

🚀 进阶使用

跨项目文档链接

在 Obsidian 中创建跨项目的知识关联：

# Project-B 文档
参见 [[Project-A-Docs#接口定义]] 了解 API 详情

与 AI 任务编排配合

输入层：在 Obsidian 总库里写需求、画架构图
  ↓
触发层：VS Code 插件监听总库变化
  ↓
执行层：AI 读取任务，在物理路径生成代码

📝 开发

构建

# 安装依赖
bun install

# 开发模式
bun run dev

# 生产构建
bun run build

代码格式化

# 使用 Biome 格式化代码
bunx biome check --write

技术栈

• 构建工具：Vite
• 框架：React 19
• 语言：TypeScript
• 文件操作：fs-extra
• 代码规范：Biome (ultracite)

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📮 联系方式

如有问题或建议，请通过 GitHub Issues 联系。