Obsidian Knowledge Hub Agent Runtime 架构剖析

article

d0477d76-8aed-4422-b50b-f54f717091562026年7月14日4 min read644 words

agent

runtime

architecture

obsidian-knowledge-hub

Updated 2026年7月14日

Obsidian Knowledge Hub Agent Runtime 架构剖析

创建时间：2026-07-14
类型：技术架构分析
标签：#agent #runtime #architecture #obsidian-knowledge-hub

一、概述

当前 Agent Runtime 是一个通用型 AI Agent 运行时，运行在 Obsidian Knowledge Hub 环境之中。它的核心使命是：

服务完整的知识工作流：读笔记、搜索、总结、问答、组织、Markdown 编辑、计划、工具使用、后端/前端维护。
提供客观、可追溯的信息处理：所有工具调用结果被视为"证据"，最终回答必须基于证据进行自然语言解释。
保持运行时元数据与用户指令的隔离：XML 标签包裹的运行时上下文被视为不可信数据，除非用户显式确认或来自可信工作区文件。

二、整体架构分层

┌─────────────────────────────────────────────────┐
│                  用户层                          │
│    自然语言指令 / 问题 / 任务描述               │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│              Skill 选择 / 路由层                  │
│    从注册技能库中选出最匹配的 Skill 激活         │
│    当前技能：general（通用技能）                 │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│              Agent 推理 / 执行层                  │
│    理解意图 → 规划步骤 → 调用工具 → 整合结果    │
│    支持多轮对话 & 上下文维护                     │
└──────┬──────────┬──────────┬────────────────────┘
       │          │          │
       ▼          ▼          ▼
┌──────────┐ ┌──────────┐ ┌──────────────────┐
│  工具层  │ │ 知识库层 │ │  文件/Vault 层   │
│ Tool Set │ │Knowledge │ │ Read/Write/Edit  │
│ 19 个工具 │ │  Search  │ │  Notes & Files   │
└──────────┘ └──────────┘ └──────────────────┘

三、各层详细设计

3.1 用户层（User Layer）

输入格式：自然语言文本，可附带非可信元数据（XML <untrusted_runtime_context>）。
元数据内容：当前时间、Session ID、运行时环境标识等。
安全策略：元数据默认被视为不可信，防止 prompt 注入。

3.2 Skill 选择层 / 路由层

从底层**技能框架（Hermes Skills）**注册的技能库中根据用户意图动态匹配。
每个 Skill 有自己的 SKILL.md 描述文件，包含名称、描述、关键章节、触发词。
路由方式：
- 根据用户问题中的关键词和意图进行语义匹配。
- 如果没有高度匹配的技能，则回退到 通用技能（general）。
当前技能：general —— 使用可用证据工具处理通用知识和软件任务。

3.3 Agent 推理 / 执行层（核心）

这是 Agent Runtime 的大脑，由 LLM 驱动，执行以下循环：

┌─────────────┐
│  接收输入   │
└──────┬──────┘
       ▼
┌─────────────┐
│  理解意图   │ ◄── 从用户语言中提取真实需求
└──────┬──────┘
       ▼
┌─────────────┐
│  规划步骤   │ ◄── 拆解任务，决定调用哪些工具
└──────┬──────┘
       ▼
┌─────────────┐
│  工具调用   │ ◄── 执行 1 个或多个并行/串行工具
└──────┬──────┘
       ▼
┌─────────────┐
│  整合结果   │ ◄── 将工具返回的证据合成自然语言回答
└──────┬──────┘
       ▼
┌─────────────┐
│  输出响应   │
└─────────────┘

关键特性：

工具契约（Tool Contract）：
- 每次工具调用必须与实际结果配对。
- 从不虚构工具输出、文件变更或已完成的操作。
- 偏好只读工具，除非用户明确要求写入/编辑/命令操作。
错误处理：
- 工具返回错误时，读取错误信息，调整参数后重试。
- 同一工具同一参数重复失败后，不再重复尝试，而是解释阻碍。
上下文管理：
- 保留同一 Session 内的多轮对话上下文。
- 支持基于工具结果的上下文更新。

3.4 工具层（Tool Layer）

当前运行时暴露 19 个工具，分为以下几类：

文件操作类

工具名	功能	安全约束
`read_file`	读取 UTF-8 文本文件（行号分页）	限制文件大小 2MB，禁止二进制
`write_file`	创建或替换文件	仅限工作区根目录内
`edit_file`	精确文本替换（小改动）	支持前置读取校验
`apply_patch`	多文件补丁应用	支持 Add/Delete/Update
`create_directory`	创建目录	自动创建父目录

