关键词：Agent 知识工程、持久记忆、反思沉淀、分层加载、知识分类体系

本文提出了一套完整的 Agent 知识工程实践体系，其核心目标是让 Coding Agent 能够像人类一样，在协作中持续学习、记忆和成长，而非依赖单次对话的 Prompt Engineering。

Agent知识工程实践：构建持久记忆体系，让Coding Agent像人一样学习成长

Agent 知识工程实践：让 Coding Agent 像人一样学习、记忆和成长

开源项目 agent-knowledge-framework 是一个用于管理 AI coding agent 团队知识的框架。它通过分层结构（通用知识 + 角色私有知识）和分类体系（experience / skill / principle / insight），让多个 agent 能高效地积累、检索和复用工程经验。

知识获取：Agent 通过三种认知方式主动学习。复盘旧知——完成任务后主动反思，沉淀经验；对标他方——直接阅读博客、PR、架构文档，在项目语境下提炼可落地的原则；沙盒演练——通过低成本实验探索未知工具，在与环境交互中获取反馈。知识的具体内容由 Agent 自己总结，人的角色是追问“为什么”和提醒“记下来”。
知识存储：构建多层持久记忆体系。AGENTS.md 承载项目级轻量规则；独立知识库按五分法（experience/skill/principle/insight/question）和角色维度组织，形成结构化知识网络；同时接入团队既有文档和代码仓库，让 Agent 融入团队信息流。
知识维护：通过反馈闭环让 Agent 在犯错时自行改进知识；元认知规范（knowledge-sedimentation.md）指导沉淀流程；comment 机制建立知识间的双向链接；dreaming 巡检自动发现索引缺口和过时内容。
知识使用：采用分层加载策略。AGENTS.md 常驻 context 作为恢复锚点，通过索引摘要按需加载 skill/principle/insight，experience 作为证据在需要时升级加载。triggers 机制让知识主动找到 Agent，知识间的连接形成联想网络，实现精准的 Context Engineering。

整套体系基于纯文本文件，不依赖复杂基础设施，强调在真实协作中让知识体系自然生长，最终让 Agent“越用越懂项目”。

本文目录

引入：Agent 不是菜，他只是不知道
知识从哪来？——让 agent 像人一样学习
- 复盘旧知：反思沉淀，将经历转化为存量经验
- 对标他方：学习借鉴，从他人的实践中寻找参考
- 沙盒演练：模拟试错，通过“低成本实验”获取行为反馈
知识怎么存？——Persistent Memory
- 存在哪？——多种载体
- 独立知识库的内部结构：两个维度
怎么维护？——让知识保持活性
- 反馈闭环——已有的知识没起作用怎么办
- 元认知——沉淀知识本身也是一种知识
- Comment——欢迎来到 Web 2.0
- Dreaming——仿生 agent 会梦见电子 H100 吗
Agent 怎么读？——Context Engineering
- 分层加载：常驻 vs 按需
- Trigger：让知识主动找到 agent
- 联想：从一条知识到一片知识
- Context 压缩后的恢复
结语
附录 A：AGENTS.md 实例
附录 B：经验沉淀规范（knowledge-sedimentation.md）

引入：Agent 不是菜，他只是不知道

很多时候 agent 产出的东西和预期有偏差、不可用，总需要反复提修改意见。

新人入职，即使经验丰富、技能多面，即使新工作的文档和代码组织得非常完善，实际上手时也需要一段时间 ramping up——上手摸索，和同事对齐。这个过程本质上是将同事的知识——包括那些不可见的知识——蒸馏给他。agent 和新人一样，能力不缺，缺的是关于你的项目、你的团队、你的偏好的那些上下文。给够了，就能上手。

很多人把 agent 用不好归结为“prompt 没写好”，然后去研究 prompt engineering ——怎么措辞、怎么分步、怎么给 few-shot example。这些有用，但解决的是“怎么把一个问题问清楚”，而不是“agent 缺什么知识”。你可以用最完美的 prompt 让 agent 做一个跨层 API 重构，但如果他不知道项目四层架构各层的修改顺序、不知道 Python wrapper 有三处间接调用、不知道改完签名还要同步 .pyi 文件——还是会做错。prompt engineering 优化的是单次对话的表达效率，knowledge engineering 解决的是 agent 的认知基础。前者是战术，后者是战略。

agent 的可发挥上限很大程度上取决于你给他的知识。

知识从哪来？——让 agent 像人一样学习

不妨先问问人是怎么学会新东西的。

