Skip to content

Timcai06/Flux

BranchesTags

Repository files navigation

Flux - AI-Powered Browser Assistant

项目概览 (Project Overview)

Flux 是一款基于 AI Agent 架构的智能浏览器助手，融合了 Monica 的全触达交互与 Manus 的端到端执行能力。

核心价值：

  • 🧠 智能感知：自动理解网页内容、用户意图和浏览上下文
  • 🤖 自主执行：从简单查询到复杂任务的全自动化闭环
  • 🔄 动态调度：通过 LiteLLM 根据任务复杂度智能选择最优 AI 模型
  • 👁️ 可视化反馈：实时流式展示 AI 操作过程，任务透明可控

技术定位：浏览器侧边栏 + 后台 Agent 引擎 + 多模型智能路由

核心功能 (Core Features)

1. 感知系统 (Sensory Layer)

像 Monica 一样理解你的浏览环境

  • 无处不在的侧边栏 (Ubiquitous Sidebar)

    • 基于 Plasmo 开发，常驻浏览器，快捷键一键唤起
    • 响应式设计，适配各种屏幕尺寸

  • 主动语境注入 (Active Context Injection)

    • 自动捕获：网页 DOM 结构、选中文本、页面元数据
    • 视觉理解：支持截图分析，无需用户手动描述背景
    • 零摩擦交互：直接提问，AI 自动理解上下文

  • 智能面板 (Smart Panel)

    • 在特定网站（Google、GitHub、电商）自动触发
    • 提供场景化服务：搜索摘要、代码解析、商品比价

2. 执行系统 (Motor Layer)

像 Manus 一样完成复杂任务

  • 自主任务闭环 (Autonomous Agent Loop)

    • 用户输入目标 → AI 自动规划步骤 → 后台浏览器执行 → 结果反馈
    • 示例："在闲鱼找个评价好的 iPhone 15" → 自动搜索、筛选、对比

  • 视觉导航 (Visual-Language Acting)

    • 当网站无 API 时，通过 GPT-4o Vision 识别页面元素坐标
    • 模拟真人操作：点击、输入、滚动、表单填写

  • 影子浏览器直播 (Ghost Browser Stream)

    • WebSocket 实时推送后台浏览器操作画面（15 FPS）
    • 任务进度可视化，用户随时可介入或终止

技术架构 (Tech Stack)

层级 技术选型 核心优势
前端插件 Plasmo (React + Tailwind) 现代化扩展开发框架，支持热更新和跨浏览器兼容
AI 中枢 LiteLLM 🔑 核心：统一多模型接口，支持智能路由和自动降级
后端服务 FastAPI 高性能异步框架，原生支持 WebSocket 和长时任务
自动化引擎 Playwright 真实浏览器模拟，支持多标签页协同和反爬虫对抗
Agent 编排 LangGraph Plan-Act-Check 循环，比 LangChain 更稳定和可控
实时通信 WebSocket 毫秒级双向通信，支持流式响应和视频流传输

架构图

┌─────────────────────────────────────────────────────────┐
│  Browser Extension (Plasmo)                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  Sidebar UI  │  │Content Script│  │ Background   │  │
│  │  (React)     │  │ (DOM Capture)│  │   Service    │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
└─────────┼──────────────────┼──────────────────┼─────────┘
          │                  │                  │
          └──────────────────┴──────────────────┘
                             │ WebSocket
          ┌──────────────────┴──────────────────┐
          │  Backend (FastAPI)                  │
          │  ┌────────────────────────────────┐ │
          │  │  LiteLLM Router                │ │
          │  │  ├─ DeepSeek (简单任务)        │ │
          │  │  ├─ Claude 3.5 (复杂推理)      │ │
          │  │  └─ GPT-4o (视觉解析)          │ │
          │  └────────────────────────────────┘ │
          │  ┌────────────────────────────────┐ │
          │  │  LangGraph Agent               │ │
          │  │  Plan → Act → Check → Loop     │ │
          │  └────────────────────────────────┘ │
          │  ┌────────────────────────────────┐ │
          │  │  Playwright Browser Pool       │ │
          │  │  (Headless + Screenshot)       │ │
          │  └────────────────────────────────┘ │
          └─────────────────────────────────────┘

扩展性设计 (Scalability Roadmap)

阶段 1：多模型专家系统

利用 LiteLLM Router 实现智能模型调度

  • 📝 简单总结/翻译 → DeepSeek（成本优化）
  • 🧠 复杂推理/规划 → Claude 3.5 Sonnet（质量优先）
  • 👁️ 视觉解析/定位 → GPT-4o（视觉能力）
  • 🔄 自动降级：主模型失败时切换备用模型

阶段 2：个人技能库 (Skills Library)

