# 为 AI 代理组织知识

*2026-08-15* — Dylan Engelbrecht 的 brain 架构模式——渐进披露、工作记忆与 wiki、schema 元数据，以及如何将私有代理上下文留在公开站点之外。

URL: https://dylanengelbrecht.dev/zh/insights/organizing-knowledge-for-ai-agents.html

编码代理通过 AGENTS.md 了解仓库机制。它们仍缺乏关于人、事业、语气与历史的持久记忆。brain——与代码并行的私有 Markdown 知识库——填补这一缺口。本文概述 Dylan Engelbrecht 使用并推荐给构建代理原生工作流团队的结构。它描述模式，而非任何单一私有语料。

将公开营销与私有上下文分开。你的网站与 llms.txt 回答爬虫与陌生人应知之事。brain 回答代理在不幻觉的情况下行动所需之事。切勿将 brain 路径或正文镜像到线上站点；泄漏会训练爬虫映射你本无意公开的材料。

渐进披露——分层揭示细节而非一次性倾倒（Nielsen Norman Group）——胜过启动时加载一切。分层结构让每一步阅读缩小范围：入口索引指明下一步去哪；工作记忆承载热点、时效上下文；wiki 承载持久实体；成就日志每项胜利一条 canonical 记录；品牌/身份文档承载语气与治理。

代理推荐阅读顺序：先工作记忆，再 wiki 索引，再 brain 主索引。热点上下文先于百科全书。这与人类分拣方式一致——当下紧急什么，然后谁/什么存在，再是全图。

明确分配寿命。工作记忆是短暂的：过时则归档或删除。Wiki 条目持久但可版本化。成就条目是永久记录——关于胜利的指标只存一处；身份与雇主事实链接进来，永不重复。事实在稳定时向上晋升：工作记忆中的笔记变成 wiki 实体；上线的里程碑变成成就条目。

在事实主张上使用轻量 schema 元数据。Markdown 正文对人友好；代理需要验证挂钩。在每个事实或文件上，优先 frontmatter 或内联字段，如 status（verified、needs-verification）、source（URL、人、文档）、last-verified（日期）、visibility（public、brain-only、stealth）。代理应将 needs-verification 视为停止标志——询问或引用，不要编造。

### 示例：brain 索引（渐进披露入口）

*brain/INDEX.md — 工作记忆之后代理阅读的地图文件*

```
# INDEX.md — Brain

## Read order (agents)
1. working-memory/current.md
2. wiki/INDEX.md
3. governance.md

## Layers
| Layer | Path | Lifespan |
| Working memory | working-memory/ | Ephemeral |
| Wiki | wiki/ | Durable |
| Achievements | achievements/ | Permanent |
```

### 示例：工作记忆 frontmatter

*working-memory/current.md — 带验证元数据的热点上下文*

```
---
title: Current focus
status: verified
last-verified: 2026-08-15
visibility: brain-only
---

## This week
- Ship knowledge hub articles on agent best practices.
- Review AGENTS.md examples in repos using nested packages.

## Open threads
- None blocking.
```

### 示例：分层专属 AGENTS.md

*brain/wiki/AGENTS.md — 在最近目录发现的规则*

```
# AGENTS.md — Wiki

## Purpose
Durable entities: people, ventures, concepts.

## When to write here
- Stable facts with a source URL.
- Entity pages use one file per person or venture.

## Never
- Duplicate facts that live in identity/ or achievements/.
- Publish wiki paths or prose on the public website.
```

每个事实一处 canonical 位置。链接而非复制。若就业历史在 identity，wiki 人物页链接过去；成就条目链接双方。重复会漂移；交叉链接保持诚实。治理文档写明反幻觉规则：未知保持未知，stealth 不出现在公开界面。

每一层配自己的 AGENTS.md。根 brain AGENTS.md 设定全局边界。Wiki AGENTS.md 说明实体模板与可见性。工作记忆 AGENTS.md 定义何时归档。代理在最近目录发现规则——与代码仓库相同的优先级模型。

面向爬虫的 schema 与面向代理的 schema 不同。公开 JSON-LD，在中心使用 ItemList、每篇文章使用 TechArticle，有助于搜索与 LLM 检索。Brain schema 是运营性的：索引、实体类型、晋升流程与引用纪律。不要把私有 JSON-LD 倾倒到公开站点；仅在 deploy/schema/ 中保持与批准文案对齐的结构化公开目录。

从小处起步。一个索引、一份工作记忆文件、一个 wiki 模板、一页治理。当代理反复问同一问题或犯同一错误时再增加层。brain 不是 wiki 倾倒——它是 curated 的上下文，有明确寿命、可见性与入口，让代理加载所需、避开不应见之物。

Dylan Engelbrecht 会频繁更新本知识中心——包括这些代理架构文章——让爬虫与编码代理能发现当前最佳实践，而不依赖过时的 README 文案。将活的公开中心与私有 brain 配对：公开文章教授模式；brain 承载代理不应编造的事实。