1. 定位与总体结构

AIPex 是一个开源的「用自然语言命令自动化浏览器」解决方案（browser-use），同时面向 Chrome 与 Edge 浏览器分发扩展。资料来源：README.md:1-30。仓库采用 pnpm monorepo 架构，根 package.json 通过 workspaces: ["packages/*"] 管理所有子包，并集中提供 dev、build、typecheck、preflight、lint:dependencies 等脚本。资料来源：package.json:1-30。该结构使得浏览器扩展、AI 运行时、UI 工具包与外部桥接可以并行演进、互不耦合。

2. 包结构与职责划分

AIPex 将系统拆为五个可独立发布的 npm 包与一个独立子项目：

资料来源：packages/core/package.json:1-40、packages/browser-runtime/package.json:1-30、packages/dom-snapshot/package.json:1-30、packages/aipex-react/package.json:1-30、packages/browser-ext/package.json:1-30、mcp-bridge/package.json:1-30。

3. 分层架构与数据流

graph TB
    User[用户] --> Ext[cool-aipex 扩展]
    Ext --> React[aipex-react UI]
    React --> Core[aipex-core Agent]
    Core --> Runtime[browser-runtime]
    Runtime --> Snap[dom-snapshot]
    Ext -- WebSocket --> Bridge[mcp-bridge]
    Bridge -- MCP --> Agent[外部 Agent / Claude]

• 核心层：aipex-core 封装 @openai/agents，对外暴露 AIPex.chat() 异步生成器，事件包括 content_delta、tool_call_start/complete/error、tool_call_args_streaming_* 等。资料来源：packages/core/README.md:1-40。
• 运行时层：browser-runtime 提供 SmartLocator/DomLocator 双模式元素定位，以及 RuntimeAddon、NoopBrowserAutomationHost、InMemoryOmniActionRegistry 等宿主契约，便于在不同环境（扩展、Node、CI）复用。资料来源：packages/browser-runtime/README.md:1-50。
• DOM 快照层：dom-snapshot 绕过 CDP 的 AXTree，纯 JS 遍历 DOM 并模拟无障碍树结构，配合 data-aipex-nodeid 持久化节点 ID，且支持同源 iframe 递归。资料来源：packages/dom-snapshot/README.md:1-40。
• UI 与扩展层：aipex-react 提供 chatbot、omni、AI Elements 等组件；cool-aipex 打包 Chrome/Edge MV3 扩展。资料来源：packages/aipex-react/package.json:1-30、packages/browser-ext/package.json:1-30。
• MCP 桥接：扩展选项页的 mcp-bridge-panel 仅允许 127.0.0.1 与 ::1 本地连接，通过 WebSocket 暴露 tools/list 与 tools/call。资料来源：packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx:1-30。

4. 关键子系统

4.1 工具与消息适配

ToolManager 单例统一管理 allBrowserTools，按 BROWSER、UI、PAGE、SCREENSHOT、DOWNLOAD、INTERVENTION、SKILL 分类，并支持动态注册与订阅通知。资料来源：packages/browser-ext/src/services/tool-manager.ts:1-30。message-adapter.ts 则在 runtime 与扩展 UI 之间转换消息格式，并能识别 { success: false, error: "..." } 的业务失败。资料来源：packages/browser-ext/src/lib/message-adapter.ts:1-30。

4.2 技能与沙箱

skillManager 单例负责注册、加载、启用技能，元数据持久化到 IndexedDB，内置 wcag22-a11y-audit 等合规审计能力。资料来源：packages/browser-runtime/src/skill/lib/services/skill-manager.ts:1-30。zenfs-manager.ts 通过 @zenfs/core 与 @jitl/quickjs-ng-wasmfile-release-sync 在浏览器侧提供虚拟文件系统，为隔离脚本执行提供读写、复制、重命名等能力。资料来源：packages/browser-runtime/src/lib/vm/zenfs-manager.ts:1-30。

5. 社区关注与已知限制

• Firefox 支持：官方在 Issue #1 中表示将借助框架重构考虑多浏览器适配。
• iframe 快照：dom-snapshot 已支持同源 iframe 递归，但跨域 iframe 受同源策略限制（Issue #100）。
• MCP 多会话：当前 mcp-bridge 仅支持单一 Claude 会话，并发连接会失败（Issue #202）。
• 仓库体积：约 97 MiB，社区正在清理历史大对象（Issue #53）。
• v0.1.0 新能力：最新发布新增 chatbot 技能管理与 UX 审计目标（Release v0.1.0）。

See Also

• DOM 快照采集与序列化
• AI Agent 核心
• MCP 桥接协议
• 工具注册与管理

概述与设计目标

