@tencent-ai/codebuddy-code 2.67.0 → 2.68.0-next.19b562c.20260330

package/dist/web-ui/docs/cn/cli/release-notes/v2.8.0.md

@@ -0,0 +1,18 @@
+# 🚀 CodeBuddy Code v2.8.0 发布
+
+## ✨ 新功能
+
+- 编辑器原生集成：支持通过 ACP 协议与 Zed 等编辑器深度集成，带来更流畅的 AI 辅助开发体验
+- 智能安全防护：引入五级命令风险分级系统，覆盖文件操作、Git 管理、容器控制等 9 大类场景，高风险操作自动拦截确认，让 AI 自动化更安心
+
+## 🔧 改进优化
+
+- 危险操作智能识别：优化风险评估策略，自动识别可能丢失数据的 Git 操作并提升风险等级，主分支保护更严格
+- 安全模式增强：改进权限绕过模式的安全检查，交互场景下极高风险操作仍需确认，兼顾自动化与安全
+- 视觉提示升级：高风险命令确认界面使用警告色高亮，一眼识别潜在危险操作
+- 文档解析效率提升：优化 Markdown 文件处理性能，加载速度更快
+
+## 🐛 问题修复
+
+- 安全审批机制加固：修复高风险命令可能跳过确认的漏洞，确保所有危险操作都经过用户授权
+- 提示模板优化：消除系统提示中的重复内容，提升 AI 响应的准确性

package/dist/web-ui/docs/cn/cli/release-notes/v2.8.1.md

@@ -0,0 +1,17 @@
+# 🚀 CodeBuddy Code v2.8.1 发布
+
+## 🔧 改进优化
+
+- **Plan 模式重构**：采用全新的 Sub-Agent 架构重构 Plan 模式，提供更智能、更稳定的任务规划和执行能力
+- **智能模型图片检测**：自动检测模型图片支持能力，在模型不支持时智能处理图片输入，提升跨模型使用的流畅度
+- **运行环境健康检查**：启动时自动检测 Node.js 版本，提前规避环境兼容性问题，确保工具稳定运行
+- **ACP 协议体验增强**：创建会话时自动推送命令列表，支持智能补全；优化认证方式，根据网络环境自动推荐最佳登录选项
+- **权限命令风险调整**：优化 sudo/su 等提权命令的风险分级策略，减少不必要的二次确认，在保障安全的前提下提升效率
+
+## 🐛 问题修复
+
+- **Git 操作安全增强**：优化危险命令检测规则，更精准地识别和拦截强制推送、删除分支等高风险 Git 操作
+- **Windows 路径兼容**：修复 Windows 系统下的路径大小写敏感问题，提升跨平台文件操作的稳定性
+- **非交互模式工具控制**：修复用户问答工具在非交互模式下的行为逻辑，确保自动化流程顺畅执行
+- **专享版环境适配**：修复专享版环境识别异常，确保配置加载的正确性
+- **剪贴板检测兼容性**：临时调整剪贴板检测策略，解决部分环境下的误触发问题，提升使用体验

package/dist/web-ui/docs/cn/cli/release-notes/v2.8.2.md

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.8.2 发布
+
+## 🔧 改进优化
+
+- **对话上下文增强**：改进对话消息处理机制，确保完整的上下文信息在多轮对话中正确保留和传递，提升 AI 响应的连贯性和准确性

package/dist/web-ui/docs/cn/cli/release-notes/v2.8.3.md

@@ -0,0 +1,14 @@
+# 🚀 CodeBuddy Code v2.8.3 发布
+
+## 🔧 改进优化
+
+- **Gemini 模型支持扩展**：新增 Gemini-3.0-Pro 模型支持，为你提供更强大的推理能力和更大的上下文窗口，胜任更复杂的编程任务
+- **文件处理智能优化**：自动识别并跳过超大文件的引用处理，有效避免性能问题，提升大型项目的响应速度
+- **代码架构稳定性增强**：优化中间件依赖注入机制、服务初始化流程和会话类型定义，提升系统运行稳定性和代码维护性
+- **会话管理体验提升**：改进会话恢复面板的数据处理逻辑，提供更流畅的会话管理体验
+- **权限控制可靠性**：完善目录信任状态管理，让权限控制更精准、更可靠
+
+## 🐛 问题修复
+
+- **远程执行环境连接稳定性**：优化认证令牌处理机制，提升连接沙箱和远程执行环境时的稳定性
+- **Shell 命令兼容性**：改进命令执行环境，支持需要终端交互的工具命令，提升各类命令的执行成功率

