# https://github.com/AIPexStudio/AIPex 项目说明书

生成时间：2026-06-20 22:07:57 UTC

## 目录

- [AIPex 系统架构总览](#page-1)
- [浏览器自动化引擎：DOM 快照、定位器与工具集](#page-2)
- [MCP 桥接与 AI 代理集成](#page-3)
- [技能系统、对话管理与用户界面](#page-4)

<a id='page-1'></a>

## AIPex 系统架构总览

### 相关页面

相关主题：[浏览器自动化引擎：DOM 快照、定位器与工具集](#page-2), [MCP 桥接与 AI 代理集成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/AIPexStudio/AIPex/blob/main/README.md)
- [package.json](https://github.com/AIPexStudio/AIPex/blob/main/package.json)
- [packages/core/README.md](https://github.com/AIPexStudio/AIPex/blob/main/packages/core/README.md)
- [packages/core/package.json](https://github.com/AIPexStudio/AIPex/blob/main/packages/core/package.json)
- [packages/browser-runtime/README.md](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/README.md)
- [packages/browser-runtime/package.json](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/package.json)
- [packages/dom-snapshot/README.md](https://github.com/AIPexStudio/AIPex/blob/main/packages/dom-snapshot/README.md)
- [packages/aipex-react/package.json](https://github.com/AIPexStudio/AIPex/blob/main/packages/aipex-react/package.json)
- [packages/browser-ext/package.json](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/package.json)
- [mcp-bridge/package.json](https://github.com/AIPexStudio/AIPex/blob/main/mcp-bridge/package.json)
- [packages/browser-ext/src/services/tool-manager.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/services/tool-manager.ts)
- [packages/browser-ext/src/lib/message-adapter.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/lib/message-adapter.ts)
- [packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx)
- [packages/browser-runtime/src/skill/lib/services/skill-manager.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/src/skill/lib/services/skill-manager.ts)
- [packages/browser-runtime/src/lib/vm/zenfs-manager.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/src/lib/vm/zenfs-manager.ts)
</details>

# AIPex 系统架构总览

## 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 包与一个独立子项目：

| 包名 | 角色 | 关键依赖 |
|------|------|----------|
| `@aipexstudio/aipex-core` | 平台无关的 AI Agent 框架 | `@openai/agents`、`lru-cache`、`zod` |
| `@aipexstudio/browser-runtime` | 浏览器自动化运行时、宿主契约 | `@aipexstudio/aipex-core`、`@aipexstudio/dom-snapshot`、`@zenfs/core` |
| `@aipexstudio/dom-snapshot` | 纯 JS 的 DOM 快照采集 | 无运行时依赖 |
| `@aipexstudio/aipex-react` | React UI 工具包、Chatbot/Omni 组件 | `@radix-ui/*`、`@ricky0123/vad-web` |
| `@aipexstudio/cool-aipex` | 浏览器扩展主入口（构建产物） | `@ai-sdk/{openai,anthropic,google}` |
| `mcp-bridge` | MCP 协议 WebSocket 桥接 | Node ≥ 18 |

资料来源：[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. 分层架构与数据流

```mermaid
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](https://github.com/AIPexStudio/AIPex/releases/tag/v0.1.0)）。

## See Also

- [DOM 快照采集与序列化](dom-snapshot.md)
- [AI Agent 核心](aipex-core.md)
- [MCP 桥接协议](mcp-bridge.md)
- [工具注册与管理](tool-manager.md)

---

<a id='page-2'></a>

## 浏览器自动化引擎：DOM 快照、定位器与工具集

### 相关页面

相关主题：[AIPex 系统架构总览](#page-1), [MCP 桥接与 AI 代理集成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/dom-snapshot/README.md](https://github.com/AIPexStudio/AIPex/blob/main/packages/dom-snapshot/README.md)
- [packages/dom-snapshot/package.json](https://github.com/AIPexStudio/AIPex/blob/main/packages/dom-snapshot/package.json)
- [packages/browser-runtime/README.md](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/README.md)
- [packages/browser-ext/package.json](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/package.json)
- [packages/core/package.json](https://github.com/AIPexStudio/AIPex/blob/main/packages/core/package.json)
- [mcp-bridge/package.json](https://github.com/AIPexStudio/AIPex/blob/main/mcp-bridge/package.json)
- [packages/browser-ext/src/lib/message-adapter.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/lib/message-adapter.ts)
- [packages/browser-runtime/src/lib/vm/zenfs-manager.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/src/lib/vm/zenfs-manager.ts)
- [packages/browser-ext/src/services/share-conversation.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/services/share-conversation.ts)
- [packages/browser-runtime/src/skill/lib/services/skill-manager.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/src/skill/lib/services/skill-manager.ts)
</details>

# 浏览器自动化引擎：DOM 快照、定位器与工具集

## 概述与设计目标

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

与依赖 Chrome DevTools Protocol（CDP）AXTree 的传统方案不同，AIPex 默认走纯 DOM 路线，规避 CDP 的浏览器依赖、通信延迟与配置复杂度 资料来源：[packages/dom-snapshot/README.md](https://github.com/AIPexStudio/AIPex/blob/main/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](https://github.com/AIPexStudio/AIPex/blob/main/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](https://github.com/AIPexStudio/AIPex/blob/main/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](https://github.com/AIPexStudio/AIPex/blob/main/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](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/src/lib/vm/zenfs-manager.ts), [packages/browser-runtime/src/skill/lib/services/skill-manager.ts](https://github.com/AIPexStudio/AIPex/blob/main/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](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/package.json), [packages/core/package.json](https://github.com/AIPexStudio/AIPex/blob/main/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](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/lib/message-adapter.ts)。对话分享经 `share-conversation.ts` 上传，截图字段被刻意剔除以保护隐私 资料来源：[packages/browser-ext/src/services/share-conversation.ts](https://github.com/AIPexStudio/AIPex/blob/main/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](https://github.com/AIPexStudio/AIPex/blob/main/mcp-bridge/package.json), [packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx)。

```mermaid
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](https://github.com/AIPexStudio/AIPex/blob/main/packages/dom-snapshot/README.md)
- [packages/browser-runtime/README.md](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/README.md)
- [packages/browser-ext/src/lib/message-adapter.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/lib/message-adapter.ts)
- [mcp-bridge/package.json](https://github.com/AIPexStudio/AIPex/blob/main/mcp-bridge/package.json)
- [issue #1 Firefox Support](https://github.com/AIPexStudio/AIPex/issues/1)
- [issue #100 iframe snapshot](https://github.com/AIPexStudio/AIPex/issues/100)
- [issue #202 MCP 单会话](https://github.com/AIPexStudio/AIPex/issues/202)
- [issue #80 Requested device not found](https://github.com/AIPexStudio/AIPex/issues/80)

---

<a id='page-3'></a>

## MCP 桥接与 AI 代理集成

### 相关页面

相关主题：[AIPex 系统架构总览](#page-1), [浏览器自动化引擎：DOM 快照、定位器与工具集](#page-2), [技能系统、对话管理与用户界面](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp-bridge/package.json](https://github.com/AIPexStudio/AIPex/blob/main/mcp-bridge/package.json)
- [README.md](https://github.com/AIPexStudio/AIPex/blob/main/README.md)
- [packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx)
- [packages/browser-ext/package.json](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/package.json)
- [package.json](https://github.com/AIPexStudio/AIPex/blob/main/package.json)
- [packages/browser-runtime/README.md](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/README.md)
</details>

# MCP 桥接与 AI 代理集成

## 1. 概述与设计目标

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

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

资料来源：[mcp-bridge/package.json](https://github.com/AIPexStudio/AIPex/blob/main/mcp-bridge/package.json)

## 2. 系统架构

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

```mermaid
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](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx)。
2. **仅允许 localhost 连接**（`127.0.0.1`、`::1`），从源头避免网络暴露 [mcp-bridge-panel.tsx](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx)。
3. 桥接面板作为可选项设置项集成在浏览器扩展的 Options 页面中，与扩展核心功能统一打包 [packages/browser-ext/package.json](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/package.json)。

资料来源：[mcp-bridge-panel.tsx](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx)

## 3. 与 AI 代理的集成方式

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

| 集成路径 | 适用代理 | 协议载体 | 备注 |
|---|---|---|---|
| `mcp-bridge` 守护进程 | Claude Code、Cursor、Copilot 等 MCP 兼容代理 | MCP（JSON-RPC）→ WebSocket | 需独立启动 Node 进程；通过 `pnpm dev` 等脚本运行 [package.json](https://github.com/AIPexStudio/AIPex/blob/main/package.json) |
| `aipex-browser` Skill 包 | Claude Code、OpenClaw 等支持 Skill 协议的运行时 | Skill Manifest + 工具调用 | 内置 30+ 浏览器工具的完整参数 schema 与使用策略 [README.md](https://github.com/AIPexStudio/AIPex/blob/main/README.md) |

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

资料来源：[README.md](https://github.com/AIPexStudio/AIPex/blob/main/README.md)、[package.json](https://github.com/AIPexStudio/AIPex/blob/main/package.json)

## 4. 已知的局限性

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

此外，社区对浏览器兼容性（[Issue #1](https://github.com/AIPexStudio/AIPex/issues/1) Firefox 支持）与 `search_elements` 嵌套 iframe 处理（[Issue #100](https://github.com/AIPexStudio/AIPex/issues/100)）的诉求，也会直接影响通过 MCP 暴露的浏览器工具在多代理场景下的可用性。

## See Also

- [DOM Snapshot 与页面理解](https://github.com/AIPexStudio/AIPex/blob/main/packages/dom-snapshot/README.md)
- [浏览器运行时（browser-runtime）](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/README.md)
- [项目主 README](https://github.com/AIPexStudio/AIPex/blob/main/README.md)

---

<a id='page-4'></a>

## 技能系统、对话管理与用户界面

### 相关页面

相关主题：[AIPex 系统架构总览](#page-1), [MCP 桥接与 AI 代理集成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/browser-runtime/src/skill/lib/services/skill-manager.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/src/skill/lib/services/skill-manager.ts)
- [packages/browser-runtime/src/lib/vm/zenfs-manager.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-runtime/src/lib/vm/zenfs-manager.ts)
- [packages/browser-ext/src/lib/message-adapter.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/lib/message-adapter.ts)
- [packages/browser-ext/src/services/share-conversation.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/services/share-conversation.ts)
- [packages/browser-ext/src/lib/automation-mode-toolbar.tsx](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/lib/automation-mode-toolbar.tsx)
- [packages/browser-ext/src/pages/options/file-components/FilePreview.tsx](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/pages/options/file-components/FilePreview.tsx)
- [packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/pages/options/mcp-bridge-panel.tsx)
- [packages/browser-ext/src/pages/options/file-components/utils.ts](https://github.com/AIPexStudio/AIPex/blob/main/packages/browser-ext/src/pages/options/file-components/utils.ts)
- [packages/dom-snapshot/README.md](https://github.com/AIPexStudio/AIPex/blob/main/packages/dom-snapshot/README.md)
- [README.md](https://github.com/AIPexStudio/AIPex/blob/main/README.md)
</details>

# 技能系统、对话管理与用户界面

AIPex 是一个在已有浏览器中运行的自然语言自动化代理，其核心交互体验由三个相互配合的子系统构成：技能（Skill）系统提供可执行能力的封装与管理，对话（Conversation）系统负责消息与工具调用的编排，用户界面（UI）子系统则把这些能力以工具栏、文件预览、桥接面板等形式呈现给用户。本页说明这三者之间的关系与关键源码位置。

## 技能系统（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]()]。

## 端到端协同流程

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

```mermaid
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 快照与页面理解](https://github.com/AIPexStudio/AIPex/blob/main/packages/dom-snapshot/README.md)
- [MCP Bridge 桥接协议](https://github.com/AIPexStudio/AIPex/blob/main/mcp-bridge/package.json)
- [AIPex 项目总览](https://github.com/AIPexStudio/AIPex/blob/main/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: AIPexStudio/AIPex; human_manual_source: deepwiki_human_wiki -->