Claudesidian：Claude Code + Obsidian 入门套件

使用 Claude Code 将你的 Obsidian 私库转变为一个由 AI 驱动的第二大脑。

这是什么？

这是一个预配置的 Obsidian 私库结构，旨在与 Claude Code 无缝协作，使你能够：

• 将 AI 视为思考伙伴，而不仅仅是写作助手
• 使用 PARA 方法组织知识
• 通过 Git 实现版本控制
• 随时随地访问你的私库（包括在移动设备上）

快速开始

1. 获取入门套件

选项 A：使用 Git 克隆

# 使用你喜欢的文件夹名称进行克隆（将 'my-vault' 替换为你喜欢的名称）
git clone https://github.com/heyitsnoah/claudesidian.git my-vault
cd my-vault

# 示例：
# git clone https://github.com/heyitsnoah/claudesidian.git obsidian-notes
# git clone https://github.com/heyitsnoah/claudesidian.git knowledge-base
# git clone https://github.com/heyitsnoah/claudesidian.git second-brain

选项 B：下载 ZIP 文件（无需 Git）

1. 在 GitHub 上点击“Code”→“Download ZIP”
2. 解压到你想要的位置
3. 在 Claude Code 中打开该文件夹

2. 运行设置向导

# 在目录中启动 Claude Code
claude

# 在 Claude Code 中运行交互式设置向导
/init-bootstrap

这将：

• 自动安装依赖项
• 断开与原始 claudesidian 仓库的连接
• 智能分析你现有的私库结构和模式
• 安全地导入你现有的 Obsidian 私库到 OLD_VAULT/ 目录下（如果你有的话）
• 在征得你同意的情况下，检索你的公开作品以提供个性化上下文
• 询问你的工作流偏好
• 创建个性化的 CLAUDE.md 配置
• 设置你的文件夹结构
• 可选地配置 Gemini Vision 以进行图像/视频分析
• 可选地配置 Firecrawl 以进行网络研究
• 初始化 Git 以实现版本控制

3. 在 Obsidian 中打开（可选但推荐）

• 下载 Obsidian
• 从 claudesidian 文件夹中打开私库
• 这样你就可以在 Claude Code 的同时使用 Obsidian 的可视化界面

4. 你的第一次会话

告诉 Claude Code：

我正在开始一个关于[主题]的新项目。
我现在处于思考模式，而不是写作模式。
请在我的私库中搜索任何相关的现有笔记，
然后通过提问来帮助我探索这个主题。

或者使用 Claude Code 中预配置的命令之一：

/thinking-partner   # 用于协作式探索
/daily-review       # 用于每日回顾
/research-assistant # 用于深入研究主题

文件夹结构

claudesidian/
├── 00_Inbox/           # 新想法的临时收集点
├── 01_Projects/        # 有时间限制的正在进行的项目
├── 02_Areas/           # 持续性的责任领域
├── 03_Resources/       # 参考资料和知识库
├── 04_Archive/         # 已完成的项目和不再活跃的内容
├── 05_Attachments/     # 图片、PDF 等文件
├── 06_Metadata/        # 私库配置和模板
│   ├── Reference/      # 文档和指南
│   └── Templates/      # 可重用的笔记模板
└── .scripts/           # 用于自动化的辅助脚本

核心概念

思考模式 vs 写作模式

思考模式（研究与探索）：

• Claude 会提出问题以理解你的目标
• 搜索现有笔记以找到相关内容
• 帮助建立不同想法之间的联系
• 记录见解和进展

写作模式（内容创作）：

• 根据你的研究生成草稿
• 帮助组织和编辑内容
• 制作最终成果

PARA 方法

项目：有明确的截止日期和具体成果

• 示例：“2025 年第四季度营销战略”
• 创建于 01_Projects/ 文件夹中

领域：持续进行且无明确结束日期

• 示例：“健康”、“财务”、“团队管理”
• 存在于 02_Areas/ 文件夹中

资源：持续感兴趣的主题

• 示例：“AI 研究”、“写作技巧”
• 存放在 03_Resources/ 文件夹中

归档：不再活跃的内容

• 包括已完成项目及其成果
• 以及不再相关的旧笔记

技能

Claudesidian 自带代理技能，当你描述任务时会自动发现。这些技能可在 Claude Code、OpenCode、Codex、Cursor 和 Pi 中使用——它们位于 .agents/skills/<name>/SKILL.md（规范路径），并在 .claude/skills/ 和 .pi/skills/ 中设有符号链接。

