本指南将帮助你搭建一个完全本地运行、隐私安全的个人 AI 知识库。
所有数据存储在你的电脑上，无需互联网连接，永久免费。

=====================================================================
一、核心工具简介
=====================================================================

1. Ollama – 本地大模型运行工具，提供 API 服务。
2. Obsidian – 本地笔记软件，支持双向链接和插件扩展。
3. Agent Client – Obsidian 插件，通过 ACP 协议连接 AI 代理。
4. OpenCode – 开源的 AI 编程助手，作为 Agent Client 的后端，可调用 Ollama。

工作流程：
Obsidian (Agent Client) <--> OpenCode (ACP 模式) <--> Ollama (模型服务)

=====================================================================
二、环境准备
=====================================================================

1. 安装 Ollama

2. 安装 Obsidian

   • 访问 https://obsidian.md/download
   • 下载安装并打开，创建一个新的知识库文件夹（Vault）。

=====================================================================
三、下载并配置 Ollama 模型
=====================================================================

1. 拉取所需模型（至少需要对话模型 + 嵌入模型）：

   ollama pull qwen2.5:7b # 对话模型（中文推荐，约 4.7GB）

   ollama pull llama3.2 # 或者轻量版（约 2GB，英文强）

   ollama pull nomic-embed-text # 嵌入模型（语义搜索，约 274MB）

2. 验证模型已下载：
   ollama list

3. 测试对话模型是否工作：
   ollama run qwen2.5:7b "你好，请介绍一下你自己"

4. 保持 Ollama 服务在后台运行（通常安装后会自动运行）：
   如果未自动运行，执行：ollama serve

=======================================================================

四、安装并配置 OpenCode（ACP 代理）

OpenCode 作为 Agent Client 的“翻译器”，让 Obsidian 能通过它调用 Ollama。

1. 全局安装 OpenCode：
   npm install -g opencode-ai

2. 验证安装：
   opencode --version

3. 配置 OpenCode 使用本地 Ollama 模型（以 qwen2.5:7b 为例）：
   opencode model add qwen2.5:7b --provider ollama

4. 测试 OpenCode 能否以 ACP 模式运行（会持续运行，按 Ctrl+C 停止）：
   opencode acp
   如果看到类似 "ACP server listening" 的提示，表示成功。

=====================================================================
五、安装并配置 Obsidian Agent Client 插件
=====================================================================

Agent Client 插件让 Obsidian 能与 OpenCode 通信。

1. 在 Obsidian 中启用第三方插件：

   • 打开 Obsidian 设置 → 第三方插件 → 关闭“安全模式”。

2. 安装 Agent Client：

   • 点击“浏览”，搜索 “Agent Client”。
   • 找到并安装，然后启用。

   （注意：如果社区插件库中没有，可通过 BRAT 安装：
   安装 BRAT 插件 → 添加 Beta 插件：RAIT-09/obsidian-agent-client）

3. 配置 Agent Client 连接 OpenCode：

   • 进入 Agent Client 插件设置。
   • 点击 “Add custom agent”。
   • 填写以下信息：

   ┌─────────────────────┬────────────────────────────────────────┐
   │ 字段 │ 值 │
   ├─────────────────────┼────────────────────────────────────────┤
   │ Agent ID │ opencode │
   │ Display name │ OpenCode (Ollama) │
   │ Path │ 填写 opencode 的路径 │
   │ │ macOS/Linux: which opencode │
   │ │ Windows: where opencode │
   │ │ 通常为 /usr/local/bin/opencode │
   │ Arguments │ acp │
   │ Environment variables│ 可留空，或设置： │
   │ │ OPENCODE_PROVIDER=ollama │
   │ │ OPENCODE_MODEL=qwen2.5:7b │
   └─────────────────────┴────────────────────────────────────────┘

   • 保存配置，确保该 Agent 处于启用状态。

4. 开放 Ollama 的 CORS 权限（允许 Obsidian 访问）：

   • 完全退出 Ollama（在活动监视器或任务管理器中结束进程）。
   • 重新启动 Ollama 并添加环境变量：

   macOS/Linux：
   OLLAMA_ORIGINS=app://obsidian.md* ollama serve

   Windows (PowerShell)：
   $env:OLLAMA_ORIGINS="app://obsidian.md*"; ollama serve

   建议将此命令保存为一个启动脚本，方便后续使用。

