拓冰网站定制 
如果你是一个 Obsidian 重度用户每天在笔记的海洋里遨游那么最近一定被一个词刷屏了Agent。从 ChatGPT 到 Claude再到国内的 DeepSeek大模型的能力早已不限于聊天。但你是否想过让一个专属的 AI 助手直接“住”进你的 Obsidian 知识库不仅能回答你关于笔记的问题还能帮你整理、归纳、甚至基于你的知识库进行创作这听起来像是未来但 DeepSeek 推出的Harness框架正在让这个未来触手可及。它不是一个现成的 Obsidian 插件而是一个强大的AI Agent 开发框架。这意味着你可以用它来“组装”一个完全为你 Obsidian 工作流定制的智能体。很多人看到“Agent 开发框架”就望而却步以为需要高深的 AI 知识和复杂的工程能力。但 Harness 的核心设计理念恰恰相反它试图将构建 AI 应用的门槛从“算法工程”降低到“功能组装”。你不需要从头训练模型也不需要理解复杂的提示工程Prompt Engineering的所有细节你只需要清晰地定义“你想让 AI 帮你做什么”以及“它能调用哪些工具Tools”。本文将带你从零开始深入浅出地拆解如何利用 DeepSeek Harness 框架为你心爱的 Obsidian 打造一个专属的 AI Agent。我们将不止步于“是什么”而是聚焦于“为什么能”和“怎么做”。你会看到整个过程更像是在用乐高积木搭建一个智能工作台而非编写晦涩的代码。1. 这篇文章真正要解决的问题为什么是 Harness Obsidian在深入代码之前我们必须先回答一个根本问题市面上 AI 工具这么多为什么偏偏要选择 DeepSeek Harness 来开发 Obsidian Agent这背后是三个核心痛点的精准打击。痛点一数据孤岛与上下文割裂。你或许试过将 Obsidian 的笔记复制粘贴到 ChatGPT 的网页对话框里。一次两次尚可但如果想让 AI 深度理解你成百上千篇笔记之间的联系、你的知识体系脉络这种手动搬运的方式效率极低且无法形成持续的“记忆”。你的知识库是活的、不断增长的但传统的 AI 对话窗口是死的、一次性的。痛点二通用模型与专属知识的鸿沟。ChatGPT 很强大但它不了解“你”。它不知道你笔记里“那个重要的项目”具体指什么也不清楚你自创的标签体系“#PKM/核心”代表怎样的分类逻辑。一个理想的助手应该以你的个人知识库为“记忆体”和“事实依据”来回答问题而不是依赖它那可能已经过时或泛化的通用知识。痛点三开发门槛与灵活性的矛盾。你当然可以自己调用 OpenAI 或 DeepSeek 的 API写一个 Python 脚本去读取 Obsidian 的 Markdown 文件然后构建一个简单的问答系统。但这意味着你要处理文件 I/O、文本分割、向量化Embedding、检索Retrieval、对话历史管理等一系列问题。而 Harness 框架的价值在于它已经将这些底层能力模块化、标准化了。你需要关心的不再是“轮子怎么造”而是“这辆车要往哪里开以及配备什么功能”。因此Harness Obsidian 的组合瞄准的正是这样一个场景为每一位知识工作者提供一个以自己私有、动态增长的知识库为大脑的可高度定制化功能的数字助理。它不仅仅是“聊天机器人”更是能主动介入你工作流的智能体Agent。2. 核心概念拆解Agent、Skill、Harness 与 Obsidian Vault在动手之前我们需要统一语言。这几个概念是理解整个项目的基石。Agent智能体在 AI 语境下Agent 不是一个简单的聊天程序。它是一个能够感知环境你的输入、你的知识库、进行决策判断该调用哪个工具、执行动作读取文件、搜索、生成文本并达成目标的自治系统。我们最终要构建的就是一个专属于你 Obsidian 的 Agent。Skill技能这是 Harness 框架的核心抽象。一个 Skill 就是一个 Agent 能够执行的独立功能单元。你可以把它理解为 Agent 的“工具包”里的一个个工具。例如read_note技能根据笔记标题或路径读取笔记内容。search_vault技能在全库中基于语义或关键词搜索相关笔记。summarize技能总结一篇长笔记的核心观点。generate_outline技能基于某个主题利用现有笔记生成文章大纲。Harness 的强大之处在于它提供了一套标准方式来定义、实现和注册这些 Skill。Harness框架DeepSeek Harness 是一个用于构建、编排和管理 AI Agent 的开源框架。它负责处理所有繁琐的底层工作对话管理维护与用户的多轮对话历史。技能路由理解用户意图自动调用合适的 Skill。大模型集成无缝对接 DeepSeek 等大模型处理自然语言理解与生成。状态管理保持 Agent 在一次会话中的上下文状态。你可以把 Harness 看作一个“智能体操作系统”而我们的 Obsidian Agent 就是运行在这个系统上的一个“超级应用”。Obsidian Vault知识库这就是我们的“环境”。Obsidian 以纯 Markdown 文件形式存储所有笔记通常集中在一个文件夹Vault中。这种无锁定的、基于文件系统的设计使得外部程序我们的 Agent可以非常方便地通过标准文件 API 进行读取和交互这是实现深度集成的前提。3. 环境准备与前置条件开始搭建之前请确保你的环境满足以下要求。这是一个典型的基于 Python 的技术栈。3.1 基础运行环境操作系统Windows 10/11, macOS 10.15, 或主流的 Linux 发行版如 Ubuntu 20.04。本文示例将在 macOS/Linux 环境下演示Windows 用户请注意路径分隔符\需改为/或使用os.path处理。Python版本 3.8 至 3.11。推荐使用 3.9 或 3.10 以获得最佳兼容性。在终端使用python --version或python3 --version检查。包管理工具pip通常随 Python 安装。建议升级到最新版pip install --upgrade pip。3.2 获取 DeepSeek API 密钥我们的 Agent 需要“大脑”即 DeepSeek 的大模型。你需要访问 DeepSeek 官方平台例如 platform.deepseek.com。注册并登录账号。在控制台中找到“API Keys”或“密钥管理”部分。创建一个新的 API 密钥并妥善保存。注意密钥一旦创建将只显示一次请立即复制保存到安全的地方。3.3 准备你的 Obsidian 仓库确保你的 Obsidian Vault 已经存在并且包含一些笔记。这是 Agent 将要操作的“知识世界”。找到你的 Vault 的绝对路径。例如macOS/Linux:/Users/YourName/Documents/MyObsidianVaultWindows:C:\Users\YourName\Documents\MyObsidianVault重要备份在开发阶段我们的 Agent 将以“只读”模式运行但出于绝对安全考虑在进行任何涉及文件写入的操作前请务必备份你的 Vault。3.4 创建项目目录为你的 Agent 项目创建一个独立的工作目录与你的 Obsidian Vault 分开。mkdir obsidian-agent cd obsidian-agent4. 项目初始化与 Harness 框架安装我们将在这个独立目录中构建我们的 Agent 应用。4.1 创建虚拟环境强烈推荐使用虚拟环境可以隔离项目依赖避免包冲突。# 创建虚拟环境 python -m venv venv # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate激活后你的命令行提示符前通常会显示(venv)。4.2 安装 DeepSeek HarnessHarness 框架及其核心依赖可以通过 pip 安装。目前你可能需要从官方指定的源或 GitHub 安装。# 假设 harness 已发布到 PyPI安装核心包 pip install deepseek-harness # 通常还需要安装相关的 AI 依赖如 openai 兼容包DeepSeek API 兼容 OpenAI 格式 pip install openai4.3 初始化项目结构一个清晰的目录结构有助于管理代码。创建如下文件和文件夹obsidian-agent/ ├── venv/ # Python 虚拟环境由上一步创建 ├── skills/ # 存放所有自定义 Skill 的目录 │ ├── __init__.py │ └── obsidian_skills.py # 我们将在这里编写 Obsidian 相关技能 ├── agent_core.py # Agent 核心配置与启动文件 ├── config.yaml # 配置文件存放 API Key、Vault 路径等 └── requirements.txt # 项目依赖列表生成requirements.txt文件pip freeze requirements.txt5. 核心流程拆解构建 Obsidian 专属技能Skills这是最核心的一步。我们将创建几个最实用、最基础的 Obsidian Skill。Harness 框架中一个 Skill 通常包含以下几个部分技能描述用自然语言告诉 AI 这个技能是做什么的。输入参数定义技能需要哪些输入。执行函数具体的代码逻辑。输出格式定义技能返回的结果结构。5.1 创建技能文件在skills/obsidian_skills.py中我们开始编写第一个技能读取笔记。# skills/obsidian_skills.py import os import yaml from typing import Dict, Any, Optional from harness.skill import Skill, SkillInput, SkillOutput class ReadNoteSkill(Skill): 一个用于读取 Obsidian 仓库中指定笔记内容的技能。 def __init__(self, vault_path: str): 初始化技能需要传入 Obsidian 仓库的根路径。 Args: vault_path: Obsidian 仓库的绝对路径。 super().__init__( nameread_note, description根据笔记的标题或文件路径读取该笔记的完整内容。如果找不到会尝试进行模糊搜索。, inputs[ SkillInput(namenote_identifier, typestring, description笔记的标题不含.md或相对仓库根目录的路径如 Projects/Agent设计.md) ] ) self.vault_path vault_path def _find_note_file(self, identifier: str) - Optional[str]: 根据标识符查找笔记文件的实际路径。 # 情况1标识符本身是带 .md 后缀的路径 if identifier.endswith(.md): candidate os.path.join(self.vault_path, identifier) if os.path.exists(candidate): return candidate # 如果不带路径直接是文件名也在根目录找找 candidate os.path.join(self.vault_path, os.path.basename(identifier)) if os.path.exists(candidate): return candidate # 情况2标识符是标题不含.md # 先尝试直接加上 .md candidate os.path.join(self.vault_path, f{identifier}.md) if os.path.exists(candidate): return candidate # 情况3模糊搜索整个仓库简单实现实际项目可用更高效方法 for root, dirs, files in os.walk(self.vault_path): for file in files: if file.endswith(.md): # 检查文件名不含后缀是否包含标识符或反之 file_name_without_ext os.path.splitext(file)[0] if identifier in file_name_without_ext or file_name_without_ext in identifier: return os.path.join(root, file) return None def execute(self, inputs: Dict[str, Any]) - SkillOutput: 执行技能读取笔记内容。 note_identifier inputs.get(note_identifier, ).strip() if not note_identifier: return SkillOutput(successFalse, error未提供笔记标识符。) note_path self._find_note_file(note_identifier) if not note_path or not os.path.exists(note_path): return SkillOutput( successFalse, errorf未找到标识符为 {note_identifier} 的笔记。请检查标题或路径是否正确。 ) try: with open(note_path, r, encodingutf-8) as f: content f.read() # 返回成功结果包含内容和元数据 return SkillOutput( successTrue, data{ content: content, path: os.path.relpath(note_path, self.vault_path), title: os.path.splitext(os.path.basename(note_path))[0] } ) except Exception as e: return SkillOutput(successFalse, errorf读取笔记时发生错误{str(e)}) # 接下来可以定义第二个技能搜索仓库 class SearchVaultSkill(Skill): 在全仓库中搜索包含特定关键词的笔记。 def __init__(self, vault_path: str): super().__init__( namesearch_vault, description在 Obsidian 仓库中搜索包含特定关键词或短语的笔记。返回匹配的笔记列表及其摘要。, inputs[ SkillInput(namequery, typestring, description搜索关键词或短语) ] ) self.vault_path vault_path def execute(self, inputs: Dict[str, Any]) - SkillOutput: query inputs.get(query, ).strip().lower() if not query: return SkillOutput(successFalse, error未提供搜索关键词。) results [] try: for root, dirs, files in os.walk(self.vault_path): for file in files: if file.endswith(.md): file_path os.path.join(root, file) try: with open(file_path, r, encodingutf-8) as f: content f.read().lower() if query in content: # 简单提取前200字符作为预览 preview content[:200].replace(\n, ) ... rel_path os.path.relpath(file_path, self.vault_path) results.append({ title: os.path.splitext(file)[0], path: rel_path, preview: preview }) except: continue # 跳过无法读取的文件 return SkillOutput( successTrue, data{ query: query, count: len(results), results: results[:10] # 限制返回数量 } ) except Exception as e: return SkillOutput(successFalse, errorf搜索过程中发生错误{str(e)})代码解读ReadNoteSkill和SearchVaultSkill都继承自 Harness 框架的Skill基类。__init__方法中定义了技能的元数据name,description,inputs这些信息会被 Harness 用来让 AI 理解何时调用该技能。execute方法是技能的核心它接收输入参数执行实际的文件操作并返回一个标准化的SkillOutput对象。我们实现了简单的文件查找和全文搜索逻辑。在生产环境中SearchVaultSkill可以升级为使用向量数据库进行语义搜索效率会高得多。5.2 创建配置文件在项目根目录创建config.yaml用于管理敏感信息和可变配置。# config.yaml deepseek: api_key: your_deepseek_api_key_here # 请替换为你的真实 API 密钥 base_url: https://api.deepseek.com # DeepSeek API 端点 model: deepseek-chat # 使用的模型根据 DeepSeek 最新文档调整 obsidian: vault_path: /absolute/path/to/your/obsidian/vault # 你的 Obsidian 仓库绝对路径 agent: name: Obsidian 知识助手 system_prompt: | 你是一个集成在 Obsidian 笔记软件中的智能助手。你的核心能力是基于用户的个人知识库Obsidian Vault进行问答和操作。 你可以读取指定的笔记或根据用户的问题在全库中搜索相关信息。 你的回答应当基于知识库中的事实如果知识库中没有相关信息请诚实告知用户并可以基于你的通用知识提供建议但需注明。 请保持回答专业、清晰、有帮助。重要提示永远不要将包含真实 API 密钥的config.yaml提交到 Git 等版本控制系统。你应该将其添加到.gitignore文件中并使用config.example.yaml存储模板。6. 组装与启动构建完整的 Agent现在我们将技能、配置和 Harness 框架的核心组装起来创建一个可运行的 Agent。6.1 编写 Agent 核心文件创建agent_core.py# agent_core.py import yaml import os import sys from pathlib import Path # 将当前目录和技能目录加入 Python 路径确保模块导入正常 sys.path.insert(0, str(Path(__file__).parent)) from harness import Harness, Agent from skills.obsidian_skills import ReadNoteSkill, SearchVaultSkill def load_config(): 加载配置文件。 config_path Path(__file__).parent / config.yaml if not config_path.exists(): raise FileNotFoundError(f配置文件未找到{config_path}。请确保 config.yaml 存在并已正确配置。) with open(config_path, r, encodingutf-8) as f: return yaml.safe_load(f) def create_obsidian_agent(config: dict) - Agent: 创建并配置 Obsidian 专属 Agent。 # 1. 初始化 Harness 框架 harness Harness( api_keyconfig[deepseek][api_key], base_urlconfig[deepseek][base_url], modelconfig[deepseek][model] ) # 2. 获取 Obsidian 仓库路径 vault_path config[obsidian][vault_path] if not os.path.isdir(vault_path): raise ValueError(f配置的 Obsidian 仓库路径不存在或不是一个目录{vault_path}) print(f[INFO] 已加载 Obsidian 仓库{vault_path}) # 3. 创建技能实例 read_skill ReadNoteSkill(vault_pathvault_path) search_skill SearchVaultSkill(vault_pathvault_path) # 4. 向 Harness 注册技能 harness.register_skill(read_skill) harness.register_skill(search_skill) print(f[INFO] 已注册技能{read_skill.name}, {search_skill.name}) # 5. 创建 Agent并注入系统提示词 agent harness.create_agent( nameconfig[agent][name], system_promptconfig[agent][system_prompt] ) return agent def main(): 主函数启动 Agent 交互循环。 try: config load_config() agent create_obsidian_agent(config) print(f\n{*50}) print(f欢迎使用 {agent.name}) print(你可以向我提问关于你的 Obsidian 笔记的问题。) print(例如) print( - 读取《项目规划》这篇笔记) print( - 搜索所有提到「机器学习」的笔记) print( - 帮我总结一下《每周复盘》的内容需要后续扩展总结技能) print(输入 quit 或 退出 结束对话。) print(f{*50}\n) # 简单的命令行交互循环 while True: try: user_input input(\n你).strip() if user_input.lower() in [quit, exit, 退出, q]: print(再见) break if not user_input: continue print(f\n{agent.name}, end, flushTrue) # 调用 Agent 处理用户输入streamTrue 可实现流式输出 response agent.chat(user_input, streamTrue) full_response for chunk in response: print(chunk, end, flushTrue) full_response chunk print() # 换行 except KeyboardInterrupt: print(\n\n检测到中断退出。) break except Exception as e: print(f\n处理请求时出错{e}) except Exception as e: print(f启动 Agent 失败{e}) sys.exit(1) if __name__ __main__: main()6.2 安装缺失依赖确保安装了 PyYAML 用于读取配置文件。pip install pyyaml7. 运行结果与效果验证一切就绪让我们启动 Agent 并进行首次对话测试。7.1 启动 Agent在项目根目录下运行python agent_core.py如果一切配置正确你将看到类似以下的启动信息[INFO] 已加载 Obsidian 仓库/Users/YourName/Documents/MyObsidianVault [INFO] 已注册技能read_note, search_vault 欢迎使用 Obsidian 知识助手 你可以向我提问关于你的 Obsidian 笔记的问题。 例如 - 读取《项目规划》这篇笔记 - 搜索所有提到「机器学习」的笔记 - 帮我总结一下《每周复盘》的内容需要后续扩展总结技能 输入 quit 或 退出 结束对话。 7.2 进行对话测试现在你可以像与 ChatGPT 一样与你的 Obsidian Agent 对话。它会自动判断你的意图并调用相应的技能。测试场景 1读取笔记你读取《项目规划》这篇笔记 Obsidian 知识助手我将为您查找并读取标题为“项目规划”的笔记。 思考中...调用 read_note 技能 找到笔记《项目规划》。内容如下 --- # 项目规划个人知识管理助手 **目标**构建一个基于AI的Obsidian辅助工具... 后续显示笔记完整内容测试场景 2搜索笔记你搜索所有提到“Python”的笔记 Obsidian 知识助手我将为您在全库中搜索包含“Python”的笔记。 思考中...调用 search_vault 技能 搜索完成。共找到 5 篇相关笔记 1. **《学习日志-2024-03》** 路径Daily/2024-03.md 预览今天学习了Python装饰器的用法它能够在不修改原函数代码的情况下增加功能... 2. **《数据分析脚本编写》** 路径Projects/DataAnalysis.md 预览这个项目主要使用Python的pandas和matplotlib库... 后续列出其他结果7.3 验证技能调用Harness 框架的一个优点是它通常会在后台或通过设置显示 Agent 的“思考过程”即它决定调用哪个技能以及调用的结果。这有助于调试和理解 Agent 的行为。你可以在agent.chat()方法中增加相关参数或查看框架日志来观察这一过程。8. 扩展技能让 Agent 更强大基础技能只能读取和搜索。一个真正有用的助手应该能“思考”和“创作”。让我们为它添加两个更高级的技能总结笔记和生成关联图谱建议。8.1 添加总结技能在skills/obsidian_skills.py中新增一个类# 在 skills/obsidian_skills.py 文件末尾添加 from harness.skill import Skill, SkillInput, SkillOutput # 假设我们已经能够调用大模型进行总结 import openai class SummarizeNoteSkill(Skill): 总结一篇笔记的核心内容。 def __init__(self, vault_path: str, api_key: str, base_url: str): super().__init__( namesummarize_note, description对指定的笔记进行总结提炼其核心观点、关键事实和结论。, inputs[ SkillInput(namenote_identifier, typestring, description需要总结的笔记标识符) ] ) self.vault_path vault_path # 初始化 OpenAI 兼容客户端用于 DeepSeek self.client openai.OpenAI(api_keyapi_key, base_urlbase_url) def execute(self, inputs: Dict[str, Any]) - SkillOutput: note_identifier inputs.get(note_identifier, ).strip() if not note_identifier: return SkillOutput(successFalse, error未提供笔记标识符。) # 复用 ReadNoteSkill 的逻辑查找并读取笔记这里简化实际可依赖或重构 note_path self._find_note_file_simple(note_identifier) if not note_path: return SkillOutput(successFalse, errorf未找到笔记 {note_identifier}。) try: with open(note_path, r, encodingutf-8) as f: content f.read() if len(content) 50: return SkillOutput(successTrue, data{summary: 笔记内容过短无需总结。, original_length: len(content)}) # 调用大模型进行总结 response self.client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个专业的总结助手。请用简洁清晰的中文总结以下文本的核心内容分点列出关键信息。}, {role: user, content: f请总结以下笔记\n\n{content[:3000]}} # 限制长度防止超 token ], temperature0.3, max_tokens500 ) summary response.choices[0].message.content return SkillOutput( successTrue, data{ summary: summary, title: os.path.splitext(os.path.basename(note_path))[0], original_length: len(content) } ) except Exception as e: return SkillOutput(successFalse, errorf总结笔记时发生错误{str(e)}) def _find_note_file_simple(self, identifier): # 简化的查找逻辑实际项目应复用或提取公共方法 import os possible_paths [ os.path.join(self.vault_path, f{identifier}.md), os.path.join(self.vault_path, identifier), ] for p in possible_paths: if os.path.exists(p): return p return None8.2 更新 Agent 创建函数修改agent_core.py中的create_obsidian_agent函数注册新的技能# 在 agent_core.py 的导入部分添加 from skills.obsidian_skills import SummarizeNoteSkill # 修改 create_obsidian_agent 函数内部注册技能的部分 def create_obsidian_agent(config: dict) - Agent: # ... 前面的初始化代码不变 ... # 创建技能实例 read_skill ReadNoteSkill(vault_pathvault_path) search_skill SearchVaultSkill(vault_pathvault_path) # 新增总结技能需要传入 API 配置 summarize_skill SummarizeNoteSkill( vault_pathvault_path, api_keyconfig[deepseek][api_key], base_urlconfig[deepseek][base_url] ) # 向 Harness 注册技能 harness.register_skill(read_skill) harness.register_skill(search_skill) harness.register_skill(summarize_skill) # 注册新技能 print(f[INFO] 已注册技能{read_skill.name}, {search_skill.name}, {summarize_skill.name}) # ... 后续代码不变 ...现在你的 Agent 就具备了总结能力。你总结一下《学习日志-2024-03》这篇笔记 Obsidian 知识助手我来为您总结这篇笔记。 思考中...调用 summarize_note 技能 已成功总结笔记《学习日志-2024-03》。 **总结如下** 1. **主题**Python装饰器学习。 2. **关键内容**记录了装饰器的基本概念、语法糖、带参数的装饰器实现以及在实际项目如日志记录、权限检查中的应用示例。 3. **难点与解决**理解了闭包在装饰器中的作用并通过编写一个计时装饰器加深了理解。 4. **后续计划**计划学习类装饰器和functools.wraps的使用。 原文长度约1200字。9. 常见问题与排查思路在开发和运行过程中你可能会遇到以下问题。这里提供系统的排查思路。问题现象可能原因排查方式解决方案启动报错ModuleNotFoundError: No module named harness1. Harness 包未安装。2. 虚拟环境未激活。3. Python 路径问题。1. 执行pip list | grep harness检查。2. 确认命令行提示符前有(venv)。3. 在 Python 交互环境中import sys; print(sys.path)查看路径。1. 确保在虚拟环境中运行pip install deepseek-harness。2. 重新激活虚拟环境。3. 在代码开头使用sys.path添加项目根目录。运行时报错openai.AuthenticationError1. API 密钥错误或过期。2.base_url配置错误。3. 网络问题导致无法访问 API。1. 检查config.yaml中的api_key是否复制完整。2. 确认base_url是 DeepSeek 最新的有效端点。3. 使用curl或浏览器测试 API 端点连通性。1. 在 DeepSeek 平台重新生成 API 密钥并更新配置。2. 查阅 DeepSeek 官方文档确认 API 地址。3. 检查网络代理或防火墙设置。Agent 无法找到笔记1.vault_path配置错误。2. 笔记标识符输入有误。3. 文件权限问题。1. 打印vault_path变量确认路径正确。2. 检查技能中的查找逻辑尝试打印搜索过程。3. 检查 Python 进程是否有权读取目标目录。1. 使用绝对路径并确保路径中的大小写和符号正确。2. 优化_find_note_file函数增加更灵活的匹配如忽略空格、中英文括号。3. 调整文件系统权限。技能未被调用Agent 直接通用回答1. 技能描述 (description) 不够清晰。2. 系统提示词 (system_prompt) 未引导 Agent 使用技能。3. 用户提问方式太模糊。1. 观察 Harness 的调试日志看 Agent 是否进行了技能路由决策。2. 检查system_prompt是否明确说明了可用技能。1. 重写技能描述更精确地定义其用途和适用场景。2. 在system_prompt中举例说明如何使用技能。3. 引导用户提问更具体如“请使用‘读取笔记’技能查看《XXX》”。处理长笔记时 API 调用超时或 Token 超限1. 笔记内容过长超出模型上下文窗口。2. 网络延迟高。1. 在代码中打印发送给 API 的文本长度。2. 监控 API 调用耗时。1. 在发送前对长文本进行智能截断或分块总结。2. 增加请求超时时间。3. 考虑使用更高上下文长度的模型如果可用。搜索技能效率低下对大型仓库数千笔记进行全文件遍历搜索速度慢。使用time模块对搜索函数进行计时。1. 引入缓存机制如对笔记建立索引文件。2.升级为向量搜索将笔记内容向量化后存入向量数据库如 Chroma, FAISS实现语义搜索。10. 最佳实践与工程建议将个人项目推向更稳定、可用的阶段需要遵循一些工程最佳实践。10.1 配置管理分离配置将config.yaml拆分为config.example.yaml模板和本地config.local.yaml被.gitignore忽略。通过环境变量或代码判断加载哪个文件。使用环境变量对于 API 密钥等极度敏感信息优先使用环境变量。# 在启动前设置 export DEEPSEEK_API_KEYyour_key_here# 在代码中读取 import os api_key os.getenv(DEEPSEEK_API_KEY, defaultfallback_key_if_any)10.2 技能设计单一职责每个技能只做一件事并做好。例如read_note只负责读取summarize_note负责总结而不是一个技能既读又总结。健壮性对所有外部调用文件 I/O、网络请求进行异常捕获并返回友好的错误信息。输入验证在技能执行函数开头验证输入参数的有效性。10.3 性能优化向量化搜索对于SearchVaultSkill全量遍历是原型阶段的权宜之计。生产环境必须引入向量数据库。流程如下安装sentence-transformers等嵌入模型库。编写脚本将仓库内所有笔记转换为向量存入 Chroma 或 FAISS。修改SearchVaultSkill将用户查询也转换为向量在向量数据库中进行相似度搜索。可以定期如每天运行增量更新索引的脚本。缓存对频繁读取的笔记内容或元数据如笔记列表进行内存或磁盘缓存设置合理的过期时间。10.4 安全与隐私只读优先在技能设计初期尽量保持“只读”操作。谨慎实现写入、修改、删除文件的技能。如果必须实现务必加入二次确认机制并做好版本备份如操作前自动 git commit。权限隔离确保 Agent 进程只能访问指定的 Obsidian Vault 目录不能越权访问系统其他文件。API 用量监控DeepSeek API 调用会产生费用。在代码中加入简单的用量统计和日志避免意外消耗。10.5 部署与使用封装为服务可以将agent_core.py封装为 REST API 服务使用 FastAPI、Flask这样 Obsidian 插件或其他前端就可以通过 HTTP 调用你的 Agent。开发 Obsidian 插件终极目标是开发一个真正的 Obsidian 插件在插件内调用本地或远程的 Agent 服务实现无缝集成。这需要 JavaScript/TypeScript 知识。日志记录为 Agent 添加详细的日志记录如使用 Pythonlogging模块记录每一次用户交互、技能调用和 API 请求便于调试和优化。通过以上步骤你不仅拥有了一个能运行的 Obsidian AI Agent更掌握了一套用 Harness 框架构建专属智能体的方法论。这个 Agent 的潜力远不止于此你可以继续为它添加“智能标签推荐”、“周报自动生成”、“知识图谱问答”等高级技能让它真正成为你知识管理系统的核心大脑。 基于DeepSeek Harness框架构建Obsidian专属AI智能体实践指南
如果你是一个 Obsidian 重度用户每天在笔记的海洋里遨游那么最近一定被一个词刷屏了Agent。从 ChatGPT 到 Claude再到国内的 DeepSeek大模型的能力早已不限于聊天。但你是否想过让一个专属的 AI 助手直接“住”进你的 Obsidian 知识库不仅能回答你关于笔记的问题还能帮你整理、归纳、甚至基于你的知识库进行创作这听起来像是未来但 DeepSeek 推出的Harness框架正在让这个未来触手可及。它不是一个现成的 Obsidian 插件而是一个强大的AI Agent 开发框架。这意味着你可以用它来“组装”一个完全为你 Obsidian 工作流定制的智能体。很多人看到“Agent 开发框架”就望而却步以为需要高深的 AI 知识和复杂的工程能力。但 Harness 的核心设计理念恰恰相反它试图将构建 AI 应用的门槛从“算法工程”降低到“功能组装”。你不需要从头训练模型也不需要理解复杂的提示工程Prompt Engineering的所有细节你只需要清晰地定义“你想让 AI 帮你做什么”以及“它能调用哪些工具Tools”。本文将带你从零开始深入浅出地拆解如何利用 DeepSeek Harness 框架为你心爱的 Obsidian 打造一个专属的 AI Agent。我们将不止步于“是什么”而是聚焦于“为什么能”和“怎么做”。你会看到整个过程更像是在用乐高积木搭建一个智能工作台而非编写晦涩的代码。1. 这篇文章真正要解决的问题为什么是 Harness Obsidian在深入代码之前我们必须先回答一个根本问题市面上 AI 工具这么多为什么偏偏要选择 DeepSeek Harness 来开发 Obsidian Agent这背后是三个核心痛点的精准打击。痛点一数据孤岛与上下文割裂。你或许试过将 Obsidian 的笔记复制粘贴到 ChatGPT 的网页对话框里。一次两次尚可但如果想让 AI 深度理解你成百上千篇笔记之间的联系、你的知识体系脉络这种手动搬运的方式效率极低且无法形成持续的“记忆”。你的知识库是活的、不断增长的但传统的 AI 对话窗口是死的、一次性的。痛点二通用模型与专属知识的鸿沟。ChatGPT 很强大但它不了解“你”。它不知道你笔记里“那个重要的项目”具体指什么也不清楚你自创的标签体系“#PKM/核心”代表怎样的分类逻辑。一个理想的助手应该以你的个人知识库为“记忆体”和“事实依据”来回答问题而不是依赖它那可能已经过时或泛化的通用知识。痛点三开发门槛与灵活性的矛盾。你当然可以自己调用 OpenAI 或 DeepSeek 的 API写一个 Python 脚本去读取 Obsidian 的 Markdown 文件然后构建一个简单的问答系统。但这意味着你要处理文件 I/O、文本分割、向量化Embedding、检索Retrieval、对话历史管理等一系列问题。而 Harness 框架的价值在于它已经将这些底层能力模块化、标准化了。你需要关心的不再是“轮子怎么造”而是“这辆车要往哪里开以及配备什么功能”。因此Harness Obsidian 的组合瞄准的正是这样一个场景为每一位知识工作者提供一个以自己私有、动态增长的知识库为大脑的可高度定制化功能的数字助理。它不仅仅是“聊天机器人”更是能主动介入你工作流的智能体Agent。2. 核心概念拆解Agent、Skill、Harness 与 Obsidian Vault在动手之前我们需要统一语言。这几个概念是理解整个项目的基石。Agent智能体在 AI 语境下Agent 不是一个简单的聊天程序。它是一个能够感知环境你的输入、你的知识库、进行决策判断该调用哪个工具、执行动作读取文件、搜索、生成文本并达成目标的自治系统。我们最终要构建的就是一个专属于你 Obsidian 的 Agent。Skill技能这是 Harness 框架的核心抽象。一个 Skill 就是一个 Agent 能够执行的独立功能单元。你可以把它理解为 Agent 的“工具包”里的一个个工具。例如read_note技能根据笔记标题或路径读取笔记内容。search_vault技能在全库中基于语义或关键词搜索相关笔记。summarize技能总结一篇长笔记的核心观点。generate_outline技能基于某个主题利用现有笔记生成文章大纲。Harness 的强大之处在于它提供了一套标准方式来定义、实现和注册这些 Skill。Harness框架DeepSeek Harness 是一个用于构建、编排和管理 AI Agent 的开源框架。它负责处理所有繁琐的底层工作对话管理维护与用户的多轮对话历史。技能路由理解用户意图自动调用合适的 Skill。大模型集成无缝对接 DeepSeek 等大模型处理自然语言理解与生成。状态管理保持 Agent 在一次会话中的上下文状态。你可以把 Harness 看作一个“智能体操作系统”而我们的 Obsidian Agent 就是运行在这个系统上的一个“超级应用”。Obsidian Vault知识库这就是我们的“环境”。Obsidian 以纯 Markdown 文件形式存储所有笔记通常集中在一个文件夹Vault中。这种无锁定的、基于文件系统的设计使得外部程序我们的 Agent可以非常方便地通过标准文件 API 进行读取和交互这是实现深度集成的前提。3. 环境准备与前置条件开始搭建之前请确保你的环境满足以下要求。这是一个典型的基于 Python 的技术栈。3.1 基础运行环境操作系统Windows 10/11, macOS 10.15, 或主流的 Linux 发行版如 Ubuntu 20.04。本文示例将在 macOS/Linux 环境下演示Windows 用户请注意路径分隔符\需改为/或使用os.path处理。Python版本 3.8 至 3.11。推荐使用 3.9 或 3.10 以获得最佳兼容性。在终端使用python --version或python3 --version检查。包管理工具pip通常随 Python 安装。建议升级到最新版pip install --upgrade pip。3.2 获取 DeepSeek API 密钥我们的 Agent 需要“大脑”即 DeepSeek 的大模型。你需要访问 DeepSeek 官方平台例如 platform.deepseek.com。注册并登录账号。在控制台中找到“API Keys”或“密钥管理”部分。创建一个新的 API 密钥并妥善保存。注意密钥一旦创建将只显示一次请立即复制保存到安全的地方。3.3 准备你的 Obsidian 仓库确保你的 Obsidian Vault 已经存在并且包含一些笔记。这是 Agent 将要操作的“知识世界”。找到你的 Vault 的绝对路径。例如macOS/Linux:/Users/YourName/Documents/MyObsidianVaultWindows:C:\Users\YourName\Documents\MyObsidianVault重要备份在开发阶段我们的 Agent 将以“只读”模式运行但出于绝对安全考虑在进行任何涉及文件写入的操作前请务必备份你的 Vault。3.4 创建项目目录为你的 Agent 项目创建一个独立的工作目录与你的 Obsidian Vault 分开。mkdir obsidian-agent cd obsidian-agent4. 项目初始化与 Harness 框架安装我们将在这个独立目录中构建我们的 Agent 应用。4.1 创建虚拟环境强烈推荐使用虚拟环境可以隔离项目依赖避免包冲突。# 创建虚拟环境 python -m venv venv # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate激活后你的命令行提示符前通常会显示(venv)。4.2 安装 DeepSeek HarnessHarness 框架及其核心依赖可以通过 pip 安装。目前你可能需要从官方指定的源或 GitHub 安装。# 假设 harness 已发布到 PyPI安装核心包 pip install deepseek-harness # 通常还需要安装相关的 AI 依赖如 openai 兼容包DeepSeek API 兼容 OpenAI 格式 pip install openai4.3 初始化项目结构一个清晰的目录结构有助于管理代码。创建如下文件和文件夹obsidian-agent/ ├── venv/ # Python 虚拟环境由上一步创建 ├── skills/ # 存放所有自定义 Skill 的目录 │ ├── __init__.py │ └── obsidian_skills.py # 我们将在这里编写 Obsidian 相关技能 ├── agent_core.py # Agent 核心配置与启动文件 ├── config.yaml # 配置文件存放 API Key、Vault 路径等 └── requirements.txt # 项目依赖列表生成requirements.txt文件pip freeze requirements.txt5. 核心流程拆解构建 Obsidian 专属技能Skills这是最核心的一步。我们将创建几个最实用、最基础的 Obsidian Skill。Harness 框架中一个 Skill 通常包含以下几个部分技能描述用自然语言告诉 AI 这个技能是做什么的。输入参数定义技能需要哪些输入。执行函数具体的代码逻辑。输出格式定义技能返回的结果结构。5.1 创建技能文件在skills/obsidian_skills.py中我们开始编写第一个技能读取笔记。# skills/obsidian_skills.py import os import yaml from typing import Dict, Any, Optional from harness.skill import Skill, SkillInput, SkillOutput class ReadNoteSkill(Skill): 一个用于读取 Obsidian 仓库中指定笔记内容的技能。 def __init__(self, vault_path: str): 初始化技能需要传入 Obsidian 仓库的根路径。 Args: vault_path: Obsidian 仓库的绝对路径。 super().__init__( nameread_note, description根据笔记的标题或文件路径读取该笔记的完整内容。如果找不到会尝试进行模糊搜索。, inputs[ SkillInput(namenote_identifier, typestring, description笔记的标题不含.md或相对仓库根目录的路径如 Projects/Agent设计.md) ] ) self.vault_path vault_path def _find_note_file(self, identifier: str) - Optional[str]: 根据标识符查找笔记文件的实际路径。 # 情况1标识符本身是带 .md 后缀的路径 if identifier.endswith(.md): candidate os.path.join(self.vault_path, identifier) if os.path.exists(candidate): return candidate # 如果不带路径直接是文件名也在根目录找找 candidate os.path.join(self.vault_path, os.path.basename(identifier)) if os.path.exists(candidate): return candidate # 情况2标识符是标题不含.md # 先尝试直接加上 .md candidate os.path.join(self.vault_path, f{identifier}.md) if os.path.exists(candidate): return candidate # 情况3模糊搜索整个仓库简单实现实际项目可用更高效方法 for root, dirs, files in os.walk(self.vault_path): for file in files: if file.endswith(.md): # 检查文件名不含后缀是否包含标识符或反之 file_name_without_ext os.path.splitext(file)[0] if identifier in file_name_without_ext or file_name_without_ext in identifier: return os.path.join(root, file) return None def execute(self, inputs: Dict[str, Any]) - SkillOutput: 执行技能读取笔记内容。 note_identifier inputs.get(note_identifier, ).strip() if not note_identifier: return SkillOutput(successFalse, error未提供笔记标识符。) note_path self._find_note_file(note_identifier) if not note_path or not os.path.exists(note_path): return SkillOutput( successFalse, errorf未找到标识符为 {note_identifier} 的笔记。请检查标题或路径是否正确。 ) try: with open(note_path, r, encodingutf-8) as f: content f.read() # 返回成功结果包含内容和元数据 return SkillOutput( successTrue, data{ content: content, path: os.path.relpath(note_path, self.vault_path), title: os.path.splitext(os.path.basename(note_path))[0] } ) except Exception as e: return SkillOutput(successFalse, errorf读取笔记时发生错误{str(e)}) # 接下来可以定义第二个技能搜索仓库 class SearchVaultSkill(Skill): 在全仓库中搜索包含特定关键词的笔记。 def __init__(self, vault_path: str): super().__init__( namesearch_vault, description在 Obsidian 仓库中搜索包含特定关键词或短语的笔记。返回匹配的笔记列表及其摘要。, inputs[ SkillInput(namequery, typestring, description搜索关键词或短语) ] ) self.vault_path vault_path def execute(self, inputs: Dict[str, Any]) - SkillOutput: query inputs.get(query, ).strip().lower() if not query: return SkillOutput(successFalse, error未提供搜索关键词。) results [] try: for root, dirs, files in os.walk(self.vault_path): for file in files: if file.endswith(.md): file_path os.path.join(root, file) try: with open(file_path, r, encodingutf-8) as f: content f.read().lower() if query in content: # 简单提取前200字符作为预览 preview content[:200].replace(\n, ) ... rel_path os.path.relpath(file_path, self.vault_path) results.append({ title: os.path.splitext(file)[0], path: rel_path, preview: preview }) except: continue # 跳过无法读取的文件 return SkillOutput( successTrue, data{ query: query, count: len(results), results: results[:10] # 限制返回数量 } ) except Exception as e: return SkillOutput(successFalse, errorf搜索过程中发生错误{str(e)})代码解读ReadNoteSkill和SearchVaultSkill都继承自 Harness 框架的Skill基类。__init__方法中定义了技能的元数据name,description,inputs这些信息会被 Harness 用来让 AI 理解何时调用该技能。execute方法是技能的核心它接收输入参数执行实际的文件操作并返回一个标准化的SkillOutput对象。我们实现了简单的文件查找和全文搜索逻辑。在生产环境中SearchVaultSkill可以升级为使用向量数据库进行语义搜索效率会高得多。5.2 创建配置文件在项目根目录创建config.yaml用于管理敏感信息和可变配置。# config.yaml deepseek: api_key: your_deepseek_api_key_here # 请替换为你的真实 API 密钥 base_url: https://api.deepseek.com # DeepSeek API 端点 model: deepseek-chat # 使用的模型根据 DeepSeek 最新文档调整 obsidian: vault_path: /absolute/path/to/your/obsidian/vault # 你的 Obsidian 仓库绝对路径 agent: name: Obsidian 知识助手 system_prompt: | 你是一个集成在 Obsidian 笔记软件中的智能助手。你的核心能力是基于用户的个人知识库Obsidian Vault进行问答和操作。 你可以读取指定的笔记或根据用户的问题在全库中搜索相关信息。 你的回答应当基于知识库中的事实如果知识库中没有相关信息请诚实告知用户并可以基于你的通用知识提供建议但需注明。 请保持回答专业、清晰、有帮助。重要提示永远不要将包含真实 API 密钥的config.yaml提交到 Git 等版本控制系统。你应该将其添加到.gitignore文件中并使用config.example.yaml存储模板。6. 组装与启动构建完整的 Agent现在我们将技能、配置和 Harness 框架的核心组装起来创建一个可运行的 Agent。6.1 编写 Agent 核心文件创建agent_core.py# agent_core.py import yaml import os import sys from pathlib import Path # 将当前目录和技能目录加入 Python 路径确保模块导入正常 sys.path.insert(0, str(Path(__file__).parent)) from harness import Harness, Agent from skills.obsidian_skills import ReadNoteSkill, SearchVaultSkill def load_config(): 加载配置文件。 config_path Path(__file__).parent / config.yaml if not config_path.exists(): raise FileNotFoundError(f配置文件未找到{config_path}。请确保 config.yaml 存在并已正确配置。) with open(config_path, r, encodingutf-8) as f: return yaml.safe_load(f) def create_obsidian_agent(config: dict) - Agent: 创建并配置 Obsidian 专属 Agent。 # 1. 初始化 Harness 框架 harness Harness( api_keyconfig[deepseek][api_key], base_urlconfig[deepseek][base_url], modelconfig[deepseek][model] ) # 2. 获取 Obsidian 仓库路径 vault_path config[obsidian][vault_path] if not os.path.isdir(vault_path): raise ValueError(f配置的 Obsidian 仓库路径不存在或不是一个目录{vault_path}) print(f[INFO] 已加载 Obsidian 仓库{vault_path}) # 3. 创建技能实例 read_skill ReadNoteSkill(vault_pathvault_path) search_skill SearchVaultSkill(vault_pathvault_path) # 4. 向 Harness 注册技能 harness.register_skill(read_skill) harness.register_skill(search_skill) print(f[INFO] 已注册技能{read_skill.name}, {search_skill.name}) # 5. 创建 Agent并注入系统提示词 agent harness.create_agent( nameconfig[agent][name], system_promptconfig[agent][system_prompt] ) return agent def main(): 主函数启动 Agent 交互循环。 try: config load_config() agent create_obsidian_agent(config) print(f\n{*50}) print(f欢迎使用 {agent.name}) print(你可以向我提问关于你的 Obsidian 笔记的问题。) print(例如) print( - 读取《项目规划》这篇笔记) print( - 搜索所有提到「机器学习」的笔记) print( - 帮我总结一下《每周复盘》的内容需要后续扩展总结技能) print(输入 quit 或 退出 结束对话。) print(f{*50}\n) # 简单的命令行交互循环 while True: try: user_input input(\n你).strip() if user_input.lower() in [quit, exit, 退出, q]: print(再见) break if not user_input: continue print(f\n{agent.name}, end, flushTrue) # 调用 Agent 处理用户输入streamTrue 可实现流式输出 response agent.chat(user_input, streamTrue) full_response for chunk in response: print(chunk, end, flushTrue) full_response chunk print() # 换行 except KeyboardInterrupt: print(\n\n检测到中断退出。) break except Exception as e: print(f\n处理请求时出错{e}) except Exception as e: print(f启动 Agent 失败{e}) sys.exit(1) if __name__ __main__: main()6.2 安装缺失依赖确保安装了 PyYAML 用于读取配置文件。pip install pyyaml7. 运行结果与效果验证一切就绪让我们启动 Agent 并进行首次对话测试。7.1 启动 Agent在项目根目录下运行python agent_core.py如果一切配置正确你将看到类似以下的启动信息[INFO] 已加载 Obsidian 仓库/Users/YourName/Documents/MyObsidianVault [INFO] 已注册技能read_note, search_vault 欢迎使用 Obsidian 知识助手 你可以向我提问关于你的 Obsidian 笔记的问题。 例如 - 读取《项目规划》这篇笔记 - 搜索所有提到「机器学习」的笔记 - 帮我总结一下《每周复盘》的内容需要后续扩展总结技能 输入 quit 或 退出 结束对话。 7.2 进行对话测试现在你可以像与 ChatGPT 一样与你的 Obsidian Agent 对话。它会自动判断你的意图并调用相应的技能。测试场景 1读取笔记你读取《项目规划》这篇笔记 Obsidian 知识助手我将为您查找并读取标题为“项目规划”的笔记。 思考中...调用 read_note 技能 找到笔记《项目规划》。内容如下 --- # 项目规划个人知识管理助手 **目标**构建一个基于AI的Obsidian辅助工具... 后续显示笔记完整内容测试场景 2搜索笔记你搜索所有提到“Python”的笔记 Obsidian 知识助手我将为您在全库中搜索包含“Python”的笔记。 思考中...调用 search_vault 技能 搜索完成。共找到 5 篇相关笔记 1. **《学习日志-2024-03》** 路径Daily/2024-03.md 预览今天学习了Python装饰器的用法它能够在不修改原函数代码的情况下增加功能... 2. **《数据分析脚本编写》** 路径Projects/DataAnalysis.md 预览这个项目主要使用Python的pandas和matplotlib库... 后续列出其他结果7.3 验证技能调用Harness 框架的一个优点是它通常会在后台或通过设置显示 Agent 的“思考过程”即它决定调用哪个技能以及调用的结果。这有助于调试和理解 Agent 的行为。你可以在agent.chat()方法中增加相关参数或查看框架日志来观察这一过程。8. 扩展技能让 Agent 更强大基础技能只能读取和搜索。一个真正有用的助手应该能“思考”和“创作”。让我们为它添加两个更高级的技能总结笔记和生成关联图谱建议。8.1 添加总结技能在skills/obsidian_skills.py中新增一个类# 在 skills/obsidian_skills.py 文件末尾添加 from harness.skill import Skill, SkillInput, SkillOutput # 假设我们已经能够调用大模型进行总结 import openai class SummarizeNoteSkill(Skill): 总结一篇笔记的核心内容。 def __init__(self, vault_path: str, api_key: str, base_url: str): super().__init__( namesummarize_note, description对指定的笔记进行总结提炼其核心观点、关键事实和结论。, inputs[ SkillInput(namenote_identifier, typestring, description需要总结的笔记标识符) ] ) self.vault_path vault_path # 初始化 OpenAI 兼容客户端用于 DeepSeek self.client openai.OpenAI(api_keyapi_key, base_urlbase_url) def execute(self, inputs: Dict[str, Any]) - SkillOutput: note_identifier inputs.get(note_identifier, ).strip() if not note_identifier: return SkillOutput(successFalse, error未提供笔记标识符。) # 复用 ReadNoteSkill 的逻辑查找并读取笔记这里简化实际可依赖或重构 note_path self._find_note_file_simple(note_identifier) if not note_path: return SkillOutput(successFalse, errorf未找到笔记 {note_identifier}。) try: with open(note_path, r, encodingutf-8) as f: content f.read() if len(content) 50: return SkillOutput(successTrue, data{summary: 笔记内容过短无需总结。, original_length: len(content)}) # 调用大模型进行总结 response self.client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个专业的总结助手。请用简洁清晰的中文总结以下文本的核心内容分点列出关键信息。}, {role: user, content: f请总结以下笔记\n\n{content[:3000]}} # 限制长度防止超 token ], temperature0.3, max_tokens500 ) summary response.choices[0].message.content return SkillOutput( successTrue, data{ summary: summary, title: os.path.splitext(os.path.basename(note_path))[0], original_length: len(content) } ) except Exception as e: return SkillOutput(successFalse, errorf总结笔记时发生错误{str(e)}) def _find_note_file_simple(self, identifier): # 简化的查找逻辑实际项目应复用或提取公共方法 import os possible_paths [ os.path.join(self.vault_path, f{identifier}.md), os.path.join(self.vault_path, identifier), ] for p in possible_paths: if os.path.exists(p): return p return None8.2 更新 Agent 创建函数修改agent_core.py中的create_obsidian_agent函数注册新的技能# 在 agent_core.py 的导入部分添加 from skills.obsidian_skills import SummarizeNoteSkill # 修改 create_obsidian_agent 函数内部注册技能的部分 def create_obsidian_agent(config: dict) - Agent: # ... 前面的初始化代码不变 ... # 创建技能实例 read_skill ReadNoteSkill(vault_pathvault_path) search_skill SearchVaultSkill(vault_pathvault_path) # 新增总结技能需要传入 API 配置 summarize_skill SummarizeNoteSkill( vault_pathvault_path, api_keyconfig[deepseek][api_key], base_urlconfig[deepseek][base_url] ) # 向 Harness 注册技能 harness.register_skill(read_skill) harness.register_skill(search_skill) harness.register_skill(summarize_skill) # 注册新技能 print(f[INFO] 已注册技能{read_skill.name}, {search_skill.name}, {summarize_skill.name}) # ... 后续代码不变 ...现在你的 Agent 就具备了总结能力。你总结一下《学习日志-2024-03》这篇笔记 Obsidian 知识助手我来为您总结这篇笔记。 思考中...调用 summarize_note 技能 已成功总结笔记《学习日志-2024-03》。 **总结如下** 1. **主题**Python装饰器学习。 2. **关键内容**记录了装饰器的基本概念、语法糖、带参数的装饰器实现以及在实际项目如日志记录、权限检查中的应用示例。 3. **难点与解决**理解了闭包在装饰器中的作用并通过编写一个计时装饰器加深了理解。 4. **后续计划**计划学习类装饰器和functools.wraps的使用。 原文长度约1200字。9. 常见问题与排查思路在开发和运行过程中你可能会遇到以下问题。这里提供系统的排查思路。问题现象可能原因排查方式解决方案启动报错ModuleNotFoundError: No module named harness1. Harness 包未安装。2. 虚拟环境未激活。3. Python 路径问题。1. 执行pip list | grep harness检查。2. 确认命令行提示符前有(venv)。3. 在 Python 交互环境中import sys; print(sys.path)查看路径。1. 确保在虚拟环境中运行pip install deepseek-harness。2. 重新激活虚拟环境。3. 在代码开头使用sys.path添加项目根目录。运行时报错openai.AuthenticationError1. API 密钥错误或过期。2.base_url配置错误。3. 网络问题导致无法访问 API。1. 检查config.yaml中的api_key是否复制完整。2. 确认base_url是 DeepSeek 最新的有效端点。3. 使用curl或浏览器测试 API 端点连通性。1. 在 DeepSeek 平台重新生成 API 密钥并更新配置。2. 查阅 DeepSeek 官方文档确认 API 地址。3. 检查网络代理或防火墙设置。Agent 无法找到笔记1.vault_path配置错误。2. 笔记标识符输入有误。3. 文件权限问题。1. 打印vault_path变量确认路径正确。2. 检查技能中的查找逻辑尝试打印搜索过程。3. 检查 Python 进程是否有权读取目标目录。1. 使用绝对路径并确保路径中的大小写和符号正确。2. 优化_find_note_file函数增加更灵活的匹配如忽略空格、中英文括号。3. 调整文件系统权限。技能未被调用Agent 直接通用回答1. 技能描述 (description) 不够清晰。2. 系统提示词 (system_prompt) 未引导 Agent 使用技能。3. 用户提问方式太模糊。1. 观察 Harness 的调试日志看 Agent 是否进行了技能路由决策。2. 检查system_prompt是否明确说明了可用技能。1. 重写技能描述更精确地定义其用途和适用场景。2. 在system_prompt中举例说明如何使用技能。3. 引导用户提问更具体如“请使用‘读取笔记’技能查看《XXX》”。处理长笔记时 API 调用超时或 Token 超限1. 笔记内容过长超出模型上下文窗口。2. 网络延迟高。1. 在代码中打印发送给 API 的文本长度。2. 监控 API 调用耗时。1. 在发送前对长文本进行智能截断或分块总结。2. 增加请求超时时间。3. 考虑使用更高上下文长度的模型如果可用。搜索技能效率低下对大型仓库数千笔记进行全文件遍历搜索速度慢。使用time模块对搜索函数进行计时。1. 引入缓存机制如对笔记建立索引文件。2.升级为向量搜索将笔记内容向量化后存入向量数据库如 Chroma, FAISS实现语义搜索。10. 最佳实践与工程建议将个人项目推向更稳定、可用的阶段需要遵循一些工程最佳实践。10.1 配置管理分离配置将config.yaml拆分为config.example.yaml模板和本地config.local.yaml被.gitignore忽略。通过环境变量或代码判断加载哪个文件。使用环境变量对于 API 密钥等极度敏感信息优先使用环境变量。# 在启动前设置 export DEEPSEEK_API_KEYyour_key_here# 在代码中读取 import os api_key os.getenv(DEEPSEEK_API_KEY, defaultfallback_key_if_any)10.2 技能设计单一职责每个技能只做一件事并做好。例如read_note只负责读取summarize_note负责总结而不是一个技能既读又总结。健壮性对所有外部调用文件 I/O、网络请求进行异常捕获并返回友好的错误信息。输入验证在技能执行函数开头验证输入参数的有效性。10.3 性能优化向量化搜索对于SearchVaultSkill全量遍历是原型阶段的权宜之计。生产环境必须引入向量数据库。流程如下安装sentence-transformers等嵌入模型库。编写脚本将仓库内所有笔记转换为向量存入 Chroma 或 FAISS。修改SearchVaultSkill将用户查询也转换为向量在向量数据库中进行相似度搜索。可以定期如每天运行增量更新索引的脚本。缓存对频繁读取的笔记内容或元数据如笔记列表进行内存或磁盘缓存设置合理的过期时间。10.4 安全与隐私只读优先在技能设计初期尽量保持“只读”操作。谨慎实现写入、修改、删除文件的技能。如果必须实现务必加入二次确认机制并做好版本备份如操作前自动 git commit。权限隔离确保 Agent 进程只能访问指定的 Obsidian Vault 目录不能越权访问系统其他文件。API 用量监控DeepSeek API 调用会产生费用。在代码中加入简单的用量统计和日志避免意外消耗。10.5 部署与使用封装为服务可以将agent_core.py封装为 REST API 服务使用 FastAPI、Flask这样 Obsidian 插件或其他前端就可以通过 HTTP 调用你的 Agent。开发 Obsidian 插件终极目标是开发一个真正的 Obsidian 插件在插件内调用本地或远程的 Agent 服务实现无缝集成。这需要 JavaScript/TypeScript 知识。日志记录为 Agent 添加详细的日志记录如使用 Pythonlogging模块记录每一次用户交互、技能调用和 API 请求便于调试和优化。通过以上步骤你不仅拥有了一个能运行的 Obsidian AI Agent更掌握了一套用 Harness 框架构建专属智能体的方法论。这个 Agent 的潜力远不止于此你可以继续为它添加“智能标签推荐”、“周报自动生成”、“知识图谱问答”等高级技能让它真正成为你知识管理系统的核心大脑。