• thinking-partner - 通过提问探索想法
• inbox-processor - 整理你的收集内容
• research-assistant - 深入研究主题
• daily-review - 每日回顾
• weekly-synthesis - 发现一周中的规律
• de-ai-ify - 从文本中移除 AI 写作风格
• add-frontmatter - 为笔记添加 YAML 属性
• download-attachment - 将 URL 保存到附件文件夹
• pragmatic-review - 符合 YAGNI/KISS 原则的代码审查
• pull-request - 根据你的更改创建拉取请求
• release - 发布新的 Claudesidian 版本
• upgrade - 更新到最新版本的 Claudesidian
• init-bootstrap - 重新运行设置向导
• install-claudesidian-command - 安装 Shell 命令，以便从任何地方启动私库

当你描述所需操作时，技能会自动触发——例如，“总结一下今天的工作”会加载 daily-review，“为此创建一个拉取请求”会加载 pull-request。无需使用斜杠命令。

使用 upgrade 保持更新

Claudesidian 会在你启动 Claude Code 时自动检查更新，并在有新功能可用时提醒你运行 upgrade 技能。

升级命令会智能地合并新功能，同时保留你的自定义设置：

# 首先预览将要更新的内容（建议先执行）
/upgrade check

# 运行交互式的升级
/upgrade

# 跳过确认以安全更新（高级选项）
/upgrade force

升级会做什么：

• 在进行任何更改之前创建带有时间戳的备份
• 在更新每个文件之前显示差异对比
• 保留你的个人笔记和自定义设置
• 只更新系统文件（命令、代理、脚本）
• 绝不会触及你的内容文件夹（00_Inbox、01_Projects 等）
• 提供必要的回滚功能

安全特性：

• 你的所有个人内容都受到保护
• 在 .backup/upgrade-[timestamp]/ 中创建完整备份
• 对每个文件进行逐一审查并确认
• 进度记录在 .upgrade-checklist.md 中
• 可随时停止或继续升级

视觉与文档分析（可选）

在配置了 Google Gemini MCP 后，Claude Code 可以直接处理你的附件，而无需你对其进行描述。这意味着：

• 直接图像分析：Claude 能看到实际的图像，而不是你的描述
• PDF 文本提取：无需复制粘贴即可获取完整文档文本
• 批量处理：一次分析多张截图或多个文档
• 智能整理：根据图像内容自动生成文件名
• 对比任务：比较前后截图、设计等

为什么这很重要：与其描述“一张显示错误信息的截图”，Claude Code 直接查看并读取错误内容。这对于调试 UI 问题、分析图表或处理扫描文档非常理想。

如何获取 Gemini API 密钥：

1. 访问 Google AI Studio
2. 使用 Google 账号登录
3. 点击左侧边栏中的“获取 API 密钥”
4. 创建一个新的 API 密钥（免费！）
5. 在环境变量中设置：export GEMINI_API_KEY="your-key-here"

完整设置说明请参阅 .claude/mcp-servers/README.md

网络研究（可选）

在配置了 Firecrawl 后，我们的辅助脚本会直接将完整的网页内容抓取并保存到你的知识库中。这意味着：

• 全文捕获：脚本会将整篇文章的文本输出到文件，而不是摘要
• 上下文保留：Claude 不需要在内存中存储网页内容
• 批量处理：使用 firecrawl-batch.sh 一次性保存多篇文章
• 干净的 Markdown 格式：将网页转换为可读、可搜索的 Markdown 格式
• 永久存档：你的研究内容将永远保存在你的知识库中

为什么这很重要：与其让 Claude 阅读网页并总结内容（从而丢失细节），不如使用脚本保存完整的文本。这样，Claude 就可以在不超出上下文限制的情况下搜索和分析数千篇已保存的文章。这对于研究项目、文档存档或构建知识库来说非常理想。

示例工作流程：

# 保存单篇文章
npm run firecrawl:scrape -- "https://example.com/article" "03_Resources/Articles"

# 批量保存多个 URL
npm run firecrawl:batch -- urls.txt "03_Resources/Research"

如何获取 Firecrawl API 密钥：

1. 访问 Firecrawl 并注册
2. 获取 300 次免费调用额度开始使用（开源，支持自托管）
3. 进入仪表盘找到你的 API 密钥
4. 复制密钥（格式：fc-xxxxx...）
5. 在环境变量中设置：export FIRECRAWL_API_KEY="fc-your-key-here"

辅助脚本

使用 pnpm 运行以下命令：

• attachments:list - 显示未处理的附件
• attachments:organized - 统计已整理的文件数量
• attachments:sizes - 查找大文件
• attachments:orphans - 查找未被引用的附件
• vault:stats - 显示知识库统计信息

高级设置

从任意位置快速启动

