polyv-live-cli 1.2.29-rc.0 → 1.2.29

package/README.md

@@ -1,163 +1,504 @@
-# PolyV Live CLI
+# PolyV Live CLI 保利威直播云CLI工具
 
-`polyv-live-cli` is an agent-friendly command line tool for managing PolyV live streaming accounts, channels, streams, products, coupons, playback, documents, sessions, chat, interaction tools, viewers, player settings, watch pages, and statistics.
+一个强大的命令行工具，用于管理保利威(PolyV)直播云服务。支持频道管理、直播流控制等核心功能，提供完整的API集成和友好的用户体验。
 
-The CLI is designed for both human operators and AI agents:
 
-- every command exposes `--help`;
-- most data commands support table and JSON output;
-- account configuration can be reused across commands;
-- destructive or state-changing commands use confirmation prompts or `--force` where supported.
+## ✨ 特性
 
-## Install
+### 🏗️ 核心功能
+- **频道管理**: 创建、查看、更新、删除直播频道
+- **流控制**: 获取推流密钥、开始/停止直播、实时状态监控
+- **认证集成**: 完整的PolyV OpenAPI认证支持
+- **多输出格式**: 支持表格和JSON格式输出
 
-Use the latest published CLI directly:
+### 🛠️ 技术特性
+- **TypeScript**: 完整的类型安全和智能提示
+- **分层架构**: 清晰的命令、处理器、服务分层设计
+- **错误处理**: 用户友好的错误消息和详细的调试信息
+- **配置灵活**: 支持环境变量、命令行参数、配置文件
+- **测试完备**: 80%+测试覆盖率，包含单元测试和集成测试
 
+## 📦 安装
+
+### 全局安装
 ```bash
-npx --yes polyv-live-cli@latest --help
+npm install -g polyv-live-cli
 ```
 
-Or install it globally:
+### 本地开发
+```bash
+git clone https://github.com/your-repo/polyv-cli.git
+cd polyv-cli
+npm install
+npm run build
+```
+
+## 🚀 快速开始
+
+### 1. 配置认证信息
+
+#### 🎯 推荐方式：交互式配置 (推荐)
+
+使用 `config set` 命令进行一次性交互式配置，系统会安全地将认证信息保存到用户主目录：
 
 ```bash
-npm install -g polyv-live-cli
+# 交互式配置认证信息
+polyv-live-cli config set
+```
+
+运行后会提示输入：
+- PolyV App ID
+- PolyV App Secret  
+- PolyV User ID (可选)
+- API Base URL (可选，默认为官方API地址)
+
+配置完成后，所有后续命令都会自动使用保存的认证信息，无需重复设置。
+
+#### 📋 配置管理命令
+
+```bash
+# 显示当前配置
+polyv-live-cli config show
+
+# 获取特定配置项
+polyv-live-cli config get appId
+
+# 设置特定配置项
+polyv-live-cli config put appId your_new_app_id
+
+# 删除特定配置项
+polyv-live-cli config unset appId
+
+# 清空所有配置
+polyv-live-cli config clear
+```
+
+#### 🔧 其他认证方式
+
+**方法二：环境变量**
+```bash
+export POLYV_APP_ID="your_app_id"
+export POLYV_APP_SECRET="your_app_secret"
+export POLYV_USER_ID="your_user_id"  # 可选
+```
+
+**方法三：命令行参数**
+```bash
+polyv-live-cli --appId your_app_id --appSecret your_app_secret [command]
+```
+
+#### 🔄 认证优先级
+
+系统会按以下优先级使用认证信息：
+1. **命令行参数** (最高优先级)
+2. **环境变量**
+3. **全局配置文件** (config set 设置的内容)
+4. **默认值** (最低优先级)
+
+### 2. 基础使用示例
+
+```bash
+# 首次使用：配置认证信息
+polyv-live-cli config set
+
+# 查看帮助
 polyv-live-cli --help
+
+# 查看版本
+polyv-live-cli --version
+
+# 查看当前配置
+polyv-live-cli config show
+
+# 创建频道
+polyv-live-cli channel create --name "我的直播间" --scene topclass
+
+# 查看频道列表
+polyv-live-cli channel list
+
+# 获取推流密钥
+polyv-live-cli stream get-key --channelId 3151318
+
+# 开始直播
+polyv-live-cli stream start --channelId 3151318
+
+# 查看直播状态
+polyv-live-cli stream status --channelId 3151318
+
+# 停止直播
+polyv-live-cli stream stop --channelId 3151318
 ```
 
-Node.js 18 or later is required.
+## 📋 命令参考
 
-## Authentication
+### 配置管理 (Configuration Management)
 
-Add an account and set it as default:
+#### 交互式配置设置
+```bash
+polyv-live-cli config set
+```
+启动交互式配置向导，引导用户输入认证信息并保存到全局配置文件。
 