AIPex 的浏览器自动化引擎由三个核心包协同构成：负责页面结构捕获的 @aipexstudio/dom-snapshot、提供定位器与运行时能力的 @aipexstudio/browser-runtime，以及承载代理与 AI 工具编排的 @aipexstudio/aipex-core 资料来源：packages/core/package.json。整体目标是让 LLM 驱动的代理在用户已安装的浏览器中以自然语言驱动页面交互，避免迁移到独立自动化浏览器。根级 package.json 通过 pnpm 工作区把 dev、build、preflight（format + lint + typecheck + test）脚本统一串联，确保快照、运行时与扩展共享同一构建链路 资料来源：package.json。

与依赖 Chrome DevTools Protocol（CDP）AXTree 的传统方案不同，AIPex 默认走纯 DOM 路线，规避 CDP 的浏览器依赖、通信延迟与配置复杂度 资料来源：packages/dom-snapshot/README.md。该路径在面对权限模型严格的 Firefox 时尤其关键——社区 issue #1 已长期追踪 Firefox 适配，目前由 DOM 路径降低迁移门槛。

DOM 快照采集系统

@aipexstudio/dom-snapshot 是引擎的"眼睛"。collectDomSnapshot(document, options) 接收 Document 节点并返回 SerializedDomSnapshot，结构包含树形 root、扁平 idToNode 索引和携带 URL/标题的 metadata 资料来源：packages/dom-snapshot/README.md。采集器会跳过 aria-hidden/display:none/inert 节点、为可交互元素注入持久化的 data-aipex-nodeid，并递归进入同源 iframe。三项关键可配置项： maxTextLength（默认 160，截断元素文本但不影响 StaticText）、includeHidden（默认 false）、captureTextNodes（默认 true）。

buildTextSnapshot 与 formatSnapshot 将快照序列化为 LLM 友好的线性文本；searchSnapshotText 支持管道符多词和 glob 模式，便于在大量节点中精确定位。该包以 ESM 模块独立分发，exports 字段已配置为发布形态 资料来源：packages/dom-snapshot/package.json。

社区 issue #100 指出 search_elements 在跨域或深度嵌套 iframe 场景下仍存在缺口，官方建议参考 chrome-devtools-mcp、Playwright、Stagehand 的递归方案改进。

定位器、运行时与文件沙箱

@aipexstudio/browser-runtime 把快照转译为可执行动作，并行提供两条元素访问路径：SmartLocator/SmartElementHandle 经 chrome.debugger 走 CDP 高保真通道；DomLocator/DomElementHandle 走纯 JS 通道，在调试协议被禁用或 Firefox 场景下回退，内置同源 iframe 坐标偏移补偿 资料来源：packages/browser-runtime/README.md。SnapshotManager 通过 cdp | dom 策略字段在两者间调度，实现"快照一次、动作多源"。

运行时同时暴露无副作用契约 RuntimeAddon、NoopBrowserAutomationHost、InMemoryOmniActionRegistry、NullInterventionHost、NoopContextProvider，便于在测试或受限扩展上下文中降级使用。文件系统子模块 zenfs-manager.ts 在浏览器内挂载虚拟 FS，支持 readFile/writeFile/rename/stat 等操作，文本类型清单覆盖 .ts/.py/.go/.rs/.java 等常见源码后缀，为 skill-manager 加载的 wcag22-a11y-audit 等内置技能提供持久化底座 资料来源：packages/browser-runtime/src/lib/vm/zenfs-manager.ts, packages/browser-runtime/src/skill/lib/services/skill-manager.ts。

工具集成、MCP 桥接与已知限制

扩展端 @aipexstudio/cool-aipex 把 allBrowserTools 注入由 @openai/agents 驱动的代理，可选用 Gemini / OpenAI / Anthropic / OpenRouter 资料来源：packages/browser-ext/package.json, packages/core/package.json。message-adapter.ts 负责把 AI SDK 的 tool_use、reasoning、source-url part 标准化为运行时 UI 消息，并识别 { success: false, error } 形式的业务级失败，避免抛出到代理循环 资料来源：packages/browser-ext/src/lib/message-adapter.ts。对话分享经 share-conversation.ts 上传，截图字段被刻意剔除以保护隐私 资料来源：packages/browser-ext/src/services/share-conversation.ts。

外部 IDE 代理（Cursor、Claude Code）通过根级 mcp-bridge 子包以 WebSocket 暴露 tools/list 与 tools/call，仅允许 127.0.0.1/::1 回环连接 资料来源：mcp-bridge/package.json, packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx。

flowchart LR
  Page[Web 页面 DOM] --> Snap[collectDomSnapshot]
  Snap --> Mgr[SnapshotManager]
  Mgr --> Smart[SmartLocator CDP]
  Mgr --> Dom[DomLocator DOM]
  Smart --> Agent[AIPex Agent]
  Dom --> Agent
  Agent --> Tools[allBrowserTools]
  Tools --> MCP[mcp-bridge WebSocket]
  Tools --> Skills[skill-manager + zenfs]

