surfai 0.8.1__tar.gz

surfai-0.8.1/.gitignore

@@ -0,0 +1,29 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+/mnt/fnos/
+/tmp/

surfai-0.8.1/DEVELOPMENT_LOG.md

@@ -0,0 +1,315 @@
+# SurfAI 开发日志
+
+**项目**: SurfAI - 自然语言浏览器自动化工具  
+**创建时间**: 2026-03-07  
+**最后更新**: 2026-03-07
+
+---
+
+## 版本历史
+
+- v0.1.0 - MVP 基础功能
+- v0.2.0 - 智能提取 + 数据导出
+- v0.3.0 - 本地解析器（零成本）
+- v0.3.1 - Ollama 优化
+- v0.4.0 - Excel 导出 + 代理支持
+- v0.4.1 - 截图详细日志
+- v0.4.2 - 项目文件夹结构
+- v0.4.3 - 项目文件夹重构
+- v0.4.4 - 文件夹结构最终版
+- v0.5.0 - 网页监控功能
+- v0.6.0 - 反检测增强
+- v0.7.0 - 录制回放功能
+- v0.8.0 - Chrome 扩展
+- v0.8.1 - 扩展前后端联调
+
+---
+
+## Phase 1: MVP 基础功能 (v0.1.0)
+
+### 开发内容
+1. **项目结构搭建** - Python 包结构、虚拟环境
+2. **浏览器核心** - Browser 类、导航、提取、截图
+3. **LLM 集成** - Kimi/DeepSeek/OpenAI 支持
+4. **CLI 工具** - config/run/status 命令
+5. **配置管理** - JSON 配置文件
+
+### 遇到的问题
+- extract() 无 LLM 配置时报错 → 添加优雅降级
+
+---
+
+## Phase 2: 功能增强 (v0.2.0)
+
+### 开发内容
+1. **Ollama 本地 LLM 支持**
+2. **智能提取模块** - 表格、链接、列表、价格
+3. **数据导出模块** - JSON/CSV/TXT
+
+### 遇到的问题
+- 正则表达式转义警告 → 使用原始字符串
+
+---
+
+## Phase 3: 零成本模式 (v0.3.0)
+
+### 开发内容
+1. **本地意图解析器** - 无需 API Key
+2. **LocalProvider** - 自动降级到本地模式
+3. **中英文指令支持**
+
+---
+
+## Phase 4: Ollama 集成优化 (v0.3.1)
+
+### 开发内容
+1. **Ollama 配置** - qwen3.5:0.8b 模型
+2. **超时优化** - 120秒超时
+3. **双 API 支持** - /api/chat + /api/generate
+
+### 遇到的问题
+- Ollama API 404 → 实现双 API 支持
+- 模型推理超时 → 增加超时时间 + 降级处理
+
+---
+
+## Phase 5: Excel 导出和代理支持 (v0.4.0)
+
+### 开发内容
+1. **Excel 导出** - openpyxl 支持
+2. **自动样式** - 蓝色表头 + 自动列宽
+3. **代理支持** - HTTP/SOCKS5
+
+---
+
+## Phase 6: 截图详细日志 (v0.4.1)
+
+### 开发内容
+- screenshot() 返回字典而非字符串
+- 包含成功状态、文件大小、页面信息等
+
+---
+
+## Phase 7: 项目文件夹结构 (v0.4.2 - v0.4.4)
+
+### 开发内容
+- 创建 `/mnt/fnos/SurfAI/` 项目根目录
+- 开发日志文件夹
+- 项目文件文件夹（截图 + 导出数据）
+- 整理所有历史文件到新结构
+
+### 最终结构
+```
+/mnt/fnos/SurfAI/
+├── 开发日志/
+└── 项目文件/
+    ├── 截图/
+    └── 导出数据/
+```
+
+---
+
+## Phase 8: 网页监控功能 (v0.5.0)
+
+### 开发内容
+1. **PageMonitor 类** - 定时检查网页变化
+2. **变化检测** - 支持元素或整页监控
+3. **自动截图** - 变化时自动截图
+4. **历史记录** - 保存监控历史
+
+### 使用方式
+```python
+from surfai import PageMonitor
+
+monitor = PageMonitor()
+await monitor.watch(
+    url='https://example.com',
+    interval=60,
+    max_checks=10,
+)
+```
+
+---
+
+## Phase 9: 反检测增强 (v0.6.0)
+
+### 开发内容
+1. **StealthConfig** - 反检测配置
+2. **隐藏 webdriver** - navigator.webdriver = undefined
+3. **模拟插件** - 3个真实浏览器插件
+4. **随机指纹** - User Agent、视口、语言
+5. **Cloudflare 支持** - 自动检测验证
+
+### 测试结果
+```
+🚀 测试反检测功能
+============================================================
+🧪 测试 1: 默认反检测模式
+   navigator.webdriver: None
+   navigator.plugins.length: 3
+   User Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...
+   ✅ 反检测模式工作正常
+
+🧪 测试 2: 自定义反检测配置
+   navigator.languages: ['zh-CN', 'zh', 'en-US', 'en']
+   ✅ 自定义配置工作正常
+
+🧪 测试 3: 关闭反检测模式
+   ✅ 正常模式工作正常
+
+============================================================
+🎉 反检测功能测试通过!
+============================================================
+```
+
+### 使用方式
+```python
+from surfai import Browser, StealthConfig
+
+# 默认开启反检测
+browser = Browser()
+
+# 自定义配置
+config = StealthConfig(
+    hide_webdriver=True,
+    fake_plugins=True,
+    fake_languages=True,
+    random_viewport=True,
+)
+browser = Browser(stealth=True, stealth_config=config)
+```
+
+---
+
+## 项目统计
+
+| 类别 | 数量 |
+|------|------|
+| 截图文件 | 7 个 |
+| 导出文件 | 9 个 |
+| 开发日志 | 4 个 |
+| 版本迭代 | 11 个 |
+
+---
+
+## Phase 10: 录制回放功能 (v0.7.0)
+
+### 开发内容
+1. **ActionRecorder 类** - 录制浏览器动作
+2. **ActionPlayer 类** - 回放录制的动作
+3. **RecordingBrowser 类** - 带录制功能的浏览器
+4. **录制格式** - JSON 格式保存
+
+### 支持的动作
+- `goto` - 导航到 URL
+- `click` - 点击元素
+- `type` - 输入文本
+- `extract` - 提取数据
+- `screenshot` - 截图
+- `wait` - 等待
+- `scroll` - 滚动
+
+### 测试结果
+```
+🚀 测试录制回放功能
+============================================================
+🧪 测试 1: 录制动作
+🔴 开始录制...
+   📝 录制: goto {'url': 'example.com'}
+   📝 录制: click {'selector': 'button'}
+   📝 录制: type {'selector': 'input', 'text': 'hello'}
+   📝 录制: screenshot {}
+⏹️  录制结束，共 4 个动作
+💾 录制已保存: /mnt/fnos/SurfAI/项目文件/导出数据/recording_20260307_093111.json
+
+🧪 测试 2: 回放动作
+▶️  开始回放，共 4 个动作
+   [1/4] 执行: goto ✅
+   [2/4] 执行: click ❌ (页面无此元素)
+   [3/4] 执行: type ❌ (页面无此元素)
+   [4/4] 执行: screenshot ✅
+✅ 回放完成
+
+🧪 测试 3: 验证录制文件
+✅ 录制文件有效，共 4 个动作
+============================================================
+🎉 录制回放功能测试通过!
+============================================================
+```
+
+### 使用方式
+```python
+from surfai import ActionRecorder, ActionPlayer, Browser
+
+# 录制
+recorder = ActionRecorder()
+recorder.start()
+recorder.record('goto', {'url': 'example.com'})
+recorder.record('click', {'selector': 'button'})
+recorder.stop()
+recorder.save()
+
+# 回放
+browser = Browser()
+await browser.launch()
+player = ActionPlayer()
+await player.play('recording.json', browser)
+```
+
+---
+
+## Phase 11: Chrome 扩展 (v0.8.0)
+
+### 开发内容
+1. **扩展清单** - manifest.json v3
+2. **侧边栏界面** - 美观的 UI 设计
+3. **后端 API** - FastAPI 服务
+4. **功能集成**:
+   - 执行指令
+   - 截图
+   - 执行历史
+   - 连接状态显示
+
+### 扩展结构
+```
+extension/
+├── manifest.json
+├── icons/
+├── popup/
+│   ├── sidepanel.html
+│   └── sidepanel.js
+└── background/
+    └── background.js
+```
+
+### v0.8.1 更新
+- 添加 `surfai server` CLI 命令
+- 完善后台脚本 (background.js)
+- 优化侧边栏通信逻辑
+- 添加截图预览通知
+- 添加错误提示通知
+
+### 使用方式
+1. 安装 Chrome 扩展
+2. 启动后端服务: `surfai server`
+3. 在侧边栏输入指令
+
+### 后端 API
+- `POST /execute` - 执行指令
+- `POST /screenshot` - 截图
+- `GET /health` - 健康检查
+- `GET /config` - 获取配置
+
+---
+
+## 待办事项
+
+- [ ] 用户使用真实 API Key 测试
+- [ ] 测试复杂网站（GitHub、淘宝等）
+- [ ] 发布到 PyPI
+- [ ] 发布 Chrome 扩展
+- [ ] 完善文档和示例
+
+---
+
+**维护说明**: 此日志会持续追加更新，不删除历史内容。