让 Flux 学习你的操作习惯

  • 用户录制特定网站的操作流程（如"京东下单流程"）
  • AI 自动提取关键步骤，生成可复用的执行脚本
  • 支持参数化：同一流程适配不同输入（商品名、价格区间）

阶段 3：身份托管中心 (Secure Identity Vault)

安全的跨站点自动化

  • 加密存储用户各平台的 Session/Cookie
  • 支持免登录自动化操作（购物、预约、表单填写）
  • 安全机制：本地加密 + 用户授权 + 定期刷新

阶段 4：跨平台扩展

从浏览器到桌面

  • 通过 Electron 将 Flux 扩展到操作系统级别
  • 支持桌面应用自动化（文件管理、邮件处理）
  • 统一的 AI 助手体验：浏览器 + 桌面 + 移动端

实施路线图 (Implementation Roadmap)

阶段一：核心大脑打通 (Neural Link)

步骤 1.1：LiteLLM 环境集成

  • 内容：创建虚拟环境，安装 litellm 和 python-dotenv，配置 .env 文件存储 API keys
  • 目的：建立统一的模型访问层，支持多模型热切换
  • 验收方式：
    • 自动化测试：运行 pytest tests/test_litellm_integration.py，测试 DeepSeek、OpenAI、Claude 等多个模型调用
    • 手动验证：运行 python -m app.tests.litellm_demo.py，确认能获得各模型的标准化响应
    • 性能测试：单次 API 调用延迟 < 2 秒

步骤 1.2：FastAPI 对话接口封装

  • 内容：实现 /chat WebSocket 接口，支持流式响应，集成错误处理中间件
  • 目的：提供前后端实时通信通道
  • 验收方式：
    • 单元测试：pytest tests/api/test_chat_endpoint.py，覆盖连接建立、消息收发、异常断开场景
    • 集成测试：使用 wscat 或 Postman WebSocket 客户端发送测试消息，验证流式文本接收
    • 压力测试：并发 100 个 WebSocket 连接，保持稳定 5 分钟

阶段二：感知交互构建 (Visual Antenna)

步骤 2.1：Plasmo 侧边栏原型

  • 内容：初始化 Plasmo 项目，使用 Tailwind CSS 构建响应式侧边栏 UI，实现快捷键唤起功能
  • 目的：创建用户友好的交互界面
  • 验收方式：
    • E2E 测试：使用 Playwright 测试插件安装、快捷键唤起（Cmd/Ctrl + Shift + F）、界面渲染
    • 手动验证：Chrome/Edge/Firefox 三大浏览器均能正常加载和显示侧边栏
    • UI 测试：侧边栏在不同屏幕尺寸下保持可用性（最小 320px 宽度）

步骤 2.2：跨域语境抓取

  • 内容：开发 Content Scripts，实现 DOM 解析、选中文本捕获、页面元数据提取，通过消息传递到后端
  • 目的：让 Flux "看到"用户当前浏览内容
  • 验收方式：
    • 单元测试：npm run test content-script.test.ts，验证 HTML 解析、文本选择、元数据提取逻辑
    • 手动验证：访问不同类型网站（GitHub、Google、电商网站），侧边栏显示正确的页面摘要
    • 安全测试：确保无法读取敏感内容（密码框、iframe 跨域限制）

阶段三：端到端动作实现 (Action Limbs)

步骤 3.1：影子浏览器接口

  • 内容：开发 /execute API，集成 Playwright Headless 模式，实现浏览器生命周期管理（启动、导航、截图、关闭）
  • 目的：在后端创建可操控的浏览器实例
  • 验收方式：
    • 单元测试：pytest tests/services/test_playwright.py，测试浏览器启动、页面导航、截图功能
    • 集成测试：调用 API 访问 example.com，验证返回的 base64 截图能正常显示
    • 资源测试：单次浏览任务内存占用 < 500MB，任务完成后自动释放

步骤 3.2：视觉坐标定位

  • 内容：结合 GPT-4o Vision 解析页面截图，提取目标元素坐标，实现智能点击、输入、滚动操作
  • 目的：实现基于视觉的网页操作能力
  • 验收方式：
    • 功能测试：给定常见网站（登录页、搜索页），AI 能正确定位并点击目标元素（准确率 > 85%）
    • 回归测试：创建 50 个测试用例覆盖不同 UI 模式（按钮、输入框、链接、下拉菜单）
    • 手动验证：在 3 个不同网站执行"搜索-点击"流程，成功率 100%

阶段四：任务闭环与直播 (Agent Loop)

