obsidian-helper

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: obsidian-helper
description: |
  Obsidian 智能笔记助手。当用户提到 obsidian、日记、笔记、知识库、capture、review 时激活。

  【激活后必须执行】：
  1. 先完整阅读本 SKILL.md 文件
  2. 理解 AI 写入三条硬规矩（00_Inbox/AI/、追加式、白名单字段）
  3. 按 STEP 0 → STEP 1 → ... 顺序执行
  4. 不要跳过任何步骤，不要自作主张

  【禁止行为】：
  - 禁止不读 SKILL.md 就开始工作
  - 禁止跳过用户确认步骤
  - 禁止在非 00_Inbox/AI/ 位置创建新笔记（除非用户明确指定）
version: 1.4.0
author: Claude Code
---

# 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}}

### 必须完成
- [ ]

### 应该完成
- [ ]

### 可以完成
- [ ]

## 今日笔记

### 上午


### 下午


### 晚间


## 想法与灵感


## 今日创建的链接