需要留意的限制与社区反馈：size-pack 约 97 MiB 已在 issue #53 中规划瘦身；MCP 桥接目前仅支持单 Claude 会话（issue #202），多窗口并发会触发连接失败；扩展偶现 "Requested device not found"（issue #80），多源于调试通道被占用；Firefox 适配（issue #1）尚未合并。

See Also

• packages/dom-snapshot/README.md
• packages/browser-runtime/README.md
• packages/browser-ext/src/lib/message-adapter.ts
• mcp-bridge/package.json
• issue #1 Firefox Support
• issue #100 iframe snapshot
• issue #202 MCP 单会话
• issue #80 Requested device not found

1. 概述与设计目标

AIPex 是一个"零迁移"的浏览器自动化代理，它的核心优势之一就是通过 MCP（Model Context Protocol）桥接让外部 AI 代理能够直接控制用户已经在使用的浏览器，而无需安装独立浏览器或购买订阅服务 README.md。

MCP 桥接子系统位于 mcp-bridge 工作区，是一个独立的 Node.js（>=18.0.0）进程，负责在外部 AI 代理（如 Claude Code、Cursor、Copilot 等）和浏览器扩展之间转发符合 Model Context Protocol 规范的 tools/list 与 tools/call 消息 mcp-bridge/package.json。其声明的关键词包括 mcp、model-context-protocol、aipex、browser、cursor、claude、copilot、websocket、bridge，清晰体现了"以 WebSocket 在 AI 代理与浏览器之间架设协议桥梁"的设计意图。

资料来源：mcp-bridge/package.json

2. 系统架构

MCP 桥接由三个层级构成：浏览器扩展内部的桥接面板、外部独立运行的桥接守护进程，以及运行在用户本机的 AI 代理。

flowchart LR
    A[AI Agent<br/>Claude Code / Cursor / Copilot] -->|MCP over stdio / TCP| B[mcp-bridge 守护进程<br/>Node.js + WebSocket]
    B -->|WebSocket JSON-RPC| C[AIPex 浏览器扩展<br/>Bridge Panel]
    C -->|Chrome APIs| D[当前浏览器标签页]
    D -->|DOM Snapshot + 执行结果| C
    C --> B
    B --> A

桥接面板向用户展示三个关键信息点：

1. 桥接通过 MCP 协议对外暴露 tools/list 和 tools/call，允许外部代理调用 AIPex 的浏览器自动化工具集 mcp-bridge-panel.tsx。
2. 仅允许 localhost 连接（127.0.0.1、::1），从源头避免网络暴露 mcp-bridge-panel.tsx。
3. 桥接面板作为可选项设置项集成在浏览器扩展的 Options 页面中，与扩展核心功能统一打包 packages/browser-ext/package.json。

资料来源：mcp-bridge-panel.tsx

3. 与 AI 代理的集成方式

AIPex 通过两条路径让外部 AI 代理接入浏览器自动化能力：

第二条路径——aipex-browser Skill——特别适合不依赖独立守护进程的场景；代理只需加载 Skill 清单，即可"按需"发现并使用 AIPex 的浏览器工具集，避免从零探索工具调用方式。

资料来源：README.md、package.json

4. 已知的局限性

根据社区反馈（Issue #202 https://github.com/AIPexStudio/AIPex/issues/202），MCP 桥接目前仅支持一个 Claude 会话：当用户多开 Claude 窗口时，后续启动的会话会提示连接失败，只有第一个开启的会话能正常运行。这与桥接面板中"仅允许 localhost"的策略有关——单进程单端口的桥接守护进程在并发连接处理上还存在竞争缺陷，需要在后续版本中引入多客户端会话隔离或端口池机制。

此外，社区对浏览器兼容性（Issue #1 Firefox 支持）与 search_elements 嵌套 iframe 处理（Issue #100）的诉求，也会直接影响通过 MCP 暴露的浏览器工具在多代理场景下的可用性。

See Also

• DOM Snapshot 与页面理解
• 浏览器运行时（browser-runtime）
• 项目主 README

技能系统（Skill System）

技能系统是 AIPex "可扩展性" 的核心，允许用户在浏览器中加载、执行并管理多个内置或自定义技能。技能元数据以 SkillMetadata 类型描述，包含 id、name、description、version、uploadedAt 与 enabled 等字段，并通过 skillStorage.saveSkillMetadata 持久化到 IndexedDB 资料来源：[packages/browser-runtime/src/skill/lib/services/skill-manager.ts]。