+#### 显示当前配置
 ```bash
-polyv-live-cli account add production --app-id <appId> --app-secret <appSecret> --user-id <userId>
-polyv-live-cli account set-default production
-polyv-live-cli account current
+polyv-live-cli config show [options]
+
+选项:
+  --output <format>         输出格式: table|json (默认: table)
 ```
 
-Switch the current shell session to a named account:
+#### 获取特定配置项
+```bash
+polyv-live-cli config get <key>
+
+参数:
+  <key>                     配置项名称 (appId|appSecret|userId|baseUrl)
+```
 
+#### 设置特定配置项
 ```bash
-polyv-live-cli use production
+polyv-live-cli config put <key> <value>
+
+参数:
+  <key>                     配置项名称 (appId|appSecret|userId|baseUrl)
+  <value>                   配置项值
 ```
 
-Use one account for a single command:
+#### 删除特定配置项
+```bash
+polyv-live-cli config unset <key>
+
+参数:
+  <key>                     配置项名称 (appId|appSecret|userId|baseUrl)
+```
 
+#### 清空所有配置
 ```bash
-polyv-live-cli channel list -a production -o json
+polyv-live-cli config clear
 ```
+删除所有保存的配置信息。
 
-Or pass credentials directly when automation requires it:
+### 频道管理 (Channel Management)
 
+#### 创建频道
 ```bash
-polyv-live-cli channel list --appId <appId> --appSecret <appSecret> --userId <userId> -o json
+polyv-live-cli channel create [options]
+
+选项:
+  --name <string>           频道名称 (必需)
+  --scene <string>          场景类型: topclass|ppt|pure (必需)
+  --description <string>    频道描述
+  --publisher <string>      主持人名称
+  --password <string>       频道密码
+  --max-viewers <number>    最大观看人数
+  --output <format>         输出格式: table|json (默认: table)
 ```
 
-Do not print or log AppSecret. Stream keys returned by `stream get-key -o json` are also sensitive and should only be sent to trusted streaming software.
+#### 查看频道列表
+```bash
+polyv-live-cli channel list [options]
 
-## Common Flows
+选项:
+  --page <number>           页码 (默认: 1)
+  --per-page <number>       每页数量 (默认: 20)
+  --output <format>         输出格式: table|json (默认: table)
+```
 
-Create and inspect a channel:
+#### 获取频道详情
+```bash
+polyv-live-cli channel get --channelId <id> [options]
+
+选项:
+  --channelId <string>      频道ID (必需)
+  --output <format>         输出格式: table|json (默认: table)
+```
 
+#### 更新频道
 ```bash
-polyv-live-cli channel create -n "Product Launch" --scene topclass --template ppt -o json
-polyv-live-cli channel list -P 1 -l 20 -o json
-polyv-live-cli channel get -c <channelId> -o json
+polyv-live-cli channel update --channelId <id> [options]
+
+选项:
+  --channelId <string>      频道ID (必需)
+  --name <string>           频道名称
+  --description <string>    频道描述
+  --publisher <string>      主持人名称
+  --password <string>       频道密码
+  --max-viewers <number>    最大观看人数
+  --start-time <timestamp>  开始时间 (13位时间戳)
+  --end-time <timestamp>    结束时间 (13位时间戳)
+  --page-views <number>     累积观看数
+  --likes <number>          点赞数
+  --cover-img <url>         封面图片URL
+  --splash-img <url>        引导页图片URL
+  --output <format>         输出格式: table|json (默认: table)
+```
+
+#### 删除频道
+```bash
+polyv-live-cli channel delete --channelId <id>
+
+选项:
+  --channelId <string>      频道ID (必需)
 ```
 
-Check stream status and get OBS credentials:
+### 流控制 (Stream Control)
 
+#### 获取推流密钥
 ```bash
-polyv-live-cli stream status -c <channelId> -o json
-polyv-live-cli stream get-key -c <channelId> -o json
+polyv-live-cli stream get-key --channelId <id> [options]
+
+选项:
+  --channelId <string>      频道ID (必需)
+  --output <format>         输出格式: table|json (默认: table)
+```
+
+#### 开始直播
+```bash
+polyv-live-cli stream start --channelId <id>
+
+选项:
+  --channelId <string>      频道ID (必需)
 ```
 
-Manage products and coupons:
+#### 停止直播
+```bash
+polyv-live-cli stream stop --channelId <id>
+
+选项:
+  --channelId <string>      频道ID (必需)
+```
 