package/dist/web-ui/docs/cn/cli/release-notes/v2.8.4.md

@@ -0,0 +1,9 @@
+# 🚀 CodeBuddy Code v2.8.4 发布
+
+## 🔧 改进优化
+
+- 类型定义优化：改进代码组织结构，提升长期维护效率
+
+## 🐛 问题修复
+
+- 权限模式同步：修复子任务执行时权限设置未能正确应用的问题，确保批量操作权限控制的一致性

package/dist/web-ui/docs/cn/cli/release-notes/v2.8.5.md

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.8.5 发布
+
+## 📚 文档增强
+
+- GitLab CI/CD 集成指南：新增完整的 CI/CD 集成文档，帮助您在 GitLab 流水线中轻松使用 CodeBuddy Code，包含详细的配置示例、使用场景说明和常见问题解决方案

package/dist/web-ui/docs/cn/cli/release-notes/v2.8.6.md

@@ -0,0 +1,14 @@
+# 🚀 CodeBuddy Code v2.8.6 发布
+
+## 🔧 改进优化
+
+- 终端输入处理增强：改进跨平台输入解析机制，提升终端使用的稳定性和兼容性
+- 粘贴体验优化：完善大段文本粘贴处理，自动识别粘贴模式，提升文本输入便捷性
+- 消息处理机制优化：重构内部消息队列，提升对话响应速度和系统稳定性
+- 界面渲染性能提升：优化应用主界面和聊天视图的渲染效率，提供更流畅的交互体验
+- 命令执行流程简化：优化终端命令执行逻辑，提升执行效率
+
+## 🐛 问题修复
+
+- 协议模式配置保持：修复客户端协议模式下多轮会话中配置丢失的问题，确保会话稳定性
+- tmux 剪贴板粘贴：修复在 tmux 终端环境中无法粘贴剪贴板图片的问题

package/dist/web-ui/docs/cn/cli/release-notes/v2.9.0.md

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.9.0 发布
+
+## ✨ 新功能
+
+- 认证成功通知：新增用户登录成功后的 Hook 通知事件，支持在认证完成时触发自定义脚本，实现登录后的自动化工作流

package/dist/web-ui/docs/cn/cli/remote-control.md