面对一个新的库或工具，会直接进入文档把所有 API 背下来吗？似乎不是，背下来了也不敢说掌握了。而现在许多人对 skill 的使用就是这样——给 agent install 一个 skill，他只是知道了这些 API。但怎么用、有什么坑、什么情况用什么、注意什么，这些和场景息息相关的东西，不可能全由一个官方 skill 包罗万象。因此需要发挥 agent 能够和环境交互、获得反馈的优势，让他更主动地学习，就像人一样。重点是让 agent 用人的认知方式去主动学习和吸收知识。

复盘旧知：反思沉淀，将经历转化为存量经验

2. 知识怎么来？——从交互中主动学习

知识不会凭空产生。它源于 Agent 在真实协作场景中的实践、反思与探索。人的核心作用不是直接灌输知识，而是设计机制，引导 Agent 主动学习、消化并沉淀。

复盘反思：从每次会话中提炼经验

这是最基本的学习方式。每次人机交互——用户的指令、Agent 的决策、用户的反馈——都蕴含着宝贵的上下文知识。这些知识尤为重要，因为它们直接关联到 Agent 在真实场景中遇到的具体问题。

完成任务后，不要立即结束会话，而是引导 Agent 进行复盘：
* 直接沉淀：要求 Agent “将本次任务中你认为重要的信息或决策依据，记录到 AGENTS.md 中”。
* 引导反思：通过提问帮助 Agent 查漏补缺。例如，“你刚才为什么没有采用 X 方案？” Agent 会解释其当时的认知局限，从而暴露出缺失的信息，你可以借此将这部分知识补充完整。
* 纠正改进：当 Agent 犯错时，要求其“反思一下，如何更新 AGENTS.md 以避免未来出现同类问题”。这促使 Agent 将具体教训转化为可执行的规则。

对标借鉴：从外部实践中获取参考

面对难题时，成熟的开发者会寻找外部参考：一篇切中要害的技术博客、一个相似功能的 Pull Request、一个优秀项目的架构设计。在 Agent 协作中，应延续这一习惯，但改变方式。

与其由你搜索答案后直接将结论“喂”给 Agent，不如让 Agent 自己去阅读原始材料并消化。自己理解的知识，比被告知的结论用起来更扎实。

1. 参考代码与项目结构
当需要对不熟悉的代码库添加功能或做出技术选型时，直接让 Agent 去研究相关实践。

“参考 https://github.com/apache/opendal/ 项目中使用 PyO3 组织 Python binding 的结构，来规划我们项目的绑定层。”

2. 理解设计哲学与理念
对于设计理念类文章，让 Agent 结合具体项目场景进行解读和提炼，比单纯知晓概念更有价值。

阅读这篇文章：https://ferd.ca/the-zen-of-erlang.html。
结合我们项目中批处理作业的错误处理现状，思考 “Let it crash” 理念哪些可以借鉴、哪些不适用，并沉淀为一条适用于本项目的设计原则。

关键在于让 Agent 在你的项目语境下重新理解抽象概念，明确其适用场景、边界条件以及与现有体系的衔接方式。这种“带着问题去学习”产出的原则，更具指导意义。

沙盒演练：在安全环境中通过实验学习

面对一个新工具（尤其是内部工具或缺乏文档的工具），最有效的学习方式不是通读 API，而是在预期场景中进行实验。Agent 同样可以如此。

例如，团队有一个内部集群调度工具 jobMan，没有公开文档。与其人工编写使用手册，不如设计一个沙盒任务，让 Agent 通过交互来探索：

我们的环境中有一个内部集群调度工具 jobMan。请结合其 help 输出和内部团队提供的简要文档，尝试使用它提交一系列不会实际修改环境的测试任务，包括但不限于：
1. 长时间运行的任务
2. 运行时长不一的任务
3. 使用不同资源配额的任务
4. 确定会因段错误、内存溢出、非零退出码而失败的任务
5. 在特定参数下会失败的任务
6. 有概率失败但重试后可成功的任务

提交这些用例后，请使用 jobMan 命令行工具监控任务状态、查看日志、进行重试等操作，并尝试让失败的任务最终成功。请将整个探索过程中的所有操作、观察和结论总结下来，沉淀为一份关于如何使用 jobMan 的 Skill。

沙盒演练的核心优势在于，Agent 能够通过实际执行命令、观察输出、并根据反馈调整行为，从而通过与环境的交互来弥补训练数据的空白。对于内部工具，一次精心设计的沙盒演练所产出的知识，往往比阅读十遍静态文档更实用。

