diff --git a/docs/docs.json b/docs/docs.json index fcacd6dd7..f33f030d0 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -9,60 +9,137 @@ }, "favicon": "/favicon.svg", "navigation": { - "tabs": [ + "languages": [ { - "tab": "Documentation", - "groups": [ + "language": "en", + "tabs": [ { - "group": "Getting Started", - "pages": ["introduction", "quickstart"] - }, - { - "group": "User Guides", - "pages": [ - "guides/task-creation", - "guides/password-management", - "guides/takeover-mode" - ] - }, - { - "group": "Deployment", - "pages": [ - "deployment/railway", - "deployment/helm", - "deployment/litellm" + "tab": "Documentation", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "introduction", + "quickstart" + ] + }, + { + "group": "User Guides", + "pages": [ + "guides/task-creation", + "guides/password-management", + "guides/takeover-mode" + ] + }, + { + "group": "Deployment", + "pages": [ + "deployment/railway", + "deployment/helm", + "deployment/litellm" + ] + }, + { + "group": "Core Concepts", + "pages": [ + "core-concepts/architecture", + "core-concepts/agent-system", + "core-concepts/desktop-environment", + "core-concepts/rpa-comparison" + ] + } ] }, { - "group": "Core Concepts", - "pages": [ - "core-concepts/architecture", - "core-concepts/agent-system", - "core-concepts/desktop-environment", - "core-concepts/rpa-comparison" + "tab": "API Reference", + "groups": [ + { + "group": "Overview", + "pages": [ + "api-reference/introduction" + ] + }, + { + "group": "Agent API", + "pages": [ + "api-reference/agent/tasks", + "api-reference/agent/ui" + ] + }, + { + "group": "Computer Control API", + "pages": [ + "api-reference/computer-use/unified-endpoint", + "api-reference/computer-use/examples" + ] + } ] } ] }, - { - "tab": "API Reference", - "groups": [ - { - "group": "Overview", - "pages": ["api-reference/introduction"] - }, + { + "language": "cn", + "tabs": [ { - "group": "Agent API", - "pages": [ - "api-reference/agent/tasks", - "api-reference/agent/ui" + "tab": "文档", + "groups": [ + { + "group": "快速开始", + "pages": [ + "/zh/introduction", + "/zh/quickstart" + ] + }, + { + "group": "用户指南", + "pages": [ + "zh/guides/task-creation", + "zh/guides/password-management", + "zh/guides/takeover-mode" + ] + }, + { + "group": "部署", + "pages": [ + "zh/deployment/railway", + "zh/deployment/helm", + "zh/deployment/litellm" + ] + }, + { + "group": "核心概念", + "pages": [ + "zh/core-concepts/architecture", + "zh/core-concepts/agent-system", + "zh/core-concepts/desktop-environment", + "zh/core-concepts/rpa-comparison" + ] + } ] }, { - "group": "Computer Control API", - "pages": [ - "api-reference/computer-use/unified-endpoint", - "api-reference/computer-use/examples" + "tab": "API Reference", + "groups": [ + { + "group": "Overview", + "pages": [ + "zh/api-reference/introduction" + ] + }, + { + "group": "Agent API", + "pages": [ + "zh/api-reference/agent/tasks", + "zh/api-reference/agent/ui" + ] + }, + { + "group": "Computer Control API", + "pages": [ + "zh/api-reference/computer-use/unified-endpoint", + "zh/api-reference/computer-use/examples" + ] + } ] } ] diff --git a/docs/zh/api-reference/agent/tasks.mdx b/docs/zh/api-reference/agent/tasks.mdx new file mode 100644 index 000000000..3b7f6e747 --- /dev/null +++ b/docs/zh/api-reference/agent/tasks.mdx @@ -0,0 +1,310 @@ +--- +title: '任务 API' +description: 'Bytebot 代理任务 API 参考文档' +--- + +## 任务 API + +任务 API 允许您管理 Bytebot 代理系统中的任务。在完整代理设置运行时，可通过 `http://localhost:9991/tasks` 访问。 + +## 任务模型 + +```typescript +{ + id: string; + description: string; + status: 'PENDING' | 'IN_PROGRESS' | 'NEEDS_HELP' | 'NEEDS_REVIEW' | 'COMPLETED' | 'CANCELLED' | 'FAILED'; + priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'; + createdAt: string; + updatedAt: string; +} +``` + +## 端点 + +### 创建任务 + +创建新任务供代理处理。 + + + 创建新任务 + + +#### 请求体 + +```json +{ + "description": "This is a description of the task", + "priority": "MEDIUM" // Optional: LOW, MEDIUM, HIGH, URGENT +} +``` + +#### 带文件上传 + +要上传任务文件，请使用 `multipart/form-data`： + +```bash +curl -X POST http://localhost:9991/tasks \ + -F "description=Analyze the uploaded contracts and extract key terms" \ + -F "priority=HIGH" \ + -F "files=@contract1.pdf" \ + -F "files=@contract2.pdf" +``` + +上传的文件会自动保存到桌面，并可在任务描述中引用。 + +#### 响应 + +```json +{ + "id": "task-123", + "description": "This is a description of the task", + "status": "PENDING", + "priority": "MEDIUM", + "createdAt": "2025-04-14T12:00:00Z", + "updatedAt": "2025-04-14T12:00:00Z" +} +``` + +### 获取所有任务 + +检索所有任务的列表。 + + + 获取所有任务 + + +#### 响应 + +```json +[ + { + "id": "task-123", + "description": "This is a description of the task", + "status": "PENDING", + "priority": "MEDIUM", + "createdAt": "2025-04-14T12:00:00Z", + "updatedAt": "2025-04-14T12:00:00Z" + }, + // ...more tasks +] +``` + +### 获取进行中任务 + +检索当前正在进行的任务（如果有）。 + + + 获取当前进行中的任务 + + +#### 响应 + +```json +{ + "id": "task-123", + "description": "This is a description of the task", + "status": "IN_PROGRESS", + "priority": "MEDIUM", + "createdAt": "2025-04-14T12:00:00Z", + "updatedAt": "2025-04-14T12:00:00Z" +} +``` + +如果没有任务正在进行，响应将为 `null`。 + +### 按 ID 获取任务 + +按 ID 检索特定任务。 + + + 按 ID 获取任务 + + +#### 响应 + +```json +{ + "id": "task-123", + "description": "This is a description of the task", + "status": "PENDING", + "priority": "MEDIUM", + "createdAt": "2025-04-14T12:00:00Z", + "updatedAt": "2025-04-14T12:00:00Z", + "messages": [ + { + "id": "msg-456", + "content": [ + { + "type": "text", + "text": "This is a message" + } + ], + "role": "USER", + "taskId": "task-123", + "createdAt": "2025-04-14T12:05:00Z", + "updatedAt": "2025-04-14T12:05:00Z" + } + // ...more messages + ] +} +``` + +### 更新任务 + +更新现有任务。 + + + 更新任务 + + +#### 请求体 + +```json +{ + "status": "COMPLETED", + "priority": "HIGH" +} +``` + +#### 响应 + +```json +{ + "id": "task-123", + "description": "This is a description of the task", + "status": "COMPLETED", + "priority": "HIGH", + "createdAt": "2025-04-14T12:00:00Z", + "updatedAt": "2025-04-14T12:01:00Z" +} +``` + +### 删除任务 + +删除任务。 + + + 删除任务 + + +#### 响应 + +状态码 `204 No Content`，响应体为空。 + +## 消息内容结构 + +Bytebot 代理系统中的消息使用与 Anthropic 的 Claude API 兼容的内容块结构： + +```typescript +type MessageContent = MessageContentBlock[]; + +interface MessageContentBlock { + type: string; + [key: string]: any; +} + +interface TextContentBlock { + type: "text"; + text: string; +} + +interface ImageContentBlock { + type: "image"; + source: { + type: "base64"; + media_type: string; + data: string; + }; +} +``` + +## 错误响应 + +API 可能返回以下错误响应： + +| 状态码 | 描述 | +|-------------|--------------------------------------------| +| `400` | 错误请求 - 参数无效 | +| `404` | 未找到 - 资源不存在 | +| `500` | 内部服务器错误 - 服务器端错误 | + +错误响应示例： + +```json +{ + "statusCode": 404, + "message": "Task with ID task-123 not found", + "error": "Not Found" +} +``` + +## 代码示例 + + +```javascript JavaScript +const axios = require('axios'); + +async function createTask(description) { + const response = await axios.post('http://localhost:9991/tasks', { + description + }); + return response.data; +} + +async function findInProgressTask() { + const response = await axios.get('http://localhost:9991/tasks/in-progress'); + return response.data; +} + +// Example usage +async function main() { + // Create a new task + const task = await createTask('Compare React, Vue, and Angular for a new project'); + console.log('Created task:', task); + + // Get current in-progress task + const inProgressTask = await findInProgressTask(); + console.log('In progress task:', inProgressTask); +} +``` + +```python Python +import requests + +def create_task(description): + response = requests.post( + "http://localhost:9991/tasks", + json={ + "description": description + } + ) + return response.json() + +def find_in_progress_task(): + response = requests.get("http://localhost:9991/tasks/in-progress") + return response.json() + +# Example usage +def main(): + # Create a new task + task = create_task("Compare React, Vue, and Angular for a new project") + print(f"Created task: {task}") + + # Get current in-progress task + in_progress_task = find_in_progress_task() + print(f"In progress task: {in_progress_task}") +``` + +```curl cURL +# Create a new task +curl -X POST http://localhost:9991/tasks \ + -H "Content-Type: application/json" \ + -d '{ + "description": "Compare React, Vue, and Angular for a new project" + }' + +# Get current in-progress task +curl -X GET http://localhost:9991/tasks/in-progress +``` + \ No newline at end of file diff --git a/docs/zh/api-reference/agent/ui.mdx b/docs/zh/api-reference/agent/ui.mdx new file mode 100644 index 000000000..ae2de78ea --- /dev/null +++ b/docs/zh/api-reference/agent/ui.mdx @@ -0,0 +1,150 @@ +--- +title: '任务界面' +description: 'Bytebot 任务界面文档' +--- + +## Bytebot 任务界面 + +Bytebot 任务界面提供了一个基于网页的界面，用于与 Bytebot 代理系统进行交互。它结合了操作动态和嵌入式 noVNC 查看器，让您可以实时观看它在桌面上执行任务。 + +Bytebot Task Detail + +## 访问界面 + +当运行完整的 Bytebot 代理系统时，任务界面可在以下位置访问： + +``` +http://localhost:9992 +``` + +## 界面组件 + +### 任务管理面板 + +任务管理面板允许您： + +- 创建新任务 +- 查看现有任务 +- 查看任务状态和优先级 +- 选择要处理的任务 + +Task Management Panel + +### 任务界面 + +主任务界面提供： + +- 与代理的任务历史记录 +- 消息中支持 Markdown 格式 +- 自动滚动到新消息 + +### 桌面查看器 + +嵌入式 noVNC 查看器显示： + +- 桌面环境的实时视图 +- 代理操作的可视化反馈 +- 可展开以接管桌面的选项 +- 连接状态指示器 + +## 功能特性 + +### 任务创建 + +要创建新任务： + +1. 输入任务描述 +2. 点击“开始任务”按钮（或按 Enter 键） + +### 对话控制 + +任务界面支持： + +- 带有 Markdown 格式的文本消息 +- 查看消息中的图像内容 +- 显示工具使用操作 +- 展示工具结果 + +### 桌面交互 + +虽然主要用于查看，桌面面板允许： + +- 接管桌面 +- 实时监控代理操作 + +## 消息类型 + +任务界面根据 Bytebot 的内容块结构显示不同类型的消息： + +- **用户消息**：您的指令和查询 +- **助手消息**：来自代理的响应，可能包括： + - **文本内容块**：Markdown 格式的文本响应 + - **图像内容块**：生成或捕获的图像 + - **工具使用内容块**：正在执行的计算机操作 + - **工具结果内容块**：计算机操作的结果 + +消息内容结构遵循以下格式： + +```typescript +interface Message { + id: string; + content: MessageContentBlock[]; + role: Role; // "USER" or "ASSISTANT" + createdAt?: string; +} + +interface MessageContentBlock { + type: string; + [key: string]: any; +} + +interface TextContentBlock extends MessageContentBlock { + type: "text"; + text: string; +} + +interface ImageContentBlock extends MessageContentBlock { + type: "image"; + source: { + type: "base64"; + media_type: string; + data: string; + }; +} +``` + +## 技术细节 + +Bytebot 任务用户界面使用以下技术构建： + +- **Next.js**：前端的 React 框架 +- **Tailwind CSS**：用于样式设计 +- **ReactMarkdown**：用于渲染 markdown 内容 +- **noVNC**：用于嵌入式桌面查看器 + +## 故障排除 + +### 连接问题 + +如果您遇到连接问题： + +1. 确保所有 Bytebot 服务正在运行 +2. 检查端口 9990、9991 和 9992 是否可访问 +3. 尝试刷新浏览器 +4. 检查浏览器控制台中的错误消息 + +### 桌面查看器问题 + +如果桌面查看器未显示： + +1. 确保 Bytebot 容器正在运行 +2. 检查 noVNC 服务是否在端口 9990 可访问 + +### 消息显示问题 + +如果消息未正确显示： + +1. 检查消息内容格式是否正确 +2. 确保代理服务正在正确处理任务 +3. 检查浏览器控制台是否存在渲染错误 +4. 尝试刷新浏览器 \ No newline at end of file diff --git a/docs/zh/api-reference/computer-use/examples.mdx b/docs/zh/api-reference/computer-use/examples.mdx new file mode 100644 index 000000000..f096e480c --- /dev/null +++ b/docs/zh/api-reference/computer-use/examples.mdx @@ -0,0 +1,544 @@ +--- +title: "计算机使用 API 示例" +description: "使用 Bytebot API 实现常见自动化场景的代码示例" +--- + +## 基础示例 + +以下是在不同编程语言中使用计算机使用 API 的一些实用示例。 + +### 使用 cURL + + +```bash Opening a Web Browser +# Move to Firefox/Chrome icon in the dock and click it +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "move_mouse", "coordinates": {"x": 100, "y": 960}}' + +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "click_mouse", "button": "left", "clickCount": 1}' + +```` + +```bash Taking and Saving a Screenshot +# Take a screenshot +response=$(curl -s -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "screenshot"}') + +# Extract the base64 image data and save to a file +echo $response | jq -r '.data.image' | base64 -d > screenshot.png +```` + +```bash Typing and Keyboard Shortcuts +# Type text in a text editor +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "type_text", "text": "Hello, this is an automated test!", "delay": 30}' + +# Press Ctrl+S to save +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "press_keys", "key": "s", "modifiers": ["control"]}' +``` + + + +### Python 示例 + + +```python Basic Automation +import requests +import json +import base64 +import time +from io import BytesIO +from PIL import Image + +def control_computer(action, **params): +url = "http://localhost:9990/computer-use" +data = {"action": action, **params} +response = requests.post(url, json=data) +return response.json() + +# Open a web browser by clicking an icon + +control_computer("move_mouse", coordinates={"x": 100, "y": 960}) +control_computer("click_mouse", button="left") + +# Wait for the browser to open + +control_computer("wait", duration=2000) + +# Type a URL + +control_computer("type_text", text="https://example.com") +control_computer("press_keys", key="enter") + +```` + +```python Screenshot and Analysis +import requests +import json +import base64 +import cv2 +import numpy as np +from PIL import Image +from io import BytesIO + +def take_screenshot(): + url = "http://localhost:9990/computer-use" + data = {"action": "screenshot"} + response = requests.post(url, json=data) + + if response.json()["success"]: + img_data = base64.b64decode(response.json()["data"]["image"]) + image = Image.open(BytesIO(img_data)) + return np.array(image) + return None + +# Take a screenshot +img = take_screenshot() + +# Convert to grayscale for analysis +if img is not None: + gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) + + # Save the screenshot + cv2.imwrite("screenshot.png", img) + + # Perform image analysis (example: find edges) + edges = cv2.Canny(gray, 100, 200) + cv2.imwrite("edges.png", edges) +```` + +```python Web Form Automation +import requests +import time + +def control_computer(action, **params): + url = "http://localhost:9990/computer-use" + data = {"action": action, **params} + response = requests.post(url, json=data) + return response.json() + +def fill_web_form(form_fields): + # Click on the first form field + control_computer("move_mouse", coordinates=form_fields[0]) + control_computer("click_mouse", button="left") + + # Fill out each field + for i, field in enumerate(form_fields): + # Input the field value + control_computer("type_text", text=field["value"]) + + # If not the last field, press Tab to move to next field + if i < len(form_fields) - 1: + control_computer("press_keys", key="tab") + time.sleep(0.5) + + # Submit the form by pressing Enter + control_computer("press_keys", key="enter") + +# Example form fields with coordinates and values +form_fields = [ + {"x": 500, "y": 300, "value": "John Doe"}, + {"x": 500, "y": 350, "value": "john@example.com"}, + {"x": 500, "y": 400, "value": "Password123"} +] + +fill_web_form(form_fields) +``` + + + +### JavaScript/Node.js 示例 + + +```javascript Basic Automation +const axios = require('axios'); + +async function controlComputer(action, params = {}) { +const url = "http://localhost:9990/computer-use"; +const data = { action, ...params }; + +try { +const response = await axios.post(url, data); +return response.data; +} catch (error) { +console.error('Error:', error.message); +return { success: false, error: error.message }; +} +} + +// Example: Automate opening an application and typing +async function automateTextEditor() { +try { +// Open text editor by clicking its icon +await controlComputer("move_mouse", { coordinates: { x: 150, y: 960 } }); +await controlComputer("click_mouse", { button: "left" }); + + // Wait for it to open + await controlComputer("wait", { duration: 2000 }); + + // Type some text + await controlComputer("type_text", { + text: "This is an automated test using Node.js and Bytebot", + delay: 30 + }); + + console.log("Automation completed successfully"); + +} catch (error) { +console.error("Automation failed:", error); +} +} + +automateTextEditor(); + +```` + +```javascript Advanced: Screenshot Comparison +const axios = require('axios'); +const fs = require('fs'); +const { createCanvas, loadImage } = require('canvas'); +const pixelmatch = require('pixelmatch'); + +async function controlComputer(action, params = {}) { + const url = "http://localhost:9990/computer-use"; + const data = { action, ...params }; + + try { + const response = await axios.post(url, data); + return response.data; + } catch (error) { + console.error('Error:', error.message); + return { success: false, error: error.message }; + } +} + +async function compareScreenshots() { + try { + // Take first screenshot + const screenshot1 = await controlComputer("screenshot"); + + // Do some actions + await controlComputer("move_mouse", { coordinates: { x: 500, y: 500 } }); + await controlComputer("click_mouse", { button: "left" }); + await controlComputer("wait", { duration: 1000 }); + + // Take second screenshot + const screenshot2 = await controlComputer("screenshot"); + + // Compare screenshots + if (screenshot1.success && screenshot2.success) { + const img1Data = Buffer.from(screenshot1.data.image, 'base64'); + const img2Data = Buffer.from(screenshot2.data.image, 'base64'); + + fs.writeFileSync('screenshot1.png', img1Data); + fs.writeFileSync('screenshot2.png', img2Data); + + // Now you could load and compare these images + // This requires additional image comparison libraries + console.log('Screenshots saved for comparison'); + } + } catch (error) { + console.error("Screenshot comparison failed:", error); + } +} + +compareScreenshots(); +```` + + + +## 文件操作 + +### 写入文件 + +这些示例展示了如何向桌面环境写入文件： + + +```python Python +import requests +import base64 + +def write_file(path, content): + url = "http://localhost:9990/computer-use" + + # Encode content to base64 + encoded_content = base64.b64encode(content.encode('utf-8')).decode('utf-8') + + data = { + "action": "write_file", + "path": path, + "data": encoded_content + } + + response = requests.post(url, json=data) + return response.json() + +# Write a text file +result = write_file("/home/user/hello.txt", "Hello, Bytebot!") +print(result) # {'success': True, 'message': 'File written successfully...'} + +# Write to desktop (relative path) +result = write_file("report.txt", "Daily report content") +print(result) # File will be written to /home/user/Desktop/report.txt +``` + +```javascript JavaScript +const axios = require('axios'); + +async function writeFile(path, content) { + const url = "http://localhost:9990/computer-use"; + + // Encode content to base64 + const encodedContent = Buffer.from(content, 'utf-8').toString('base64'); + + const data = { + action: "write_file", + path: path, + data: encodedContent + }; + + const response = await axios.post(url, data); + return response.data; +} + +// Write a text file +writeFile("/home/user/notes.txt", "Meeting notes...") + .then(result => console.log(result)) + .catch(error => console.error(error)); + +// Write HTML file to desktop +const htmlContent = '

Hello

'; +writeFile("index.html", htmlContent) + .then(result => console.log("HTML file created")); +``` + + +### 读取文件 + +这些示例展示了如何从桌面环境读取文件： + + +```python Python +import requests +import base64 + +def read_file(path): + url = "http://localhost:9990/computer-use" + + data = { + "action": "read_file", + "path": path + } + + response = requests.post(url, json=data) + result = response.json() + + if result['success']: + # Decode the base64 content + content = base64.b64decode(result['data']).decode('utf-8') + return { + 'content': content, + 'name': result['name'], + 'size': result['size'], + 'mediaType': result['mediaType'] + } + else: + return result + +# Read a text file +file_data = read_file("/home/user/hello.txt") +print(f"Content: {file_data['content']}") +print(f"Size: {file_data['size']} bytes") +print(f"Type: {file_data['mediaType']}") +``` + +```javascript JavaScript +const axios = require('axios'); + +async function readFile(path) { + const url = "http://localhost:9990/computer-use"; + + const data = { + action: "read_file", + path: path + }; + + const response = await axios.post(url, data); + const result = response.data; + + if (result.success) { + // Decode the base64 content + const content = Buffer.from(result.data, 'base64').toString('utf-8'); + return { + content: content, + name: result.name, + size: result.size, + mediaType: result.mediaType + }; + } else { + throw new Error(result.message); + } +} + +// Read a file from desktop +readFile("report.txt") + .then(fileData => { + console.log(`Content: ${fileData.content}`); + console.log(`Size: ${fileData.size} bytes`); + console.log(`Type: ${fileData.mediaType}`); + }) + .catch(error => console.error("Error reading file:", error)); +``` + + +## 自动化方案 + +### 浏览器自动化 + +此示例演示了如何自动化浏览器交互： + +```python +import requests +import time + +def control_computer(action, **params): + url = "http://localhost:9990/computer-use" + data = {"action": action, **params} + response = requests.post(url, json=data) + return response.json() + +def automate_browser(): + # Open browser (assuming browser icon is at position x=100, y=960) + control_computer("move_mouse", coordinates={"x": 100, "y": 960}) + control_computer("click_mouse", button="left") + time.sleep(3) # Wait for browser to open + + # Type URL + control_computer("type_text", text="https://example.com") + control_computer("press_keys", key="enter") + time.sleep(2) # Wait for page to load + + # Take screenshot of the loaded page + screenshot = control_computer("screenshot") + + # Click on a link (coordinates would need to be adjusted for your target) + control_computer("move_mouse", coordinates={"x": 300, "y": 400}) + control_computer("click_mouse", button="left") + time.sleep(2) + + # Scroll down + control_computer("scroll", direction="down", scrollCount=5) + +automate_browser() +``` + +### 表单填写自动化 + +此示例展示了如何自动化填写 Web 应用程序中的表单： + +```javascript +const axios = require("axios"); + +async function controlComputer(action, params = {}) { + const url = "http://localhost:9990/computer-use"; + const data = { action, ...params }; + const response = await axios.post(url, data); + return response.data; +} + +async function fillForm() { + // Click first input field + await controlComputer("move_mouse", { coordinates: { x: 400, y: 300 } }); + await controlComputer("click_mouse", { button: "left" }); + + // Type name + await controlComputer("type_text", { text: "John Doe" }); + + // Tab to next field + await controlComputer("press_keys", { key: "tab" }); + + // Type email + await controlComputer("type_text", { text: "john@example.com" }); + + // Tab to next field + await controlComputer("press_keys", { key: "tab" }); + + // Type message + await controlComputer("type_text", { + text: "This is an automated message sent using Bytebot's Computer Use API", + delay: 30, + }); + + // Tab to submit button + await controlComputer("press_keys", { key: "tab" }); + + // Press Enter to submit + await controlComputer("press_keys", { key: "enter" }); +} + +fillForm().catch(console.error); +``` + +## 与测试框架集成 + +计算机使用 API 可以与流行的测试框架集成： + +### Selenium 替代方案 + +Bytebot 可作为 Web 测试中 Selenium 的替代方案： + +```python +import requests +import time +import json + +class BytebotWebDriver: + def __init__(self, base_url="http://localhost:9990"): + self.base_url = base_url + + def control_computer(self, action, **params): + url = f"{self.base_url}/computer-use" + data = {"action": action, **params} + response = requests.post(url, json=data) + return response.json() + + def open_browser(self, browser_icon_coords): + self.control_computer("move_mouse", coordinates=browser_icon_coords) + self.control_computer("click_mouse", button="left") + time.sleep(3) # Wait for browser to open + + def navigate_to(self, url): + self.control_computer("type_text", text=url) + self.control_computer("press_keys", key="enter") + time.sleep(2) # Wait for page to load + + def click_element(self, coords): + self.control_computer("move_mouse", coordinates=coords) + self.control_computer("click_mouse", button="left") + + def type_text(self, text): + self.control_computer("type_text", text=text) + + def press_keys(self, key, modifiers=None): + params = {"key": key} + if modifiers: + params["modifiers"] = modifiers + self.control_computer("press_keys", **params) + + def take_screenshot(self): + return self.control_computer("screenshot") + +# Usage example +driver = BytebotWebDriver() +driver.open_browser({"x": 100, "y": 960}) +driver.navigate_to("https://example.com") +driver.click_element({"x": 300, "y": 400}) +driver.type_text("Hello Bytebot!") +``` \ No newline at end of file diff --git a/docs/zh/api-reference/computer-use/unified-endpoint.mdx b/docs/zh/api-reference/computer-use/unified-endpoint.mdx new file mode 100644 index 000000000..7542e105a --- /dev/null +++ b/docs/zh/api-reference/computer-use/unified-endpoint.mdx @@ -0,0 +1,547 @@ +--- +title: "统一计算机操作 API" +description: "通过单一端点控制桌面环境的所有方面" +--- + +## 概述 + +统一计算机操作API通过单一端点实现对Bytebot虚拟桌面环境所有方面的精细控制。它用一个统一的接口取代了多个特定端点，可处理各种计算机操作，如鼠标移动、点击、按键等。 + +## 端点 + +| 方法 | URL | 描述 | +| ------ | ---------------- | ----------------------------------------------- | +| POST | `/computer-use` | 在虚拟桌面中执行计算机操作 | + +## 请求格式 + +所有对统一端点的请求都遵循以下格式： + +```json +{ + "action": "action_name", + ...action-specific parameters +} +``` + +`action`参数决定要执行的操作，其余参数取决于具体的操作。 + +## 可用操作 + +### move_mouse + +将鼠标光标移动到特定位置。 + +**参数：** + +| 参数 | 类型 | 必需 | 描述 | +| --------------- | ------ | -------- | --------------------------------- | +| `coordinates` | Object | 是 | 要移动到的目标坐标 | +| `coordinates.x` | Number | 是 | X坐标 | +| `coordinates.y` | Number | 是 | Y坐标 | + +**示例:** + +```json +{ + "action": "move_mouse", + "coordinates": { + "x": 100, + "y": 200 + } +} +``` + +### trace_mouse + +沿坐标路径移动鼠标。 + +**参数：** + +| 参数 | 类型 | 必填 | 描述 | +| ------------ | ------ | -------- | ----------------------------------------------- | +| `path` | Array | 是 | 鼠标路径的坐标对象数组 | +| `path[].x` | Number | 是 | 路径中每个点的 X 坐标 | +| `path[].y` | Number | 是 | 路径中每个点的 Y 坐标 | +| `holdKeys` | Array | 否 | 沿路径移动时按住的键 | + +**示例:** + +```json +{ + "action": "trace_mouse", + "path": [ + { "x": 100, "y": 100 }, + { "x": 150, "y": 150 }, + { "x": 200, "y": 200 } + ], + "holdKeys": ["shift"] +} +``` + +### click_mouse + +在当前或指定位置执行鼠标点击。 + +**参数：** + +| 参数 | 类型 | 必填 | 描述 | +| --------------- | ------ | -------- | ----------------------------------------------------- | +| `coordinates` | Object | 否 | 要点击的坐标（省略时使用当前位置） | +| `coordinates.x` | Number | 是* | X 坐标 | +| `coordinates.y` | Number | 是* | Y 坐标 | +| `button` | String | 是 | 鼠标按钮：'left'、'right' 或 'middle' | +| `clickCount` | Number | 是 | 要执行的点击次数 | +| `holdKeys` | Array | 否 | 点击时按住的键（例如 ['ctrl', 'shift']） | + +**示例:** + +```json +{ + "action": "click_mouse", + "coordinates": { + "x": 150, + "y": 250 + }, + "button": "left", + "clickCount": 2 +} +``` + +### press_mouse + +在当前或指定位置按下或释放鼠标按钮。 + +**参数：** + +| 参数 | 类型 | 必填 | 描述 | +| --------------- | ------ | -------- | -------------------------------------------------------- | +| `coordinates` | Object | 否 | 按下/释放的坐标（省略时使用当前位置） | +| `coordinates.x` | Number | 是* | X 坐标 | +| `coordinates.y` | Number | 是* | Y 坐标 | +| `button` | String | 是 | 鼠标按钮：'left'、'right' 或 'middle' | +| `press` | String | 是 | 动作：'up' 或 'down' | + +**示例:** + +```json +{ + "action": "press_mouse", + "coordinates": { + "x": 150, + "y": 250 + }, + "button": "left", + "press": "down" +} +``` + +### drag_mouse + +点击并拖动鼠标从一个点到另一个点。 + +**参数：** + +| 参数 | 类型 | 必填 | 描述 | +| ------------ | ------ | -------- | --------------------------------------------- | +| `path` | Array | 是 | 拖动路径的坐标对象数组 | +| `path[].x` | Number | 是 | 路径中每个点的 X 坐标 | +| `path[].y` | Number | 是 | 路径中每个点的 Y 坐标 | +| `button` | String | 是 | 鼠标按钮：'left'、'right' 或 'middle' | +| `holdKeys` | Array | 否 | 拖动时按住的功能键 | + +**示例:** + +```json +{ + "action": "drag_mouse", + "path": [ + { "x": 100, "y": 100 }, + { "x": 200, "y": 200 } + ], + "button": "left" +} +``` + +### scroll + +向上、向下、向左或向右滚动。 + +**参数：** + +| 参数 | 类型 | 必填 | 描述 | +| --------------- | ------ | -------- | ------------------------------------------------ | +| `coordinates` | Object | 否 | 滚动坐标（省略时使用当前位置） | +| `coordinates.x` | Number | 是* | X 坐标 | +| `coordinates.y` | Number | 是* | Y 坐标 | +| `direction` | String | 是 | 滚动方向：'up', 'down', 'left', 'right' | +| `scrollCount` | Number | 是 | 滚动步数 | +| `holdKeys` | Array | 否 | 滚动时需按住的按键 | + +**示例:** + +```json +{ + "action": "scroll", + "direction": "down", + "scrollCount": 5 +} +``` + +### type_keys + +输入一系列键盘按键。 + +**参数：** + +| 参数 | 类型 | 必填 | 描述 | +| ------- | ------ | ---- | -------------------------------- | +| `keys` | Array | 是 | 按顺序输入的按键数组 | +| `delay` | Number | 否 | 按键之间的延迟时间（毫秒） | + +**示例:** + +```json +{ + "action": "type_keys", + "keys": ["a", "b", "c", "enter"], + "delay": 50 +} +``` + +### press_keys + +按下或释放键盘按键。 + +**参数：** + +| 参数 | 类型 | 是否必需 | 描述 | +| --------- | ------- | -------- | ------------------------------------------ | +| `keys` | 数组 | 是 | 要按下或释放的按键数组 | +| `press` | 字符串 | 是 | 动作: 'up' 或 'down' | + +**示例:** + +```json +{ + "action": "press_keys", + "keys": ["ctrl", "shift", "esc"], + "press": "down" +} +``` + +### type_text + +输入文本字符串，可设置延迟。 + +**参数：** + +| 参数 | 类型 | 是否必需 | 描述 | +| --------- | ------- | -------- | ----------------------------------------------------- | +| `text` | 字符串 | 是 | 要输入的文本 | +| `delay` | 数字 | 否 | 字符间的延迟时间（毫秒）（默认: 0） | + +**示例:** + +```json +{ + "action": "type_text", + "text": "Hello, Bytebot!", + "delay": 50 +} +``` + +### paste_text + +在当前光标位置粘贴文本。这对于标准键盘上没有的特殊字符特别有用。 + +**参数：** + +| 参数 | 类型 | 是否必需 | 描述 | +| --------- | ------- | -------- | ------------------------------------------------------------------------ | +| `text` | 字符串 | 是 | 要粘贴的文本，包括特殊字符和表情符号 | + +**示例:** + +```json +{ + "action": "paste_text", + "text": "Special characters: ©®™€¥£ émojis 🎉" +} +``` + +### wait + +等待指定时长。 + +**参数：** + +| 参数 | 类型 | 必填 | 描述 | +| ---------- | ------ | -------- | ----------------------------- | +| `duration` | 数值 | 是 | 等待时长（毫秒） | + +**示例:** + +```json +{ + "action": "wait", + "duration": 2000 +} +``` + +### screenshot + +捕获桌面截图。 + +**参数：** 无需参数 + +**示例:** + +```json +{ + "action": "screenshot" +} +``` + +### cursor_position + +获取鼠标光标的当前位置。 + +**参数：** 无需参数 + +**示例:** + +```json +{ + "action": "cursor_position" +} +``` + +### application + +在不同应用程序之间切换或导航至桌面/目录。 + +**参数：** + +| 参数 | 类型 | 必填 | 描述 | +| ------------- | ------ | -------- | ------------------------------------------------------------------------ | +| `application` | 字符串 | 是 | 要切换到的应用程序。请参阅下方可用选项。 | + +**可用应用程序：** + +- `firefox` - Mozilla Firefox 网页浏览器 +- `1password` - 密码管理器 +- `thunderbird` - 电子邮件客户端 +- `vscode` - Visual Studio Code 编辑器 +- `terminal` - 终端/控制台应用程序 +- `desktop` - 切换至桌面 +- `directory` - 文件管理器/目录浏览器 + +**示例:** + +```json +{ + "action": "application", + "application": "firefox" +} +``` + +### write_file + +将文件写入桌面环境文件系统。 + +**参数：** + +| 参数 | 类型 | 是否必需 | 描述 | +| --------- | ------ | -------- | -------------------------------------------------------------- | +| `path` | String | 是 | 文件路径（绝对路径或相对于 /home/user/Desktop 的相对路径） | +| `data` | String | 是 | Base64 编码的文件内容 | + +**示例:** + +```json +{ + "action": "write_file", + "path": "/home/user/documents/example.txt", + "data": "SGVsbG8gV29ybGQh" +} +``` + +### read_file + +从桌面环境文件系统中读取文件。 + +**参数：** + +| 参数 | 类型 | 是否必需 | 描述 | +| --------- | ------ | -------- | -------------------------------------------------------------- | +| `path` | String | 是 | 文件路径（绝对路径或相对于 /home/user/Desktop 的相对路径） | + +**示例:** + +```json +{ + "action": "read_file", + "path": "/home/user/documents/example.txt" +} +``` + +## 响应格式 + +响应格式根据执行的操作而有所不同。 + +### 标准响应 + +大多数操作返回一个简单的成功响应： + +```json +{ + "success": true +} +``` + +### 截图响应 + +```json +{ + "success": true, + "data": { + "image": "base64_encoded_image_data" + } +} +``` + +### 光标位置响应 + +```json +{ + "success": true, + "data": { + "x": 123, + "y": 456 + } +} +``` + +### 写入文件响应 + +```json +{ + "success": true, + "message": "File written successfully to: /home/user/documents/example.txt" +} +``` + +### 读取文件响应 + +```json +{ + "success": true, + "data": "SGVsbG8gV29ybGQh", + "name": "example.txt", + "size": 12, + "mediaType": "text/plain" +} +``` + +### 错误响应 + +```json +{ + "success": false, + "error": "Error message" +} +``` + +## 代码示例 + +### JavaScript/Node.js 示例 + +```javascript +const axios = require('axios'); + +const bytebot = { + baseUrl: 'http://localhost:9990/computer-use/computer', + + async action(params) { + try { + const response = await axios.post(this.baseUrl, params); + return response.data; + } catch (error) { + console.error('Error:', error.response?.data || error.message); + throw error; + } + }, + + // Convenience methods + async moveMouse(x, y) { + return this.action({ + action: 'move_mouse', + coordinates: { x, y } + }); + }, + + async clickMouse(x, y, button = 'left') { + return this.action({ + action: 'click_mouse', + coordinates: { x, y }, + button + }); + }, + + async typeText(text) { + return this.action({ + action: 'type_text', + text + }); + }, + + async pasteText(text) { + return this.action({ + action: 'paste_text', + text + }); + }, + + async switchApplication(application) { + return this.action({ + action: 'application', + application + }); + }, + + async screenshot() { + return this.action({ action: 'screenshot' }); + } +}; + +// Example usage: +async function example() { + // Switch to Firefox + await bytebot.switchApplication('firefox'); + + // Navigate to a website + await bytebot.moveMouse(100, 35); + await bytebot.clickMouse(100, 35); + await bytebot.typeText('https://example.com'); + await bytebot.action({ + action: 'press_keys', + keys: ['enter'], + press: 'down' + }); + + // Wait for page to load + await bytebot.action({ + action: 'wait', + duration: 2000 + }); + + // Paste some special characters + await bytebot.pasteText('© 2025 Example Corp™ - €100'); + + // Take a screenshot + const result = await bytebot.screenshot(); + console.log('Screenshot taken!'); +} + +example().catch(console.error); diff --git a/docs/zh/api-reference/endpoint/create.mdx b/docs/zh/api-reference/endpoint/create.mdx new file mode 100644 index 000000000..0a970f299 --- /dev/null +++ b/docs/zh/api-reference/endpoint/create.mdx @@ -0,0 +1,4 @@ +--- +title: '创建植物' +openapi: 'POST /plants' +--- \ No newline at end of file diff --git a/docs/zh/api-reference/endpoint/delete.mdx b/docs/zh/api-reference/endpoint/delete.mdx new file mode 100644 index 000000000..07912237c --- /dev/null +++ b/docs/zh/api-reference/endpoint/delete.mdx @@ -0,0 +1,4 @@ +--- +title: '删除植物' +openapi: 'DELETE /plants/{id}' +--- \ No newline at end of file diff --git a/docs/zh/api-reference/endpoint/get.mdx b/docs/zh/api-reference/endpoint/get.mdx new file mode 100644 index 000000000..fb22fe878 --- /dev/null +++ b/docs/zh/api-reference/endpoint/get.mdx @@ -0,0 +1,4 @@ +--- +title: '获取植物数据' +openapi: 'GET /plants' +--- \ No newline at end of file diff --git a/docs/zh/api-reference/endpoint/webhook.mdx b/docs/zh/api-reference/endpoint/webhook.mdx new file mode 100644 index 000000000..8ff705747 --- /dev/null +++ b/docs/zh/api-reference/endpoint/webhook.mdx @@ -0,0 +1,4 @@ +--- +title: '新建植物' +openapi: 'WEBHOOK /plant/webhook' +--- \ No newline at end of file diff --git a/docs/zh/api-reference/introduction.mdx b/docs/zh/api-reference/introduction.mdx new file mode 100644 index 000000000..6788d3b0a --- /dev/null +++ b/docs/zh/api-reference/introduction.mdx @@ -0,0 +1,158 @@ +--- +title: "API 参考" +description: "Bytebot API 端点的概述，用于程序化控制" +--- + +# Bytebot API 概述 + +Bytebot 提供两个主要的 API 用于程序化控制： + +## 1. 代理 API（任务管理） + +代理 API 运行在端口 9991 上，提供高级任务管理： + + + + 以编程方式创建、管理和监控 AI 驱动的任务 + + + 用于自定义 UI 的 WebSocket 连接和实时更新 + + + +### 代理 API 基础 URL + +``` +http://localhost:9991 +``` + +### 任务创建示例 + +```bash +curl -X POST http://localhost:9991/tasks \ + -H "Content-Type: application/json" \ + -d '{ + "description": "Download invoices from webmail and organize by date", + "priority": "HIGH" + }' +``` + +## 2. 桌面 API（直接控制） + +桌面 API 运行在端口 9990 上，提供低级桌面控制： + + + + 直接控制鼠标、键盘和屏幕捕获 + + + 常见自动化场景的代码示例 + + + +### 桌面 API 基础 URL + +``` +http://localhost:9990 +``` + +### 桌面控制示例 + +```bash +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "screenshot"}' +``` + +### MCP 支持 + +桌面 API 还公开了一个 MCP（模型上下文协议）端点： + +``` +http://localhost:9990/mcp +``` + +连接您的 MCP 客户端以通过 SSE 访问桌面控制工具。 + +## 身份验证 + +- **本地访问**：默认无需认证 +- **远程访问**：根据安全需求配置认证 +- **生产环境**：实施 API 密钥、OAuth 或其他认证方法 + +## 响应格式 + +### Agent API 响应 + +```json +{ + "id": "task-123", + "status": "RUNNING", + "description": "Your task description", + "messages": [...], + "createdAt": "2024-01-01T00:00:00Z" +} +``` + +### Desktop API 响应 + +```json +{ + "success": true, + "data": { ... }, // Response data specific to the action + "error": null // Error message if success is false +} +``` + +## 错误处理 + +两个 API 均使用标准 HTTP 状态码： + +| 状态码 | 描述 | +| ----------- | ------------------------------------ | +| 200 | 成功 | +| 201 | 已创建（新资源） | +| 400 | 错误请求 - 参数无效 | +| 401 | 未授权 - 认证失败 | +| 404 | 未找到 - 资源不存在 | +| 500 | 内部服务器错误 | + +## 速率限制 + +- **Agent API**：无硬性限制，但需考虑任务队列容量 +- **Desktop API**：无速率限制，但快速操作可能影响桌面性能 + +## 最佳实践 + +1. **使用 Agent API 进行高级自动化** - 让 AI 处理复杂任务 +2. **使用 Desktop API 实现精确控制** - 当需要精确操作时 +3. **组合使用两个 API** - 通过 Agent API 创建任务，通过 Desktop API 监控 +4. **优雅处理错误** - 为瞬时故障实施重试逻辑 +5. **监控资源使用情况** - 两个 API 都可能消耗大量资源 + +## 后续步骤 + + + + 让您的 API 运行起来 + + + 查看 API 的实际应用 + + \ No newline at end of file diff --git a/docs/zh/core-concepts/agent-system.mdx b/docs/zh/core-concepts/agent-system.mdx new file mode 100644 index 000000000..d3091d014 --- /dev/null +++ b/docs/zh/core-concepts/agent-system.mdx @@ -0,0 +1,281 @@ +--- +title: "智能代理系统" +description: "为您自托管的桌面自动化提供动力的AI大脑" +--- + +## 概述 + +Bytebot智能代理系统将简单的桌面容器转变为智能自主的计算机用户。通过将Claude AI与结构化任务管理相结合，它能理解自然语言请求并像人类一样执行复杂的工作流程。 + +Bytebot Agent Architecture + +## AI代理工作原理 + +### 大脑：多模型AI集成 + +Bytebot的核心是一个灵活的AI集成系统，支持多种模型。选择最适合您需求的AI： + +**Anthropic Claude**（默认）： + +- 最适合复杂推理和视觉理解 +- 擅长遵循详细指令 +- 在桌面自动化任务上表现卓越 + +**OpenAI GPT模型**： + +- 快速可靠，适用于通用自动化 +- 强大的代码理解和生成能力 +- 对常规任务具有成本效益 + +**Google Gemini**： + +- 高效处理大批量任务 +- 速度与能力的良好平衡 +- 出色的多语言支持 + +使用任何模型的代理都能： + +1. **理解上下文**：结合完整对话历史处理您的自然语言请求 +2. **规划行动**：将复杂任务分解为可执行的计算机操作 +3. **实时适应**：根据屏幕显示内容调整执行方式 +4. **从反馈中学习**：通过对话改进任务执行效果 + +### 对话流程 + + + + "为我的SaaS产品研究竞争对手并创建对比表格" + + + AI模型理解请求并规划：打开浏览器→搜索→访问网站→提取数据→创建文档 + + + 智能体控制桌面：点击、输入、截图、读取内容 + + + 实时状态更新并在需要时请求澄清 + + + 完成任务并提供输出（文件、截图、摘要） + + + +## 任务管理系统 + +### 任务生命周期 + +任务按照结构化生命周期流转： + +```mermaid +graph LR + A[Created] --> B[Queued] + B --> C[Running] + C --> D[Needs Help] + C --> E[Completed] + C --> F[Failed] + D --> C +``` + +### 任务属性 + +每个任务包含： + +- **描述**：需要完成的内容 +- **优先级**：紧急、高、中或低 +- **状态**：生命周期中的当前状态 +- **类型**：立即执行或计划执行 +- **历史记录**：所有已采取的消息和操作 + +### 智能任务处理 + +智能体智能处理任务： + +1. **优先级队列**：紧急任务优先运行 +2. **错误恢复**：自动重试失败的操作 +3. **人工介入**：遇到困难时请求帮助 +4. **上下文保持**：跨会话维护对话历史 + +## 实际能力 + +### 智能体能够执行的操作 + + + + - 浏览网站 + - 填写表单 + - 提取数据 + - 下载文件 + - 监控变化 + + + - 创建文档 + - 编辑电子表格 + - 生成报告 + - 整理文件 + - 转换格式 + + + - 通过浏览器访问网页邮件 + - 读取和提取信息 + - 填写联系表单 + - 导航通信门户 + - 处理验证流程 + + + - 从PDF中提取数据 + - 处理CSV文件 + - 创建可视化图表 + - 生成摘要 + - 转换数据格式 + + + +## 技术架构 + +### 核心组件 + +1. **NestJS Agent Service** + - 集成多个AI提供商API（Anthropic、OpenAI、Google） + - 处理WebSocket连接 + - 与桌面API协调工作 + +2. **Message System** + - 结构化对话格式 + - 支持文本和图像 + - 维护完整上下文 + - 实现丰富交互 + +3. **Database Schema** + ```sql + Tasks: id, description, status, priority, timestamps + Messages: id, task_id, role, content, timestamps + Summaries: id, task_id, content, parent_id + ``` + +4. **Computer Action Bridge** + - 将AI决策转换为桌面操作 + - 处理屏幕截图和反馈 + - 管理操作时机 + - 提供错误处理 + +### API 端点 + +程序化控制的关键端点： + +```typescript +// Create a new task +POST /tasks +{ + "description": "Your task description", + "priority": "HIGH", + "type": "IMMEDIATE" +} + +// Get task status +GET /tasks/:id + +// Send a message +POST /tasks/:id/messages +{ + "content": "Additional instructions" +} + +// Get task history +GET /tasks/:id/messages +``` + +## 聊天界面功能 + +网页界面提供： + +### 实时交互 + +- 与AI代理实时聊天 +- 即时状态更新 +- 进度指示器 +- 错误通知 + +### 视觉反馈 + +- 嵌入式桌面查看器 +- 截图历史记录 +- 操作回放 +- 任务时间线 + +### 任务管理 + +- 创建和优先排序任务 +- 查看活跃和已完成任务 +- 导出对话日志 +- 管理任务队列 + +## 安全与隐私 + +### 数据隔离 + +- 所有处理都在您的基础设施中进行 +- 不向外部服务发送数据（除您选择的AI提供商API外） +- 对话本地存储 +- 完整的审计追踪 + +### 访问控制 + +- 可配置的身份验证 +- API密钥管理 +- 网络隔离选项 + +## 扩展代理功能 + +### 集成点 + +- 通过Agent API进行外部API调用 +- 为专业工作流程定制AI提示词 +- 支持MCP协议实现工具集成 + +### 最佳实践 + +1. **明确指令**：具体说明期望结果 +2. **分解复杂任务**：使用多个小型任务以获得更好效果 +3. **提供上下文**：包含相关文件或URL +4. **监控进度**：通过桌面视图获取实时反馈 +5. **审查结果**：验证输出是否符合要求 + +## 故障排除 + + + + - 检查 AI 供应商 API 密钥是否有效 + - 确认代理服务正在运行 + - 查看日志中的错误信息 + - 确保供应商处有足够的 API 额度/配额 + + + + - 监控系统资源 + - 检查网络延迟 + - 降低截图频率 + - 针对所选模型优化 AI 提示 + - 考虑切换到更快的模型（例如 Gemini Flash） + + + +## 后续步骤 + + + + 让您的代理运行起来 + + + 与您的应用集成 + + + 了解可实现的功能 + + + 优化您的工作流程 + + \ No newline at end of file diff --git a/docs/zh/core-concepts/architecture.mdx b/docs/zh/core-concepts/architecture.mdx new file mode 100644 index 000000000..464f34f54 --- /dev/null +++ b/docs/zh/core-concepts/architecture.mdx @@ -0,0 +1,239 @@ +--- +title: "架构" +description: "Bytebot桌面代理的工作原理详解" +--- + +## 概述 + +Bytebot是一个采用模块化架构构建的自托管AI桌面代理。它结合了Linux桌面环境和人工智能，创建了一个能够通过自然语言指令执行任务的自主计算机用户。 + +Bytebot Architecture Diagram + +## 系统架构 + +系统由四个主要组件协同工作： + +### 1. Bytebot桌面容器 + +系统的基础 - 提供虚拟Linux桌面环境： + +- **Ubuntu 22.04 LTS** 基础系统，确保稳定性和兼容性 +- **XFCE4桌面** 提供轻量级、响应迅速的UI界面 +- **bytebotd守护进程** - 基于nutjs构建的自动化服务，执行计算机操作 +- **预装应用程序**：Firefox ESR、Thunderbird、文本编辑器和开发工具 +- **noVNC** 用于远程桌面访问 + +**核心特性:** + +- 与主机系统完全隔离运行 +- 跨不同平台保持环境一致性 +- 可安装额外软件进行自定义 +- 通过端口9990的REST API访问 +- MCP SSE端点位于 `/mcp` +- 使用 `@bytebot/shared` 包的共享类型 + +### 2. AI代理服务 + +系统的大脑 - 使用LLM编排任务： + +- **NestJS Framework** 用于构建健壮、可扩展的后端 +- **LLM Integration** 支持 Anthropic Claude、OpenAI GPT 和 Google Gemini 模型 +- **WebSocket Support** 提供实时更新 +- **Computer Use API Client** 用于控制桌面 +- **Prisma ORM** 用于数据库操作 +- **计算机操作工具定义**（鼠标、键盘、截图） + +**职责：** + +- 解析自然语言请求 +- 规划计算机操作序列 +- 管理任务状态和进度 +- 处理错误和重试 +- 通过 WebSocket 提供实时任务更新 + +### 3. Web 任务界面 + +与 AI 代理交互的用户界面： + +- **Next.js 15 Application** 配合 TypeScript 确保类型安全 +- **嵌入式 VNC Viewer** 用于观看桌面操作 +- **任务管理** UI 带有状态徽章 +- **WebSocket Connections** 提供实时更新 +- **可复用组件** 确保一致的 UI +- **API 工具** 简化服务器通信 + +**功能特性:** + +- 任务创建和管理界面 +- 桌面选项卡用于直接手动控制 +- 带接管模式的实时桌面查看器 +- 任务历史和状态跟踪 +- 响应式设计适配所有设备 + +### 4. PostgreSQL 数据库 + +代理系统的持久化存储： + +- **Tasks Table**：存储任务详情、状态和元数据 +- **Messages Table**：存储 AI 对话历史 +- **Prisma ORM** 用于类型安全的数据库访问 + +## 数据流 + +### 任务执行流程 + + + + 用户通过聊天界面以自然语言描述任务 + + + Agent 服务创建任务记录并将其添加到处理队列 + + + LLM 分析任务并生成计算机操作计划 + + + Agent 通过 REST API 或 MCP 将计算机操作发送至 bytebotd + + + bytebotd 在桌面上执行操作（鼠标、键盘、截图） + + + Agent 接收结果，更新任务状态，并继续或完成任务 + + + 结果和状态更新实时发送回用户 + + + +### 通信协议 + +```mermaid +graph LR + A[Tasks UI] -->|WebSocket| B[Agent Service] + A -->|HTTP Proxy| C[Desktop VNC] + B -->|REST/MCP| D[Desktop API] + B -->|SQL| E[PostgreSQL] + B -->|HTTPS| F[LLM Provider] + D -->|IPC| G[bytebotd] +``` + +## 安全架构 + +### 隔离层 + +1. **容器隔离** + - 每个桌面运行在独立的 Docker 容器中 + - 默认无法访问主机文件系统 + - 通过显式端口映射实现网络隔离 + +2. **进程隔离** + - bytebotd 以非 root 用户身份运行 + - 不同服务使用独立进程 + - 通过 Docker 强制执行资源限制 + +3. **网络安全** + - 默认仅允许本地主机访问服务 + - 可配置身份验证 + - 外部连接使用 HTTPS/WSS + +### API 安全 + +- **Desktop API**: 默认无需认证（仅限 localhost）。支持 REST 和 MCP。 +- **Agent API**: 可通过 API 密钥进行安全保护 +- **Database**: 密码保护，不对外暴露 + + + 默认配置适用于开发环境。生产环境需： + - 对所有 API 启用身份验证 + - 所有连接使用 HTTPS/WSS + - 实施网络策略 + - 定期轮换凭据 + + +## 部署模式 + +### 单用户（开发环境） + +```yaml +Services: All on one machine +Scale: 1 instance each +Use Case: Personal automation, development +Resources: 4GB RAM, 2 CPU cores +``` + +### 生产环境部署 + +```yaml +Services: All services on dedicated hardware +Scale: Single instance (1 agent, 1 desktop) +Use Case: Business automation +Resources: 8GB+ RAM, 4+ CPU cores +``` + +### 企业级部署 + +```yaml +Services: Kubernetes orchestration +Scale: Single instance with high availability +Use Case: Organization-wide automation +Resources: Dedicated nodes +``` + +## 扩展点 + +### 自定义工具 + +向桌面添加专用软件： + +```dockerfile +FROM bytebot/desktop:latest +RUN apt-get update && apt-get install -y \ + your-custom-tools +``` + +### AI 集成 + +扩展代理能力： + +- 为 LLM 定制工具 +- 附加 AI 模型 +- 专用提示词 +- 领域特定知识 + +## 性能注意事项 + +### 资源使用 + +- **桌面容器**: 空闲时约 1GB 内存，活跃时 2GB+ +- **代理服务**: 约 256MB 内存 +- **UI 服务**: 约 128MB 内存 +- **数据库**: 约 256MB 内存 + +### 优化建议 + +1. 为容器分配充足资源 +2. 限制并发任务以防过载 +3. 定期监控资源使用情况 +4. 使用 LiteLLM 代理实现供应商灵活性 + +## 后续步骤 + + + + 了解AI智能体功能 + + + 探索虚拟桌面环境 + + + 与您的应用程序集成 + + + 部署您自己的实例 + + \ No newline at end of file diff --git a/docs/zh/core-concepts/desktop-environment.mdx b/docs/zh/core-concepts/desktop-environment.mdx new file mode 100644 index 000000000..0d8a21700 --- /dev/null +++ b/docs/zh/core-concepts/desktop-environment.mdx @@ -0,0 +1,277 @@ +--- +title: "桌面环境" +description: "Bytebot执行任务的虚拟Linux桌面环境" +--- + +## 概述 + +Bytebot桌面环境（也称为Bytebot Core）是一个运行在Docker容器中的完整Linux桌面。这是Bytebot执行工作的地方——点击按钮、输入文本、浏览网站以及使用应用程序，就像您亲自操作一样。 + +Bytebot Desktop Environment + +## 为何选择虚拟桌面？ + +### 完全隔离 + +- **主机零风险**：所有操作都在容器内进行 +- **沙盒环境**：桌面无法访问您的主机系统 +- **轻松重置**：几秒钟内即可销毁并重新创建 +- **纯净工作区**：每次重启都提供全新的环境 + +### 随处一致 + +- **平台无关**：在Mac、Windows或Linux上拥有相同的环境 +- **可重现性**：每次设置都完全一致 +- **版本控制**：可固定特定版本以确保稳定性 +- **无依赖项**：所有内容都包含在容器中 + +### 专为自动化打造 + +- **可预测的UI**：一致的元素定位 +- **纯净环境**：无弹窗或干扰 +- **自动化就绪**：针对程序化控制进行优化 +- **快速启动**：几秒钟内桌面即可就绪 + +## 技术栈 + +### 基础系统 + +- **Ubuntu 22.04 LTS**：稳定、得到良好支持的Linux发行版 +- **XFCE4桌面**：轻量级、响应迅速的桌面环境 +- **X11显示服务器**：标准Linux图形系统 +- **supervisord**：服务管理 + +### 预装软件 + + + + - Firefox ESR（扩展支持版本） + - 预配置用于自动化 + - 纯净配置文件无干扰 + + + - 文本编辑器 + - 办公工具 + - PDF 查看器 + - 文件管理器 + + + - Thunderbird 邮件客户端 + - 终端模拟器 + + + - 1Password 密码管理器 + - Visual Studio Code (VSCode) + - Git 版本控制 + - Python 3 环境 + + + +### 核心服务 + +1. **bytebotd 守护进程** + - 运行在端口 9990 + - 处理所有自动化请求 + - 基于 nutjs 框架构建 + - 提供 REST API + +2. **noVNC Web 客户端** + - 基于浏览器的桌面访问 + - 无需安装客户端 + - 包含 WebSocket 代理 + +3. **Supervisor** + - 进程管理 + - 服务监控 + - 自动重启 + - 日志管理 + +## 桌面功能 + +### 显示配置 + +```bash +# Resolution +1920x1080 @ 24-bit color +``` + +### 用户环境 + +- **用户名**: `user` +- **主目录**: `/home/user` +- **Sudo 权限**: 是（无密码） +- **桌面会话**: 启用自动登录 + +### 文件系统 + +``` +/home/user/ +├── Desktop/ # Desktop shortcuts +├── Documents/ # User documents +├── Downloads/ # Browser downloads +├── .config/ # Application configs +└── .local/ # User data +``` + +## 访问桌面 + +### 网页浏览器（推荐） + +导航至 `http://localhost:9990/vnc` 即可立即访问： + +- 无需安装任何软件 +- 可在任何带有浏览器的设备上运行 +- 支持触控设备 +- 剪贴板共享功能 + +### MCP 控制 + +核心容器还暴露了一个 [MCP](https://github.com/rekog-labs/MCP-Nest) 端点。 +将您的 MCP 客户端连接到 `http://localhost:9990/mcp`，即可通过 SSE 调用这些工具。 + +```json +{ + "mcpServers": { + "bytebot": { + "command": "npx", + "args": [ + "mcp-remote", + "http://127.0.0.1:9990/mcp", + "--transport", + "http-first" + ] + } + } +} +``` + +### 直接 API 控制 + +自动化场景下的最高效选择： + +```bash +# Take a screenshot +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "screenshot"}' + +# Move mouse +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "move_mouse", "coordinate": {"x": 500, "y": 300}}' +``` + +## 自定义配置 + +### 添加软件 + +创建一个自定义的 Dockerfile： + +```dockerfile +FROM ghcr.io/bytebot-ai/bytebot-desktop:edge + +# Install additional packages +RUN apt-get update && apt-get install -y \ + slack-desktop \ + zoom \ + your-custom-app + +# Copy configuration files +COPY configs/ /home/user/.config/ +``` + +## 性能优化 + +### 资源分配 + +```yaml +# Recommended settings +deploy: + resources: + limits: + cpus: '2' + memory: 4G + reservations: + cpus: '1' + memory: 2G +``` + +## 安全加固 + + + 默认配置优先考虑易用性。对于生产环境，请应用以下安全措施： + + +### 基本安全步骤 + +1. **修改默认密码** + ```bash + # 设置用户密码 + passwd bytebot + ``` + +2. **限制网络访问** + ```yaml + # 白名单特定域名 + environment: + - ALLOWED_DOMAINS=company.com,trusted-site.com + + # 或仅限制在本地网络访问 + ports: + - "10.0.0.0/8:9990:9990" + ``` + +## 故障排除 + + + + 检查日志： + ```bash + docker logs bytebot-desktop + ``` + 常见问题： + - 内存不足 + - 端口冲突 + - 显示服务器错误 + + + + 监控资源： + ```bash + docker stats bytebot-desktop + ``` + 解决方案： + - 增加内存分配 + - 检查磁盘空间 + - 更新容器镜像 + + + +## 最佳实践 + +1. **定期更新**：保持基础镜像更新以获取安全补丁 +2. **持久化存储**：为重要数据挂载卷 +3. **备份配置**：将自定义设置保存在容器外部 +4. **监控资源**：跟踪 CPU/内存使用情况 +5. **清理临时文件**：定期清理以提升性能 + +## 后续步骤 + + + + 部署您的第一个智能体 + + + 通过编程方式控制桌面 + + + 添加 AI 功能 + + + 设置身份验证 + + \ No newline at end of file diff --git a/docs/zh/core-concepts/rpa-comparison.mdx b/docs/zh/core-concepts/rpa-comparison.mdx new file mode 100644 index 000000000..f14f40157 --- /dev/null +++ b/docs/zh/core-concepts/rpa-comparison.mdx @@ -0,0 +1,285 @@ +--- +title: "Bytebot 与传统 RPA 对比" +description: "Bytebot 如何超越传统 RPA 工具，彻底变革企业自动化" +--- + +# 新一代企业自动化 + +Bytebot 代表了企业在流程自动化方法上的根本性转变。虽然像 UiPath、Automation Anywhere 和 Blue Prism 这样的传统 RPA 工具需要大量的脚本编写和脆弱的工作流程，但 Bytebot 利用人工智能来像人类一样理解和执行任务。 + +## 传统 RPA 的局限性 + + + + 当 UI 元素即使发生微小变化时，传统 RPA 就会失效 + + + 需要专门的开发人员和漫长的实施周期 + + + 随着应用程序的发展，需要不断更新 + + + 无法处理意外情况或变化 + + + +## Bytebot 的不同之处 + +### 视觉智能 vs 元素映射 + +**传统 RPA:** + +```xml + + + + + + +``` + +**Bytebot:** + +``` +"Click the blue Submit button at the bottom of the form" +``` + +Bytebot 像人类一样通过视觉理解界面。它不依赖每次更新都会失效的脆弱技术定位器。 + +### 自然语言 vs 复杂脚本 + +**传统 RPA 工作流程:** + +- 在 Studio 中设计 +- 映射每个元素 +- 编写错误处理脚本 +- 全面测试 +- 提心吊胆地部署 +- 出现问题及时修复（经常发生） + +**Bytebot 工作流程：** + +- 描述您的需求 +- Bytebot 智能解析 +- 智能处理错误 +- 自动适应变化 + +## 真实企业案例 + +### 金融服务自动化 + + + + ```csharp + // 500+ 行代码处理单个银行门户 + var loginPage = new LoginPageObject(); + loginPage.WaitForElement("username", 30); + loginPage.EnterText("username", credentials.User); + loginPage.EnterText("password", credentials.Pass); + + // 使用复杂条件逻辑处理双因素认证 + if (loginPage.Has2FAPrompt()) { + var method = loginPage.Get2FAMethod(); + switch(method) { + case "SMS": + // 再写 50 行代码 + case "Email": + // 再写 50 行代码 + case "Authenticator": + // 再写 50 行代码 + } + } + + // 使用精确选择器下载对账单 + navigation.ClickElement("xpath://div[@id='acct-menu']"); + navigation.ClickElement("xpath://a[contains(@href,'statements')]"); + // ... 继续数百行代码 + ``` + + + ``` + 任务: "登录大通银行门户，导航至对账单， + 下载账户尾号 4521 上个月的所有对账单， + 并将其保存至 Finance/BankStatements/Chase/" + + 仅此而已。Bytebot 自动处理所有事项——包括双因素认证。 + ``` + + + +### 多系统集成 + +一家金融科技公司需要自动化操作人员的工作，这些操作人员： + +1. 登录多个支持双因素认证的银行门户 +2. 下载交易文件 +3. 对这些文件运行专有脚本 +4. 将结果上传至内部系统 + +**传统RPA面临的挑战：** + +- 实施周期长达6个月 +- 每月因UI变更而失效 +- 需要专门的维护团队 +- 无法处理新银行接入而无需开发 +- 每家银行需单独处理复杂的双因素认证逻辑 + +**Bytebot解决方案：** + +- 一周内完成部署 +- 自动适应UI变更 +- 通过密码管理器自动处理双因素认证 +- 通过简单指令即可添加新银行 +- 完全无需人工干预 + +## 性能对比 + +| 指标 | 传统RPA | Bytebot | +|--------|----------------|---------| +| **实施时间** | 3-6个月 | 1-2周 | +| **开发人员要求** | RPA专家 | 任何技术用户 | +| **维护工作量** | 占用40%开发时间 | 近乎为零 | +| **处理UI变更** | 立即失效 | 自动适应 | +| **错误恢复** | 仅支持预设脚本 | 智能适配 | +| **新增流程** | 需要数周开发 | 几分钟描述即可 | +| **成本** | 每年10万美元以上 | 自托管于您的基础设施 | + +## 常见RPA迁移模式 + +### 1. 发票处理 + +**迁移前（UiPath）：** + +- 2000多行工作流XML代码 +- 供应商门户更新即导致系统中断 +- 要求严格的文件夹结构 +- 遇到意外弹窗即失败 + +**迁移后（Bytebot）：** + +- 单段描述 +- 处理门户变更 +- 需要时请求帮助 +- 智能处理变化 + +### 2. 合规报告 + +**之前（Automation Anywhere）：** + +- 复杂的机器人编排 +- 每个系统使用独立机器人 +- 固定调度 +- 缺乏灵活性 + +**之后（Bytebot）：** + +- 单一统一工作流 +- 自然语言指令 +- 动态适应 +- 需要时进行人工协作 + +### 3. 数据迁移 + +**之前（Blue Prism）：** + +- 庞大的流程定义 +- 需要精确字段映射 +- 数据变化时中断 +- 有限的错误处理 + +**之后（Bytebot）：** + +- 描述映射规则 +- 智能处理变化 +- 请求澄清 +- 包含可视化验证 + +## 与现有RPA集成 + +Bytebot可与现有RPA投资协同工作： + +```mermaid +graph LR + A[Legacy RPA] -->|Handles stable processes| B[Structured Systems] + C[Bytebot] -->|Handles complex/changing processes| D[Dynamic Systems] + C -->|Takes over when RPA fails| A + E[Human Operator] -->|Guides via takeover mode| C +``` + +## 企业架构 + +### 部署选项 + + + + 在您的数据中心部署，实现最高安全性和合规性 + + + 使用您的AWS/Azure/GCP基础设施，完全掌控 + + + 本地处理敏感数据，利用云端进行扩展 + + + 为机密环境提供完全隔离的部署方案 + + + +### 安全与合规 + +- **数据主权**: 所有处理都在您的基础设施上进行 +- **审计追踪**: 完整记录每个操作日志 +- **访问控制**: 与您的 IAM/SSO 集成 +- **合规性**: 支持 SOC2、HIPAA、PCI-DSS 兼容部署 + +## 迁移入门指南 + + + + 列出您当前的 RPA 工作流，特别是： + - 频繁中断的流程 + - 需要定期维护的流程 + - 处理多个系统的流程 + - 需要人工决策点的流程 + + + + 选择一个有问题的流程： + - 记录业务流程 + - 部署 Bytebot + - 自然描述任务 + - 比较结果 + + + + 随着信心增长： + - 迁移更复杂的流程 + - 淘汰脆弱的 RPA 机器人 + - 减少维护开销 + - 跨部门扩展 + + + +## 后续步骤 + + + + 在您的环境中部署 Bytebot + + + 查看源代码并参与贡献 + + + 加入我们的 Discord 获取支持 + + + 获取企业部署帮助 + + + + + **准备好超越传统 RPA 了吗？** Bytebot 为流程自动化带来类人智能，消除传统工具的脆弱性和复杂性，同时提供企业级的可靠性和安全性。 + \ No newline at end of file diff --git a/docs/zh/deployment/helm.mdx b/docs/zh/deployment/helm.mdx new file mode 100644 index 000000000..2558247a5 --- /dev/null +++ b/docs/zh/deployment/helm.mdx @@ -0,0 +1,290 @@ +--- +title: "Helm 部署" +description: "使用 Helm charts 在 Kubernetes 上部署 Bytebot" +--- + +# 使用 Helm 在 Kubernetes 上部署 Bytebot + +Helm 提供了一种简单的方法在 Kubernetes 集群上部署 Bytebot。 + +## 前置条件 + +- Kubernetes 集群 (1.19+) +- 已安装 Helm 3.x +- 已配置 kubectl +- 集群中可用内存 8GB+ + +## 快速开始 + + + + ```bash + git clone https://github.com/bytebot-ai/bytebot.git + cd bytebot + ``` + + + + 创建一个 `values.yaml` 文件，至少包含一个 API 密钥： + + ```yaml + bytebot-agent: + apiKeys: + anthropic: + value: "sk-ant-your-key-here" + # 可选：添加更多提供商 + # openai: + # value: "sk-your-key-here" + # gemini: + # value: "your-key-here" + ``` + + + + ```bash + helm install bytebot ./helm \ + --namespace bytebot \ + --create-namespace \ + -f values.yaml + ``` + + + + ```bash + # 端口转发以进行本地访问 + kubectl port-forward -n bytebot svc/bytebot-ui 9992:9992 + + # 通过 http://localhost:9992 访问 + ``` + + + +## 基本配置 + +### API 密钥 + +配置至少一个 AI 提供商： + +```yaml +bytebot-agent: + apiKeys: + anthropic: + value: "sk-ant-your-key-here" + openai: + value: "sk-your-key-here" + gemini: + value: "your-key-here" +``` + +### 资源限制（可选） + +根据您的需求调整资源： + +```yaml +# Desktop container (where automation runs) +desktop: + resources: + requests: + memory: "2Gi" + cpu: "1" + limits: + memory: "4Gi" + cpu: "2" + +# Agent (AI orchestration) +agent: + resources: + requests: + memory: "1Gi" + cpu: "500m" +``` + +### 外部访问（可选） + +启用基于域名的入口访问： + +```yaml +ui: + ingress: + enabled: true + hostname: bytebot.your-domain.com + tls: true +``` + +## 访问 Bytebot + +### 本地访问（推荐） + +```bash +kubectl port-forward -n bytebot svc/bytebot-ui 9992:9992 +``` + +访问地址：http://localhost:9992 + +### 外部访问 + +如果您配置了入口： + +- 访问地址：https://bytebot.your-domain.com + +## 验证部署 + +检查所有 Pod 是否正在运行： + +```bash +kubectl get pods -n bytebot +``` + +预期输出： + +``` +NAME READY STATUS RESTARTS AGE +bytebot-agent-xxxxx 1/1 Running 0 2m +bytebot-desktop-xxxxx 1/1 Running 0 2m +bytebot-postgresql-0 1/1 Running 0 2m +bytebot-ui-xxxxx 1/1 Running 0 2m +``` + +## 故障排除 + +### Pod 无法启动 + +检查 Pod 状态： + +```bash +kubectl describe pod -n bytebot +``` + +常见问题： + +- 内存/CPU 不足：使用 `kubectl top nodes` 检查节点资源 +- 缺少 API 密钥：验证您的 values.yaml 配置 + +### 连接问题 + +测试服务连通性： + +```bash +kubectl logs -n bytebot deployment/bytebot-agent +``` + +### 查看日志 + +```bash +# All logs +kubectl logs -n bytebot -l app=bytebot --tail=100 + +# Specific component +kubectl logs -n bytebot deployment/bytebot-agent +``` + +## 升级指南 + +```bash +# Update your values.yaml as needed, then: +helm upgrade bytebot ./helm -n bytebot -f values.yaml +``` + +## 卸载 + +```bash +# Remove Bytebot +helm uninstall bytebot -n bytebot + +# Clean up namespace +kubectl delete namespace bytebot +``` + +## 高级配置 + + + + 如果使用 Kubernetes 密钥管理（Vault、Sealed Secrets 等）： + + ```yaml + bytebot-agent: + apiKeys: + anthropic: + useExisting: true + secretName: "my-api-keys" + secretKey: "anthropic-key" + ``` + + 手动创建密钥： + ```bash + kubectl create secret generic my-api-keys \ + --namespace bytebot \ + --from-literal=anthropic-key="sk-ant-your-key" + ``` + + + + 对于集中式 LLM 管理，使用内置的 LiteLLM 代理： + + ```bash + helm install bytebot ./helm \ + -f values-proxy.yaml \ + --namespace bytebot \ + --create-namespace \ + --set bytebot-llm-proxy.env.ANTHROPIC_API_KEY="your-key" + ``` + + 这提供： + - 集中式 API 密钥管理 + - 请求路由和负载均衡 + - 速率限制和重试逻辑 + + + + 配置持久化存储： + + ```yaml + desktop: + persistence: + enabled: true + size: "20Gi" + storageClass: "fast-ssd" + + postgresql: + persistence: + size: "20Gi" + storageClass: "fast-ssd" + ``` + + + + ```yaml + # 网络策略 + networkPolicy: + enabled: true + + # Pod 安全 + podSecurityContext: + runAsNonRoot: true + runAsUser: 1000 + fsGroup: 1000 + + # 启用身份验证 + auth: + enabled: true + type: "basic" + username: "admin" + password: "changeme" # 生产环境中请使用密钥！ + ``` + + + +## 后续步骤 + + + + 将 Bytebot 与您的应用程序集成 + + + 使用任何 LLM 提供商与 Bytebot 配合 + + + + + **需要帮助？** 加入我们的 [Discord 社区](https://discord.com/invite/d9ewZkWPTP) 或查看我们的 [GitHub 讨论区](https://github.com/bytebot-ai/bytebot/discussions)。 + \ No newline at end of file diff --git a/docs/zh/deployment/litellm.mdx b/docs/zh/deployment/litellm.mdx new file mode 100644 index 000000000..e09bec764 --- /dev/null +++ b/docs/zh/deployment/litellm.mdx @@ -0,0 +1,510 @@ +--- +title: "LiteLLM 集成" +description: "通过 LiteLLM 代理在 Bytebot 中使用任何 LLM 提供商" +--- + +# 通过 LiteLLM 将任意 LLM 连接到 Bytebot + +LiteLLM 作为一个统一代理，让您可以在 Bytebot 中使用 100 多个 LLM 提供商——包括 Azure OpenAI、AWS Bedrock、Anthropic、Hugging Face、Ollama 等。本指南将向您展示如何将 LiteLLM 与 Bytebot 一起设置。 + +## 为何使用 LiteLLM？ + + + + 使用 Azure、AWS、GCP、Anthropic、OpenAI、Cohere 以及本地模型 + + + 在一个地方监控所有提供商的花费 + + + 在多个模型和提供商之间分发请求 + + + 当主模型不可用时自动故障转移 + + + +## 使用 Bytebot 内置的 LiteLLM 代理快速入门 + +Bytebot 包含一个预配置的 LiteLLM 代理服务，可轻松使用任何 LLM 提供商。以下是设置方法： + + + + 最简单的方法是使用启用代理的 Docker Compose 文件： + + ```bash + # 克隆 Bytebot + git clone https://github.com/bytebot-ai/bytebot.git + cd bytebot + + # 在 docker/.env 中设置您的 API 密钥 + cat > docker/.env << EOF + # 添加任意组合的这些密钥 + ANTHROPIC_API_KEY=sk-ant-your-key-here + OPENAI_API_KEY=sk-your-key-here + GEMINI_API_KEY=your-key-here + EOF + + # 使用 LiteLLM 代理启动 Bytebot + docker-compose -f docker/docker-compose.proxy.yml up -d + ``` + + 这会自动： + - 在端口 4000 上启动 `bytebot-llm-proxy` 服务 + - 通过 `BYTEBOT_LLM_PROXY_URL` 配置代理供代理使用 + - 使所有配置的模型都可通过代理使用 + + + + 要添加自定义模型或提供商，请编辑 LiteLLM 配置： + + ```yaml + # packages/bytebot-llm-proxy/litellm-config.yaml + model_list: + # 添加 Azure OpenAI + - model_name: azure-gpt-4o + litellm_params: + model: azure/gpt-4o-deployment + api_base: https://your-resource.openai.azure.com/ + api_key: os.environ/AZURE_API_KEY + api_version: "2024-02-15-preview" + + # 添加 AWS Bedrock + - model_name: claude-bedrock + litellm_params: + model: bedrock/anthropic.claude-3-5-sonnet + aws_region_name: us-east-1 + + # 通过 Ollama 添加本地模型 + - model_name: local-llama + litellm_params: + model: ollama/llama3:70b + api_base: http://host.docker.internal:11434 + ``` + + 然后重新构建： + ```bash + docker-compose -f docker/docker-compose.proxy.yml up -d --build + ``` + + + + Bytebot 代理会自动查询代理以获取可用模型： + + ```bash + # 通过 Bytebot API 检查可用模型 + curl http://localhost:9991/tasks/models + + # 或直接从 LiteLLM 代理获取 + curl http://localhost:4000/model/info + ``` + + UI 将在模型选择器中显示所有可用模型。 + + + +## 工作原理 + +### 架构 + +```mermaid +graph LR + A[Bytebot UI] -->|Select Model| B[Bytebot Agent] + B -->|BYTEBOT_LLM_PROXY_URL| C[LiteLLM Proxy :4000] + C -->|Route Request| D[Anthropic API] + C -->|Route Request| E[OpenAI API] + C -->|Route Request| F[Google API] + C -->|Route Request| G[Any Provider] +``` + +### 核心组件 + +1. **bytebot-llm-proxy 服务**: 在 Docker 中运行的 LiteLLM 实例，具备以下特性： + - 在 Bytebot 网络内的 4000 端口运行 + - 使用 `packages/bytebot-llm-proxy/litellm-config.yaml` 中的配置 + - 从环境变量继承 API 密钥 + +2. **智能体集成**: Bytebot 智能体： + - 检查 `BYTEBOT_LLM_PROXY_URL` 环境变量 + - 若已设置，则通过 `/model/info` 端点查询代理以获取可用模型 + - 将所有 LLM 请求通过代理路由 + +3. **预配置模型**: 开箱即用支持： + - Anthropic: Claude Opus 4, Claude Sonnet 4 + - OpenAI: GPT-4.1, GPT-4o + - Google: Gemini 2.5 Pro, Gemini 2.5 Flash + +## 供应商配置 + +### Azure OpenAI + +```yaml +model_list: + - model_name: azure-gpt-4o + litellm_params: + model: azure/gpt-4o-deployment-name + api_base: https://your-resource.openai.azure.com/ + api_key: your-azure-key + api_version: "2024-02-15-preview" + + - model_name: azure-gpt-4o-vision + litellm_params: + model: azure/gpt-4o-deployment-name + api_base: https://your-resource.openai.azure.com/ + api_key: your-azure-key + api_version: "2024-02-15-preview" + supports_vision: true +``` + +### AWS Bedrock + +```yaml +model_list: + - model_name: claude-bedrock + litellm_params: + model: bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0 + aws_region_name: us-east-1 + # Uses AWS credentials from environment + + - model_name: llama-bedrock + litellm_params: + model: bedrock/meta.llama3-70b-instruct-v1:0 + aws_region_name: us-east-1 +``` + +### Google Vertex AI + +```yaml +model_list: + - model_name: gemini-vertex + litellm_params: + model: vertex_ai/gemini-1.5-pro + vertex_project: your-gcp-project + vertex_location: us-central1 + # Uses GCP credentials from environment +``` + +### 本地模型 (Ollama) + +```yaml +model_list: + - model_name: local-llama + litellm_params: + model: ollama/llama3:70b + api_base: http://ollama:11434 + + - model_name: local-mixtral + litellm_params: + model: ollama/mixtral:8x7b + api_base: http://ollama:11434 +``` + +### Hugging Face + +```yaml +model_list: + - model_name: hf-llama + litellm_params: + model: huggingface/meta-llama/Llama-3-70b-chat-hf + api_key: hf_your_token +``` + +## 高级功能 + +### 负载均衡 + +在多个供应商之间分发请求： + +```yaml +model_list: + - model_name: gpt-4o + litellm_params: + model: gpt-4o + api_key: sk-openai-key + + - model_name: gpt-4o # Same name for load balancing + litellm_params: + model: azure/gpt-4o + api_base: https://azure.openai.azure.com/ + api_key: azure-key + +router_settings: + routing_strategy: "least-busy" # or "round-robin", "latency-based" +``` + +### 备用模型 + +配置自动故障转移： + +```yaml +model_list: + - model_name: primary-model + litellm_params: + model: claude-3-5-sonnet-20241022 + api_key: sk-ant-key + + - model_name: fallback-model + litellm_params: + model: gpt-4o + api_key: sk-openai-key + +router_settings: + model_group_alias: + "smart-model": ["primary-model", "fallback-model"] + +# Use "smart-model" in Bytebot config +``` + +### 成本控制 + +设置支出限制并跟踪使用情况： + +```yaml +general_settings: + master_key: sk-litellm-master + database_url: "postgresql://user:pass@localhost:5432/litellm" + + # Budget limits + max_budget: 100 # $100 monthly limit + budget_duration: "30d" + + # Per-model limits + model_max_budget: + gpt-4o: 50 + claude-3-5-sonnet: 50 + +litellm_settings: + callbacks: ["langfuse"] # For detailed tracking +``` + +### 速率限制 + +防止 API 过度使用： + +```yaml +model_list: + - model_name: rate-limited-gpt + litellm_params: + model: gpt-4o + api_key: sk-key + rpm: 100 # Requests per minute + tpm: 100000 # Tokens per minute +``` + +## 替代方案：外部 LiteLLM 代理 + +如果您希望单独运行 LiteLLM 或已有现有的 LiteLLM 部署： + +### 选项 1：修改 docker-compose.yml + +```yaml +# docker-compose.yml (without built-in proxy) +services: + bytebot-agent: + environment: + # Point to your external LiteLLM instance + - BYTEBOT_LLM_PROXY_URL=http://your-litellm-server:4000 + # ... rest of config +``` + +### 选项 2：使用环境变量 + +```bash +# Set the proxy URL before starting +export BYTEBOT_LLM_PROXY_URL=http://your-litellm-server:4000 + +# Start normally +docker-compose -f docker/docker-compose.yml up -d +``` + +### 选项 3：独立运行 LiteLLM + +```bash +# Run your own LiteLLM instance +docker run -d \ + --name litellm-external \ + -p 4000:4000 \ + -v $(pwd)/custom-config.yaml:/app/config.yaml \ + -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ + ghcr.io/berriai/litellm:main \ + --config /app/config.yaml + +# Then start Bytebot with: +export BYTEBOT_LLM_PROXY_URL=http://localhost:4000 +docker-compose up -d +``` + +## Kubernetes 部署 + +使用 Helm 进行部署： + +```yaml +# litellm-values.yaml +replicaCount: 2 + +image: + repository: ghcr.io/berriai/litellm + tag: main + +service: + type: ClusterIP + port: 4000 + +config: + model_list: + - model_name: claude-3-5-sonnet + litellm_params: + model: claude-3-5-sonnet-20241022 + api_key: ${ANTHROPIC_API_KEY} + + general_settings: + master_key: ${LITELLM_MASTER_KEY} + +# Then in Bytebot values.yaml: +agent: + openai: + enabled: true + apiKey: "${LITELLM_MASTER_KEY}" + baseUrl: "http://litellm:4000/v1" + model: "claude-3-5-sonnet" +``` + +## 监控与调试 + +### LiteLLM 仪表盘 + +访问指标和日志： + +```bash +# Port forward to dashboard +kubectl port-forward svc/litellm 4000:4000 + +# Access at http://localhost:4000/ui +# Login with your master_key +``` + +### 调试请求 + +启用详细日志记录： + +```yaml +litellm_settings: + debug: true + detailed_debug: true + +general_settings: + master_key: sk-key + store_model_in_db: true # Store request history +``` + +### 常见问题 + + + + 检查模型名称是否完全匹配： + ```bash + curl http://localhost:4000/v1/models \ + -H "Authorization: Bearer sk-key" + ``` + + + + 验证 LiteLLM 和 Bytebot 中的主密钥： + ```bash + # 测试 LiteLLM + curl http://localhost:4000/v1/chat/completions \ + -H "Authorization: Bearer sk-key" \ + -H "Content-Type: application/json" \ + -d '{"model": "your-model", "messages": [{"role": "user", "content": "test"}]}' + ``` + + + + 检查每个提供商的延迟： + ```yaml + router_settings: + routing_strategy: "latency-based" + enable_pre_call_checks: true + ``` + + + +## 最佳实践 + +### Bytebot 模型选择 + +选择具有强大视觉能力的模型以获得最佳效果： + + + + - Claude 3.5 Sonnet (综合最佳) + - GPT-4o (优秀视觉+推理能力) + - Gemini 1.5 Pro (大上下文窗口) + + + - Claude 3.5 Haiku (快速+便宜) + - GPT-4o mini (良好平衡) + - Gemini 1.5 Flash (极速) + + + - LLaVA (支持视觉) + - Qwen-VL (支持视觉) + - CogVLM (支持视觉) + + + +### 性能优化 + +```yaml +# Optimize for Bytebot workloads +router_settings: + routing_strategy: "latency-based" + cooldown_time: 60 # Seconds before retrying failed provider + num_retries: 2 + request_timeout: 600 # 10 minutes for complex tasks + + # Cache for repeated requests + cache: true + cache_params: + type: "redis" + host: "redis" + port: 6379 + ttl: 3600 # 1 hour +``` + +### 安全性 + +```yaml +general_settings: + master_key: ${LITELLM_MASTER_KEY} + + # IP allowlist + allowed_ips: ["10.0.0.0/8", "172.16.0.0/12"] + + # Audit logging + store_model_in_db: true + + # Encryption + encrypt_keys: true + + # Headers to forward + forward_headers: ["X-Request-ID", "X-User-ID"] +``` + +## 后续步骤 + + + + 完整的100+提供商列表 + + + LiteLLM代理服务器官方文档 + + + 完整的LiteLLM文档 + + + + + **专业提示:** 从单个提供商开始，然后根据需要添加更多。LiteLLM让您无需更改Bytebot配置即可轻松切换或组合模型。 + \ No newline at end of file diff --git a/docs/zh/deployment/railway.mdx b/docs/zh/deployment/railway.mdx new file mode 100644 index 000000000..616ae0080 --- /dev/null +++ b/docs/zh/deployment/railway.mdx @@ -0,0 +1,89 @@ +--- +title: "在 Railway 上部署 Bytebot" +description: "使用官方一键模板在 Railway 上部署完整 Bytebot 堆栈的全面指南" +--- + +> **TL;DR –** 点击下方按钮，添加您的 AI API 密钥（Anthropic、OpenAI 或 Google），您的个人 Bytebot 实例将在约 2 分钟内上线。 + +[![在 Railway 上部署](https://railway.com/button.svg)](https://railway.com/deploy/bytebot?referralCode=L9lKXQ) + +--- + +## 为什么选择 Railway？ + +Railway 提供零运维的 PaaS 体验，具备私有网络和按服务日志功能，完美契合 Bytebot 的多容器架构。官方模板使用推送到 `edge` 分支的最新容器镜像将所有服务连接在一起。 + +--- + +## 部署内容 + +| 服务 | 容器镜像 (edge) | 端口 | 是否暴露 | 用途 | +| ---------------- | -------------------------------------------------------------------- | ----- | -------- | -------------------------------------- | +| **bytebot-ui** | `ghcr.io/bytebot-ai/bytebot-ui:edge` | 9992 | **是** | 面向外部呈现的 Next.js Web 用户界面 | +| **bytebot-agent**| `ghcr.io/bytebot-ai/bytebot-agent:edge` | 9991 | 否 | 任务编排与 LLM 调用 | +| **bytebot-desktop**| `ghcr.io/bytebot-ai/bytebot-desktop:edge` | 9990 | 否 | 容器化的 Ubuntu + XFCE 桌面环境 | +| **postgres** | `postgres:14-alpine` | 5432 | 否 | 持久化存储层 | + +所有内部流量均通过 Railway 的[私有网络](https://docs.railway.com/guides/private-networking)进行传输。仅 `bytebot-ui` 被分配了公共域名。 + +--- + +## 分步详细指南 + + + + 点击上方的 **Deploy on Railway** 按钮或访问 [https://railway.com/deploy/bytebot?referralCode=L9lKXQ](https://railway.com/deploy/bytebot?referralCode=L9lKXQ)。 + + + 对于 bytebot-agent 资源，添加您的 AI API 密钥（至少选择一种）： + - **Anthropic**：粘贴到 `ANTHROPIC_API_KEY` 以使用 Claude 模型 + - **OpenAI**：粘贴到 `OPENAI_API_KEY` 以使用 GPT 模型 + - **Google**：粘贴到 `GEMINI_API_KEY` 以使用 Gemini 模型 + + 其他设置保持默认。 + + + 点击 **Deploy**。Railway 将拉取预构建的镜像，创建 Postgres 数据库并在私有网络中链接所有服务。 + + + 当构建日志显示 *"bytebot-ui: ready"* 时，点击生成的 URL（例如 `https://bytebot-ui-prod.up.railway.app`）。您应该能看到任务界面。创建任务并观看桌面流！ + _提示：您可以从 Railway 仪表板跟踪每个服务的日志。_ + + + + + 首次部署会下载多个容器层 – 预计需要约 2 分钟。后续重新部署会快得多。 + + +--- + +## 私有网络与安全 + +• **私有网络**确保代理、桌面端和数据库能够安全通信，无需将端口暴露至互联网。 +• **公开暴露**仅限于提供静态资源和代理 WebSocket 流量的用户界面。 +• **添加认证**可通过将用户界面置于 Railway 内置密码保护或外部提供商（如 Cloudflare Access、Auth0、OAuth 代理）之后实现。 +• 您还可以从 Railway 仪表板将自定义域名指向用户界面，并启用 Cloudflare 以获取 WAF/CDN 保护。 + +--- + +## 自定义与扩展 + +1. **更换镜像** – Fork 代码库，推送您自己的镜像并编辑模板中的 `Dockerfile` 引用。 +2. **增加资源** – 每项服务在 Railway 中均有独立的 CPU/内存滑块。若计划运行重度自动化任务，请提升桌面端或代理的资源配额。 + +--- + +## 故障排除 + +| 现象 | 可能原因 | 解决方案 | +| ------- | ------------ | ---- | +| Web 界面显示“连接中…” | 桌面端未就绪或私有网络配置错误 | 等待 `bytebot-desktop` 容器完成启动，或重启服务 | +| 代理报错 `401` 或 `403` | API 密钥缺失/无效 | 在 Railway 环境变量中重新输入 AI 提供商的 API 密钥 | +| 桌面端视频卡顿 | 免费版 Railway 限流 | 升级套餐或在桌面端设置中降低屏幕分辨率 | + +--- + +## 后续步骤 + +• 探索 [REST API](/api-reference/introduction) 以编程方式编写任务脚本。 +• 加入我们的 [Discord](https://discord.com/invite/d9ewZkWPTP) 社区获取支持并展示您的自动化成果！ \ No newline at end of file diff --git a/docs/zh/guides/password-management.mdx b/docs/zh/guides/password-management.mdx new file mode 100644 index 000000000..86b5e5d0b --- /dev/null +++ b/docs/zh/guides/password-management.mdx @@ -0,0 +1,388 @@ +--- +title: "密码管理与双因素认证" +description: "Bytebot 如何使用密码管理器自动处理身份验证" +--- + +# 使用 Bytebot 实现自动化身份验证 + +当您设置密码管理器扩展后，Bytebot 可以自动处理身份验证 - 包括密码、双因素认证，甚至复杂的多步骤身份验证流程。 + + + **重要提示**：密码管理器扩展默认未启用。您需要使用桌面视图手动安装它们。 + + +## 工作原理 + +Bytebot 内置 1Password 并支持任何基于浏览器的密码管理器扩展。它可以： + +- 自动从密码管理器填充密码 +- 处理双因素认证代码（TOTP/验证器应用） +- 跨不同系统管理多个账户 +- 与单点登录和联合身份验证配合使用 +- 存储和使用 API 密钥与令牌 + +## 设置密码管理 + +### 选项 1：1Password（推荐） + + + + 1. 前往 Bytebot UI 中的 Desktop 标签页 + 2. 打开 Firefox + 3. 从 Firefox 扩展商店安装 1Password 扩展 + 4. 登录您的 1Password 账户（或为 Bytebot 创建专用账户） + + + + 在您的 1Password 管理面板中： + 1. 创建一个名为 "Bytebot Automation" 的保险库 + 2. 添加 Bytebot 所需的凭据 + 3. 与 Bytebot 账户共享该保险库 + 4. 设置适当的权限（推荐只读权限） + + + + 1Password 扩展将自动： + - 检测登录表单 + - 填充凭据 + - 处理 2FA 验证码 + - 提交表单 + + + +### 选项 2：其他密码管理器 + +您可以通过 Desktop 视图安装任何基于浏览器的密码管理器： + + + + 1. 打开桌面标签页 + 2. 启动 Firefox + 3. 从 Firefox 扩展商店安装 Bitwarden 扩展 + 4. 登录您的 Bitwarden 账户 + 5. 在 Bitwarden 偏好设置中配置自动填充设置 + + + 1. 打开桌面标签页 + 2. 启动 Firefox + 3. 从 Firefox 扩展商店安装 LastPass 扩展 + 4. 使用企业账户登录 + 5. 接受任何用于自动化凭据的共享文件夹 + + + 1. 打开桌面标签页 + 2. 如需请安装 KeePassXC 应用程序 + 3. 在 Firefox 中安装 KeePassXC 浏览器扩展 + 4. 配置浏览器集成 + 5. 加载您的 KeePass 数据库 + + + +## 处理不同的认证类型 + +### 标准用户名/密码 + +```yaml +# Task description +Task: "Log into our CRM system and export the customer list" + +# Bytebot automatically: +1. Navigates to login page +2. Password manager detects form +3. Auto-fills credentials +4. Submits login +5. Proceeds with task +``` + +### 基于时间的双因素认证 (TOTP) + +```yaml +# Task description +Task: "Access the banking portal and download statements" + +# Bytebot handles: +1. Enters username/password from password manager +2. When 2FA prompt appears +3. Password manager provides TOTP code +4. Enters code automatically +5. Completes authentication +``` + +### 复杂多步骤认证 + +```yaml +# Task description +Task: "Log into the government portal (uses email verification)" + +# Bytebot can: +1. Fill initial credentials +2. Handle "send code to email" flows +3. Access webmail account (also in password manager) +4. Retrieve verification code from webmail +5. Complete authentication +``` + +## 企业设置指南 + +### 集中式凭据管理 + + + + 为 Bytebot 设置专用服务账户： + ``` + - bytebot-finance@company.com (银行门户) + - bytebot-hr@company.com (人力资源系统) + - bytebot-ops@company.com (运营工具) + ``` + + + + 构建您的密码管理器结构： + ``` + Bytebot 保险库/ + ├── 财务系统/ + │ ├── 银行门户 A + │ ├── 银行门户 B + │ └── 支付处理器 + ├── 内部工具/ + │ ├── ERP 系统 + │ ├── CRM 平台 + │ └── 人力资源门户 + └── 外部服务/ + ├── 供应商门户 1 + ├── 政府网站 + └── 合作伙伴系统 + ``` + + + + 配置自动密码轮换： + ```javascript + // 密码轮换自动化示例 + { + "schedule": "monthly", + "task": "对于'需要轮换'保险库中的每个凭据， + 在系统中更新密码并保存新密码" + } + ``` + + + +### 安全最佳实践 + + + + 仅共享 Bytebot 执行特定任务所需的凭据 + + + 启用密码管理器审计日志以跟踪访问情况 + + + 按敏感级别和部门分离保险库 + + + 每月审计 Bytebot 的凭据访问情况 + + + +## 常见身份验证场景 + +### 银行与金融系统 + +```yaml +Scenario: Daily bank reconciliation across 5 banks + +Setup: +- Each bank credential in password manager +- 2FA seeds stored for TOTP generation +- Bytebot's IP whitelisted at banks + +Task: "Log into each bank account, download yesterday's + transactions, and consolidate into daily report" + +Result: Fully automated, no human intervention needed +``` + +### 政府与合规门户 + +```yaml +Scenario: Weekly regulatory filings + +Setup: +- Service account with 2FA enabled +- Password manager has TOTP seed +- Security questions stored as notes + +Task: "Log into state tax portal, file weekly sales tax + report using data from tax_data.csv" + +Handles: Password, 2FA, security questions, CAPTCHAs +``` + +### 多租户 SaaS 平台 + +```yaml +Scenario: Managing multiple client accounts + +Setup: +- Credentials for each tenant/client +- Organized in password manager by client +- Naming convention: client-platform-role + +Task: "For each client in client_list.txt, log into their + Shopify account and export this month's orders" + +Scales: Handles 100+ accounts seamlessly +``` + +## 高级身份验证功能 + +### SSO 和 SAML 集成 + +```yaml +# Bytebot can handle SSO flows +Task: "Log into Salesforce using Okta SSO" + +Process: +1. Navigate to Salesforce +2. Click "Log in with SSO" +3. Redirect to Okta +4. Password manager fills Okta credentials +5. Handle any 2FA on Okta +6. Redirect back to Salesforce +7. Continue with task +``` + +### API 密钥管理 + +```yaml +# Store API keys in password manager +Password Entry: "OpenAI API Key" +- Username: "api" +- Password: "sk-proj-..." +- Notes: "Rate limit: 10000/day" + +# Use in tasks +Task: "Configure the application to use our OpenAI API key + from the password manager" +``` + +### 基于证书的身份验证 + +```yaml +# For systems requiring certificates +Setup: +1. Store certificate password in manager +2. Mount certificate file to Bytebot +3. Configure browser to use certificate + +Task: "Access the enterprise portal that requires + client certificate authentication" +``` + +## 身份验证故障排除 + + + + **解决方案：** + - 确保扩展已安装并登录 + - 检查网站是否已保存在密码管理器中 + - 确认自动填充设置已启用 + - 尝试刷新页面 + + + + **常见原因：** + - 时间同步问题（检查系统时钟） + - 保存了错误的 TOTP 种子 + - 网站使用非标准双因素认证 + + **修复方法：** + ```bash + # 同步系统时间 + docker exec bytebot-desktop ntpdate -s time.nist.gov + ``` + + + + **解决方案：** + - 启用"记住我"功能（如果可用） + - 增加目标系统中的会话超时时间 + - 将长任务拆分为小块 + - 尽可能使用 API 访问 + + + +## 集成示例 + +### 财务自动化脚本 + +```python +# Example: Automated invoice collection +tasks = [ + { + "description": "Log into vendor portal A and download all pending invoices", + "credentials": "vault://Financial Systems/Vendor Portal A" + }, + { + "description": "Log into vendor portal B and download all pending invoices", + "credentials": "vault://Financial Systems/Vendor Portal B" + }, + { + "description": "Process all downloaded invoices through our AP system", + "credentials": "vault://Internal Tools/AP System" + } +] + +# Bytebot handles all authentication automatically +``` + +### 合规自动化 + +```yaml +Daily Compliance Check: + Morning: + - Log into regulatory portal (2FA enabled) + - Download new compliance updates + - Check our status + + If Non-Compliant: + - Log into internal system + - Create compliance ticket + - Notify compliance team + + All credentials managed automatically +``` + +## 最佳实践总结 + +✅ **建议做法：** + +- 为 Bytebot 使用专用服务账户 +- 在逻辑保险库中组织凭据 +- 在所有账户上启用双因素认证（Bytebot 会处理！） +- 定期轮换密码 +- 监控访问日志 + +❌ **禁止做法：** + +- 与 Bytebot 共享个人凭据 +- 在任务描述中存储密码 +- 为了方便而禁用双因素认证 +- 在不同系统中使用相同密码 +- 忽略认证错误 + +## 后续步骤 + + + + 查看认证实战案例 + + + 编程式凭据管理 + + + + + **颠覆性变革**：通过正确的密码管理器设置，Bytebot 甚至可以自动处理最复杂的认证流程。无需再手动干预双因素认证，无需再不安全地共享密码，您的自动化工作流中再也不会有认证瓶颈！ + \ No newline at end of file diff --git a/docs/zh/guides/takeover-mode.mdx b/docs/zh/guides/takeover-mode.mdx new file mode 100644 index 000000000..78246443f --- /dev/null +++ b/docs/zh/guides/takeover-mode.mdx @@ -0,0 +1,141 @@ +--- +title: "接管模式" +description: "在需要引导或协助 Bytebot 时掌控桌面控制权" +--- + +# 接管模式：人机协作 + +接管模式允许您在需要时掌控桌面来帮助 Bytebot。有两种使用方式： + +## 1. 任务执行期间 + +在任务详情视图中，您可以点击接管按钮来： + +- 当智能体走向错误路径时中断它 +- 引导它找到正确的解决方案 +- 在它遇到困难时解决问题 + +## 2. 自动激活 + +当任务状态设置为"需要帮助"时，接管模式会自动启用 - 这发生在智能体意识到无法独立完成某项任务时。 + +## 操作记录方式 + +您在接管期间的所有操作（点击、拖拽、滚动、输入、按键）都会自动记录在与智能体使用的同一统一操作空间中。这意味着 Bytebot 能够理解并学习您的所有操作。 + +## 设置用的桌面标签页 + +在任务之外，主页面有一个专门的**桌面**标签页，提供： + +- 自由访问桌面的权限 +- 此模式下不会记录任何操作 +- 非常适合： + - 安装程序 + - 登录应用程序或网站 + - 设置桌面环境 + - 一般桌面维护 + +## 激活接管模式 + +### 方法一：任务期间手动接管 + + + + 当 Bytebot 正在处理任务时，点击任务以打开详情视图。 + + + + 点击接管按钮以中断智能体并取得控制权。 + + + + 执行必要操作以越过障碍或展示正确路径。 + + + + 点击释放控制权，让 Bytebot 从您离开的位置继续执行。 + + + +### 方法二：需要帮助时自动触发 + +当 Bytebot 将任务状态设置为"需要帮助"时： + +- 接管模式自动启用 +- 您将收到 Bytebot 需要协助的通知 +- 取得控制权以帮助解决问题 +- 当您释放控制权后 Bytebot 将继续执行 + +## 常见使用场景 + +### 1. 复杂界面导航 + + + **场景**：处理专有或复杂软件 + + **步骤**： + 1. 让 Bytebot 打开应用程序 + 2. 接管控制以导航复杂界面 + 3. 使用聊天功能解释您的操作 + 4. 交还控制权让 Bytebot 继续执行 + + **示例**："打开我们的内部 CRM，我将向您展示如何导航到报告部分" + + +### 2. 错误恢复 + + + **场景**: Bytebot 遇到错误或卡住 + + **步骤**: + 1. 注意到 Bytebot 遇到困难 + 2. 接管控制以解决问题 + 3. 引导它绕过问题 + 4. 在聊天中解释出错原因 + 5. 交还控制权让 Bytebot 继续 + + **示例**: "让我来处理这个意外弹窗，它正在阻塞工作流程" + + +### 3. 通过演示进行教学 + + + **场景**: 复杂的多步骤流程 + + **步骤**: + 1. 需要演示时接管控制 + 2. 正常执行任务（无需放慢速度） + 3. 使用聊天解释点击内容和原因 + 4. 交还控制权 + 5. 要求 Bytebot 重复该流程 + + **示例**: "看我如何通过供应商门户导航找到发票部分" + + + + **重要提示**: 接管模式期间每个操作都会截图。请勿输入任何不希望被截图捕获的数据。 + + +## 最佳实践 + +### 正确做法 ✅ + +- **接管时使用聊天**: 输入消息解释您正在做什么以及原因 +- **解释您的点击**: 分享 UI 元素及其用途的上下文 +- **离开前交还控制权**: 在退出任务详情视图前始终释放控制权 +- **测试理解程度**: 要求 Bytebot 总结所学内容 + +### 错误做法 ❌ + +- **输入您不希望被捕获的数据**：所有操作都会被截图记录 +- **跳过聊天解释**：上下文有助于 Bytebot 学习模式 +- **控制期间离开任务视图**：这将导致任务卡在接管模式中 +- **不要预设知识**：请解释特定应用的工作流程 + + + **无需缓慢操作**：Bytebot 会在每个动作前后捕获状态，因此您可以按正常速度工作。 + + +## 概述 + +当您需要引导 Bytebot 或处理其无法单独应对的情况时，接管模式提供了灵活性。无论是导航复杂界面、从错误中恢复，还是教授新的工作流程，接管模式都能确保您在需要时始终保持控制权。 \ No newline at end of file diff --git a/docs/zh/guides/task-creation.mdx b/docs/zh/guides/task-creation.mdx new file mode 100644 index 000000000..e5e54fc66 --- /dev/null +++ b/docs/zh/guides/task-creation.mdx @@ -0,0 +1,442 @@ +--- +title: "任务创建与管理" +description: "掌握创建高效任务并管理其完成过程的技巧" +--- + +# 在 Bytebot 中创建和管理任务 + +本指南将带您了解创建 Bytebot 可有效执行的任务以及管理其生命周期的所有必要知识。 + +## 理解任务 + +任务是您希望 Bytebot 完成的任何工作。任务可以是： + +- **简单型**："登录 GitHub" 或 "访问 example.com"（使用一个程序） +- **复杂型**："从电子邮件下载发票并保存到文件夹"（使用多个程序） +- **基于文件型**："读取上传的 PDF 并提取所有电子邮件地址"（处理上传的文件） +- **协作型**："处理发票，请我处理特殊审批" + +## 文件处理 + +Bytebot 具有强大的文件处理能力，非常适合文档处理和数据分折任务。 + +### 上传任务文件 + +创建任务时，您可以上传文件，这些文件将自动保存到桌面实例。这对于以下场景非常有用： + +- **文档处理**：上传 PDF、电子表格或文档供 Bytebot 分析 +- **数据分析**：提供 CSV 文件或数据集进行处理 +- **模板填充**：上传需要填写的表格或模板 +- **批量操作**：上传多个文件进行批量处理 + + + **游戏规则改变者**：Bytebot 能够将整个文件（包括 PDF）直接读取到 LLM 上下文中。这意味着它可以快速处理大量数据，并理解复杂文档，无需手动提取。 + + +### 文件上传示例 + + + + 1. 创建任务时点击附件按钮 + 2. 选择要上传的文件（PDF、CSV、图片等） + 3. 文件将自动保存到桌面 + 4. 在任务描述中引用它们： + ``` + "读取上传的 contracts.pdf 并提取所有付款条款， + 然后创建一个包含供应商名称和条款的摘要电子表格" + ``` + + + ```bash + # 创建任务时上传文件（multipart/form-data） + curl -X POST http://localhost:9991/tasks \ + -F "description=Analyze the uploaded financial statements and create a summary" \ + -F "priority=HIGH" \ + -F "files=@financial_statements_2024.pdf" \ + -F "files=@budget_comparison.xlsx" + ``` + + + +### 文件处理能力 + + + + - 从 PDF 中提取文本 + - 将整个 PDF 读入上下文 + - 解析表单和合同 + - 提取表格和数据 + + + - 读取 Excel/CSV 文件 + - 分析数据模式 + - 生成报告 + - 跨多个工作表交叉引用 + + + - 总结长文档 + - 提取关键信息 + - 比较多个文件 + - 回答关于内容的问题 + + + - 处理多个文件 + - 对每个文件应用相同的分析 + - 合并结果 + - 生成统一报告 + + + +## 创建您的第一个任务 + +### 使用 Web 界面 + + + + 导航至 `http://localhost:9992` + + + + 在左侧的输入字段中，输入您想要完成的任务。例如： + ``` + 登录我的 GitHub 账户并检查新通知 + ``` + + + + 按下箭头按钮或按 Enter 键。Bytebot 将开始加载并着手处理您的任务。 + + + +### 使用 API + +```bash +curl -X POST http://localhost:9991/tasks \ + -H "Content-Type: application/json" \ + -d '{ + "description": "Download all PDF invoices from my email and organize by date", + "priority": "HIGH", + "type": "IMMEDIATE" + }' +``` + +## 编写有效的任务描述 + +### 黄金法则 + + + + ❌ "做一些研究" + ✅ "研究适用于小型企业的前5名CRM工具" + + + ❌ "填写表格" + ✅ "在example.com上用测试数据填写联系表单" + + + ❌ "整理文件" + ✅ "按类型将下载文件夹中的文件整理到子文件夹中" + + + ❌ "做多个不相关的事情" + ✅ "专注于具有明确步骤的单一目标" + + + +### 任务描述模板 + +#### 企业流程自动化 + +``` +Log into [system] and: +1. [Navigate to specific section] +2. [Download/Extract data] +3. [Process through other system] +4. [Update records/Generate report] +Handle any [specific scenarios] + +Example: +Log into our banking portal and: +1. Navigate to wire transfers section +2. Download all pending wire confirmations +3. Match against our ERP payment records +4. Flag any discrepancies in the reconciliation sheet +(Bytebot handles all authentication including 2FA automatically via password manager) +``` + +#### 多应用工作流 + +``` +Access [System A] to get [data] +Then in [System B]: +1. [Process the data] +2. [Update records] +Finally in [System C]: +1. [Verify updates] +2. [Generate confirmation] + +Example: +Access Salesforce to get list of new customers from today +Then in NetSuite: +1. Create customer records with billing info +2. Set up payment terms +Finally in our shipping system: +1. Verify addresses are valid +2. Generate welcome kit shipping labels +``` + +#### 合规与审计任务 + +``` +For each [entity] in [source]: +1. Check [compliance requirement] +2. Document [specific data] +3. Flag any [violations/issues] +Generate report showing [metrics] + +Example: +For each vendor in our approved vendor list: +1. Check their insurance certificates are current +2. Document expiration dates and coverage amounts +3. Flag any expiring within 30 days +Generate report showing compliance percentage by category +``` + +## 管理活动任务 + +### 任务状态 + +Task Lifecycle + +任务会经历以下状态： + +1. **已创建** → 任务已定义但未开始 +2. **已排队** → 等待代理可用 +3. **运行中** → 正在积极处理 +4. **需要帮助** → 需要人工输入 +5. **已完成** → 成功完成 +6. **已失败** → 无法完成 + +### 监控进度 + +#### 实时更新 + +通过任务详情查看器观察Bytebot的工作过程： + +- **绿点**：任务正在积极运行 +- **状态消息**：当前正在执行的步骤 +- **桌面视图**：实时查看Bytebot所见内容 + +#### 聊天消息 + +Bytebot提供如下更新： + +``` +Assistant: I'm now searching for project management tools... +Assistant: Found 15 options, filtering by your criteria... +Assistant: Creating the comparison table with 5 tools... +``` + +### 与运行中的任务交互 + +#### 提供额外信息 + +``` +User: "Also include free tier options in your research" +Assistant: "I'll add a column for free tier availability to the comparison table." +``` + +#### 澄清指令 + +``` +Assistant: "I found multiple forms on this page. Which one should I fill out?" +User: "Use the 'Contact Sales' form on the right side" +``` + +#### 修改任务 + +``` +User: "Actually, make it top 10 tools instead of top 5" +Assistant: "I'll expand my research to include 10 tools in the comparison." +``` + +## 高级任务管理 + +### 任务依赖关系 + +链接相互依赖的任务： + +``` +Task 1: "Download the invoice from the vendor portal" +Task 2: "Open the downloaded invoice and extract the total amount" +Task 3: "Enter the amount into our accounting system" +``` + +## 最佳实践 + +### 正确做法 ✅ + +1. **从简单开始**：在复杂任务前先用基础任务测试 +2. **提供示例**："按照上周报告的格式进行排版" +3. **安全包含凭据**：使用接管模式输入密码 +4. **设定合理预期**：复杂任务需要时间完成 +5. **检查结果**：始终验证重要输出 + +### 错误做法 ❌ + +1. **单任务过载**：将复杂工作流拆分为多个步骤 +2. **假定已知**：解释自定义应用程序 +3. **跳过上下文**：始终提供必要的背景信息 +4. **忽略错误**：及时处理问题 +5. **匆忙处理关键任务**：留出时间仔细执行 + +## 按类别划分的任务示例 + +### 📄 文档处理与分析 + +``` +"Read the uploaded contract.pdf and extract all key terms including payment schedules, deliverables, and termination clauses. Create a summary document with these details." + +"Process all the uploaded invoice PDFs, extract vendor names, amounts, and due dates, then create a consolidated Excel spreadsheet sorted by due date." + +"Analyze the uploaded financial_report.pdf and answer these questions: What was the revenue growth? What are the main risk factors mentioned? What is the debt-to-equity ratio?" + +"Read through the uploaded employee_handbook.pdf and create a checklist of all compliance requirements mentioned in the document." +``` + +### 🏦 企业自动化（RPA风格工作流） + +``` +"Log into our banking portal, download all transaction files from last month, save them to the Finance/Statements folder, then run the reconciliation script on each file." + +(Note: Bytebot handles all authentication including 2FA automatically using the built-in password manager) + +"Access the vendor portal at supplier.example.com, navigate to the invoice section, download all pending invoices, extract the data into our standard template, and upload to the AP system." + +"Open our legacy ERP system, export the customer list, then for each customer, look them up in the new CRM and update their status and last contact date." +``` + +### 📊 财务运营与数据分析 + +``` +"Read the uploaded bank_statements folder containing 12 monthly PDFs, extract all transactions over $10,000, and create a summary report showing patterns and anomalies." + +"Log into each of our 5 bank accounts, download the daily statements, consolidate them into a single cash position report, and save to the shared finance folder." + +"Process the uploaded expense_reports.zip file, review all reports over $1,000, create a summary with policy violations flagged, and prepare for approval." + +"Navigate to the tax authority website, download all GST/VAT returns for Q4, extract the figures, and populate our tax reconciliation spreadsheet." +``` + +### 🔄 多系统集成 + +``` +"Pull today's orders from Shopify, create corresponding entries in NetSuite, update inventory in our WMS, and trigger shipping labels in ShipStation." + +"Extract employee data from Workday, cross-reference with our access control system, identify discrepancies, and create tickets for IT to resolve." + +"Log into our insurance portal, download policy documents for all active policies, extract key dates and coverage amounts, update our risk management database." +``` + +### 📈 合规与报告 + +``` +"Access all state regulatory websites for our operating regions, check for new compliance updates since last month, download relevant documents, and create a summary report." + +"Log into our various SaaS tools (list provided), export user access reports, consolidate into a single audit trail, and flag any terminated employees still with access." + +"Navigate to customer portal, download all SLA performance reports, extract metrics, compare against our internal data, and highlight discrepancies." +``` + +### 🤝 开发与质量保证集成 + +``` +"After the code agent deploys the new feature, test the complete user journey from signup to checkout, take screenshots at each step, and verify against the design specs." + +"Run through all test scenarios in our QA checklist, but for any failures, have the code agent analyze the error and attempt a fix, then retest automatically." + +"Monitor our staging environment, when a new build is deployed, automatically run the smoke test suite and create a visual regression report comparing to production." +``` + +## 常见问题排查 + + + + **可能原因**: + - 等待缓慢的页面/应用加载 + - 遇到意外弹窗 + - 下一步操作不明确 + + **解决方案**: + - 通过桌面查看器检查当前状态 + - 通过聊天提供说明 + - 使用接管模式协助 + - 取消并使用更清晰的指令重新开始 + + + + **可能原因**: + - 指令模糊不清 + - 网站/应用发生变化 + - 上下文理解错误 + + **解决方案**: + - 检查任务描述的清晰度 + - 提供具体示例 + - 拆分为更小的子任务 + - 使用接管模式进行演示 + + + + **可能原因**: + - 无效URL或应用程序 + - 缺少先决条件 + - 系统资源问题 + + **解决方案**: + - 验证URL和应用程序名称 + - 确保所需文件/数据存在 + - 检查系统资源 + - 查看聊天中的错误消息 + + + +## 任务管理技巧 + +### 组织多个任务 + +1. **使用清晰命名**: 包含日期、类别或项目信息 +2. **分组相关任务**: 批量处理相似任务 +3. **优先级管理**: 仅为真正紧急情况保留'紧急'标签 +4. **定期检查**: 审查已完成任务的质量 + +### 性能优化 + +- **批量处理相似任务**：将网页调研、数据录入等任务分组处理 +- **准备资源**：开始前备好文件/数据 +- **清理桌面**：减少干扰和弹窗 +- **稳定环境**：确保网络通畅和系统资源充足 + +### 从任务中学习 + +每项任务完成后： + +1. 复盘Bytebot采用的处理方式 +2. 记录存在的低效环节 +3. 优化后续任务描述 +4. 建立高效提示词库 + +## 后续步骤 + + + + 学习人机协作技巧 + + + 实现任务自动化创建 + + + + + **专业提示**：从简单任务开始以了解Bytebot能力，随后根据使用经验逐步增加任务复杂度。 + \ No newline at end of file diff --git a/docs/zh/introduction.mdx b/docs/zh/introduction.mdx new file mode 100644 index 000000000..7743fc2b4 --- /dev/null +++ b/docs/zh/introduction.mdx @@ -0,0 +1,216 @@ +--- +title: 简介 +description: "开源AI桌面代理，可自动化任何计算机任务" +--- + +

+ Bytebot Logo + Bytebot Logo +

+ +## 什么是 Bytebot？ + +Bytebot 是一个开源 AI 代理，能够控制计算机桌面为您完成任务。它在您自有基础设施的 Docker 容器中运行，为您提供一个可以执行以下操作的虚拟助手： + +- 使用任何桌面应用程序（浏览器、电子邮件、办公工具等） +- 处理上传的文件，包括 PDF、电子表格和文档 +- 将整个文件直接读入 LLM 上下文进行快速分析 +- 自动化重复性任务，如数据录入和表单填写 +- 处理跨多个应用程序的复杂工作流 +- 无需人工监督，全天候 24/7 工作 + +只需用简单的英语描述您需要完成的任务，Bytebot 就会找出如何执行——点击按钮、输入文本、浏览网站、阅读文档并完成任务，就像人类一样。 + +## 为什么选择 Bytebot 而非传统 RPA？ + + + + 与UiPath等工具不同，无需设计流程图或编写脚本——只需自然描述任务 + + + 基于AI的理解能力意味着Bytebot能适应UI变化而不会中断 + + + 可读取和理解任何界面，不仅限于预设映射的元素 + + + 自动处理意外弹窗、错误和变化情况 + + + +## 为何选择自托管Bytebot？ + + + + 您的任务和数据永远不会离开您的基础设施。所有操作都在您的服务器本地运行。 + + + 可自定义桌面环境，安装任何应用程序，并根据您的精确需求进行配置。 + + + 使用您自己的LLM API密钥，不受平台限制或额外费用影响。 + + + 每个桌面在独立容器中运行，与主机系统完全隔离。 + + + +## 实际应用场景 + +### 企业自动化（RPA替代方案） + +Bytebot是下一代RPA（机器人流程自动化）。它能处理与传统工具（如UiPath）相同的复杂工作流，但具备AI驱动的自适应能力和自动身份验证功能： + +- **财务运营**：自动化银行门户访问（配置密码管理器扩展时包含双重认证），下载交易文件并通过多个系统进行处理 +- **合规工作流**：导航政府网站，下载监管文件，提取数据并更新合规跟踪系统 +- **多系统集成**：通过自动化UI交互，桥接缺乏API的遗留系统 +- **供应商管理**：登录供应商门户，下载发票，与内部系统对账并处理付款 + +### 业务流程自动化 + +- **数据核对**：从多个SaaS平台拉取报告，交叉引用数据并生成合并报告 +- **客户 onboarding**：在CRM、银行和验证系统之间导航以完成新客户设置 +- **采购订单处理**：从网页邮箱门户提取采购订单，录入ERP系统并更新库存数据库 +- **人力资源运营**：从各系统收集员工数据，更新记录并确保跨平台一致性 + +### 开发与质量保证集成 + +当与编码代理结合使用时，Bytebot变得更加强大： + +- **全栈测试**：使用编码代理生成代码，然后让Bytebot通过可视化方式测试并验证输出结果 +- **自动化调试**：让Bytebot复现用户反馈的问题，同时由编码代理分析和修复代码 +- **端到端开发**：代码代理编写功能，Bytebot进行测试，形成完整的开发闭环 +- **视觉回归测试**：通过截图对比自动检测不同部署版本间的UI变更 + +## 工作原理 + + + + 只需通过任务界面用自然语言告诉Bytebot您需要完成什么 + + + Bytebot理解您的需求并将其分解为具体的计算机操作指令 + + + Bytebot在其虚拟桌面上使用键盘和鼠标执行任务 + + + 通过任务详情视图实时监控工作进度，或让其独立完成任务 + + + 接收已完成的任务输出、截图或完成确认 + + + +## 架构概览 + +Bytebot由四个协同工作的集成组件组成： + +Bytebot Agent Architecture + + + + 基于 Ubuntu 22.04 系统，配备 XFCE4、VSCode、Firefox、Thunderbird 邮件客户端及自动化守护进程 (bytebotd) + + + 使用 LLM（Anthropic Claude、OpenAI GPT、Google Gemini）进行任务规划与执行的 NestJS 服务 + + + 用于创建和管理任务的 Next.js 网络应用程序 + + + 提供任务管理和直接桌面控制的编程接口 + + + +## 快速开始 + + + + 2 分钟内启动 Bytebot + + + 了解整体架构设计 + + + 与您的应用程序集成 + + + +## 核心功能 + +### 🤖 自然语言控制 + +只需告诉 Bytebot 您的需求。无需编码或复杂的自动化工具。 + +### 🖥️ 完整桌面访问 + +Bytebot 可使用任何可安装的应用程序——浏览器、办公工具、定制软件。 + +### 🔒 完全隐私保护 + +完全在您的基础设施上运行。您的数据永远不会离开您的服务器。 + +### 🔄 两种操作模式 + +- **自主模式**：Bytebot 独立完成任务 +- **接管模式**：您可以在需要时介入并接管控制 + +### 🖱️ 直接桌面访问 + +- **桌面标签页**：自由访问虚拟桌面进行设置、安装程序或手动操作 +- **任务视图**：在任务执行过程中观看并与 Bytebot 互动 + +### 🚀 轻松部署 + +- 在 Railway 上一键部署 +- 使用 Docker Compose 进行自托管 +- 提供 Kubernetes 的 Helm charts + +### 🔌 开发者友好 + +- 提供 REST API 进行程序化控制 +- 任务管理 API +- 可扩展架构 +- 支持 MCP（模型上下文协议） + +## 社区与支持 + + + + 加入我们的社区获取帮助、技巧和讨论 + + + 报告问题、贡献代码或为项目点赞 + + + + + **准备好为您的 AI 配备专属计算机了吗？** 从我们的[快速入门指南](/quickstart)开始，几分钟内即可运行您自己的 AI 桌面代理。 + \ No newline at end of file diff --git a/docs/zh/quickstart.mdx b/docs/zh/quickstart.mdx new file mode 100644 index 000000000..0602a8c17 --- /dev/null +++ b/docs/zh/quickstart.mdx @@ -0,0 +1,361 @@ +--- +title: "快速开始" +description: "2分钟内让您的AI桌面助手运行起来" +--- + +# 选择您的部署方式 + +Bytebot 可根据您的需求通过多种方式部署： + + + + ## ☁️ 一键部署到 Railway + +[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/bytebot?referralCode=L9lKXQ) + + + + 点击 Railway 上 Bytebot 模板中的 "Deploy Now" 按钮。 + + + 为 bytebot-agent 资源输入您的 `ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 或 `GEMINI_API_KEY`。 + + + 点击 **Deploy**。Railway 将构建堆栈，通过私有网络连接服务，并为 UI 输出一个公共 URL。您的代理应在几分钟内准备就绪！ + + + + + 需要更多详细信息？请参阅完整的 Railway 部署指南。 + + + + + ## 🐳 使用 Docker Compose 自托管 + +## 先决条件 + +- Docker ≥ 20.10 +- Docker Compose +- 可用 4GB+ RAM +- 来自以下提供商之一的 AI API 密钥： + - Anthropic ([在此获取](https://console.anthropic.com)) - Claude 模型 + - OpenAI ([在此获取](https://platform.openai.com/api-keys)) - GPT 模型 + - Google ([在此获取](https://makersuite.google.com/app/apikey)) - Gemini 模型 + +## 🚀 2 分钟设置 + +只需三个命令即可运行您的自托管 AI 桌面代理： + + + + ```bash + git clone https://github.com/bytebot-ai/bytebot.git + cd bytebot + + # 配置您的 AI 提供商（选择一个）： + echo "ANTHROPIC_API_KEY=your_api_key_here" > docker/.env # 用于 Claude + # echo "OPENAI_API_KEY=your_api_key_here" > docker/.env # 用于 OpenAI + # echo "GEMINI_API_KEY=your_api_key_here" > docker/.env # 用于 Gemini + ``` + + + + ```bash + docker-compose -f docker/docker-compose.yml up -d + ``` + +这将启动所有四个服务： + +- **Bytebot Desktop**: 容器化的 Linux 环境 +- **AI Agent**: 基于 LLM 的任务处理器（支持 Claude、GPT 或 Gemini） +- **Chat UI**: 用于交互的 Web 界面 +- **Database**: 用于持久化的 PostgreSQL + + + + +导航至 [http://localhost:9992](http://localhost:9992) 以访问 Bytebot UI。 + +**两种交互方式：** +1. **任务**: 输入任务描述，让 Bytebot 自主工作 +2. **桌面**: 直接访问虚拟桌面进行手动控制 + +尝试询问： + +- "打开 Firefox 并搜索天气预报" +- "截取桌面截图" +- "创建一个包含今天日期的文本文件" + + + + + + **第一次使用？** 初始启动可能需要 2-3 分钟，因为 Docker 会下载镜像。后续启动会快得多。 + + +## 🎯 您刚刚部署的内容 + +您现在拥有一个完整的 AI 桌面自动化系统，包含： + + + **🔐 密码管理器支持**: 当您安装密码管理器扩展时，Bytebot 可以自动处理身份验证。请参阅我们的 [密码管理指南](/guides/password-management) 获取设置说明。 + + + + + - 理解自然语言 + - 规划并执行任务 + - 适应错误 + - 自主工作 + + + - 完整的 Ubuntu 环境 + - 浏览器、办公工具 + - 文件系统访问 + - 应用程序支持 + + + - 创建和管理任务 + - 实时桌面视图 + - 对话历史记录 + - 接管模式 + + + - 编程控制 + - 任务管理 API + - 直接桌面访问 + - MCP 协议支持 + + + +## 🚀 您的第一个任务 + +现在让我们看看 Bytebot 的实际操作！尝试以下示例任务： + +### 简单任务（测试基础功能） + + + "截取桌面截图" + + + "打开 Firefox 并访问 google.com" + + + "创建一个名为 'hello.txt' 的文本文件，包含今天的日期" + + + "检查系统信息并告诉我操作系统版本" + + + +### 高级任务（体验强大功能） + + + "查找今天排名前 5 的 AI 新闻故事并创建摘要文档" + + + "访问黑客新闻，找到排名前 10 的故事，并将它们保存到 CSV 文件" + + + "上传 PDF 合同并提取所有付款条款和截止日期" + + + "搜索 '机器学习教程'，在前 3 个结果中打开标签页，并为每个页面截取屏幕截图" + + + +## 访问您的服务 + +| 服务 | URL | 用途 | +| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------- | +| **任务 UI** | [http://localhost:9992](http://localhost:9992) | 与代理交互的主要界面 | +| **代理 API** | [http://localhost:9991/tasks](http://localhost:9991/tasks) | 用于编程创建任务的 REST API | +| **桌面 API** | [http://localhost:9990/computer-use](http://localhost:9990/computer-use) | 低级桌面控制 API | +| **MCP SSE** | [http://localhost:9990/mcp](http://localhost:9990/mcp) | 连接 MCP 客户端以访问工具 | + + + + ## ☸️ 使用 Helm 部署 + + 请参阅我们的 [Helm 部署指南](/deployment/helm) 了解 Kubernetes 安装。 + + + ## 🖥️ 仅桌面容器 + + 如果您只需要虚拟桌面而不需要 AI 代理： + + ```bash + # 使用预构建镜像（推荐） + docker-compose -f docker/docker-compose.core.yml pull + docker-compose -f docker/docker-compose.core.yml up -d + ``` + + 或在本地构建： + ```bash + docker-compose -f docker/docker-compose.core.yml up -d --build + ``` + + 在 [http://localhost:9990/vnc](http://localhost:9990/vnc) 访问桌面 + + + +## 管理您的智能体 + +### 查看日志 + +监控您的智能体正在执行的操作： + +```bash +# All services +docker-compose -f docker/docker-compose.yml logs -f + +# Just the agent +docker-compose -f docker/docker-compose.yml logs -f bytebot-agent +``` + +### 停止服务 + +```bash +docker-compose -f docker/docker-compose.yml down +``` + +### 更新至最新版本 + +```bash +docker-compose -f docker/docker-compose.yml pull +docker-compose -f docker/docker-compose.yml up -d +``` + +### 重置所有内容 + +移除所有数据并重新开始： + +```bash +docker-compose -f docker/docker-compose.yml down -v +``` + +## 快速 API 示例 + +### 通过 API 创建任务 + +```bash +# Simple task +curl -X POST http://localhost:9991/tasks \ + -H "Content-Type: application/json" \ + -d '{ + "description": "Search for flights from NYC to London next month", + "priority": "MEDIUM" + }' + +# Task with file upload +curl -X POST http://localhost:9991/tasks \ + -F "description=Read this contract and summarize the key terms" \ + -F "priority=HIGH" \ + -F "files=@contract.pdf" +``` + +### 直接桌面控制 + +```bash +# Take a screenshot +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "screenshot"}' + +# Type text +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "type_text", "text": "Hello, Bytebot!"}' +``` + +## 故障排除 + + + + 检查 Docker 是否正在运行且资源充足： + ```bash + docker info + docker-compose -f docker/docker-compose.yml logs + ``` + + + 确保所有服务都在运行： + ```bash + docker-compose -f docker/docker-compose.yml ps + ``` + 所有服务应显示为 "Up"（运行中）。 + + + 检查您的 API 密钥是否正确设置： + ```bash + cat docker/.env + docker-compose -f docker/docker-compose.yml logs bytebot-agent + ``` + 确保您使用的是来自 Anthropic、OpenAI 或 Google 的有效 API 密钥。 + + + +## 📚 后续步骤 + + + + 学习如何有效创建和管理任务 + + + 在需要引导 Bytebot 时接管控制 + + + 使用任意 LLM 提供商与 Bytebot 配合 + + + 通过应用程序自动化 Bytebot + + + +## 🔧 配置选项 + +### 环境变量 + + + + ```bash + # 选择一个 AI 提供商： + ANTHROPIC_API_KEY=sk-ant-... # 用于 Claude 模型 + OPENAI_API_KEY=sk-... # 用于 GPT 模型 + GEMINI_API_KEY=... # 用于 Gemini 模型 + + # 可选：使用特定模型 + ANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # 默认 + OPENAI_MODEL=gpt-4o + GEMINI_MODEL=gemini-1.5-flash + ``` + + + ```bash + # 如有需要，更改默认端口 + # 编辑 docker-compose.yml 的 ports 部分： + # bytebot-ui: + # ports: + # - "8080:9992" # 将 8080 改为您所需的端口 + ``` + + + ```bash + # 要使用多个 LLM 提供商，请使用代理设置： + docker-compose -f docker/docker-compose.proxy.yml up -d + + # 这包含一个预配置的 LiteLLM 代理 + ``` + + + + + **需要帮助？** 加入我们的 [Discord + 社区](https://discord.com/invite/d9ewZkWPTP) 获取支持并分享 + 您正在构建的内容！ + \ No newline at end of file diff --git a/docs/zh/rest-api/computer-use.mdx b/docs/zh/rest-api/computer-use.mdx new file mode 100644 index 000000000..d76826eab --- /dev/null +++ b/docs/zh/rest-api/computer-use.mdx @@ -0,0 +1,526 @@ +--- +title: "计算机操作" +openapi: "POST /computer-use" +description: "在虚拟桌面环境中执行计算机操作" +--- + +在 Bytebot 桌面环境中执行鼠标移动、点击、键盘输入和截图等操作。 + +## 请求 + + + 要执行的计算机操作类型。必须是以下之一：`move_mouse`、`trace_mouse`、 + `click_mouse`、`press_mouse`、`drag_mouse`、`scroll`、`type_keys`、`press_keys`、 + `type_text`、`wait`、`screenshot`、`cursor_position`。 + + +### 鼠标操作 + + + + 要移动到的目标坐标。 + + + + X 坐标（水平位置） + + + Y 坐标（垂直位置） + + + + +**请求示例** + +```json +{ + "action": "move_mouse", + "coordinates": { + "x": 100, + "y": 200 + } +} +``` + + + + + + 鼠标路径的坐标对象数组。 + + + + + + X 坐标 + + + Y 坐标 + + + + + + +{" "} + + + 在沿路径移动鼠标时按住的按键。 + + +**示例请求** + +```json +{ + "action": "trace_mouse", + "path": [ + { "x": 100, "y": 100 }, + { "x": 150, "y": 150 }, + { "x": 200, "y": 200 } + ], + "holdKeys": ["shift"] +} +``` + + + + + + 要点击的坐标（如果省略则使用当前光标位置）。 + + + + X坐标（水平位置） + + + Y坐标（垂直位置） + + + + +{" "} + + + 要点击的鼠标按钮。必须是以下之一：`left`、`right`、`middle`。 + + +{" "} + + + 要执行的点击次数。 + + +{" "} + + + 点击时按住的功能键（例如，['ctrl', 'shift']） + + + 键名 + + + + +**示例请求** + +```json +{ + "action": "click_mouse", + "coordinates": { + "x": 150, + "y": 250 + }, + "button": "left", + "clickCount": 2 +} +``` + + + + + + 要按下/释放的坐标（如果省略则使用当前光标位置）。 + + + + X 坐标（水平位置） + + + Y 坐标（垂直位置） + + + + +{" "} + + + 要按下/释放的鼠标按钮。必须是以下之一：`left`、`right`、`middle`。 + + +{" "} + + + 是按下还是释放按钮。必须是以下之一：`up`、`down`。 + + +**示例请求** + +```json +{ + "action": "press_mouse", + "coordinates": { + "x": 150, + "y": 250 + }, + "button": "left", + "press": "down" +} +``` + + + + + + 拖拽路径的坐标对象数组。 + + + + + + X 坐标 + + + Y 坐标 + + + + + + +{" "} + + + 用于拖拽的鼠标按钮。必须是以下之一：`left`、`right`、`middle`。 + + +{" "} + + + 拖拽时按住的按键。 + + +**示例请求** + +```json +{ + "action": "drag_mouse", + "path": [ + { "x": 100, "y": 100 }, + { "x": 200, "y": 200 } + ], + "button": "left" +} +``` + + + + + + 要滚动到的坐标（如果省略则使用当前光标位置）。 + + + + X 坐标 + + + Y 坐标 + + + + +{" "} + + + 滚动方向。必须是以下之一：`up`、`down`、`left`、`right`。 + + +{" "} + + + 要执行的滚动步数。 + + +{" "} + + + 滚动时要按住的键。 + + +**示例请求** + +```json +{ + "action": "scroll", + "direction": "down", + "scrollCount": 5 +} +``` + + + +### 键盘操作 + + + + 要按顺序输入的键数组。 + + + 键名 + + + + +{" "} + + + 按键之间的延迟（毫秒）。 + + +**示例请求** + +```json +{ + "action": "type_keys", + "keys": ["a", "b", "c", "enter"], + "delay": 50 +} +``` + + + + + + 要按下或释放的按键数组。 + + + 键名 + + + + +{" "} + + + 按下或释放按键。必须是以下之一：`up`、`down`。 + + +**示例请求** + +```json +{ + "action": "press_keys", + "keys": ["ctrl", "shift", "esc"], + "press": "down" +} +``` + + + + + + 要输入的文本字符串。 + + +{" "} + + + 字符之间的延迟（毫秒）。 + + +**示例请求** + +```json +{ + "action": "type_text", + "text": "Hello, Bytebot!", + "delay": 50 +} +``` + + + + + + 要粘贴的文本。对于标准键盘上没有的特殊字符非常有用。 + + +**示例请求** + +```json +{ + "action": "paste_text", + "text": "Special characters: ©®™€¥£ émojis 🎉" +} +``` + + + +### 系统操作 + + + + 等待时长（毫秒）。 + + +**示例请求** + +```json +{ + "action": "wait", + "duration": 2000 +} +``` + + + + +无需参数。 + +**请求示例** + +```json +{ + "action": "screenshot" +} +``` + + + + +无需参数。 + +**请求示例** + +```json +{ + "action": "cursor_position" +} +``` + + + + + + 要切换到的应用程序。可用选项：`firefox`、`1password`、`thunderbird`、`vscode`、`terminal`、`desktop`、`directory`。 + + +**请求示例** + +```json +{ + "action": "application", + "application": "firefox" +} +``` + +**可用应用程序：** +- `firefox` - Mozilla Firefox 网页浏览器 +- `1password` - 密码管理器 +- `thunderbird` - 电子邮件客户端 +- `vscode` - Visual Studio Code 编辑器 +- `terminal` - 终端/控制台应用程序 +- `desktop` - 切换到桌面 +- `directory` - 文件管理器/目录浏览器 + + + +## 响应 + +响应根据执行的操作而有所不同： + +### 默认响应 + +大多数操作返回一个简单的成功响应： + +```json +{ + "success": true +} +``` + +### 截图响应 + +返回以 base64 编码字符串形式的截图： + +```json +{ + "success": true, + "data": { + "image": "base64_encoded_image_data" + } +} +``` + +### 光标位置响应 + +返回当前光标位置： + +```json +{ + "success": true, + "data": { + "x": 123, + "y": 456 + } +} +``` + +### 错误响应 + +```json +{ + "success": false, + "error": "Error message" +} +``` + +### 代码示例 + + +```bash cURL +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "move_mouse", "coordinates": {"x": 100, "y": 200}}' +``` + +```python Python +import requests + +def control_computer(action, **params): + url = "http://localhost:9990/computer-use" + data = {"action": action, **params} + response = requests.post(url, json=data) + return response.json() + +# Move the mouse +result = control_computer("move_mouse", coordinates={"x": 100, "y": 100}) +print(result) +``` + +```javascript JavaScript +const axios = require("axios"); + +async function controlComputer(action, params = {}) { + const url = "http://localhost:9990/computer-use"; + const data = { action, ...params }; + const response = await axios.post(url, data); + return response.data; +} + +// Move mouse example +controlComputer("move_mouse", { coordinates: { x: 100, y: 100 } }) + .then((result) => console.log(result)) + .catch((error) => console.error("Error:", error)); +``` + + \ No newline at end of file diff --git a/docs/zh/rest-api/examples.mdx b/docs/zh/rest-api/examples.mdx new file mode 100644 index 000000000..86460d718 --- /dev/null +++ b/docs/zh/rest-api/examples.mdx @@ -0,0 +1,582 @@ +--- +title: "使用示例" +description: "使用 Bytebot REST API 实现常见自动化场景的代码示例" +--- + +本页面提供了在不同编程语言和场景下使用 Bytebot REST API 的实用示例。 + +## 语言示例 + +### cURL 示例 + + +```bash Open Application and Navigate +# Open an application (like Firefox) +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "move_mouse", "coordinates": {"x": 100, "y": 950}}' + +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "click_mouse", "button": "left", "clickCount": 2}' + +# Wait for application to open + +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "wait", "duration": 150}' + +# Type URL in address bar + +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "type_text", "text": "https://example.com"}' + +# Press Enter to navigate + +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "typ_keys", "keys": ["enter"]}' + +```` + +```bash Take and Save Screenshot +# Take a screenshot +response=$(curl -s -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "screenshot"}') + +# Extract the base64 image data and save to a file +echo $response | jq -r '.data.image' | base64 -d > screenshot.png +echo "Screenshot saved to screenshot.png" +```` + +```bash Copy and Paste Text +# Select text with triple click (selects a paragraph) +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "move_mouse", "coordinates": {"x": 400, "y": 300}}' + +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "click_mouse", "button": "left", "clickCount": 3}' + +# Copy with Ctrl+C +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "press_keys", "keys": ["ctrl", "c"], "press": "down"}' + +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "press_keys", "keys": ["ctrl", "c"], "press": "up"}' + +# Click elsewhere to paste +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "move_mouse", "coordinates": {"x": 400, "y": 500}}' + +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "click_mouse", "button": "left"}' + +# Paste with Ctrl+V +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "press_keys", "keys": ["ctrl", "v"], "press": "down"}' + +curl -X POST http://localhost:9990/computer-use \ + -H "Content-Type: application/json" \ + -d '{"action": "press_keys", "keys": ["ctrl", "v"], "press": "up"}' +``` + + + +### Python 示例 + + +```python Web Form Automation +import requests +import time + +def control_computer(action, **params): +url = "http://localhost:9990/computer-use" +data = {"action": action, **params} +response = requests.post(url, json=data) +return response.json() + +def fill_web_form(): # Navigate to a form (e.g., login form) +control_computer("move_mouse", coordinates={"x": 500, "y": 300}) +control_computer("click_mouse", button="left") + + # Type username + control_computer("type_text", text="user@example.com") + + # Tab to password field + control_computer("type_keys", keys=["tab"]) + + # Type password + control_computer("type_text", text="secure_password") + + # Tab to login button + control_computer("type_keys", keys=["tab"]) + + # Press Enter to submit + control_computer("type_keys", keys=["enter"]) + + # Wait for page to load + control_computer("wait", duration=2000) + + print("Form submitted successfully") + +# Run the automation + +# fill_web_form() + +```` + +```python File Upload Dialog +import requests +import time + +def control_computer(action, **params): + url = "http://localhost:9990/computer-use" + data = {"action": action, **params} + response = requests.post(url, json=data) + return response.json() + +def upload_file(file_path="/path/to/file.txt"): + # Click the upload button + control_computer("move_mouse", coordinates={"x": 400, "y": 300}) + control_computer("click_mouse", button="left") + + # Wait for file dialog to appear + control_computer("wait", duration=1000) + + # Type the file path + control_computer("type_text", text=file_path) + + # Press Enter to confirm + control_computer("press_keys", keys=["enter"], press="down") + control_computer("press_keys", keys=["enter"], press="up") + + # Wait for upload to complete + control_computer("wait", duration=3000) + + # Take screenshot of result + result = control_computer("screenshot") + if result["success"]: + print("File upload completed and screenshot taken") + +# Run the automation +# upload_file("/Users/username/Documents/example.pdf") +```` + +```python Screenshot Monitoring +import requests +import base64 +import time +from io import BytesIO +from PIL import Image + +def take_screenshot(): + url = "http://localhost:9990/computer-use" + response = requests.post(url, json={"action": "screenshot"}) + if response.json()["success"]: + img_data = base64.b64decode(response.json()["data"]["image"]) + return Image.open(BytesIO(img_data)) + return None + +def monitor_for_changes(interval=5, duration=60): + """Monitor the screen for changes at regular intervals""" + first_screenshot = take_screenshot() + if not first_screenshot: + print("Failed to take initial screenshot") + return + + first_screenshot.save("baseline.png") + print("Baseline screenshot saved") + + end_time = time.time() + duration + screenshot_count = 1 + + while time.time() < end_time: + time.sleep(interval) + + current = take_screenshot() + if current: + filename = f"screenshot_{screenshot_count}.png" + current.save(filename) + print(f"Saved {filename}") + screenshot_count += 1 + + print(f"Monitoring completed. Saved {screenshot_count} screenshots.") + +# Run the monitoring for 30 seconds, taking a screenshot every 5 seconds +# monitor_for_changes(interval=5, duration=30) +``` + + + +### JavaScript/Node.js 示例 + + +```javascript Browser Navigation +const axios = require('axios'); + +async function controlComputer(action, params = {}) { +const url = "http://localhost:9990/computer-use"; +const data = { action, ...params }; + +try { +const response = await axios.post(url, data); +return response.data; +} catch (error) { +console.error('Error:', error.message); +throw error; +} +} + +async function navigateToWebsite(url) { +console.log(`Navigating to ${url}...`); + +// Open Firefox/Chrome by clicking on dock icon +await controlComputer("move_mouse", { coordinates: { x: 100, y: 950 } }); +await controlComputer("click_mouse", { button: "left" }); + +// Wait for browser to open +await controlComputer("wait", { duration: 2000 }); + +// Click in URL bar (usually near the top) +await controlComputer("move_mouse", { coordinates: { x: 400, y: 60 } }); +await controlComputer("click_mouse", { button: "left" }); + +// Select all existing text (Cmd+A on Mac, Ctrl+A elsewhere) +await controlComputer("press_keys", { keys: ["ctrl"], press: "down" }); +await controlComputer("press_keys", { keys: ["a"], press: "down" }); +await controlComputer("press_keys", { keys: ["a"], press: "up" }); +await controlComputer("press_keys", { keys: ["ctrl"], press: "up" }); + +// Type the URL +await controlComputer("type_text", { text: url }); + +// Press Enter to navigate +await controlComputer("press_keys", { keys: ["enter"], press: "down" }); +await controlComputer("press_keys", { keys: ["enter"], press: "up" }); + +// Wait for page to load +await controlComputer("wait", { duration: 3000 }); + +console.log("Navigation completed"); +} + +// Usage +// navigateToWebsite("https://example.com").catch(console.error); + +```` + +```javascript Data Entry Automation +const axios = require('axios'); + +async function controlComputer(action, params = {}) { + const url = "http://localhost:9990/computer-use"; + const data = { action, ...params }; + + try { + const response = await axios.post(url, data); + return response.data; + } catch (error) { + console.error('Error:', error.message); + throw error; + } +} + +// Function to fill a data entry form +async function fillDataEntryForm(formData) { + // Click on the first form field + await controlComputer("move_mouse", { coordinates: { x: 400, y: 250 } }); + await controlComputer("click_mouse", { button: "left" }); + + // Fill each field and press Tab to move to the next + for (const [index, value] of formData.entries()) { + // Type the value + await controlComputer("type_text", { text: value }); + + // If not the last field, press Tab to move to next field + if (index < formData.length - 1) { + await controlComputer("press_keys", { keys: ["tab"], press: "down" }); + await controlComputer("press_keys", { keys: ["tab"], press: "up" }); + await controlComputer("wait", { duration: 300 }); + } + } + + // Find and click the submit button + await controlComputer("move_mouse", { coordinates: { x: 400, y: 500 } }); + await controlComputer("click_mouse", { button: "left" }); + + // Take a screenshot of the result + const result = await controlComputer("screenshot"); + console.log("Form submitted successfully"); + + return result; +} + +// Example form data +const formFields = [ + "John Doe", // Name + "john.doe@example.com", // Email + "123 Main St", // Address + "555-123-4567" // Phone +]; + +// Usage +// fillDataEntryForm(formFields).catch(console.error); +```` + +```javascript UI Testing +const axios = require("axios"); +const fs = require("fs"); + +async function controlComputer(action, params = {}) { + const url = "http://localhost:9990/computer-use"; + const data = { action, ...params }; + + try { + const response = await axios.post(url, data); + return response.data; + } catch (error) { + console.error("Error:", error.message); + throw error; + } +} + +// Simple UI testing framework +async function testUIElement(name, options) { + const { x, y, expectedResult } = options; + + console.log(`Testing UI element: ${name}`); + + // Take screenshot before interaction + const beforeShot = await controlComputer("screenshot"); + fs.writeFileSync( + `before_${name}.png`, + Buffer.from(beforeShot.data.image, "base64") + ); + + // Click the element + await controlComputer("move_mouse", { coordinates: { x, y } }); + await controlComputer("click_mouse", { button: "left" }); + + // Wait for any UI changes + await controlComputer("wait", { duration: 1000 }); + + // Take screenshot after interaction + const afterShot = await controlComputer("screenshot"); + fs.writeFileSync( + `after_${name}.png`, + Buffer.from(afterShot.data.image, "base64") + ); + + console.log(`Test for ${name} completed. Screenshots saved.`); + + if (expectedResult && typeof expectedResult === "function") { + // Call custom verification function if provided + await expectedResult(); + } +} + +// Example UI elements to test +const uiElements = [ + { name: "login_button", x: 500, y: 400 }, + { name: "menu_icon", x: 50, y: 50 }, + { name: "close_dialog", x: 800, y: 200 }, +]; + +// Run tests sequentially +async function runUITests() { + for (const element of uiElements) { + await testUIElement(element.name, element); + // Add some delay between tests + await controlComputer("wait", { duration: 2000 }); + } + console.log("All UI tests completed"); +} + +// Usage +// runUITests().catch(console.error); +``` + + + +### 常见自动化场景 + +### 浏览器自动化工作流 + +此示例演示了一个完整的浏览器工作流程，包括打开网站并与之交互： + +```python +import requests +import time + +def control_computer(action, **params): + url = "http://localhost:9990/computer-use" + data = {"action": action, **params} + response = requests.post(url, json=data) + return response.json() + +def browser_workflow(): + # Open browser (assuming browser icon is at position x=100, y=960) + control_computer("move_mouse", coordinates={"x": 100, "y": 960}) + control_computer("click_mouse", button="left") + time.sleep(3) # Wait for browser to open + + # Type URL and navigate + control_computer("type_text", text="https://example.com") + control_computer("press_keys", key="enter") + time.sleep(2) # Wait for page to load + + # Take screenshot of the loaded page + screenshot = control_computer("screenshot") + + # Click on a link (coordinates would need to be adjusted for your target) + control_computer("move_mouse", coordinates={"x": 300, "y": 400}) + control_computer("click_mouse", button="left") + time.sleep(2) + + # Scroll down + control_computer("scroll", direction="down", amount=500) + + # Fill a search box + control_computer("move_mouse", coordinates={"x": 600, "y": 200}) + control_computer("click_mouse", button="left") + control_computer("type_text", text="search query") + control_computer("press_keys", key="enter") + +browser_workflow() +``` + +### 表单填写工作流 + +此示例展示了完整的表单填写过程： + +```javascript +const axios = require("axios"); + +async function controlComputer(action, params = {}) { + const url = "http://localhost:9990/computer-use"; + const data = { action, ...params }; + const response = await axios.post(url, data); + return response.data; +} + +async function fillForm() { + // Navigate to form page + await controlComputer("move_mouse", { coordinates: { x: 100, y: 960 } }); + await controlComputer("click_mouse", { button: "left" }); + await controlComputer("wait", { duration: 3000 }); + await controlComputer("type_text", { text: "https://example.com/form" }); + await controlComputer("press_keys", { key: "enter" }); + await controlComputer("wait", { duration: 2000 }); + + // Fill form + // Name field + await controlComputer("move_mouse", { coordinates: { x: 400, y: 250 } }); + await controlComputer("click_mouse", { button: "left" }); + + // Type the value + await controlComputer("type_text", { text: "John Doe" }); + + // Email field (tab to next field) + await controlComputer("press_keys", { keys: ["tab"], press: "down" }); + await controlComputer("press_keys", { keys: ["tab"], press: "up" }); + await controlComputer("type_text", { text: "john@example.com" }); + + // Message field (tab to next field) + await controlComputer("press_keys", { keys: ["tab"], press: "down" }); + await controlComputer("press_keys", { keys: ["tab"], press: "up" }); + await controlComputer("type_text", { + text: "This is an automated message sent using Bytebot's Computer Use API", + delay: 30, + }); + + // Submit form + await controlComputer("press_keys", { keys: ["tab"], press: "down" }); + await controlComputer("press_keys", { keys: ["tab"], press: "up" }); + await controlComputer("press_keys", { key: "enter" }); + + // Take screenshot of confirmation page + await controlComputer("wait", { duration: 2000 }); + const screenshot = await controlComputer("screenshot"); + + console.log("Form submitted successfully"); +} + +fillForm().catch(console.error); +``` + +### 自动化框架集成 + +您可以使用 Bytebot 创建可重用的自动化框架： + +```python +import requests +import time +import json + +class BytebotDriver: + """A Selenium-like driver for Bytebot""" + + def __init__(self, base_url="http://localhost:9990"): + self.base_url = base_url + + def control_computer(self, action, **params): + url = f"{self.base_url}/computer-use" + data = {"action": action, **params} + response = requests.post(url, json=data) + return response.json() + + def open_browser(self, browser_icon_coords): + """Open a browser by clicking its icon""" + self.control_computer("move_mouse", coordinates=browser_icon_coords) + self.control_computer("click_mouse", button="left") + time.sleep(3) # Wait for browser to open + + def navigate_to(self, url): + """Navigate to a URL in the browser""" + self.control_computer("type_text", text=url) + self.control_computer("press_keys", key="enter") + time.sleep(2) # Wait for page to load + + def click_element(self, coords): + """Click an element at the specified coordinates""" + self.control_computer("move_mouse", coordinates=coords) + self.control_computer("click_mouse", button="left") + + def type_text(self, text): + """Type text at the current cursor position""" + self.control_computer("type_text", text=text) + + def press_key(self, key, modifiers=None): + """Press a keyboard key with optional modifiers""" + params = {"key": key} + if modifiers: + params["modifiers"] = modifiers + self.control_computer("press_keys", **params) + + def take_screenshot(self): + """Take a screenshot of the desktop""" + return self.control_computer("screenshot") + + def scroll(self, direction, amount): + """Scroll in the specified direction""" + self.control_computer("scroll", direction=direction, amount=amount) + +# Example usage +driver = BytebotDriver() +driver.open_browser({"x": 100, "y": 960}) +driver.navigate_to("https://example.com") +driver.click_element({"x": 300, "y": 400}) +driver.type_text("Hello Bytebot!") +driver.press_key("enter") +result = driver.take_screenshot() +print(f"Screenshot captured: {result['success']}") +``` \ No newline at end of file diff --git a/docs/zh/rest-api/input-tracking.mdx b/docs/zh/rest-api/input-tracking.mdx new file mode 100644 index 000000000..a4b5afb4e --- /dev/null +++ b/docs/zh/rest-api/input-tracking.mdx @@ -0,0 +1,38 @@ +--- +title: "输入追踪" +openapi: "POST /input-tracking/start" +description: "在 Bytebot 桌面上启动和停止输入追踪功能" +--- + +Bytebot 守护进程可以通过 `InputTracking` 模块监控鼠标和键盘事件。 +默认情况下追踪功能处于禁用状态，可通过 REST API 进行切换。 +追踪到的操作会通过 WebSocket 流式传输，以便代理将其存储为消息。 + +## 启动追踪 + +`POST /input-tracking/start` + +开始捕获输入事件。该端点返回一个简单的状态对象： + +```json +{ + "status": "started" +} +``` + +## 停止追踪 + +`POST /input-tracking/stop` + +停止捕获事件并清除所有内部缓冲区。响应格式与启动端点类似： + +```json +{ + "status": "stopped" +} +``` + +## WebSocket 流 + +当追踪处于活动状态时，操作会在守护进程运行的 WebSocket 服务器的 `input_action` 通道上发出。 +客户端可以连接到守护进程并监听这些事件，以便根据需要持久化存储。 \ No newline at end of file diff --git a/docs/zh/rest-api/introduction.mdx b/docs/zh/rest-api/introduction.mdx new file mode 100644 index 000000000..13871e45b --- /dev/null +++ b/docs/zh/rest-api/introduction.mdx @@ -0,0 +1,76 @@ +--- +title: "简介" +description: "Bytebot REST API 概览" +--- + +## Bytebot REST API + +Bytebot 的核心功能通过其 REST API 提供，该 API 提供了与桌面环境交互的端点。通过 API 可以实现对鼠标移动、键盘输入和屏幕捕获的程序化控制。 + +### 基础 URL + +所有 API 端点都相对于基础 URL： + +``` +http://localhost:9990 +``` + +端口可在运行容器时进行配置。 + +### 认证 + +Bytebot API 在本地访问时默认不需要身份验证。对于远程访问，应实施标准的网络安全实践。 + +### 响应格式 + +所有 API 响应都遵循标准 JSON 格式： + +```json +{ + "success": true, + "data": { ... }, // Response data specific to the action + "error": null // Error message if success is false +} +``` + +### 错误处理 + +当发生错误时，API 返回： + +```json +{ + "success": false, + "data": null, + "error": "Detailed error message" +} +``` + +常见 HTTP 状态码： + +| 状态码 | 描述 | +| ----------- | -------------------------------- | +| 200 | 成功 | +| 400 | 错误请求 - 参数无效 | +| 500 | 内部服务器错误 | + +### 可用端点 + + + + 执行桌面自动化操作，如鼠标移动、点击、键盘输入和屏幕截图 + + + 控制和流式传输来自桌面的键盘和鼠标事件 + + + 常见自动化场景的代码示例和片段 + + + +### 速率限制 + +该 API 目前未实施速率限制，但过多的请求可能会影响虚拟桌面环境的性能。 \ No newline at end of file