obsidian-helper

执行任何功能前，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/

├── 00_Inbox/ # 随手记

│ └── AI/ # 【重要】AI 专用落地区

├── 10_Projects/ # 有截止时间的项目

├── 20_Areas/ # 长期领域（学习/健康/职业）

├── 30_Resources/ # 资料库

│ └── Products/ # 产品卡片

├── 40_Zettels/ # 永久笔记（结论/洞见）

├── 90_Archive/ # 归档

├── 99_System/Templates/ # 模板

└── Daily Notes/ # 日记

```

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 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」

执行流程

```

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

{{用户输入的内容}}

---

```

使用示例

示例 1:

```

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

```

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

示例 2:

```

用户: /capture 新想法

```

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

---

触发条件

• 用户输入 /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 - 让笔记更智能