贯穿始终的关键认知是：知识的具体内容应由 Agent 自己生成，而非由人代劳。 无论是复盘、对标还是沙盒演练，产出的知识都是 Agent 在具体场景中消化、理解并总结的。Agent 比人更清楚自己需要记住什么，因为它是这些知识的最终使用者。人的角色是引导者：在 Agent 犯错时提问“为什么”，在它做对时要求“记下来”，而不是替它手写规则。

3. 知识怎么存？——构建持久记忆体系

知识产生了，但 Agent 的上下文窗口是有限的。会话结束，所学大多会消失；长会话中，早期信息也会被压缩或遗忘。如果知识仅存在于临时对话中，Agent 就如同一个永远在“新手期”的成员——每次任务都近乎从零开始。

因此，知识必须被持久化。然而，“存储”只是第一步，更关键的是如何组织——存储方式决定了知识能否被高效检索、复用，以及是否会随时间“腐烂”成无效信息。

存在哪？——多元化的知识载体

在实践中，知识自然地分布在不同的载体上，各司其职：

`AGENTS.md` / `CLAUDE.md` —— 项目专属的轻量级指令集

这是最基础的实践。在项目仓库根目录放置一个 AGENTS.md（或 CLAUDE.md），Agent 启动时会自动加载其内容。其中应记载“关于本项目，Agent 必须知道的事项”：如协作规范、安全红线、关键目录结构等。
其特点是始终保持在上下文窗口内，因此必须极度精简——只收录那些“一旦违反就可能造成不可逆损失”的核心规则。例如：“所有写操作必须在 worktree/ 目录中进行”、“Agent 不得自行合并 Pull Request”。

独立知识库 —— Agent 团队的共享“大脑”

AGENTS.md 与特定项目绑定，但大量知识是跨项目通用的（例如 Git 工作流规范、代码重构步骤、通用工具的使用技巧）。这类知识需要一个独立于任何具体项目的中枢来存放、共享和演进。为此，可以建立一个专门的 agent-knowledge-base 仓库。
使用方式：在知识库路径下启动 Coding Agent，在任务开始时告知其本次可能需要的知识领域，然后指引它切换到实际的工作目录（如 project-a/）去执行任务。知识库是 Agent 的“家”和“智库”，工作目录是“工地”——从家中携带必要的知识去工地干活，完工后将新的经验带回家里沉淀。
其特点是结构化、可检索、可持续演进——它是一个有明确分类和层次的知识体系，而不仅仅是扁平化的笔记。

既有载体 —— 项目本身的文档与代码

Agent 产出的代码、撰写的文档、提交的 Pull Request 描述，其本身就是知识的载体。一个结构清晰、注释良好的代码库，Agent 通过阅读代码就能理解项目惯例；一份详尽的 PR 描述，就是后续类似任务的最佳参考。
这一层无需额外维护，但需要有意识地让产出物自身承载知识：要求 PR 描述清晰说明“为什么这么改”而不仅是“改了哪里”；在反直觉的实现处添加解释性注释。独立知识库可以充当“索引”或“地图”，当 Agent 需要理解某个决策背景时，能指引它“去查阅某份架构文档”或“参考某个历史 PR”，而非将所有内容都复制到知识库中。

人机协作网络 —— 接入团队现有知识体系

[[IMAGE_2]]
最理想的状态是，Agent 的记忆体系能够无缝接入团队已有的知识网络（如内部 Wiki、文档站点、设计决策记录）。这要求知识库具备良好的结构和接口，未来可通过工具链集成，让 Agent 不仅能读写自己的记忆，还能在授权范围内查询团队的集体智慧。

上文讨论了代码仓库和项目文档，但团队的知识远不止于此。Notion 上的设计文档、Slack/飞书中的技术讨论与 On-Call 实战、Jira 里的需求背景、内部 Wiki 上的 On-Call 手册——这些才是团队日常沉淀知识的核心场所。如果智能体只能访问代码仓库，就如同一个只读过课本、却从未参与过课堂讨论的学生。

“读”是基础——让智能体能够搜索 Notion 页面、查阅即时通讯工具中被标记的技术决策、读取问题跟踪系统中的上下文。这样，当它遇到问题时，就能自行翻阅团队的讨论记录来寻找答案。

但更具价值的是“写”。智能体不应仅仅在终端中输出一堆文字然后等待人工查看。它可以将设计方案写入 Notion 页面供团队成员评审，在即时通讯工具中汇报进展和遇到的问题，在拉取请求描述中用团队习惯的格式清晰地阐述变更背景。当智能体使用团队熟悉的渠道和格式来呈现工作时，其产出才能真正融入团队的信息流，而不是被锁在一个孤立的对话窗口中。

