Agent感知原语拆解：文件、浏览器、日志与外部数据如何接入

模型只能直接处理被放进当前上下文的信息。

它没有自动知道你的项目目录里有哪些文件，不知道服务器刚刚发生了什么，也不知道浏览器页面是否已经加载完成。要让 Agent 处理真实任务，Harness 必须先把现实环境转换成模型可以理解、可以引用、可以继续行动的上下文。

这就是感知原语要解决的问题。

感知不是简单地“把更多内容塞给模型”。一个可靠的感知层还要说明信息从哪里来、什么时候读取、谁有权限、是否可能过期，以及它能不能作为完成判断的事实依据。

一、感知原语回答什么问题

可以把感知原语概括成一句话：Agent 如何知道现在发生了什么？

常见原语包括：

• 文件和目录读取；
• 代码与文本搜索；
• Git 分支和工作区状态；
• Shell、测试和日志输出；
• 网页搜索和网页正文；
• 浏览器 DOM、无障碍树和页面状态；
• 截图、图片和视觉输入；
• 数据库、API 和企业连接器；
• 进程、端口、环境变量和系统状态；
• 文件监听和外部事件更新。

这些入口提供的信息质量不同。当前测试输出通常比对话里的“我记得已经通过了”更接近事实；数据库当前状态通常比一份旧报表更接近现实；网页快照则要考虑发布日期、缓存和来源。

二、文件系统是最基础的感知界面

对编码 Agent 来说，文件系统是最常见的现实世界入口。它不只是读取文件内容，还包括：

• 当前工作区有哪些文件；
• 项目使用什么语言和框架；
• 哪些文件最近发生过变化；
• 哪些目录是生成物、缓存或依赖；
• 当前 Git 分支和未提交 Diff；
• 构建、测试和配置入口在哪里。

一次可靠的项目检查通常分成三步：

列目录 -> 找入口 -> 读取相关文件

不要一上来读取整个仓库。先用目录结构和文件名判断范围，再读取 README、依赖清单、构建配置、入口代码和测试。这样既减少上下文噪声，也降低误读无关文件的风险。

一个项目探索任务可以要求 Agent 输出证据：

请检查当前项目，但不要修改文件。

先输出：
1. 目录结构摘要；
2. 启动、构建和测试命令；
3. 关键入口文件；
4. 环境变量名称；
5. 最近的 Git 状态；
6. 你无法确认的内容。

每个判断引用具体文件路径，不要把推测写成事实。

三、搜索比完整读取更重要

大型项目不可能每次都全部读入上下文。搜索原语让 Agent 可以先定位，再读取局部上下文：

搜索：找到所有数据库连接、API 路由和错误处理
读取：打开匹配位置前后若干行
关联：继续读取调用方和配置来源
验证：运行测试或实际请求

代码搜索、文本搜索、文件名搜索和结构化查询各有用途。搜索结果也不是最终证据：一个字符串可能出现在注释、测试样例或已经废弃的文件中。Agent 需要继续确认它是否在当前执行路径上。

搜索原语的返回结果最好包含：文件路径、行号、匹配文本和搜索条件。只有一段没有位置的文本，用户很难复核，后续 Agent 也难以继续行动。

四、终端、日志和测试是动态感知

文件告诉 Agent“代码写了什么”，命令和日志告诉它“当前实际发生了什么”。这两者不能互相替代。

例如，看到配置里写着端口 3000，不代表当前进程真的监听了 3000；看到测试文件里有一个用例，也不代表它最近通过了。

动态感知通常包括：

执行命令
    |
读取退出码、标准输出和错误输出
    |
判断是否需要继续、修复或暂停

一个可靠 Harness 要保留命令的工作目录、环境摘要、开始时间、结束时间和退出码。长输出应该保存到文件并向模型提供摘要与路径，而不是无条件塞满上下文。

日志也需要区分来源：应用日志、反向代理日志、系统日志、测试日志和第三方服务响应，故障含义并不相同。Agent 看到一条 500，还需要知道这是浏览器收到的状态、Nginx 记录的状态，还是应用内部异常。

