Obsidian AI 集成与最佳实践报告

更新日期: 2026-03-14
文档版本: 1.0

Obsidian AI 集成与最佳实践报告

更新日期: 2026-03-14 文档版本: 1.0

目录

  1. AI 集成方案概述
  2. Claude Code 集成
  3. Obsidian AI 插件
  4. 自动化脚本最佳实践
  5. Templater 高级用法
  6. URI Scheme 自动化
  7. 工作流设计建议

一、AI 集成方案概述

1.1 集成方式对比

方式 优点 缺点 适用场景
Local REST API 功能完整，支持所有操作 需要 Obsidian 运行 脚本自动化、AI Agent
URI Scheme 简单快速，无需插件 功能有限 快捷操作、跨应用
Templater 内置强大，支持 JS 仅限 Obsidian 内部 模板自动化
AI 插件 开箱即用 可能收费，依赖外部服务 日常 AI 辅助

1.2 架构图

┌─────────────────────────────────────────────────────────────────────────┐
│                        Obsidian AI 集成架构                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐              │
│  │ Claude Code │     │   GPT/Claude │     │  其他 AI    │              │
│  └──────┬──────┘     └──────┬──────┘     └──────┬──────┘              │
│         │                   │                   │                      │
│         └───────────────────┼───────────────────┘                      │
│                             │                                           │
│                             ▼                                           │
│                    ┌────────────────┐                                   │
│                    │  Local REST API │                                  │
│                    │   (端口 27124)  │                                  │
│                    └────────┬───────┘                                   │
│                             │                                           │
│         ┌───────────────────┼───────────────────┐                      │
│         │                   │                   │                      │
│         ▼                   ▼                   ▼                      │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐              │
│  │   读取笔记   │     │   写入笔记   │     │   搜索内容   │              │
│  └─────────────┘     └─────────────┘     └─────────────┘              │
│                             │                                           │
│                             ▼                                           │
│                    ┌────────────────┐                                   │
│                    │   Obsidian     │                                   │
│                    │   仓库 (Vault)  │                                  │
│                    └────────────────┘                                   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

二、Claude Code 集成

2.1 配置 MCP 服务器

方式一：使用 Local REST API

创建 MCP 服务器配置文件：

// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

方式二：直接 HTTP 调用

Claude Code 可以直接使用 Bash 工具调用 REST API：

# Claude Code 执行的命令示例
curl -X POST "https://127.0.0.1:27124/periodic/daily/" \
  -H "Authorization: Bearer $OBSIDIAN_API_KEY" \
  -H "Content-Type: text/markdown" \
  -k \
  -d "## AI 自动记录\n\n这是 Claude Code 自动添加的内容"

2.2 Claude Code 工作流示例

# Claude Code 自动化场景

## 场景 1：自动保存研究笔记
用户: "帮我把这份研究报告保存到 Obsidian"
Claude Code:
1. 调用 REST API 创建笔记
2. 保存到指定路径

## 场景 2：追加到日记
用户: "记录一下今天的进展"
Claude Code:
1. 调用 /periodic/daily/ 端点
2. 追加时间戳和内容

## 场景 3：搜索笔记
用户: "帮我找一下关于机器学习的笔记"
Claude Code:
1. 调用 /search/simple/ 端点
2. 返回匹配结果

2.3 Claude Code 提示词模板

# 给 Claude Code 的 Obsidian 集成指令

你已连接到我的 Obsidian 仓库，可以通过 Local REST API 操作笔记。

## API 配置
- Base URL: https://127.0.0.1:27124
- API Key: 已配置在环境变量中

## 可用操作
1. 创建笔记: PUT /vault/{path}
2. 读取笔记: GET /vault/{path}
3. 追加内容: POST /vault/{path}
4. 搜索笔记: POST /search/simple/
5. 追加日记: POST /periodic/daily/

## 使用规范
- 创建笔记时使用有意义的文件名
- 内容使用标准 Markdown 格式
- 追加日记时自动添加时间戳
- 搜索时使用精准关键词

三、Obsidian AI 插件

3.1 主流 AI 插件对比

插件 模型支持 特点 价格
Copilot OpenAI, Anthropic, Local 对话式 AI，支持上下文 免费/付费
Text Generator 多模型 文本生成，模板支持 免费
Khoj 本地模型 私有化，支持搜索 免费
Smart Connections Embeddings 语义链接，推荐相关笔记 免费
BMO Chatbot Ollama 本地运行，完全私有 免费

3.2 Obsidian Copilot 配置

