Files
Obsidian/MyArticles/剖析 Page-Agent 核心能力与代码结构.md
coco 8b94d76799 a
2026-07-21 13:57:15 +08:00

5.2 KiB
Raw Permalink Blame History

  •  轻松集成
    • 无需 浏览器插件 / Python / 无头浏览器。
    • 纯页面内 JavaScript,一切都在你的网页中完成。
  • 📖 基于文本的 DOM 操作
    • 无需截图,无需多模态模型或特殊权限。
  • 🧠 用你自己的 LLM
  • 🎨 精美 UI,支持人机协同
  • 🐙 可选的 Chrome 扩展,支持跨页面任务。

https://alibaba.github.io/page-agent/docs/introduction/overview/

💡 应用场景

  • SaaS AI 副驾驶 — 几行代码为你的产品加上 AI 副驾驶,无需重写后端。
  • 智能表单填写 — 把 20 次点击变成一句话。ERP、CRM、管理后台的最佳拍档。
  • 无障碍增强 — 用自然语言让任何网页无障碍。语音指令、屏幕阅读器,零门槛。
  • 跨页面 Agent — 通过可选的 Chrome 扩展,让你自己的 Agent 跨标签页工作。

从你提供的代码片段和仓库地址(https://github.com/alibaba/page-agent)来看,page-agent 是阿里巴巴开源的一个面向页面代理/控制的工具库,核心能力围绕页面信息采集、DOM 操作、交互增强、前端框架适配 等方向,以下是对该仓库核心能力和代码结构的梳理:

一、核心模块与功能

1. 页面信息采集(getPageInfo.ts)

提供页面视口、滚动、尺寸等核心信息的精准获取,包括:

  • 视口宽高(viewport_width/height)、页面总宽高(page_width/height);

  • 滚动位置(scroll_x/y)、可视区外剩余像素(pixels_below/right);

  • 基于视口的分页计算(pages_above/below、total_pages)等。

// 核心用法示例
const pageInfo = getPageInfo();
console.log('当前滚动位置:', pageInfo.scroll_y);
console.log('页面总页数:', pageInfo.total_pages);

2. 前端框架适配补丁(patches/)

针对主流框架的 DOM 结构/交互特性做兼容处理:

  • AntD 适配(antd.ts):修复 AntD Select 组件(input[role="combobox"])因 DOM 结构(div 包 input、input 不可见)导致的信息采集问题;

  • React 适配(react.ts):识别 React 根节点(#root/[data-reactroot] 等),添加 data-page-agent-not-interactive 属性,避免根节点事件被误判为交互元素。

3. 扁平化 DOM 树模型(dom_tree/type.ts)

定义高效的 DOM 树存储结构 FlatDomTree,区分文本节点、普通元素、可交互元素,支持:

  • 节点可见性、视口内状态、交互标识;

  • 可交互元素关联原生 HTMLElement 引用,便于后续操作。

4. 可视化动效(motion-css/)

提供页面交互的动效增强能力(如高亮、过渡动画):

  • 多色层旋转/渐变动画(蓝/紫/橙/黄四层,支持顺时针/逆时针旋转);

  • 动效的显示/隐藏控制(createMotion 生成动效容器,show/hide 触发入场/退场动画)。

5. 开发者工具(website/src/components/)

提供调试配套组件:

  • JSConsole.tsx:嵌入式 JS 调试台,支持代码执行、console 拦截、结果高亮,适配多轮执行上下文共享;

  • HighlightSyntax.tsx:语法高亮工具,支持 JS/TS 全量 token(字符串、注释、关键字、类型、装饰器等);

  • ThemeSwitcher.tsx:明暗主题切换,支持系统主题跟随、localStorage 持久化。

二、工程化配置

1. 依赖管理(dependabot.yml)

  • npm 依赖:按「生产/开发依赖」分组,仅自动更新 minor/patch 版本,major 版本需人工审查;

  • GitHub Actions 依赖:全量分组,每周自动更新。

2. 部署流程(deploy-demo.yml)

  • 触发条件:main 分支 push;

  • 部署步骤:Node.js 24 环境构建 → 打包 website → 部署到 GitHub Pages。

3. 忽略配置(.gitignore)

覆盖日志、依赖、构建产物、编辑器配置、环境文件、AI 工具缓存等,符合前端工程化最佳实践。

三、核心应用场景

  1. 页面自动化测试:精准获取页面状态 + 识别可交互元素,替代传统的坐标/选择器操作;

  2. 低代码/可视化搭建:FlatDomTree 扁平化结构便于 DOM 遍历/操作,动效模块增强交互反馈;

  3. 前端监控/埋点:结合页面信息采集 + 框架适配,精准捕获用户行为;

  4. 调试工具开发:JSConsole/语法高亮可快速集成到自研调试平台。

四、使用建议

  1. 安装:需先确认仓库的发布方式(npm 包/源码引入),源码引入需处理 monorepo 结构(packages/ 下多包);

  2. 适配扩展:如需支持 Vue/ElementUI 等框架,可参考 patches/antd.ts/react.ts 扩展补丁;

  3. 动效定制:基于 motion-css 可修改颜色、动画时长、混合模式(mix-blend-mode)适配业务风格。

如果需要更具体的功能解析(如某模块源码解读、二次开发示例),可以补充说明具体方向。