aiskillstore/obsidian-helper

Obsidian Helper - 智能笔记助手

这是一个与 Obsidian MCP 深度整合的智能助手，提供三大核心功能来提升你的笔记效率。

---

⚡ 首次使用必读：自动检测与配置引导

执行任何功能前，Claude 必须先执行 STEP 0

STEP 0: MCP 连接检测（每次会话首次使用时执行）
├─ 尝试调用 obsidian_list_files_in_vault()
├─ 如果成功 → 继续执行用户请求的功能
└─ 如果失败 → 进入【配置引导流程】

配置引导流程（全中文提示）

当 MCP 连接失败时，Claude 必须向用户显示以下引导信息：

---

检测到 Obsidian MCP 未连接，我来帮你配置！

📋 配置步骤

第一步：安装 Obsidian 插件

1. 打开 Obsidian → 设置 → 第三方插件
2. 关闭「安全模式」
3. 点击「浏览」，搜索 Local REST API
4. 安装并启用该插件

第二步：获取 API Key

1. 在 Obsidian 设置中找到 Local REST API 插件设置
2. 点击「Copy API Key」复制你的 API Key
3. 记下端口号（默认是 27124）

第三步：配置 Claude Code MCP

在终端运行以下命令，将 你的API_KEY 替换为刚才复制的 Key：

# 创建 MCP 配置目录（如果不存在）
mkdir -p ~/.claude

# 添加 Obsidian MCP 配置
cat >> ~/.claude/mcp.json << 'EOF'
{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "你的API_KEY",
        "OBSIDIAN_HOST": "https://127.0.0.1:27124"
      }
    }
  }
}
EOF

或者手动编辑 ~/.claude/mcp.json：

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "你的API_KEY",
        "OBSIDIAN_HOST": "https://127.0.0.1:27124"
      }
    }
  }
}

第四步：重启 Claude Code

# 完全退出 Claude Code，然后重新启动
claude

第五步：验证连接

重启后，再次输入你想要的命令（如 /daily），我会自动验证连接是否成功。

---

❓ 常见问题

| 问题 | 解决方案 | |------|----------| | 插件找不到 | 确保 Obsidian 版本 ≥ 1.0.0 | | 连接被拒绝 | 检查 Obsidian 是否正在运行 | | API Key 无效 | 重新在插件设置中复制 Key | | 端口冲突 | 在插件设置中修改端口，并更新 mcp.json |

需要帮助？ 告诉我你遇到的具体错误信息，我来帮你解决。

---

连接成功后的提示

当 MCP 连接成功时，Claude 应该简短确认：

✅ Obsidian 已连接！检测到你的知识库，现在开始执行 [功能名称]...

---

🎯 核心功能概览

| 命令 | 功能 | 使用场景 | |------|------|----------| | /daily | 智能日记助手 | 每日开始时，快速启动一天 | | /capture <主题> | 知识捕获 | 随时记录想法、笔记 | | /review [period] | 周期回顾 | 定期总结复盘 |

---

🏗️ 推荐 Vault 结构（PARA + Zettelkasten）

Vault/
├── 00_Inbox/                 # 随手记
│   └── AI/                   # 【重要】AI 专用落地区
├── 10_Projects/              # 有截止时间的项目
├── 20_Areas/                 # 长期领域（学习/健康/职业）
├── 30_Resources/             # 资料库
│   └── Products/             # 产品卡片
├── 40_Zettels/               # 永久笔记（结论/洞见）
├── 90_Archive/               # 归档
├── 99_System/Templates/      # 模板
└── Daily Notes/              # 日记

⚠️ AI 写入三条硬规矩

Claude 必须遵守以下规则：

规则 1: AI 专用落地区

新建笔记默认位置: 00_Inbox/AI/
用户确认后才移动到其他位置

规则 2: 追加式写入

✅ 用 obsidian_append_content 追加
✅ 用 obsidian_patch_content 在指定标题下追加
❌ 不要重写整篇笔记

规则 3: Properties 白名单

# 只允许写这些字段，不能发明新字段
---
type: note | product | project | zettel
title: ""
tags: []
status: active | done | archived
created: {{date}}
---

---

📋 功能一：/daily - 智能日记助手

触发条件

• 用户输入 /daily
• 用户说「开始今天的日记」「今日日记」「daily note」

执行流程

STEP 0: MCP 连接检测（见上方）

