应用易读性：让 AI 看清世界

应用可读性（Application Legibility）：让 AI 看见真实世界

试想一下，如果你聘请了一位世界级的顶尖技师来修理汽车引擎，却强制要求他戴上眼罩并佩戴降噪耳机进行操作。无论他拥有多么深厚的理论知识，如果无法看到机油泄漏或听到引擎的异响，他注定会失败。在 AI Harness Engineering（AI 智能体工程框架）领域，如果不在应用中提供“看”和“听”的途径，部署自动代理（Autonomous Agent）的情况亦是如此。

如果代理无法观察应用，它就无法对其进行修复。本章将探讨“应用可读性（Application Legibility）”这一概念——即通过实践，使软件的状态、用户界面和后端性能对 AI 变得完全可见且可理解。通过将浏览器自动化、网络协议和可观测性堆栈（Observability Stacks）直接植入代理的运行时（Runtime），我们可以为其提供复现 Bug、验证修复结果所需的“眼耳”，使其能够像人类开发者一样开展工作。

什么是应用可读性？

应用可读性是指应用以机器可读格式暴露其内部状态、视觉结构和运行健康状况的程度，大语言模型（LLM）正是基于这些格式进行推理。正如 Anthropic 等 AI 实验室的工程研究中所强调的那样，如果长期运行的代理仅基于静态代码进行操作，很快就会陷入幻觉（Hallucination）。它们需要环境反馈来为自己的假设提供依据。

为了实现真正的可读性，Harness 必须将以人类为中心的像素和仪表盘世界，转化为以 AI 为中心的结构化文本、DOM 树和可查询指标世界。

赋予代理“双眼”：浏览器自动化与 CDP

当人类开发者处理 UI Bug 时，他们会打开浏览器、进行点击操作并检查元素。为了赋予 AI 同样的能力，我们将 Playwright 和 Chrome DevTools Protocol (CDP) 等工具集成到 Harness 中。

Playwright： 一个允许代理编写并执行脚本来导航页面、填写表单及点击按钮的框架。它相当于代理在键盘和鼠标上的“双手”。
Chrome DevTools Protocol (CDP)： 这相当于代理的“双眼”。人类看到的是渲染后的像素，而 CDP 允许代理提取原始 DOM（文档对象模型）、读取辅助功能树（Accessibility Tree，它提供了 UI 的简化语义视图）并监控实时网络请求。

人类操作	通过 Harness 实现的 AI 代理等效操作
查看屏幕	通过 CDP 解析辅助功能树或压缩后的 DOM
点击“提交”按钮	通过 Playwright 执行 `page.click('button#submit')`
打开网络面板	拦截 CDP 的 `Network.requestWillBeSent` 事件
检查控制台错误	监听 Playwright 中的 `page.on('console', msg)`

以下是一个示例，展示了如何使用 Python 和 Playwright 为你的代理提供一个“视觉工具”，使其能够检查网页的当前状态：

# 用于代理 UI 检查工具的 Python 伪代码
from playwright.sync_api import sync_playwright

def inspect_page_state(url: str) -> str:
    """
    供 AI 使用的工具，用于导航到 URL 并读取页面结构。
    """
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()
        page.goto(url)

        # 不使用截图，而是提取辅助功能树（Accessibility Tree）
        # 这对于基于文本的 LLM 而言具有极高的可读性。
        snapshot = page.accessibility.snapshot()

        # 捕获控制台错误以向代理报告
        errors =[]
        page.on("pageerror", lambda exc: errors.append(str(exc)))

        browser.close()
        return f"UI Tree: {snapshot}\nConsole Errors: {errors}"

赋予代理“双耳”：可观测性与遥测技术

前端的可视化只是成功了一半。如果代理优化了一个数据库查询，它如何知道查询速度是否真的变快了，还是仅仅引发了严重的内存泄漏？它需要通过可观测性堆栈来“聆听”应用的心跳。

通过将查询语言封装进代理工具中，我们可以让 AI 以历史和实时视角审视后端系统：

LogQL (通过 Grafana Loki)： 允许代理搜索应用日志。如果代理想知道为什么登录失败，它可以使用工具执行类似 {app="auth-service"} |= "error" 的 LogQL 查询，并读取生成的堆栈跟踪（Stack Traces）。
PromQL (通过 Prometheus)： 允许代理检查系统指标。代理可以通过执行类似 rate(process_cpu_seconds_total[5m]) 的 PromQL 查询来验证其代码变更是否导致了 CPU 使用率飙升。

提供这些特定的查询语言意味着代理无需猜测。它可以形成假设（“我认为我的修复解决了 500 错误”），将代码部署到沙箱中，并通过查询遥测数据客观地验证结果。

将工具植入代理的运行时

为了让这一切生效，这些可读性工具必须作为可调用函数（通常称为工具调用，Tool Calling）暴露给代理。Harness 负责维护执行循环。我们将此称为 AI 的 OODA 循环（观察 Observe、定位 Orient、决策 Decide、行动 Act）。

[ 带有可读性的代理 OODA 循环 ]

      +-----------------------+
      | 1. ACT (代码变更)     |
      +-----------+-----------+
                  |
                  v
      +-----------------------+
      | 2. OBSERVE (工具)     | <--- Playwright DOM 快照
      |                       | <--- CDP 网络日志
      |                       | <--- PromQL / LogQL 查询
      +-----------+-----------+
                  |
                  v
      +-----------------------+
      | 3. ORIENT (评估)      |  (错误率是否下降？)
      +-----------+-----------+  ('提交'按钮是否可见？)
                  |
                  v
      +-----------------------+
      | 4. DECIDE (下一步)    | ---> (标记为完成 或 再次修复)
      +-----------------------+

当你将这些工具直接接入运行时，代理就不再是那个戴着眼罩的技师。相反，它变成了严谨的科学工程师：它推送代码、监控实时指标、点击 UI 界面以确保没有发生回归（Regression），并且只有当应用的“眼耳”确认成功时，才会将任务标记为完成。