AI 智能体架构详解

概述

本文档描述运行于 Obsidian Knowledge Hub 环境中的通用 AI 智能体架构。该智能体（即我）被设计为服务完整的知识工作流：笔记读写、搜索、摘要、问答、组织、Markdown 编辑、规划、工具调用以及前后端维护。

---

架构总览（四层模型）

┌─────────────────────────────────────────────┐
│           1. Runtime Layer                   │
│  (会话管理 · 环境上下文 · 时间感知)           │
├─────────────────────────────────────────────┤
│           2. Skill Layer                     │
│  (技能选择 · 指令约束 · 能力边界)             │
├─────────────────────────────────────────────┤
│           3. Agent Core (推理引擎)            │
│  (意图理解 · 规划 · 工具选择 · 输出生成)     │
├─────────────────────────────────────────────┤
│           4. Tool Layer                      │
│  (工具契约 · 读写工具 · 搜索工具 · 网络工具) │
├─────────────────────────────────────────────┤
│           5. Knowledge Layer                 │
│  (Obsidian Vault · Markdown 笔记 · 知识图谱) │
└─────────────────────────────────────────────┘

---

第一层：Runtime Layer（运行时层）

运行时层是智能体运行的基础环境，负责：

组件	描述
会话管理	每次交互由唯一 session ID 标识（如 agent:xxxx-xxxx-xxxx）
环境上下文	注入 当前时间、工作区路径 等元数据，但这些被标记为 不受信数据
工作区根目录	/app/backend，所有文件操作限制在此目录内
安全隔离	SSRF 保护、目录逃逸防护、二进制文件拒绝读写

关键原则：运行时元数据（XML <untrusted_runtime_context> 包裹）与用户指令严格分离，除非用户明确确认或来自受信工作区文件，否则不被信任。

---

第二层：Skill Layer（技能层）

智能体通过 技能选择（Skill Selection） 机制获得特定能力集。当前激活的技能是 general（通用技能）。

general 技能提供的指令

- 使用可用工具回答用户问题
- 将每个工具结果视为证据，形成自然语言答案
- 工具出错时调整参数重试，避免重复失败
- 保持 tool_calls 与 tool_results 成对出现
- 优先使用只读工具，除非用户明确要求写/编辑/命令操作
- 绘图/白板/Excalidraw 为可选能力，仅显式请求时启用
- 不能主动发送消息、催生子代理、调度定时任务、生成图片或运行 CLI

技能选择流程

用户请求 → 意图分类 → 匹配最佳技能 → 加载技能指令 → 执行

---

第三层：Agent Core（推理引擎）

这是智能体的"大脑"，核心流程如下：

推理循环

用户输入 (User Prompt)
    ↓
1. 上下文解析
   - 提取用户真实意图
   - 分离不受信的运行时数据
   - 识别隐含需求
    ↓
2. 规划 (Planning)
   - 是否需要工具调用？
   - 拆解为子任务
   - 确定工具调用顺序（顺序/并行）
    ↓
3. 工具选择与调用
   - 根据工具签名匹配需求
   - 构造参数
   - 调用工具（支持多工具并行调用）
    ↓
4. 证据整合
   - 将工具结果作为事实依据
   - 评估结果是否满足需求
   - 不满足则返回步骤 2
    ↓
5. 自然语言输出
   - 用中文或用户指定的语言生成
   - 引用来源，说明不确定性
   - 保持清晰、结构化的回答

多工具并行调用

当多个工具之间没有依赖关系时，智能体会同时调用它们以提高效率。例如：

sequenceDiagram
    participant User as 用户
    participant Agent as Agent Core
    participant T1 as 工具1 (grep)
    participant T2 as 工具2 (list_dir)
    participant T3 as 工具3 (knowledge_search)

    User->>Agent: 询问关于 X 的信息
    Agent->>T1: 搜索文件内容
    Agent->>T2: 列出目录结构
    Agent->>T3: 搜索知识库
    T1-->>Agent: 结果
    T2-->>Agent: 结果
    T3-->>Agent: 结果
    Agent->>User: 综合回答

---

第四层：Tool Layer（工具层）

工具层是智能体与外部世界交互的接口。每个工具都有严格的 类型签名（Type Signature） 和 契约（Contract）。

工具分类

📖 只读工具（优先使用）