STEP 1: 获取日记信息
├─ 尝试 obsidian_get_periodic_note(period: "daily")
├─ 如果失败，使用 obsidian_list_files_in_dir("Daily Notes") 查找今日文件
├─ 使用 obsidian_get_recent_periodic_notes 或手动获取昨日日记
└─ 检查日记是否已存在

STEP 2: 分析昨日内容
├─ 读取昨日日记内容
├─ 提取未完成的 TODO（正则匹配 `- \[ \]`）
├─ 识别重要事项
└─ 生成简要总结

STEP 3: 生成今日日记
├─ 如果今日日记不存在，创建新日记
├─ 使用标准模板结构
├─ 自动填入：
│   ├─ 昨日未完成事项 → 今日待办
│   ├─ 日期和星期（中文格式）
│   └─ 基础模板结构
└─ 使用 obsidian_append_content 写入

STEP 4: 向用户报告
├─ 显示日记创建/更新状态
├─ 列出继承的未完成任务数量
└─ 询问是否需要补充内容

日记模板结构

---
date: {{YYYY-MM-DD}}
tags: [daily]
---

# {{星期}}, {{月}} {{日}}, {{年}}

## 今日重点

> [!tip] Focus
>

## 任务

### 从昨日继承
{{yesterday_incomplete_todos}}

### 必须完成
- [ ]

### 应该完成
- [ ]

### 可以完成
- [ ]

## 今日笔记

### 上午


### 下午


### 晚间


## 想法与灵感


## 今日创建的链接


## 晚间反思

### 顺利的地方


### 可以改进的地方


### 感恩

使用示例

用户输入: /daily 或 开始今日日记

Claude 执行:

1. 检测 MCP 连接 ✓
2. 获取今日日记（如 2026-01-19）
3. 获取昨日日记，提取未完成事项
4. 创建/更新今日日记
5. 回复：「✅ 今日日记已创建！从昨日继承了 X 项未完成任务。」

---

📋 功能二：/capture - 快速知识捕获

触发条件

• 用户输入 /capture <主题> 或 /capture <主题> <内容>
• 用户说「记录一下」「捕获」「添加笔记」「capture」

执行流程

STEP 0: MCP 连接检测

STEP 1: 解析用户输入
├─ 提取主题关键词（第一个词或引号内容）
├─ 提取要记录的内容（主题之后的所有文本）
└─ 如果只有主题没有内容，询问用户要记录什么

STEP 2: 搜索现有笔记
├─ 使用 obsidian_simple_search(query: 主题) 搜索
├─ 分析搜索结果的相关性
└─ 按相关度排序

STEP 3: 决策与执行
├─ 情况A：找到高度相关笔记（标题包含主题）
│   ├─ 告诉用户：「找到相关笔记《XXX》，是否追加到此笔记？」
│   ├─ 用户确认后，使用 obsidian_patch_content 追加
│   └─ 追加格式：## {{时间戳}} 捕获\n{{内容}}
│
├─ 情况B：找到部分相关笔记
│   ├─ 列出最相关的 3 个笔记
│   ├─ 询问：「选择追加到哪个笔记，或创建新笔记？」
│   └─ 根据用户选择执行
│
└─ 情况C：未找到相关笔记
    ├─ 告诉用户：「未找到相关笔记，将创建新笔记」
    ├─ 询问存放位置（列出现有文件夹）
    └─ 使用 obsidian_append_content 创建

STEP 4: 确认完成
└─ 显示：「✅ 已保存到《XXX》」

捕获内容格式

## 2026-01-19 14:30 捕获

{{用户输入的内容}}

---

使用示例

示例 1:

用户: /capture API设计 RESTful API 应该使用名词而非动词

Claude: 搜索 → 找到「API设计最佳实践.md」→ 询问确认 → 追加内容

示例 2:

用户: /capture 新想法

Claude: 「你想记录什么内容？」→ 用户输入 → 搜索 → 处理

---

📋 功能三：/review - 周期回顾生成器

触发条件

• 用户输入 /review 或 /review weekly 或 /review monthly
• 用户说「周回顾」「月度总结」「复盘」「review」

执行流程

STEP 0: MCP 连接检测

STEP 1: 确定回顾周期
├─ 解析参数：daily / weekly（默认）/ monthly
└─ 计算时间范围

STEP 2: 收集数据
├─ 获取周期内的日记文件
│   ├─ 尝试 obsidian_get_recent_periodic_notes
│   └─ 备选：obsidian_list_files_in_dir + 日期过滤
├─ 使用 obsidian_batch_get_file_contents 批量读取
├─ 使用 obsidian_get_recent_changes 获取活跃文件
└─ 提取所有相关内容

