lightshortcuts 1.0.9 → 1.1.0

package/docs/README.md

@@ -0,0 +1,357 @@
+# LSC 命令行工具使用文档
+
+## 1. 命令概览
+
+LSC (Light Shortcuts) 是一个用于管理和发布离线包的命令行工具，提供了丰富的命令来简化开发和发布流程。
+
+| 命令 | 别名 | 描述 |
+|------|------|------|
+| `login` | - | 登录会话 |
+| `md5` | - | 获取MD5密码 |
+| `logout` | - | 注销会话 |
+| `use` | - | 设置当前发布版本 |
+| `config` | - | 交互式配置离线包发布参数 |
+| `init` | - | 快速初始化配置模板 |
+| `publish` | `p` | 发布离线包 |
+| `batch` | `b` | 批量发布离线包 |
+| `deal version` | - | 处理离线包兼容版本重叠 |
+| `clean all` | - | 批量处理离线包兼容版本重叠 |
+| `pwd` | `dir` | 打印当前地址 |
+| `zip` | - | 压缩目录为zip文件 |
+
+## 2. 命令详情
+
+### 2.1 `login` - 登录会话
+
+**描述**: 登录到指定环境的管控台会话。
+
+**选项**:
+- `-e, --env <type>`: 选择管控台的环境（可选）
+
+**使用示例**:
+```bash
+# 登录到默认环境（dev）
+lsc login
+
+# 登录到指定开发环境
+lsc login --env dev
+```
+
+交互式登录成功会在主目录生成.lscrc.json文件，也可以手动生成如下文件放置到项目目录或主目录下。如果项目目前存在该登录配置文件，优先该配置，否则以主目录文件为准。
+
+登录配置文件示例如下：
+
+```json
+{
+    "currentEnv": "dev",
+    "dev": {
+        "lightBaseURL": "http://light.example.com",//必填，light平台的地址
+        "account": "user@example.com",//必填，light平台注册的邮箱或手机号
+        "password": "mypassword",//必填，加密后的密码，可以通过执行命令lsc pwd生成
+        "wecomWebhook": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxx"//选填，企微推送通知机器人链接
+    }
+}
+```
+
+**说明**: 如果不指定环境，会尝试读取当前配置的环境，如果不存在则默认使用 `dev` 环境。
+
+### 2.2 `md5` - 获取MD5密码
+
+**描述**: 根据密码和邮箱生成MD5加密后的密码。
+
+**选项**:
+- `-p, --password <type>`: 输入密码（可选）
+- `-e, --email <type>`: 输入邮箱（可选）
+
+**使用示例**:
+```bash
+# 交互式输入密码和邮箱
+lsc md5
+
+# 直接指定密码和邮箱
+lsc md5 --password mypassword --email user@example.com
+```
+
+**说明**: 如果不指定密码或邮箱，会进入交互式输入模式。
+
+### 2.3 `logout` - 注销会话
+
+**描述**: 注销当前或指定的管控台会话。
+
+**选项**:
+- `-e, --env <type>`: 选择管控台的环境（可选）
+- `-l, --link <link>`: 注销指定管控台链接（可选）
+- `-t, --token <token>`: 注销指定token（可选）
+
+**使用示例**:
+```bash
+# 注销当前环境的会话
+lsc logout
+
+# 注销指定环境、链接和token的会话
+lsc logout --env prod --link https://example.com --token abc123
+```
+
+**说明**: 如果不指定环境，会使用当前配置的环境。如果不指定链接或token，会使用当前环境的配置。
+
+### 2.4 `use <name>` - 设置当前发布版本
+
+**描述**: 设置当前使用的离线包环境。
+
+**参数**:
+- `<name>`: 环境名称
+
+**使用示例**:
+```bash
+# 设置当前环境为 dev
+lsc use dev
+```
+
+**说明**: 环境名称必须是已经登录过的环境。
+
+### 2.5 `config` - 交互式配置离线包发布参数
+
+**描述**: 交互式配置离线包发布的各项参数。
+
+**使用示例**:
+```bash
+# 进入交互式配置
+lsc config
+```
+
+**说明**: 会进入交互式问答模式，配置包括：
+- 离线包ID
+- 发布版本号
+- APP版本范围（iOS、Android、Harmony）
+- 发布的APP选择
+- 离线包压缩包存放位置
+- 离线包名称
+- 上一版本处理方式
+- 发布日志
+
+### 2.6 `init` - 快速初始化配置模板
+
+**描述**: 快速初始化离线包发布配置模板。
+
+**使用示例**:
+```bash
+# 初始化配置模板
+lsc init
+```
+
+**说明**: 如果配置文件已存在，会询问是否重新初始化。
+
+### 2.7 `publish` - 发布离线包
+
+**描述**: 发布单个离线包。
+
+**别名**: `p`
+
+**使用示例**:
+```bash
+# 发布离线包
+lsc publish
+
+# 使用别名
+lsc p
+```
+
+**说明**: 发布前需要确保已登录（`lsc login`）并配置好发布参数（`lsc config` 或 `lsc init`）。
+
+### 2.8 `batch` - 批量发布离线包
+
+**描述**: 批量发布多个离线包。
+
+**别名**: `b`
+
+**使用示例**:
+```bash
+# 批量发布离线包
+lsc batch
+
+# 使用别名
+lsc b
+```
+
+**说明**: 会根据配置的 `pkg_dir` 目录下的zip文件进行批量发布，以zip文件名作为离线包ID。
+
+### 2.9 `deal version` - 处理离线包兼容版本重叠
+
+**描述**: 处理指定APP和离线包的版本兼容重叠问题。
+
+**使用示例**:
+```bash
+# 处理离线包版本重叠
+lsc deal version
+```
+
+**说明**: 会进入交互式输入模式，需要输入APP ID和离线包ID。
+
+### 2.10 `clean all` - 批量处理离线包兼容版本重叠
+
+**描述**: 批量处理多个APP的离线包版本兼容重叠问题。
+
+**使用示例**:
+```bash
+# 批量处理离线包版本重叠
+lsc clean all
+```
+
+**说明**: 会进入交互式输入模式，需要输入APP ID列表（逗号分隔）。
+
+### 2.11 `pwd` - 打印当前地址
+
+**描述**: 打印当前工作目录的绝对路径。
+
+**别名**: `dir`
+
+**使用示例**:
+```bash
+# 打印当前地址
+lsc pwd
+
+# 使用别名
+lsc dir
+```
+
+### 2.12 `zip` - 压缩dist目录为zip文件
+
+**描述**: 压缩dist目录下的所有文件（不包括自身生成的zip文件）为一个zip文件。
+
+**选项**:
+- `--dir <distDir>`: 指定dist目录的绝对路径（可选）
+- `--output <outputZipFile>`: 指定输出zip文件的路径（可选）
+- `--zn <zipFilename>`: 指定zip文件名（可选）
+
+**使用示例**:
+```bash
+# 使用默认配置压缩
+lsc zip
+
+# 指定dist目录、输出路径和文件名
+lsc zip --dir /path/to/dist --output /path/to/output --zn myapp.zip
+```
+
+**说明**: 如果不指定参数，会使用 `lsc.config.json` 中的配置。
+
+## 3. 配置文件
+
+LSC 使用 `lsc.config.json` 文件存储配置信息，主要包括：
+
+| 配置项 | 描述 | 默认值 |
+|--------|------|--------|
+| `pkgid` | 必选项，离线包ID | - |
+| `set_pkg_version` | 发布版本号 | "1.0.1" |
+| `ios_version_scope` | iOS版本范围 | "7.0.7" |
+| `android_version_scope` | Android版本范围 | "7.0.7.0" |
+| `harmony_version_scope` | Harmony版本范围 | "1.0.1" |
+| `publish_app_arr` | 必选项，发布的APP列表 | ["3542", "3543"] |
+| `pkg_dir` | 离线包存放目录 | "./dist/" |
+| `pkg_zip_name` | 离线包文件名 | "dist.zip" |
+| `task_status` | 上一版本处理方式（对离线包有效） | 0（保留） |
+| `release_desc` | 发布日志 | "功能更新" |
+| need_wechat_push | 是否开启微信企微机器人推送 | false |
+| publish_h5web_arr | 必选项，要发布的H5应用的ID | - |
+| h5web_name | H5应用对应的名称 | - |
+
+lsc.config.json示例及说明：
+
+```json
+{
+    "pkgid": "lscpkg",//必填
+    "need_wechat_push": false,
+    "set_pkg_version": "1.0.1",
+    "ios_version_scope": "7.0.7",
+    "android_version_scope": "7.0.7.0",
+    "harmony_version_scope": "1.0.1",
+    "publish_app_arr": [
+        "3542"//需要发布的APP的ID
+    ],
+    "pkg_dir": "./dist/",
+    "pkg_zip_name": "lscdemo.zip",
+    "task_status": 2,
+    "apps_name": {
+        "3542": "开发版",
+        "3543": "仿真版"
+    },
+    "publish_h5web_arr": [
+        "8112734868610136",//需要发布的H5的ID
+        "8112734868610049"
+    ],
+    "h5web_name": {
+        "8112734868610136": "账户分析PC公版",
+        "8112734868610049": "账户分析超级终端版本"
+    }
+}
+```
+
+
+
+## 4. zip压缩变量
+
+| 环境变量 | 描述 | 默认值 |
+|----------|------|--------|
+| `ZIP_COMPRESSION_LEVEL` | 压缩级别 (0-9) | 9 |
+| `ZIP_STAT_CONCURRENCY` | 文件状态检查并发数 | 4 |
+| `ZIP_STAT_TIMEOUT` | 文件状态检查超时时间（毫秒） | 10000 |
+
+## 5. 常见问题
+
+### 5.1 登录失败
+
+**解决方案**:
+- 检查网络连接
+- 确认环境参数正确
+- 确认账号密码正确
+
+### 5.2 发布失败
+
+**解决方案**:
+- 确认已登录（`lsc login`）
+- 确认配置文件存在（`lsc config` 或 `lsc init`）
+- 检查离线包文件是否存在
+- 检查网络连接
+
+### 5.3 压缩失败
+
+**解决方案**:
+- 确认dist目录存在
+- 确认配置文件存在
+- 检查目录权限
+
+## 6. 示例工作流
+
+### 6.1 首次使用流程
+
+1. **初始化配置**: `lsc init`
+2. **配置发布参数**: `lsc config`
+3. **登录管控台**: `lsc login`
+4. **压缩文件**: `lsc zip`
+5. **发布离线包**: `lsc publish`
+
+### 6.2 日常发布流程
+
+1. **确保已登录**: `lsc login`
+2. **构建项目**（根据项目实际命令）
+3. **压缩文件**: `lsc zip`
+4. **发布离线包**: `lsc publish`
+
+### 6.3 批量发布流程
+
+1. **确保已登录**: `lsc login`
+2. **构建多个项目**
+3. **准备多个zip文件**到配置的 `pkg_dir` 目录
+4. **批量发布**: `lsc batch`
+
+## 7. 版本信息
+
+- **工具版本**: 1.1.0
+- **最后更新**: 2026-01-21
+
+## 8. 注意事项
+
+1. **安全提示**: 登录信息会存储在本地配置文件中，请确保配置文件的安全性
+2. **版本重叠**: 使用 `deal version` 和 `clean all` 命令时请谨慎，可能会影响现有版本
+3. **配置文件**: 请确保 `lsc.config.json` 文件存在且配置正确
+4. **网络连接**: 发布和登录操作需要网络连接到管控台
+5. **权限**: 确保有足够的权限读写配置文件和发布目录