读懂 Codex（4.3）：项目根目录和 AGENTS.md 的发现算法

AGENTS.md 发现不是从 cwd 无限向上搜索。算法先用项目根标记确定边界，再从根到当前目录逐层查找规则文件；找不到根标记时只检查当前目录。这个边界同时决定“能看到哪些规则”和“绝不能越过哪里”。

根目录发现

默认根标记是 .git，配置可以替换标记集合。算法从当前目录向父目录探测，找到最近一个含任意标记的祖先即停止；空标记列表会禁用向上遍历。

从 cwd 向上查找项目根标记的边界算法 — 图 4.3-1：向上阶段只定位根；真正加载规则时再按相反方向从根走回 cwd。未发现标记不会退化为扫描整个文件系统。

async def find_project_root(fs, cwd, markers):
    if markers == []:
        return cwd
    for directory in ancestors(cwd):
        if await fs.contains_any(directory, markers or [".git"]):
            return directory
    return cwd

远程执行环境下，探测通过该环境的 ExecutorFileSystem 完成，而不是默认读取宿主本地磁盘。源码对祖先元数据探测设有并发上限，用一次有界批量查询降低远端往返延迟。

从根到 cwd 选择文件

每层候选顺序是 AGENTS.override.md、AGENTS.md、配置的 fallback 文件名；同一层只采用第一个存在的普通文件。层级顺序则是根在前、越接近 cwd 越靠后。

图 4.3-2：目录层级全部参与，文件候选在每一层互斥选择。override 的优先级是“同目录替代”，不是让整个项目只剩一份规则。

async def discover_agent_docs(fs, root, cwd, fallbacks):
    candidates = ["AGENTS.override.md", "AGENTS.md", *fallbacks]
    selected = []
    for directory in path_from_root(root, cwd):
        for name in candidates:
            path = directory / name
            if await fs.is_file(path):
                selected.append(path)
                break
    return selected

环境和错误边界

一次 Turn 可以包含多个已选择环境。load_project_instructions 分别使用每个环境的文件系统与 cwd，合并各自加载项。单个环境读取失败会记录错误，并让其他环境继续；读取中途遇到文件已消失则跳过该文件，以容忍发现与读取之间的竞态。

若 project_doc_max_bytes 为零，发现直接关闭。符号链接、远端路径 URI 和宿主路径转换由文件系统抽象负责，发现层不应自行用本地 Path.exists() 猜测。

源码与测试锚点

codex-rs/core/src/agents_md.rs：根定位、逐层候选和读取预算。
codex-rs/file-system：向上标记发现与文件系统抽象。
codex-rs/core/src/agents_md_tests.rs：根标记、fallback、override 与无根场景。

根目录发现

从根到 cwd 选择文件

环境和错误边界

源码与测试锚点

评论