安装一个 shell 命令，以便从任何目录启动你的知识库：

# 在 Claude Code 中运行：
/install-claudesidian-command

这会创建一个名为 claudesidian 的别名，它会：

• 自动切换到你的知识库目录
• 尝试恢复现有的会话（如果存在）
• 如果没有会话，则启动一个新的会话
• 完成后返回到你原来的目录

使用方法：

# 从终端的任何位置运行：
claudesidian

# 它会自动恢复上次会话或启动一个新的会话

该命令会被添加到你的 shell 配置文件（/.zshrc、/.bashrc 等）中，因此在每次打开终端时都会生效。

Git 集成

初始化 Git 以进行版本控制：

git init
git add .
git commit -m "初始知识库设置"
git remote add origin your-repo-url
git push -u origin main

最佳实践：

• 每次工作结束后提交一次
• 使用描述性的提交信息
• 在开始工作前先拉取最新代码

移动端访问

1. 搭建一个小服务器（迷你 PC、云 VPS 或家用服务器）
2. 安装 Tailscale 以实现安全的 VPN 访问
3. 将你的知识库克隆到服务器上
4. 在手机上使用 Termius 或类似的 SSH 客户端
5. 远程运行 Claude Code

自定义命令

通过将指令保存到 .claude/commands/ 目录来创建专用命令：

研究助理（06_Metadata/Agents/research-assistant.md）：

你是一名研究助理。

- 在知识库中搜索相关信息
- 整合来自多个来源的研究成果
- 识别知识缺口
- 提出进一步探索的方向

小贴士与最佳实践

经验之谈

1. 先思考再行动：不要急于立即生成内容
2. 尽可能多地提供上下文：更多的上下文能带来更好的结果
3. 保存一切：捕捉聊天记录、片段以及部分想法
4. 信任但验证：始终仔细阅读 AI 生成的内容
5. 适时中断：AI 可以帮助你轻松恢复工作状态

故障排除

Claude Code 找不到我的笔记

• 确保你是在知识库根目录下运行 Claude Code
• 检查文件权限
• 确认 Markdown 文件具有 .md 扩展名

Git 冲突

• 在开始工作前务必先拉取最新代码
• 经常提交，并附上清晰的提交信息
• 对于实验性更改，请使用分支

附件管理

• 运行 npm run attachments:create-organized 来设置文件夹结构
• 使用辅助脚本查找孤立的文件
• 为便于 Git 管理，建议将附件大小控制在 10MB 以内

哲学理念

此设置基于以下核心原则：

1. AI 放大思考能力，而不仅仅是写作能力
2. 本地文件意味着完全掌控
3. 结构化有助于激发创造力
4. 迭代胜过完美
5. 目标是洞察力，而非单纯的信息

贡献方式

我们欢迎社区的贡献！这是一个不断完善的模板，受益于每个人的参与。

如何贡献

1. 在 GitHub 上 fork 该仓库
2. 创建一个功能分支（git checkout -b feature/amazing-feature）
3. 进行修改
4. 测试你的更改，确保一切正常运行
5. 提交更改（git commit -m '添加超赞功能'）
6. 推送到分支（git push origin feature/amazing-feature）
7. 打开一个带有清晰说明的 Pull Request，解释你所做的工作

我们期待的贡献

• 新命令：适用于常见工作流程的实用 Claude Code 命令
• 新代理：针对特定任务的专业代理
• 文档改进：更优秀的说明、示例或指南
• 错误修复：发现 bug？请修复它！
• 工作流程模板：分享你的高效工作流程
• 辅助脚本：使知识库管理更便捷的自动化工具
• 集成指南：将 Claudesidian 与其他工具连接起来
• 核心更新：对升级系统、设置向导或其他核心功能的改进

指南

• 保持命令简洁且单一功能
• 编写清晰的文档并附带示例
• 提交前进行充分测试
• 遵循现有代码风格和结构
• 更新 CHANGELOG.md 文件以记录您的更改
• 欢迎使用 AI 生成的内容，但您必须在提交前仔细阅读并审查所有内容——切勿提交您不理解的代码

获取更新

当有新功能被贡献并合并后，用户可以通过以下命令轻松获取：

/upgrade

升级命令会智能地将新功能合并到现有代码中，同时保留您的个性化配置，使您能够轻松受益于社区贡献，而不会丢失自己的工作成果。

有问题或想法吗？

• 在开始工作之前，请先开一个议题讨论重大变更
• 参与现有议题的讨论
• 分享您的使用场景——这有助于我们更好地理解需求

请记住：最佳实践源于实际使用，而非理论。您的真实使用经验会让整个项目对每个人都有所裨益！

资源