五、浏览器感知不是只有截图

浏览器任务至少有三类感知信息：

结构信息

DOM、可访问性树、元素角色、文本和属性，适合定位按钮、输入框、表格和链接。

状态信息

当前 URL、加载状态、网络请求、控制台错误、登录状态和弹窗状态，适合判断页面是否真的完成加载。

视觉信息

截图、布局、颜色、遮挡、间距和响应式表现，适合发现结构化树不容易表达的问题。

三者应该结合使用。只看截图，Agent 可能知道按钮在哪里，却不知道按钮的真实角色和请求结果；只看 DOM，可能发现不了移动端溢出和遮挡。

浏览器感知任务可以要求分层输出：

请检查当前页面，不要点击提交按钮。

输出四部分：
1. 页面结构：主要区域、表单和可操作元素；
2. 页面状态：URL、加载状态、控制台和网络错误；
3. 视觉问题：遮挡、溢出、空白和层级问题；
4. 需要人工确认的内容。

不要把截图中看不清的文字补全成确定事实。

六、外部数据连接器要带来源

数据库、API、企业文档和搜索服务可以极大扩展 Agent 的感知范围，但也带来数据权限和新鲜度问题。

每一份外部数据最好携带元信息：

{
  "source": "internal-ticket-system",
  "record_id": "INC-1234",
  "retrieved_at": "2026-07-30T09:30:00+08:00",
  "authority": "system-of-record",
  "permission_scope": "project-a-read",
  "content": "..."
}

source 说明来自哪里，retrieved_at 说明什么时候读取，authority 说明是否是权威系统，permission_scope 说明 Agent 在什么权限下看到它。没有这些信息，模型很容易把缓存、草稿和正式数据混在一起。

七、感知结果要区分事实、推断和线索

可以要求 Agent 把输入分成三种：

这一步很重要。Agent 看到日志中的报错，只能确认报错出现，不能自动确认根因；看到网页上的价格，只能确认当前页面显示什么，还要考虑地区、套餐和日期。

八、感知原语的失败模式

读取范围过大

把整个仓库、全部日志或所有历史对话注入上下文，会导致关键内容被淹没。修复方式是先索引、再检索、后局部读取。

读取范围过小

只给 Agent 一个报错字符串，它可能看不到配置、调用方和环境。修复方式是围绕错误向上追踪输入，向下追踪执行结果。

信息过期

使用旧的缓存、旧截图或上一次会话的状态，会让 Agent 做出与当前环境不符的判断。需要标记读取时间，并在关键动作前重新读取。

权限不一致

浏览器能看到的页面，服务器 API 不一定能访问；用户能读取的文件，子 Agent 不一定有权限。感知层要返回权限失败，而不是静默当成空数据。

内容注入

网页、Issue、邮件和代码注释都可能包含诱导模型改变规则的内容。外部内容必须作为数据处理，不能直接成为系统指令。

九、设计感知层的检查表

为每一个感知接口问六个问题：

1. 输入来自哪里？
2. 读取时间是什么？
3. 它是否是权威来源？
4. Agent 是否有权访问？
5. 返回结果是否足够小、结构化和可引用？
6. 信息失效或读取失败时如何表现？

如果接口只返回一段自然语言，却没有来源、时间和错误状态，后续推理很难可靠。感知层越结构化，认知和验证层越容易工作。

结论

感知原语是 Agent 进入现实世界的第一步。文件、搜索、终端、浏览器、截图、日志、数据库和外部连接器，分别提供不同角度的环境信息。

可靠的感知不是读取得越多越好，而是让 Agent 在正确时间读取正确范围，并知道信息来自哪里、是否过期、是否可信、是否有权限。只有把这些元信息保留下来，模型的后续推理才有可能建立在事实而不是猜测上。

参考资料

• Playwright 官方文档，用于核对浏览器自动化、页面状态和测试能力。
• Model Context Protocol Specification，用于理解外部工具和数据连接的协议边界。