独立知识库的内部结构：两个维度

在四种知识载体中，AGENTS.md 足够简单无需额外结构，代码和文档的组织由项目本身决定，团队知识网络则由团队自身的工具链决定。真正需要设计的是独立知识库的内部组织方式。我们可以用两个正交的维度来划分：横向按类型，纵向按受众。

横向分类：五分法

知识的类型可以用以下五种来覆盖：

这些类型之间存在清晰的生成关系：

question（待验证的疑问） ↓（某次实践验证） experience（原始素材） ↓（提炼） skill / principle / insight（可复用知识）

experience 是基础。每当智能体完成一项工作——修复了 bug、跑通了流程、踩了坑——都应先记录为 experience，然后从中提炼：
* 能抽出操作流程吗？ → skill
* 能抽出行为准则吗？ → principle
* 能归纳出跨场景的规律吗？ → insight

只写 experience 不提炼，那只是日记。只写 skill 不留 experience，后人将无法理解“为什么有这条规则”。两步都要做。

为什么是五种而不是更多？每增加一种类型，就多一个判断分支。分类带来的认知负担，是知识沉淀流程能否持续运转的关键瓶颈。

为什么没有 Fact（事实）？ 直觉上，“默认 runner 用的是某个镜像”、“某个 secret 只在特定环境可用”、“某些 workflow 只在特定 branch / path 条件下触发”这类系统状态描述，似乎不属于现有五种类型中的任何一种——它们不是事件、不是流程、不是准则、也不是规律。

但 fact 几乎总是从 experience 中发现的——智能体在查看某次运行时确认了默认 runner，在排查某个 job 失败时才知道 secret 或触发条件的限制，这些发现过程本身就是 experience。

更关键的问题是：fact 会过时，但没有自然的更新机制。 系统升级、配置变更后，fact 库里的信息就变成了误导。而 experience 天然带有时间戳，智能体查到旧记录时会自然地意识到“这是半年前的，可能需要验证一下”。单独维护 fact 列表，看起来方便，实际上是在制造一个无人维护就会腐烂的定时炸弹。

因此，我们不单独维护 fact。环境信息应放在项目文档或 AGENTS.md 里作为“环境描述”，其维护责任跟随项目；实践中发现的事实则自然沉淀为 experience，并保留其时间和上下文。

纵向分类：分角色

横向是类型维度，纵向则是受众维度：这条知识是谁需要的？

agent-knowledge-framework/ ├── base/ # 跨角色通用知识 │ ├── principles/ # 通用原则（凭证安全、git worktree 协作） │ ├── skills/ # 通用技能 │ └── insights/ # 通用洞察（跨层改动逐层 review） └── roles/ # 各角色目录 ├── cli-tool-dev/ # CLI/TUI 工具开发 │ ├── AGENTS.md # 角色描述 + 知识索引（始终加载） │ ├── skills/ # 如"textual TUI 开发模式" │ ├── principles/ # 角色专有原则 │ ├── insights/ # 角色专有洞察 │ ├── experience/ # 如"textual TUI 首次实践踩坑记录" │ └── questions.md # 待验证的疑问 ├── maintainer/ # 知识仓库维护 └── ... # 其他角色

判断标准不是“多个角色都有用就放 base”。例如，db3-dev 和 db3-ops 都会接触同一个数据库，但关注点完全不同：一个关注如何修改 schema，另一个关注如何验证数据一致性。

再比如，db3-ops 和 minio-ops 都会使用 MinIO 客户端 mc，看起来是“同一个工具的知识”。但 db3-ops 用 mc 做数据治理——mc find 探测前缀是否存在、mc mv 迁移待清理数据，关注对象和元数据的一致性；而 minio-ops 用 mc 做安全审计——mc admin trace 抓取删除/覆盖请求、按 access key 和 IP 归因，关注谁在什么时候做了什么破坏性操作。同一个 mc 命令，两个角色提炼出的 skill 完全不同，硬合并到 base 反而会丢失各自视角的针对性。

base 只应存放真正与角色视角无关的知识——例如 git worktree 协作规范、凭证安全原则、GitHub PR 工作流——无论从哪个角色的视角看，这些知识都是一样的。

