AI Helper 文档中心

主题

网页增强工具 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与优化建议
  8. 故障排查指南
  9. 结论
  10. 附录：使用示例与最佳实践

引言 ​

本文件面向“网页增强工具”的开发者与使用者，系统性说明扩展端（Chrome Manifest V3）与本地 Agent 端的协作方式，并重点聚焦以下能力：

  • 信息提取：文本与结构化数据、表格、链接、表单、图片、元数据、JSON-LD/Microdata、iframe 内容、页面内搜索。
  • 交互操作：元素定位与点击、表单填写与提交、滚动与导航控制、键盘输入模拟、弹窗处理、等待稳定。
  • 截图与图像处理：全页截图、区域选择截图、图片预览与压缩、视觉识别集成。
  • Shadow DOM 穿透与跨域 iframe 访问策略。
  • 快照编排与 ref 跨帧路由，支撑 query_elements → interact_element/fill_form/select_dropdown 的稳定引用。
  • 性能优化、常见问题排查与最佳实践。

本项目为双进程架构：扩展端（src/）+ 独立本地代理端 Agent（agent/src/server.js）。两端版本号同步，当前以 2.3.1 为准。扩展端通过本地 HTTP/WebSocket 调用 Agent 的文件读写、命令执行、长期记忆与 RAG 能力；Agent 源码修改后需重启进程才生效。

项目结构 ​

围绕“网页增强工具”，关键代码分布在 content 脚本（页面侧）、background 工具定义与编排器（后台侧）、共享渲染器（快照输出），以及 side panel 的图片处理入口。

graph TB
subgraph "Content Script页面侧"
PE["page-extract.js<br/>元数据/链接/表单/图片/Markdown/JSON/iframe/搜索"]
PI["page-interaction.js<br/>交互元素查询/树构建/ref注册"]
IT["interaction-tools.js<br/>点击/滚动/等待/键盘/上传/下拉/存储"]
SDU["shadow-dom-utils.js<br/>Shadow DOM/iframe 深度查询"]
PU["page-utils.js<br/>选择器/高亮/auto-wait/富文本填充"]
end
subgraph "Background后台侧"
BT["browser-tools.js<br/>工具定义与参数Schema"]
SO["snapshot-orchestrator.js<br/>query_elements 编排/跨帧路由"]
TE["tool-executor.js<br/>工具执行/截图/视觉识别/消息重试"]
TH["tool-helpers.js<br/>参数解析/结果归一化/注入重试"]
TS["tool-screenshot.js<br/>截图下载触发"]
end
subgraph "Shared共享"
PSR["page-snapshot-renderer.js<br/>快照唯一渲染出口"]
end
subgraph "Side Panel侧面板"
IH["image-helpers.js<br/>全页/区域截图/裁剪/预览"]
end
PE --> SDU
PE --> PU
PI --> SDU
PI --> PU
IT --> SDU
IT --> PU
BT --> SO
SO --> PSR
TE --> SO
TE --> TH
TE --> TS
IH --> TE

图表来源

章节来源

