企微瓣 CLI 技能 (qwb-cli)
qwb 是企微瓣平台的命令行工具，所有操作通过执行 qwb 命令完成。
安装：npm install -g qwb-cli
输出默认为 JSON 格式（AI 友好），加 --format table 可切换为人类友好表格。
前置条件：认证
所有业务接口（除 auth 外）都需要先登录。
# 密码登录
qwb auth login -p <手机号> -w <密码>
# 验证码登录
qwb auth send-code -p <手机号>
qwb auth login -p <手机号> -c <验证码>
# 查看登录状态
qwb auth status
# 查看/设置配置（如 API 地址）
qwb auth config # 查看
qwb auth config --api-url <url> # 设置 API 地址
# 退出
qwb auth logout
Token 存储在 ~/.qwb/credentials.json，默认有效期 30 天。
命令概览
| 领域 | 命令前缀 | 能力 |
|---|
| 认证 | qwb auth | 登录、登出、配置管理 |
| 用户 | qwb user | 查看/更新用户资料 |
| 语音合成 | qwb voice | MiniMax TTS、音色列表、作品管理 |
| 声音克隆 | qwb clone | 上传音频、创建/管理克隆声音 |
| 数字人 | qwb dh | 列表、创建、视频生成（纯文本/音频） |
| 瓣值 | qwb petals | 余额概览、批次、消费历史 |
| AI 对话 | qwb ai | 多模型对话 |
| 阿里百炼 | qwb ds | 通义千问对话、CosyVoice TTS、音色克隆 |
| 图像 | qwb image | AI 图片生成（文生图/图生图）、去背景 |
语音合成 (qwb voice)
获取系统音色列表
qwb voice voices
返回所有可用系统音色，包含 ID、名称、性别、语言、风格、标签。
语音合成
# 最简用法（使用默认音色）
qwb voice synthesize -t "你好，欢迎使用企微瓣"
# 指定系统音色
qwb voice synthesize -t "你好" --voice-id <音色ID>
# 使用克隆声音
qwb voice synthesize -t "你好" --clone-id <克隆声音ID>
# 完整参数
qwb voice synthesize -t "文本内容" \
--voice-id <id> `# 系统音色 ID（不传用默认）` \
--speed 1.0 `# 语速 0.5-2.0` \
--volume 1.0 `# 音量 0.1-2.0` \
--pitch 0 `# 音调 -1.0~1.0` \
--emotion auto `# 情感: auto/happy/sad/angry/calm/fluent` \
--format mp3 `# 格式: mp3/wav/pcm` \
--title "作品标题" \
--subtitle `# 生成字幕`
返回：jobId、audioUrl（或 audioExternalUrl）、时长、文件大小、消耗瓣值、剩余瓣值。
作品管理
qwb voice works # 作品列表（分页：--page, --limit）
qwb voice work <id> # 作品详情
qwb voice delete <id> # 删除作品
声音克隆 (qwb clone)
qwb clone list # 克隆声音列表（--page, --page-size, --status）
qwb clone upload --file <path> # 上传音频文件
qwb clone create \
--name "我的声音" \
--voice-id <唯一ID> \
--audio-id <upload返回的资源ID> \
--description "描述" \
--demo-text "试听文本"
qwb clone delete <id> # 软删除
qwb clone restore <id> # 恢复
数字人 (qwb dh)
查看数字人
qwb dh list # 所有可用数字人（含系统预设）
qwb dh my # 我的克隆数字人（--page, --page-size, --search）
qwb dh status <id> # 查询创建状态
创建数字人
# 本地视频文件（自动上传到 OSS）
qwb dh create \
--video ./my-video.mp4 \
--name "数字人名称" \
--gender male \
--description "描述" \
--wait # 等待创建完成（轮询状态）
# 远程 URL
qwb dh create \
--video https://oss.example.com/video.mp4 \
--name "数字人名称" \
--gender female
生成数字人视频
# 最简用法（自动选择数字人 + 自动使用默认声音）
qwb dh video-create --script "你好，欢迎使用企微瓣"
# 指定数字人
qwb dh video-create --dh-id <id> --script "你好，欢迎使用企微瓣"
# 使用自定义音频（忽略 TTS）
qwb dh video-create --script "对口型文本" --audio-url <音频URL>
# 完整参数
qwb dh video-create \
--script "脚本文本" `# 必填` \
--dh-id <id> `# 可选，不传自动选择第一个可用的` \
--audio-url <url> `# 可选，提供后用音频模式` \
--speed 1 `# TTS 语速 0.5-2` \
--duration 30 `# 音频时长（秒，预估消费用）` \
--width 1080 --height 1920 `# 视频尺寸` \
--bg-color "#EDEDED" `# 背景颜色` \
--wait `# 等待生成完成（轮询状态）`
逻辑：
- 不传
--dh-id → CLI 自动调用 dh list 获取第一个 READY 状态的数字人
- 不传
--audio-url → 使用 text 模式（数字人默认声音 TTS）
- 传了
--audio-url → 使用 audio 模式
查询视频状态
qwb dh video-status <jobId> # 返回 status、videoUrl、duration、errorMessage
瓣值管理 (qwb petals)
qwb petals overview # 余额概览
qwb petals batches # 批次列表
qwb petals history # 消费历史（--page, --limit, --type）
AI 对话 (qwb ai)
qwb ai models # 获取可用模型列表
qwb ai chat -i "你好" # 默认模型对话
qwb ai chat -i "你好" \
--model-id <id> \
--system-prompt "你是一个助手" \
--temperature 0.7 \
--max-tokens 2048 \
--stream # 流式输出
阿里百炼 DashScope (qwb ds)
对话
qwb ds token # 获取临时 Token
qwb ds models # 模型列表
qwb ds chat -i "你好" \
--model qwen-plus \ # qwen-turbo/qwen-plus/qwen-max/qwen-long
--system-prompt "你是助手" \
--temperature 1.0 \
--max-tokens 2048 \
--search # 启用联网搜索
CosyVoice 语音合成
qwb ds voices # 预设音色列表
qwb ds tts -t "你好" \
--voice longxiaochun_v2 \ # 音色 ID
--format mp3 \
--sample-rate 22050 \
--volume 50 \
--rate 1 --pitch 1
克隆音色管理
qwb ds clone-create --name "音色名" --audio-url <url> --text "训练文本"
qwb ds clone-list # 克隆音色列表
qwb ds clone-detail <voiceId> # 音色详情
qwb ds clone-update <voiceId> --name "新名称"
qwb ds clone-delete <voiceId>
图像处理 (qwb image)
AI 图片生成
# 文生图
qwb image generate "一只可爱的橘猫在阳光下打哈欠"
# 指定尺寸和输出
qwb image generate "星际穿越风格壁纸" -s 3k -o wallpaper.png
# 图生图（单张参考）
qwb image generate "将背景换成海边" -i https://example.com/photo.jpg
# 图生图（多张参考）
qwb image generate "将图1的服装换为图2的服装" -i img1.jpg -i img2.jpg
# 选项
# -s, --size <size> 尺寸: 2k(默认)/3k/WIDTHxHEIGHT
# -i, --image <urls...> 参考图片 URL（支持多张）
# --no-watermark 不添加水印
# -o, --output <path> 保存到本地文件
图像去背景
qwb image remove-bg --image-url <url>
用户信息 (qwb user)
qwb user profile # 查看当前用户信息
qwb user update --nickname "新昵称" --avatar <url>
核心规则
输出格式
- 默认 JSON（AI Agent 友好，机器解析）
--format table：人类友好的表格--format quiet：最少输出（脚本/管道用）--pretty：格式化 JSON
错误处理
- 退出码：0 = 成功，1 = 业务错误，2 = 认证错误，3 = 网络错误
- 错误输出到 stderr，正常结果到 stdout
- 捕获到退出码 2 时，提示用户重新登录
异步任务模式
数字人创建和视频生成是异步任务：
- 提交后返回
jobId
- 加
--wait 自动轮询直到完成/失败
- 不加
--wait 则需手动通过 dh status <id> 或 dh video-status <jobId> 查询
典型工作流
快速生成语音
qwb voice synthesize -t "欢迎使用企微瓣，这是一段测试语音"
无需指定音色，使用系统默认。返回音频 URL 和瓣值消耗。
快速生成数字人视频
qwb dh video-create --script "大家好，欢迎来到我们的产品发布会" --wait
自动选择系统数字人 → TTS 合成 → 生成视频 → 等待完成返回视频 URL。
AI 图片创作
qwb image generate "赛博朋克城市夜景，霓虹灯闪烁" -s 3k -o cyber_city.png
文生图并保存到本地。
查看消费情况
qwb petals overview && qwb petals history --limit 5
克隆声音后合成
# 1. 上传音频
qwb clone upload --file my_voice.wav
# 2. 创建克隆（用返回的 audioId）
qwb clone create --name "我的声音" --voice-id my-voice-001 --audio-id <audioId>
# 3. 用克隆声音合成
qwb voice synthesize -t "这是用我的克隆声音说的话" --clone-id <cloneId>
