Doramagic.ai
English

Doramagic 项目包 · 项目说明书

agent-web-interface 项目

面向 AI 代理的 token 高效浏览器自动化 MCP，提供语义化页面快照与稳定的元素 ID。

项目概述与三层架构

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 第 1 层：安装与 CLI 层

继续阅读本节完整说明和来源证据。

章节 第 2 层：协议服务层

继续阅读本节完整说明和来源证据。

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

继续阅读本节完整说明和来源证据。

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），因此传递依赖（[email protected]、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

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

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

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 DialogPage.javascriptDialogOpeningdialog-surface 模块
File pickerPage.fileChooserOpenedfile-picker-surface 模块
PermissionBrowser.permissionsPrompt (或 Page.permissionsState)permission-surface 模块
DownloadBrowser.downloadWillBegindownload-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

关键规则:

数据流(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、[email protected] 等传递依赖存在 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

资料来源：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

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

语义快照生成与元素状态系统（位于 src/snapshot/ 目录）是 agent-web-interface 项目面向 LLM Agent 的核心适配层。它把浏览器真实页面（包括标准 DOM 与各类非 DOM 表面，例如 JavaScript 弹窗、文件选择器、权限提示、下载面板）转换为一种稳定、紧凑、可寻址的语义表示，供 Agent 通过快照消费状态、通过稳定 eid ...

章节 相关页面

继续阅读本节完整说明和来源证据。

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. 快照编译流水线

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 上仍因 [email protected]、js-yaml 等传递依赖存在高危 DoS（#93）；快照系统本身不涉及网络面，但下游安装链受影响。

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

资料来源：src/snapshot/snapshot-compiler.ts:1-40

MCP 工具集与非 DOM 表面统一

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

章节 相关页面

继续阅读本节完整说明和来源证据。

概览与目标

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）仍因 [email protected]、js-yaml 等传递依赖的高危 DoS 处于红态，与本次重构无关；迁移前后应分别核对工具注册表与快照输出，确保非 DOM 节点能正确出现在 Agent 视野中。资料来源：issue #93

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

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 失败模式：security_permissions: 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

high 失败模式：security_permissions: 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

high 失败模式：security_permissions: Represent permission and download non-DOM surfaces

Developers may expose sensitive permissions or credentials: Represent permission and download non-DOM surfaces

high 失败模式：security_permissions: 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

Pitfall Log / 踩坑日志

项目：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 ([email protected], js-yaml)

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

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: high-severity DoS in transitive deps ([email protected], 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

来源：Doramagic 发现、验证与编译记录