• Obsidian 官方文档
• PARA 方法
• Claude Code 官方文档

灵感来源

本入门工具包的灵感来源于以下内容中讨论的工作流：

• 如何将 Claude Code 用作第二大脑 —— Noah Brier 对 Dan Shipper 的访谈
• 由 Alephic 团队构建——一家以 AI 为导向的战略与软件合作伙伴，帮助企业通过定制化 AI 系统解决复杂挑战

许可证

MIT 许可证——您可以自由地按任何方式使用本项目，并根据需要进行修改。

---

请记住：骑自行车刚开始时可能会觉得摇晃，但很快您就会忘记它曾经有多难。

Claudesidian 快速上手指南

Claudesidian 是一个预配置的 Obsidian 知识库模板，旨在与 Claude Code 无缝协作。它将你的本地笔记库转变为由 AI 驱动的“第二大脑”，支持 PARA 知识管理法、Git 版本控制以及深度的 AI 思维协作。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS, Linux 或 Windows (WSL2 推荐)
• 核心依赖：
  • Node.js (建议 v18+)
  • Git
  • pnpm (包管理工具)
  • Claude Code (需已安装并配置好 API Key)
• 可选工具：
  • Obsidian：用于可视化查看和管理笔记。
  • Google Gemini API Key：用于图像/PDF 分析（可选）。
  • Firecrawl API Key：用于网页内容抓取（可选）。

提示：国内用户若遇到 npm/pnpm 下载缓慢，可临时切换镜像源： pnpm config set registry https://registry.npmmirror.com

安装步骤

1. 获取项目代码

你可以选择通过 Git 克隆或直接下载 ZIP 包。推荐使用 Git 以便后续更新。

方式 A：使用 Git 克隆（推荐）

# 将仓库克隆到你喜欢的文件夹名称（例如 my-vault）
git clone https://github.com/heyitsnoah/claudesidian.git my-vault
cd my-vault

# 安装依赖
pnpm install

方式 B：下载 ZIP 包

1. 在 GitHub 页面点击 "Code" → "Download ZIP"。
2. 解压到本地目录。
3. 终端进入该目录并运行 pnpm install。

2. 运行初始化向导

进入目录后，启动 Claude Code 并运行内置的引导程序。这将自动配置环境、迁移旧笔记（如有）并生成个性化配置文件。

# 启动 Claude Code
claude

# 在 Claude Code 交互界面中，输入以下命令运行向导
/init-bootstrap

向导将执行以下操作：

• 自动安装缺失的依赖。
• 断开与原仓库的关联，使其成为你的独立项目。
• 智能分析现有结构，若有旧 Obsidian 库会安全导入至 OLD_VAULT/。
• 询问你的工作流偏好，生成个性化的 CLAUDE.md。
• 初始化 Git 版本控制。
• （可选）配置 Gemini Vision 和 Firecrawl。

3. 连接 Obsidian（可选但推荐）

为了获得图形化界面体验：

1. 打开 Obsidian 软件。
2. 选择 "Open folder as vault"（打开文件夹作为库）。
3. 指向你刚才克隆的 my-vault 目录。

基本使用

安装完成后，你可以通过两种模式与 AI 协作：思考模式（探索与提问）和 写作模式（内容生成）。

启动会话

在终端进入项目目录，运行：

claude

常用指令示例

1. 开启新项目（思考模式） 告诉 Claude 你想探索一个主题，让它先检索库中现有笔记并提出问题，而不是直接生成文章。

I'm starting a new project about [你的主题].
I'm in thinking mode, not writing mode.
Please search my vault for any relevant existing notes,
then help me explore this topic by asking questions.

2. 使用预设技能命令 Claudesidian 内置了多种自动化技能，可直接在对话中调用：

• 协作探索：

  /thinking-partner
  

• 每日复盘：

  /daily-review
  

• 深度研究：

  /research-assistant
  

注意：部分技能支持自然语言触发。例如，直接说 "wrap up my day" 会自动加载 daily-review 技能，无需输入斜杠命令。

目录结构概览

系统采用 PARA 方法 组织文件，建议遵循以下结构存放笔记：

• 00_Inbox/：临时收集的新想法。
• 01_Projects/：有明确截止日期的活跃项目。
• 02_Areas/：长期持续的責任领域（如健康、财务）。
• 03_Resources/：参考材料和知识库。
• 04_Archive/：已完成的项目或非活跃内容。
• 06_Metadata/：包含模板和系统配置。

保持更新

当有新功能发布时，Claude Code 会提示你升级。运行以下命令可安全更新系统文件（不会触碰你的个人笔记）：

# 在 Claude Code 中运行
/upgrade