# joybrowser

**Repository Path**: yushanbo/joybrowser

## Basic Information

- **Project Name**: joybrowser
- **Description**: joybrowser
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-05-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JoyBrowser

JoyBrowser 是一个面向 agent 场景的浏览器控制平台原型，用来替代 `chrome-devtools-mcp`，并补齐其在页面语义理解、扩展侧上下文采集，以及拟人化桌面自动化上的不足。

项目采用 monorepo 结构，核心由三部分组成：

- **Electron + Vue 桌面应用**：负责会话管理、工具路由、桥接服务、操作审计与可视化界面。
- **WXT Chrome 扩展**：负责页面侧语义快照、辅助函数执行，以及把标签页上下文桥接回桌面端。
- **Shared 协议包**：负责共享领域模型、桥接消息结构与工具调用协议。

当前仓库已经完成工作区搭建、桥接协议、基础工具路由、语义快照、两种执行模式的分工，以及桌面 UI 和核心测试，但仍属于原型阶段。

## 执行模式

当前系统明确分成两种模式：

- **Web automation mode (`semantic`)**：所有浏览器侧操作都交给 extension 执行。桌面应用负责 session/page 管理、工具路由、动作记录和桥接调度，但不直接代替页面做点击或输入。
- **Mouse mode (`humanized`)**：extension 负责返回语义目标与坐标信息，桌面应用接管真实的鼠标和键盘动作，用桌面输入完成点击、聚焦、输入与提交。

这意味着 JoyBrowser 的职责边界已经固定为：**extension 负责页面内语义与浏览器动作，app 负责桌面级输入和控制编排。**

## 项目目标

JoyBrowser 想解决的不是“再做一个浏览器自动化工具”，而是构建一个更适合 agent 使用的浏览器控制底座，重点包括：

- 用 **扩展侧语义快照** 提供比纯 DevTools 更贴近页面结构的高信号上下文。
- 用 **桌面侧拟人化执行模型** 支持更自然的鼠标和键盘操作路径。
- 用 **统一控制服务** 管理 session、page、artifact、action 和桥接状态。
- 在未来接入 **真正的 MCP server transport**、**Puppeteer/Chrome 运行时** 和 **原生 OS 自动化 API**。

## 当前能力

根据当前实现与规格，仓库已经覆盖以下能力：

### 1. 浏览器控制基础能力

桌面端通过 `BrowserControlService` 和 `McpToolRouter` 暴露一组 MCP-compatible 工具路由，已覆盖：

- 新建页面
- 列出页面
- 选择页面
- 页面导航
- 等待文本出现
- 获取语义快照
- 截图
- 查看 console 消息
- 查看 network 请求
- 执行脚本
- 点击
- Hover
- Fill
- 输入文本
- 按键
- 运行 page helper

其中与页面 DOM 直接交互的 `click`、`hover`、`fill`、`type_text`、`press_key` 已经接入 extension 桥接链路；而 mouse mode 下的可见点击/输入则由 app 根据 extension 提供的目标信息执行桌面输入。

### 2. 扩展到桌面端桥接

Chrome 扩展通过 WebSocket 连接本地桌面端桥接服务，支持：

- 标签页激活或加载完成时自动连接
- 扩展注册时上报 `sessionId`、`pageId`、`protocolVersion`、`token`、`capabilities`
- 接收桌面端下发的快照请求、helper 请求与页面动作请求
- 将页面事件回传给桌面端

当前默认桥接地址为：

- `ws://127.0.0.1:4491`

### 3. 页面语义快照

扩展侧会从页面中提取一批高价值交互节点，当前快照重点关注：

- `a`
- `button`
- `input`
- `textarea`
- `select`
- 带 `role` 的元素
- 带 `tabindex` 的元素

每个节点会采集：

- 稳定 `uid`
- `frameId`
- `role`
- `name`
- `text`
- `selectorHint`
- `bounds`
- `attributes`

这为后续的语义定位、重定位和拟人化动作执行提供了基础。

### 4. 页面辅助函数

当前已实现的 helper 包括：

- `findInteractiveElements`
- `findByText`

它们可以返回结构化结果和元素引用，供桌面端后续动作使用。

### 5. 模式化执行链路

当前实现已经把两条执行链路拆清楚：

