Hermes Agent 上下文文件目录链：monorepo 中自动合并 git root 到当前目录的所有 AGENTS.md

在 monorepo 里工作过的同学大概都遇到过这种尴尬：你在 packages/webapp/ 里开了一个会话，agent 却只认识眼前这一份 AGENTS.md——仓库根目录那份写着全团队约定的文件（分支策略、CI 流程、提交规范），它根本看不见。于是你要么在每个子目录里重复一遍规则，要么眼睁睁看着 agent 一遍遍违反约定。这周开始，Hermes 会把整条上下文文件链自动合并进来，一次解决。

在 monorepo 深处启动会话，Hermes 只“看”到一层

AGENTS.md 是 Hermes Agent 的主要项目上下文文件：告诉 agent 项目结构、代码约定、特殊注意事项。但在以前，如果你在 monorepo/packages/webapp/ 里启动会话，Hermes 只加载当前目录的那份 AGENTS.md——仓库根目录那份“全仓通用规范”（提交规范、分支策略、CI 流程）完全看不到，除非你手动在深层目录里复制一份。

复制带来新的问题：内容分叉、更新不同步、还占上下文预算。

2026-08-08 合入 Hermes Agent main 的目录链（directory chain）功能解决了这个问题：只要工作目录在 git 仓库内，会话启动时 Hermes 会从 git 根目录 → 每一层中间目录 → 当前目录 自动加载整条链上的所有 AGENTS.md，合并进系统提示。该机制移植自 grok-cli 的 directoryChain 实现。

目录链怎么工作

monorepo/                       （git 根目录，cwd = packages/webapp/）
├── AGENTS.md                  ← 第一个加载（仓库级通用约定）
└── packages/
    ├── AGENTS.md              ← 第二个加载
    └── webapp/
        └── AGENTS.md          ← 最后加载（最具体，优先级最高）

关键行为：

  • 来源标签（provenance label）：每份文件都以相对路径作为小标题注入，例如 ## ../../AGENTS.md、## AGENTS.md，agent 能看出每段规范来自哪个目录；
  • 深层优先：越深的文件在提示中越靠后，更具体的规范覆盖/补充更通用的规范；
  • 内容去重：链上出现内容完全相同的副本（复制或符号链接的文件），只保留第一份，不浪费上下文；
  • 预算上限：每份文件单独走截断预算，合并后的整条链还有一次总预算封顶——深 monorepo 不会把上下文文件开销无限放大；
  • 安全扫描：每一份文件都先经过既有的上下文文件威胁扫描（_scan_context_content），恶意内容会被拦截，不会进入系统提示。

非 git 目录：父目录绝不越权

目录链有一个刻意的安全边界：如果当前目录不在 git 仓库内，链就只有 [cwd] 一项，不会去翻父目录。这样放在 /tmp 或 $HOME 里的 AGENTS.md 永远不会泄漏进无关会话——和 .hermes.md 的既有安全设计一脉相承。

优先级系统：一次只加载一种上下文文件

注意目录链只作用于 AGENTS.md。Hermes 的项目上下文类型优先级是：

.hermes.md / HERMES.md  →  AGENTS.md  →  CLAUDE.md  →  .cursorrules

（每次会话只加载第一种命中的类型，SOUL.md 作为全局人格独立加载。）也就是说，如果你仓库根目录用的是 CLAUDE.md（Claude Code 风格），目录链不会生效——CLAUDE.md 仍然只查当前目录。想要链式加载，就用 AGENTS.md。

和“渐进式子目录发现”的分工

很多读者可能已经熟悉 Hermes 的另一个机制：会话中 agent 读入某个子目录的文件时，会按需发现并注入该目录的 AGENTS.md（每个子目录每会话最多检查一次）。目录链与它互补：

机制 时机 覆盖范围
目录链（新） 会话启动时 git root → cwd 的纵向整条链，进系统提示
渐进式子目录发现 会话进行中 agent 实际访问的横向子目录，按需注入对话

两者都受同样的安全扫描保护，且都不影响系统提示的字节稳定性（提示缓存友好）。

monorepo 实战：三层 AGENTS.md 怎么分

目录链的典型用法是按粒度分层：

# 仓库根 AGENTS.md（monorepo 级）
## 通用约定
- 所有 PR 必须通过 CI 与 lint
- 提交信息遵循 Conventional Commits
- 变更记录写到 CHANGELOG.md

# packages/AGENTS.md（包级）
## 包规范
- 新增包必须在 registry 注册
- 包间依赖只能通过公开 API

# packages/webapp/AGENTS.md（目录级，最具体）
## 前端专属
- 组件使用 TypeScript strict 模式
- 样式统一走 design tokens，禁止内联色值
- 测试放 __tests__/，用 Vitest

启动在 packages/webapp/ 的会话会拿到全部三层：仓库级约定打底、包级规范补充、前端专属要求压轴。改动前端代码时 agent 不会写出违反仓库存档策略的提交信息，也不会内联色值破坏设计系统。

升级建议

  1. 把仓库根目录的通用规范（分支/提交/CI）沉淀为根级 AGENTS.md，深层目录只写真正属于该层的规范，避免复制；
  2. 同一份内容不要拷贝进多个目录——目录链会去重，但“只存一份”才是正解；
  3. 如果你从 Claude Code / Cursor 生态迁移，把根级 CLAUDE.md 改名为 AGENTS.md（或放一份 AGENTS.md）即可获得整条链的能力。

想进一步压低长任务失败率，可以看站内的长任务与超时配置指南；把上下文文件与效率技巧搭配使用效果更好。如果你刚接触 Hermes Agent，建议先走一遍安装指南再回来试验。

一句话总结：把 AGENTS.md 按“仓库 → 包 → 目录”三层组织好，Hermes 会在会话启动时自动拼出完整的项目上下文——通用规范不再丢失，具体规范自然压轴，而这一切都是自动的。