核心组件 ​

  • 信息提取工具（content/page-extract.js）
    • 元数据：title/description/keywords/author、Open Graph/Twitter Card、canonical、JSON-LD、Microdata。
    • 链接：a/img 链接，支持内外链过滤、可选包含图片。
    • 表单：input/textarea/select 字段结构、必填、占位符、选项列表、生成选择器。
    • 图片：尺寸过滤、背景图抽取、批量下载（限前若干张）。
    • Markdown/JSON：页面转 Markdown、结构化 JSON（tables/lists/jsonLd/articles/microdata）。
    • iframe：同源可访问时提取 title/text/htmlLength，支持嵌套。
    • 搜索：plain/regex 模式、大小写敏感、上下文片段、可选 Range 高亮。
  • 交互操作工具（content/interaction-tools.js）
    • 点击：deepQuerySelector + autoWaitAfterAction，自动检测 URL/DOM 变化。
    • 表单填写：text/select/checkbox/radio/contenteditable，绕过 React 受控组件。
    • 滚动：top/bottom/coordinates/selector，边界判定与无进展标记。
    • 可见性检查：display/visibility/opacity/clip-path/视口判定。
    • 等待：appeared/disappeared/visible/hidden，轮询超时。
    • 键盘输入：InputEvent/KeyboardEvent，兼容富文本编辑器。
    • 文件上传：DataTransfer + Blob/File，base64 解码回退。
    • 按文本点击：遍历可交互元素，精确/包含匹配，诊断错误原因。
    • 下拉选择：原生 select 与自定义下拉（div+ul+li），超时匹配。
    • Storage 管理：session/localStorage get/set/remove/clear。
  • Shadow DOM 与 iframe 穿透（content/shadow-dom-utils.js）
    • deepQuerySelector/All：优先 Shadow DOM，再当前根，跳过跨域 iframe。
    • deepGetText/Html：合并 body.innerText/shadow tree/iframe 内容。
    • 选择范围/坐标：跨 iframe 偏移修正。
    • 监听器：selectionchange 多 root 附加/移除。
  • 交互元素查询与快照（content/page-interaction.js + shared/page-snapshot-renderer.js）
    • 可交互元素遍历、角色推导、名称解析、属性序列化。
    • 叠加层（dialog/popover/menu/listbox）分区，打开层子树独立。
    • ref 编号：WeakMap 跨快照复用，失效时 selector 兜底重查。
    • renderSnapshot：统一渲染入口，分页/预算/帧区块头/截断提示。
  • Background 工具定义与编排（background/tools/browser-tools.js + snapshot-orchestrator.js）
    • browser-tools.js：interact_element/scroll_to/wait_element/handle_dialog/fill_form/keyboard_input/file_upload/select_dropdown/page_content/extract_data/query_elements/search_in_page/iframe_content/scroll_collect 等工具 Schema。
    • snapshot-orchestrator.js：webNavigation 帧枚举 → 并行定向收集各帧 ops → frame 节点三重对应 → 全局 ref 编号表 → 渲染 frames[]。
    • 跨帧路由：shouldRouteRefTool/routeSingleRefTool/routeFillForm，失败时提供最近有效 ref 建议。
  • 工具执行与辅助（background/tool-executor.js + tool-helpers.js）
    • 工具分发、MCP/RAG 动态注册、网络访问校验、截图下载、视觉识别 API 调用。
    • tryParseToolArgs：两阶段解析 + 位置引导修复 + 尾随逗号/未引号字符串/括号补全。
    • normalizeToolResult：统一 {success,content,...} 返回格式。
    • sendToContentScriptWithRetry：失败自动注入 content script 并重试。
  • 截图与图像处理（background/tool-screenshot.js + side_panel/image-helpers.js）
    • 全页截图：CAPTURE_TAB → dataUrl → 压缩/预览。
    • 区域截图：START_REGION_SELECTION → rect → CAPTURE_TAB → Canvas 裁剪 → 预览。
    • 下载：triggerScreenshotDownload(dataUrl, format)。

章节来源

架构总览 ​

下图展示一次典型的“查询元素 → 跨帧路由 → 目标帧交互”的端到端流程。

sequenceDiagram
participant User as "用户/模型"
participant BG as "Background 工具执行器"
participant Orchestrator as "快照编排器"
participant ContentTop as "顶层 Content Script"
participant FrameA as "子帧 Content Script"
participant Renderer as "快照渲染器"
User->>BG : 调用 query_elements(args)
BG->>Orchestrator : executeSnapshotQuery(args)
Orchestrator->>ContentTop : SNAPSHOT_COLLECT(frames=auto)
Orchestrator->>FrameA : SNAPSHOT_COLLECT(frames=auto)
ContentTop-->>Orchestrator : overlayTrees/bodyTree/frameInfo
FrameA-->>Orchestrator : overlayTrees/bodyTree/frameInfo
Orchestrator->>Renderer : renderSnapshot(frames[])
Renderer-->>User : 文本快照含 [ref N]
User->>BG : 调用 interact_element(ref=N, action=click)
BG->>Orchestrator : shouldRouteRefTool()
Orchestrator->>FrameA : INTERACT_ELEMENT(ref=local, _frameRouted=true)
FrameA-->>Orchestrator : 结果可能带 suggestions
Orchestrator-->>User : 翻译后的结果含全局 ref 建议

图表来源

详细组件分析 ​

信息提取工具（page-extract.js） ​

  • 元数据提取
    • 读取 meta[property|name]、og:、twitter:、article:*、canonical。
    • 解析 JSON-LD（支持 @graph 数组）与 Microdata（itemscope/itemprop）。
  • 链接提取
    • a[href]/img[src]，区分内外链，可选 includeImages。
  • 表单提取
    • input/textarea/select，记录 name/id/type/placeholder/required/options，生成选择器。
  • 图片提取
    • 尺寸过滤、背景图抽取、可选下载（限制数量）。
  • Markdown/JSON 转换
    • 递归遍历 DOM，输出 Markdown；或结构化 tables/lists/jsonLd/articles/microdata。
  • iframe 内容
    • 仅同源可访问，返回 selector/url/title/textContent/htmlLength，支持嵌套。
  • 页面内搜索
    • plain/regex 模式，caseSensitive，contextLength，maxResults，highlight（Range 包裹，SEC-08）。