需要强调的是：一个启动的智能体不一定只对应一个角色。 一次任务可能同时涉及数据库运维和 MDR 开发，可以同时加载多个角色的知识。角色不是智能体的身份，而是知识的组织单元——为智能体在读和写时提供更明确的指引：
* 读的指引很好理解：告诉智能体优先读取哪个分类下的经验和技能，避免在整个知识库里漫无目的地搜索。
* 写的指引更需要角色的预设：在沉淀经验时，角色告诉智能体从哪个视角去总结和提炼、需要特别注意什么。例如，同一次跨层 bug 修复，mdr-developer 的视角可能关注 FFI 层的类型映射陷阱，而 db3-ops 的视角则关注数据一致性的验证方法——提炼方向不同，产出的 skill 和 insight 也不同。

为什么按角色划分，，而不是按项目、时间或主题？因为角色天然解决了“加载什么”和“如何提炼”两个核心问题，无需额外的过滤或分类逻辑。按项目划分会将同一角色的知识打散（一个角色可能参与多个项目），按时间划分则无法提供有效的视角指引。

然而，角色的划分并非一成不变。初始分类可能带有一定的随意性——基于直觉划分几个角色，并开始填充知识。真正关键的是角色会随着知识库的自然增长而动态演化：

分裂：当一个角色积累了过多知识，且其中包含明显不同的关注主线时——例如，一个角色同时包含数据库Schema设计的知识和大量数据治理的操作经验——将其拆分为两个独立的角色会比硬塞在一起更清晰。
合并：当两个角色的知识高度重叠，维护两份独立的文档成为负担时，合并它们反而更利于知识的查找与维护。
互相学习：一个角色遇到的“坑”，另一个角色也可能遇到。在定期的巡检中，若发现跨角色间的相似经验，可以提示将其提炼为通用知识，或在另一个角色的文档中添加索引引用。
自我修订：每个角色的文档中都有一段角色描述，定义其关注点和擅长领域。随着经验积累，Agent会发现最初的描述可能不再准确——实际工作范围可能更宽或更窄——此时应及时更新描述，避免描述与现实脱节。

重构的时机无需刻意规划。当你发现一个角色的文档索引变得臃肿、在多个角色间犹豫某条知识该归何处、或某个角色长期没有新增知识时，这些就是需要调整的信号。角色划分的最终目标始终是让Agent更容易地查找和沉淀知识，当现有划分妨碍了这一目标，就应进行调整。

将两个维度正交组合，便构成了完整的知识坐标系：类型（五分法）× 受众（角色/通用知识库）。

如何维护？——让知识保持活性

知识存储仅仅是开始。缺乏维护的知识库将迅速退化为信息垃圾场——过时的经验会误导Agent，缺乏索引的技能永远不会被读取，孤立的洞见无法追溯到其源头。核心矛盾在于：知识会“腐烂”，但人类没有精力时刻监控。

反馈闭环——当现有知识未起作用时

知识被记录下来，并不意味着Agent就会自动应用。常见的情况是：规则明明写在文档里，Agent却依然犯错。此时不应简单地重复“去读一下文档”，而应追问为什么规则没有起作用，进而改进知识本身。

例如：关于使用worktree的规则早已写入文档，但Agent仍在主分支上直接修改代码。询问“你为何没有使用worktree？”后，Agent反思发现原因是“认为只是初步探索，不需要worktree”——然而探索很快演变为正式开发，此时再将改动迁移到worktree就非常麻烦。问题不在于不知道规则，而在于规则未覆盖到这个边界场景。于是，Agent自行在文档中补充了一条：“即使是‘初步探索’，也应在worktree中进行”。

后来，同一条规则再次失效——在长会话中，上下文被压缩，Agent忘记了worktree规则。这次原因并非规则本身不佳，而是知识加载机制存在缺陷。于是又增加了一条：“当对流程细节不确定时，先重新阅读一遍相关文档”。

这就是反馈闭环：犯错 → 追问原因 → 发现是知识缺失/不够具体/加载时机不当 → Agent自行改进知识。具体内容始终由Agent自己撰写，人类的角色是在犯错时提问“为什么”，在做对时提醒“记下来”。上层的组织结构——如五分法、按角色分类——由人类根据知识积累到一定量后的判断来设计，但结构内部填充的具体内容，始终由Agent产出。

元认知——关于“如何沉淀知识”的知识

“如何沉淀知识”这件事本身，也需要被沉淀和规范。

最初，Agent沉淀经验的方式是随手在文档中添加几行文字——没有分类、没有结构、未经提炼。几天后，文档就变成了杂乱的备忘录，连Agent自己都难以找到之前记录的内容。

