@tencent-ai/agent-sdk 0.3.116 → 0.3.118

package/cli/dist/web-ui/docs/cn/cli/sandboxing.md

@@ -1,316 +0,0 @@
-# Sandbox 沙箱使用指南 （Beta)
-
-> ⚠️ **Beta 功能**: Sandbox 功能目前处于 Beta 阶段，API 和功能可能会有变动。
-
-CodeBuddy 支持在隔离的沙箱环境中运行，提供安全的代码执行和项目开发环境。
-
-## 🎯 沙箱类型
-
-- **Container Sandbox （容器沙箱）**：基于 Docker/Podman 的本地容器环境
-- **E2B Sandbox （云端沙箱）**：基于 E2B 云服务的远程隔离环境
-- **Teleport 模式 （远程连接）**：连接到已部署的远程沙箱服务
-
-## 🚀 快速开始
-
-### Container Sandbox （容器）
-
-```bash
-# 基本使用 - 自动挂载当前目录
-codebuddy --sandbox "帮我分析这个项目"
-
-# 等价于
-codebuddy --sandbox container "帮我分析这个项目"
-
-# 管道模式
-echo "运行测试" | codebuddy --sandbox --print
-```
-
-**前置要求**:
-- 安装 Docker 或 Podman
-- 确保 Docker daemon 运行中
-
-### E2B Sandbox （云端）
-
-```bash
-# 设置 E2B API Key
-export E2B_API_KEY=your_api_key
-
-# 基本使用 （需要完整的 API URL)
-codebuddy --sandbox https://api.e2b.dev "创建一个 Python web 应用"
-
-# 上传当前工作目录
-codebuddy --sandbox https://api.e2b.dev --sandbox-upload-dir "分析这个项目"
-```
-
-### Teleport 模式 （远程连接）
-
-Teleport 模式用于连接到 BGA (Background Agent) 后台已创建的远程沙箱环境。这是一种特殊的连接模式，主要用于云端调度场景。
-
-```bash
-# 使用 teleport 值连接到远程沙箱
-codebuddy --teleport session_abc123XYZ4567890 "连接到远程沙箱"
-
-# 自定义请求头 （用于认证或路由）
-codebuddy --teleport session_abc123XYZ4567890 \
-  -H "X-Domain: example.com" \
-  -H "X-Enterprise-Id: ent123" \
-  "执行任务"
-```
-
-**Teleport 值格式**:
-- 格式： `session_{cliSessionId}`
-- `cliSessionId`：唯一的会话标识符
-- 示例： `session_abc123XYZ4567890`
-
-**工作原理**:
-1. BGA 后台生成唯一的 `cliSessionId`
-2. BGA 在沙箱中将代码 clone 到 `/workspace/{cliSessionId}` 目录
-3. BGA 生成 teleport 命令： `codebuddy --teleport session_{cliSessionId}`
-4. CLI 解析 teleport 值，连接到指定沙箱并切换到正确的工作目录
-5. 以 `root` 用户身份在沙箱中执行命令
-
-**前置要求**:
-- 有效的 teleport 值 （由 BGA 后台生成）
-- 正确的认证凭证 （通过 E2B_API_KEY 或 CODEBUDDY_AUTH_TOKEN)
-- 网络连通性到 BGA 后台服务
-
-**特点**:
-- 代码已由 BGA 后台准备，无需上传
-- 自动使用 root 用户执行命令
-- 工作目录自动设置为 `/workspace/{cliSessionId}`
-- 支持自定义 HTTP 请求头进行认证和路由
-
-## 📦 沙箱复用机制
-
-### 别名系统
-
-为用户/项目分配独立沙箱：
-
-```bash
-# 使用用户 ID 作为别名
-codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "任务"
-
-# 使用项目名作为别名
-codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "任务"
-```
-
-别名映射存储在 `~/.codebuddy/sandbox-state.json`,支持自动创建和复用。
-
-### 默认行为
-
-沙箱自动复用，无需手动指定 ID:
-
-```bash
-# 第一次 - 创建新沙箱
-$ codebuddy --sandbox https://api.e2b.dev "Hello"
-[Sandbox] Creating new E2B sandbox...
-[Sandbox] Created new sandbox: sb_abc123
-
-# 再次启动 - 自动复用
-$ codebuddy --sandbox https://api.e2b.dev "继续工作"
-[Sandbox] Reusing sandbox: sb_abc123
-```
-
-### 多项目管理
-
-一个沙箱可托管多个项目，自动隔离在不同目录：
-
-```
-/workspace/
-  ├── home-user-projectA/
-  ├── home-user-projectB/
-  └── var-www-website/
-```
-
-## ⚙️ 高级参数
-
-### 沙箱创建和连接
-
-```bash
-# 强制创建新沙箱 （忽略缓存）
-codebuddy --sandbox --sandbox-new "从头开始"
-
-# 连接到指定沙箱 ID （真实 ID)
-codebuddy --sandbox --sandbox-id sb_abc123 "继续上次的工作"
-
-# 使用别名 （自定义名称，自动创建和复用）
-codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "任务"     # 用户ID
-codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "任务"  # 项目名
-codebuddy --sandbox https://api.e2b.dev --sandbox-id team-backend -p "任务" # 团队名
-
-# 退出时终止沙箱 （默认保持运行以便复用）
-codebuddy --sandbox --sandbox-kill "完成后清理"
-```
-
-### 环境变量配置
-
-```bash
-# E2B 配置
-export E2B_API_KEY=your_api_key              # 必需
-export E2B_TEMPLATE=base                     # 模板名称 (默认: base)
-export E2B_TIMEOUT_MS=3600000                # 超时时间 (默认: 1小时)
-export E2B_ALLOW_INTERNET_ACCESS=true        # 允许互联网访问 (默认: true)
-
-# Container Sandbox 配置
-export CODEBUDDY_SANDBOX_IMAGE=node:20-alpine  # Docker 镜像
-```
-
-## 📊 沙箱管理
-
-### 列出沙箱
-
-```bash
-$ codebuddy sandbox list
-E2B Sandboxes:
-* sb_abc123 （2 projects, last used 2m ago)
-  sb_xyz789 （1 project, last used 2h ago)
-```
-
-### 查看详情
-
-```bash
-# 查看当前沙箱
-$ codebuddy sandbox info
-
-# 查看指定沙箱
-$ codebuddy sandbox info sb_xyz789
-```
-
-### 终止沙箱
-
-```bash
-$ codebuddy sandbox kill sb_abc123
-```
-
-### 清理失效沙箱
-
-```bash
-$ codebuddy sandbox clean
-```
-
-## 🔍 工作原理
-
-### 项目目录映射
-
-```bash
-本地路径： /Users/yangsubo/projectA
-沙箱路径： /workspace/Users-yangsubo-projectA
-```
-
-### 状态持久化
-
-沙箱状态保存在 `~/.codebuddy/sandbox-state.json`
-
-## 💡 最佳实践
-
-### 1. 选择合适的沙箱类型
-
-```bash
-# 需要本地容器隔离
-codebuddy --sandbox container "本地开发任务"
-
-# 云端协作或无本地环境
-codebuddy --sandbox https://api.e2b.dev "云端开发"
-
-# 连接到远程部署的沙箱服务
-codebuddy --teleport session_abc123XYZ4567890 "远程开发"
-```
-
-### 2. 项目隔离
-
-```bash
-cd ~/work/projectA
-codebuddy --sandbox "开发功能 X"
-
-cd ~/work/projectB
-codebuddy --sandbox "修复 bug Y"
-```
-
-### 3. 长期开发
-
-```bash
-# 第一天
-codebuddy --sandbox "搭建开发环境"
-
-# 第二天 - 秒级启动，环境保留
-codebuddy --sandbox "继续开发"
-```
-
-### 4. 临时任务
-
-使用 `--sandbox-kill` 自动清理：
-
-```bash
-codebuddy --sandbox --sandbox-kill "快速测试一个想法"
-```
-
-### 5. 定期清理
-
-```bash
-# 查看所有沙箱
-codebuddy sandbox list
-
-# 清理失效的
-codebuddy sandbox clean
-
-# 手动终止特定沙箱
-codebuddy sandbox kill sb_old123
-```
-
-## ⚠️ 注意事项
-
-### Container Sandbox
-
-- **挂载模式**：容器沙箱自动挂载当前目录，文件修改实时同步
-- **网络隔离**: Docker 容器与主机网络隔离
-- **资源限制**：受 Docker 配置限制
-
-### E2B Sandbox
-
-- **上传延迟**：首次上传项目需要时间，文件越多越慢
-- **文件同步**：不支持自动同步，需要重新上传或手动同步
-- **费用**: E2B 云服务可能产生费用，请查看官方定价
-- **超时**：沙箱有最大运行时间限制 （默认 1 小时）
-
-### 交互式命令
-
-E2B 和 Container 都支持交互式 PTY:
-
-```bash
-codebuddy --sandbox "用 vim 编辑 main.py"
-codebuddy --sandbox "运行 htop 查看进程"
-```
-
-## 🔧 故障排查
-
-### Docker 未运行
-
-```bash
-Error: Neither Docker nor Podman is available
-```
-**解决**：启动 Docker Desktop 或 Podman
-
-### E2B API Key 缺失
-
-```bash
-Error: E2B_API_KEY environment variable is required
-```
-**解决**: `export E2B_API_KEY=your_key_here`
-
-### 沙箱连接失败
-
-```bash
-Failed to connect to sandbox sb_abc123
-```
-**解决**：沙箱可能已过期，使用 `--sandbox-new` 创建新的
-
-### 查看调试日志
-
-```bash
-codebuddy --sandbox --debug "测试命令"
-```
-
-## 📚 相关文档
-
-- [CLI 参考](./cli-reference.md) - 完整命令行参数说明
-- [E2B 官方文档](https://e2b.dev/docs) - E2B 云服务文档

package/cli/dist/web-ui/docs/en/cli/sandboxing.md

@@ -1,316 +0,0 @@
-# Sandbox Usage Guide (Beta)
-
-> ⚠️ **Beta Feature**: The Sandbox feature is currently in Beta. APIs and functionality may change.
-
-CodeBuddy supports running in isolated sandbox environments, providing secure code execution and project development environments.
-
-## 🎯 Sandbox Types
-
-- **Container Sandbox**: Local container environment based on Docker/Podman
-- **E2B Sandbox**: Remote isolated environment based on E2B cloud service
-- **Teleport Mode**: Connect to remotely deployed sandbox services
-
-## 🚀 Quick Start
-
-### Container Sandbox
-
-```bash
-# Basic usage - automatically mounts current directory
-codebuddy --sandbox "Help me analyze this project"
-
-# Equivalent to
-codebuddy --sandbox container "Help me analyze this project"
-
-# Pipe mode
-echo "Run tests" | codebuddy --sandbox --print
-```
-
-**Prerequisites**:
-- Docker or Podman installed
-- Docker daemon running
-
-### E2B Sandbox (Cloud)
-
-```bash
-# Set E2B API Key
-export E2B_API_KEY=your_api_key
-
-# Basic usage (requires full API URL)
-codebuddy --sandbox https://api.e2b.dev "Create a Python web application"
-
-# Upload current working directory
-codebuddy --sandbox https://api.e2b.dev --sandbox-upload-dir "Analyze this project"
-```
-
-### Teleport Mode (Remote Connection)
-
-Teleport mode is used to connect to remote sandbox environments created by BGA (Background Agent). This is a special connection mode primarily used for cloud scheduling scenarios.
-
-```bash
-# Connect to remote sandbox using teleport value
-codebuddy --teleport session_abc123XYZ4567890 "Connect to remote sandbox"
-
-# Custom headers (for authentication or routing)
-codebuddy --teleport session_abc123XYZ4567890 \
-  -H "X-Domain: example.com" \
-  -H "X-Enterprise-Id: ent123" \
-  "Execute task"
-```
-
-**Teleport Value Format**:
-- Format: `session_{cliSessionId}`
-- `cliSessionId`: Unique session identifier
-- Example: `session_abc123XYZ4567890`
-
-**How It Works**:
-1. BGA backend generates a unique `cliSessionId`
-2. BGA clones code to `/workspace/{cliSessionId}` directory in the sandbox
-3. BGA generates teleport command: `codebuddy --teleport session_{cliSessionId}`
-4. CLI parses the teleport value, connects to the specified sandbox and switches to the correct working directory
-5. Executes commands as `root` user in the sandbox
-
-**Prerequisites**:
-- Valid teleport value (generated by BGA backend)
-- Correct authentication credentials (via E2B_API_KEY or CODEBUDDY_AUTH_TOKEN)
-- Network connectivity to BGA backend service
-
-**Features**:
-- Code is prepared by BGA backend, no upload needed
-- Automatically executes commands as root user
-- Working directory automatically set to `/workspace/{cliSessionId}`
-- Supports custom HTTP headers for authentication and routing
-
-## 📦 Sandbox Reuse Mechanism
-
-### Alias System
-
-Assign independent sandboxes for users/projects:
-
-```bash
-# Use user ID as alias
-codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "Task"
-
-# Use project name as alias
-codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "Task"
-```
-
-Alias mappings are stored in `~/.codebuddy/sandbox-state.json`, supporting automatic creation and reuse.
-
-### Default Behavior
-
-Sandboxes are automatically reused without manually specifying IDs:
-
-```bash
-# First time - creates new sandbox
-$ codebuddy --sandbox https://api.e2b.dev "Hello"
-[Sandbox] Creating new E2B sandbox...
-[Sandbox] Created new sandbox: sb_abc123
-
-# Next launch - automatically reuses
-$ codebuddy --sandbox https://api.e2b.dev "Continue working"
-[Sandbox] Reusing sandbox: sb_abc123
-```
-
-### Multi-Project Management
-
-A single sandbox can host multiple projects, automatically isolated in different directories:
-
-```
-/workspace/
-  ├── home-user-projectA/
-  ├── home-user-projectB/
-  └── var-www-website/
-```
-
-## ⚙️ Advanced Parameters
-
-### Sandbox Creation and Connection
-
-```bash
-# Force create new sandbox (ignore cache)
-codebuddy --sandbox --sandbox-new "Start from scratch"
-
-# Connect to specific sandbox ID (real ID)
-codebuddy --sandbox --sandbox-id sb_abc123 "Continue previous work"
-
-# Use aliases (custom names, auto-create and reuse)
-codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "Task"     # User ID
-codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "Task"  # Project name
-codebuddy --sandbox https://api.e2b.dev --sandbox-id team-backend -p "Task" # Team name
-
-# Terminate sandbox on exit (default keeps running for reuse)
-codebuddy --sandbox --sandbox-kill "Clean up after completion"
-```
-
-### Environment Variable Configuration
-
-```bash
-# E2B configuration
-export E2B_API_KEY=your_api_key              # Required
-export E2B_TEMPLATE=base                     # Template name (default: base)
-export E2B_TIMEOUT_MS=3600000                # Timeout (default: 1 hour)
-export E2B_ALLOW_INTERNET_ACCESS=true        # Allow internet access (default: true)
-
-# Container Sandbox configuration
-export CODEBUDDY_SANDBOX_IMAGE=node:20-alpine  # Docker image
-```
-
-## 📊 Sandbox Management
-
-### List Sandboxes
-
-```bash
-$ codebuddy sandbox list
-E2B Sandboxes:
-* sb_abc123 (2 projects, last used 2m ago)
-  sb_xyz789 (1 project, last used 2h ago)
-```
-
-### View Details
-
-```bash
-# View current sandbox
-$ codebuddy sandbox info
-
-# View specific sandbox
-$ codebuddy sandbox info sb_xyz789
-```
-
-### Terminate Sandbox
-
-```bash
-$ codebuddy sandbox kill sb_abc123
-```
-
-### Clean Up Invalid Sandboxes
-
-```bash
-$ codebuddy sandbox clean
-```
-
-## 🔍 How It Works
-
-### Project Directory Mapping
-
-```bash
-Local path: /Users/yangsubo/projectA
-Sandbox path: /workspace/Users-yangsubo-projectA
-```
-
-### State Persistence
-
-Sandbox state is saved in `~/.codebuddy/sandbox-state.json`
-
-## 💡 Best Practices
-
-### 1. Choose the Right Sandbox Type
-
-```bash
-# Need local container isolation
-codebuddy --sandbox container "Local development task"
-
-# Cloud collaboration or no local environment
-codebuddy --sandbox https://api.e2b.dev "Cloud development"
-
-# Connect to remotely deployed sandbox service
-codebuddy --teleport session_abc123XYZ4567890 "Remote development"
-```
-
-### 2. Project Isolation
-
-```bash
-cd ~/work/projectA
-codebuddy --sandbox "Develop feature X"
-
-cd ~/work/projectB
-codebuddy --sandbox "Fix bug Y"
-```
-
-### 3. Long-term Development
-
-```bash
-# Day one
-codebuddy --sandbox "Set up development environment"
-
-# Day two - instant startup, environment preserved
-codebuddy --sandbox "Continue development"
-```
-
-### 4. Temporary Tasks
-
-Use `--sandbox-kill` for automatic cleanup:
-
-```bash
-codebuddy --sandbox --sandbox-kill "Quickly test an idea"
-```
-
-### 5. Regular Cleanup
-
-```bash
-# View all sandboxes
-codebuddy sandbox list
-
-# Clean up invalid ones
-codebuddy sandbox clean
-
-# Manually terminate specific sandbox
-codebuddy sandbox kill sb_old123
-```
-
-## ⚠️ Important Notes
-
-### Container Sandbox
-
-- **Mount Mode**: Container sandbox automatically mounts current directory, file changes sync in real-time
-- **Network Isolation**: Docker container is isolated from host network
-- **Resource Limits**: Subject to Docker configuration limits
-
-### E2B Sandbox
-
-- **Upload Delay**: Initial project upload takes time, more files means slower upload
-- **File Sync**: Automatic sync not supported, requires re-upload or manual sync
-- **Cost**: E2B cloud service may incur charges, check official pricing
-- **Timeout**: Sandboxes have maximum runtime limits (default: 1 hour)
-
-### Interactive Commands
-
-Both E2B and Container support interactive PTY:
-
-```bash
-codebuddy --sandbox "Edit main.py with vim"
-codebuddy --sandbox "Run htop to view processes"
-```
-
-## 🔧 Troubleshooting
-
-### Docker Not Running
-
-```bash
-Error: Neither Docker nor Podman is available
-```
-**Solution**: Start Docker Desktop or Podman
-
-### E2B API Key Missing
-
-```bash
-Error: E2B_API_KEY environment variable is required
-```
-**Solution**: `export E2B_API_KEY=your_key_here`
-
-### Sandbox Connection Failed
-
-```bash
-Failed to connect to sandbox sb_abc123
-```
-**Solution**: Sandbox may have expired, use `--sandbox-new` to create a new one
-
-### View Debug Logs
-
-```bash
-codebuddy --sandbox --debug "Test command"
-```
-
-## 📚 Related Documentation
-
-- [CLI Reference](./cli-reference.md) - Complete command-line parameter documentation
-- [E2B Official Documentation](https://e2b.dev/docs) - E2B cloud service documentation