flowchart TD
Start(["开始"]) --> Meta["提取元数据<br/>meta/og/twitter/jsonld/microdata"]
Meta --> Links["提取链接<br/>a/img 内外链过滤"]
Links --> Forms["提取表单<br/>input/textarea/select"]
Forms --> Images["提取图片<br/>尺寸/背景图/下载"]
Images --> ToMD["页面转 Markdown"]
ToMD --> ToJSON["页面转结构化 JSON"]
ToJSON --> Iframe["iframe 内容<br/>同源可访问"]
Iframe --> Search["页面内搜索<br/>plain/regex/highlight"]
Search --> End(["结束"])

图表来源

章节来源

交互操作工具（interaction-tools.js） ​

  • 点击与自动等待
    • clickElement(selector) 先 deepQuerySelector，点击后 autoWaitAfterAction，报告 URL/DOM 变化。
  • 表单填写
    • fillForm(fields)：text/select/checkbox/radio/contenteditable；React 受控组件用 setNativeValue。
  • 滚动与导航
    • scrollToPosition(options)：top/bottom/coordinates/selector，边界判定与 moved=false 标记。
  • 可见性与等待
    • isElementTrulyVisible(el)：display/visibility/opacity/尺寸/视口。
    • waitForElement(selector, state, timeout)：appeared/disappeared/visible/hidden。
  • 键盘输入
    • keyboardInput({key,text,...})：InputEvent/KeyboardEvent，富文本 execCommand 回退。
  • 文件上传
    • fileUpload(selector, fileName, fileContent, fileType)：Blob/File/DataTransfer。
  • 按文本点击
    • clickByText(text, options)：遍历可交互元素，精确/包含匹配，诊断 textNotFound/textHidden/textNotClickable。
  • 下拉选择
    • selectDropdown(triggerSelector, optionText, optionSelector, timeout)：原生 select 与自定义下拉。
  • Storage 管理
    • manageStorage({action, storage, key, value})：get/set/remove/clear。
flowchart TD
A["点击元素"] --> B{"是否检测到变化？"}
B --> |是| C["报告导航/DOM 变化"]
B --> |否| D["完成"]
E["填写表单"] --> F{"字段类型？"}
F --> |text| G["setNativeValue + input/change"]
F --> |select| H["设置 value + change"]
F --> |checkbox/radio| I["checked + change"]
F --> |contenteditable| J["fillContentEditable"]
K["滚动到目标"] --> L{"目标类型？"}
L --> |top/bottom| M["scrollTo(0/scrollHeight)"]
L --> |coordinates| N["scrollTo(x,y)"]
L --> |selector| O["scrollIntoView(...)"]
P["键盘输入"] --> Q{"文本 or 按键？"}
Q --> |文本| R["InputEvent insertText"]
Q --> |按键| S["KeyboardEvent keydown/keypress/keyup"]

图表来源

章节来源

Shadow DOM 穿透与跨域 iframe 访问 ​

  • deepQuerySelector/All：优先 Shadow DOM，再当前根；IFRAME/FRAME 同源可访问时递归；跨域抛错捕获跳过。
  • deepGetText/Html：Document.body.innerText 或 ShadowRoot.textContent；IFRAME 同源可访问时追加内容。
  • 选择范围与坐标：跨 iframe 累加 frameElement.getBoundingClientRect 偏移。
  • selectionchange 监听：attachSelectionListeners/removeSelectionListeners 多 root 管理。
flowchart TD
S["deepQuerySelector(selector, root)"] --> CheckShadow{"root.querySelectorAll ?"}
CheckShadow --> |是| ForEach["遍历 * 元素"]
ForEach --> HasShadow{"el.shadowRoot ?"}
HasShadow --> |是| RecurseShadow["递归 shadowRoot"]
HasShadow --> |否| IsIframe{"el.tagName === IFRAME/FRAME ?"}
IsIframe --> |是| TryDoc["try contentDocument/contentWindow.document"]
TryDoc --> Found{"找到文档？"}
Found --> |是| RecurseIframe["递归 iframeDoc"]
Found --> |否| Next["下一个元素"]
RecurseShadow --> Next
RecurseIframe --> Next
CheckShadow --> |否| QuerySel["root.querySelector(selector)"]
QuerySel --> Return["返回匹配元素或 null"]

图表来源

章节来源