+#### 查看流状态
 ```bash
-polyv-live-cli product list -c <channelId> -o json
-polyv-live-cli coupon add --name "Full 100 minus 20" --type MAX_OUT --availableAmount 100 \
-  --receiveStart 1704067200000 --receiveEnd 1704153600000 \
-  --useTimeType RANGE --useStart 1704067200000 --useEnd 1704758400000 \
-  --condition FULL_REDUCE --full 100 --reduce 20 --limitPerPerson 1 -o json
-polyv-live-cli coupon list -o json
+polyv-live-cli stream status --channelId <id> [options]
+
+选项:
+  --channelId <string>      频道ID (必需)
+  --output <format>         输出格式: table|json (默认: table)
+  --watch                   持续监控模式 (5秒更新)
 ```
 
-Query playback, documents, sessions, and statistics:
+## 🎯 使用场景
 
+### 1. 批量频道管理
 ```bash
-polyv-live-cli playback list -c <channelId> -o json
-polyv-live-cli document list -c <channelId> -o json
-polyv-live-cli session list -c <channelId> -o json
-polyv-live-cli statistics view -c <channelId> --start-day 2026-06-01 --end-day 2026-06-20 -o json
+# 批量创建频道
+for i in {1..5}; do
+  polyv-live-cli channel create --name "批量频道$i" --scene topclass --publisher "主持人$i"
+done
+
+# 查看所有频道
+polyv-live-cli channel list --per-page 50 --output json
 ```
 
-Preview the built-in e-commerce scene before writing data:
+### 2. 自动化直播流程
+```bash
+#!/bin/bash
+CHANNEL_ID="3151318"
+
+echo "🚀 开始直播..."
+polyv-live-cli stream start --channelId $CHANNEL_ID
+
+echo "📡 获取推流信息..."
+polyv-live-cli stream get-key --channelId $CHANNEL_ID
 
+echo "📊 监控直播状态..."
+polyv-live-cli stream status --channelId $CHANNEL_ID --watch
+```
+
+### 3. CI/CD集成
 ```bash
-polyv-live-cli setup e-commerce --dry-run -o json
+# 在CI/CD流水线中使用
+polyv-live-cli channel create \
+  --name "自动化测试频道" \
+  --scene topclass \
+  --description "CI/CD自动创建" \
+  --output json > channel_info.json
+
+CHANNEL_ID=$(cat channel_info.json | jq -r '.channelId')
+echo "创建的频道ID: $CHANNEL_ID"
 ```
 
-## Command Groups
+## ⚙️ 配置选项
 
-The current CLI exposes 40 top-level commands. Use top-level help first, then the deepest subcommand help before running a write operation.
+### 配置方法优先级
+1. **命令行参数** (最高优先级)
+2. **环境变量**
+3. **全局配置文件** (推荐用于全局安装)
+4. **项目配置文件**
+5. **默认值** (最低优先级)
 
+### 交互式配置 (推荐)
 ```bash
-polyv-live-cli --help
-polyv-live-cli channel --help
-polyv-live-cli channel create --help
+# 交互式设置配置
+polyv-live-cli config set
+
+# 查看当前配置
+polyv-live-cli config show
+
+# 查看特定配置值
+polyv-live-cli config get appId
+
+# 设置特定配置值
+polyv-live-cli config put appId your_app_id
+
+# 清除配置
+polyv-live-cli config clear
 ```
 
-Main command families:
+全局配置文件位置：`~/.polyv-live-cli/config.json`
 
-| Area | Commands |
-| --- | --- |
-| Accounts and configuration | `account`, `use`, `platform`, `global`, `user`, `group`, `partner` |
-| Channel and stream operations | `channel`, `stream`, `monitor`, `transmit` |
-| Marketing and commerce | `product`, `coupon`, `card-push`, `promotion` |
-| Content and playback | `playback`, `record`, `document`, `session`, `material`, `webapp` |
-| Interactions | `chat`, `lottery`, `checkin`, `qa`, `questionnaire`, `donate`, `interaction`, `robot` |
-| Viewers and access control | `viewer`, `watch-condition`, `whitelist`, `custom-field`, `invite-sales` |
-| Player, watch page, data, and AI | `player`, `web`, `statistics`, `finance`, `ai` |
-| Workflow templates | `setup` |
+### 环境变量
+| 变量名 | 说明 | 必需 |
+|--------|------|------|
+| `POLYV_APP_ID` | PolyV应用ID | ✅ |
+| `POLYV_APP_SECRET` | PolyV应用密钥 | ✅ |
+| `POLYV_USER_ID` | PolyV用户ID | ❌ |
+| `POLYV_BASE_URL` | API基础URL | ❌ |
+| `POLYV_TIMEOUT` | 请求超时时间(ms) | ❌ |
+| `DEBUG` | 调试模式 | ❌ |
 
-## Safety
+## 🔐 认证与安全
 
-Commands that create, update, delete, start, stop, push, send, merge, transcode, import, batch-update, or change global/channel settings can affect live data. Confirm the target account, channel ID, and object ID before running them. Use `--force` only after the user or operator has explicitly approved the operation.
+### PolyV API认证
+本工具使用PolyV官方的MD5签名认证机制：
 
