ChatGPT MD

🚀 通过 Ollama/LM Studio 将 ChatGPT、OpenRouter.ai 和本地 LLM（大语言模型）无缝集成到 Obsidian 中。

🚀 新功能

v3.1.0：智能体（Agents）系统

创建可复用的 AI 角色，自定义系统提示（system prompt）、模型和温度（temperature）设置。

将智能体定义为带有 frontmatter（前置元数据）和系统提示正文的 Markdown 文件。通过 Choose Agent（选择智能体）命令将智能体应用到任意笔记，或使用 AI Wizard（AI 向导） 创建新智能体——只需描述你的需求，AI 就会为你生成名称、温度值和完整的系统提示。

v3.0.0：注重隐私的 AI 工具调用（默认关闭 - 设置 → ChatGPT MD → Tool Calling）

你的 AI 助手现在可以主动搜索你的知识库（vault）、读取文件并查询网络——采用“人在回路”（human-in-the-loop）架构，确保你始终掌控一切。

工具调用基于隐私优先原则构建。当 AI 需要信息时，会请求使用工具的权限——你批准执行、审查结果，并精确控制哪些内容返回给模型。未经明确同意，任何数据都不会离开你的知识库。

快速入门 🏁

只需几个简单步骤即可开始：

1. 安装 ChatGPT MD：进入 设置 > 社区插件 > 浏览，搜索 ChatGPT MD 并点击 安装。
2. 添加你的 OpenAI API 密钥：在插件设置中添加 OpenAI API 密钥，或安装 Ollama 并选择你喜欢的本地 LLM。
3. 开始聊天：使用 ChatGPT MD: Chat 命令（cmd + p 或 ctrl + p）从任意笔记启动对话。

💡 专业提示：设置快捷键以获得最佳体验！进入 设置 > 快捷键，搜索 ChatGPT MD: Chat 并添加你喜欢的快捷键（例如 cmd + j）。

先开始聊天吧，不必过于担心高级功能，它们会自然而然地掌握 :-)

本地 LLM 设置（Ollama & LM Studio）🏠

想保持对话私密并避免 API 费用？使用 ChatGPT MD 搭配本地 LLM！

Ollama 设置

1. 安装 Ollama：从 ollama.ai 下载并在你的系统上安装
2. 下载模型：在终端运行：

   ollama pull llama3.2    # 或任意你选择的模型
   ollama pull qwen2.5     # 另一个流行选项
   

3. 配置 ChatGPT MD：
   • 进入 设置 > ChatGPT MD > Ollama 默认设置
   • Ollama URL 应已自动设为 http://localhost:11434
   • 在设置中指定默认模型（例如 ollama@llama3.2）
4. 开始聊天：使用 ChatGPT MD: Chat 命令与配置的默认模型对话，或在单个笔记中覆盖设置：

   ---
   model: ollama@llama3.2  # 如需覆盖默认值
   temperature: 0.7
   ---
   

LM Studio 设置

1. 安装 LM Studio：从 lmstudio.ai 下载
2. 在 LM Studio 中下载并加载模型
3. 启动服务器：在 LM Studio 中进入 Local Server 并启动
4. 配置 ChatGPT MD：
   • 进入 设置 > ChatGPT MD > LM Studio 默认设置
   • LM Studio URL 应设为 http://localhost:1234
   • 在设置中指定默认模型（例如 lmstudio@your-model-name）
5. 开始聊天：使用 ChatGPT MD: Chat 命令与配置的默认模型对话，或在单个笔记中覆盖设置：

   ---
   model: lmstudio@your-model-name  # 如需覆盖默认值
   temperature: 0.7
   ---
   

查找你的模型名称

• Ollama：在终端运行 ollama list 查看已安装的模型
• LM Studio：在 LM Studio 界面中查看已加载模型的名称

本地 LLM 重要说明

• 默认模型配置：在设置中将你偏好的本地模型设为默认值——其使用方式与云服务完全相同
• 按笔记覆盖：可通过 frontmatter 在单个笔记中覆盖默认模型，与其他提供商一致
• 模型发现：使用 ollama list（Ollama）或检查 LM Studio 界面，找到可用于配置的可用模型名称

功能

