obsidian

Obsidian

概述

本技能全面介绍如何使用 Obsidian， 这是一款功能强大的知识管理和笔记应用。 内容涵盖库结构、用于插件开发的 Obsidian API、 URI 方案自动化、Markdown 扩展，以及通过 Local REST API 与外部工具集成。

快速参考

库结构

my-vault/
├── .obsidian/              # Configuration folder
│   ├── app.json            # App settings
│   ├── appearance.json     # Theme settings
│   ├── community-plugins.json  # Installed plugins list
│   ├── core-plugins.json   # Core plugin toggles
│   ├── hotkeys.json        # Custom keybindings
│   ├── plugins/            # Plugin data folders
│   │   └── <plugin-id>/
│   │       ├── main.js     # Compiled plugin code
│   │       ├── manifest.json
│   │       └── data.json   # Plugin settings
│   └── workspace.json      # Layout state
├── Notes/                  # User notes (any structure)
├── Attachments/            # Images, PDFs, etc.
└── Templates/              # Template files

Obsidian URI 方案

Obsidian 原生支持使用 obsidian:// 协议进行自动化操作：

# Open a vault
obsidian://open?vault=MyVault

# Open a specific file
obsidian://open?vault=MyVault&file=Notes/MyNote

# Create a new note
obsidian://new?vault=MyVault&name=NewNote&content=Hello

# Search the vault
obsidian://search?vault=MyVault&query=keyword

# Open daily note
obsidian://daily?vault=MyVault

URI 参数

参数	描述
vault	库名称（必填）
file	不含 .md 扩展名的文件路径
path	包含文件夹的完整文件路径
name	创建笔记时使用的笔记名称
content	要插入的内容
query	搜索查询
heading	跳转到标题
block	跳转到块引用

工作流决策树

What do you need to do?
├── Automate Obsidian from external tools?
│   ├── Simple open/create operations?
│   │   └── Use: Native obsidian:// URI scheme
│   ├── Complex automation (append, prepend, commands)?
│   │   └── Use: Advanced URI plugin
│   └── Full programmatic access?
│       └── Use: Local REST API plugin
├── Build a plugin for Obsidian?
│   └── See: Plugin Development section
├── Work with vault files directly?
│   └── Use: obsidian-cli or direct file operations
├── Extend markdown syntax?
│   └── See: Markdown Extensions section
└── Query notes and metadata?
    └── Use: Local REST API or Dataview plugin

插件开发

插件结构

my-plugin/
├── main.ts           # Plugin entry point
├── manifest.json     # Plugin metadata
├── package.json      # npm dependencies
├── styles.css        # Optional styles
├── tsconfig.json     # TypeScript config
└── esbuild.config.mjs # Build config

manifest.json

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "minAppVersion": "1.0.0",
  "description": "A sample plugin for Obsidian",
  "author": "Your Name",
  "authorUrl": "https://github.com/username",
  "isDesktopOnly": false
}

基本插件模板

import { Plugin, Notice, MarkdownView } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    console.log('Loading plugin');

    // Register a command
    this.addCommand({
      id: 'my-command',
      name: 'My Command',
      callback: () => {
        new Notice('Hello from my plugin!');
      }
    });

    // Register editor command
    this.addCommand({
      id: 'my-editor-command',
      name: 'Insert Text',
      editorCallback: (editor, view: MarkdownView) => {
        editor.replaceSelection('Inserted text');
      }
    });

    // Register event listener
    this.registerEvent(
      this.app.workspace.on('file-open', (file) => {
        if (file) {
          console.log('Opened:', file.path);
        }
      })
    );
  }

  onunload() {
    console.log('Unloading plugin');
  }
}

核心 API 类

类	用途	访问方式
App	核心应用实例	this.app
Vault	文件系统操作	this.app.vault
Workspace	窗格和布局管理	this.app.workspace
MetadataCache	文件元数据索引	this.app.metadataCache
FileManager	安全处理用户文件	this.app.fileManager

插件生命周期