步骤 4.1：LangGraph 逻辑编排

  • 内容：实现 Plan-Act-Check 循环，任务分解引擎，步骤依赖管理，失败重试机制
  • 目的：让 Flux 具备自主规划和执行复杂任务的能力
  • 验收方式：
    • 单元测试：pytest tests/agents/test_langgraph.py，测试任务拆解、状态机转换、错误恢复
    • E2E 测试：给定任务"打开豆瓣-搜索《肖申克的救赎》-提取评分和影评数"，验证自动执行
    • 压力测试：同时执行 5 个并发任务，平均完成时间 < 30 秒

步骤 4.2：画面直播流

  • 内容：建立 WebSocket 双向通道，实现 Playwright 截图实时推送（15 FPS），前端视频流渲染
  • 目的：提供可视化的任务执行过程
  • 验收方式：
    • 性能测试：单路视频流延迟 < 200ms，视频码率控制在 1 Mbps 以内
    • 手动验证：观看 AI 执行 3 步操作，画面流畅无卡顿
    • 兼容性测试：在 Chrome、Safari、Edge 浏览器中均能正常播放直播流

关键技术挑战与解决方案

1. 视觉定位准确性

挑战：GPT-4o Vision 识别元素坐标可能不精确，导致点击失败

解决方案：

  • 多模态融合：结合 DOM 结构 + 视觉识别，优先使用 CSS Selector
  • 容错机制：点击失败时自动重试，调整坐标偏移量
  • 置信度评分：低置信度时提示用户手动介入

2. 成本控制

挑战：频繁调用 GPT-4o Vision 成本高昂

解决方案：

  • 智能缓存：相似页面结构复用之前的识别结果
  • 降级策略：简单页面优先使用 Playwright 原生定位
  • 批量处理：一次截图识别多个元素，减少 API 调用

3. 反爬虫对抗

挑战：部分网站检测 Playwright 自动化特征

解决方案：

  • Stealth 插件：隐藏 WebDriver 特征
  • 真实浏览器模式：使用 Playwright 的 channel='chrome' 连接真实浏览器
  • 行为模拟：添加随机延迟、鼠标轨迹、滚动行为

4. 并发任务管理

挑战：多用户同时执行任务时浏览器资源占用过高

解决方案：

  • 浏览器池：预创建 5 个浏览器实例，复用 Context
  • 任务队列：超过并发限制时排队等待
  • 资源监控：内存占用超过阈值时自动清理闲置浏览器

安全与隐私设计

数据安全

  • ✅ API Keys 存储在 .env 文件，永不提交到代码仓库
  • ✅ 用户 Session 使用 AES-256 加密存储
  • ✅ WebSocket 连接强制 WSS（TLS 加密）
  • ✅ 敏感操作（支付、密码）需用户二次确认

隐私保护

  • ✅ 页面内容仅在用户主动触发时发送到后端
  • ✅ 不收集用户浏览历史和个人信息
  • ✅ 支持本地部署模式（Self-hosted）
  • ✅ 截图数据不持久化存储，任务完成后立即删除

权限控制

  • ✅ 浏览器扩展仅请求必要权限（activeTab, storage）
  • ✅ 用户可随时撤销 Flux 的网站访问权限
  • ✅ 敏感网站（银行、医疗）默认禁用自动化功能

开发与部署

快速启动

# 1. 克隆项目
git clone https://github.com/your-org/flux.git
cd flux

# 2. 启动后端
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env  # 配置 API Keys
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 3. 启动前端（新终端）
cd frontend
npm install
npm run dev  # 开发模式，支持热更新

# 4. 加载扩展到浏览器
# Chrome: 访问 chrome://extensions
# 开启"开发者模式" → "加载已解压的扩展程序" → 选择 frontend/build/chrome-mv3-dev

生产部署

# 后端部署（Docker）
docker build -t flux-backend ./backend
docker run -d -p 8000:8000 --env-file .env flux-backend

# 前端打包
cd frontend
npm run build  # 生成 build/chrome-mv3-prod

# 发布到 Chrome Web Store
# 1. 压缩 build/chrome-mv3-prod 为 flux.zip
# 2. 上传到 Chrome Developer Dashboard
# 3. 填写商店信息并提交审核

项目里程碑

阶段 目标 预计时间 关键交付物
MVP 基础对话 + 简单自动化 4 周 侧边栏 + LiteLLM 集成 + Playwright 基础操作
Alpha 视觉导航 + 任务闭环 8 周 GPT-4o Vision 定位 + LangGraph 编排
Beta 实时直播 + 多模型路由 12 周 WebSocket 视频流 + 智能模型调度
V1.0 技能库 + 身份托管 16 周 操作录制 + Session 加密存储
V2.0 跨平台扩展 24 周 Electron 桌面版 + 移动端适配

参考资源

核心依赖文档

相关项目

技术博客

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages