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

120 lines
5.2 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
-  **轻松集成**
- 无需 `浏览器插件` / `Python` / `无头浏览器`。
- 纯页面内 JavaScript,一切都在你的网页中完成。
- **📖 基于文本的 DOM 操作**
- 无需截图,无需多模态模型或特殊权限。
- **🧠 用你自己的 LLM**
- **🎨 精美 UI,支持人机协同**
- **🐙 可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension),支持跨页面任务。**
https://alibaba.github.io/page-agent/docs/introduction/overview/
## 💡 应用场景
- **SaaS AI 副驾驶** — 几行代码为你的产品加上 AI 副驾驶,无需重写后端。
- **智能表单填写** — 把 20 次点击变成一句话。ERP、CRM、管理后台的最佳拍档。
- **无障碍增强** — 用自然语言让任何网页无障碍。语音指令、屏幕阅读器,零门槛。
- **跨页面 Agent** — 通过可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension),让你自己的 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`)等。
```TypeScript
// 核心用法示例
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`)适配业务风格。
如果需要更具体的功能解析(如某模块源码解读、二次开发示例),可以补充说明具体方向。