// onload() - Called when plugin is enabled
async onload() {
  // Initialize UI components
  // Register event handlers
  // Set up commands
  // Load settings
}

// onunload() - Called when plugin is disabled
onunload() {
  // Cleanup is mostly automatic
  // Custom cleanup for external resources
}

Local REST API

Local REST API 插件提供 HTTP 端点，以编程方式与 Obsidian 交互。

安装

1. 从社区插件中安装“Local REST API”
2. 启用插件
3. 在设置中配置 API 密钥
4. 默认端点：https://127.0.0.1:27124

身份验证

# Using API key header
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://127.0.0.1:27124/vault/

常用端点

# List all files
GET /vault/

# Get file content
GET /vault/{path-to-file}

# Create/Update file
PUT /vault/{path-to-file}
Content-Type: text/markdown
Body: File content here

# Delete file
DELETE /vault/{path-to-file}

# Search vault
POST /search/simple/
Content-Type: application/json
Body: {"query": "search term"}

# Execute command
POST /commands/{command-id}

# Get active file
GET /active/

# Open file in Obsidian
POST /open/{path-to-file}

Python 示例

import requests

class ObsidianAPI:
    def __init__(self, api_key, base_url="https://127.0.0.1:27124"):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
        self.session = requests.Session()
        self.session.verify = False  # Self-signed cert

    def list_files(self, path=""):
        response = self.session.get(
            f"{self.base_url}/vault/{path}",
            headers=self.headers
        )
        return response.json()

    def read_file(self, path):
        response = self.session.get(
            f"{self.base_url}/vault/{path}",
            headers=self.headers
        )
        return response.text

    def write_file(self, path, content):
        response = self.session.put(
            f"{self.base_url}/vault/{path}",
            headers={**self.headers, "Content-Type": "text/markdown"},
            data=content.encode('utf-8')
        )
        return response.status_code == 204

    def search(self, query):
        response = self.session.post(
            f"{self.base_url}/search/simple/",
            headers=self.headers,
            json={"query": query}
        )
        return response.json()

Markdown 扩展

Obsidian 通过特殊语法扩展了标准 Markdown：

内部链接（Wikilinks）

