@optima-chat/optima-agent 0.9.13 → 0.9.15

package/.claude/skills/gen/SKILL.md

@@ -1,279 +1,327 @@
----
-name: gen
-description: "生成和编辑图片/语音/虚拟试穿。使用场景：生成图片(generate images/生成图片/画图)、编辑图片(edit images/编辑图片/图生图/风格转换)、文本转语音(TTS/语音合成/朗读)、语音识别(ASR/语音转文字/转录)、虚拟试穿(virtual try-on/试穿/换装/试衣)。视频生成请使用 video-gen skill。"
----
-
-# AI 内容生成工具
-
-## 图片生成
-
-### 标准工作流程
-
-```bash
-# 文生图
-gen image "提示词" -o /home/aiuser/project/result.png
-
-# 图片编辑/风格转换
-gen image "转成水彩风格" -i photo.png -o /home/aiuser/project/result.png
-
-# 读取并描述结果
-Read /home/aiuser/project/result.png
-```
-
-### gen image 命令
-
-统一的图像生成/编辑命令。
-
-```bash
-gen image <prompt> [options]
-```
-
-#### 参数
-
-| 参数 | 说明 |
-|------|------|
-| `-i, --input <path>` | 输入图像（可多次使用，最多 8 张） |
-| `-W, --width <px>` | 输出宽度（默认 1024，最大 2048） |
-| `-H, --height <px>` | 输出高度（默认 1024，最大 2048） |
-| `-o, --output <path>` | 输出目录或完整路径 |
-| `-s, --seed <number>` | 随机种子（可复现结果） |
-| `-f, --format <fmt>` | 输出格式：jpeg \| png |
-| `--provider <name>` | 供应商：grsai（默认） \| bfl |
-| `-m, --model <model>` | 模型：gpt-image-2（默认） \| nano-banana-fast \| nano-banana-pro \| flux-kontext-pro \| flux-kontext-max 等 |
-| `--aspect-ratio <ratio>` | 宽高比：1:1 \| 16:9 \| 9:16 \| 4:3 等 |
-| `--image-size <size>` | nano-banana-pro 输出尺寸：1K \| 2K \| 4K |
-
-### 工作流示例
-
-#### 文生图
-
-```bash
-gen image "a cute fluffy cat sitting on a windowsill, natural lighting" -o /home/aiuser/project/cat.png
-Read /home/aiuser/project/cat.png
-```
-
-#### 图片风格转换
-
-```bash
-gen image "watercolor painting style, artistic brushstrokes" -i photo.jpg -o /home/aiuser/project/watercolor.png
-Read /home/aiuser/project/watercolor.png
-```
-
-#### 多图风格融合
-
-将第一张图的风格应用到第二张图的内容上：
-
-```bash
-gen image "apply the artistic style from image 1 to the content of image 2" -i style.png -i content.png -o /home/aiuser/project/fusion.png
-Read /home/aiuser/project/fusion.png
-```
-
-#### 多图元素组合
-
-从多张图中提取元素组合成新图：
-
-```bash
-gen image "The person from image 1 is petting the cat from image 2, in a cozy living room" -i person.jpg -i cat.jpg -o /home/aiuser/project/combined.png
-```
-
-#### 精确颜色控制
-
-使用 hex code 指定精确颜色：
-
-```bash
-gen image "a modern logo with brand color #02eb3c as the primary accent" -o /home/aiuser/project/logo.png
-```
-
-#### 产品海报
-
-```bash
-gen image "Disney Pixar style 3D poster, [产品描述], cute character, vibrant gradient background, professional studio lighting" -W 1024 -H 1024 -o /home/aiuser/project/poster.png
-```
-
-### 提示词指南
-
-#### 结构
-
-**Subject + Action + Style + Context**
-
-词序很重要，靠前的元素优先级更高。
-
-#### 长度建议
-
-| 长度 | 词数 | 适用场景 |
-|------|------|----------|
-| 短 | 10-30 | 快速概念探索 |
-| 中 | 30-80 | 大多数项目（推荐） |
-| 长 | 80+ | 复杂场景 |
-
-#### 最佳实践
-
-| 技巧 | 说明 | 示例 |
-|------|------|------|
-| 描述想要的 | 不支持负向提示词 | "sharp focus" 而非 "no blur" |
-| 精确颜色 | 使用 hex code | `"brand color #1a1a2e"` |
-| 文字渲染 | 用引号包裹文字 | `"The text 'OPEN' in red neon"` |
-| 摄影风格 | 指定相机/镜头 | `"shot on Fujifilm X-T5, 35mm f/1.4"` |
-| 多语言 | 用原生语言更地道 | 法语描述巴黎场景 |
-
-#### 示例对比
-
-```bash
-# 简单
-gen image "a robot"
-
-# 添加风格
-gen image "a friendly AI robot, cute cartoon style, bright colors, 3D render"
-
-# 完整描述
-gen image "Disney Pixar style 3D animated robot character, friendly cheerful expression, wearing headset, surrounded by floating icons, gradient purple-blue background, professional studio lighting, vibrant colors"
-```
-
-### 分辨率选择
-
-最大 2048x2048。
-
-| 用途 | 分辨率 |
-|------|--------|
-| 社交媒体 | 1024x1024 |
-| 宽屏壁纸 | 1920x1088 |
-| 竖屏海报 | 768x1280 |
-
-### 生成规则
-
-#### 生成后
-- 使用 Read 工具查看生成的图片
-- 向用户描述图片内容（颜色、风格、构图、元素）
-- 验证是否符合用户要求
-
-#### 多图参考
-- 最多 8 张输入图
-
-## 虚拟试穿 (Virtual Try-On)
-
-使用 FASHN AI tryon-v1.6 将服装穿到人物照片上。
-
-```bash
-gen tryon <人物照片> <服装照片> [options]
-```
-
-### 参数
-
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `-o, --output <path>` | 输出文件路径 | `./gen-output/tryon_{timestamp}.png` |
-| `-c, --category <type>` | 服装类别：auto \| tops \| bottoms \| one-pieces | auto |
-| `-m, --mode <mode>` | 生成模式：performance \| balanced \| quality | quality |
-| `--garment-type <type>` | 服装照片类型：auto \| flat-lay \| model | auto |
-| `-n, --num-samples <n>` | 生成数量 (1-4) | 1 |
-| `--format <fmt>` | 输出格式：png \| jpeg | png |
-| `--seed <n>` | 随机种子（可复现） | - |
-
-### 示例
-
-```bash
-# 基本用法
-gen tryon person.jpg garment.jpg -o /home/aiuser/project/result.png
-Read /home/aiuser/project/result.png
-
-# 使用 URL 图片
-gen tryon https://example.com/model.jpg https://example.com/dress.jpg -o /home/aiuser/project/result.png
-
-# 指定服装类别和快速模式
-gen tryon person.jpg top.jpg -c tops -m performance -o /home/aiuser/project/result.png
-
-# 生成多张结果
-gen tryon person.jpg dress.jpg -n 4 -c one-pieces -o /home/aiuser/project/result.png
-```
-
-### 注意事项
-
-- 支持本地图片路径和 URL
-- 服装类别：auto (自动检测), tops (上装), bottoms (下装), one-pieces (连体)
-- 三种模式：performance (~7s), balanced (~9s), quality (~13s)
-- 默认保存到 `./gen-output/`
-
-## 语音合成 (TTS)
-
-使用 DashScope qwen3-tts-flash 将文本转为语音。
-
-```bash
-gen tts <文本> [options]
-```
-
-### 参数
-
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `-o, --output <path>` | 输出文件路径 | `./gen-output/tts_{timestamp}.wav` |
-| `--voice <name>` | 声音名称 | Cherry |
-| `--voices` | 列出可用声音 | - |
-| `--play` | 生成后自动播放 | - |
-
-### 可用声音
-
-- 女声：Cherry, Serena, Chelsie, Aria, Bella, Vivian, Jennifer, Katerina, Breeze, Maple, Sakura
-- 男声：Ethan, Aiden, Brandon, Ryan, Luke, Leo
-
-### 示例
-
-```bash
-# 中文语音合成
-gen tts "你好，欢迎使用语音合成功能" -o /home/aiuser/project/hello.wav
-
-# 指定男声
-gen tts "Hello, welcome!" --voice Ethan -o /home/aiuser/project/greeting.wav
-
-# 生成后播放
-gen tts "测试语音" --play -o /home/aiuser/project/test.wav
-```
-
-### 注意事项
-
-- 输出格式为 WAV
-- 最大 5000 字符
-- 支持中、英、日、韩、法、德等 10 种语言（自动检测）
-- 默认保存到 `./gen-output/`
-
-## 语音识别 (ASR)
-
-使用 Groq Whisper 将语音转为文字。
-
-```bash
-gen asr <音频文件> [options]
-```
-
-### 参数
-
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `--language <lang>` | 语言提示：zh \| en \| ja \| ko 等 | 自动检测 |
-| `--model <name>` | Whisper 模型 | whisper-large-v3-turbo |
-
-### 示例
-
-```bash
-# 自动检测语言
-gen asr /home/aiuser/project/recording.mp3
-
-# 指定语言提示（提高准确率）
-gen asr /home/aiuser/project/recording.wav --language zh
-```
-
-### 注意事项
-
-- 支持 mp3, wav, m4a, ogg, webm 格式
-- 文件大小限制 25MB
-
-## 任务管理
-
-所有生成命令会自动等待完成。如需查看历史或管理任务：
-
-```bash
-gen task list                     # 查看所有任务
-gen task list --type image        # 按类型过滤
-gen task list --status failed     # 按状态过滤
-gen task get <task_id>            # 查看任务详情
-gen task cancel <task_id>         # 取消任务
-gen task retry <task_id>          # 重试失败的任务
-```
+---
+name: gen
+description: "生成和编辑图片/语音/虚拟试穿。使用场景：生成图片(generate images/生成图片/画图)、编辑图片(edit images/编辑图片/图生图/风格转换)、文本转语音(TTS/语音合成/朗读)、语音识别(ASR/语音转文字/转录)、虚拟试穿(virtual try-on/试穿/换装/试衣)。视频生成请使用 video-gen skill。"
+---
+
+# AI 内容生成工具
+
+## 图片生成
+
+### 标准工作流程
+
+```bash
+# 文生图
+gen image "提示词" -o /home/aiuser/project/result.png
+
+# 图片编辑/风格转换
+gen image "转成水彩风格" -i photo.png -o /home/aiuser/project/result.png
+
+# 读取并描述结果
+Read /home/aiuser/project/result.png
+```
+
+### gen image 命令
+
+统一的图像生成/编辑命令。
+
+```bash
+gen image <prompt> [options]
+```
+
+#### 参数
+
+| 参数 | 说明 |
+|------|------|
+| `-i, --input <path>` | 输入图像（可多次使用，最多 8 张） |
+| `-W, --width <px>` | 输出宽度（默认 1024，最大 2048） |
+| `-H, --height <px>` | 输出高度（默认 1024，最大 2048） |
+| `-o, --output <path>` | 输出目录或完整路径 |
+| `-s, --seed <number>` | 随机种子（可复现结果） |
+| `-f, --format <fmt>` | 输出格式：jpeg \| png |
+| `--provider <name>` | 供应商：grsai（默认） \| bfl |
+| `-m, --model <model>` | 模型：gpt-image-2（默认） \| nano-banana-fast \| nano-banana-pro \| flux-kontext-pro \| flux-kontext-max 等 |
+| `--aspect-ratio <ratio>` | 宽高比：1:1 \| 16:9 \| 9:16 \| 4:3 等 |
+| `--image-size <size>` | nano-banana-pro 输出尺寸：1K \| 2K \| 4K |
+
+### 工作流示例
+
+#### 文生图
+
+```bash
+gen image "a cute fluffy cat sitting on a windowsill, natural lighting" -o /home/aiuser/project/cat.png
+Read /home/aiuser/project/cat.png
+```
+
+#### 图片风格转换
+
+```bash
+gen image "watercolor painting style, artistic brushstrokes" -i photo.jpg -o /home/aiuser/project/watercolor.png
+Read /home/aiuser/project/watercolor.png
+```
+
+#### 多图风格融合
+
+将第一张图的风格应用到第二张图的内容上：
+
+```bash
+gen image "apply the artistic style from image 1 to the content of image 2" -i style.png -i content.png -o /home/aiuser/project/fusion.png
+Read /home/aiuser/project/fusion.png
+```
+
+#### 多图元素组合
+
+从多张图中提取元素组合成新图：
+
+```bash
+gen image "The person from image 1 is petting the cat from image 2, in a cozy living room" -i person.jpg -i cat.jpg -o /home/aiuser/project/combined.png
+```
+
+#### 精确颜色控制
+
+使用 hex code 指定精确颜色：
+
+```bash
+gen image "a modern logo with brand color #02eb3c as the primary accent" -o /home/aiuser/project/logo.png
+```
+
+#### 产品海报
+
+```bash
+gen image "Disney Pixar style 3D poster, [产品描述], cute character, vibrant gradient background, professional studio lighting" -W 1024 -H 1024 -o /home/aiuser/project/poster.png
+```
+
+### 提示词指南
+
+#### 结构
+
+**Subject + Action + Style + Context**
+
+词序很重要，靠前的元素优先级更高。
+
+#### 长度建议
+
+| 长度 | 词数 | 适用场景 |
+|------|------|----------|
+| 短 | 10-30 | 快速概念探索 |
+| 中 | 30-80 | 大多数项目（推荐） |
+| 长 | 80+ | 复杂场景 |
+
+#### 最佳实践
+
+| 技巧 | 说明 | 示例 |
+|------|------|------|
+| 描述想要的 | 不支持负向提示词 | "sharp focus" 而非 "no blur" |
+| 精确颜色 | 使用 hex code | `"brand color #1a1a2e"` |
+| 文字渲染 | 用引号包裹文字 | `"The text 'OPEN' in red neon"` |
+| 摄影风格 | 指定相机/镜头 | `"shot on Fujifilm X-T5, 35mm f/1.4"` |
+| 多语言 | 用原生语言更地道 | 法语描述巴黎场景 |
+
+#### 示例对比
+
+```bash
+# 简单
+gen image "a robot"
+
+# 添加风格
+gen image "a friendly AI robot, cute cartoon style, bright colors, 3D render"
+
+# 完整描述
+gen image "Disney Pixar style 3D animated robot character, friendly cheerful expression, wearing headset, surrounded by floating icons, gradient purple-blue background, professional studio lighting, vibrant colors"
+```
+
+### 分辨率选择
+
+最大 2048x2048。
+
+| 用途 | 分辨率 |
+|------|--------|
+| 社交媒体 | 1024x1024 |
+| 宽屏壁纸 | 1920x1088 |
+| 竖屏海报 | 768x1280 |
+
+### 生成规则
+
+#### 生成后
+- 使用 Read 工具查看生成的图片
+- 向用户描述图片内容（颜色、风格、构图、元素）
+- 验证是否符合用户要求
+
+#### 多图参考
+- 最多 8 张输入图
+
+## 虚拟试穿 (Virtual Try-On)
+
+使用 FASHN AI tryon-v1.6 将服装穿到人物照片上。
+
+```bash
+gen tryon <人物照片> <服装照片> [options]
+```
+
+### 参数
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `-o, --output <path>` | 输出文件路径 | `./gen-output/tryon_{timestamp}.png` |
+| `-c, --category <type>` | 服装类别：auto \| tops \| bottoms \| one-pieces | auto |
+| `-m, --mode <mode>` | 生成模式：performance \| balanced \| quality | quality |
+| `--garment-type <type>` | 服装照片类型：auto \| flat-lay \| model | auto |
+| `-n, --num-samples <n>` | 生成数量 (1-4) | 1 |
+| `--format <fmt>` | 输出格式：png \| jpeg | png |
+| `--seed <n>` | 随机种子（可复现） | - |
+
+### 示例
+
+```bash
+# 基本用法
+gen tryon person.jpg garment.jpg -o /home/aiuser/project/result.png
+Read /home/aiuser/project/result.png
+
+# 使用 URL 图片
+gen tryon https://example.com/model.jpg https://example.com/dress.jpg -o /home/aiuser/project/result.png
+
+# 指定服装类别和快速模式
+gen tryon person.jpg top.jpg -c tops -m performance -o /home/aiuser/project/result.png
+
+# 生成多张结果
+gen tryon person.jpg dress.jpg -n 4 -c one-pieces -o /home/aiuser/project/result.png
+```
+
+### 注意事项
+
+- 支持本地图片路径和 URL
+- 服装类别：auto (自动检测), tops (上装), bottoms (下装), one-pieces (连体)
+- 三种模式：performance (~7s), balanced (~9s), quality (~13s)
+- 默认保存到 `./gen-output/`
+
+## 语音合成 (TTS)
+
+使用 DashScope qwen3-tts-flash 将文本转为语音。
+
+```bash
+gen tts <文本> [options]
+```
+
+### 参数
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `-o, --output <path>` | 输出文件路径 | `./gen-output/tts_{timestamp}.wav` |
+| `--voice <name>` | 声音名称 | Cherry |
+| `--voices` | 列出可用声音 | - |
+| `--play` | 生成后自动播放 | - |
+
+### 可用声音
+
+- 女声：Cherry, Serena, Chelsie, Aria, Bella, Vivian, Jennifer, Katerina, Breeze, Maple, Sakura
+- 男声：Ethan, Aiden, Brandon, Ryan, Luke, Leo
+
+### 示例
+
+```bash
+# 中文语音合成
+gen tts "你好，欢迎使用语音合成功能" -o /home/aiuser/project/hello.wav
+
+# 指定男声
+gen tts "Hello, welcome!" --voice Ethan -o /home/aiuser/project/greeting.wav
+
+# 生成后播放
+gen tts "测试语音" --play -o /home/aiuser/project/test.wav
+```
+
+### 注意事项
+
+- 输出格式为 WAV
+- 最大 5000 字符
+- 支持中、英、日、韩、法、德等 10 种语言（自动检测）
+- 默认保存到 `./gen-output/`
+
+## 语音识别 (ASR)
+
+使用 Groq Whisper 将语音转为文字。
+
+```bash
+gen asr <音频文件> [options]
+```
+
+### 参数
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--language <lang>` | 语言提示：zh \| en \| ja \| ko 等 | 自动检测 |
+| `--model <name>` | Whisper 模型 | whisper-large-v3-turbo |
+
+### 示例
+
+```bash
+# 自动检测语言
+gen asr /home/aiuser/project/recording.mp3
+
+# 指定语言提示（提高准确率）
+gen asr /home/aiuser/project/recording.wav --language zh
+```
+
+### 注意事项
+
+- 支持 mp3, wav, m4a, ogg, webm 格式
+- 文件大小限制 25MB
+
+## 任务管理
+
+所有生成命令会自动等待完成。如需查看历史或管理任务：
+
+```bash
+gen task list                     # 查看所有任务
+gen task list --type image        # 按类型过滤
+gen task list --status failed     # 按状态过滤
+gen task get <task_id>            # 查看任务详情
+gen task cancel <task_id>         # 取消任务
+gen task retry <task_id>          # 重试失败的任务
+```
+
+## 错误处理（重要）
+
+所有 `gen` 命令在失败时会返回结构化错误。**不要把原始 `error_message`（可能是中文报错）直接抛给用户**——根据 `error_code` 字段决定应对策略。
+
+### 失败响应示例
+
+```json
+{
+  "success": true,
+  "data": {
+    "task_id": "abc-123",
+    "status": "failed",
+    "error_code": "UPSTREAM_MAINTENANCE",
+    "retryable": true,
+    "error_message": "上游生成服务正在维护中，请稍后再试"
+  }
+}
+```
+
+注意：`success: true` + `status: "failed"` 是任务执行完成但生成失败；`success: false` 才是 CLI 调用本身失败。两者都要按 `error_code` 处理。
+
+### 处理对照表
+
+| `error_code` | 你应该做的 | 给用户的话术（参考） |
+|---|---|---|
+| `UPSTREAM_MAINTENANCE` | **不立即重试**。告知用户服务维护中，建议 5-10 分钟后再试 | "图片生成服务正在维护，建议 5-10 分钟后我再帮您试一次" |
+| `CONTENT_POLICY_VIOLATION` | **改写 prompt** 去掉敏感/违规元素，自动重试**最多 1 次**。仍失败再交给用户 | "您的描述触发了内容审核，我换个说法重试：……" |
+| `UPSTREAM_TIMEOUT` | 立即重试 1 次（静默） | （重试成功就别提；连续失败再说） |
+| `UPSTREAM_RATE_LIMITED` | 等 30 秒后重试 1 次 | "请求频率过高，稍等几十秒再试" |
+| `UPSTREAM_NETWORK` | 立即重试 1 次（静默） | （同 timeout） |
+| `PROVIDER_INSUFFICIENT_CREDITS` | **不重试**。明确告诉用户问题不在他、不在他的余额 | "生成服务后端额度不足（与您账户余额无关），已记录" |
+| `UPSTREAM_UNKNOWN` 或字段缺失 | **不重试**。把 `error_message` 透传给用户 | "图片生成失败：{error_message}" |
+
+### 通用规则
+
+1. **`retryable: true`** 的失败：自动重试**最多 1 次**，不要循环
+2. **`retryable: false`**：永远不重试，立即给用户结果
+3. 改写 prompt 重试时，**告诉用户你做了什么改动**（透明）
+4. `success: false`（CLI 本身报错）直接报给用户，不重试
+5. 没有 `error_code` 字段的旧版响应：当作 `UPSTREAM_UNKNOWN` 处理
+
+### 反面示例（不要这样做）
+
+❌ 把 `"维护中"` 三个字直接砸给用户
+❌ 任何失败都自动 retry 三五次造成账单浪费
+❌ `CONTENT_POLICY_VIOLATION` 时换汤不换药地原 prompt 重试
+❌ `PROVIDER_INSUFFICIENT_CREDITS` 时让用户去充值（这跟用户余额无关）