STEP 3: 分析内容
├─ 统计任务完成情况
│   ├─ 已完成：匹配 `- \[x\]`
│   └─ 未完成：匹配 `- \[ \]`
├─ 提取重要事件和成就
├─ 识别高频主题词
├─ 发现知识关联
└─ 生成洞察

STEP 4: 生成报告
├─ 使用对应周期的模板
├─ 填充统计数据
├─ 添加分析内容
├─ 保存到 Daily Notes/ 文件夹
│   ├─ 周报：YYYY-WXX 周回顾.md
│   └─ 月报：YYYY-MM 月度回顾.md
└─ 使用 obsidian_append_content 写入

STEP 5: 展示结果
├─ 显示回顾摘要
├─ 列出关键数据
└─ 询问是否需要修改或补充

周回顾模板

# {{年}}-W{{周}} 周回顾 | {{日期范围}}

## 📊 数据概览
| 指标 | 数值 |
|------|------|
| 📝 笔记数量 | {{count}} |
| ✅ 完成任务 | {{completed}} |
| ⏳ 未完成任务 | {{incomplete}} |
| 📂 活跃文件 | {{active}} |

## 🏆 本周成就
{{achievements}}

## 📋 任务总结

### ✅ 已完成
{{completed_list}}

### ⏳ 待继续
{{incomplete_list}}

## 💡 关键洞察
{{insights}}

## 🔗 知识连接
本周涉及的主要主题：{{themes}}

## 🎯 下周重点
1.
2.
3.

## 📝 反思
### 做得好的地方

### 可以改进的地方

---
*生成时间: {{timestamp}}*

---

🔧 配置选项

用户可以在 Obsidian 库中创建 _config/obsidian-helper.md 自定义配置：

# Obsidian Helper 配置

## 日记设置
- 日记文件夹: Daily Notes/
- 日记格式: YYYY-MM-DD
- 周回顾格式: YYYY-[W]ww

## 捕获设置
- 默认捕获文件夹: Resources/
- 自动添加时间戳: true

## 回顾设置
- 默认回顾周期: weekly
- 回顾保存位置: Daily Notes/

Claude 在执行功能前，应检查是否存在此配置文件并读取设置。

---

🛠️ 技术实现

依赖的 MCP 工具

| 工具 | 用途 | 必需 | |------|------|------| | obsidian_list_files_in_vault | 检测连接、列出库结构 | ✅ | | obsidian_list_files_in_dir | 列出目录文件 | ✅ | | obsidian_get_file_contents | 读取文件内容 | ✅ | | obsidian_batch_get_file_contents | 批量读取 | ✅ | | obsidian_simple_search | 文本搜索 | ✅ | | obsidian_append_content | 创建/追加内容 | ✅ | | obsidian_patch_content | 精确编辑 | ⚪ | | obsidian_get_periodic_note | 获取周期笔记 | ⚪ | | obsidian_get_recent_periodic_notes | 最近周期笔记 | ⚪ | | obsidian_get_recent_changes | 最近修改 | ⚪ |

错误处理策略

| 错误类型 | 处理方式 | |----------|----------| | MCP 未连接 | 显示完整配置引导（见上方） | | 文件不存在 | 自动创建 | | API 不可用 | 使用备选方法（如直接文件操作） | | 搜索无结果 | 提示创建新笔记 |

---

📚 快速参考

/daily                    → 启动今日日记，继承昨日未完成
/capture <主题>           → 快速捕获到相关笔记
/capture <主题> <内容>    → 捕获指定内容
/review                   → 生成周回顾（默认）
/review daily             → 生成日回顾
/review weekly            → 生成周回顾
/review monthly           → 生成月回顾

---

🆘 帮助命令

当用户输入以下内容时，显示帮助信息：

• obsidian help
• obsidian 帮助
• /daily help
• 怎么用 obsidian helper

显示内容：

📖 Obsidian Helper 使用指南

🗓️ /daily - 智能日记
   自动创建今日日记，继承昨日未完成任务

📝 /capture <主题> [内容] - 知识捕获
   快速记录想法到相关笔记
   示例：/capture API设计 REST要用名词

📊 /review [weekly|monthly] - 周期回顾
   自动分析笔记，生成回顾报告

⚙️ 配置问题？
   输入「配置 obsidian」查看 MCP 配置指南

---

Obsidian Helper v1.1.0 - 让笔记更智能