surfai-0.8.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SurfAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

surfai-0.8.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include surfai *.py

surfai-0.8.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: surfai
+Version: 0.8.1
+Summary: Natural language browser automation
+Project-URL: Homepage, https://github.com/surfai/surfai
+Project-URL: Repository, https://github.com/surfai/surfai
+Author: SurfAI Team
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,browser,llm,scraping
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn>=0.23.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SurfAI
+
+🏄 **Natural Language Browser Automation**
+
+Say what you want, SurfAI does the browsing.
+
+## Quick Start
+
+```bash
+# Install
+pip install surfai
+
+# Configure your LLM (choose one)
+surfai config --model kimi --key sk-your-kimi-key
+surfai config --model deepseek --key sk-your-deepseek-key
+
+# Start automating
+surfai "Go to GitHub and find the most starred Python project"
+```
+
+## Features
+
+- 🎯 **Zero Code**: Just say what you want in natural language
+- 🤖 **Multi-LLM**: Supports Kimi, DeepSeek, OpenAI, Gemini
+- 🔒 **Local First**: Runs on your machine, data stays private
+- 📸 **Screenshots**: Capture pages automatically
+- 📊 **Data Export**: Save results to CSV, JSON, Excel
+
+## Supported Models
+
+| Model | Provider | Setup |
+|-------|----------|-------|
+| Kimi | Moonshot | `surfai config --model kimi --key sk-xxx` |
+| DeepSeek | DeepSeek | `surfai config --model deepseek --key sk-xxx` |
+| GPT-4o | OpenAI | `surfai config --model openai --key sk-xxx` |
+| Gemini | Google | `surfai config --model gemini --key xxx` |
+
+## Usage Examples
+
+### Command Line
+
+```bash
+# Extract data
+surfai "Go to example.com and get all product prices"
+
+# Take screenshot
+surfai "Open github.com/microsoft and take a screenshot"
+
+# Complex task
+surfai "Search for 'Python tutorials' on Google, open the first result, summarize the content"
+```
+
+### Python API
+
+```python
+import asyncio
+from surfai import Browser
+
+async def main():
+    async with Browser() as browser:
+        await browser.goto("https://github.com/openclaw/openclaw")
+        stars = await browser.extract("stars count")
+        print(f"Stars: {stars}")
+        await browser.screenshot("openclaw.png")
+
+asyncio.run(main())
+```
+
+## Configuration
+
+Configuration is stored in `~/.surfai/config.json`:
+
+```json
+{
+  "default_model": "kimi",
+  "models": {
+    "kimi": {
+      "api_key": "sk-xxx",
+      "base_url": "https://api.moonshot.cn/v1"
+    },
+    "deepseek": {
+      "api_key": "sk-xxx",
+      "base_url": "https://api.deepseek.com/v1"
+    }
+  }
+}
+```
+
+## License
+
+MIT License - see LICENSE file for details.