- **Web automation mode**：`BrowserControlService -> ExtensionBridgeRuntime -> LocalBridgeServer -> extension background/content`
- **Mouse mode**：`BrowserControlService -> snapshot/target resolution -> desktop input adapter`

前者强调页面内语义动作，后者强调桌面级鼠标键盘接管。

### 6. 拟人化自动化

项目已实现拟人化动作规划的基础算法，包括：

- 鼠标路径生成
- 停顿窗口控制
- 键盘节奏变化
- 修正行为建模
- 动作执行结果记录
- 执行后验证状态记录

目前仓库中的 desktop input 仍以适配器抽象和测试替身为主，真实 OS 级鼠标键盘注入仍是后续增强项。

### 7. 桌面可视化面板

Electron + Vue 界面已经提供以下操作视图：

- Bridge 状态
- Desktop readiness 状态
- Session 列表
- Page 列表
- Artifact 列表
- Action 列表
- 默认 profile 配置
- Operator notes

这使得当前原型具备了基础的运行观测能力。

## 仓库结构

```text
joybrowser/
├─ apps/
│  ├─ desktop/              # Electron + Vue 桌面应用
│  │  ├─ src/main/          # Electron 主进程入口
│  │  ├─ src/preload/       # 预加载层
│  │  ├─ src/renderer/      # Vue 渲染层 UI
│  │  ├─ src/core/          # 控制服务、运行时、artifact 存储
│  │  ├─ src/bridge/        # 本地桥接服务
│  │  ├─ src/mcp/           # MCP-compatible 工具路由
│  │  └─ src/automation/    # 拟人化执行与权限检查
│  └─ extension/            # WXT Chrome 扩展
│     └─ entrypoints/       # background / content 入口
├─ packages/
│  └─ shared/               # 共享类型、领域模型、协议定义
├─ tests/                   # Vitest 测试
├─ docs/                    # 项目文档与差距分析
├─ openspec/                # 变更提案、设计和任务清单
├─ package.json             # workspace 根配置
└─ tsconfig.base.json       # TypeScript 基础配置
```

## 技术栈

### Workspace 与语言

- Node.js
- npm workspaces
- TypeScript
- ESM

### 桌面端

- Electron
- Vue 3
- Vite
- `ws`
- `puppeteer-core`（已安装，后续可用于真实浏览器接入）

### 扩展端

- WXT
- Chrome Extension APIs

### 测试

- Vitest
- jsdom

## 环境要求

建议环境：

- **Node.js 20+**
- **npm 10+**
- macOS、Windows 或 Linux 中可运行 Electron 与 Chromium 扩展开发环境的平台

如果你要继续推进“拟人化桌面自动化”，还需要关注系统级权限，尤其是 macOS 上的：

- Accessibility
- Input Monitoring

当前项目已经提供权限检查状态展示，但尚未接入真实 OS 自动化执行。

## 安装依赖

在仓库根目录执行：

```bash
npm install
```

## 开发命令

### 启动桌面端开发环境

```bash
npm run dev:desktop
```

### 启动扩展开发环境

```bash
npm run dev:extension
```

### 构建全部工作区

```bash
npm run build
```

### 类型检查

```bash
npm run typecheck
```

### 运行测试

```bash
npm test
```

## 各工作区脚本

### 根目录

```bash
npm run build
npm run dev:desktop
npm run dev:extension
npm run typecheck
npm test
```

### `@joybrowser/desktop`

```bash
npm run dev -w @joybrowser/desktop
npm run build -w @joybrowser/desktop
npm run typecheck -w @joybrowser/desktop
```

### `@joybrowser/extension`

```bash
npm run dev -w @joybrowser/extension
npm run build -w @joybrowser/extension
npm run typecheck -w @joybrowser/extension
```

### `@joybrowser/shared`

```bash
npm run build -w @joybrowser/shared
npm run typecheck -w @joybrowser/shared
```

## 运行方式说明

当前项目更适合作为“原型平台”运行，而不是直接作为生产可用工具使用。

典型开发链路如下：

1. 启动桌面端开发环境。
2. 启动扩展开发环境。
3. 将 WXT 构建出的扩展加载到 Chrome/Chromium。
4. 打开目标页面，让扩展完成桥接注册。
5. 通过桌面端查看 session、page、artifact、action 和权限状态。
6. 在后续接入真实 MCP transport 后，再让外部 agent 通过标准协议调用工具。