┌─────────────────────────────────────────────────────────────┐
│  Copilot 插件配置                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  模型设置:                                                   │
│  ├── OpenAI: gpt-4-turbo                                    │
│  ├── Anthropic: claude-sonnet-4.6                           │
│  └── 自定义: 你的 API 端点                                   │
│                                                             │
│  功能:                                                       │
│  ├── 💬 对话模式 - 和笔记对话                                │
│  ├── 📝 文本生成 - 续写、改写                                │
│  ├── 🔍 智能搜索 - 语义搜索                                  │
│  └── 📊 笔记分析 - 总结、提取                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

3.3 Khoj 本地 AI 配置

优点: 完全本地运行，隐私安全

  1. 安装 Khoj 桌面应用
  2. 安装 Obsidian Khoj 插件
  3. 配置模型路径
# khoj.yml
search-type: semantic
model: llama3
embeddings-model: all-MiniLM-L6-v2

3.4 Smart Connections 语义链接

工作原理:
1. 对所有笔记生成 Embeddings
2. 建立向量索引
3. 根据当前笔记推荐相关内容

使用方式:
- 侧边栏显示"相关笔记"
- 支持语义搜索
- 发现隐藏的知识关联

四、自动化脚本最佳实践

4.1 Python 自动化脚本库

#!/usr/bin/env python3
"""
Obsidian 自动化工具库
依赖: pip install requests python-dateutil
"""

import os
import json
import requests
from datetime import datetime
from pathlib import Path
from typing import Optional, List, Dict

class ObsidianVault:
    """Obsidian 仓库自动化工具"""

    def __init__(self, api_key: str, vault_path: str = None):
        self.base_url = "https://127.0.0.1:27124"
        self.headers = {"Authorization": f"Bearer {api_key}"}
        self.verify = False
        self.vault_path = vault_path

    def _request(self, method: str, endpoint: str, **kwargs) -> requests.Response:
        """发送请求"""
        url = f"{self.base_url}{endpoint}"
        kwargs["headers"] = {**self.headers, **kwargs.get("headers", {})}
        kwargs["verify"] = self.verify
        return requests.request(method, url, **kwargs)

    # ========== 笔记操作 ==========

    def create_note(self, path: str, content: str) -> bool:
        """创建笔记"""
        resp = self._request("PUT", f"/vault/{path}",
                           headers={"Content-Type": "text/markdown"},
                           data=content.encode('utf-8'))
        return resp.status_code == 204

    def read_note(self, path: str) -> Optional[str]:
        """读取笔记"""
        resp = self._request("GET", f"/vault/{path}")
        return resp.text if resp.status_code == 200 else None

    def append_note(self, path: str, content: str) -> bool:
        """追加内容"""
        resp = self._request("POST", f"/vault/{path}",
                           headers={"Content-Type": "text/markdown"},
                           data=content.encode('utf-8'))
        return resp.status_code == 204

    def delete_note(self, path: str) -> bool:
        """删除笔记"""
        resp = self._request("DELETE", f"/vault/{path}")
        return resp.status_code == 204

    # ========== 日记操作 ==========

    def append_daily(self, content: str, date: datetime = None) -> bool:
        """追加到日记"""
        endpoint = "/periodic/daily/"
        if date:
            endpoint = f"/periodic/daily/{date.year}/{date.month:02d}/{date.day:02d}/"

        timestamp = datetime.now().strftime("%H:%M")
        formatted_content = f"\n## {timestamp}\n{content}"

        resp = self._request("POST", endpoint,
                           headers={"Content-Type": "text/markdown"},
                           data=formatted_content.encode('utf-8'))
        return resp.status_code == 204

    def get_daily(self, date: datetime = None) -> Optional[str]:
        """获取日记内容"""
        endpoint = "/periodic/daily/"
        if date:
            endpoint = f"/periodic/daily/{date.year}/{date.month:02d}/{date.day:02d}/"

        resp = self._request("GET", endpoint)
        return resp.text if resp.status_code == 200 else None

    # ========== 搜索 ==========

    def search(self, query: str) -> List[Dict]:
        """搜索笔记"""
        resp = self._request("POST", "/search/simple/",
                           json={"query": query})
        return resp.json() if resp.status_code == 200 else []

    # ========== 文件夹操作 ==========

    def list_directory(self, path: str = "") -> Dict:
        """列出目录内容"""
        endpoint = f"/vault/{path}/" if path else "/vault/"
        resp = self._request("GET", endpoint)
        return resp.json() if resp.status_code == 200 else {}

    # ========== 高级功能 ==========

    def quick_capture(self, content: str, title: str = None) -> bool:
        """快速收集到 Inbox"""
        if title is None:
            title = datetime.now().strftime("%Y-%m-%d %H%M%S")

        path = f"00-Inbox/{title}.md"
        full_content = f"# {title}\n\n创建时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n{content}"
        return self.create_note(path, full_content)

    def log_event(self, event_type: str, description: str) -> bool:
        """记录事件到日志"""
        content = f"\n### {event_type}\n时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n{description}\n"
        return self.append_daily(content)

    def find_backlinks(self, note_path: str) -> List[str]:
        """查找反向链接（简化版）"""
        note_name = Path(note_path).stem
        results = self.search(f"[[{note_name}]]")
        return [r.get('path', '') for r in results]