surfai-0.8.1/PROGRESS.md

@@ -0,0 +1,32 @@
+# SurfAI
+
+## 开发进度
+
+### Phase 1: MVP (进行中)
+
+- [x] 项目结构搭建
+- [x] 配置管理 (Config)
+- [x] LLM 抽象层
+- [x] Kimi (Moonshot) 集成
+- [x] DeepSeek 集成
+- [x] OpenAI 集成
+- [x] LLM Router
+- [x] 浏览器核心 (Browser)
+- [x] CLI 命令行接口
+- [x] 示例代码
+- [ ] 安装测试
+- [ ] 文档完善
+
+### Phase 2: 增强 (待开始)
+
+- [ ] Gemini 支持
+- [ ] 智能表格提取
+- [ ] 数据导出 (CSV/Excel)
+- [ ] 反检测增强
+- [ ] 错误重试机制
+
+### Phase 3: 云端 (待开始)
+
+- [ ] 云端浏览器托管
+- [ ] 代理 IP 池
+- [ ] Dashboard

surfai-0.8.1/PROJECT.md

@@ -0,0 +1,86 @@
+# SurfAI 项目管理
+
+## 项目信息
+
+- **名称**: SurfAI
+- **路径**: `/home/alpha/.openclaw/workspace/projects/surfai`
+- **环境**: Python 3.12 + 虚拟环境
+- **版本**: 0.2.0
+- **状态**: Phase 2 完成
+
+## 快速开始
+
+```bash
+cd /home/alpha/.openclaw/workspace/projects/surfai
+source venv/bin/activate
+
+# 配置 API 模型
+surfai config --model kimi --key <your-key>
+# 或配置本地 Ollama（零成本）
+surfai config --model ollama --key dummy --base-url http://localhost:11434
+
+# 使用
+surfai run "你的指令"
+```
+
+## 开发规范
+
+1. **必须在虚拟环境中开发**
+   ```bash
+   source venv/bin/activate
+   ```
+
+2. **安装新依赖**
+   ```bash
+   pip install <package>
+   # 然后更新 pyproject.toml
+   ```
+
+3. **测试**
+   ```bash
+   pytest
+   ```
+
+## 目录结构
+
+```
+surfai/
+├── surfai/           # 主代码
+│   ├── browser.py    # 浏览器核心
+│   ├── cli.py        # 命令行
+│   ├── config.py     # 配置管理
+│   ├── extractor.py  # 智能提取
+│   ├── exporter.py   # 数据导出
+│   └── llm/          # LLM  providers
+├── examples/         # 示例
+├── tests/            # 测试
+├── venv/             # 虚拟环境（不提交）
+├── pyproject.toml    # 包配置
+└── README.md         # 文档
+```
+
+## 功能清单
+
+### Phase 1 (✅ 完成)
+- [x] 浏览器核心（导航、截图、CSS 提取）
+- [x] Kimi/DeepSeek/OpenAI 集成
+- [x] CLI 命令行
+- [x] 配置管理
+
+### Phase 2 (✅ 完成)
+- [x] Ollama 本地 LLM 支持
+- [x] 智能提取（表格、链接、列表、价格）
+- [x] 数据导出（JSON/CSV/TXT）
+- [x] 复杂交互（点击、输入、滚动）
+
+### Phase 3 (待开始)
+- [ ] 云端浏览器托管
+- [ ] 代理 IP 池
+- [ ] Dashboard
+- [ ] 更多导出格式（Excel）
+
+## 待办
+
+- [ ] 用户测试（需要 API Key）
+- [ ] 完善文档
+- [ ] 发布到 PyPI

