> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/AgriciDaniel/claude-obsidian) · [上游 README](https://github.com/AgriciDaniel/claude-obsidian/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 # claude-obsidian：面向 Obsidian + Claude Code 的自组织 AI 第二大脑

[](https://github.com/AgriciDaniel/claude-obsidian/stargazers) [](LICENSE) [](https://github.com/AgriciDaniel/claude-obsidian/releases/latest) [](https://github.com/AgriciDaniel/claude-obsidian/actions/workflows/test.yml) [](https://code.claude.com/docs/en/discover-plugins) [](https://obsidian.md) [](https://agentskills.io) [](https://www.skool.com/ai-marketing-hub-pro) [](https://agricidaniel.com/blog/claude-obsidian-ai-second-brain) Claude + Obsidian 知识伴侣与自组织 AI 第二大脑。一个持续运行的 AI 笔记助手，用于构建并维护持久、复利增长的 wiki 知识库。你添加的每个来源都会被整合进来。你提出的每个问题都会从已读内容中检索。知识像利息一样复利增长。 面向 AI 笔记、个人知识管理（PKM）、第二大脑工作流，以及私有 Notion 替代方案的开源 Obsidian AI 插件。**15 个 Claude Code 技能**、多智能体支持、多写者安全（v1.7+）、一流方法论模式（LYT / PARA / Zettelkasten / Generic，自 v1.8 起），以及 10 原则思维框架（v1.9）。基于 [Andrej Karpathy 的 LLM Wiki 模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). > **获取该技能的两种方式。** 选择适合你工作方式的一种。 > > - 🌐 **公开开源构建**（最新：`v1.9.2`，推荐）：[Daniel Agrici 的 GitHub](https://github.com/AgriciDaniel/claude-obsidian). 上的免费 MIT 许可版本。向所有人开放，无需会员资格。包含全部内容：v1.7 Compound Vault、v1.8 方法论模式，以及 v1.9 思维框架与审计加固。 > - ⚡ **AI Marketing Hub Pro**：相同的 MIT 许可核心，另可最早获得开发中功能（先于公开版落地）、直接协作机会，以及 [Pro 社区](https://www.skool.com/ai-marketing-hub-pro). Pro 成员从 [AI Marketing Hub](https://github.com/AI-Marketing-Hub) 组织镜像安装（见下方 Option 2 的替换说明）。 > ✨ **v1.7「Compound Vault」重构**：默认采用 Obsidian CLI 作为传输层，混合检索（上下文前缀 + BM25 + 余弦重排序，依据 [Anthropic 2024 年 9 月研究](https://www.anthropic.com/news/contextual-retrieval)), 按文件咨询锁，修复潜在的多写者损坏漏洞，并与 [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills). 基座对齐。完整指南：[docs/compound-vault-guide.md](docs/compound-vault-guide.md)。可选 [DragonScale Memory](docs/dragonscale-guide.md) 扩展（日志折叠、确定性页面地址、语义分块 lint、边界优先 autoresearch）。 --- ## 目录 - [功能概览](#what-it-does) - [为何选择 claude-obsidian？](#why-claude-obsidian) - [快速开始](#quick-start) - [命令](#commands) - [`/wiki`：setup、scaffold、continue](#wiki-setup-scaffold-continue) - [`/autoresearch`：自主研究循环](#autoresearch-autonomous-research-loop) - [`/canvas`：可视化层](#canvas-visual-layer) - [`/think`：10 原则思维循环](#think-10-principle-thinking-loop) - [方法论模式（v1.8+）](#methodology-modes-v18) - [知识库用例（v1.0+）](#vault-use-cases-v10) - [跨项目知识库](#cross-project-knowledge-base) - [会创建什么](#what-gets-created) - [架构](#architecture) - [MCP 设置（可选）](#mcp-setup-optional) - [插件](#plugins) - [CSS 片段](#css-snippets-auto-enabled-by-setup-vaultsh) - [Banner 插件](#banner-plugin) - [文件结构](#file-structure) - [AutoResearch 配置](#autoresearch-programmd) - [种子知识库](#seed-vault) - [配套工具：claude-canvas](#companion-claude-canvas) - [常见问题](#faq) - [系统要求](#requirements) - [卸载](#uninstall) - [贡献](#contributing) - [相关项目](#related-projects) - [社区](#community) - [许可证](#license) --- ## 功能概览 ### [YouTube 演示](https://www.youtube.com/watch?v=a2hgayvr-H4)

你投入来源材料。Claude 阅读它们，提取实体与概念，更新交叉引用，并将一切归档到结构化的 Obsidian 知识库中。每次摄入都会让 wiki 更丰富。 你提出问题。Claude 读取热缓存（近期上下文），扫描索引，深入相关页面，并综合给出答案。它引用具体的 wiki 页面，而非训练数据。 你执行 lint。Claude 发现孤立页、死链、过时论断和缺失的交叉引用。你的 wiki 无需手动清理即可保持健康。 每次会话结束时，Claude 会更新热缓存。下一次会话以完整的近期上下文开始，无需回顾。

--- ## 为何选择 claude-obsidian？ 大多数 Obsidian AI 插件是聊天界面。它们回答关于你现有笔记的问题。claude-obsidian 是知识引擎。它自主创建、组织、维护并演进你的笔记。 | 能力 | claude-obsidian | Smart Connections | Copilot | |---|---|---|---| | **自动整理笔记** | ✅ 创建实体、概念、交叉引用 | ❌ | ❌ | | **矛盾标注** | ✅ `[!contradiction]` 标注并附来源 | ❌ | ❌ | | **会话记忆** | ✅ 热缓存在对话间持久保存 | ❌ | ❌ | | **知识库维护** | ✅ 8 类 lint（孤立页、死链、缺口） | ❌ | ❌ | | **自主研究** | ✅ 3 轮网络研究并填补缺口 | ❌ | ❌ | | **方法论模式** | ✅ LYT / PARA / Zettelkasten / Generic（一流支持） | ❌ | ❌ | | **思维框架** | ✅ 10 原则循环，可作为可调用技能 | ❌ | ❌ | | **多模型支持** | ✅ Claude、Gemini、Codex、Cursor、Windsurf | ❌ 仅 Claude | ✅ 多种 | | **可视化画布** | ✅ 通过 [claude-canvas](https://github.com/AgriciDaniel/claude-canvas) | ❌ | ❌ | | **多写者安全** | ✅ 按文件咨询锁（v1.7+） | ❌ | ❌ | | **带引用的查询** | ✅ 引用具体 wiki 页面 | ✅ 引用相似笔记 | ✅ 引用笔记 | | **批量摄入** | ✅ 多来源并行智能体 | ❌ | ❌ | | **开源** | ✅ MIT | ✅ MIT | ⚠️ Freemium | > 📖 **深度解读：** [I Turned Obsidian Into a Self-Organizing AI Brain](https://agricidaniel.com/blog/claude-obsidian-ai-second-brain). 含数据可视化、市场背景与工作流演示的完整拆解。 --- ## 快速开始 > ℹ️ 以下命令安装的是来自 `AgriciDaniel/claude-obsidian` 的**公开开源构建**（推荐，无需会员资格）。希望最早获得开发中功能的 **AI Marketing Hub Pro 成员**可将 `AgriciDaniel/claude-obsidian` 替换为 `AI-Marketing-Hub/claude-obsidian`（Option 2 也会替换插件 slug；见该选项下的说明）。 ### 方案 1：克隆为库（推荐，2 分钟完成完整配置） ```bash git clone https://github.com/AgriciDaniel/claude-obsidian cd claude-obsidian bash bin/setup-vault.sh ``` 在 Obsidian 中打开该文件夹：**管理库（Manage Vaults）→ 将文件夹作为库打开（Open folder as vault）→ 选择 `claude-obsidian/`**。 在同一文件夹中打开 Claude Code。输入 `/wiki`。 > ℹ️ `setup-vault.sh` 会配置 `graph.json`（筛选 + 颜色）、`app.json`（排除插件目录）和 `appearance.json`（启用 CSS）。在首次打开 Obsidian 之前运行一次即可。开箱即用即可获得完整预配置的图谱视图、配色方案和 wiki 结构。 --- ### 方案 2：作为 Claude Code 插件安装 插件安装分两步：先添加市场目录，再从其中安装插件。 > ℹ️ **你要安装哪个版本？** > > - **公开版（推荐，无需会员）：** 下方命令会安装来自 [`AgriciDaniel/claude-obsidian`](https://github.com/AgriciDaniel/claude-obsidian). 的免费 MIT 许可版本。无需注册。 > - **AI Marketing Hub Pro 会员？** 若要抢先体验开发中功能，将 `AgriciDaniel/claude-obsidian` 替换为 `AI-Marketing-Hub/claude-obsidian`，并将插件 slug `claude-obsidian@agricidaniel-claude-obsidian` 替换为 `claude-obsidian@ai-marketing-hub-claude-obsidian`。组织镜像需要已通过身份验证的 `gh auth login`（或 GitHub PAT），且有权访问 `AI-Marketing-Hub` 组织。若 `/plugin marketplace add` 返回 404，说明你的账户尚未加入该组织。请在 [Skool 社区](https://www.skool.com/ai-marketing-hub-pro) 私信申请加入。 ```bash # Step 1: add the marketplace claude plugin marketplace add AgriciDaniel/claude-obsidian # Step 2: install the plugin claude plugin install claude-obsidian@agricidaniel-claude-obsidian ``` 在任意 Claude Code 会话中：`/wiki`。Claude 会引导你完成库配置。 验证是否安装成功： ```bash claude plugin list ``` --- ### 方案 3：添加到现有库 将 `WIKI.md` 复制到你的库根目录。粘贴给 Claude： ``` Read WIKI.md in this project. Then: 1. Check if Obsidian is installed. If not, install it. 2. Check if the Local REST API plugin is running on port 27124. 3. Configure the MCP server. 4. Ask me ONE question: "What is this vault for?" Then scaffold the full wiki structure. ``` --- ## 命令 | 你说 | Claude 会 | |---------|------------| | `/wiki` | 设置检查、脚手架搭建，或从上次中断处继续 | | `ingest [file]` | 读取来源，创建 8-15 个 wiki 页面，更新索引和日志 | | `ingest all of these` | 批量处理多个来源，然后交叉引用 | | `what do you know about X?` | 读取索引，深入相关页面，综合生成答案 | | `/save` | 将当前对话归档为 wiki 笔记 | | `/save [name]` | 以指定标题保存（跳过命名询问） | | `/autoresearch [topic]` | 运行自主研究循环：搜索、抓取、综合、归档 | | `/canvas` | 打开或创建可视化画布，列出区域和节点 | | `/canvas add image [path]` | 将图片（URL 或本地路径）添加到画布并自动布局 | | `/canvas add text [content]` | 向画布添加 Markdown 文本卡片 | | `/canvas add pdf [path]` | 将 PDF 文档添加为渲染预览节点 | | `/canvas add note [page]` | 将 wiki 页面固定为画布上的链接卡片 | | `/canvas zone [name]` | 添加新的带标签区域以组织可视化内容 | | `/canvas from banana` | 将最近生成的图片捕获到画布上 | | `/think [problem]` | 对非平凡问题应用十原则思考循环 | | `lint the wiki` | 健康检查：孤儿页、死链、缺口、建议 | | `update hot cache` | 用最新上下文摘要刷新 hot.md | > ✨ **想要更多？** [claude-canvas](https://github.com/AgriciDaniel/claude-canvas) 提供 12 个模板、6 种布局算法、AI 图像生成、演示文稿和完整画布编排。两者一并安装，相互补充。 ### `/wiki`：设置、脚手架、继续 首次设置流程： 1. 检查是否已安装 Obsidian 2. 检查 Local REST API 插件（若需要 MCP 传输） 3. 询问「这个库是做什么的？」（一个问题，决定脚手架方向） 4. 根据所选的[方法论模式](#methodology-modes-v18)和[库用例](#vault-use-cases-v10)搭建脚手架 5. 初始化 `hot.md`、`index.md`、`log.md`、`wiki/meta/dashboard.base` 6. 建议首次摄入 后续运行时，`/wiki` 会从上次中断处继续。它会检查库健康状态、暴露过时论断，并显示 `hot.md` 中的近期活动。 ### `/autoresearch`：自主研究循环 可配置方案见 [`skills/autoresearch/references/program.md`](skills/autoresearch/references/program.md)： - 最大轮次（默认 3） - 每会话最大页面数（默认 15） - 来源偏好规则（学术、官方文档、新闻） - 置信度评分 + 领域约束 循环流程： 1. **第 1 轮，广泛搜索**：分解为 3-5 个角度，每个角度运行 2-3 次查询，每个角度抓取前 2-3 条结果 2. **第 2 轮，补缺**：针对矛盾与缺失内容进行定向搜索 3. **第 3 轮，综合检查**（可选）：若仍有重大缺口，再跑一轮 4. **归档**：综合页 + 来源页 + 实体页 + 概念页，全部交叉引用 按 [`skills/autoresearch/SKILL.md`](skills/autoresearch/SKILL.md) 中的 `## Web egress hygiene (v1.8.2+)` 策略进行 URL 校验与内容净化：拒绝 `file://` / `javascript:` / RFC1918 主机，剥离 `