@tencent-ai/agent-sdk 0.3.99 → 0.3.101

package/cli/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 云服务文档

package/cli/dist/web-ui/docs/cn/cli/scheduled-tasks.md

@@ -0,0 +1,161 @@
+# 定时任务
+
+CodeBuddy Code 支持在会话中创建和管理定时任务，可以按照设定的时间表重复执行指令，或者在未来某个时间点触发一次性操作。常见用途包括：定期检查构建状态、轮询任务完成情况、在特定时间点提醒自己等。
+
+> **注意**：定时任务是会话级别的。任务只在 CodeBuddy Code 运行期间有效，退出后自动清除。
+
+
+## 创建一次性提醒
+
+如果只需要在未来某个时间点提醒一次，可以直接用自然语言描述：
+
+```
+下午四点半提醒我同步一下今天的进展
+```
+
+```
+一个小时后看看刚才那个构建任务有没有产出
+```
+
+```
+明天早上 9 点帮我生成一份昨天的工作日报
+```
+
+这类任务会在指定时间触发一次，执行完毕后自动删除。
+
+---
+
+## 管理已有任务
+
+### 查看当前所有任务
+
+```
+我现在有哪些定时任务？
+```
+
+列表中包含任务 ID、执行频率、任务类型（循环 / 一次性）以及对应的指令。
+
+### 取消任务
+
+```
+取消部署检查的定时任务
+```
+
+或者通过任务 ID 取消：
+
+```
+帮我删掉 ID 为 xxx 的定时任务
+```
+
+底层分别对应 `CronList` 和 `CronDelete` 工具，可以通过对话直接操作，无需记住具体命令。
+
+---
+
+## 任务执行机制
+
+### 执行时机
+
+任务只会在会话**空闲**时触发，即系统没有在处理其他请求的时候。如果正好在执行某个操作，触发时间会顺延到操作完成后。
+
+### 时间偏移（Jitter）
+
+系统会对任务的触发时间添加少量随机偏移，以避免大量任务同时执行带来的拥堵：
+
+- **循环任务**：最多延迟周期时长的 10%（上限 15 分钟）
+- **一次性任务**：对于整点和半点任务，最多提前 90 秒执行
+
+例如，设置 `每小时` 执行的任务，实际触发时间可能在整点后的 0-6 分钟内随机分布。
+
+### 自动过期
+
+**循环任务在创建 3 天后自动过期删除**，过期前会最后触发一次。  
+如果需要任务持续更长时间，可以在过期后重新创建，或者改用外部调度方案（如 GitHub Actions 等）。
+
+---
+
+## Cron 表达式参考
+
+
+需要「每周一早上 10 点」「每月 1 号」这类精确时间，直接告诉 AI 你的需求，它会自动转成 cron 表达式并创建任务：
+
+```
+每周一早上 10 点帮我生成本周的工作计划
+```
+
+```
+每月 1 号早上统计上个月的代码提交量，按人汇总
+```
+
+```
+每周五下午 5:30 提醒我同步进度、更新任务状态
+```
+
+```
+每天中午 12 点检查一下有没有待我审查的 PR
+```
+
+```
+工作日早上 9:15 把昨天未合并的 PR 列出来
+```
+
+AI 回复时会告诉你实际使用的 cron 表达式和执行频率，方便确认是否符合预期。
+
+**格式：**
+```
+分钟  小时  日期  月份  周几
+```
+
+**常用表达式：**
+
+| 表达式 | 含义 |
+|--------|------|
+| `*/5 * * * *` | 每 5 分钟 |
+| `*/15 * * * *` | 每 15 分钟 |
+| `0 * * * *` | 每小时整点 |
+| `0 9 * * *` | 每天上午 9 点 |
+| `0 9 * * 1-5` | 工作日上午 9 点 |
+| `0 0 1 * *` | 每月 1 日午夜 |
+| `30 18 * * 5` | 每周五下午 6:30 |
+
+**字段说明：**
+
+| 字段 | 取值范围 | 特殊符号 |
+|------|---------|---------|
+| 分钟 | 0–59 | `*`（任意）、`*/N`（每 N 分钟）、`N,M`（列举）、`N-M`（范围）|
+| 小时 | 0–23 | 同上 |
+| 日期 | 1–31 | 同上 |
+| 月份 | 1–12 | 同上 |
+| 周几 | 0–6 | 0 或 7 = 周日，1 = 周一，依此类推 |
+
+---
+
+## 注意事项
+
+| 事项 | 说明 |
+|------|------|
+| **会话绑定** | 任务随会话存在，CodeBuddy Code 退出后任务消失，不会写入磁盘 |
+| **循环任务上限** | 每个会话最多同时存在 50 个定时任务 |
+| **最小间隔** | 1 分钟（秒级设置会被自动向上取整） |
+| **任务过期** | 循环任务 3 天后自动清除 |
+| **不补跑** | 会话中断期间错过的任务不会补发执行 |
+
+---
+
+## 禁用定时任务
+
+如果需要完全关闭定时任务功能，可以设置环境变量：
+
+```bash
+CODEBUDDY_DISABLE_CRON=1 codebuddy
+```
+
+启用后，`/loop` 技能不再可用，`CronCreate`、`CronList`、`CronDelete` 工具也会被禁用。
+
+---
+
+## 相关文档
+
+- [技能系统](./skills.md)
+- [斜杠命令参考](./slash-commands.md)
+- [会话与上下文管理](./cli-reference.md)
+- [Hooks 事件系统](./hooks.md)