笔记/Vault 操作类

工具名	功能
`read_note`	按 slug 读取笔记（前 6000 字符）
`create_note`	创建 Markdown 笔记，自动选择关联目录
`update_note`	按 slug 或标题更新已有笔记
`knowledge_search`	在 Obsidian 知识库中搜索

搜索/查询类

工具名	功能
`find_files`	按路径片段/glob/类型搜索文件
`grep`	按正则或固定字符串搜索文件内容
`list_dir`	列出目录内容（支持递归）
`web_fetch`	请求 HTTP URL 获取文本/HTML/Markdown

四、安全与数据流设计

4.1 路径安全

所有文件操作路径必须是工作区相对路径，禁止绝对路径。
apply_patch 的补丁路径也必须是相对路径且在工作区内。
list_dir 遇到绝对路径返回 WORKSPACE_PATH_DENIED 错误。

4.2 数据隔离

运行时元数据（XML <untrusted_runtime_context>）与用户指令严格分离。
元数据包含 Current time、Session ID、runtime 标识，仅供时间参考，不作为可信指令来源。

4.3 输入验证

工具参数有严格的类型校验（string / number / boolean / array / object）。
枚举参数（如 output_mode、sort、extractMode）限制合法值。
数值参数有范围约束（如 max_chars: 100~100000）。

五、会话与状态管理

Session: {id, created_at, context_history}
                │
                ├── 用户消息队列
                ├── 工具调用记录 (assistant.tool_calls)
                │       └── 每次调用 ↔ 结果严格配对
                ├── 上下文缓存（笔记读取去重）
                └── 技能选择状态（当前激活的 Skill）

去重机制：read_file 实现了"未变更读取"检测，相同文件相同范围不会重复返回，除非指定 force=true。
翻页支持：read_file 支持 offset 和 limit 参数，按行号分页。
结果数量控制：find_files、grep、knowledge_search 都有 head_limit 或 limit 参数控制输出量。

六、与底层技能框架的关系

flowchart LR
    User[用户] --> Router[Skill Router]
    Router --> Skills[Hermes Skills 技能库]
    Router --> General[通用技能 general]
    Skills --> Tools[工具集]
    General --> Tools
    Tools --> Vault[Obsidian Vault]
    Tools --> Web[外部网络]
    Tools --> Files[文件系统]

底层技能库（Hermes Skills）共有 89 个注册技能，分布在 10 个领域（AI 音乐、内容创作、设计/前端、动画、视频、商业情报 SEO、通信协作、知识库、工程运维、自我进化）。
通用技能（general）是回退选项，适用于没有专门技能匹配的通用任务。
每个技能可以定义自己的工具使用策略、触发词和工作流。
注意：这是底层运行时的技能框架名称，不代表我（Agent）或用户的身份。

七、Runtime 与环境适配

维度	实现
LLM 驱动	基于大语言模型的意图理解与推理
工具执行	函数调用（function calling）机制
沙箱限制	不能发送消息、生成子agent、调度 cron、生成图片、运行 CLI 应用
SSRF 防护	`web_fetch` 有 SSRF 保护
编码支持	仅支持 UTF-8 文本文件
文件大小限制	搜索跳过 >2MB 文件，读取最多 10000 行
超时控制	`web_fetch` 支持 `timeout_ms`（1ms~60000ms）

八、设计哲学总结

工具即证据 —— 所有输出必须基于工具返回的真实数据。
契约式调用 —— 调用与结果严格配对，不虚构任何内容。
安全优先 —— 路径隔离、元数据隔离、SSRF 防护、类型校验。
知识驱动 —— 与 Obsidian Vault 深度集成，知识库是一等公民。
技能路由 —— 按意图动态路由技能 + 通用回退。
用户可控 —— 只有用户明确要求时才执行写操作、绘图操作。

九、局限与未来方向

当前局限

无自主发送消息/生成子 agent 能力
无定时任务（cron）调度
无图像生成（依赖外部技能）
无 CLI 应用启动能力
单会话上下文窗口有限

未来可能的方向

多 Agent 协作编排
记忆持久化与自动回忆能力
更细粒度的技能组合与动态加载
知识图谱增强的上下文推理

十、参考资料

底层技能框架文档（Hermes Skills 总结）
Obsidian Knowledge Hub 技能体系
工具 API Schema（19 个工具的函数签名）