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：

```bash
# 创建 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`：

```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**

```bash
# 完全退出 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 白名单
```yaml
# 只允许写这些字段，不能发明新字段
---
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: 向用户报告
├─ 显示日记创建/更新状态
├─ 列出继承的未完成任务数量
└─ 询问是否需要补充内容
```

### 日记模板结构

```markdown
---
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》」
```

### 捕获内容格式

```markdown
## 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: 展示结果
├─ 显示回顾摘要
├─ 列出关键数据
└─ 询问是否需要修改或补充
```

### 周回顾模板

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

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

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

## 📋 任务总结

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

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

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

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

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

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

### 可以改进的地方

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

---

## 🔧 配置选项

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

```markdown
# 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 - 让笔记更智能*