## 测试覆盖

当前已有测试覆盖以下方向：

- **控制服务**：验证 session/page 创建与选择、拟人化动作记录
- **桥接服务**：验证扩展注册握手与协议确认
- **拟人化工具**：验证鼠标路径生成与键盘输入计划

对应测试文件包括：

- `tests/controlService.test.ts`
- `tests/bridgeServer.test.ts`
- `tests/humanization.test.ts`

## 当前限制

根据当前实现与差距审查，项目仍有这些明显缺口：

1. 真实 Chrome 编排尚未接入，当前仍以内存运行时适配器为主。
2. 还没有完整的 MCP server transport，只具备工具路由层兼容性。
3. 原生鼠标和键盘发射尚未真正接入操作系统 API。
4. 尚未实现性能追踪、Lighthouse、内存分析等更深层诊断能力。
5. 更丰富的 network 观察、扩展管理、screencast 等能力仍待补齐。

## 下一步建议

如果要把这个原型继续推进，优先级建议如下：

1. 用 Puppeteer 驱动替换当前内存运行时适配器。
2. 在现有工具路由外包一层真正的 MCP server transport。
3. 接入原生桌面输入 API，把拟人化动作从“计划与记录”推进到“真实执行”。
4. 持久化 screenshot、snapshot、network 和 action artifact。
5. 扩展 page helper 与语义定位能力，提高动态页面上的重定位稳定性。

## 关键实现参考

如果你要快速理解代码，可优先阅读以下位置：

- `apps/desktop/src/main/index.ts`：Electron 主入口、IPC 注册、桥接与控制服务装配
- `apps/desktop/src/mcp/toolRouter.ts`：工具名到内部动作意图的映射
- `apps/desktop/src/core/browserRuntime.ts`：当前浏览器运行时适配器抽象与内存实现
- `apps/extension/entrypoints/background/index.ts`：扩展与桌面端的 WebSocket 桥接
- `apps/extension/entrypoints/content/lib/semanticSnapshot.ts`：语义快照与 helper 实现
- `apps/desktop/src/renderer/src/App.vue`：桌面控制面板 UI

## OpenSpec

仓库中包含完整的 OpenSpec 变更资料，位于：

- `openspec/changes/replace-chrome-devtools-mcp/`

其中包括：

- `proposal.md`：为什么要做这件事
- `design.md`：设计细节
- `tasks.md`：任务拆解与完成情况
- `specs/`：能力级规格说明

如果你要继续开发，建议先看这部分，再决定是补真实运行时、补 MCP transport，还是补 OS 自动化层。

## 状态总结

JoyBrowser 当前已经完成了“替代方案骨架”的关键搭建：

- 有工作区结构
- 有共享协议
- 有桌面端控制核心
- 有扩展桥接
- 有语义快照
- 有拟人化动作规划
- 有基础测试
- 有可视化面板

但它仍然是一个 **架构已成型、执行链路未完全落地** 的原型。若要进入下一阶段，最关键的是把“内存模拟”替换成“真实浏览器 + 真实输入 + 真实协议传输”。


### 控制台测试脚本
~~~
const state = await window.joybrowser.getState();
const page = state.pages.find(p => p.url.includes('csdn.net')) ?? state.pages[0];

const snapshot = await window.joybrowser.invokeTool('take_snapshot', {
  sessionId: 'default-session',
  pageId: page.id,
});

const keyword = 'AI搜索';
const target = snapshot.nodes.find(node =>
  (node.text && node.text.includes(keyword)) ||
  (node.name && node.name.includes(keyword))
);

if (!target) {
  throw new Error(`没找到元素: ${keyword}`);
}

console.log('matched target =', target);

const result = await window.joybrowser.invokeTool('click', {
  sessionId: 'default-session',
  pageId: page.id,
  mode: 'humanized',
  profileId: 'balanced',
  target: {
    uid: target.uid,
    frameId: target.frameId,
    selectorHint: target.selectorHint,
    text: target.text,
    role: target.role,
    bounds: target.bounds,
    geometrySource: 'snapshot-node',
  },
});

console.log('click result =', result);
~~~