Loading... # Claudian：将 Claude Code 嵌入 Obsidian 的侧边栏聊天插件 # 一、概述 ## 1. 简介 ### A. 是什么 Claudian 是一款 Obsidian 插件，将 Claude Agent（基于 Claude Agent SDK）嵌入为侧边栏聊天界面。用户的笔记库（vault）成为 Claude 的工作目录，使其具备完整的代理能力：文件读写、搜索、bash 命令和多步骤工作流。 ### B. 为什么值得关注 - 将 AI 能力直接集成到笔记工作流中 - 无需切换应用即可在 Obsidian 内使用 Claude Code - 支持完整的 Claude Agent SDK 功能集 ### C. 核心价值 - 在笔记环境中直接调用 AI 进行文件操作和代码执行 - 上下文感知的智能助手，自动关联当前笔记 - 支持多标签页、视觉识别、MCP 服务器集成等高级功能 ## 2. 前置知识 ### A. 必备条件 - 已安装 Claude Code CLI - Obsidian v1.8.9 或更高版本 - Claude 订阅或 API 密钥，或支持 Anthropic API 格式的自定义模型提供商（OpenRouter、Kimi、GLM、DeepSeek 等） - 仅支持桌面端（macOS、Linux、Windows） ### B. 推荐知识 - 熟悉 Obsidian 基础操作 - 了解 Claude Code 的基本使用方法 - 对 MCP（Model Context Protocol）有基本了解 # 二、环境准备 ## 1. 系统要求 - 操作系统：macOS、Linux 或 Windows - Obsidian 版本：v1.8.9+ - Claude Code CLI：已安装并配置 - 桌面环境（不支持移动端） ## 2. 安装步骤 ### 方式一：从 GitHub Release 安装（推荐） 1. 从最新发布版本下载 `main.js`、`manifest.json` 和 `styles.css` 三个文件 2. 在笔记库的插件文件夹中创建 `claudian` 文件夹： ``` /path/to/vault/.obsidian/plugins/claudian/ ``` 3. 将下载的文件复制到 `claudian` 文件夹中 4. 在 Obsidian 中启用插件： - 设置 → 社区插件 → 启用「Claudian」 ### 方式二：使用 BRAT 安装 BRAT（Beta Reviewers Auto-update Tester）允许直接从 GitHub 安装和自动更新插件。 1. 从 Obsidian 社区插件安装 BRAT 插件 2. 在设置 → 社区插件中启用 BRAT 3. 打开 BRAT 设置，点击「Add Beta plugin」 4. 输入仓库 URL：`https://github.com/YishenTu/claudian` 5. 点击「Add Plugin」，BRAT 将自动安装 Claudian 6. 在设置 → 社区插件中启用 Claudian ### 方式三：从源码安装（开发模式） 1. 将仓库克隆到笔记库的插件文件夹： ``` cd /path/to/vault/.obsidian/plugins git clone https://github.com/YishenTu/claudian.git cd claudian ``` 2. 安装依赖并构建： ``` npm install npm run build ``` 3. 在 Obsidian 中启用插件 ## 3. 验证安装 安装完成后，在 Obsidian 中： - 检查功能区是否出现机器人图标 - 尝试打开聊天侧边栏 - 验证 Claude CLI 是否被正确识别 # 三、核心概念 ## 1. 基本术语 ### A. Claudian Service Claude Agent SDK 的包装器，负责与 Claude API 的通信和会话管理。 ### B. Slash Commands 可重用的提示词模板，通过 `/command` 触发，支持参数占位符、`@file` 引用和可选的内联 bash 替换。 ### C. Skills 可重用的能力模块，基于上下文自动调用，兼容 Claude Code 的技能格式。 ### D. MCP Servers 通过 Model Context Protocol 连接外部工具和数据源，支持 stdio、SSE 和 HTTP 三种模式。 ### E. Inline Edit 内联编辑模式，可直接在笔记中编辑选中文本或在光标位置插入内容，提供单词级差异预览。 ## 2. 系统架构 ```mermaid graph TB User[用户] --> Obsidian[Obsidian] Obsidian --> Claudian[Claudian Plugin] Claudian --> SDK[Claude Agent SDK] SDK --> ClaudeAPI[Claude API] Claudian --> Vault[笔记库 Vault] Claudian --> MCP[MCP Servers] Claudian --> Plugins[Claude Code Plugins] Claudian --> FileSystem[文件系统] Vault --> FileOps[文件读写操作] MCP --> ExternalTools[外部工具] Plugins --> Skills[技能扩展] FileSystem --> Bash[Bash 命令执行] ```  ## 3. 工作流程 ```mermaid sequenceDiagram participant U as 用户 participant O as Obsidian participant C as Claudian participant S as Claude SDK participant A as Claude API U->>O: 打开聊天/选择文本 O->>C: 激活 Claudian C->>C: 收集上下文（笔记、文件、选择） C->>S: 发送消息和工具调用 S->>A: 请求 Claude A-->>S: 返回响应和工具结果 S-->>C: 处理后的响应 C->>O: 更新 UI C->>C: 执行文件操作/Bash 命令 C-->>U: 显示结果 ```  # 四、功能特性 ## 1. 完整的代理能力 Claudian 利用 Claude Code 的能力，在 Obsidian 笔记库中实现： ### A. 文件操作 - 读取笔记内容 - 写入和编辑文件 - 搜索文件和内容 - 多步骤工作流自动化 ### B. Bash 命令执行 - 直接在笔记库中执行终端命令 - 支持脚本自动化 - 可配置命令阻止列表确保安全 ### C. 上下文感知 - 自动附加当前聚焦的笔记 - 使用 `@` 提及其他文件 - 按标签排除笔记 - 包含编辑器选择内容（高亮） - 访问外部目录获取额外上下文 ## 2. 视觉识别支持 通过以下方式发送图像进行分析： - 拖放图片到聊天界面 - 粘贴图片 - 输入文件路径 ## 3. 内联编辑模式 ### A. 功能说明 - 选择文本 + 快捷键触发内联编辑 - 直接在笔记中编辑选中的文本 - 在光标位置插入内容 - 提供单词级差异预览 - 只读工具访问以获取上下文 ### B. 使用场景 - 快速修改段落内容 - AI 辅助润色文本 - 代码片段优化 ## 4. 指令模式（#） ### A. 功能说明 - 从聊天输入直接添加精细的自定义指令到系统提示词 - 在模态框中查看和编辑指令 - 指令会附加到默认系统提示词 ### B. 使用方法 在聊天输入中输入 `#` 即可进入指令模式，添加自定义指令。 ## 5. 斜杠命令 ### A. 创建命令 - 在设置中创建可重用的提示词模板 - 通过 `/command` 触发 - 支持参数占位符 - 支持 `@file` 引用 - 可选的内联 bash 替换 ### B. 管理命令 - 在设置中导入/导出命令 - 可覆盖模型和允许的工具 ## 6. 技能系统 ### A. 技能格式 - 兼容 Claude Code 的技能格式 - 添加 `SKILL.md` 文件到 `~/.claude/skills/` 或 `{vault}/.claude/skills/` - 推荐使用 Claude Code 管理技能 ### B. 自动调用 - 基于上下文自动调用相关技能 - 扩展 Claudian 的能力 ## 7. Claude Code 插件支持 ### A. 插件发现 - 自动从 `~/.claude/plugins` 发现 - 支持每个笔记库的独立配置 - 用户范围的插件在所有笔记库中可用 - 项目范围的插件仅在匹配的笔记库中可用 ### B. 插件管理 - 通过设置启用/禁用插件 - 插件技能和斜杠命令无缝集成 - 推荐使用 Claude Code 管理插件 ## 8. MCP 支持 ### A. 服务器配置 - 在设置中添加 MCP 服务器 - 支持 stdio、SSE、HTTP 三种模式 - 配置上下文保存模式 - 使用 `@mcp-server` 在聊天中激活 ### B. @-提及下拉菜单 输入 `@` 可查看： - 活动的 MCP 服务器 - 外部上下文 - 笔记库文件 ## 9. 高级模型控制 ### A. 模型选择 - 在 Haiku、Sonnet 和 Opus 之间选择 - 通过环境变量配置自定义模型 - 微调思考预算 ### B. 环境变量 - 在设置中配置自定义环境变量 - 支持环境变量片段保存和恢复 ## 10. 安全特性 ### A. 权限模式 - YOLO 模式：无批准提示，所有工具调用自动执行 - Safe 模式：每次工具调用需要批准，Bash 需要精确匹配，文件工具允许前缀匹配 ### B. 安全措施 - 命令阻止列表（支持正则，平台特定） - 笔记库限制（通过 realpath 符号链接安全检查） - 允许的导出路径（默认：`~/Desktop`、`~/Downloads`） ## 11. 多标签页支持 ### A. 功能特性 - 运行多个并发聊天会话 - 独立的流式响应 - 延迟服务初始化 - 可配置的标签页限制（3-10 个） ### B. 性能优化 - 延迟初始化减少资源占用 - 独立会话管理 # 五、配置详解 ## 1. 基本设置 ### A. 用户名 为个性化问候设置用户名称。 ### B. 排除标签 防止笔记自动加载的标签（如 `sensitive`、`private`）。 ### C. 媒体文件夹 配置笔记库存储附件的位置，用于嵌入式图像支持（如 `attachments`）。 ### D. 自定义系统提示词 附加到默认系统提示词的额外指令（指令模式 `#` 保存此处）。 ### E. 自动生成对话标题 在首次交换后切换 AI 驱动的标题生成。 ### F. 标题生成模型 用于自动生成对话标题的模型（默认：Auto/Haiku）。 ### G. Vim 风格导航映射 配置按键绑定，如 `map w scrollUp`、`map s scrollDown`、`map i focusInput`。 ## 2. 快捷键设置 ### A. 内联编辑快捷键 触发选定文本内联编辑的快捷键。 ### B. 打开聊天快捷键 打开聊天侧边栏的快捷键。 ## 3. MCP 服务器配置 ### A. 添加/编辑/删除服务器 - 配置 MCP 服务器连接参数 - 设置上下文保存模式 - 验证服务器连接 ### B. 服务器类型 - stdio：标准输入输出模式 - SSE：服务器发送事件模式 - HTTP：HTTP 请求模式 ## 4. Claude Code 插件管理 ### A. 插件发现 - 自动扫描 `~/.claude/plugins` 目录 - 显示可用的 Claude Code 插件 ### B. 插件启用/禁用 - 用户范围插件：所有笔记库可用 - 项目范围插件：仅在匹配的笔记库中可用 ## 5. 安全设置 ### A. 加载用户 Claude 设置 加载 `~/.claude/settings.json`（用户的 Claude Code 权限规则可能绕过 Safe 模式）。 ### B. 启用命令阻止列表 阻止危险的 bash 命令（默认：开启）。 ### C. 阻止的命令 阻止的命令模式（支持正则，平台特定）。 ### D. 允许的导出路径 笔记库外部可以导出文件的路径（默认：`~/Desktop`、`~/Downloads`）。支持 `~`、`$VAR`、`${VAR}` 和 `%VAR%`（Windows）。 ## 6. 环境变量设置 ### A. 自定义变量 Claude SDK 的环境变量（KEY=VALUE 格式）。 ### B. 环境变量片段 保存和恢复环境变量配置。 ## 7. 高级设置 ### A. Claude CLI 路径 Claude Code CLI 的自定义路径（留空以自动检测）。 # 六、安全与权限 ## 1. 访问范围 | 范围 | 访问权限 | |------|---------| | 笔记库 | 完整读写（通过 realpath 符号链接安全） | | 导出路径 | 仅写入（如 `~/Desktop`、`~/Downloads`） | | 外部上下文 | 完整读写（仅会话，通过文件夹图标添加） | ## 2. 权限模式 ### A. YOLO 模式 - 无批准提示 - 所有工具调用自动执行（默认） ### B. Safe 模式 - 每次工具调用需要批准 - Bash 命令需要精确匹配 - 文件工具允许前缀匹配 ## 3. 隐私与数据使用 ### A. 发送到 API 的内容 - 用户输入 - 附加的文件 - 图像 - 工具调用输出 - 默认发送到 Anthropic，通过 `ANTHROPIC_BASE_URL` 自定义端点 ### B. 本地存储 - 设置和会话元数据存储在 `vault/.claude/` - 会话消息存储在 `~/.claude/projects/`（SDK 原生） - 旧版会话存储在 `vault/.claude/sessions/` ### C. 遥测 - 无遥测功能 - 仅跟踪用户配置的 API 提供商 # 七、故障排查 ## 1. Claude CLI 未找到 ### A. 问题现象 遇到 `spawn claude ENOENT` 或 `Claude CLI not found` 错误。 ### B. 原因分析 插件无法自动检测 Claude 安装路径，常见于 Node 版本管理器（nvm、fnm、volta）。 ### C. 解决方案 **步骤 1**：找到 CLI 路径并在设置 → 高级 → Claude CLI 路径中设置。 | 平台 | 命令 | 示例路径 | |------|------|---------| | macOS/Linux | `which claude` | `/Users/you/.volta/bin/claude` | | Windows（原生） | `where.exe claude` | `C:\Users\you\AppData\Local\Claude\claude.exe` | | Windows（npm） | `npm root -g` | `{root}\@anthropic-ai\claude-code\cli.js` | **注意**：在 Windows 上，避免使用 `.cmd` 包装器。使用 `claude.exe` 或 `cli.js`。 **替代方案**：在设置 → 环境 → 自定义变量中，将 Node.js bin 目录添加到 PATH。 ## 2. npm CLI 和 Node.js 不在同一目录 ### A. 问题检查 如果使用 npm 安装的 CLI，检查 `claude` 和 `node` 是否在同一目录： ``` dirname $(which claude) dirname $(which node) ``` ### B. 问题分析 如果不同，GUI 应用如 Obsidian 可能找不到 Node.js。 ### C. 解决方案 **方案 1**：安装原生二进制文件（推荐） **方案 2**：在设置 → 环境中添加 Node.js 路径：`PATH=/path/to/node/bin` ## 3. 仍有问题 如果上述方法都无法解决问题，请在 GitHub 上提交 issue，包含以下信息： - 平台 - CLI 路径 - 错误消息 # 八、项目架构 ## 1. 目录结构 ``` src/ ├── main.ts # 插件入口点 ├── core/ # 核心基础设施 │ ├── agent/ # Claude Agent SDK 包装器（ClaudianService） │ ├── commands/ # 斜杠命令管理（SlashCommandManager） │ ├── hooks/ # PreToolUse/PostToolUse 钩子 │ ├── images/ # 图像缓存和加载 │ ├── mcp/ # MCP 服务器配置、服务和测试 │ ├── plugins/ # Claude Code 插件发现和管理 │ ├── prompts/ # 代理的系统提示词 │ ├── sdk/ # SDK 消息转换 │ ├── security/ # 批准、阻止列表、路径验证 │ ├── storage/ # 分布式存储系统 │ ├── tools/ # 工具常量和实用程序 │ └── types/ # 类型定义 ├── features/ # 功能模块 │ ├── chat/ # 主聊天视图 + UI、渲染、控制器、标签页 │ ├── inline-edit/ # 内联编辑服务 + UI │ └── settings/ # 设置标签页 UI ├── shared/ # 共享 UI 组件和模态框 │ ├── components/ # 输入工具栏组件、下拉菜单、选择高亮 │ ├── mention/ # @-提及下拉菜单控制器 │ ├── modals/ # 批准 + 指令模态框 │ └── icons.ts # 共享 SVG 图标 ├── i18n/ # 国际化（10 种语言环境） ├── utils/ # 模块化实用函数 └── style/ # 模块化 CSS（→ styles.css） ``` ## 2. 核心模块说明 ### A. Core 层 - **agent**：Claude Agent SDK 的核心包装器，负责与 Claude API 通信 - **commands**：斜杠命令的管理和执行 - **mcp**：MCP 服务器的配置、连接和管理 - **plugins**：Claude Code 插件的发现和集成 - **security**：权限控制和安全策略 ### B. Features 层 - **chat**：主聊天界面，包括消息渲染、会话管理、多标签页支持 - **inline-edit**：内联编辑功能，直接在笔记中编辑文本 - **settings**：插件设置界面 ### C. Shared 层 - **components**：可复用的 UI 组件 - **mention**：@-提及功能的下拉菜单 - **modals**：各种模态框（批准、指令编辑等） # 九、使用场景 ## 1. 笔记整理与优化 - AI 辅助整理笔记结构 - 自动生成摘要和标签 - 内容润色和改写 ## 2. 代码开发 - 在笔记中直接编写和测试代码 - 代码审查和优化建议 - 自动化脚本执行 ## 3. 知识管理 - 智能搜索笔记库 - 关联笔记推荐 - 知识图谱构建 ## 4. 自动化工作流 - 批量处理笔记 - 自动生成报告 - 定时任务执行 # 十、路线图 ## 1. 已完成功能 - Claude Code 插件支持 - 钩子和其他高级功能 - MCP 服务器集成 - 多标签页支持 - 视觉识别 ## 2. 计划中功能 - 更多集成选项 - 性能优化 - 用户体验改进 # 十一、许可证 Claudian 采用 MIT 许可证开源。 # 十二、致谢 - Obsidian 团队提供插件 API - Anthropic 提供 Claude 和 Claude Agent SDK *** ## 参考资料 1. [Claudian GitHub Repository](https://github.com/YishenTu/claudian) 最后修改：2026 年 01 月 15 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