• 交互式对话：
  • 从任意 Markdown 笔记直接与 ChatGPT、OpenRouter.ai 模型和 Ollama 互动，实时编辑问题或回复，并无缝继续对话。
• 隐私保护 & 零 API 费用：
  • 通过 Ollama 使用本地 LLM，将聊天保留在本地计算机，避免 API 费用。
• 支持联网的模型：
  • 通过 OpenAI 的 gpt-4o-search-preview 和 Perplexity 的 openrouter@perplexity/llama-3.1-sonar-small-128k-online（通过 openrouter.ai）获取实时网络信息。
• 多 AI 提供商支持：
  • 可选择 OpenAI、OpenRouter.ai（提供 Gemini、Claude、DeepSeek、Llama、Perplexity 等模型）或通过 Ollama 使用本地模型。
• 系统指令（System Commands）：
  • 通过系统指令指导 LLM，获得最佳回答。
• 链接上下文（Link context）：
  • 在对话中提供指向知识库中任意其他笔记的链接（Markdown 或 Wiki 链接），以增强上下文。
• 按笔记配置（Per-note Configuration）：
  • 通过 frontmatter 覆盖默认设置，使用来自 OpenAI API、OpenRouter.ai 或 Ollama API 的参数。
• Markdown 支持：
  • 完整渲染所有回复中的列表、代码块等内容。
• 极简设置：
  • 使用你的 OpenAI API 密钥、OpenRouter.ai API 密钥，或通过 Ollama 在本地安装任意 LLM。
• 注释块（Comment Blocks）：
  • 使用注释块忽略笔记中的部分内容。
• 聊天模板（Chat Templates）：
  • 为重复场景使用和共享 frontmatter 模板。探索 chatgpt-md-templates。

隐私与安全

ChatGPT MD

• 仅将数据本地存储在你的知识库中，无任何追踪，除直接调用 AI API（OpenAI、OpenRouter.ai）外无第三方集成。
• 允许你使用 Ollama（本地 LLM 安装）进行离线的对话式知识探索。

默认配置

该插件预置了均衡的默认配置，让你立即开始使用。
你可以更改全局设置，或通过 frontmatter 在任意笔记中使用本地参数
（在笔记第一行输入 --- 即可添加属性）

---
system_commands: ['You are a helpful assistant.']
temperature: 0.3
top_p: 1
max_tokens: 300
presence_penalty: 0.5
frequency_penalty: 0.5
stream: true
stop: null
n: 1
model: gpt-5-mini

# 服务特定 URL（可选，未指定时将使用全局设置）
openaiUrl: https://api.openai.com
# openrouterUrl: https://openrouter.ai

ollamaUrl: http://localhost:11434

---

💡 小贴士：对于推理、编程或文本生成等更复杂的任务，可将 `max_tokens` 增加至更高值（例如 `4096`）。
默认模型 `gpt-5-mini` 针对速度和效率进行了优化。如需更强的推理能力，请升级到 `gpt-5`；若需超轻量级响应，可使用 `gpt-5-nano`。

### 工具