因此，制定了knowledge-sedimentation.md——一份沉淀规范，指导Agent在完成重要工作后主动问自己四个问题（是否踩坑？→ 记录经验；能否提炼出可复用的操作流程或模式？→ 提炼技能；是否有抽象准则？→ 总结原则；能否跨场景泛化？→ 形成洞见），并判断知识应归属于特定角色还是通用知识库，同时要求更新现有文档而非不断新建文件。

这份规范本身也经历了迭代。最初只包含“从经验到技能/原则”的提炼路径，后来加入了“洞见”（从多次经验中归纳规律）和“问题”（已知的未知）。每次发现沉淀流程存在缺陷，就更新规范——这就是元认知：将关于知识管理的认知也纳入知识体系本身。

具体而言，元认知体现在三个层面：

如何沉淀（knowledge-sedimentation.md）：包括如何分类、如何提炼、如何判断归属。
何时沉淀：沉淀不应等待人类提醒。规范中明确列出了触发沉淀的场景——例如，在PR审查中修复问题（尤其是经过多轮迭代的）、修复跨层级Bug、首次成功运行某个流程、踩了非显而易见的“坑”。这些场景本身就是一种认知：意识到“何时该停下来反思”比“如何反思”更难习得。
反思的意识：Agent天生缺乏“应该沉淀一下”的冲动，这种意识必须被显式地写入规范。规范要求Agent在上述场景完成后主动自问四个问题，而非等待用户指令“总结一下”——从而将反思从被动响应转变为主动习惯。在工具层面，虽然某些框架提供了在特定事件（如会话结束时）触发脚本的钩子机制，理论上可将沉淀检查自动化，但为了保持方法的通用性，不依赖特定工具，目前仍选择将触发条件明确写入提示词或规范中。

批注机制——建立知识间的连接

经验是某个时间点的快照，但知识并非静态。一条经验可能因系统升级而失效，可能被另一个角色从不同角度重新解读，也可能在后续被提炼为一条洞见。

如果经验之间缺乏连接，知识库就会变成信息孤岛。为此，引入了一个轻量级的批注机制——在经验文件末尾添加## 批注部分，记录后续发生的关联事件：

## 批注

### memory-cleaner (2026-03-04)

从本次与 db3-ops 的 SIGKILL 经验中提炼出通用洞见：
`base/insights/sigkill-skips-cleanup.md`

### db3-developer (2026-02-26)

本条经验在系统升级后部分失效，新行为参见：
`experience/2026-02-26-s3-last-modified-column.md`

批注在经验之间、以及经验与洞见/原则之间建立了双向链接。阅读经验时，能看到“这条经验后来发生了什么”；阅读洞见时，能追溯到“这条认知是从哪些经验中归纳出来的”。

保持边界同样重要——批注是注释和索引，而非正文。如果一条批注开始包含深度分析，它就应该成为独立的洞见或技能文档，批注中仅保留链接。

巡检机制——知识的定期整理与维护

人在睡眠中会整理白天的记忆——Agent也可以拥有类似的机制。为此，设立了一个维护者角色，定期对知识库进行自动化巡检：

机械层（Linter）——自动执行：

巡检（Linting）与复盘（Dreaming）

巡检（Linting）旨在自动化检查知识库的结构与内容健康度，主要分为语法层和语义层。

语法层（linting）—— 自动修复或标记：
- 坏链接扫描：检查 Markdown 文件中引用的内部路径或文件是否有效。
- 索引缺口：识别 skill/ 或 insight/ 目录下已存在的文件，是否在 AGENTS.md 的索引中缺失对应条目。
- 近似重复检测：对 skill/ 或 insight/ 文件的标题和描述进行 token Jaccard 相似度计算，对相似度过高的条目进行候选标记。
语义层（synthesis）—— 输出候选，人工决策：
- 发现 experience 文件通过 source: 字段指向了某个 insight，但该 insight 中并未反向链接回此 experience。
- 识别多条 experience 描述了相似的现象或问题，可能值得归纳总结为一个新的 insight。
- 发现 experience 中提到的软件版本号、文件路径或命令已明显过时。

一个关键的设计决策是：让 linter 自动执行检查和修复，而 synthesis 层仅输出候选清单供人工判断。让 Agent 自主进行内容提炼和合并是危险的，它可能误判两条看似相似但实际不同的经验，或者抽象掉有价值的上下文细节。因此，复盘（dreaming）的核心价值在于发现问题，而不是自动解决问题。

