# Obsidian Aider
与笔记深度共生的 Obsidian 专属沉浸式 AI 助手，边读边写，伴随你的思考与知识创作。
English | 简体中文
---
## 💡 项目定位与适用人群
**Obsidian Aider** 是一款深度嵌入 Obsidian 笔记工作流的无干扰、原生级 AI 知识伴侣。它专注于文字阅读、文献理解、思维发散与内容创作，帮助你在不离开个人笔记界面的前提下，与自己的知识库和前沿大模型展开自然高效的对话。
### 满足的需求与解决的痛点
- **与知识库深度融合，告别割裂的频繁切换**：无需在网页端 AI 与 Obsidian 笔记窗口之间繁琐地来回复制粘贴。Aider 在侧边栏随时感知当前编辑内容，输入 `@` 即可随时调取库内笔记或文件夹作为参考资料，实现真正的沉浸式伴随阅读与写作；
- **纯粹清爽的创作界面，专注文字与思考**：去除了杂乱冗余的配置门槛与复杂的界面干扰，呈现优雅的短信式气泡对话与推理思考折叠，把完整的屏幕空间与注意力完完全全留给文字和灵感；
- **智能控流与省流，免费模型更耐用稳定**：针对普通用户常用的免费与轻量级 API 额度，内置智能请求控流、Token 消耗深度优化与自动避让防限流机制，有效避免频繁触发 429 报错，让低成本和免费额度也能持久稳定陪伴创作；
- **开箱即用，全平台随时随地可用**：无需安装或配置任何额外的编程语言环境，电脑端与手机平板移动端全平台支持，随身携带的笔记库在移动设备上也能随时唤起 AI 助手。
### 适合人群
- 📚 **科研人员与学者**：快速梳理长篇论文、检索学术文献、跨笔记交叉比对论据观点；
- ✍️ **知识博主与写作者**：在侧边栏构思文章大纲、推敲段落措辞、润色文字表达、突破写作瓶颈；
- 🎒 **学生与自学者**：将个人笔记库转化为随时提问的专属智能导师，检索核心概念并提炼考点总结；
- 💡 **PKM 个人知识管理爱好者**：追求安静、克制、原生般流畅交互的 Obsidian 长期使用者。
---
## ⚖️ 核心特性速览
### 1. 沉浸自然的对话与创作交互
- **优雅视觉融合**：短信式对话气泡原生自适应 Obsidian 官方深浅色及各类社区主题（如 Minimal）；
- **推理过程优雅折叠**：支持思考推理型模型（如 DeepSeek-R1 等）的思考流折叠呈现，保持主界面清爽规整；
- **历史对话原位修改**：支持对历史提问直接就地修改并重新生成，便于多轮思路探索与持续迭代。
### 2. 知识库边读边聊 (`@` 联动)
- **精准引用笔记上下文**：在输入框键入 `@` 即可模糊搜索并嵌入单篇笔记或整个目录；
- **当前文档主动感知**：自动感知当前激活编辑窗口的笔记，一键实现文档概括、观点提炼与交叉问答。
### 3. 本地向量知识库深度检索 (RAG)
- **智能语义切分**：按 Markdown 标题层级与自然段落智能分块，保留笔记上下文完整连贯性；
- **全知识库智能问答**：对话框下方一键点击「全知识库对话」，初次使用提供交互式就地向导，自动配置向量索引并无缝开启问答；
- **二次重排序模型 (Rerank)**：支持接入 Bge-Reranker 等专用重排模型，对初筛候选切片进行深度交叉打分，大幅提升问答精准度；
- **纯净引用溯源**：AI 回复前清晰展示引用文档来源及行号区间，点击即可直达对应笔记原始位置；
- **安全黑白名单过滤**：支持指定包含（白名单）或排除（黑名单）目录，系统目录（`.obsidian`、`.git`、`.trash` 等）底层强制排除，杜绝无效扫描。
### 4. 经济省流与智能防限流机制
- **🌱 Eco 轻量模式**：智能优化对话上下文构建，显著降低 Token 消耗（相比常规请求节省高达 75%）；
- **智能退避与静默重试**：遇到服务商限流（429）时自动计算最佳重试间隔，告别频繁手动刷新；
- **智能死循环熔断保护**：防止复杂多轮任务陷入无限反复调用，确保始终输出清晰总结。
### 5. 极致轻巧，全平台通用
- **超轻体积秒开**：最终打包体积仅约 **0.44 MB**，启动即开即用，对笔记库无任何性能负担；
- **全面跨平台**：完全遵循 Obsidian 官方沙箱规范，完美兼容 Windows、macOS、Linux 桌面端以及 iOS、Android 移动设备。
### 6. 开箱即用免配置内置工具
- **国内必应联网搜索**：免 API Key、免代理直连，即时检索互联网最新事实与资讯；
- **网页正文抓取提取**：粘贴任意网页 URL 链接，秒级转换为排版干净的 Markdown 文本；
- **全球实时天气预报**：基于全球开放气象源，即时查询各地实时天气与未来预报；
- **arXiv 学术论文检索**：直连全球开放文献库，快速检索计算机、人工智能等领域的学术论文与摘要；
- **系统精准时间感知**：毫秒级系统当前日期、星期与时区识别，确保时间感知准确无误。
---
## 🌐 开箱即用的多服务商生态
Obsidian Aider 具备灵活强大的模型服务商支持。插件**默认预置并启用了 4 家核心服务商**（填入对应 API Key 即可使用）：
- **OpenAI**
- **DeepSeek**
- **OpenRouter**
- **SiliconFlow (硅基流动)**
除上述 4 家默认启用的核心服务商外，您还可以根据需求在设置中一键添加并配置项目支持的任意服务商：
- **国际主流云端大模型**：Anthropic (Claude)、Google Gemini、xAI (Grok)、Mistral AI、Perplexity、Groq、Azure OpenAI
- **国内开放大模型平台**：ModelScope (魔搭社区)
- **本地离线私有大模型**：Ollama、LM Studio（无需联网，完全本地运算，保障数据隐私）
- **自定义与中转平台**：OpenAI Compatible（全面兼容任意符合 OpenAI API规范的自建模型、第三方中转及 OneAPI / NewAPI 服务）
- **网页订阅会话授权**：支持 Claude Plan、OpenAI Plan、Gemini Plan 原生会话凭证快速连接
---
## 🚀 快速上手与使用
### 1. 方式一：通过 Obsidian 官方社区插件市场安装（推荐）
本项目已通过官方审核并在 **Obsidian 官方社区插件市场（Community Plugins）** 正式上架发布：
1. 打开 Obsidian，进入 **设置 -> 第三方插件（Community plugins）**；
2. 确保“受限模式”已关闭，点击 **浏览（Browse）**；
3. 在搜索框中输入 **`Aider`**；
4. 找到 **Aider** 插件，点击 **安装（Install）**，安装完成后点击 **启用（Enable）**。
### 2. 方式二：手动离线安装
若因网络原因无法直接访问官方市场，您也可以手动离线安装：
1. 前往 [最新 Releases 页面](https://github.com/vimbackground/obsidian-aider/releases/latest) 下载 `main.js`、`manifest.json`、`styles.css` 三个文件；
3. 将它们放入笔记库目录 `<你的笔记库>/.obsidian/plugins/aider/`；
4. 打开 Obsidian，进入 **设置 -> 第三方插件**，点击已安装插件列表的刷新按钮并启用 **Aider**。
### 3. 开始使用
- **唤起对话**：点击 Obsidian 左侧边栏的图标（或通过快捷键 `Ctrl/Cmd + P` 搜索 `Open chat`）打开 Aider 侧边栏；
- **文章对话**：点击输入框底部的「文章对话」（或按 `Enter`），针对当前打开的笔记进行提问；
- **全知识库对话 (RAG)**：点击输入框底部的「全知识库对话」（或按 `Shift + Enter`），基于全库笔记向量索引进行深度问答。首次使用将弹出快速引导向导，助您一键配置嵌入模型并立即开始；
- **精准引用笔记**：在输入框键入 `@` 即可选择指定单篇笔记或文件夹作为参考资料；
- **配置服务商与模型**：进入 **设置 -> Aider**，填入服务商 API Key，即可在对话框底部随时切换对话模型、嵌入模型与重排模型。
---
## 🛠️ 开发者与技术操作指南
如果您是开发者，希望从源码进行编译调试或了解自动化构建流水线，请参阅专门的：
👉 **[开发者与技术操作指南 (docs/DEVELOPMENT.md)](docs/DEVELOPMENT.md)**
---
## 🙏 致谢
本项目在产品设计理念与早期底层架构上深受开源项目 [obsidian-smart-composer](https://github.com/glowingjade/obsidian-smart-composer) 的启发，在此对原作者 [glowingjade](https://github.com/glowingjade) 的无私开源贡献表达诚挚的感谢！
---
## 📄 开源许可证
本项目基于 [MIT 许可证](LICENSE) 开源。