# ASDM Bootstrapper CLI 离线包打包指南

本文档详细说明如何将 `asdm-bootstrapper-cli` 项目打包成离线可用的 CLI 工具包。

## 项目结构分析

当前项目具备完善的 CLI 工具基础：
- **技术栈**: TypeScript + Node.js
- **构建工具**: TypeScript Compiler (tsc)
- **入口文件**: `src/index.ts` (shebang: `#!/usr/bin/env node`)
- **包配置**: 已配置 `bin` 字段支持 `asdm` 和 `asdm-bootstrapper` 命令

## 打包方案

### 方案一：标准 npm 包（推荐）

这是最标准的方式，使用 npm 内置的打包功能：

```bash
# 进入项目目录
cd asdm-bootstrapper-cli

# 构建并打包
npm run package
```

这会生成一个 `.tgz` 文件，如：`asdm-bootstrapper-cli-0.1.2.tgz`

**用户安装方式：**
```bash
npm install -g asdm-bootstrapper-cli-0.1.2.tgz
```

**优点：**
- 标准 npm 包格式
- 自动处理依赖关系
- 支持版本管理
- 便于分发和安装

### 方案二：增强版离线包

提供更好的用户体验和完整的安装脚本：

```bash
# 构建增强版离线包
npm run package-offline
```

这会生成包含以下内容的完整包：
- 编译后的 JavaScript 代码
- 类型定义文件 (.d.ts)
- 源码映射文件 (.map)
- 跨平台安装脚本 (Linux/Mac & Windows)
- 完整的项目文档

**生成的文件：**
- `asdm-bootstrapper-cli-0.1.2-offline.tgz` - 主包文件
- 自动创建 `dist-offline/` 目录包含安装脚本

**用户安装方式：**
1. **使用安装脚本（推荐）：**
   ```bash
   # Linux/Mac
   ./install.sh
   
   # Windows
   install.bat
   ```

2. **手动安装：**
   ```bash
   npm install -g asdm-bootstrapper-cli-0.1.2-offline.tgz
   ```

## 打包流程详解

### 1. 代码编译
使用 TypeScript Compiler 将 TypeScript 代码编译为 JavaScript：
```bash
npm run build
```

### 2. 包内容组织
打包包含以下关键文件：

```
asdm-bootstrapper-cli/
├── dist/                 # 编译后的代码
│   ├── index.js         # 入口文件
│   ├── index.d.ts       # 类型定义
│   └── ...              # 其他模块
├── package.json         # 包配置信息
├── README.md           # 使用说明
├── LICENSE             # 许可证
├── install.sh          # Linux/Mac 安装脚本
└── install.bat         # Windows 安装脚本
```

### 3. 依赖处理
包内不包含 `node_modules`，安装时自动从 npm registry 下载依赖。

## 用户使用说明

### 前置要求
- Node.js (推荐 v16+)
- npm (推荐 v8+)

### 安装步骤

1. **下载离线包文件**
2. **执行安装命令**
   ```bash
   npm install -g <package-file>.tgz
   ```
3. **验证安装**
   ```bash
   asdm --version
   asdm --help
   ```

### 常用命令

```bash
# 查看帮助
asdm --help

# 配置管理
asdm config init
asdm config --set-base-url <url>

# 工具集管理
asdm toolset list
asdm toolset install <toolset-id>

# 工作区管理
asdm workspace list <workspace-id>
```

## 分发策略

### 1. 文件分发
- 分发单个 `.tgz` 文件
- 文件大小约 50-100KB（不包含依赖）

### 2. 安装前置检查
安装脚本会自动检查：
- Node.js 是否安装
- npm 是否可用
- 权限是否足够

### 3. 网络要求
- 安装时需要联网下载依赖
- 运行时支持离线模式（通过 mock 配置）

## 特殊配置

### Mock 模式
支持完全离线运行：
```bash
asdm config --set-mock y
asdm toolset install <toolset-id>  # 从本地 mock 目录安装
```

### 自定义配置
用户可以通过配置文件自定义：
- API 端点地址
- 下载镜像源
- 语言设置

## 维护说明

### 版本更新
1. 更新 `package.json` 中的版本号
2. 重新打包
3. 分发新版本包文件

### 依赖更新
如果需要更新依赖：
1. 更新 `package.json`
2. 重新构建和打包
3. 用户重新安装即可获得最新依赖

## 故障排除

### 常见问题

1. **安装失败**
   - 检查 Node.js 版本
   - 检查网络连接
   - 检查文件完整性

2. **命令不存在**
   - 检查全局安装路径
   - 重新安装包

3. **权限问题**
   - 使用 sudo (Linux/Mac)
   - 以管理员身份运行 (Windows)

## 总结

`asdm-bootstrapper-cli` 项目已经具备完善的离线打包能力，支持：

✅ **标准 npm 包格式** - 兼容所有 npm 生态
✅ **跨平台支持** - Linux, macOS, Windows
✅ **离线运行** - 通过 mock 模式支持完全离线
✅ **用户友好** - 提供安装脚本和完整文档
✅ **易于维护** - 标准化的构建和分发流程

推荐使用 `npm run package-offline` 命令构建增强版离线包，提供最佳的用户体验。