交互元素查询与快照（page-interaction.js + page-snapshot-renderer.js） ​

  • 可交互元素遍历：role 推导、isInteractiveElement、isSubtreePruned/isElementHidden。
  • 名称解析链：select 选中项 → aria-labelledby → aria-label → label[for]/包裹 label → placeholder → title → alt → input button value → 直接文本 → 前兄弟文本。
  • 属性序列化：href/type/placeholder/value/checked/selected。
  • 树构建：overlayTrees（打开层）与 bodyTree（主体），iframe 在 auto 模式下作为 frame 节点。
  • ref 编号：WeakMap 跨快照复用，失效时 selector 兜底重查；collectRefSuggestions 提供附近有效 ref。
  • renderSnapshot：frames[] 先序流，分页/字符预算/截断提示，frame 区块头与 host 片段。
classDiagram
class PageInteraction {
+queryInteractiveElements(options)
+collectSnapshotOps(options)
+getElementCount(selector, includeHidden)
+scrollAndCollect(args)
+interactByRef(ref, action, options)
-registerElement(el, role, name)
-resolveByRef(ref)
-buildAttributeText(el, role)
-resolveAccessibleName(el, role)
}
class SnapshotRenderer {
+renderSnapshot(options)
-collectMatchedNodes(nodes, out)
-renderNode(node, lines, ctx)
-renderFrameSection(frame, lines, ctx)
}
PageInteraction --> SnapshotRenderer : "输出结构化 ops"

图表来源

章节来源

Background 工具定义与快照编排（browser-tools.js + snapshot-orchestrator.js） ​

  • browser-tools.js：定义所有浏览器相关工具的 id/category/execution/parameters，如 interact_element、scroll_to、wait_element、handle_dialog、fill_form、keyboard_input、file_upload、select_dropdown、page_content、extract_data、query_elements、search_in_page、iframe_content、scroll_collect。
  • snapshot-orchestrator.js：
    • 帧规划：planFrames(allFrames)，depth≤3，MAX_VISIBLE_FRAMES=20。
    • 并行收集：collectFrame(tabId, frameId, isTop, ...)，子帧超时 400ms，顶层 5000ms。
    • 三重对应：sameOriginHref/srcUrl/orderInParent 匹配 frame 节点。
    • 全局 ref 编号：fwd/rev 双表维护，tab 维度，loadId 重载作废。
    • 跨帧路由：shouldRouteRefTool/routeSingleRefTool/routeFillForm，失败时 suggestions 翻译为全局 ref。
flowchart TD
A["executeSnapshotQuery(args)"] --> B{"frames='none'?"}
B --> |是| C["executeTopOnlyQuery -> renderSnapshot(local refs)"]
B --> |否| D["getAllFrames -> planFrames"]
D --> E["并行 collectFrame(effective frames)"]
E --> F["statuses: ok/unreachable/hidden"]
F --> G["frameIndexMap + replaceRefsWithGlobals"]
G --> H["markFrameNodes(triple match)"]
H --> I["renderSnapshot(frames[], global refs)"]

图表来源

章节来源

工具执行与辅助（tool-executor.js + tool-helpers.js） ​

  • 工具执行：分发到 background/content_script，MCP/RAG 动态注册，网络访问校验，截图下载，视觉识别 API。
  • 参数解析：tryParseToolArgs 两阶段解析 + 位置引导修复 + 尾随逗号/未引号字符串/括号补全 + fixArrayObjectMismatch。
  • 结果归一化：normalizeToolResult 统一 {success,content,...}。
  • 注入重试：sendToContentScriptWithRetry 失败自动注入 content script 并重试。
  • 截图下载：triggerScreenshotDownload(dataUrl, format)。
flowchart TD
A["收到工具调用"] --> B["tryParseToolArgs(argsStr)"]
B --> C{"解析成功？"}
C --> |是| D["执行 handler"]
C --> |否| E["记录警告/返回空"]
D --> F["normalizeToolResult(result)"]
F --> G{"需要截图？"}
G --> |是| H["triggerScreenshotDownload(dataUrl,format)"]
G --> |否| I["返回结果"]

图表来源

章节来源

截图与图像处理（tool-screenshot.js + image-helpers.js） ​

  • 全页截图：side_panel/image-helpers.js 发送 CAPTURE_TAB，获取 dataUrl，压缩并附加预览。
  • 区域截图：START_REGION_SELECTION 获取 rect，CAPTURE_TAB 后 Canvas 裁剪，再压缩预览。
  • 下载：background/tool-screenshot.js 触发 chrome.downloads.download。
sequenceDiagram
participant SP as "Side Panel"
participant BG as "Background"
participant CS as "Content Script"
SP->>CS : START_REGION_SELECTION
CS-->>SP : rect (x,y,width,height)
SP->>BG : CAPTURE_TAB
BG-->>SP : dataUrl
SP->>SP : cropImage(dataUrl, rect)
SP->>SP : compressAndAttachImage(blob)
SP->>BG : triggerScreenshotDownload(dataUrl, format)

