# 让 Agent 操作没有 API 的内部系统，保存键留给人

> Playwright MCP 读取页面无障碍快照而非截图，登录会话和每次写操作仍由人掌控。

原文: https://fdetimes.net/zh/guides/playwright-mcp-internal-web-no-api/

设想在客户现场的一天。运营团队希望用一个 Agent 自动更新订单状态，但他们的内部系统是多年前写的网页界面，完全没有 API。前线部署工程师（FDE）在坐到客户身边之前，就应该对这种情况心里有数。

Playwright MCP 是一个务实的解法。Microsoft 将它作为 MCP 服务器发布，让大模型（LLM）通过 Playwright 控制浏览器。关键在于，它基于结构化的无障碍快照工作，因此既不需要截图，也不需要视觉模型。

本文用五个步骤走一遍一个假设案例：Agent 登录内部订单管理页面，填写状态更新表单，只有在人批准后才点击“保存”。你需要 Node.js、已安装的 Playwright、一个支持 MCP 的客户端，以及一个用来练手的网站。如果手头没有真实的内部应用，在本地跑一个演示应用就够了。

## 第 1 步：登录会话是最敏感的资产

Agent 不应该每次运行都输入密码。Playwright 建议把已认证的状态保存到文件中复用，将文件放在 `playwright/.auth` 目录下，并把该目录加入 `.gitignore`。

```bash
mkdir -p playwright/.auth
echo "playwright/.auth" >> .gitignore
git status   # 这里不应出现 .auth 目录
```

原因在 Playwright 文档里写得很清楚：认证状态文件包含敏感信息，强烈建议不要提交到代码仓库，私有仓库也不行。在客户那里，这个文件通常是某位真实员工的会话 cookie。文件泄露，就等于泄露了这个人的访问权限。

本步检查：运行 `git status`，确认 `.auth` 里的任何文件都没有出现。生成状态文件的方法，参照 Playwright 文档中的 Authentication 页面。

## 第 2 步：启动服务器并预加载会话

Playwright MCP 提供 `--storage-state` 选项，可以把登录会话预加载到一个隔离会话中，因此 Agent 的浏览器打开时就已经登录。下面的片段只用来说明参数；准确的启动命令和客户端配置语法，请以 microsoft/playwright-mcp 仓库的 README 为准。

```bash
# 示意代码，已简化：按 README 替换 <启动命令>
<Playwright MCP 启动命令> \
  --storage-state playwright/.auth/user.json \
  --allowed-origins https://orders.internal.example
```

`--allowed-origins` 参数限制浏览器可以请求哪些源，让 Agent 更难跑到别的网站上去。但 README 明确指出，这个参数不是安全边界。把它当作唯一防线，是设计缺陷。

## 第 3 步：Agent 读快照，而不是猜坐标

Agent 打开页面时，会收到一份描述元素树的快照。每个元素都有一个 ref，例如 `e5`，Agent 在后续工具调用中使用它。Playwright 文档的概括是：不截图，不猜坐标。

下例中的标签来自一个越南语界面的应用：“Order ID”即订单号，“Status”是状态，“Save”是保存按钮。

```text
# 示意快照，已缩短
- textbox "Order ID" [ref=e5]
- combobox "Status" [ref=e7]
- button "Save" [ref=e9]
```

对老旧的内部网页应用来说，这一点差别很大。视觉模型得猜“保存”按钮在哪个像素上；有了快照，Agent 只需说“填写 e5，选择 e7，点击 e9”。即使布局偏移几个像素，按 ref 操作照样能点中。

本步检查：在 Agent 动手之前，让它先列出表单的 ref。如果快照缺少标签，比如某个输入框没有 label，你就找到了 Agent 会选错元素的原因。把它记下来，反馈给客户团队。

## 第 4 步：真正的保护是人

第 2 步说明了 `--allowed-origins` 不足以构成屏障。那么屏障在哪里？MCP 规范给出了答案：始终应有一个人在回路中，并有权拒绝工具调用。规范还建议客户端在敏感操作前请求确认，并保留日志供审计。

