Rust/codex-rs

2026-09-07 12:19:59作者：昌雅子Ethen

In the codex-rs folder where the rust code lives:

Crate names are prefixed with codex-. For example, the core folder's crate is named codex-core
When using format! and you can inline variables into {}, always do that.
Install any commands the repo relies on (for example just, rg, or cargo-insta) if they aren't already available...
When running Rust commands (e.g. just fix or just test) be patient with the command and never try to kill them using the PID...


注意它的行文特征：全部是“在本仓库内应当如何做”的可执行约定，而不是泛泛的背景介绍——这正是 `AGENTS.md` 应有的形态。模型在后续所有会话中都能直接依循这些命令与风格约束，无需使用者重复交代。

## 加载范围与优先级：全局文件 + 项目目录层级

Open Interpreter 自动加载两类 `AGENTS.md`，官方文档用如下表格定义其作用域：

| 作用域 | 路径 |
| ------ | ---- |
| 全局（Global） | `~/.openinterpreter/AGENTS.md` |
| 项目（Project） | 从仓库根目录向下直到当前工作目录的所有 `AGENTS.md` 文件 |

- **全局文件**：存放在 Open Interpreter 的主目录下，对所有项目生效。默认主目录即 `~/.openinterpreter/`（可参考 [codex-rs/utils/home-dir/src/lib.rs](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/codex-rs/utils/home-dir/src/lib.rs?utm_source=gitcode_repo_files)，其中同时支持 `INTERPRETER_HOME` 环境变量等覆盖方式）。全局指导由 [codex-rs/codex-home/src/instructions/mod.rs](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/codex-rs/codex-home/src/instructions/mod.rs?utm_source=gitcode_repo_files) 中的 `CodexHomeUserInstructionsProvider` 负责读取。
- **项目文件**：会遍历“仓库根目录 → 当前工作目录”路径上的每一层目录，逐层收集存在的 `AGENTS.md` 并按根目录到当前目录的顺序拼接。

**优先级规则**：更具体的文件会覆盖或补充更宽泛的文件。一个文件离当前工作目录越近，通常就越相关——这与常见的 monorepo 协作模式一致：越深层的目录可声明越贴近具体任务的约束。

### 拼接语义的源码印证

模型最终看到的不是多个独立文件，而是一段**按顺序拼接好的文本**。在 [codex-rs/core/src/agents_md.rs](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/codex-rs/core/src/agents_md.rs?utm_source=gitcode_repo_files) 中：

- 项目根目录的判定：从当前工作目录逐级向上寻找 `project_root_markers` 中声明的标记文件（默认只有 `.git`，见 [codex-rs/config/src/project_root_markers.rs](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/codex-rs/config/src/project_root_markers.rs?utm_source=gitcode_repo_files)）；找不到标记时只考虑当前目录；标记列表为空则完全禁用父目录遍历，`AGENTS.md` 只作用于当前目录。
- 收集顺序：先确定从根到 cwd 的目录链，再对每一层探测候选文件名，把命中的文件按**根目录在前、当前目录在后**的顺序拼接。换言之，越靠近当前目录的说明在最终文本中越靠后，也就离本次用户请求越近。
- 用户/全局说明与项目说明之间会插入分隔符 `--- project-doc ---`（常量 `AGENTS_MD_SEPARATOR`），告诉模型“以下属于工作区范围的项目指导”。

该顺序在测试 [codex-rs/core/tests/suite/agents_md.rs](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/codex-rs/core/tests/suite/agents_md.rs?utm_source=gitcode_repo_files) 中被直接断言：当全局文件与项目文件同时存在时，最终指令形如 `global doc\n\n--- project-doc ---\n\nproject doc`——全局在前、项目在后。

### 多环境与会话级缓存

如果一次会话同时涉及多个工作环境（例如并行操作多个项目目录），代码会对每个环境都执行一次上述发现逻辑；当检测到来自多个不同项目环境的说明时，拼接文本还会为每个环境标注 `for {environment_id} with root {path}`，避免模型混淆各环境的指导归属（见 [codex-rs/core/src/agents_md.rs](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/codex-rs/core/src/agents_md.rs?utm_source=gitcode_repo_files) 中 `environment_labeled_text` 的实现）。