surfai-0.8.1/README.md

@@ -0,0 +1,91 @@
+# SurfAI
+
+🏄 **Natural Language Browser Automation**
+
+Say what you want, SurfAI does the browsing.
+
+## Quick Start
+
+```bash
+# Install
+pip install surfai
+
+# Configure your LLM (choose one)
+surfai config --model kimi --key sk-your-kimi-key
+surfai config --model deepseek --key sk-your-deepseek-key
+
+# Start automating
+surfai "Go to GitHub and find the most starred Python project"
+```
+
+## Features
+
+- 🎯 **Zero Code**: Just say what you want in natural language
+- 🤖 **Multi-LLM**: Supports Kimi, DeepSeek, OpenAI, Gemini
+- 🔒 **Local First**: Runs on your machine, data stays private
+- 📸 **Screenshots**: Capture pages automatically
+- 📊 **Data Export**: Save results to CSV, JSON, Excel
+
+## Supported Models
+
+| Model | Provider | Setup |
+|-------|----------|-------|
+| Kimi | Moonshot | `surfai config --model kimi --key sk-xxx` |
+| DeepSeek | DeepSeek | `surfai config --model deepseek --key sk-xxx` |
+| GPT-4o | OpenAI | `surfai config --model openai --key sk-xxx` |
+| Gemini | Google | `surfai config --model gemini --key xxx` |
+
+## Usage Examples
+
+### Command Line
+
+```bash
+# Extract data
+surfai "Go to example.com and get all product prices"
+
+# Take screenshot
+surfai "Open github.com/microsoft and take a screenshot"
+
+# Complex task
+surfai "Search for 'Python tutorials' on Google, open the first result, summarize the content"
+```
+
+### Python API
+
+```python
+import asyncio
+from surfai import Browser
+
+async def main():
+    async with Browser() as browser:
+        await browser.goto("https://github.com/openclaw/openclaw")
+        stars = await browser.extract("stars count")
+        print(f"Stars: {stars}")
+        await browser.screenshot("openclaw.png")
+
+asyncio.run(main())
+```
+
+## Configuration
+
+Configuration is stored in `~/.surfai/config.json`:
+
+```json
+{
+  "default_model": "kimi",
+  "models": {
+    "kimi": {
+      "api_key": "sk-xxx",
+      "base_url": "https://api.moonshot.cn/v1"
+    },
+    "deepseek": {
+      "api_key": "sk-xxx",
+      "base_url": "https://api.deepseek.com/v1"
+    }
+  }
+}
+```
+
+## License
+
+MIT License - see LICENSE file for details.