在订单示例中，读取快照、填写输入框可以交给 Agent。点击 e9（“保存”）会修改真实数据，必须暂停，等人批准。一条容易执行的规则：凡是无法撤销的操作都需要确认，每次工具调用都要记录日志，连同 ref 和填入的值。

**要点:** 限制域名只能防止 Agent 乱跑；人工批准和审计日志才是真正的保护。

## 第 5 步：用 MCP 探索，用脚本日常运行

官方文档把 MCP 归入专门的智能体循环和探索式自动化这一类。代价是 token：工具 schema 和快照都会占用上下文。对于在大型代码库中工作的编码智能体，例如 Claude Code 或 Copilot，Playwright 推荐使用 CLI。

一项第三方基准测试（不属于官方文档）发现，同一任务通过 MCP 消耗约 114,000 个 token，通过 Playwright CLI 约 27,000 个。

这些数字取决于配置，仅供参考。即便如此，不妨算一笔账，假设每次订单更新的消耗与基准任务完全相同：如果 Agent 每天更新 50 个订单，你要花 5,700,000 个 token，而不是 1,350,000 个。

所以流程一旦清楚，就把它固化为脚本。Playwright codegen 会录制你的操作，并优先使用基于 role、文本和 test id 的定位器。

做法：启动 codegen，然后手动完整重复 Agent 走过的步骤。codegen 会把它们录下来，生成一份便于审查的脚本。它不会转换 e5 这类 ref；在脚本中取代这些 ref 的，是它生成的 role、文本和 test id 定位器。

| 阶段 | 合适的工具 | 原因 |
|---|---|---|
| 流程尚不清楚，界面陌生 | Playwright MCP | Agent 读取快照，自行试探 |
| 流程清楚，需反复运行 | codegen 生成的脚本或 CLI | token 更少，稳定，便于审查 |

## 最常见的错误

第一，提交了认证状态文件，通常是因为生成文件前没有更新 `.gitignore`。第二，以为 `--allowed-origins` 已经足够安全，跳过了确认步骤。第三，在已经稳定的流程上一直跑 MCP，然后被 token 账单吓一跳。

更隐蔽的问题出在界面本身。快照的质量取决于页面的无障碍标签。面对满是无名字段的表单，不要试图写更长的提示词。建议客户补上 label 或 test id，这个小改动对 Agent 和 codegen 脚本都有帮助。

## 这项技能如何写进简历

阅读 FDE 岗位描述时，看到“legacy systems”“internal tools”“browser automation”或“human-in-the-loop”这类字眼，就是提起这项技能的时机。简历上不要只写“用过 Playwright MCP”。

把完整的故事讲出来：为一个没有 API 的系统做了自动化，没让登录会话进入代码仓库，在数据写入前设置了审批步骤，之后改用脚本降低成本。

到客户现场的第一天，第一件事是坐在一位操作员旁边，记下哪些操作可以撤销、哪些不能。这份清单决定了确认步骤放在哪里，往往比你给 Agent 写的任何提示词都重要。

**本周动手试试:**

- 把某个内部网页应用（或演示应用）的登录状态保存到 playwright/.auth，将该目录加入 .gitignore，再用 git status 检查。
- 让 Agent 读取一个表单的快照，列出每个输入框的 ref，并让它在点击保存按钮前停下来请求确认。
- 用 Playwright codegen 录制同一流程，对比脚本中的定位器和 Agent 使用的 ref。

## 信源

- [GitHub - microsoft/playwright-mcp: Playwright MCP server](https://github.com/microsoft/playwright-mcp)

- [Introduction | Playwright](https://playwright.dev/mcp/introduction)

- [The hidden cost of Agentic QA: How Playwright CLI reduced AI token usage by 40x](https://www.tothenew.com/insights/article/hidden-cost-agentic-qa-how-playwright-cli-reduced-ai-token-usage-40x)

- [Authentication | Playwright](https://playwright.dev/docs/auth)

- [Tools - Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)

- [Test generator | Playwright](https://playwright.dev/docs/codegen)