为避免重复昂贵的磁盘发现，[codex-rs/core/src/agents_md_manager.rs](https://gitcode.com/GitHub_Trending/op/openinterpreter/blob/8e5d19bfcd705c3786c5641971dce5c2dc1aa64d/codex-rs/core/src/agents_md_manager.rs?utm_source=gitcode_repo_files) 在会话内缓存了“环境选择 → 已加载说明”的结果：只有当环境的快照（selections）发生变化时才会重新加载；切换工作目录后缓存失效并自动刷新，保证指令始终与当前目录匹配。

## 临时覆盖：AGENTS.override.md

在本地做实验、临时替换全局说明时，不必删除或改写 `~/.openinterpreter/AGENTS.md`。只需创建这个文件：

```text
~/.openinterpreter/AGENTS.override.md

Open Interpreter 在读取全局指导时会优先使用 AGENTS.override.md，其内容将完全取代默认的全局 AGENTS.md。删除该覆盖文件后即可恢复正常的全局文件。

源码同样印证了这一优先级：codex-rs/codex-home/src/instructions/mod.rs 中，全局说明的候选文件名列表固定为 ["AGENTS.override.md", "AGENTS.md"]——先探测 override 文件，命中即返回，不再读取默认文件。

值得一提的实现细节是，override 机制不仅作用于全局目录。在项目级发现逻辑 candidate_filenames（codex-rs/core/src/agents_md.rs）中，每个目录层也按 AGENTS.override.md → AGENTS.md → 自定义 fallback 文件名的顺序探测，因此若某项目目录同时存在这两个文件，该目录层只会加载 AGENTS.override.md。对应的集成测试 agents_override_is_preferred_over_agents_md 明确断言“override 存在时 AGENTS.md 应被忽略”。也就是说，你可以用同名 override 文件对任意单个目录临时改写指导，而无需改动团队共享的 AGENTS.md。

大小限制：project_doc_max_bytes

项目说明最终会占用模型上下文，因此不能无上限加载。合并后的项目说明受 project_doc_max_bytes 限制；官方文档特别指出，目录特定的文件会被优先处理，以便在达到限制时靠近当前目录的指导仍然能够保留下来。

在 codex-rs/core/src/agents_md.rs 的 read_agents_md 中可以看到完整的预算逻辑：

读取配置项 project_doc_max_bytes 作为总字节预算 remaining；
按根目录到当前目录的顺序逐文件读取，每次读取后从剩余预算中扣除该文件实际占用的字节数；
若单个文件超过剩余预算，会对该文件执行截断（data.truncate(...)）并给出告警日志；预算耗尽（remaining == 0）后停止加载后续文件；
文件内容为空（trim 后无字符）时不计入结果。

如何配置该限制

project_doc_max_bytes 是配置文件中的一个常规项，定义于 codex-rs/config/src/config_toml.rs（默认值见常量 DEFAULT_PROJECT_DOC_MAX_BYTES = 32 * 1024，即 32 KiB），并在 codex-rs/core/config.schema.json 中登记为：

{
  "project_doc_max_bytes": {
    "default": 32768,
    "description": "Maximum number of bytes to include from an AGENTS.md project doc file.",
    "minimum": 0,
    "type": "integer"
  }
}

因此你可以在配置文件中将其调大（获得更充足的项目上下文）或调小（省出上下文给对话本身）。特别地，将该值设为 0 时，codex-rs/core/src/agents_md.rs 会直接返回空结果——即完全禁用项目级 AGENTS.md 的加载。

扩展候选文件名：project_doc_fallback_filenames

部分团队已经在使用 CLAUDE.md 等其他约定文件维护项目规范。为避免重复维护，Open Interpreter 提供了 project_doc_fallback_filenames：当某个目录下找不到 AGENTS.md 时，会按顺序探测该列表中声明的文件名，把它们也当作项目说明的候选来源。

候选顺序为：AGENTS.override.md → AGENTS.md → project_doc_fallback_filenames 中的各文件名（自动去重并跳过空串），见 candidate_filenames 的实现；
配置默认值为空列表（[]），需要在配置文件（如 config.toml）中显式给出，例如把 CLAUDE.md 加入其中即可让旧规范文件无缝接入。

一个完整的 AGENTS.md 模板

官方文档给出了一份可直接复制的模板骨架，覆盖了构建命令、代码约定与注意事项三个最常用的板块：

# Project Instructions

## Commands
- `pnpm test` runs unit tests.
- `pnpm lint` must pass before final changes.
- Use `pnpm typecheck` after editing TypeScript types.

## Conventions
- Keep server code under `src/server`.
- Keep UI components small and colocated with their tests.
- Prefer existing helpers in `src/lib`.

## Cautions
- Do not edit generated files under `src/generated`.
- Ask before changing database migrations.