# https://github.com/lespaceman/agent-web-interface 项目说明书

生成时间：2026-07-05 12:35:12 UTC

## 目录

- [项目概述与三层架构](#page-1)
- [浏览器生命周期、CDP 与 Worker 管理](#page-2)
- [语义快照生成与元素状态系统](#page-3)
- [MCP 工具集与非 DOM 表面统一](#page-4)

<a id='page-1'></a>

## 项目概述与三层架构

### 相关页面

相关主题：[浏览器生命周期、CDP 与 Worker 管理](#page-2), [语义快照生成与元素状态系统](#page-3), [MCP 工具集与非 DOM 表面统一](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/lespaceman/agent-web-interface/blob/main/README.md)
- [package.json](https://github.com/lespaceman/agent-web-interface/blob/main/package.json)
- [src/index.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/index.ts)
- [src/http-entry.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/http-entry.ts)
- [src/server/mcp-server.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/server/mcp-server.ts)
- [src/server/server-config.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/server/server-config.ts)
</details>

# 项目概述与三层架构

`agent-web-interface` 是一个通过 MCP（Model Context Protocol）协议向 LLM 代理暴露浏览器自动化能力的 npm 包，安装命令为 `npx agent-web-interface install`。项目最新稳定版本为 v4.6.6，遵循"代理看到的页面状态与真实页面状态一致"这一核心设计原则 ([README.md:1-40](), [package.json:1-30]())。

## 项目定位与目标

项目核心使命是把浏览器交互从"特殊工具调用"统一为"快照+动作"的常规模型。具体而言：

- **统一页面表征**：DOM 控件与非 DOM 表面（文件选择器、JavaScript 对话框、权限提示、下载面板）在快照中以一致的 `eid` 形式出现 ([README.md:40-80]())
- **安装即用**：`npx agent-web-interface install` 作为主推入口，旧的 `npx skills add` 路径作为高级备选保留 ([README.md:60-90]())
- **公共契约稳定**：动作工具（click、type、find、get_element 等）以 `eid` 为锚点，跨 DOM 与非 DOM 表面通用

资料来源：[README.md:1-100](), [package.json:1-30]()

## 三层架构总览

```
┌─────────────────────────────────────────────────────┐
│  第 1 层  安装/CLI 层   npx agent-web-interface     │
│           install / doctor / 技能注入               │
├─────────────────────────────────────────────────────┤
│  第 2 层  协议服务层   MCP Server + HTTP Entry      │
│           mcp-server.ts · http-entry.ts             │
├─────────────────────────────────────────────────────┤
│  第 3 层  浏览器自动化层  Playwright/CDP + 非 DOM    │
│           合成 eid 路由 · 文件选择器 · 对话框        │
└─────────────────────────────────────────────────────┘
```

### 第 1 层：安装与 CLI 层

`package.json` 中定义的 `bin` 字段将 `agent-web-interface` 命令映射到 CLI 入口，负责：交互式安装摘要、依赖诊断（`doctor` 子命令）、技能（skill）注入宿主代理。

- 安装路径由 `#73` 引入并明确文档化 ([README.md:60-90]())
- `doctor` 命令用于验证浏览器二进制、权限、网络可达性
- 安装流程在 v4.6.4 (#84) 中修复了三处摘要 UI 缺陷 ([CHANGELOG v4.6.4]())

资料来源：[package.json:20-60](), [src/index.ts:1-40]()

### 第 2 层：协议服务层

协议服务层承载两种入口，由 `server-config.ts` 集中配置：

| 入口 | 文件 | 职责 |
|------|------|------|
| MCP 传输 | `src/server/mcp-server.ts` | 通过 stdio/SSE 暴露工具列表给 LLM 代理 |
| HTTP 桥接 | `src/http-entry.ts` | 为本地控制台与 Web UI 提供 HTTP 接口 |

`server-config.ts` 统一管理端口、headless 开关、用户数据目录、超时阈值等参数，避免在多处硬编码 ([src/server/server-config.ts:1-60]())。MCP 层注册的每个工具都附带详细描述（v4.6.6 的 #99 增强了工具与参数的描述以提升 LLM 可发现性）。

资料来源：[src/server/mcp-server.ts:1-80](), [src/http-entry.ts:1-40](), [src/server/server-config.ts:1-60]()

### 第 3 层：浏览器自动化与非 DOM 表面

最底层是实际的浏览器驱动 + 非 DOM 合成表面实现。该层负责：

1. **DOM 交互**：点击、键入、滚动、选择等基础操作
2. **快照生成**：将 DOM 与非 DOM 表面统一序列化为带 `eid` 的节点树
3. **非 DOM 表面路由**：当点击触发 `alert`、`confirm`、`prompt`、`beforeunload` 或文件选择器时，动作调用立即返回 `non_dom` 块，包含合成控件（确定/取消、路径输入等），后续 `click`/`type` 通过同一 `eid` 寻址 ([#85]())
4. **权限与下载表面**：在需要代理介入时暴露为非 DOM 块，否则放行正常页面交互 ([#88]())

设计上的关键约束：**不再暴露独立的 `upload` 与 `handle_dialog` MCP 工具**——它们的功能由 click/type 通过合成 `eid` 统一承载，仅保留底层模块 ([#92]())。

资料来源：[src/server/mcp-server.ts:80-160](), [src/http-entry.ts:40-100]()

## 关键设计权衡

- **快照优先**：所有动作的输入都是 `eid`（字符串引用），而非选择器或坐标，使得代理无需理解 DOM 结构
- **阻塞语义**：当非 DOM 表面处于活动状态时，作用于底层 DOM 的调用必须先解除阻塞，避免代理感知失真
- **安全审计门禁**：`npm audit` 在 high/critical 级别阻断 CI（[#93]()），因此传递依赖（ws@7.5.10、js-yaml）的高危问题会直接影响发布

资料来源：[package.json:60-120](), [src/server/mcp-server.ts:1-80]()

## 相关社区议题

- PRD 与实施分解：[#85]()、[#86]()、[#87]()、[#88]()、`#89`、`#90`、`#91`
- 工具收敛：[#92]() 移除 upload/handle_dialog
- 安装体验：[#73]()、`#84`
- 安全门禁：[#93]() 传递依赖 DoS

---

<a id='page-2'></a>

## 浏览器生命周期、CDP 与 Worker 管理

### 相关页面

相关主题：[项目概述与三层架构](#page-1), [MCP 工具集与非 DOM 表面统一](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/browser/browser-session-config.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/browser/browser-session-config.ts)
- [src/browser/ensure-browser.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/browser/ensure-browser.ts)
- [src/browser/session-manager.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/browser/session-manager.ts)
- [src/browser/session-manager.types.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/browser/session-manager.types.ts)
- [src/browser/stealth.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/browser/stealth.ts)
- [src/browser/page-registry.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/browser/page-registry.ts)
</details>

# 浏览器生命周期、CDP 与 Worker 管理

## 概述

`agent-web-interface` 是一个面向 LLM 智能体的浏览器自动化 MCP 工具。其核心运行单元是一台受控的 Chromium 浏览器，浏览器由 Node.js 端通过 Chrome DevTools Protocol (CDP) 驱动。围绕"长期可被智能体复用"的浏览器实例，系统抽象出三件事：

- **浏览器生命周期**：负责 headless/headful 模式、用户数据目录、启动参数以及自动恢复。`资料来源：[src/browser/ensure-browser.ts:1-40]()`
- **CDP 会话与页面注册**：单浏览器多 Tab 场景下,每个 Tab 分配独立 CDP 会话并通过 `page-registry` 统一寻址。`资料来源：[src/browser/page-registry.ts:1-30]()`
- **会话/Worker 隔离**：`session-manager` 把逻辑会话与会话内 worker、目标 Tab 绑定,提供给上层 MCP 工具。`资料来源：[src/browser/session-manager.ts:1-60]()`

这三层之间的契约由 `browser-session-config.ts` 集中表达。`资料来源：[src/browser/browser-session-config.ts:1-50]()`

## 浏览器生命周期:从启动到恢复

`ensure-browser.ts` 是浏览器进程的入口守护。其职责分为三段:

1. **检测与启动**:若本地未运行受管浏览器,使用 `puppeteer.launch` 以无头模式启动 Chromium,并注入自定义 `--user-data-dir`,保证持久化状态。`资料来源：[src/browser/ensure-browser.ts:42-90]()`
2. **健康检查与自愈**:若已有浏览器进程但 CDP 端点不可达,自动重启并清理孤儿 profile;`browser-session-config.ts` 中定义的 `headless`、`executablePath`、`proxy` 等可配置字段会在此处被读取。`资料来源：[src/browser/browser-session-config.ts:24-70]()`
3. **隐身配置**:通过 `stealth.ts` 在 `Page.addScriptToEvaluateOnNewDocument` 阶段注入指纹脚本,降低被目标站点识别为自动化的概率,这与 CDP 的 `Target.setAutoAttach` 一起注册。`资料来源：[src/browser/stealth.ts:10-55]()`

## CDP 会话、Page Registry 与 non-DOM 表面

浏览器启动后,工具侧通过 `browser.target()` 与 `target.page()` 取得每个 Tab 的 `CDPSession`。所有 Tab 由 `page-registry` 持有,key 通常为 `sessionId` 或 `targetId`,工具方法(如 `navigate`、`snapshot`)通过该 registry 路由到正确页面。`资料来源：[src/browser/page-registry.ts:30-80]()`

non-DOM 表面(文件选择器、`alert/confirm/prompt`、`beforeunload`、权限弹窗、下载)在 CDP 层会被表达为独立的 `Target` 或 `Page.javascriptDialogOpening` 事件,而非普通 DOM 元素。`session-manager` 将这些事件统一封装成 blocking `non_dom` action,继续通过既有的 `click`/`type` 工具语义处理(参见社区 issue #86、#87、#88、`#92`)。`资料来源：[src/browser/session-manager.ts:80-140]()`

| 表面类型 | CDP 事件 | 注册位置 |
|---|---|---|
| JS Dialog | `Page.javascriptDialogOpening` | `dialog-surface` 模块 |
| File picker | `Page.fileChooserOpened` | `file-picker-surface` 模块 |
| Permission | `Browser.permissionsPrompt` (或 `Page.permissionsState`) | `permission-surface` 模块 |
| Download | `Browser.downloadWillBegin` | `download-surface` 模块 |

`资料来源：[src/browser/session-manager.types.ts:20-90]()`

## Worker 与多智能体隔离

`session-manager.types.ts` 定义了 worker 类型,每个 worker 是 `Session` 下的最小并行单元,拥有自己的 `targetId` 和 CDP 会话,但共享同一 Chromium 进程。`资料来源：[src/browser/session-manager.types.ts:30-100]()`

关键规则:

- **进程内隔离**:通过不同 `BrowserContext` 实现 cookie/localStorage 隔离,而不是拉起新的 Chromium。`资料来源：[src/browser/session-manager.ts:140-200]()`
- **并发上限**:由 `browser-session-config.ts` 中的 `maxWorkers` 控制,避免单个智能体耗尽 CDP 句柄。`资料来源：[src/browser/browser-session-config.ts:60-100]()`
- **优雅退出**:`dispose()` 关闭所有 worker 的 CDP 会话,最后调用 `browser.close()`;失败时通过 `ensure-browser.ts` 的自愈逻辑下次再恢复。`资料来源：[src/browser/session-manager.ts:200-260]()`

## 数据流(Mermaid)

```mermaid
flowchart LR
  A[MCP Tool 调用] --> B[session-manager]
  B --> C{worker 存在?}
  C -- 是 --> D[page-registry 查找 targetId]
  C -- 否 --> E[ensure-browser 自愈]
  E --> D
  D --> F[CDPSession.send]
  F --> G[Chromium Target/Page]
  G -- 事件 --> H{类型}
  H -- JS Dialog --> I[dialog-surface]
  H -- File Picker --> J[file-picker-surface]
  H -- DOM 节点 --> K[DOM 快照]
  I 与 J --> L[合成 non_dom action]
  K --> L
  L --> A
```

## 常见陷阱与社区反馈

- **CDP WebSocket 抖动**:`js-yaml`、`ws@7.5.10` 等传递依赖存在 DoS 漏洞(issue #93),会影响 `browser-session-config.ts` 中的 WebSocket 配置路径,需通过 `npm audit` 在 CI 拦截。`资料来源：[src/browser/browser-session-config.ts:1-20]()`
- **独立工具被合并**:`upload`、`handle_dialog` 工具已下线(issue #92),其能力并入 `click`/`type`,因此后续 CDP 事件接入务必注册到 non-DOM 表面模块,而不是新建 MCP 工具。
- **端到端验证**:non-DOM 表面的端到端验收套件(issue #90)依赖 `page-registry` 的稳定寻址。

资料来源：[src/browser/ensure-browser.ts:1-40]()、[src/browser/session-manager.ts:1-60]()、[src/browser/page-registry.ts:30-80]()、[src/browser/stealth.ts:10-55]()、[src/browser/browser-session-config.ts:24-70]()

---

<a id='page-3'></a>

## 语义快照生成与元素状态系统

### 相关页面

相关主题：[项目概述与三层架构](#page-1), [MCP 工具集与非 DOM 表面统一](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/snapshot/snapshot-compiler.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/snapshot/snapshot-compiler.ts)
- [src/snapshot/snapshot-store.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/snapshot/snapshot-store.ts)
- [src/snapshot/element-resolver.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/snapshot/element-resolver.ts)
- [src/snapshot/node-synthesizer.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/snapshot/node-synthesizer.ts)
- [src/snapshot/node-filter.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/snapshot/node-filter.ts)
- [src/snapshot/kind-mapping.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/snapshot/kind-mapping.ts)
</details>

# 语义快照生成与元素状态系统

## 1. 系统目的与作用范围

`语义快照生成与元素状态系统`（位于 `src/snapshot/` 目录）是 `agent-web-interface` 项目面向 LLM Agent 的核心适配层。它把浏览器真实页面（包括标准 DOM 与各类非 DOM 表面，例如 JavaScript 弹窗、文件选择器、权限提示、下载面板）转换为一种稳定、紧凑、可寻址的语义表示，供 Agent 通过快照消费状态、通过稳定 `eid` 发起动作。该系统统一了"页面状态 → Agent 感知"的边界，使非 DOM 交互不再成为特例，而是与常规 DOM 控件共享同一套快照动作语义——这正是 PRD #85（Unify non-DOM surfaces with snapshot action semantics）所追求的契约。

资料来源：[src/snapshot/snapshot-compiler.ts:1-40]()

## 2. 核心模块划分

| 模块 | 角色 |
|------|------|
| `snapshot-compiler.ts` | 编排入口；接收浏览器原始节点树，过滤 → 合成 → 寻址 → 入库 |
| `snapshot-store.ts` | 维护当前快照、版本号与历史回滚 |
| `element-resolver.ts` | 将语义节点映射到稳定 `eid`，处理重渲染下的重映射 |
| `node-synthesizer.ts` | 为原生 DOM 与非 DOM 表面构造统一节点结构（含合成控件） |
| `node-filter.ts` | 按可见性、角色、白名单策略裁剪噪声节点 |
| `kind-mapping.ts` | 定义 `kind` 枚举，把 HTML / ARIA / 浏览器原生 UI 归一化 |

各模块通过编译管线串联：原始树经过滤进入合成阶段，再经寻址写入存储，最终作为 Agent 工具（如 `find`、`get_element`、`click`、`type`）的输入。

资料来源：[src/snapshot/node-filter.ts:1-30]()、[src/snapshot/node-synthesizer.ts:1-35]()、[src/snapshot/element-resolver.ts:1-40]()

## 3. 快照编译流水线

```mermaid
flowchart LR
    A[原始 DOM/非 DOM 树] --> B[node-filter<br/>可见性+白名单]
    B --> C[node-synthesizer<br/>合成节点+非 DOM 控件]
    C --> D[kind-mapping<br/>归一化 kind]
    D --> E[element-resolver<br/>分配稳定 eid]
    E --> F[snapshot-store<br/>当前快照+版本]
    F --> G[Agent 工具输入]
```

- **过滤**：依据视口可见性、ARIA 角色与白名单丢弃无关节点，减小 token 消耗 资料来源：[src/snapshot/node-filter.ts:30-80]()
- **合成**：为 JavaScript 弹窗、文件选择器等非 DOM 表面追加合成控件（如"确认/取消/输入框"），使 Agent 仍以 `click`/`type` 操作 资料来源：[src/snapshot/node-synthesizer.ts:35-90]()
- **归一化**：`kind-mapping` 把 `<button>`、ARIA `button`、合成按钮统一映射为同一 `kind`，保证工具参数一致 资料来源：[src/snapshot/kind-mapping.ts:1-50]()
- **寻址**：`element-resolver` 在每次快照中重新计算 `eid` 与底层 selector 的绑定，并在 DOM 重渲染后保持引用稳定 资料来源：[src/snapshot/element-resolver.ts:40-110]()
- **存储**：`snapshot-store` 暴露当前快照、版本号与变更原因，供 Agent 工具读取并支持基于 `eid` 的精确动作回放 资料来源：[src/snapshot/snapshot-store.ts:1-60]()

## 4. 非 DOM 表面的统一表达

依据 #85 与 #86/#87/#88，弹窗、文件选择器、权限与下载面板被建模为阻塞型 `non_dom` 节点。它们在快照中拥有与 DOM 节点同构的字段（`eid`、`kind`、属性、状态），但额外携带"阻塞原因"与"合成控件列表"。Agent 无需调用旧式 `upload` 或 `handle_dialog` 专用工具（详见 #92），直接使用 `click`/`type` 即可——后端动作层通过 `eid` 路由到对应非 DOM 模块执行。这一设计把"页面状态"与"动作语义"统一为单一契约。

资料来源：[src/snapshot/snapshot-compiler.ts:40-120]()、[src/snapshot/node-synthesizer.ts:90-160]()

## 5. 与 Agent 工具的协作

- `find`/`get_element` 等读取工具直接查询 `snapshot-store` 的当前快照；
- `click`/`type` 等动作工具以 `eid` 为入参，由 `element-resolver` 反查 selector 或非 DOM 处理器；
- 每次动作完成后，`snapshot-compiler` 触发增量或全量重编译，更新版本号；
- 当检测到阻塞性非 DOM 表面时，动作工具立即返回 `non_dom` 节点集合，强制 Agent 下一轮基于新快照决策（参考 #86 的 tracer-bullet 路径）。

资料来源：[src/snapshot/snapshot-compiler.ts:120-200]()、[src/snapshot/snapshot-store.ts:60-140]()

## 6. 边界与设计权衡

- **过滤可逆性**：被裁剪节点若后续被交互触及，需通过"懒展开"策略重新进入快照，避免 Agent 看不到关键控件 资料来源：[src/snapshot/node-filter.ts:80-140]()
- **eid 稳定性**：依赖选择器指纹 + 角色 + 文本摘要，重渲染或微调文案时尽量复用同一 `eid`，降低 Agent 重新寻址成本 资料来源：[src/snapshot/element-resolver.ts:110-180]()
- **非 DOM 边界**：仅在浏览器真正接管 UI（弹窗/选择器/权限/下载）时合成，避免污染普通 DOM 快照 资料来源：[src/snapshot/node-synthesizer.ts:160-220]()
- **安全约束**：当前 `npm audit` 在 `main` 上仍因 `ws@7.5.10`、`js-yaml` 等传递依赖存在高危 DoS（#93）；快照系统本身不涉及网络面，但下游安装链受影响。

资料来源：[src/snapshot/kind-mapping.ts:50-120]()、[src/snapshot/snapshot-store.ts:140-200]()

---

<a id='page-4'></a>

## MCP 工具集与非 DOM 表面统一

### 相关页面

相关主题：[项目概述与三层架构](#page-1), [语义快照生成与元素状态系统](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/tools/tool-registration.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/tools/tool-registration.ts)
- [src/tools/interaction-tools.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/tools/interaction-tools.ts)
- [src/tools/observation-tools.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/tools/observation-tools.ts)
- [src/tools/form-tools.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/tools/form-tools.ts)
- [src/non-dom/dialog.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/non-dom/dialog.ts)
- [src/non-dom/file-picker.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/non-dom/file-picker.ts)
- [src/non-dom/permission.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/non-dom/permission.ts)
- [src/non-dom/download.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/non-dom/download.ts)
- [src/snapshots/snapshot.ts](https://github.com/lespaceman/agent-web-interface/blob/main/src/snapshots/snapshot.ts)
- [src/skills/agent-web-interface.md](https://github.com/lespaceman/agent-web-interface/blob/main/src/skills/agent-web-interface.md)
- [tests/e2e/non-dom.test.ts](https://github.com/lespaceman/agent-web-interface/blob/main/tests/e2e/non-dom.test.ts)
</details>

# MCP 工具集与非 DOM 表面统一

## 概览与目标

agent-web-interface 通过 MCP（Model Context Protocol）向 LLM Agent 暴露一组浏览器自动化工具。`tool-registration.ts` 在启动时统一注册各模块导出的工具定义，使 Agent 在调用前能发现 schema 与参数语义。资料来源：[src/tools/tool-registration.ts:1-120]()

传统实现中，文件选择器、JS 对话框、权限提示、下载面板等「非 DOM 表面」被作为特例处理：Agent 需要调用独立的 `upload` 与 `handle_dialog` 工具，且这些状态在快照中并不可见。#85 提出 PRD，要求把上述表面统一为快照中的 `non_dom` 合成控件，由 `click` / `type` 等通用动作直接操作，让 Agent 的认知与浏览器真实状态保持一致。资料来源：[issue #85]() [issue #92]()

## 工具集的分层结构

`tool-registration.ts` 按职责挂载不同模块：

| 模块 | 职责 | 代表工具 |
| --- | --- | --- |
| `navigation-tools.ts` | 标签页、URL 切换 | `navigate`, `tab_*` |
| `observation-tools.ts` | 读取页面与元素状态 | `snapshot`, `find`, `get_element` |
| `interaction-tools.ts` | 对元素执行动作 | `click`, `type`, `hover` |
| `form-tools.ts` | 表单级复合操作 | `fill`, `submit` |

所有工具通过 `tool-registration.ts` 注入统一描述与参数 schema，便于 LLM 在调用前发现并区分它们。资料来源：[src/tools/tool-registration.ts:20-140]() [src/tools/interaction-tools.ts:1-80]() [src/tools/observation-tools.ts:1-60]()

## 非 DOM 表面统一模型

统一后，浏览器控制的非 DOM 交互以 `non_dom` 节点出现在快照中，并附带稳定 `eid`：

- **对话框（#86）**：`alert` / `confirm` / `prompt` / `beforeunload` 触发时，对应动作立即返回，并在响应中暴露 `non_dom` 表面，Agent 可对合成按钮或输入框执行 `click` / `type`。资料来源：[src/non-dom/dialog.ts:1-160]()
- **文件选择器（#87）**：`click` 命中 DOM 上传控件后弹出 picker，由 `file-picker.ts` 暴露路径输入与 `choose` / `save` 合成控件，取代旧 `upload` 工具。资料来源：[src/non-dom/file-picker.ts:1-180]()
- **权限与下载（#88）**：阻塞型权限提示和需要 Agent 关注的下载面板由 `permission.ts` 与 `download.ts` 渲染为同一 `non_dom` 形态；非阻塞结果则继续走普通页面交互，不进入非 DOM 表面。资料来源：[src/non-dom/permission.ts:1-140]() [src/non-dom/download.ts:1-140]()

`snapshot.ts` 在生成快照时检测这些表面并附加 `non_dom` 节点，使 `find` / `get_element` 走同一套 `eid` 路由。资料来源：[src/snapshots/snapshot.ts:1-220]() [src/tools/observation-tools.ts:60-200]()

## 工具面收敛与迁移

统一后，#92 删除独立的 `upload` 与 `handle_dialog` MCP 工具，但保留底层 `non-dom` 模块作为内部组件。迁移路径如下：

1. `click` 命中上传控件 → 返回 `non_dom` 文件选择器 → Agent 对合成 `eid` 调 `type` 写入路径、`click` 触发 `choose`。资料来源：[src/tools/interaction-tools.ts:80-240]()
2. JS 对话框 → `click` / `type` 直接作用于合成按钮或输入框，不再需要专用工具。资料来源：[src/non-dom/dialog.ts:80-220]()
3. `tool-registration.ts` 从导出列表中移除 `upload` / `handle_dialog`，并更新工具描述以引导 Agent 使用新流程。资料来源：[src/tools/tool-registration.ts:140-240]()

## 验收、技能与边界

端到端验收（#90）在 `tests/e2e/non-dom.test.ts` 中覆盖：阻塞对话框、文件选择器、权限/下载表面、合成 `eid` 路由，以及 `find` / `get_element` 在非 DOM 节点上的行为一致性。资料来源：[tests/e2e/non-dom.test.ts:1-280]()

`src/skills/agent-web-interface.md`（#89）同步更新，指导 Agent 把所有非 DOM 交互视为普通快照节点：先 `snapshot`、再 `find`、再对合成 `eid` 发起动作，避免再走旧工具链。资料来源：[src/skills/agent-web-interface.md:1-180]()

需要注意的边界：上述 PR 系列（#86–#92）尚未合并入主干时，`Security Audit` CI（#93）仍因 `ws@7.5.10`、`js-yaml` 等传递依赖的高危 DoS 处于红态，与本次重构无关；迁移前后应分别核对工具注册表与快照输出，确保非 DOM 节点能正确出现在 Agent 视野中。资料来源：[issue #93]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：lespaceman/agent-web-interface

摘要：发现 32 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: Add end-to-end acceptance suite for non-DOM surfaces。

## 1. 安全/权限坑 · 失败模式：security_permissions: Add end-to-end acceptance suite for non-DOM surfaces

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Add end-to-end acceptance suite for non-DOM surfaces
- 对用户的影响：Developers may expose sensitive permissions or credentials: Add end-to-end acceptance suite for non-DOM surfaces
- 证据：failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/90 | Add end-to-end acceptance suite for non-DOM surfaces

## 2. 安全/权限坑 · 失败模式：security_permissions: PRD: Unify non-DOM surfaces with snapshot action semantics

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: PRD: Unify non-DOM surfaces with snapshot action semantics
- 对用户的影响：Developers may expose sensitive permissions or credentials: PRD: Unify non-DOM surfaces with snapshot action semantics
- 证据：failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/85 | PRD: Unify non-DOM surfaces with snapshot action semantics

## 3. 安全/权限坑 · 失败模式：security_permissions: Represent permission and download non-DOM surfaces

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Represent permission and download non-DOM surfaces
- 对用户的影响：Developers may expose sensitive permissions or credentials: Represent permission and download non-DOM surfaces
- 证据：failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/88 | Represent permission and download non-DOM surfaces

## 4. 安全/权限坑 · 失败模式：security_permissions: Update agent-web-interface skill for non-DOM surfaces

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Update agent-web-interface skill for non-DOM surfaces
- 对用户的影响：Developers may expose sensitive permissions or credentials: Update agent-web-interface skill for non-DOM surfaces
- 证据：failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/89 | Update agent-web-interface skill for non-DOM surfaces

## 5. 安装坑 · 失败模式：installation: Release v4.4.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Release v4.4.0
- 对用户的影响：Upgrade or migration may change expected behavior: Release v4.4.0
- 证据：failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.4.0 | Release v4.4.0

## 6. 安装坑 · 失败模式：installation: Release v4.6.2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Release v4.6.2
- 对用户的影响：Upgrade or migration may change expected behavior: Release v4.6.2
- 证据：failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.6.2 | Release v4.6.2

## 7. 安装坑 · 失败模式：installation: Release v4.6.3

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Release v4.6.3
- 对用户的影响：Upgrade or migration may change expected behavior: Release v4.6.3
- 证据：failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.6.3 | Release v4.6.3

## 8. 安装坑 · 失败模式：installation: Release v4.6.4

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Release v4.6.4
- 对用户的影响：Upgrade or migration may change expected behavior: Release v4.6.4
- 证据：failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.6.4 | Release v4.6.4

## 9. 安装坑 · 失败模式：installation: Release v4.6.5

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Release v4.6.5
- 对用户的影响：Upgrade or migration may change expected behavior: Release v4.6.5
- 证据：failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.6.5 | Release v4.6.5

## 10. 安装坑 · 失败模式：installation: Remove upload and handle_dialog MCP tools

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Remove upload and handle_dialog MCP tools
- 对用户的影响：Developers may fail before the first successful local run: Remove upload and handle_dialog MCP tools
- 证据：failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/92 | Remove upload and handle_dialog MCP tools

## 11. 安装坑 · 失败模式：installation: Security: high-severity DoS in transitive deps (ws@7.5.10, js-yaml)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Security: high-severity DoS in transitive deps (ws@7.5.10, js-yaml)
- 对用户的影响：Developers may fail before the first successful local run: Security: high-severity DoS in transitive deps (ws@7.5.10, js-yaml)
- 证据：failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/93 | Security: high-severity DoS in transitive deps (ws@7.5.10, js-yaml)

## 12. 安装坑 · 失败模式：installation: docs: README quickstart + CHANGELOG for install/doctor

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: docs: README quickstart + CHANGELOG for install/doctor
- 对用户的影响：Developers may fail before the first successful local run: docs: README quickstart + CHANGELOG for install/doctor
- 证据：failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/73 | docs: README quickstart + CHANGELOG for install/doctor

## 13. 安装坑 · 来源证据：Implement blocking dialog surfaces with synthetic controls

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Implement blocking dialog surfaces with synthetic controls
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lespaceman/agent-web-interface/issues/86 | 来源类型 github_issue 暴露的待验证使用条件。

## 14. 安装坑 · 来源证据：Remove upload and handle_dialog MCP tools

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Remove upload and handle_dialog MCP tools
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lespaceman/agent-web-interface/issues/92 | 来源类型 github_issue 暴露的待验证使用条件。

## 15. 安装坑 · 来源证据：Replace upload with file picker non-DOM surfaces

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Replace upload with file picker non-DOM surfaces
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lespaceman/agent-web-interface/issues/87 | 来源类型 github_issue 暴露的待验证使用条件。

## 16. 安装坑 · 来源证据：docs: README quickstart + CHANGELOG for install/doctor

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：docs: README quickstart + CHANGELOG for install/doctor
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lespaceman/agent-web-interface/issues/73 | 来源类型 github_issue 暴露的待验证使用条件。

## 17. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/lespaceman/agent-web-interface | host_targets=mcp_host, claude

## 18. 配置坑 · 失败模式：configuration: Release v4.5.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Release v4.5.0
- 对用户的影响：Upgrade or migration may change expected behavior: Release v4.5.0
- 证据：failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.5.0 | Release v4.5.0

## 19. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/lespaceman/agent-web-interface | README/documentation is current enough for a first validation pass.

## 20. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/lespaceman/agent-web-interface | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/lespaceman/agent-web-interface | no_demo; severity=medium

## 22. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/lespaceman/agent-web-interface | no_demo; severity=medium

## 23. 安全/权限坑 · 来源证据：Add end-to-end acceptance suite for non-DOM surfaces

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add end-to-end acceptance suite for non-DOM surfaces
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lespaceman/agent-web-interface/issues/90 | 来源类型 github_issue 暴露的待验证使用条件。

## 24. 安全/权限坑 · 来源证据：PRD: Unify non-DOM surfaces with snapshot action semantics

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：PRD: Unify non-DOM surfaces with snapshot action semantics
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lespaceman/agent-web-interface/issues/85 | 来源类型 github_issue 暴露的待验证使用条件。

## 25. 安全/权限坑 · 来源证据：Represent permission and download non-DOM surfaces

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Represent permission and download non-DOM surfaces
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lespaceman/agent-web-interface/issues/88 | 来源类型 github_issue 暴露的待验证使用条件。

## 26. 安全/权限坑 · 来源证据：Security: high-severity DoS in transitive deps (ws@7.5.10, js-yaml)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: high-severity DoS in transitive deps (ws@7.5.10, js-yaml)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lespaceman/agent-web-interface/issues/93 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 27. 安全/权限坑 · 来源证据：Update agent-web-interface skill for non-DOM surfaces

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Update agent-web-interface skill for non-DOM surfaces
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lespaceman/agent-web-interface/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。

## 28. 能力坑 · 失败模式：capability: Implement blocking dialog surfaces with synthetic controls

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Implement blocking dialog surfaces with synthetic controls
- 对用户的影响：Developers may hit a documented source-backed failure mode: Implement blocking dialog surfaces with synthetic controls
- 证据：failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/86 | Implement blocking dialog surfaces with synthetic controls

## 29. 能力坑 · 失败模式：conceptual: Replace upload with file picker non-DOM surfaces

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Replace upload with file picker non-DOM surfaces
- 对用户的影响：Developers may hit a documented source-backed failure mode: Replace upload with file picker non-DOM surfaces
- 证据：failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/87 | Replace upload with file picker non-DOM surfaces

## 30. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/lespaceman/agent-web-interface | issue_or_pr_quality=unknown

## 31. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/lespaceman/agent-web-interface | release_recency=unknown

## 32. 维护坑 · 失败模式：maintenance: Release v4.6.6

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Release v4.6.6
- 对用户的影响：Upgrade or migration may change expected behavior: Release v4.6.6
- 证据：failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.6.6 | Release v4.6.6

<!-- canonical_name: lespaceman/agent-web-interface; human_manual_source: deepwiki_human_wiki -->