-For tests or release validation, prefer temporary channels and clean them up afterwards instead of mutating a long-lived configured channel.
+1. **参数收集**: 收集appId、timestamp、channelId等参数
+2. **参数排序**: 按字典序排序参数
+3. **字符串拼接**: 格式为 `appSecret + 排序后参数 + appSecret`
+4. **MD5签名**: 计算MD5哈希值并转换为大写
+5. **请求发送**: 将签名作为sign参数发送
 
-## Development
+### 安全最佳实践
+- ✅ 使用环境变量存储敏感信息
+- ✅ 敏感数据在输出中自动脱敏
+- ✅ 不在日志中记录密钥信息
+- ✅ 支持用户级别的权限控制
 
-From the repository root:
+## 🧪 测试
 
+### 运行测试
 ```bash
-pnpm install
-pnpm --filter polyv-live-cli build
-pnpm --filter polyv-live-cli test
-pnpm --filter polyv-live-cli test:integration
+# 运行所有测试
+npm test
+
+# 运行单元测试
+npm run test:unit
+
+# 运行集成测试
+npm run test:integration
+
+# 查看测试覆盖率
+npm run test:coverage
 ```
 
-Generate API and CLI inventory reports:
+### 测试覆盖率
+- **单元测试**: 80%+ 代码覆盖率
+- **集成测试**: 核心工作流全覆盖
+- **错误处理**: 各种异常场景测试
 
+## 🐛 故障排除
+
+### 常见问题
+
+#### 1. 认证失败
 ```bash
-pnpm api:inventory
-pnpm cli:inventory
+❌ 认证失败: 无效的appId或appSecret
+
+解决方案:
+- 检查POLYV_APP_ID和POLYV_APP_SECRET环境变量
+- 确认PolyV控制台中的应用凭据
+- 验证网络连接和防火墙设置
 ```
 
-Run the local built CLI:
+#### 2. 频道未找到
+```bash
+❌ 频道未找到: 频道ID 3151318 不存在
+
+解决方案:
+- 确认频道ID是否正确
+- 检查账号是否有访问该频道的权限
+- 使用 channel list 命令查看可用频道
+```
+
+#### 3. 推流密钥获取失败
+```bash
+❌ 获取推流密钥失败: 频道未在直播状态
+
+解决方案:
+- 使用 stream start 命令先开始直播
+- 确认频道类型支持推流功能
+- 检查频道配置是否正确
+```
 
+### 调试模式
 ```bash
-node packages/cli/dist/index.js --help
+# 启用详细调试信息
+DEBUG=1 polyv-live-cli [command]
+
+# 或设置环境变量
+export DEBUG=1
+polyv-live-cli [command]
 ```
 
-## Release
+## 🏗️ 开发
 
-Dry-run the package before publishing:
+### 项目结构
+```
+src/
+├── commands/          # CLI命令定义
+│   ├── channel.commands.ts
+│   └── stream.commands.ts
+├── handlers/          # 业务逻辑处理器
+│   ├── channel.handler.ts
+│   └── stream.handler.ts
+├── services/          # API服务层
+│   ├── channel.service.ts
+│   └── stream.service.ts
+├── types/             # TypeScript类型定义
+│   ├── channel.ts
+│   ├── stream.ts
+│   └── auth.ts
+├── utils/             # 工具函数
+│   ├── errors.ts
+│   ├── formatter.ts
+│   └── signature.ts
+└── config/            # 配置管理
+    └── manager.ts
+```
 
+### 开发命令
 ```bash
-pnpm release:cli:dry
+# 开发模式
+npm run dev
+
+# 构建项目
+npm run build
+
+# 代码检查
+npm run lint
+
+# 类型检查
+npm run type-check
+
+# 清理构建
+npm run clean
 ```
 
-Publish only after the package version has been bumped beyond the current npm version and the build, tests, inventory checks, and `git diff --check` pass.
+### 贡献指南
+1. Fork 项目仓库
+2. 创建功能分支: `git checkout -b feature/new-feature`
+3. 提交变更: `git commit -m 'feat: add new feature'`
+4. 推送分支: `git push origin feature/new-feature`
+5. 创建Pull Request
+
+## 📄 许可证
+
+本项目基于 [MIT License](LICENSE) 开源协议。
+
+## 🆘 支持
+
+### 获取帮助
+- 📖 [PolyV官方文档](https://help.polyv.net/)
+
+---

package/dist/commands/account.commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account.commands.d.ts","sourceRoot":"","sources":["../../src/commands/account.commands.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkjBpC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoT9D"}
+{"version":3,"file":"account.commands.d.ts","sourceRoot":"","sources":["../../src/commands/account.commands.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+dpC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwD9D"}