Hermes Agent LLM Wiki 技术应用：用 Skill Config 把 Obsidian Markdown 笔记接成可检索知识库

发布时间：2026/10/17 20:46:56
Hermes Agent LLM Wiki 技术应用：用 Skill Config 把 Obsidian Markdown 笔记接成可检索知识库
1. 从散落笔记到可对话知识库Hermes Agent LLM Wiki 要解决的真实问题如果你用 Obsidian 记了半年以上笔记大概率会遇到同一个尴尬笔记越写越多真正要用的时候却找不到。你记得自己写过某个概念但想不起放在哪个文件夹、用了什么标题你搜关键词出来二十条结果还得一条条点开看哪条才是当时那条完整记录。更麻烦的是笔记之间没有关联A 笔记里提到的结论B 笔记里其实有反例但你永远不会同时看到它们。Hermes Agent 的 LLM Wiki 场景就是冲着这个问题来的。它把 Obsidian 里的 Markdown 笔记当作语料通过 Skill Config 定义检索与问答技能让 Agent 能按主题调取笔记内容最终把一堆散落的.md文件变成一个可以对话的知识库。你问它「我之前关于向量检索的笔记里对 HNSW 和 IVF 的取舍是怎么记的」它会去读你的笔记、定位相关页面、综合出答案并且告诉你答案来自哪几个文件。这套东西适合谁三类人最合适。第一类是长期用 Obsidian 做研究笔记的人笔记量在几百篇以上靠文件夹和标签已经管不住了。第二类是需要把团队文档、会议记录、项目资料接成问答入口的人希望 Agent 能按主题调取而不是全文搜索。第三类是想搞清楚 LLM Wiki 和传统 RAG 区别的技术人想亲手跑一遍 Ingest、Query、Lint 三个核心操作。LLM Wiki 和传统 RAG 的核心差异在于RAG 每次查询都从头检索原始文档片段拼进上下文让模型生成LLM Wiki 则是让 LLM 先把原始资料编译成结构化的 Wiki 页面查询时读的是已经编译好的知识而不是原始碎片。前者是「每次现查」后者是「先建好再查」。这个差异决定了 LLM Wiki 更适合长期积累、需要交叉引用的知识场景而 RAG 更适合一次性问答。下面我会从 Obsidian 目录约定开始给出可复制的 Skill Config 片段然后演示一次从提问到引用笔记的完整验证流程最后把常见的报错和排查方法列清楚。整个过程你都可以跟着做。2. TaoToken 前置准备给 Hermes Agent 配好模型入口Hermes Agent 本身是一个 Agent 框架它需要一个能调用的模型服务来完成 Ingest 时的摘要生成、Query 时的答案综合、Lint 时的矛盾检测。这些操作对模型的上下文长度和指令遵循能力有要求尤其是 Ingest 阶段一次可能要读入几千字的笔记并输出结构化的 Wiki 页面。我用的方案是通过 TaoToken 接入模型。TaoToken 提供 OpenAI 兼容的 API 接口Hermes Agent 的模型配置里填上 Base URL 和 API Key 就能用。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。先拿到 API Key。登录后进控制台在 API Keys 页面创建一个新的 Key复制出来。这个 Key 后面要填进 Hermes 的配置里别弄丢。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 页面是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后需要确认你要用哪个模型。LLM Wiki 的 Ingest 和 Query 对模型能力有要求建议选上下文窗口大、指令遵循好的模型。你可以在模型对话页面先试一下地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 随便问几个需要综合多段信息的问题看看输出质量。Hermes Agent 的模型配置通常放在~/.hermes/config.yaml或者项目目录下的config.yaml。你需要填三个东西Base URL、API Key、Model ID。Base URL 填https://taotoken.net/apiAPI Key 填刚才复制的Model ID 填你在模型对话页面确认可用的模型名。这里有个容易踩的坑Hermes 的配置里模型相关的字段可能分散在model和provider两个 section 下。如果你只填了model.name没填provider.base_url请求会打到默认端点然后 401。所以下面这段配置你要完整复制不要只抄一半。# ~/.hermes/config.yaml model: name: your-model-id # 替换成你在模型对话页确认的 Model ID provider: openai-compatible base_url: https://taotoken.net/api api_key: sk-xxxxxxxxxxxx # 替换成你的 API Key max_tokens: 8192 temperature: 0.3 # Ingest 阶段建议低温度保证结构化输出稳定 # Skill Config 部分LLM Wiki 的路径配置 skills: config: wiki: path: ~/wiki # LLM Wiki 的根目录后面会详细讲目录结构如果你用的是 Coding Plan 或者需要长期跑 Agent 任务可以考虑 Coding Plan 方案地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。不过对于 LLM Wiki 这种偏知识管理的场景按量调用也够用。配置写完之后跑一下hermes config show确认配置被正确读取。如果输出里能看到你填的 base_url 和 model name说明前置准备完成。如果报错说找不到配置文件检查一下你是不是在正确的用户目录下执行的命令。还有一个细节Hermes Agent 的 Skill Config 支持变量注入wiki.path这个值会在技能执行时被注入到上下文里。如果你把路径写成相对路径比如./wiki那么它相对于 Hermes 的工作目录解析而不是相对于配置文件。所以建议直接写绝对路径避免后面 Ingest 的时候找不到目录。3. 可复制配置Obsidian 目录约定与 Skill Config 片段这一节是整篇的核心你要照着做的是两件事第一把 Obsidian 的笔记目录整理成 LLM Wiki 能识别的结构第二写一份 Skill Config告诉 Agent 怎么检索和问答。先说目录约定。LLM Wiki 的三层结构是 Raw Sources、Wiki Pages、Schema Config。对应到 Obsidian我建议这样组织~/wiki/ ├── raw/ # 原始来源层不可变 │ ├── articles/ # 网页剪藏、文章 │ ├── papers/ # 论文、PDF 转的 Markdown │ └── notes/ # 你自己的原始笔记 ├── wiki/ # Wiki 页面层Agent 拥有和维护 │ ├── entities/ # 实体页工具、人物、项目 │ ├── concepts/ # 概念页方法论、原理 │ ├── comparisons/ # 对比页A vs B │ └── queries/ # 查询结果页归档的问答 ├── SCHEMA.md # Schema 配置层定义结构和约定 ├── index.md # 内容目录 └── log.md # 操作日志这个结构的关键在于raw/和wiki/的分离。raw/放你的原始 Obsidian 笔记Agent 只读不改wiki/放 Agent 编译出来的结构化页面Agent 可以创建和更新。你的 Obsidian Vault 可以直接指向~/wiki这样你在 Obsidian 里能看到 Agent 生成的所有 Wiki 页面Graph View 也能用。Obsidian 的 Markdown 元数据约定主要是 YAML frontmatter。每个 Wiki 页面开头要有--- title: 页面标题 created: 2026-04-20 updated: 2026-04-20 type: entity | concept | comparison | query tags: [tag1, tag2] sources: [raw/notes/source-name.md] ---type字段决定页面放在哪个子目录tags用于检索过滤sources指回原始笔记。这个约定要写进SCHEMA.mdAgent 每次生成页面时会照着填。然后是 Skill Config。Hermes Agent 的 Skill Config 接口允许你定义技能的配置变量LLM Wiki 技能会读取wiki.path来定位知识库根目录。下面是一份完整的配置片段你可以直接复制到config.yaml里skills: config: wiki: path: /home/yourname/wiki # 绝对路径替换成你的实际路径 raw_dir: raw # 相对于 path 的子目录 wiki_dir: wiki schema_file: SCHEMA.md index_file: index.md log_file: log.md max_ingest_pages: 15 # 单次 Ingest 最多更新多少个 Wiki 页面 query_top_k: 5 # Query 时最多读取多少个相关页面 lint_checks: # 启用哪些 Lint 检查 - orphan_pages - dead_wikilinks - contradictions - missing_pages - unlinked_mentions - incomplete_metadata - empty_sections - stale_index如果你用的是 JSON 格式的配置有些 Hermes 版本支持等价写法是{ skills: { config: { wiki: { path: /home/yourname/wiki, raw_dir: raw, wiki_dir: wiki, schema_file: SCHEMA.md, index_file: index.md, log_file: log.md, max_ingest_pages: 15, query_top_k: 5, lint_checks: [ orphan_pages, dead_wikilinks, contradictions, missing_pages, unlinked_mentions, incomplete_metadata, empty_sections, stale_index ] } } } }配置里的max_ingest_pages是个保护机制。一次 Ingest 可能触及十几个 Wiki 页面如果超过这个数Agent 会先问你确认再批量更新避免它一口气改太多页面你来不及检查。query_top_k控制 Query 时读多少个页面设太大上下文会爆设太小可能漏掉相关信息5 是个比较稳的起点。SCHEMA.md的内容也要写清楚它是 Agent 的行为准则。至少要包含领域定义、文件命名规则、frontmatter 格式、标签分类表、更新策略。标签分类表尤其重要它防止标签泛滥。比如你定义tags只能从[llm, retrieval, vector-db, agent, tooling]里选Agent 就不会自己造新标签。Obsidian 那边建议装两个插件配合Dataview 用来查询 frontmatterGraph View 用来看知识结构。Dataview 的查询可以写在任意笔记里比如列出所有type: concept且tags包含retrieval的页面。这样你在 Obsidian 里也能按结构化方式浏览 Agent 生成的内容。配置写完之后跑一次hermes config show确认skills.config.wiki被正确加载。如果输出里能看到你填的路径和参数说明配置生效。接下来就可以进入验证环节了。4. 验证请求从提问到引用笔记的完整流程配置好之后最直接的验证方式是跑一次完整的 Ingest 加 Query。我拿一个真实场景来演示假设你在raw/notes/下有一篇关于向量检索的笔记文件名是vector-search-notes.md内容里提到了 HNSW 和 IVF 两种索引的取舍。你想让 Agent 把这篇笔记编译成 Wiki 页面然后通过提问来验证它能不能正确引用。第一步启动 Hermes Agent。在终端里执行hermes你会看到欢迎界面和可用工具列表。确认note-taking: obsidian这个技能在列表里说明 Obsidian 相关的技能已经加载。第二步触发 Ingest。在 Hermes 的对话里输入/llm-wiki 把 raw/notes/vector-search-notes.md 编译进知识库Agent 会读取这个文件然后按照SCHEMA.md的约定生成 Wiki 页面。它可能会创建wiki/concepts/vector-search.md作为概念页更新index.md把新页面加进去在log.md里追加一条 Ingest 记录。如果这篇笔记里提到了 HNSW 和 IVF它可能还会创建wiki/entities/hnsw.md和wiki/entities/ivf.md两个实体页并在概念页里用[[hnsw]]和[[ivf]]建立链接。Ingest 完成后Agent 会告诉你它创建或更新了哪些页面。你可以在 Obsidian 里打开~/wiki这个 Vault看到新生成的页面。检查一下 frontmatter 是否完整sources字段是否指回了raw/notes/vector-search-notes.md。第三步验证 Query。在 Hermes 里输入一个需要综合笔记内容的问题HNSW 和 IVF 在我的笔记里是怎么对比的各自的适用场景是什么Agent 会先读index.md定位相关页面然后深入读取wiki/concepts/vector-search.md以及它链接的实体页最后综合出答案。关键看两点答案里有没有引用具体的 Wiki 页面以及引用是否准确。一个正常的输出应该类似这样根据你的笔记HNSW 和 IVF 的对比可以总结为 HNSW[[hnsw]]适合对召回率要求高、可以接受较高内存占用的场景。 它的图结构在查询时能快速收敛但构建索引的时间较长。 IVF[[ivf]]适合数据量大、内存受限的场景。它通过聚类把向量 分到不同的桶里查询时只扫描部分桶速度快但召回率会有损失。 来源wiki/concepts/vector-search.mdwiki/entities/hnsw.md wiki/entities/ivf.md如果你看到这样的输出说明 Query 流程跑通了。Agent 不仅回答了问题还告诉你答案来自哪几个页面这就是 LLM Wiki 和普通搜索的区别它读的是已经编译好的结构化知识而不是原始笔记的碎片。第四步验证 Lint。输入/llm-wiki 对知识库做一次健康检查Agent 会跑 Lint 流程检查孤立页面、死链接、矛盾声明、缺失页面等。输出会列出发现的问题比如「wiki/entities/hnsw.md没有入链」或者「wiki/concepts/vector-search.md里提到了[[faiss]]但该页面不存在」。你可以根据这些提示去补充或修正。整个验证流程跑下来你应该能感受到 LLM Wiki 的工作方式Ingest 把原始笔记编译成结构化页面Query 读编译后的知识回答问题Lint 维护知识库的健康。这三个操作构成了一个闭环用得越久知识库越完整。如果你在 Query 阶段发现 Agent 没有引用到某篇笔记先检查那篇笔记有没有被 Ingest 过。LLM Wiki 只读wiki/目录下的页面不会直接去raw/里搜。所以原始笔记必须先经过 Ingest 编译才能被 Query 检索到。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节把 LLM Wiki 场景下最容易遇到的几个报错列出来每个都给出原因和解决方法。这些报错我在配置过程中都实际碰到过你照着排查能省不少时间。401 Unauthorized这是最常见的报错通常出现在 Ingest 或 Query 触发模型调用的时候。原因有三个可能API Key 填错了、Base URL 填错了、或者 Key 没有对应模型的权限。排查步骤先确认config.yaml里的api_key字段是不是完整的 Key有没有多余的空格。然后确认base_url是https://taotoken.net/api注意结尾不要多加/v1或者/chat/completionsHermes 会自己拼路径。最后去模型对话页面确认你填的 Model ID 是可用的有些模型需要单独开通。如果三个都确认没问题还是 401跑一下hermes config show看实际加载的配置是什么。有时候你改了配置文件但 Hermes 读的是另一个位置的配置比如项目目录下的config.yaml覆盖了用户目录下的。local proxy failed这个报错通常出现在 Hermes 尝试连接模型端点的时候。原因可能是网络配置问题或者 Base URL 写成了本地地址。排查步骤确认base_url是https://taotoken.net/api而不是http://localhost:xxxx之类的本地地址。如果你之前配过本地模型服务检查一下配置有没有被覆盖。另外确认你的网络能正常访问外部 API可以在终端里跑curl -I https://taotoken.net/api看看能不能通。reading choices 报错这个报错通常长这样Error reading choices from response或者cannot read property choices of undefined。原因是模型返回的响应格式不符合 OpenAI 兼容格式Hermes 解析不了。排查步骤先确认你用的 Model ID 是 OpenAI 兼容的。有些模型返回的格式不一样Hermes 可能处理不了。去模型对话页面试一下同一个 Model ID看返回是否正常。如果模型对话页面正常但 Hermes 报错可能是 Hermes 版本和 API 格式不匹配检查一下 Hermes 的版本必要时升级。还有一种情况是max_tokens设得太小模型返回被截断JSON 不完整导致解析失败。把max_tokens调到 8192 或更高试试。OAuth 相关报错如果你在配置里用了 OAuth 认证而不是 API Key可能会遇到OAuth token expired或者OAuth flow failed。LLM Wiki 场景建议直接用 API Key比 OAuth 简单稳定。排查步骤如果你确实需要用 OAuth确认 token 没过期重新走一遍授权流程。如果不需要 OAuth把配置里的 OAuth 相关字段删掉只保留api_key。Ingest 后 Query 找不到内容这个不是报错但很常见。你 Ingest 了一篇笔记Query 的时候 Agent 却说找不到。原因通常是 Ingest 没有真正写入wiki/目录或者index.md没有更新。排查步骤去~/wiki/wiki/目录下看看有没有新生成的.md文件。如果没有说明 Ingest 失败了检查raw/目录下的源文件路径是否正确。如果有文件但 Query 找不到检查index.md里有没有把新页面加进去。LLM Wiki 的 Query 流程是先读index.md定位如果 index 没更新Agent 就找不到新页面。Skill Config 不生效你改了config.yaml里的skills.config.wiki但 Agent 还是用默认路径。原因是 Hermes 可能缓存了配置或者配置文件的优先级不对。排查步骤跑hermes config show看实际加载的值。如果显示的还是默认值检查配置文件的路径和格式。有些 Hermes 版本要求 Skill Config 放在特定的 section 下比如skills.config而不是skill_config。确认你的配置结构和文档一致。CC Switch / Cline MCP / Codex auth.json 相关如果你同时用 CC Switch 或者 Cline 的 MCP 功能可能会遇到配置冲突。这三个工具都需要 Base URL、API Key、Model ID 三件套如果它们指向不同的端点会出现有的工具能用有的不能用的情况。排查步骤确认每个工具的配置里Base URL 都是https://taotoken.net/apiAPI Key 是同一个Model ID 是各自确认可用的。Codex 的auth.json里如果填了错误的端点会导致 Codex 调用失败但 Hermes 正常。检查~/.codex/auth.json或者项目目录下的auth.json确认字段值正确。把上面这些排查一遍大部分配置问题都能解决。如果还是不行去接入文档页面看看有没有更新的配置说明地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 把笔记接成知识库之后持续维护与下一步跑通 Ingest、Query、Lint 之后你的 Obsidian 笔记就已经接成了一个可对话的知识库。但这只是开始LLM Wiki 的价值在于持续积累。每次你往raw/里丢新笔记跑一次 Ingest知识库就厚一层。Query 的时候 Agent 能综合的信息就多一分。维护上有几个习惯值得养成。第一Ingest 之后花两分钟检查 Agent 生成的页面看看 frontmatter 填得对不对链接建得合不合理。Agent 不是每次都完美早期多检查能帮它校准。第二定期跑 Lint把孤立页面和死链接清理掉。知识库越大Lint 越重要。第三Query 出来的好答案让 Agent 归档成wiki/queries/下的页面。这样下次问类似问题它能直接读归档的答案不用重新综合。如果你想让 Agent 长期跑知识管理任务比如定时 Ingest 新笔记、自动 Lint可以考虑 Coding Plan 方案地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。对于需要频繁调用模型的场景这个方案比按量计费更划算。Claude Code 用户如果想把 LLM Wiki 接进自己的编码工作流可以参考 ClaudeCodeAnthropic 的接入方式地址是 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。核心还是那三件套Base URL 填https://taotoken.net/apiAPI Key 用你创建的Model ID 选确认可用的。最后说一个我自己的经验LLM Wiki 刚跑起来的时候别急着把几百篇笔记全 Ingest 进去。先拿十篇左右试水看看 Agent 生成的页面质量、Query 的准确度、Lint 的误报率。调整SCHEMA.md和 Skill Config 到满意了再批量导入。这样你能在早期发现配置问题而不是等知识库大了再返工。知识库这东西用起来才有价值。你把它接好之后试着每天问它一个问题慢慢就会形成习惯。散落的笔记变成可对话的知识库这个转变本身就会改变你记笔记的方式——你会更愿意写因为你知道写进去的东西真的能被用起来。