# ========== 使用示例 ==========

if __name__ == "__main__":
    # 初始化
    vault = ObsidianVault(api_key=os.environ.get("OBSIDIAN_API_KEY"))

    # 快速收集
    vault.quick_capture("今天学到了 Obsidian REST API 的用法", "学习笔记")

    # 追加日记
    vault.append_daily("完成了 Obsidian 自动化脚本的编写")

    # 记录事件
    vault.log_event("任务完成", "Obsidian 研究文档已创建完成")

    # 搜索
    results = vault.search("Obsidian")
    print(f"找到 {len(results)} 条相关笔记")

4.2 定时任务脚本

#!/usr/bin/env python3
"""
Obsidian 定时任务
配合 cron 或 launchd 使用
"""

from datetime import datetime, timedelta
from obsidian_automation import ObsidianVault
import os

def daily_summary():
    """每日总结任务"""
    vault = ObsidianVault(api_key=os.environ["OBSIDIAN_API_KEY"])

    # 获取今日日记
    today_content = vault.get_daily()

    # 追加总结模板
    summary_template = """

---

## 📊 今日总结

**完成事项:**
- [ ] ...

**明日计划:**
- [ ] ...

**笔记统计:** 共记录 X 条内容
"""
    vault.append_daily(summary_template)

def weekly_review():
    """每周回顾"""
    vault = ObsidianVault(api_key=os.environ["OBSIDIAN_API_KEY"])

    # 创建周回顾笔记
    today = datetime.now()
    week_num = today.isocalendar()[1]
    path = f"Reviews/{today.year}-W{week_num:02d}.md"

    content = f"""# 第 {week_num} 周回顾

时间范围: {(today - timedelta(days=today.weekday())).strftime('%Y-%m-%d')} - {today.strftime('%Y-%m-%d')}

## 本周重点
-

## 完成的项目
-

## 学到的东西
-

## 下周计划
-
"""
    vault.create_note(path, content)

# cron 配置示例
# 0 21 * * * /usr/bin/python3 /path/to/obsidian_tasks.py daily
# 0 20 * * 0 /usr/bin/python3 /path/to/obsidian_tasks.py weekly

五、Templater 高级用法

5.1 动态模板示例

<%*
// 会议记录模板
let meetingTitle = await tp.system.prompt("会议主题");
let attendees = await tp.system.prompt("参会人员（逗号分隔）");
let date = tp.date.now("YYYY-MM-DD");
let time = tp.date.now("HH:mm");

tR += `# ${meetingTitle}

日期: ${date}
时间: ${time}
参会: ${attendees}

## 议程
1.
2.
3.

## 讨论内容


## 决议
-

## 待办事项
- [ ]
`;
%>

5.2 调用外部 API

<%*
// 获取天气信息
let weather = await fetch("https://api.open-meteo.com/v1/forecast?latitude=39.9&longitude=116.4&current_weather=true")
    .then(r => r.json());

let temp = weather.current_weather.temperature;
let wind = weather.current_weather.windspeed;

tR += `# 日记 - ${tp.date.now("YYYY-MM-DD")}

## 天气
🌡️ 温度: ${temp}°C
💨 风速: ${wind} km/h

## 今日事项
-
`;
%>

5.3 自动分类模板

<%*
// 根据关键词自动选择文件夹
let title = tp.file.title;
let content = tp.file.content;

// 定义关键词映射
const categoryMap = {
    "工作": "01-Projects",
    "学习": "03-Resources/Learning",
    "生活": "02-Areas/Life",
    "想法": "00-Inbox/Ideas"
};

// 匹配分类
let targetFolder = "00-Inbox";  // 默认
for (let [keyword, folder] of Object.entries(categoryMap)) {
    if (title.includes(keyword) || content.includes(keyword)) {
        targetFolder = folder;
        break;
    }
}

// 移动文件
await tp.file.move(`/${targetFolder}/${title}`);
%>

六、URI Scheme 自动化

6.1 基础 URI 格式

obsidian://动作?参数1=值1&参数2=值2

6.2 常用 URI 示例

# 打开笔记
open "obsidian://open?vault=MyVault&file=Notes/MyNote"

# 新建笔记
open "obsidian://new?vault=MyVault&name=NewNote&content=Hello%20World"

# 搜索
open "obsidian://search?vault=MyVault&query=关键词"