内置技能在 SkillManager 启动时按需懒加载。例如 wcag22-a11y-audit 技能在首次访问时检查 IndexedDB 中是否已有元数据记录，若不存在则创建默认元数据并保存，加载流程会输出 💾 Saving … / ✅ … 日志作为状态指示 资料来源：[packages/browser-runtime/src/skill/lib/services/skill-manager.ts]。

技能在运行期需要访问受限资源（如文件、脚本），因此底层通过虚拟文件系统（ZenFS 桥接到 QuickJS 沙箱）提供隔离的 readFile、writeFile、stat、rename 等能力。ZenFsManager.rename 会先 stat 源路径，区分目录与文件，再分别执行递归复制 + 删除或单文件读写，并对目标已存在的情况显式抛错 资料来源：[packages/browser-runtime/src/lib/vm/zenfs-manager.ts]。

对话管理（Conversation Management）

对话系统承担消息格式化、工具调用解析与结果错误归一化等任务。message-adapter.ts 中的 safeJsonParse 使用 try/catch 防御非法 JSON 字符串，避免流式事件破坏整轮会话；extractBusinessFailure 则识别工具返回的 { success: false, error: "..." } 业务级失败，并提取可读的错误信息 资料来源：[packages/browser-ext/src/lib/message-adapter.ts]。

会话还可以被序列化并分享。shareConversation 会过滤掉 role: "system" 的消息，将 parts 数组通过 toShareablePart 统一转换为 ShareablePart 形状——其中 tool 类型会保留 toolName、input、output、state 等字段，但有意省略 screenshot 字段以保护隐私 资料来源：[packages/browser-ext/src/services/share-conversation.ts]。

用户界面（UI）

UI 子系统负责将上述能力暴露给最终用户，主要组件包括：

• 自动化模式工具栏：AutomationModeInputToolbar 是 InputToolbarSlotProps 的插槽实现，通过 STORAGE_KEYS 与 validateAutomationMode 在 focus（前台高亮）和 background（静默执行）两种模式间切换；它使用 useStorage Hook 持久化用户选择，并集成 TokenUsageIndicator 显示实时 token 消耗 资料来源：[packages/browser-ext/src/lib/automation-mode-toolbar.tsx]。
• 文件预览：FilePreview.tsx 使用 react-syntax-highlighter 渲染文本/代码文件，配置 wrapLines 与 wordBreak: "break-word" 防止长行溢出；遇到二进制文件则显示 Alert 提示并通过 formatBytes 给出文件大小 资料来源：[packages/browser-ext/src/pages/options/file-components/FilePreview.tsx]。
• MCP 桥接面板：mcp-bridge-panel.tsx 提示该桥接器以 tools/list 与 tools/call 协议暴露工具，仅接受 127.0.0.1 与 ::1 的本地回环连接，以保证安全 资料来源：[packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx]。
• 文件操作工具：utils.ts 维护扩展名→Emoji 的映射表（如 ts→📘、zip→📦），并通过 isProtectedPath 把 /skills 与 /skills/skill-creator 标记为不可删除路径，防止误删内置技能 资料来源：[packages/browser-ext/src/pages/options/file-components/utils.ts]。

端到端协同流程

下图展示了从用户输入到工具执行的纵向数据流：

sequenceDiagram
  participant U as 用户
  participant UI as AutomationModeInputToolbar
  participant CR as Chatbot Runtime
  participant SK as SkillManager
  participant VM as ZenFS + QuickJS
  participant SH as shareConversation

  U->>UI: 输入自然语言指令
  UI->>CR: 提交消息（携带 automationMode）
  CR->>SK: 解析并调用 skill
  SK->>VM: 执行脚本 / 读写文件
  VM-->>SK: 返回结果
  SK-->>CR: 工具结果（含 success/error）
  CR-->>UI: 渲染回答
  U->>SH: 触发分享
  SH-->>U: 返回可分享 URL

整体而言，技能系统提供"原子能力"，对话系统提供"会话与编排"，UI 提供"交互入口"——三者通过统一的消息 schema 与受保护的文件命名空间耦合形成闭环。

参见

• DOM 快照与页面理解
• MCP Bridge 桥接协议
• AIPex 项目总览

Pitfall Log / 踩坑日志

项目：AIPexStudio/AIPex

摘要：发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。

1. 安全/权限坑 · 涉及密钥、隐私或敏感领域

• 严重度：high
• 证据强度：source_linked
• 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。
• 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。
• 证据：packet_text.keyword_scan | https://github.com/AIPexStudio/AIPex | matched secret / private key / privacy / trading / finance keyword

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

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

3. 能力坑 · 能力判断依赖假设

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

4. 维护坑 · 维护活跃度未知

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/AIPexStudio/AIPex | no_demo; severity=medium

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

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

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

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

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

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