Agent Native 架构设计

文件优于应用：重构知识架构

在个人知识管理（PKM）领域，我们长期依赖于特定的应用程序作为信息孤岛。这种模式下，数据与视图紧密耦合，限制了自动化和互操作性。Agent Native 架构的核心思想是颠覆这一传统，转向“文件优于应用”（File over App）范式。其本质是将文件系统，特别是 Markdown 文件集合，提升为持久化、结构化且独立于任何特定工具的主数据源。

这种架构解耦带来了直接的优势：你的知识库不再被锁定在某个应用的生态系统中。数据格式（Markdown + YAML）是开放的、人类可读的，也是机器可解析的。这为 AI Agent 直接与你的知识进行交互奠定了基础，使其能够读取、写入、甚至重构信息，而无需通过脆弱的、不断变化的应用程序 API。你不再是为应用整理笔记，而是在构建一个可供 Agent 使用的个人数据操作系统。

目录拓扑与文件命名

Agent 的导航能力直接取决于文件系统的结构。一个精心设计的目录拓扑和一致的文件命名规范，是 Agent 高效工作的关键。与其采用模糊的、基于日期的命名，不如采用面向任务和实体的 ID 系统。

考虑以下目录结构，它专为项目管理和知识沉淀而设计：

vault/
├── 00-inbox/
│   └── external-input-202310261030.md
├── 10-backlog/
│   └── P-001_refactor-auth-module.md
│   └── P-002_implement-new-api-endpoint.md
├── 20-cycles/
│   └── C-23.42_q4-performance-sprint/
│       ├── S-001_p-001-task-breakdown.md
│       ├── S-002_p-002-spike.md
│       └── 2023-W42-retrospective.md
├── 30-knowledge/
│   └── K-015_system-architecture-overview.md
│   └── K-016_api-rate-limiting-patterns.md
└── 99-archive/
    └── P-000_legacy-project-notes.md

这个结构清晰地划分了状态：inbox 用于未经处理的输入，backlog 存放待办项目，cycles 代表正在进行的工作，knowledge 是沉淀的知识，而 archive 则是归档。文件名前缀（如 P-、C-、S-、K-）充当了类型标识符，使 Agent 能轻易地通过文件名模式匹配来识别实体类型。这种结构将文件系统从一个简单的存储层次，转变为一个隐含的状态机。

Frontmatter 作为 Agent API

如果说目录结构是骨架，那么结构化的元数据（YAML Frontmatter）就是神经网络。它将非结构化的 Markdown 文本，与一个 Agent 可以精确查询和操作的结构化“API”连接起来。每个文件都成为了一个自带 API 的对象。

看一个 Backlog 中项目文件的例子：

---
uid: P-001
type: project
status: pending
title: "Refactor Authentication Module"
owner: "@alice"
dependsOn: []
related: ["K-015"]
---

## Objective

The current authentication module is outdated and needs to be replaced with a modern JWT-based approach to improve security and scalability.

这个 Frontmatter 定义了一个清晰的契约。Agent 不需要解析整个文档来理解这个文件的状态。它可以直接读取 status 字段。它知道 uid 是 P-001，并且可以通过查询 dependsOn 或 related 字段来构建依赖关系图。当 Agent 完成任务时，它只需将 status 更新为 completed，并将文件移动到 99-archive 目录。这种原子化的操作是可靠和可预测的。

本地文件系统的上下文工程

上下文工程（Context Engineering）是将原始数据转化为 Agent 可用知识的过程。在 Agent Native 架构中，这个过程发生在你的本地文件系统上。你不再仅仅是写作，你是在设计和策划 Agent 将要消费的上下文。

当一个 Agent（例如，一个基于 CLI 的工具如 Claude Code）被激活时，它的初始上下文不应只是一个空泛的提示。你应该将关键的“架构”文件注入其会话中，例如：

00_SYSTEM_PROMPT.md: 定义 Agent 的核心指令、角色和行为准则。
01_FILE_STRUCTURE.md: 解释目录拓扑和文件命名规范。
02_FRONTMATTER_SCHEMA.md: 详细说明不同文件类型（project, task, knowledge）的 YAML 字段及其含义和允许的值。

通过这种方式，Agent 在开始任何任务之前，就已经被“训练”以理解你的个人知识操作系统的规则。当你要求它“规划下一个周期”时，它知道需要扫描 10-backlog 目录，检查 status: pending 的项目，并根据 dependsOn 关系进行排序，最终在 20-cycles 目录下生成一个新的周期计划文件。

你的角色从一个内容的创作者，转变为一个 agentic 工作流的架构师。你设计的不是单个文件，而是整个系统的涌现行为。

这种方法将你的个人知识库从一个被动的笔记集合，转变为一个主动的、可编程的平台。它为实现真正的自动化知识治理铺平了道路，在这里，Agent 不仅仅是信息的检索者，更是知识生命周期的积极参与者和维护者。

Quiz Questions 1/5

在个人知识管理中，“Agent Native”架构最核心的思想是什么？

Quiz Questions 2/5

在 Agent Native 架构中，精心设计的目录结构和文件命名规范（例如，使用 P-001 这样的ID）的主要目的是什么？

Agent Native 知识管理与商业工程化