AgentSphere CLI 项目交接文档

项目概述

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

项目背景

这是一个用于管理 AgentSphere 沙箱模板的 CLI 工具，允许用户创建、构建、发布和管理沙箱环境。该项目是基于 agentsphere 平台的定制化版本，专门用于 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 镜像构建和推送
• 模板配置管理 (agentsphere.toml)
• 构建状态监控和日志输出

4. API 客户端 (src/api.ts)

统一的 API 请求处理和认证管理。

关键功能:

• AgentSphere API 客户端初始化
• 认证令牌管理和验证
• 错误处理和重试机制

重要配置文件

1. 用户配置

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

2. 项目配置 (agentsphere.toml)

• 位置: 项目根目录
• 内容: 模板 ID, 名称, 启动命令, 资源配置等
• 管理: 通过 src/config/ 模块

3. Docker 配置

• 支持文件: agentsphere.Dockerfile 或 Dockerfile
• 用途: 定义沙箱环境的构建配置

开发流程

环境设置

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 代码检查
npm run lint

构建和发布

# 构建生产版本
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 客户端
• agentsphere: agentsphere 平台 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 操作性能

版本管理

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