# AgentSphere CLI 项目交接文档

## 项目概述

**项目名称**: `agentsphere-cli`  
**版本**: 1.0.4  
**描述**: AgentSphere 沙箱模板管理的命令行工具  
**官网**: https://www.agentsphere.run/home  
**许可证**: MIT  

### 项目背景
这是一个用于管理 AgentSphere 沙箱模板的 CLI 工具，允许用户创建、构建、发布和管理沙箱环境。该项目是基于 E2B 平台的定制化版本，专门用于 AI 代理的沙箱环境管理。

## 项目架构

### 目录结构
```
agentSphere-cli/
├── src/                    # 源代码目录
│   ├── commands/          # 命令实现
│   │   ├── auth/         # 认证相关命令
│   │   ├── sandbox/      # 沙箱操作命令
│   │   └── template/     # 模板管理命令
│   ├── config/           # 配置管理
│   ├── docker/           # Docker 相关常量
│   ├── utils/            # 工具函数
│   ├── api.ts            # API 客户端配置
│   ├── index.ts          # 程序入口
│   ├── terminal.ts       # 终端交互
│   └── user.ts           # 用户配置管理
├── dist/                  # 编译输出目录
├── testground/           # 测试目录
├── scripts/              # 构建脚本
├── package.json          # 项目配置
└── README.md             # 项目文档
```

### 核心技术栈
- **运行环境**: Node.js >= 18
- **编程语言**: TypeScript
- **构建工具**: tsup
- **命令行框架**: Commander.js
- **HTTP客户端**: agentsphere-sandbox-base
- **UI组件**: boxen, chalk, inquirer
- **其他依赖**: Docker (运行时依赖)

## 主要功能模块

### 1. 认证模块 (`src/commands/auth/`)
负责用户身份认证和配置管理。

**核心文件:**
- `login.ts` - 用户登录
- `logout.ts` - 用户登出  
- `configure.ts` - 配置管理
- `info.ts` - 查看认证信息

**关键功能:**
- API Key 和 Access Token 管理
- 用户配置文件存储
- 团队配置管理

### 2. 沙箱模块 (`src/commands/sandbox/`)
管理运行中的沙箱实例。

**核心文件:**
- `spawn.ts` - 创建新沙箱
- `connect.ts` - 连接到现有沙箱 
- `list.ts` - 列出沙箱实例
- `kill.ts` - 终止沙箱
- `logs.ts` - 查看沙箱日志

**关键功能:**
- 沙箱生命周期管理
- 终端连接和交互
- 沙箱状态监控

### 3. 模板模块 (`src/commands/template/`)
管理沙箱模板的创建、构建和发布。

**核心文件:**
- `build.ts` - 构建模板 (关键文件，包含复杂的构建流程)
- `init.ts` - 初始化新模板
- `list.ts` - 列出模板
- `delete.ts` - 删除模板
- `publish.ts` - 发布/取消发布模板

**关键功能:**
- Docker 镜像构建和推送
- 模板配置管理 (e2b.toml)
- 构建状态监控和日志输出

### 4. API 客户端 (`src/api.ts`)
统一的 API 请求处理和认证管理。

**关键功能:**
- AgentSphere API 客户端初始化
- 认证令牌管理和验证
- 错误处理和重试机制

## 重要配置文件

### 1. 用户配置
- **位置**: 用户主目录的配置文件
- **内容**: API keys, access tokens, 团队信息
- **管理**: 通过 `src/user.ts` 模块

### 2. 项目配置 (e2b.toml)
- **位置**: 项目根目录
- **内容**: 模板 ID, 名称, 启动命令, 资源配置等
- **管理**: 通过 `src/config/` 模块

### 3. Docker 配置
- **支持文件**: `e2b.Dockerfile` 或 `Dockerfile`
- **用途**: 定义沙箱环境的构建配置

## 开发流程

### 环境设置
```bash
# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 代码检查
npm run lint
```

### 构建和发布
```bash
# 构建生产版本
npm run build

# 发布到 npm
npm publish
```

## 重要的业务逻辑

### 1. 模板构建流程 (`src/commands/template/build.ts:123-432`)
这是最复杂的业务逻辑，包含：
- 配置文件解析和验证
- Docker 镜像构建和推送
- 构建状态监控
- 错误处理和重试机制

### 2. 沙箱连接 (`src/commands/sandbox/connect.ts:31-51`)  
处理沙箱连接和终端交互：
- 沙箱 ID 标准化
- 终端会话建立
- 连接状态管理

### 3. 认证管理 (`src/api.ts:42-86`)
统一的认证验证和客户端配置：
- 多种认证方式支持
- 配置文件回退机制
- 错误提示和用户指导

## 外部依赖和集成

### 核心依赖
- `agentsphere-sandbox-base`: AgentSphere API 客户端
- `e2b`: E2B 平台 SDK  
- `commander`: CLI 框架
- `inquirer`: 交互式命令行
- `boxen`, `chalk`: 命令行 UI

### 运行时依赖
- **Docker**: 用于构建和推送镜像
- **网络连接**: API 调用和 Docker 注册表访问

### API 集成
- **AgentSphere API**: 主要的后端服务
- **Docker Registry**: 镜像存储和分发

## 常见问题和解决方案

### 1. 认证问题
- 确保正确配置 `AGENTSPHERE_API_KEY` 和 `AGENTSPHERE_ACCESS_TOKEN`
- 使用 `agentsphere auth login` 重新登录

### 2. 构建失败
- 检查 Docker 是否正确安装和运行
- 验证 Dockerfile 语法
- 检查网络连接和权限

### 3. 连接问题
- 验证沙箱 ID 格式
- 检查 API 密钥权限
- 确认沙箱状态为运行中

## 监控和维护

### 日志记录
- 构建过程详细日志输出
- API 请求错误处理
- 用户操作反馈

### 性能监控
- 构建时间监控
- API 响应时间
- Docker 操作性能

### 版本管理
- 遵循语义化版本控制
- 定期更新依赖包
- 向后兼容性考虑