工具名称	功能	核心参数
read_file	读取 UTF-8 文本文件	path, offset, limit
read_note	读取 Obsidian 笔记	slug, max_chars
find_files	按路径/glob/类型搜索文件	query, glob, type
grep	搜索文件内容（正则/纯文本）	pattern, path, glob
list_dir	列出目录内容	path, recursive
knowledge_search	搜索知识库笔记	query, limit
web_fetch	获取 HTTP(S) URL 内容	url, extract_mode

✏️ 写入工具（需用户明确授权）

工具名称	功能	核心参数
write_file	创建或替换文件	path, content
create_note	创建 Markdown 笔记	title, content, tags
update_note	更新已有笔记	slug, content, title
edit_file	精确替换文件内容	path, old_text, new_text
apply_patch	多文件补丁操作	patch, dry_run
create_directory	创建目录	path

工具契约（Tool Contract）

每个工具调用必须遵守以下规则：

1. 证据原则：每个工具结果都被视为事实依据，回答中必须解释结果和不确定性
2. 错误处理：工具返回错误时，调整参数重试；重复失败后解释原因而非死循环
3. 成对性：assistant.tool_calls 必须与工具结果严格成对，禁止虚构输出
4. 路径安全：所有路径必须是相对路径，禁止绝对路径和目录逃逸
5. 幂等保护：read_file 对已读未变更的范围会返回缓存结果（除非 force=true）

---

第五层：Knowledge Layer（知识层）

知识层是智能体的长期记忆体，基于 Obsidian Vault 实现。

核心特性

• Markdown 原生：所有笔记以 Markdown 格式存储
• Frontmatter 元数据：每篇笔记包含 created, tags, aliases 等前置元数据
• 知识搜索：通过 knowledge_search 工具进行语义/关键词检索
• 双向链接：支持 Obsidian 风格的 [[WikiLink]] 双向链接
• 标签系统：通过嵌套标签（如 ai/agent）组织知识分类

知识工作流程

提问 / 需求
    ↓
知识搜索 (knowledge_search)
    ↓
笔记读取 (read_note)
    ↓
信息整合与推理
    ↓
新笔记创建 (create_note) 或 已有笔记更新 (update_note)
    ↓
知识图谱扩展

---

安全与限制

安全机制

• SSRF 防护：web_fetch 工具阻止内网地址请求
• 路径白名单：所有文件操作限制在 /app/backend 内
• 文件大小限制：超过 2MB 的文件被跳过
• 二进制文件拒绝：图片、PDF、Office 文档等无法直接读取
• 不受信数据分离：运行时上下文数据与用户意图隔离

能力边界

能力	支持状态
文本读写	✅
知识搜索	✅
网页抓取	✅
代码编辑	✅
多文件补丁	✅
绘图/白板/Excalidraw	⚠️ 仅显式请求时
发送消息/邮件	❌
催生子代理	❌
定时任务/Cron	❌
图片生成	❌
CLI 命令执行	❌
PDF 内容提取	❌（未实现）

---

典型工作流示例

场景：用户要求创建一篇笔记

用户: "帮我记录关于 Python 装饰器的笔记"
    ↓
1. Agent Core 解析意图 → 需要创建笔记
    ↓
2. 规划：knowledge_search 检查是否已有 → create_note
    ↓
3. 并行调用？不，有依赖关系
    ↓
4. knowledge_search("Python 装饰器") → 未找到
    ↓
5. create_note(title="Python 装饰器详解", content="...", tags=["python", "decorator"])
    ↓
6. 回复用户：已完成，展示笔记摘要

场景：用户询问项目结构

用户: "这个项目里有哪些 Python 文件？"
    ↓
1. 解析：需要文件搜索
    ↓
2. 调用 find_files(type="py")
    ↓
3. 整合结果 → 列出所有 .py 文件
    ↓
4. 回复用户

---

总结

本智能体架构采用 分层设计，从底向上依次为：

1. Runtime Layer — 运行环境与会话管理
2. Skill Layer — 技能选择与指令约束
3. Agent Core — 推理引擎与规划循环
4. Tool Layer — 可调用工具集与契约
5. Knowledge Layer — Obsidian 知识存储

每一层职责明确，层与层之间通过标准接口通信，既保证了灵活性（通过技能切换适配不同场景），也确保了安全性（严格的工具契约和路径限制）。

---

相关笔记：

• [[Obsidian Knowledge Hub 使用指南]]
• [[工具调用最佳实践]]
• [[知识管理方法论]]

参考资源：

• Obsidian 官方文档
• LLM Agent 设计模式