JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 35
  • Score
    100M100P100Q58129F
  • License MIT

CLI for managing agentsphere sandbox templates

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (agentsphere-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    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 操作性能

    版本管理

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