图表来源

章节来源

依赖关系分析 ​

  • content 脚本内部依赖：
    • page-extract.js 依赖 shadow-dom-utils.js 与 page-utils.js。
    • interaction-tools.js 依赖 shadow-dom-utils.js、page-utils.js、page-interaction.js。
    • page-interaction.js 依赖 shadow-dom-utils.js、page-utils.js、page-snapshot-renderer.js。
  • background 与 content 通信：
    • browser-tools.js 定义工具 Schema，由 tool-executor.js 分发。
    • snapshot-orchestrator.js 协调 webNavigation 帧与 content script 的消息传递。
    • tool-helpers.js 提供通用辅助（参数解析、结果归一化、注入重试）。
  • 共享渲染器：
    • page-snapshot-renderer.js 被 page-interaction.js 与 snapshot-orchestrator.js 共用，保证快照输出一致性。
graph LR
PE["page-extract.js"] --> SDU["shadow-dom-utils.js"]
PE --> PU["page-utils.js"]
IT["interaction-tools.js"] --> SDU
IT --> PU
IT --> PI["page-interaction.js"]
PI --> SDU
PI --> PU
PI --> PSR["page-snapshot-renderer.js"]
BT["browser-tools.js"] --> SO["snapshot-orchestrator.js"]
SO --> PSR
TE["tool-executor.js"] --> SO
TE --> TH["tool-helpers.js"]
TE --> TS["tool-screenshot.js"]

图表来源

章节来源

性能与优化建议 ​

  • 避免重写 innerHTML：搜索高亮使用 Range.surroundContents（SEC-08），保留事件监听与框架虚拟 DOM 关联。
  • 控制快照字符预算：renderSnapshot 使用 maxChars 预算，容器行盲扣预算，避免大页面阻塞。
  • 限制 iframe 展开：MAX_VISIBLE_FRAMES=20，MAX_FRAME_DEPTH=3，超限计入 excludedIds。
  • 自动等待稳定：autoWaitAfterAction 最小等待 + 连续稳定计数，减少无效阻塞。
  • 参数解析鲁棒性：tryParseToolArgs 多阶段修复，防止 LLM 输出异常导致执行失败。
  • 跨帧路由失败建议：translateRoutedResult 提供最近有效 ref 建议，降低模型重试成本。
  • 图片处理：Canvas 裁剪考虑 devicePixelRatio，压缩后再附加预览，减少内存占用。

章节来源

故障排查指南 ​

  • 无法访问标签页或系统页面
    • 现象：cannotAccessTab/cannotUseOnSystemPage。
    • 排查：确认 tabId 有效且非 chrome:// / about: / chrome-extension://。
  • Content Script 注入失败
    • 现象：injectContentScriptFailed。
    • 排查：manifest.content_scripts 配置正确；sendToContentScriptWithRetry 已自动注入并重试。
  • 元素定位失败
    • 现象：elementNotFoundBySelector/invalidRef。
    • 排查：优先使用 query_elements 返回的 ref；若失效，重新调用 query_elements。
  • 跨域 iframe 不可访问
    • 现象：iframe accessible=false。
    • 排查：仅同源可访问；跨域需后端代理或同域部署。
  • 表单填写不生效（React/Vue）
    • 现象：value 未更新。
    • 排查：使用 setNativeValue 或 keyboard_input；避免直接赋值。
  • 截图下载失败
    • 现象：downloadTriggerFailed。
    • 排查：检查 downloads 权限与浏览器默认下载目录。
  • 视觉识别 API 超时或为空
    • 现象：screenshotAnalysisTimeout/screenshotAnalysisEmpty。
    • 排查：检查 imageApiBase/apiKey/modelName/streamEnabled；重试或更换模型。

章节来源

结论 ​

本“网页增强工具”以 content 脚本为核心，结合 background 的工具定义与快照编排器，实现了从信息提取、交互操作到截图与图像处理的完整能力闭环。通过 Shadow DOM 穿透、iframe 同源访问、ref 跨帧路由与统一快照渲染，系统在复杂现代 Web 应用中具备较强的稳定性与可扩展性。配合 tool-executor 的参数解析鲁棒性与注入重试机制，显著提升了自动化操作的可靠性。建议在大规模页面中合理使用分页与字符预算，优先使用 query_elements 的 ref 进行交互，并在跨域场景下采用后端代理方案。

附录：使用示例与最佳实践 ​

章节来源