# 打开今日日记
open "obsidian://daily?vault=MyVault"

6.3 Advanced URI 插件

安装 Advanced URI 插件后，功能更强大：

# 追加内容到笔记
open "obsidian://advanced-uri?vault=MyVault&filepath=Notes/MyNote&data=追加的内容&mode=append"

# 执行命令
open "obsidian://advanced-uri?vault=MyVault&commandid=editor:save-file"

# 打开设置
open "obsidian://advanced-uri?vault=MyVault&settingid=editor"

6.4 macOS Shortcuts 集成

创建快捷指令:
1. "获取剪贴板内容"
2. "URL" 操作: obsidian://new?vault=MyVault&name=QuickNote&content=[剪贴板内容]
3. "打开 URL"

七、工作流设计建议

7.1 知识收集工作流

┌─────────────────────────────────────────────────────────────┐
│                    知识收集工作流                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  📱 移动端                                                   │
│  └── 快速捕获 → 00-Inbox/                                   │
│                                                             │
│  💻 浏览器                                                   │
│  └── Obsidian Web 扩展 → 00-Inbox/WebClips/                 │
│                                                             │
│  🤖 AI Agent (Claude Code)                                  │
│  └── REST API → 00-Inbox/AICaptures/                        │
│                                                             │
│  📝 每周整理                                                 │
│  └── 00-Inbox → 01-Projects/02-Areas/03-Resources           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

7.2 日记工作流

# 日记自动化流程

## 每日自动
- [x] 早上: Templater 自动创建日记
- [x] 晚上: 自动追加总结模板
- [x] AI: 自动提取今日关键词

## 每周
- [ ] 周日: 自动生成周回顾
- [ ] AI: 分析本周笔记趋势

## 每月
- [ ] 月末: 生成本月报告
- [ ] 归档: 移动到月度文件夹

7.3 项目管理工作流

# 项目笔记结构

## 创建项目
1. Templater 模板创建项目笔记
2. 自动创建子文件夹
3. 初始化看板

## 项目进行中
- REST API 追加进度更新
- 自动关联相关笔记
- AI 生成进度报告

## 项目完成
- 自动移动到 Archives
- 生成项目总结
- 更新索引

7.4 AI 辅助工作流

用户输入 → Claude Code
              │
              ├── 理解意图
              │
              ├── 搜索相关笔记 (REST API)
              │
              ├── 分析内容
              │
              ├── 生成/更新笔记
              │
              └── 追加到日记

八、最佳实践总结

8.1 文件夹结构建议 (PARA + 改进)

MyVault/
├── 00-Inbox/           ← 快速收集，定期整理
│   ├── QuickNotes/
│   ├── WebClips/
│   └── AICaptures/
├── 01-Projects/        ← 当前项目
│   └── ProjectName/
│       ├── Notes/
│       ├── Resources/
│       └── Archive/
├── 02-Areas/           ← 持续关注领域
│   ├── Work/
│   ├── Health/
│   └── Learning/
├── 03-Resources/       ← 参考资料
│   ├── Articles/
│   ├── Books/
│   └── Templates/
├── 04-Archives/        ← 归档
├── 05-Daily/           ← 日记
├── 06-Reviews/         ← 回顾
└── Templates/          ← 模板文件

8.2 命名规范

# 推荐命名格式

## 日记
YYYY-MM-DD.md
2026-03-14.md

## 项目笔记
P-项目名-模块-功能.md
P-MyApp-API-认证.md

## 资源笔记
R-类型-标题.md
R-Book-原子习惯.md

## 会议记录
M-YYYY-MM-DD-主题.md
M-2026-03-14-产品评审.md

8.3 自动化原则

  1. 最小必要: 只自动化真正重复的任务
  2. 渐进增强: 从简单开始，逐步增加复杂度
  3. 可恢复: 保留撤销和恢复的能力
  4. 可观测: 记录自动化操作的日志

九、参考资源

官方资源

  • Obsidian 官网: https://obsidian.md
  • 插件市场: https://obsidian.md/plugins
  • 官方论坛: https://forum.obsidian.md

插件文档

  • Local REST API: https://github.com/coddingtonbear/obsidian-local-rest-api
  • Templater: https://silentvoid13.github.io/Templater/
  • Advanced URI: https://github.com/Vinzent03/obsidian-advanced-uri

社区资源

  • PKMer: https://pkmer.cn
  • Obsidian 中文论坛: https://forum-zh.obsidian.md

AI 集成

  • Obsidian Copilot: https://github.com/logancyang/obsidian-copilot
  • Khoj: https://khoj.dev
  • Smart Connections: https://github.com/brianpetro/obsidian-smart-connections

文档生成时间: 2026-03-14