从零到一掌握 OpenCode 的 AGENTS.md 记忆系统
本文是「AI 效能」系列的第六篇。前五篇讨论自动开发的边界、流程编排、初始化加速、工作区设计与 Loop 架构；这一篇把视角收回到 AI 编程代理本身：它如何从文件系统里加载项目记忆，为什么同一条规则有时生效、有时不生效。 版本说明：本文以 OpenCode V2 为准，关键边界在本机 v2.2.6 上核对。V1 的加载规则不同，迁移时不要直接套用。 很多人第一次配置 AGENTS.md ，会把它当成一份“项目说明”。写完却发现： 子目录里的规则有时生效，有时像没写； 改完文件，当前会话没有任何反应； 在 home 某个目录放了一份 AGENTS.md ，结果所有 home 内项目都被它影响； 一次普通的 read 之后，上下文突然多出几百行。 这篇文章解决的是：规则写了却不生效，或者不知道什么时候生效。它面向已经把 OpenCode 用作日常编码代理的开发者，也面向需要维护团队项目规则的人；不适合还没用过 OpenCode 的完全新手，也不打算给出一套跨工具的通用记忆方案。 这些都不是偶发问题，而是同一套机制的不同侧面：OpenCode 读取 AGENTS.md 的方式，不是“打开一个文件”，而是“按路径分层加载”。 本文从零开始，把这套机制拆成四件事：启动时加载什么、执行中补什么、什么时候更新、以及怎么设计一套不会互相打架的层级。 先说结论 问题 结论 启动时读哪些 全局文件 + 从 workspace 向上冒泡 冒泡到哪停 workspace 在 home 内 → 到 home；在 home 外 → 到项目根 workspace 不在项目内 只加载全局文件 子目录规则何时生效 用 read 读到该区域时按需加载 多个文件冲突怎么办 不解决冲突，只按顺序拼接 改了文件何时生效 启动时发现的文件热更新；子目录文件要新会话 先统一几个概念 词 含义 会话（session） 一次对话及其上下文 workspace 当前会话的工作目录，也是向上冒泡的起点 项目根（project root） 最近的 Git 或 Mercurial 仓库根；没有仓库时回退为启动目录 默认全局文件 ~/.config/opencode/AGEN...