[[Note Name]]                    # Link to note
[[Note Name|Display Text]]       # Link with alias
[[Note Name#Heading]]            # Link to heading
[[Note Name#^block-id]]          # Link to block
[[Note Name#^block-id|alias]]    # Block link with alias

嵌入（转置）

![[Note Name]]                   # Embed entire note
![[Note Name#Heading]]           # Embed section
![[Note Name#^block-id]]         # Embed block
![[image.png]]                   # Embed image
![[image.png|300]]               # Embed with width
![[image.png|300x200]]           # Embed with dimensions
![[audio.mp3]]                   # Embed audio
![[video.mp4]]                   # Embed video
![[document.pdf]]                # Embed PDF

标注块

> [!note] Title
> Content here

> [!warning] Caution
> Important warning message

> [!tip]+ Expandable (default open)
> Click to collapse

> [!info]- Collapsed (default closed)
> Click to expand

# Available types:
# note, abstract, summary, tldr, info, todo, tip, hint,
# important, success, check, done, question, help, faq,
# warning, caution, attention, failure, fail, missing,
# danger, error, bug, example, quote, cite

块引用

This is a paragraph. ^block-id

# Reference this block from another note:
[[Note#^block-id]]

标签

#tag
#nested/tag
#tag-with-dashes

Frontmatter（YAML）

---
title: My Note
date: 2024-01-15
tags:
  - tag1
  - tag2
aliases:
  - alternate name
cssclass: custom-class
---

# Note content starts here

注释

%%This is a comment that won't render%%

%%
Multi-line
comment
%%

数学公式（LaTeX）

Inline: $E = mc^2$

Block:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Mermaid 图表

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
```

CLI 工具

obsidian-cli（Yakitrak）

# Install
go install github.com/Yakitrak/obsidian-cli@latest

# Commands
obsidian-cli open "Note Name"         # Open note
obsidian-cli search "query"           # Fuzzy search
obsidian-cli create "New Note"        # Create note
obsidian-cli daily                    # Open daily note
obsidian-cli list                     # List notes

obsidian-cli（Python）

# Install
pip install obsidian-cli

# Commands
obs vault list                        # List vaults
obs vault create <name>               # Create vault
obs note search <query>               # Search notes
obs settings export                   # Export settings

最佳实践

1. 使用单独的开发库：切勿在主库中开发插件
2. 热重载插件：安装此插件以加快开发迭代
3. 使用 registerEvent()：确保卸载时正确清理
4. 优先使用 UID 而非路径：文件路径可能会改变；请使用唯一标识符
5. 正确处理异步操作：对库操作使用 await
6. 在 Obsidian 沙盒中测试：使用 BRAT 插件进行 Beta 测试
7. 遵循 manifest 约定：确保 id 与文件夹名称一致
8. 谨慎管理版本：更新 versions.json 以确保兼容性

故障排除

插件未加载

# Check console for errors
Ctrl+Shift+I (or Cmd+Option+I on Mac)

# Verify manifest.json is valid JSON
jq . manifest.json

# Check minAppVersion compatibility
# Ensure main.js exists in plugin folder

URI 无法使用

# URL encode special characters
# Spaces: %20
# Slashes: %2F
# Ampersands: %26

# Test with simple vault name first
obsidian://open?vault=test

REST API 连接失败

# Verify plugin is enabled
# Check API key is correct
# Confirm HTTPS and self-signed cert handling
# Default port: 27124

资源

参考资料

• references/uri-scheme.md - 完整的 URI 方案文档
• references/plugin-development.md - 插件开发指南
• references/vault-structure.md - 库和配置结构
• references/markdown-extensions.md - Obsidian Markdown 语法
• references/api-reference.md - TypeScript API 参考

脚本

• scripts/obsidian-vault.sh - 库管理实用工具
• scripts/obsidian-api.py - Local REST API Python 客户端

外部文档

• Obsidian 开发者文档
• Obsidian API 类型
• 示例插件模板
• Local REST API 插件
• Advanced URI 插件
• Obsidian 帮助

---

整合后的子技能（合并后）

此技能现已涵盖原先的 obsidian-master 技能（“统一编排”总括技能）。其内容作为深入参考资料保留：

主题	路径
原始编排 SKILL.md（多步骤库工作流）	References/master.md
主技能的参考文档	References/master-reference/
主技能的工作流	References/master-workflows/
主技能的工具	References/master-tools/

原先的 obsidian-second-brain 技能已重命名为 obsidian-claude-integration，以反映其实际用途：Claude Code + Obsidian 集成模式，而非泛泛的“第二大脑”概念。

仍适用的专门子技能：

• obsidian-markdown — 仅涉及语法（wikilinks、嵌入、标注框、frontmatter、标签、LaTeX、Mermaid）。
• obsidian-bases — 仅涉及 Bases（.base YAML、表格视图、筛选器、公式）。
• obsidian-nvim — 仅涉及 obsidian.nvim Neovim 插件。
• obsidian-vault-management — 对库内容执行 CRUD 操作（笔记、模板、Dataview）。
• obsidian-claude-integration — Claude Code ↔ Obsidian 集成模式。

---

注意事项

• 存在重复项时，Wikilink [[Note]] 解析会静默地选取库中按字母顺序排列的第一个匹配项。 不同文件夹中有两篇名为 "Index" 的笔记，会造成难以察觉的歧义。
• obsidian:// URI 方案要求库已在桌面应用中打开。 无头环境（CI、未运行 Obsidian 的 Claude Code）会静默地不执行任何操作。
• 除 API 密钥外，还必须单独启用 Local REST API 插件。 默认端口为 27124，但插件必须处于运行状态，HTTP 请求才能到达。
• Markdown 脚注（[^1]）要求定义前有一个空行。 如果没有空行，Obsidian 会将其渲染为纯文本，且不会报错。
• 库路径包含空格或特殊字符时：大多数插件都能处理，但有些 shell 集成插件不行。 请明确测试脚本调用。