FastGPT/deploy/helm/opensandbox/examples/DIRECTORY_STRUCTURE.md

# Examples 目录结构

本文档说明 `examples/` 目录的组织结构和设计原则。

## 📂 目录结构

```
examples/
├── README.md                          # 主文档：快速开始、最佳实践
├── DIRECTORY_STRUCTURE.md             # 本文档：目录结构说明
├── pool-examples.md                   # 详细的 Pool 配置说明
│
├── pool-agent-production.yaml         # 🌟 生产级 Agent Pool（推荐）
├── pool-sdk-compatible.yaml           # SDK 基础 Pool（execd only）
├── pool-sdk-with-tasks.yaml           # SDK 完整 Pool（execd + task-executor）
│
├── batchsandbox-basic.yaml            # Non-pooled 模式示例
└── batchsandbox-with-tasks.yaml       # Pooled 批量任务示例
```

## 📝 文件分类

### Pool 配置文件（3 个）

| 文件 | 类型 | SDK 支持 | 自定义 entrypoint | 推荐度 |
|------|------|----------|-----------------|--------|
| `pool-agent-production.yaml` | 生产级 | ✅ | ✅ | ⭐⭐⭐⭐⭐ |
| `pool-sdk-with-tasks.yaml` | 完整功能 | ✅ | ✅ | ⭐⭐⭐⭐ |
| `pool-sdk-compatible.yaml` | 基础功能 | ✅ | ❌ | ⭐⭐⭐ |

**选择建议**：
- **生产环境**：使用 `pool-agent-production.yaml`（包含详细注释和最佳实践）
- **快速测试**：使用 `pool-sdk-with-tasks.yaml`（更简洁）
- **特殊需求**：如果不需要自定义 entrypoint，使用 `pool-sdk-compatible.yaml`

### BatchSandbox 配置文件（2 个）

| 文件 | 模式 | 依赖 | 用途 |
|------|------|------|------|
| `batchsandbox-basic.yaml` | Non-pooled | 无 | 演示直接创建 Pod |
| `batchsandbox-with-tasks.yaml` | Pooled | Pool | 演示批量异构任务 |

**使用说明**：
- **SDK 场景**：通常不需要手动创建 BatchSandbox（SDK 自动创建）
- **kubectl 场景**：用于批量任务执行（RL 训练、压力测试等）

### 文档文件（3 个）

| 文件 | 内容 | 面向用户 |
|------|------|---------|
| `README.md` | 快速开始、最佳实践、故障排查 | 所有用户 |
| `pool-examples.md` | Pool 详细配置说明 | 高级用户 |
| `DIRECTORY_STRUCTURE.md` | 目录结构说明 | 开发者 |

## 🎯 设计原则

### 1. 简化选择

**问题**：之前有太多相似的示例（pool-basic, pool-with-execd, pool-with-task-executor...），用户不知道选哪个。

**解决**：
- 保留 3 个 Pool 示例，明确分类和推荐度
- 删除误导性示例（pool-basic 无 execd，pool-with-task-executor 无 execd）
- 突出推荐 `pool-agent-production.yaml`

### 2. 面向实际场景

**问题**：示例文件缺乏实际使用场景说明。

**解决**：
- 明确标注适用场景（Agent 服务、RL 训练、压力测试等）
- 提供完整的 SDK 使用代码示例
- 包含部署、验证、监控的完整流程

### 3. 最佳实践优先

**问题**：缺少生产级配置参考。

**解决**：
- 创建 `pool-agent-production.yaml` 包含：
  - 详细的配置注释
  - 容量规划建议
  - 安全最佳实践
  - 监控和调试指南

### 4. 纠正常见误区

**问题**：用户容易误解 Pool 的使用方式。

**解决**：
- 在 README.md 中突出"常见误区"章节
- 明确说明：
  - Pool 是 Pod 池，不是 Sandbox 池
  - 不需要预创建 BatchSandbox
  - SDK 每次 create() 创建新 BatchSandbox

## 🔄 文件变更历史

### 删除的文件（4 个）

| 文件 | 删除原因 |
|------|---------|
| `pool-basic.yaml` | 无 execd，SDK 无法使用，误导性 |
| `pool-with-task-executor.yaml` | 只有 task-executor 无 execd，不完整 |
| `pool-with-execd.yaml` | execd 启动方式不标准，已被 pool-sdk-compatible.yaml 替代 |
| `batchsandbox-pooled.yaml` | 依赖不存在的 basic-pool，无效 |

### 新增的文件（1 个）

| 文件 | 内容 |
|------|------|
| `pool-agent-production.yaml` | 生产级 Agent Pool 配置，包含详细注释和最佳实践 |

### 修改的文件（3 个）

| 文件 | 修改内容 |
|------|---------|
| `README.md` | 重写，添加场景分类、常见误区、容量规划等 |
| `batchsandbox-with-tasks.yaml` | 修改 poolRef 为 agent-pool，添加注释 |
| `batchsandbox-basic.yaml` | 添加详细注释说明 |

## 📊 使用场景映射

### 场景 A：多 Agent 并发使用

```
用户需求: Agent 服务、Code Interpreter、动态工作流
      ↓
推荐配置: pool-agent-production.yaml
      ↓
  使用方式: SDK 动态创建 sandbox
      ↓
    流程: Helm 部署 Pool → SDK.create() → SDK.kill()
```

### 场景 B：批量任务执行

```
用户需求: RL 训练、压力测试、批量数据处理
      ↓
推荐配置: pool-agent-production.yaml + batchsandbox-with-tasks.yaml
      ↓
  使用方式: kubectl 创建 BatchSandbox
      ↓
    流程: kubectl apply pool → kubectl apply batchsandbox → 自动清理
```

### 场景 C：测试和开发

```
用户需求: 测试特定镜像、验证功能
      ↓
推荐配置: batchsandbox-basic.yaml (non-pooled)
      ↓
  使用方式: kubectl 直接创建
      ↓
    流程: kubectl apply → kubectl delete
```

## 🔗 相关资源

- **深度分析**：`/data/home/cz/sandbox-test/pool-analysis/`
  - Pool 使用指南
  - 架构流程图
  - 验证测试脚本

- **Helm 配置**：`/data/home/cz/OpenSandbox/kubernetes/helm-chart/`
  - `values.yaml` - 默认配置
  - `values-e2e.yaml` - E2E 测试配置
  - 生产/开发环境配置：使用 `--set` 或自定义 values 文件

- **主文档**：`/data/home/cz/OpenSandbox/kubernetes/README.md`
  - Kubernetes 部署完整指南

## 💡 维护建议

### 添加新示例时

1. **明确场景**：每个示例应对应明确的使用场景
2. **完整注释**：包含配置说明、使用方式、注意事项
3. **验证测试**：确保示例可以正常运行
4. **更新文档**：同步更新 README.md 和本文档

### 修改现有示例时

1. **保持兼容**：避免破坏性变更
2. **版本说明**：在注释中说明版本要求
3. **测试验证**：修改后进行完整测试
4. **文档同步**：更新相关文档

### 删除示例时

1. **评估影响**：确认没有外部依赖
2. **提供替代**：在文档中说明替代方案
3. **迁移指南**：如果有用户使用，提供迁移步骤