除了日常巡检，复盘机制还有一个自然的应用场景：回顾白天新增的 experience，并运行相关的实验（lab）。白天工作中沉淀的 experience 往往只记录了“发生了什么”和“如何修复”，但问题的边界条件可能未被充分探索。夜间，Agent 可以扫描当天新增的 experience，从中提取值得验证的假设，并设计最小化的实验进行测试——这类似于人类在经历事件后，大脑在夜间通过梦境模拟各种可能性。由此产出的 lab 记录和修正后的 skill，可在第二天由人工进行审查。

Agent 如何读取知识？—— 上下文工程（Context Engineering）

知识被妥善存储和维护后，最后一个关键问题是：Agent 如何在正确的时机读取到正确的知识。这属于上下文工程（Context Engineering）的范畴——其核心不是将所有知识都塞进上下文，而是让 Agent 能够按需加载最相关的部分。

为何不能全部加载？一方面受限于上下文窗口的长度，填满后便没有空间进行思考和工作。但更重要的原因是：不相关的知识会污染 Agent 的判断。例如，若上下文中包含一条“网络超时时应重试3次”的原则，Agent 在处理一个完全无关的本地文件解析错误时，也可能受其影响而添加不必要的重试逻辑。因此，知识并非越多越好——精确地提供当前任务所需的知识，其效果远优于一股脑地塞入所有信息。按需加载不仅是为了节省空间，精炼上下文本身也具有重要价值。

分层加载策略：常驻 vs. 按需

并非所有知识都同等重要。加载策略可分为三层：

常驻加载（每次任务都在上下文中）：
- AGENTS.md：团队协作规则、安全底线、以及整个知识库的加载入口。
- roles/<role>/AGENTS.md：特定角色的职责定义及其专属知识索引。
  这两份文件如同“工作记忆”，始终在线，决定了 Agent 遇到问题时应向何处寻找答案。
按需加载（通过索引匹配后读取）：
- skill / principle / insight：通过 AGENTS.md 中的索引摘要判断相关性后进行加载。
- experience：作为“证据、边界条件或反例”，在需要深入理解或验证时加载。
触发式加载（特定场景下自动提醒）：
- 当操作涉及凭证、权限或令牌时 → 自动提示先阅读 base/principles/credential-safety.md。
- 当执行任何写入操作（尤其在多 Agent 并行环境下） → 自动提示先阅读工作树（worktree）相关规范。

触发器（Trigger）：让知识主动找到 Agent

被动的索引检索是不够的——Agent 可能“不知道自己不知道什么”。但也不能将所有知识的触发条件都塞入常驻上下文，否则 AGENTS.md 会变得臃肿不堪，难以维护。

实践中采用两层过滤机制：

第一层：AGENTS.md 摘要（常驻、轻量）。摘要本身即兼任触发器——关键在于包含足够的关键词。例如，一条 experience 的索引摘要写为“ClickHouse 写入 MinIO 的 PutObject 重试/499 状态码调研”，当 Agent 遇到 499 状态码时，扫描摘要便能命中此记录。摘要无需额外的触发器字段，它本身就是最轻量级的第一道过滤器。
第二层：文档 Front Matter（按需、精确）。当 Agent 打开具体文档后，Front Matter 中的 triggers 字段可提供更精确的匹配：
“`yaml
—
triggers:
- “GitHub Actions”
- “workflow”
- “触发方式”
- “needs DAG”
- “timeout conclusion”
“`
这一层不占用常驻上下文，仅在 Agent 已打开文档时才会生效——用于确认“此文档确实与当前任务高度相关”，或在多个候选文档中进行精细筛选。

两层机制配合的效果是：摘要进行粗筛（轻量、常驻），Front Matter 进行精筛（精确、按需）。无需提前加载所有触发器，摘要已承担了首轮过滤的职责。

对于 experience 类知识，这种症状型触发器尤其有价值——错误信息、异常现象等具体线索，比抽象的主题描述更容易被精确命中，能使 Agent 直接跳转到历史踩坑记录，而非从头开始排查。

AGENTS.md 中定义的“触发型 skill”是更严格的版本，它被写成硬性规则，例如：“接触凭证/权限/令牌前必须先阅读 base/principles/credential-safety.md”。这不再是建议，而是强制性的前置检查清单。

联想（Association）：从单点知识到知识网络

单点命中往往不足以解决问题。在阅读一条 skill 后，可能还需要理解其背后的 principle，或回溯到产生这条 skill 的原始 experience。这就需要知识之间的连接：