==============================================================================
六、测试与使用
==============================================================================

1. 在 Obsidian 中打开 Agent Client 聊天窗口：

   • 点击左侧边栏的机器人图标（或通过命令面板：Agent Client: New Chat）。

2. 选择你刚添加的 Agent（如 OpenCode (Ollama)）。

3. 发送一条消息，例如：
   “你好，请用中文介绍你自己。”

   如果收到回复，说明配置成功。

4. 启用知识库检索（RAG）：

   • 在聊天窗口底部，切换模式为 “Vault QA”。
   • 注意：此功能需要嵌入模型支持。
   • 如果使用 Agent Client 原生 RAG，需要额外配置嵌入模型。但 Agent Client 主要依赖 OpenCode 的能力，OpenCode 本身会调用嵌入模型进行语义搜索。

   更简单的方式是直接使用 Copilot 插件（替代方案），它原生支持嵌入模型和笔记索引。如果你希望更完整的 RAG 体验，建议安装 Copilot 插件并配置 nomic-embed-text。

=====================================================================
七、可选：安装 Copilot 插件（推荐，RAG 更强）
=====================================================================

Copilot 插件直接与 Ollama 通信，无需 OpenCode，配置更简单。

1. 在 Obsidian 中安装 Copilot 插件（社区插件市场搜索 “Copilot”）。

2. 在 Copilot 设置中：

   • Chat Model Defaults → Add Custom Model：
     Model Name: qwen2.5:7b
     Provider: Ollama
     Base URL: http://localhost:11434
   • QA Settings → Add Custom Model：
     Model Name: nomic-embed-text
     Provider: Ollama

3. 设置默认模型后，执行命令：
   Ctrl/Cmd + P → “Copilot: Force re-index vault for QA”

4. 之后即可在 Copilot 聊天窗口使用 “Vault QA” 模式，基于你的所有笔记问答。

=====================================================================
八、常见问题与故障排除
=====================================================================

问题 1：Agent Client 连接失败，提示 “Command not found”
解决：检查 Path 中填写的 opencode 路径是否正确。在终端输入 which opencode 获取绝对路径。

问题 2：CORS 错误（Cross-Origin Request Blocked）
解决：确保按照第五步第4条设置了 OLLAMA_ORIGINS 环境变量并重启 Ollama。

问题 3：Ollama 模型下载慢
解决：使用代理，或更换网络（如手机热点）。也可从 Hugging Face 手动下载后导入。

问题 4：内存不足
解决：使用更小的模型，如 llama3.2（2GB）或 qwen2.5:1.5b。
关闭其他占用内存的应用。

问题 5：OpenCode 无法识别 Ollama 模型
解决：确认 Ollama 服务正在运行：ollama list。
重新运行 opencode model add <模型名> --provider ollama。

问题 6：Windows 下 opencode 命令找不到
解决：确保 Node.js 安装时勾选了“添加到 PATH”。重启终端或电脑。

=====================================================================
九、进阶优化
=====================================================================

1. 使用多个对话模型：在 Ollama 中下载多个模型（如 qwen2.5:7b 和 deepseek-r1:7b），
   在 Copilot 或 Agent Client 中随时切换。

2. 提高检索质量：在 Copilot 设置中开启 “Reranking”，增大 “QA Context Length”。

3. 使用更好的嵌入模型：下载 bge-m3（多语言，长上下文）替换 nomic-embed-text。

4. 定时备份：定期将 Obsidian Vault 和 Ollama 模型文件夹备份到外部硬盘或云存储。

=====================================================================
十、总结
=====================================================================

你现在拥有一个完全本地、隐私安全的 AI 知识库：

• 所有笔记存储在本地（Obsidian Vault）
• 所有 AI 处理在本地（Ollama 模型）
• 无需网络连接，无 API 费用
• 通过 Agent Client 或 Copilot 获得智能问答、写作辅助、知识检索等功能