@@ -0,0 +1,247 @@
+# 远程控制（Remote Control）
+
+> **Beta**：远程控制功能目前处于 Beta 阶段，功能和接口可能会在后续版本中发生变化。欢迎试用并反馈问题。
+
+通过 Remote Control，您可以从手机、平板或任意浏览器远程访问本地运行的 CodeBuddy Code 会话。会话始终在您的本机执行，Web 界面只是一个远程窗口。
+
+## 概述
+
+Remote Control 在本地启动一个 Gateway 服务，通过 Cloudflare Tunnel 或局域网暴露一个 Web UI，让您可以从任何设备连接到正在运行的 CodeBuddy Code 会话。
+
+使用 Remote Control，您可以：
+
+- **远程使用完整的本地环境**：文件系统、MCP 服务器、工具配置全部保持可用
+- **通过 Web UI 与 Agent 交互**：在浏览器中发送消息、查看对话、监控工具执行
+- **从多设备接入**：手机扫码即可连接，支持局域网和公网访问
+- **通过终端管理会话**：在终端和 Web 端同时工作，对话保持同步
+
+## 前置条件
+
+- 已安装并登录 CodeBuddy Code（运行 `codebuddy` 后使用 `/login` 登录）
+- 若需要公网访问，需安装 [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)（可选）
+
+## 启动远程控制
+
+在 CodeBuddy Code 会话中使用 `/gateway` 命令启动远程控制服务：
+
+```
+/gateway
+```
+
+启动成功后，终端会显示连接信息：
+
+```
+Gateway started
+
+  ├─ Status   connected
+  ├─ Mode     tunnel
+  ├─ Local    http://127.0.0.1:8321
+  ├─ Tunnel   https://xxx-xxx-xxx.trycloudflare.com
+  ├─ Web UI   https://xxx-xxx-xxx.trycloudflare.com/?password=<token>
+  └─ Webhook  https://xxx-xxx-xxx.trycloudflare.com/gateway/webhook/:platform
+
+  Scan to open Web UI:
+
+  [QR Code]
+```
+
+### 连接方式
+
+Gateway 启动后，有以下几种方式从其他设备连接：
+
+- **扫描二维码**：用手机扫描终端中显示的二维码，直接打开 Web UI
+- **复制 Web UI 链接**：将带有认证 token 的 URL 在任意浏览器中打开
+- **局域网访问**：同一网络中的设备可直接访问 Local 地址（如 `http://10.x.x.x:8321`）
+
+### 子命令
+
+| 命令 | 说明 |
+|:-----|:-----|
+| `/gateway` | 启动 Gateway（默认带 Tunnel） |
+| `/gateway status` | 查看当前 Gateway 状态 |
+| `/gateway stop` | 停止 Gateway |
+| `/gateway token` | 重新生成认证 token |
+| `/gateway tunnel` | 启动带 Tunnel 的 Gateway |
+
+## 网络模式
+
+Gateway 支持两种网络模式，适应不同的使用场景：
+
+### Tunnel 模式（默认）
+
+通过 Cloudflare Quick Tunnel 自动分配一个临时公网域名（`*.trycloudflare.com`），无需任何额外配置即可从公网访问。
+
+适用场景：
+- 从外部网络（如手机移动网络）远程访问
+- 不想配置端口转发或 VPN
+
+需要安装 `cloudflared`：
+
+```bash
+# macOS
+brew install cloudflared
+
+# Debian/Ubuntu
+curl -L https://pkg.cloudflare.com/cloudflared-stable-linux-amd64.deb -o cloudflared.deb
+sudo dpkg -i cloudflared.deb
+
+# Windows
+winget install Cloudflare.cloudflared
+```
+
+### 局域网模式
+
+当 `cloudflared` 未安装或 Tunnel 启动失败时，Gateway 自动回退到局域网模式。此模式下，仅同一网络中的设备可以访问。
+
+- 默认监听端口：`8321`
+- 监听地址：`0.0.0.0`（所有网络接口）
+
+## 安全机制
+
+### 认证
+
+Gateway 启动时会自动生成一个随机密码（token），访问 Web UI 和 API 均需要通过认证。支持以下认证方式：
+
+| 方式 | 说明 |
+|:-----|:-----|
+| URL 参数 | `?password=<token>`，适合快速分享链接 |
+| Cookie | 登录后自动设置，后续访问无需重复认证 |
+| Bearer Token | `Authorization: Bearer <token>`，适合 API 调用 |
+
+密码可通过 `/gateway token` 命令重新生成。重新生成后，之前的密码立即失效。
+
+### 登录限流
+
+为防止暴力破解，认证中间件内置了登录限流机制：
+
+- 每分钟最多允许 2 次失败尝试
+- 每小时额外允许 12 次失败尝试
+- 超出限制后将暂时拒绝登录请求
+
+### 权限
+
+通过远程控制执行的任务自动以 `bypassPermissions` 模式运行，即工具执行不需要逐一审批。这是因为远程场景下无法进行交互式审批。请确保仅将访问链接分享给受信任的人。
+
+### CORS 策略
+
+Gateway 默认允许以下来源的跨域请求：
+
+- 本地回环地址（`localhost`、`127.0.0.1`、`[::1]`）
+- Tunnel 分配的公网地址
+- 通过 `gateway.corsOrigins` 配置的额外来源
+
+## Web UI
+
+Web UI 提供了完整的 CodeBuddy Code 交互界面，包括：
+
+- **对话界面**：发送消息、查看 Agent 回复、监控工具调用
+- **终端面板**：内置 Web 终端，直接在浏览器中操作远程终端
+- **实例管理**：查看和管理多个 CodeBuddy Code 实例
+- **主题切换**：支持亮色/暗色主题
+- **多语言**：支持中英文界面切换
+
+Web UI 基于 ACP（Agent Client Protocol）与本地 Agent 通信，保证了与终端交互完全一致的体验。
+
+## 配置
+
+### Settings 配置
+
+在 `~/.codebuddy/settings.json` 中可以配置 Gateway 相关选项：
+
+```json
+{
+  "gateway": {
+    "auth": "password",
+    "password": "your-custom-password",
+    "corsOrigins": ["https://your-domain.com"],
+    "maxConnections": 5,
+    "tokenTtlMs": 86400000
+  }
+}
+```
+
+| 配置键 | 说明 | 默认值 |
+|:------|:-----|:------|
+| `auth` | 认证模式，`"password"` 或 `"none"` | `"none"` |
+| `password` | 自定义密码。为空时首次启动自动生成 | 自动生成 |
+| `corsOrigins` | 额外允许的 CORS 来源列表 | `[]` |
+| `maxConnections` | ACP 最大并发连接数 | `5` |
+| `tokenTtlMs` | ACP Session Token 有效期（毫秒） | `86400000`（24 小时） |
+
+### 环境变量
+
+| 环境变量 | 说明 |
+|:---------|:-----|
+| `CODEBUDDY_CORS_ORIGINS` | 额外的 CORS 允许来源（逗号分隔） |
+
+## 实例管理
+
+当您在多个项目目录中运行 CodeBuddy Code 时，每个实例会自动注册到本地实例注册表（`~/.codebuddy/instances.json`）。Web UI 的实例管理面板可以查看所有活跃的实例，并在它们之间切换。
+
+实例信息包括：
+
+- 工作目录
+- 本地/Tunnel 地址
+- 操作系统和架构
+- 启动时间和运行状态
+
+## 第三方平台集成（Webhook）
+
+Gateway 提供了 Webhook 端点，支持接入企业通讯平台机器人：
+
+```
+{gateway-url}/gateway/webhook/:platform
+```
+
+支持的平台适配器：
+
+| 平台 | 标识 |
+|:-----|:-----|
+| 企业微信 | `wecom` |
+| 钉钉 | `dingtalk` |
+| 飞书 | `feishu` |
+| 通用 | `generic` |
+
+配置企业机器人的 Webhook 回调地址为上述端点后，即可通过企业通讯平台向 CodeBuddy Code 发送消息并接收回复。
+
+## 连接与安全
+
+- Gateway 仅在本地启动 HTTP 服务，不会在您的机器上打开入站端口
+- 公网访问通过 Cloudflare Tunnel 的出站连接实现
+- 所有 Tunnel 流量通过 Cloudflare 的 TLS 加密传输
+- 使用固定端口启动时，Quick Tunnel 域名可跨 CLI 重启保持不变（参见[保持 Tunnel 域名稳定](#保持-tunnel-域名稳定)）
+
+## 限制
+
+- **每个会话一个 Gateway**：每个 CodeBuddy Code 实例同时只支持一个 Gateway 服务
+- **终端需保持运行**：Gateway 作为本地进程运行。关闭终端或停止 CodeBuddy Code 进程后，远程连接会断开。使用 `/gateway` 重新启动
+- **Quick Tunnel 域名临时性**：Quick Tunnel 域名在 cloudflared 进程存活期间保持不变。使用固定端口启动可以跨 CLI 重启复用 cloudflared 进程（参见[保持 Tunnel 域名稳定](#保持-tunnel-域名稳定)）。如果 cloudflared 进程退出（如机器重启），域名将重新分配。如需永久固定域名，可使用 Named Tunnel（需要 Cloudflare 账号）
+- **局域网模式限制**：未安装 `cloudflared` 时仅限同一网络内的设备访问
+
+## 保持 Tunnel 域名稳定
+
+Quick Tunnel 默认每次启动 cloudflared 都会分配一个新的随机域名。通过指定固定端口，可以让域名在多次 CLI 重启之间保持不变。
+
+### 使用固定端口
+
+使用 `--port` 参数指定固定端口启动 CLI：
+
+```bash
+codebuddy --port 8321
+```
+
+这样每次启动都使用相同端口，`/gateway` 会自动复用上一次的 cloudflared 进程和域名。
+
+> 如果不指定 `--port`，系统会随机分配端口，每次端口不同导致无法匹配已有的 cloudflared 进程。
+
+### 停止 Tunnel
+
+执行 `/gateway stop` 会终止 cloudflared 进程并清理状态。下次启动将分配新域名。
+
+如果只是退出 CLI（Ctrl+C 或 `/exit`），cloudflared 进程会继续运行，等待下次 CLI 启动时复用。
+
+## 相关文档
+
+- [设置配置](settings.md)：配置 Gateway 相关选项
+- [Hooks](hooks.md)：配置工具执行前后的自定义命令
+- [权限管理](iam.md)：了解权限模式和规则

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

@@ -0,0 +1,316 @@
+# 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 云服务文档