agents-md-">AGENTS.md 类代理指令文件安全解析

一、概念定义：AGENTS.md 是什么

AGENTS.md 是一类面向 AI 代理的纯文本指令文件，通常放置在项目根目录、代码仓库目录或工作目录中，用自然语言描述项目背景、目录结构、编码规范、构建与测试方式、依赖管理要求、禁止操作以及代理协作规则。它的核心作用不是被编译器执行，而是被具备上下文感知能力的 AI 代理读取，并作为后续规划、文件操作和命令调用的参考依据。

从技术视角看，AGENTS.md 是“项目级上下文约定文件”；从业务视角看，它是“代理行为治理载体”；从使用视角看，它更像一份“人机共读的项目说明书”。它解决的问题是：开发者不必在每次对话中重复说明项目规范，代理进入目录后即可自动获得较完整的上下文，从而减少重复提示、统一团队协作习惯、降低代理误操作概率。

但必须明确：AGENTS.md 本身不是可执行程序，也不是传统意义上的病毒。它之所以带来安全风险，是因为在具备文件读取、命令执行、网络访问能力的代理系统中，自然语言指令可能被转化为工具调用。换句话说，文件是纯文本，风险在于“代理会把它当成操作意图”。

二、为什么会出现：上下文工程与自动发现机制

AI 代理要提高效率，必须理解项目上下文。没有上下文时，代理需要用户反复说明“项目用什么语言版本”“测试命令是什么”“哪些目录不能改”“依赖如何安装”。AGENTS.md 类文件把这些信息固化为可版本化、可审查、可复用的文本规则，因而成为代理工程实践中的常见做法。

它的价值主要体现在三方面：

1. 减少重复提示：项目规范一次编写，多次复用。
2. 统一代理行为：不同开发者、不同会话中的代理遵循相同约束。
3. 降低协作成本：规则文件可进入代码评审流程，便于团队维护。

问题在于，许多代理运行时会采用“自动发现、自动加载”的策略：启动时扫描当前目录及父目录，发现约定文件后直接加入上下文。这个机制提升了便利性，也扩大了攻击面。只要用户在不信任目录中启动代理，代理就可能把外部投递的文本当成项目规则。

三、核心组成：一个代理指令文件包含哪些要素

AGENTS.md 类文件通常包含以下模块：

• 项目概览：项目目标、模块划分、关键目录说明。
• 开发规范：命名约定、代码风格、提交要求、审查规则。
• 构建与测试说明：如何安装依赖、如何运行测试、如何验证结果。
• 安全策略：哪些文件禁止修改、哪些命令需要审批、敏感信息如何处理。
• 代理行为边界：是否允许联网、是否允许写全局配置、是否允许安装依赖。
• 协作流程：多代理分工、任务交接、变更记录方式。

在运行时，代理系统还需要配套机制：文件发现范围、加载优先级、规则合并策略、工具权限控制、命令审批、沙箱隔离和审计日志。单独一个 AGENTS.md 不会造成危害；真正决定风险大小的是“代理读取了什么、拥有什么权限、执行前是否确认”。

四、工作原理：从自然语言到工具调用

可以用一个简化流程描述：

代理启动
  -> 扫描工作目录及允许范围
  -> 发现 AGENTS.md 类指令文件
  -> 将文本加入上下文
  -> 结合用户任务进行规划
  -> 调用文件读写、命令执行、网络请求等工具
  -> 经过审批与沙箱策略后执行

风险链路通常包括四步：

1. 投递：网页、文档或附件诱导浏览器将文本文件静默保存到常见下载目录。
2. 触发：用户在该目录启动高权限代理，要求整理文件或编写脚本。
3. 读取与伪装：代理自动加载文件，恶意文本伪装成“项目修复步骤”“验证规范”或“依赖安装说明”。
4. 诱导执行：文本引导代理修改配置、放宽安全限制、安装不可信依赖、读取本地密钥或向外部发送数据。

这条链路的关键不是可执行文件，而是“代理信任上下文文件”。当审批策略宽松、沙箱可写、网络无限制时，纯文本也可能引发实际危害。

五、典型场景与相关概念区别

适合使用 AGENTS.md 的场景包括：团队项目规范、代码审查规则、自动化测试说明、运维脚本约束、多代理协作约定。高风险场景包括：下载目录临时启动代理、第三方共享仓库、来源不明的模板、多项目规则混合加载、持续集成流水线中的高权限执行环境。

与 README 的区别：README 主要面向人，代理不一定将其作为高优先级操作指令；AGENTS.md 更直接地面向代理行为。与结构化配置文件的区别：结构化配置字段明确、解析可控；自然语言规则自由度高，注入面更大。与脚本的区别：脚本需要显式执行，用户有心理防线；AGENTS.md 通过影响代理规划间接影响工具调用。与单次提示词注入的区别：单次注入发生在对话中，而恶意指令文件可持久化存在，属于更接近供应链风险的上下文投毒。

六、使用注意事项与治理建议

第一，不在不信任目录启动高权限代理。下载目录、临时目录、共享目录应默认视为不可信环境。

第二，限制文件发现范围。代理只应读取工作目录白名单内的规则文件，避免自动加载父目录或无关目录中的内容。

第三，坚持最小权限。默认只读、按需写入，敏感操作二次确认；关闭不必要的全局配置修改能力。

第四，启用沙箱与网络出口控制。代理执行环境应限制可访问的网络目标，隔离本地密钥和访问令牌。

第五，建立审批与审计。命令执行、依赖安装、配置修改、外发数据等操作应记录日志并可追溯。

第六，将规则文件纳入代码评审。团队应维护 AGENTS.md 模板，明确禁止代理自行关闭安全机制、读取敏感文件或安装不可信依赖。

第七，开展用户教育。纯文本不等于安全，代理时代的风险边界已从“是否双击可执行程序”扩展为“代理读取了什么、能做什么、能访问什么”。

七、总结

AGENTS.md 类代理指令文件是 AI 代理工程中的重要上下文载体，它通过自然语言规则提升项目协作效率和代理行为一致性。其核心价值在于项目级说明的复用与治理；其核心风险在于自然语言指令可能被代理转化为工具调用。正确理解它的定义、加载机制和安全边界，配合最小权限、沙箱隔离、审批审计和来源审查，才能在享受代理自动化能力的同时，避免“纯文本文件”演变为真实攻击入口。