MCP Obsidian Local

🧠 本地黑曜石人工智能代理（基于技能）

这个项目实施了一个 自主本地 AI 代理 被设计成Obsidian内部的个人助理。与传统机器人不同，此代理使用基于 技能（Skills）它的灵感来自OpenClaw和Claude Code等现代框架。

该代理能够读取您的笔记，创建内容，深入搜索您的文件系统，并以本地和私密方式执行Obsidian命令。

______________________________________________________________________

🏗️ 系统架构

该架构分为两个主要组件，通过推理循环（ReAct）共同工作：

1. 代理核心（agent.py)

系统的“大脑”。它管理语言模型（LLM）和执行界面。

• LLM发动机： 使用 llama.cpp 以 GPU 加速运行 GGUF 模型。
• 程序化工具调用： 代理具有用Python编写的“原生”工具，可以通过结构化的JSON调用：

- list_skills列出可用的操作手册。 - load_skill: 为对话上下文加载特定技能的手册。 - execute_shell允许代理执行Bash命令（如 curl, grep, ls). - read_file: 直接从磁盘读取文件 。

• 上下文管理： 监控令牌使用情况并管理对话历史记录，以保持代理集中并在模型内存限制范围内。

2.技能体系(skills/)

这些功能在 Python 中不是“硬编码”。相反，它们在Markdown文件中定义（SKILL.md).

• 动态学习： 经纪人开始“干净”。当他发现一个问题时，他发现有一个技能（例如： obsidian阅读手册，立即学习如何使用CLI工具（如 curl Obsidian API）来解决请求。
• 灵活性： 添加新功能（例如与Git集成，Python REPL，Dataview）就像创建一个带有解释性Markdown文件的新文件夹一样简单。

______________________________________________________________________

🛠️ 工具如何工作

循环反应（Loop React）

1. 思考（``): 模型分析用户的请求，并决定需要什么工具或技能。
2. 工具调用``): 模板生成一个描述动作的JSON（例如：调用） execute_shell 用一个命令 curl).
3. 执行 ： O agent.py 拦截该JSON，在终端中执行Python代码或命令，并捕获结果（stdout/stderr）。
4. 注释 ： 结果作为新的上下文消息返回到模型。
5. 最终答案： 模型会处理结果并对用户做出响应，或者决定是否需要执行另一个步骤。

与Obsidian的整合

代理以两种冗余和强大的方式与Obsidian交互：

• API REST本地： 通过comandos curl 在技能中记录，代理与插件交谈 *黑名单本地REST API* 用于界面操作（打开笔记，运行应用程序命令）。
• 直接磁盘访问 ： 对于全文搜索，代理使用 Linux 原生工具，如 grep e ls 在变量定义的文件夹中 OBSIDIAN_VAULT_PATH这可以绕过第三方插件的限制或错误，并确保即时速度。

______________________________________________________________________

📋 安装和配置

1.先决条件

• 型号gguf： 指令模板（推荐：Qwen 2.5 7B 或 Llama 3.1 8B）。
• 黑曜石插件： 安装并激活插件 本地REST API 在你的Obsidian

2. 环境设置

创建文件 .env 工程根 ：

# Caminho para o modelo GGUF
MODEL_PATH=/caminho/para/seu/modelo.gguf

# Configurações do Obsidian
OBSIDIAN_API_TOKEN=seu_token_aqui
OBSIDIAN_VAULT_PATH=/home/usuario/Documents/Vault

3. 安装

make install

______________________________________________________________________

🚀 使用

使用命令启动代理 ：

make agent

您可以要求：

• *“我对X项目有什么看法？”* （他会找到并阅读笔记）。
• *“在我今天的待办事项列表中添加‘最终审查’步骤。* （他会找到你的每日笔记并使用 PATCH 编辑）。
• *“查找所有提到‘AI’的笔记，然后给我一个摘要。* （他将使用 grep 递归和处理文件）。

______________________________________________________________________

🛡️ 安全与隐私

• 100%本地： 没有什么从你的机器出来。人工智能处理和文件访问是在本地进行的。
• 透明度 ： 代理在终端上打印您正在运行的每个命令，允许您实时审核操作。