进阶 opencode.ai 2026-11-11 16:13:22 · 18 阅读

第25章 通过AGENTS.md定义OpenCode代理的项目级指导

Instructions 添加 AGENTS.md 文件可以为 OpenCode 提供持久化的项目指导。请在此文件中定义构建命令、架构说明、代码规范以及验证要求。 AGENTS.md# 项目说明

- TypeScript 代码变更后,运行 `bun typecheck`。 - 将数据库查询逻辑保留在 `src/database` 目录中。 - 不要直接修改生成的文件。 请将项目说明文件提交到代码库,以确保在该仓库工作的所有成员都能获得相同的指导。 将 AGENTS.md 放在其指导内容需要生效的目录下。OpenCode 先加载全局文件,然后从当前工作区目录向家目录逐层加载每一个 AGENTS.md。如果工作区位于家目录之外,则在项目根目录处停止。 ~/.config/opencode/AGENTS.md ~/code/my-project/AGENTS.md ~/code/my-project/packages/AGENTS.md ~/code/my-project/packages/web/AGENTS.md ← 当前工作区 在此示例中,以上四个文件均会被加载。合并顺序如下: ~/.config/opencode/AGENTS.md packages/web/AGENTS.md packages/AGENTS.md AGENTS.md 将在所有场景通用的指导内容放在全局文件中;将适用于整个仓库的指导放在项目根目录,将更具体的指导放在离其所覆盖代码更近的位置。OpenCode 会合并这些文件,但不会解决它们之间的冲突。 如果工作区位于项目根目录之外,则只加载全局文件。设置 OPENCODE_DISABLE_PROJECT_CONFIG=1 可以在不关闭全局文件的情况下,跳过对项目 AGENTS.md 的查找。 代理在探索项目时,会发现工作区下方的说明文件。读取文件或列出目录时,OpenCode 会加载该目标与当前工作区之间存在的 AGENTS.md 文件。 文件my-project/ ← 当前工作区 ├── AGENTS.md 初始加载 └── packages/ └── web/ ├── AGENTS.md 读取该区域时加载 └── src/ └── app.ts 读取目标 嵌套文件遵循“就近优先”原则进行加载,并在其指令条目仍处于模型可见历史时去重。再次读取相同区域通常不会重复注入。如果发生压缩或回滚操作导致该条目被移除,后续读取可能会再次加载该文件。 嵌套文件加载后的编辑操作不会自动检测。如果更新的内容需要立即生效,请开启一个新的会话。 先发送所选代理或提供方提供的系统提示词,然后 OpenCode 按以下顺序组装初始说明: 1. 代理或提供方系统提示词 2. Code Mode 工具指导(若已启用) 3. MCP 服务器、参考文档及技能指导 4. 全局及项目 AGENTS.md 文件,以及配置中的指令 5. 内置日期与环境上下文 6. 通过 API 提供的会话特定指令条目 这些来源是相互合并而非覆盖关系。后续发现的嵌套 AGENTS.md 文件将按发现顺序追加到会话历史中。 在会话运行期间编辑全局文件或向上发现的 AGENTS.md,即可更新其指导内容。 终端$ printf '\n- 提交前运行集成测试套件。\n' >> AGENTS.md 在下一次模型请求前,OpenCode 检测到变更,并将在处理待决输入之前插入指令更新: AGENTS.md 变更 → 指令更新 → 下一次提示 移除所有环境中的 AGENTS.md 文件,即告知会话之前的环境说明已不再适用。 若读取暂时失败,系统会保留最后已知的指令,而非将其视为已删除。 移动会话会保留其指令状态,因此目标位置的指导内容会以更新形式引入。 对会话执行回滚提交操作会清除其指令状态,并在下一次提示前重新加载说明。 指令值仍享有特权。客户端可以看到哪些来源发生了变更,但无法看到其具体内容。 使用 instructions 数组可以在发现的 AGENTS.md 文件之外,额外添加文件、Glob 模式或 HTTP(S) URL: opencode.jsonc{ "$schema": "https://opencode.ai/config.json", "instructions": [ "CONTRIBUTING.md", "docs/guidelines/*.md", "~/rules/opencode.md", "https://example.com/instructions.md", ], } 配置中的指令会在 AGENTS.md 文件之后加载,且按其列出的顺序执行。所有配置文档中的条目将被合并。 条目解析方式 相对路径或 Glob 模式:从工作区目录向上查找至项目根目录 ~/ 路径:从家目录解析 绝对路径:按原样使用,文件名可以是 Glob 模式 http:// 或 https://:加载配置时获取,超时时间为五秒 本地文件在发生变更时会像 AGENTS.md 一样更新。匹配新 Glob 模式的文件将在下次配置变更时加载。 不存在的文件会被跳过。无法获取的 URL 也会被跳过,或者保留其最后获取到的内容。 若设置了 OPENCODE_DISABLE_PROJECT_CONFIG=1,或当前工作区位于项目之外,相对路径条目将基于全局配置目录进行解析。 已连接的 OpenCode Console 工作区也可以共享说明文件。 有关配置位置及优先级的详情,请参见 Config 章节。

评论 (0)