纵向连接（提炼链）：experience → skill/principle/insight，通过 source 字段和文档内的“如需更多上下文，请参阅相关 experience”段落实现。
横向连接（评论网络）：不同 experience 之间的关联，通过文档内评论（comment）段落中的超链接实现。
索引连接：每条知识在 AGENTS.md 中的摘要自带丰富关键词，具有相似关键词的条目自然形成关联簇。

这些连接使得知识库从一个线性列表演变为一个网络——从任意入口进入，都能沿着连接找到相关的上下文信息。

上下文压缩后的恢复

在长会话中，上下文可能会被模型自动压缩（compaction），压缩后 AGENTS.md 和角色 AGENTS.md 的内容可能被摘要或移除。此时需要识别“遗忘了什么”的信号：

当出现以下情况时，可按上下文压缩处理：
* 不确定当前角色的知识索引中包含哪些内容。
* 不记得团队对于提交 PR、GitHub Actions 流程或文档发布的硬性要求。

恢复操作很简单：重新读取一遍 AGENTS.md 和 roles/<role>/AGENTS.md，通常能在30秒内使 Agent 回到正轨。这也正是为什么这两份文件必须保持精简——它们是上下文压缩后用于恢复的“锚点”，若内容过长，恢复成本将显著增加。

结语

回到最初的论点：Agent 并非能力不足，他只是缺乏相关知识。

本文介绍的五分法、分角色、评论机制等知识库结构，并非唯一的解决方案，只是在实践中迭代出的一个示例。你完全可以根据自身需求，采用不同的分类方式和组织逻辑。最关键的是迈出第一步：为 Agent 在工作中提供一个沉淀知识的地方。 即使最初只是在 AGENTS.md 中随手添加几行记录，也远比什么都不做要强上百倍。至于后续如何组织、分类、加载优化——这些都是知识积累到一定量后自然会面临的问题，届时再进行重构的成本也很低，因为你面对的只是一堆结构清晰的文本文件。

整套体系不依赖数据库、向量检索或复杂 pipeline——核心就是目录结构加 Markdown。Agent 用 grep 就能搜索，用文本编辑器就能维护。这种简单性是它能持续运转的关键，也意味着随时可以重构，迁移成本相对可控。

知识工程没有完成的那一天。每一次 Agent 与人的协作都在产生新的知识，知识体系本身也在不断演进。重要的不是一开始就设计出完美的体系，而是先让 Agent 开始记，然后让体系在记的过程中自己长出来。

示例仓库：github.com/st1page/agent-knowledge-framework — 从实际使用方式中提取的最小公开示例，包含完整目录结构、两个示例角色（cli-tool-dev、maintainer）以及通用知识（principles/insights）。

附录 A：AGENTS.md 实例

以下是公开示例仓库中的 AGENTS.md 部分内容：

“`

Agent Notes

每个 Agent 在开始任何任务前，必须先通读本文件和角色 AGENTS.md，再开始动手。

仓库结构

agent-knowledge-framework/
├── base/ # 通用知识（所有角色共享）
│ ├── experience/ # 不属于特定角色的经验
│ ├── principles/ # 通用原则和规范
│ ├── skills/ # 通用技能（每个技能目录主入口为 SKILL.md）
│ └── insights/ # 通用洞察（跨角色的规律性认知）
└── roles/ # 各角色目录
├── cli-tool-dev/ # CLI/TUI 工具开发
├── maintainer/ # 知识仓库维护
└── /
├── AGENTS.md # 角色描述 + 知识索引（始终加载）
├── principles/ # 角色专有原则
├── skills/ # 角色专有技能
├── insights/ # 角色专有洞察
└── experience/ # 角色经验复盘
“`

附录 B：经验沉淀规范

部分内容如下：

“`

经验沉淀规范

当用户要求「总结经验」「沉淀一下」时，不要无脑堆到一个文件里。先判断这条知识的性质和受众，再决定放在哪里。

知识分类与存放位置

判断放 role 还是 base

只对本角色有意义 → roles/<role>/。例如某项目的 FFI 双层提取模式，只有该角色会用到
多个角色都可能遇到 → base/。例如「改了函数返回类型后要追踪所有消费者」「skip ≠ pass」，这些是通用工程经验

问自己：「如果另一个角色遇到类似情况，这条知识对他有用吗？」有用就放 base。
“`

关注“鲸栖”小程序，掌握最新AI资讯

本文来自网络搜集，不代表鲸林向海立场，如有侵权，联系删除。转载请注明出处：https://www.itsolotime.com/archives/25650