1. **安装**：通过 Obsidian 更新或安装 v3.0.0 或更高版本  
2. **配置**：设置 → ChatGPT MD → 工具调用（Tool Calling）→ 启用  
3. **可选**：添加 [Brave Search API 密钥](https://brave.com/search/api/)（免费额度：每月 1,000 次查询）  
4. **聊天**：使用 `ChatGPT MD: Chat` 命令。AI 在需要时会请求使用工具。

本实现采用三层审批模式：

1. **执行层（Execution Layer）**：AI 请求使用工具并附带参数  
2. **处理层（Processing Layer）**：工具通过 Obsidian 的 API 在你的知识库（vault）中本地执行（支持文件名和内容的全文搜索）  
3. **审批层（Approval Layer）**：交互式弹窗允许你在结果返回给 AI 前进行筛选

### 可用工具

**知识库搜索（Vault Search）** (`vault_search`)  
- 多词 OR 搜索：在你的知识库中匹配任意查询词  
- 同时搜索文件名和文件内容  
- 排除当前文件以防止递归  
- 可配置结果数量上限（默认：5 个文件）  
- 支持查询编辑：执行前可调整搜索词

**文件读取（File Read）** (`file_read`)  
- 当 AI 知道具体文件路径时，可直接访问文件  
- 支持批量读取多个文件  
- 经你批准后提取完整内容  
- 适用于发现文件后的定向查询

**网络搜索（Web Search）** (`web_search`)  
- 基于 Brave Search API（注重隐私，每月免费 1,000 次查询）  
- 支持自定义搜索提供者（用于自托管端点）  
- 可选完整网页内容抓取  
- 自动验证 API 密钥——仅在配置后显示该工具  
- 支持查询编辑：执行前可修改网络搜索查询

### 隐私与安全

- **本地优先执行（Local-First Execution）**：所有知识库操作完全在 Obsidian 的 API 内运行  
- **选择性共享（Selective Sharing）**：多选弹窗让你精确控制要共享的结果  
- **无遥测（No Telemetry）**：零追踪或分析——工具使用保持私密

### 配置

在 **设置 → ChatGPT MD → 工具调用** 中启用工具调用：

- **启用工具调用（Enable Tool Calling）**：总开关（默认：禁用）  
- **Brave Search API 密钥（Brave Search API Key）**：你的 Brave Search API 密钥  
- **自定义提供者 URL（Custom Provider URL）**：自托管搜索端点  
- **最大网络结果数（Max Web Results）**：返回的网络结果数量（1–10）

### 使用场景

**研究助手**： “在我的知识库中搜索关于量子计算算法的笔记，以及该主题的最新论文”

→ AI 发现相关笔记 → 你批准要共享的文件 → AI 整合并引用信息

**知识整合**： “找出我所有第三季度的会议笔记，并总结关于产品路线图的关键决策”

→ 知识库搜索返回会议文件 → 你选择相关文件 → AI 提取并总结决策

**增强型写作**： “在网上搜索最新的气候变化统计数据，并将其整合到我的文章中”

→ 网络搜索获取最新数据 → 你筛选可靠来源 → AI 将引用整合进草稿

**交叉引用发现**： “找出同时提到机器学习和效率技巧的笔记”

→ 多词 OR 搜索发现交集 → 你批准有趣的关联 → AI 突出你可能忽略的模式

⚠️ **注意**：工具支持取决于模型能力。旧版模型可能不支持函数调用。启用工具支持后，可在工具选择列表中查看各模型的工具能力。


### 多模型聊天（Multi Model Chats）
你可以在笔记中为每次请求设置和更改模型。  
通过 frontmatter 指定 `model` 属性：

对于 OpenAI 模型（包括最新的 GPT-5 系列）：

---

model: gpt-5 # 或 gpt-5-mini, gpt-5-nano, gpt-5-chat-latest system_commands: [act as a senior javascript developer]

Ollama 模型前加 `ollama@` 前缀，LM Studio 模型前加 `lmstudio@` 前缀：

---

model: ollama@gemma2:27b temperature: 1

AI 回复将在回复标题中保留所用模型名称，便于日后参考。  
你可以通过终端命令 `ollama list` 查看已安装的 Ollama 模型名称，或在 [OpenAI 模型页面](https://platform.openai.com/docs/models) 查看可用的 OpenAI 模型列表。

### 服务 URL
每个 AI 服务都有其专用的 URL 参数，可在设置中全局配置，或通过 frontmatter 在单个笔记中配置：

---

对于 OpenAI

openaiUrl: https://api.openai.com

对于 OpenRouter

openrouterUrl: https://openrouter.ai

对于 Ollama

ollamaUrl: http://localhost:11434

默认 URL 如下：
- OpenAI: `https://api.openai.com`  
- OpenRouter: `https://openrouter.ai`  
- Ollama: `http://localhost:11434`

注意：旧版本使用单一的 `url` 参数，现已弃用。请更新你的模板和笔记，改用服务专用的 URL 参数。

### 命令 👨‍💻
通过 Obsidian 的命令面板（`cmd + p` 或 `ctrl + p`）运行命令，输入 `chatgpt`，或设置快捷键  
（强烈建议为聊天命令设置快捷键（我个人使用 `cmd + j`，效果极佳，因为食指本来就放在该键上））。

#### 主要命令
- **Chat**：解析文件并与 ChatGPT 交互。建议分配快捷键，例如 `cmd + j`。

#### 创建命令
- **New Chat with Highlighted Text**：使用高亮文本和 `Chat Folder` 中的默认 frontmatter 启动聊天。  
- **New Chat From Template**：从 `Chat Template Folder` 中的模板创建聊天。

#### 实用命令
- **Infer Title**：根据笔记内容自动生成标题。可配置为在 4 条以上消息后自动运行。  
- **Add Comment Block**：插入注释块，标记笔记中应被忽略的部分。  
- **Select Model**：从所有可用的大语言模型（LLM）（OpenAI、OpenRouter.ai、Ollama）中选择，并为当前笔记设置模型。

#### 维护命令
- **Clear Chat**：清除所有消息，但保留 frontmatter。  
- **Stop Streaming (仅限桌面版)**：必要时停止正在进行的流式输出。

#### 格式化工具
- **Add Divider**：插入水平分隔线，以视觉方式组织内容。

## Beta 测试 🧪
想在功能正式发布前抢先体验最新特性吗？你可以使用社区插件 [BRAT (Beta Reviewer's Auto-update Tool)](https://github.com/TfTHacker/obsidian42-brat) 来参与 ChatGPT MD 的 Beta 测试：

1. 从 Obsidian 的社区插件（Community Plugins）中安装 BRAT 插件  
2. 打开 BRAT 设置，添加 `bramses/chatgpt-md` 作为 Beta 插件  
3. 在 BRAT 插件设置的下拉菜单中选择 "latest version"（最新版本）  
4. 在你的社区插件列表中启用 ChatGPT MD 插件  

这样你就能在新功能仍在开发和测试阶段时提前使用它们。

⚠️ **警告**：Beta 测试存在风险，需自行承担后果。请务必在全新的空库（vault）中测试 Beta 版本，切勿在主库中使用。Beta 功能可能出现故障，甚至导致数据丢失。

## 常见问题 ❓
#### 如何开始与 ChatGPT MD 聊天？
在任意笔记中，通过 Obsidian 命令面板（Command Palette，快捷键 `cmd + p` 或 `ctrl + p`）执行 `ChatGPT MD: Chat` 命令即可开始对话。

#### 我可以为 `ChatGPT MD: Chat` 命令设置快捷键吗？
当然可以！建议你这样做：进入 `设置 > 快捷键（Settings > Hotkeys）`，搜索 `ChatGPT MD: Chat`，然后绑定你喜欢的快捷键（例如 `cmd + j`）。

#### 如何使用聊天和推理模型？
你可以使用 OpenAI 的 GPT-3 和 GPT-4 模型，也可以通过 OpenRouter.ai 使用多种模型（如 Claude、Gemini、DeepSeek、Llama、Perplexity 等），或者使用通过 Ollama 安装的任意本地模型。  
通过 Ollama 本地运行的 DeepSeek-r1:7b 模型在推理任务上表现非常出色。

#### 如何使用自定义端点（custom endpoint）？
请确保你的自定义 API 符合 OpenAI 的规范，例如 Azure 托管的端点。关于 API 密钥管理的具体细节，请咨询你的服务提供商。

#### 我应该在哪里添加我的 OpenAI API 密钥？
在插件设置中添加你的 OpenAI API 密钥，或者安装 Ollama 并选择你喜欢的本地大语言模型（LLM）。

#### Frontmatter 中的 'url' 参数怎么了？
单一的 'url' 参数现已弃用。从 v2.2.0 版本开始，我们引入了针对不同服务的 URL 参数：`openaiUrl`、`openrouterUrl` 和 `ollamaUrl`。这使得配置不同服务时更加灵活清晰。请相应地更新你的模板和笔记。

🤖 尽情探索 ChatGPT MD 在你的 Obsidian 库中的强大功能吧！🚀

## 欢迎贡献 🤝

我们非常欢迎并鼓励任何形式的贡献，包括拉取请求（Pull Requests）、错误报告（bug reports）等！:octocat:

### 开发环境搭建

```bash
# 克隆仓库
git clone https://github.com/bramses/chatgpt-md.git
cd chatgpt-md

# 安装依赖
yarn install

# 开发模式（监听文件变化）
yarn dev

# 运行测试
yarn test

# 运行带覆盖率的测试
yarn test:coverage

# 代码检查
yarn lint
yarn lint:fix

# 生产构建
yarn build

测试

项目使用 Jest 进行测试，包含 104 个覆盖工具函数的测试用例。在提交 PR 前，请确保：

1. 运行 yarn test 确保所有测试通过
2. 运行 yarn lint 检查代码质量
3. 运行 yarn build 验证构建成功

代码质量标准

• 复杂度：函数应少于 50 行，圈复杂度（cyclomatic complexity）≤15
• 类型安全：尽量减少 any 的使用，优先使用显式类型
• 异步安全：所有 Promise 必须被正确处理（await、catch 或显式忽略）
• 测试：为 src/Utilities/*.test.ts 中新增的工具函数编写测试

提交前钩子（Pre-commit Hooks）

在执行 git commit 时会自动运行以下钩子：

• ESLint 自动修复代码风格问题
• Prettier 格式化代码
• 仅检查已暂存（staged）的文件

CI/CD

GitHub Actions 会在每次拉取请求（Pull Request）时自动运行以下检查：

• 代码风格检查（Lint）
• TypeScript 类型检查
• 测试套件及覆盖率
• 生产环境构建

项目结构

src/
├── Commands/           # Obsidian 命令处理器
├── Services/           # 业务逻辑与 AI 适配器
├── Views/              # UI 组件与模态框
├── Utilities/          # 纯工具函数（经过充分测试）
├── Models/             # TypeScript 接口
├── Types/              # 类型定义
└── core/               # 依赖注入容器

更多开发文档详见 CLAUDE.md 和 docs/development.md。

提交更改

1. Fork 本仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行修改（包括测试、代码检查和文档）
4. 提交更改（git commit -m 'Add amazing feature'）
5. 推送到分支（git push origin feature/amazing-feature）
6. 发起 Pull Request

你的 PR 将由 CI 自动检查。请确保所有检查通过后再请求审核！

关于开发者 ✍️

Bram 于 2023 年 3 月创建了 ChatGPT MD，现居纽约，正在开发 Your Commonbase（一个零压力存储、搜索和分享的自组织剪贴簿）。他的个人网站和通讯位于 bramadams.dev。

Deniz 于 2024 年加入 Bram 继续开发工作。他在德国一家游戏公司工作，并在工作和生活中大量使用 AI。欢迎在 Bluesky 上向他打招呼：Deniz

祝你使用 ChatGPT MD 写作愉快！💻 🎉

ChatGPT MD 快速上手指南

环境准备

• 操作系统：Windows / macOS / Linux（需支持 Obsidian）
• 依赖软件：
  • Obsidian（最新版）
  • （可选）Ollama（用于本地大模型，国内用户可使用清华镜像加速下载）
  • （可选）LM Studio
  • （可选）OpenAI 或 OpenRouter API Key（如需使用云端模型）

💡 国内建议：
安装 Ollama 时，可配置国内镜像加速模型下载（如 OLLAMA_MODELS=你的模型名 OLLAMA_HOST=0.0.0.0:11434 配合代理或镜像源），但核心服务仍需联网。

安装步骤

1. 打开 Obsidian，进入 设置 > 社区插件 > 浏览
2. 搜索 ChatGPT MD，点击 安装
3. 启用插件后，进入 设置 > ChatGPT MD 配置 API 或本地模型：
   • 使用 OpenAI：填入你的 OpenAI API Key
   • 使用 Ollama：

     # 安装 Ollama 后，在终端拉取模型（示例）
     ollama pull llama3.2
     ollama pull qwen2.5
     

     然后在插件设置中指定默认模型为 ollama@llama3.2
   • 使用 LM Studio：启动其本地服务器（默认 http://localhost:1234），并在插件中配置对应模型名（格式：lmstudio@your-model-name）

基本使用

1. 在任意笔记中按下 Ctrl + P（Windows/Linux）或 Cmd + P（macOS）
2. 输入并选择命令：ChatGPT MD: Chat
3. 开始对话！例如输入：

   请帮我总结这篇笔记的主要观点。
   

示例：使用本地模型（Ollama）

在笔记开头添加 frontmatter 覆盖默认设置：

---
model: ollama@qwen2.5
temperature: 0.7
---

然后通过 ChatGPT MD: Chat 发起对话，即可使用 Qwen2.5 本地模型，无需联网、无 API 费用。

🔥 提示：建议为 ChatGPT MD: Chat 设置快捷键（如 Cmd + J），大幅提升使用效率。