'` | jq表达式过滤输出 | muapi-cli |
资料来源：[core/edit/SKILL.md - Common Flags](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/edit/SKILL.md)
## 环境依赖
核心原语层依赖以下组件：
| 依赖 | 说明 | 用途 |
|:---|:---|:---|
| `muapi-cli` | muapi命令行工具 | 所有操作的核心引擎 |
| `curl` | HTTP客户端 | API请求 |
| `jq` | JSON处理器 | 输出解析和过滤 |
| `python3` | Python运行时 | 脚本逻辑 |
| `MUAPI_KEY` | 环境变量 | API认证 |
**安装 muapi-cli：**
```bash
# npm 安装（推荐）
npm install -g muapi-cli
# pip 安装
pip install muapi-cli
# 直接运行（无需安装）
npx muapi-cli --help
```
资料来源：[README.md - Install muapi CLI](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
## 典型工作流
### 完整图像编辑工作流
```mermaid
graph LR
A[上传图像] --> B[配置API密钥]
B --> C[执行编辑]
C --> D{同步或异步}
D -->|同步| E[直接返回结果]
D -->|异步| F[获取request_id]
F --> G[轮询结果]
G --> H{完成?}
H -->|否| G
H -->|是| I[下载输出]
I --> J[查看结果]
```
**示例代码：**
```bash
# 1. 配置API密钥
bash core/platform/setup.sh --add-key "YOUR_MUAPI_KEY"
# 2. 上传本地文件（自动获取URL）
IMAGE_URL=$(muapi upload file ./input.jpg --output-json --jq '.url' | tr -d '"')
# 3. 提交异步编辑任务
REQUEST_ID=$(muapi image edit "$IMAGE_URL" \
--prompt "转换为吉卜力动画风格" \
--model flux-kontext-pro \
--no-wait \
--output-json \
--jq '.request_id' | tr -d '"')
# 4. 轮询等待结果
bash core/platform/check-result.sh --id "$REQUEST_ID"
# 5. 下载并查看
muapi predict wait "$REQUEST_ID" --download ./outputs --view
```
### 批量处理工作流
```bash
# 批量超分处理
for img in ./images/*.jpg; do
IMAGE_URL=$(muapi upload file "$img" --output-json --jq '.url' | tr -d '"')
REQUEST_ID=$(muapi enhance upscale "$IMAGE_URL" --no-wait --output-json --jq '.request_id' | tr -d '"')
echo "$img: $REQUEST_ID" >> batch_jobs.txt
done
# 批量收集结果
while read line; do
img=$(echo "$line" | cut -d: -f1)
rid=$(echo "$line" | cut -d: -f2- | tr -d ' ')
muapi predict wait "$rid" --download "./outputs/$img"
done < batch_jobs.txt
```
## Schema 数据验证
核心原语层使用 `schema_data.json` 进行运行时验证：
```json
{
"models": {
"flux-kontext-pro": {
"endpoint": "/v1/image/edit/kontext",
"aspect_ratios": ["1:1", "16:9", "9:16", "4:3"],
"resolutions": ["1K", "2K", "4K"]
}
}
}
```
**验证功能：**
| 功能 | 说明 |
|:---|:---|
| 模型ID验证 | 确保请求的模型存在 |
| 端点解析 | 自动映射模型名到API端点 |
| 参数检查 | 验证 aspect_ratio、resolution、duration |
```bash
# 列出所有可用模型
muapi models list
# 按类别筛选
muapi models list --category video --output-json
```
资料来源：[README.md - Schema Reference](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
## 与 Expert Library 的关系
核心原语层为 Expert Library（专家库）提供底层支撑：
```mermaid
graph BT
subgraph "Expert Library 专家库"
A[Cinema Director] --> D[调用核心原语]
B[Nano-Banana] --> D
C[UI Designer] --> D
end
D --> E[core/edit]
D --> F[core/platform]
D --> G[muapi-cli]
```
**分工原则：**
| 层级 | 职责 | 抽象级别 |
|:---|:---|:---|
| Core Primitives | 原子操作，薄封装 | 低 |
| Expert Library | 领域知识，工作流编排 | 高 |
专家库中的技能（如 Cinema Director）读取 SKILL.md 文件，按照步骤指示调用核心原语，实现专业级输出而无需暴露底层细节。
资料来源：[README.md - Expert Library](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
## 常见问题与排查
### 认证问题
**症状：** API调用返回认证错误
**排查步骤：**
```bash
# 1. 确认密钥配置
bash core/platform/setup.sh --show-config
# 2. 测试密钥有效性
bash core/platform/setup.sh --test
```
### 异步任务卡住
**症状：** `check-result.sh` 长时间无响应
**排查步骤：**
```bash
# 1. 检查一次不过滤
bash core/platform/check-result.sh --id "YOUR_ID" --once
# 2. 查看任务状态
muapi predict result "YOUR_ID" --json
```
### 模型不支持
**症状：** 报错模型不存在
**解决方案：**
```bash
# 查看支持的模型列表
muapi models list --category image --output-json | jq '.models[].id'
```
## 总结
核心原语层是 Generative-Media-Skills 的基础设施，通过标准化的脚本封装提供：
- **平台无关性**：统一的 CLI 接口，底层切换透明
- **零样板**：无需编写 curl 或 JSON 解析代码
- **可组合性**：脚本可自由组合构建复杂工作流
- **类型安全**：Schema 验证确保参数正确性
核心原语层的设计哲学是**简单、可信、持久**——专注于做好一件事（与 muapi.ai API 交互），而不试图做太多。这与 Expert Library 的高级抽象形成良好互补，共同构成完整的 AI 媒体生成能力体系。
---
## 视频与动效技能库
### 相关页面
相关主题：[核心原语层详解](#core-primitives), [社交媒体技能库](#social-skills)
相关源码文件
以下源码文件用于生成本页说明：
- [library/motion/cinema-director/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/cinema-director/SKILL.md)
- [library/motion/seedance-2/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/seedance-2/SKILL.md)
- [library/motion/seedance-2/scripts/generate-seedance.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/seedance-2/scripts/generate-seedance.sh)
- [library/motion/cinema-director/scripts/generate-film.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/cinema-director/scripts/generate-film.sh)
- [library/motion/product-video-ad-maker/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/product-video-ad-maker/SKILL.md)
- [library/motion/ugc-video-factory/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/ugc-video-factory/SKILL.md)
- [library/edit/ai-clipping/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/edit/ai-clipping/SKILL.md)
# 视频与动效技能库
## 概述
视频与动效技能库是 Generative-Media-Skills 项目的核心模块之一，专门用于为 AI Agent 提供专业级的视频生成、编辑和动效制作能力。该技能库整合了文本转视频（Text-to-Video）、图片转视频（Image-to-Video）、视频剪辑（Video Editing）和短视频创作（Short Video Creation）等多条技术路线，支持从概念构思到最终成品的完整工作流。
资料来源：[README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
## 技术架构
### 分层设计
视频与动效技能库采用 **Core/Library** 分层架构：
```mermaid
graph TD
A[用户/Agent] --> B[Expert Library 专家技能层]
B --> C[core/media 媒体核心]
B --> D[core/edit 编辑核心]
B --> E[core/platform 平台核心]
C --> F[muapi-cli]
D --> F
E --> F
F --> G[muapi.ai API]
```
资料来源：[README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
### 技能分类
技能库包含 **16 个视频动效技能**，分为以下几大类：
| 类别 | 技能数量 | 代表技能 |
|:---|:---:|:---|
| 电影级视频生成 | 3 | Cinema Director、Seedance 2.0、One-Shot Video |
| 产品展示视频 | 4 | Product Video Ad Maker、Giant Product Showcase、Jewelry Product Video、Product Showcase Video |
| 人物视频创作 | 4 | Animal Vlogger Video、Talking Baby Video、UGC Lifestyle Try-On、Cartoon Dance Animation |
| 视频特效与动画 | 3 | 3D Logo Animation、AI Fight Scene Generator、Character Story Video |
| 社交媒体短视频 | 2 | UGC Video Factory、YouTube Shorts |
资料来源：[README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
## 核心组件详解
### Cinema Director（电影导演）
Cinema Director 是技能库中最具电影感的高级技能，提供专业的电影级视频生成能力。
**功能特性：**
- 支持 **Kling v3.0 Pro** 等顶级视频生成模型
- 可配置视频时长（1-10秒）
- 支持多种情绪风格（Intent）：epic（史诗）、cinematic（电影感）、dramatic（戏剧性）等
- 支持 Seedance 2.0 模型的文本转视频、图片转视频和视频扩展
资料来源：[library/motion/cinema-director/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/cinema-director/SKILL.md)
**使用示例：**
```bash
cd library/motion/cinema-director
# 创建10秒史诗级视频
bash scripts/generate-film.sh \
--subject "a cybernetic dragon over Tokyo" \
--intent "epic" \
--model "kling-v3.0-pro" \
--duration 10 \
--view
```
资料来源：[library/motion/cinema-director/scripts/generate-film.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/cinema-director/scripts/generate-film.sh)
### Seedance 2.0（字节豆包视频）
Seedance 2.0 提供导演级别的专业视频生成能力，支持三种工作模式：
| 模式 | 说明 |
|:---|:---|
| `t2v` | 文本转视频（Text-to-Video） |
| `i2v` | 图片转视频（Image-to-Video） |
| `extend` | 视频扩展（Video Extension） |
资料来源：[library/motion/seedance-2/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/seedance-2/SKILL.md)
**核心脚本参数：**
| 参数 | 类型 | 说明 |
|:---|:---:|:---|
| `--mode` | string | 工作模式：t2v/i2v/extend |
| `--subject` | string | 视频主体描述 |
| `--intent` | string | 创作意图（如 reveal、orbit、sweep） |
| `--file` | string | 输入图片路径（i2v模式必需） |
| `--request-id` | string | 扩展模式需要提供原视频ID |
| `--duration` | int | 视频时长（秒） |
| `--view` | flag | 生成后自动打开查看 |
资料来源：[library/motion/seedance-2/scripts/generate-seedance.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/seedance-2/scripts/generate-seedance.sh)
### AI Clipping（智能剪辑）
AI Clipping 提供从长视频自动提取高传播力短视频的能力，是内容创作者的效率利器。
**核心能力：**
- **服务端转录**：无需本地 Whisper，在服务端完成语音识别
- **病毒式排名**：基于传播潜力自动排序精彩片段
- **去重机制**：智能检测并去除重复内容
- **人脸追踪自动裁剪**：保持人物始终在画面中心
资料来源：[library/edit/ai-clipping/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/edit/ai-clipping/SKILL.md)
### UGC Video Factory（用户生成内容工厂）
UGC Video Factory 将产品推广流程自动化，从人物照片到10秒竖屏广告一气呵成。
**工作流：**
1. 上传人物照片
2. 上传产品照片
3. 生成推广文案
4. Nano-Banana Pro 风格编辑
5. Seedance 2.0 VIP 图片转视频
资料来源：[library/motion/ugc-video-factory/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/ugc-video-factory/SKILL.md)
### Product Video Ad Maker（产品广告制作器）
高端电影级产品视频广告制作，从简单的产品照片即可生成专业级商业视频。
**输出规格：**
- 竖屏 9:16 格式
- 适配 TikTok/Reels/Shorts 平台
- 高端商业电影质感
资料来源：[library/motion/product-video-ad-maker/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/motion/product-video-ad-maker/SKILL.md)
## MCP 工具接口
视频与动效技能通过 MCP Server 暴露为结构化工具，Claude Desktop、Cursor 等 Agent 可直接调用。
资料来源：[README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
### 视频生成相关工具
| 工具名称 | 功能 | 支持模型数 |
|:---|:---|:---:|
| `muapi_video_generate` | 文本转视频 | 13 |
| `muapi_video_from_image` | 图片转视频 | 16 |
| `muapi_video_extend` | 视频扩展 | 2 |
### 视频编辑相关工具
| 工具名称 | 功能 | 支持模型数 |
|:---|:---|:---:|
| `muapi_edit_lipsync` | 口型同步 | 4 |
| `muapi_edit_clipping` | AI 精彩片段提取 | 1 |
| `muapi_enhance_upscale` | 视频超分辨率 | 3 |
## 异步处理流程
视频生成采用异步工作模式，需要通过轮询获取结果：
```mermaid
sequenceDiagram
participant Agent
participant muapi
participant API
participant Storage
Agent->>muapi: muapi video generate --no-wait
muapi->>API: POST /video/generate
API-->>muapi: request_id
muapi-->>Agent: { request_id: "xxx" }
loop 轮询直到完成
Agent->>muapi: muapi predict result --id xxx
muapi->>API: GET /predict/result?id=xxx
API-->>muapi: status: pending/processing/done
muapi-->>Agent: status
end
API->>Storage: 存储完成的视频
Agent->>muapi: muapi predict wait --download ./outputs
muapi->>API: GET /predict/result?id=xxx
API-->>muapi: { outputs: [url] }
muapi->>Storage: 下载视频文件
muapi-->>Agent: ./outputs/video.mp4
```
资料来源：[README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
**CLI 异步操作示例：**
```bash
# 提交异步任务并获取 request_id
REQUEST_ID=$(muapi video generate "a dog running on a beach" \
--model kling-master --no-wait --output-json --jq '.request_id' | tr -d '"')
# 执行其他任务...
# 等待并下载结果
muapi predict wait "$REQUEST_ID" --download ./outputs
```
## 使用指南
### 快速开始
**前置条件：**
1. 安装 muapi-cli：`npm install -g muapi-cli`
2. 配置 API Key：`muapi auth configure --api-key "YOUR_MUAPI_KEY"`
资料来源：[README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
### 基础视频生成
```bash
# 文本转视频
muapi video generate "a sunset over mountains" \
--model kling-v3.0-pro \
--duration 5 \
--view
# 图片转视频
URL=$(muapi upload file ./product.jpg --output-json --jq '.url' | tr -d '"')
muapi video from-image "$URL" \
--subject "camera slowly zooms in" \
--model seedance-2.0 \
--view
```
### 使用高级技能
```bash
# 使用 Cinema Director 生成电影级视频
cd library/motion/cinema-director
bash scripts/generate-film.sh \
--subject "cybernetic samurai in Tokyo neon district" \
--intent "cinematic" \
--model kling-v3.0-pro \
--duration 10 \
--view
# 使用 Seedance 2.0 i2v 模式
cd library/motion/seedance-2
bash scripts/generate-seedance.sh \
--mode i2v \
--file ./concept.jpg \
--subject "camera slowly pulls back to reveal the full landscape" \
--intent "reveal" \
--view
```
## MCP Server 配置
在 Claude Desktop 或 Cursor 中配置 MCP Server：
```json
{
"mcpServers": {
"muapi": {
"command": "muapi",
"args": ["mcp", "serve"],
"env": { "MUAPI_API_KEY": "your-key-here" }
}
}
}
```
配置完成后，Agent 可直接调用 `muapi_video_generate`、`muapi_video_from_image` 等工具，无需编写 Shell 脚本。
资料来源：[README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
## 常见问题与社区反馈
根据社区讨论，以下是用户关心的热点问题：
| 问题 | 说明 | 状态 |
|:---|:---|:---:|
| 视频生成速度慢 | 用户询问 GPU 加速支持 | 已支持云端 GPU 加速 |
| 发布到第三方平台 | 用户希望在视频生成后自动发布 | 路线图中 |
| CUDA 本地运行 | 社区询问本地 CUDA 加速 | 推荐使用云端 API |
| Docker 支持 | 用户询问 Docker 部署方案 | 需要额外配置 |
资料来源：[GitHub Issues #89](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/89), [#70](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/70), [#68](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/68)
## 相关技能推荐
视频与动效技能库可与以下技能协同使用：
| 配套技能 | 用途 |
|:---|:---|
| Nano-Banana | 提供 Gemini 3 风格的图片生成作为视频素材 |
| AI Clipping | 将长视频自动剪辑为短视频 |
| Lip Sync | 为视频添加口型同步配音 |
| Social Media Pack | 生成各平台适配的社交媒体版本 |
| YouTube Thumbnail | 生成高点击率的视频缩略图 |
## 技术参考
- **CLI 文档**：[muapi-cli npm](https://www.npmjs.com/package/muapi-cli)
- **API Key 获取**：[https://muapi.ai/dashboard](https://muapi.ai/dashboard)
- **支持的模型列表**：`muapi models list --category video`
- **支持的分辨率**：`flux-dev`、`kling-v3.0-pro`、`seedance-2.0` 等主流模型
---
## 图像与设计技能库
### 相关页面
相关主题：[核心原语层详解](#core-primitives), [社交媒体技能库](#social-skills)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
- [core/edit/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/edit/SKILL.md)
- [library/visual/nano-banana/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/visual/nano-banana/SKILL.md)
- [library/visual/ui-design/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/visual/ui-design/SKILL.md)
- [library/visual/logo-creator/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/visual/logo-creator/SKILL.md)
- [library/visual/action-figure-generator/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/visual/action-figure-generator/SKILL.md)
- [library/visual/amazon-product-listing/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/visual/amazon-product-listing/SKILL.md)
- [library/visual/interior-design/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/visual/interior-design/SKILL.md)
# 图像与设计技能库
图像与设计技能库是 Generative-Media-Skills 项目中专注于视觉内容生成的专家知识层，提供 21 种专业图像生成和设计技能。该模块通过 `muapi-cli` 核心引擎驱动，结合 AI 推理能力，为 AI 代理提供从产品摄影到 UI 设计、从品牌标识到室内装修的全链路视觉内容创作能力。资料来源：[README.md]()
## 架构概览
图像与设计技能库采用 **核心层 / 技能层** 双层架构：
```mermaid
graph TD
A[AI 代理 Agent] --> B[技能层 Skill Library]
B --> C[Nano-Banana 推理生成]
B --> D[UI Designer 界面设计]
B --> E[Logo Creator 标识创作]
B --> F[Interior Design 室内设计]
B --> G[Action Figure 人偶生成]
C --> H[core/edit 编辑核心]
D --> H
E --> H
F --> H
G --> H
H --> I[muapi-cli 核心引擎]
I --> J[Flux Kontext Pro]
I --> K[Midjourney v7]
I --> L[Kling 3.0]
I --> M[HiDream]
```
技能层封装专业领域知识，核心层处理底层 API 调用，两者通过标准化 CLI 接口通信。资料来源：[README.md]()
## 核心编辑功能
`core/edit` 模块提供基础的图像编辑与增强能力，是所有高级视觉技能的底层支撑。资料来源：[core/edit/SKILL.md]()
### 可用脚本
| 脚本 | 功能描述 |
|:---|:---|
| `edit-image.sh` | 基于提示词的图像编辑（支持 Flux Kontext、GPT-4o、Midjourney、Qwen 等模型） |
| `enhance-image.sh` | 一键增强操作：超分辨率、背景移除、人脸替换、色彩化、吉卜力风格、产品摄影 |
| `lipsync.sh` | 视频唇形同步（支持 Sync Labs、LatentSync、Creatify、Veed） |
| `video-effects.sh` | 视频特效：AI 特效、人脸替换、舞蹈、换装、Luma 修饰/重构 |
### 常用参数
所有脚本支持以下通用参数：
```bash
--async # 异步提交，不等待结果
--json # 输出 JSON 格式
--timeout N # 超时时间（秒）
--help # 显示帮助信息
```
### 快速使用
```bash
# 图像编辑
bash edit-image.sh --image-url "https://..." --prompt "添加太阳镜" --model flux-kontext-pro
# 超分辨率放大
bash enhance-image.sh --op upscale --image-url "https://..."
# 背景移除
bash enhance-image.sh --op background-remove --image-url "https://..."
# 唇形同步
bash lipsync.sh --video-url "https://..." --audio-url "https://..." --model sync
# 舞蹈特效
bash video-effects.sh --op dance --image-url "https://..." --audio-url "https://..."
```
资料来源：[core/edit/SKILL.md]()
## Nano-Banana 推理生成
Nano-Banana 是项目中最具创新性的图像生成技能，采用 AI 推理驱动的方式生成高质量视觉内容。其设计理念融合了 Gemini 3 的推理风格，能够在生成过程中进行多步思考和优化。资料来源：[library/visual/nano-banana/SKILL.md]()
### 核心特性
- **推理驱动的生成**：通过链式思维（Chain-of-Thought）方式分析输入，逐步优化生成结果
- **2K/4K 高分辨率输出**：支持超高清分辨率选项
- **多风格支持**：涵盖微距摄影、电影感、人像、产品摄影等多种风格
- **视角控制**：支持鱼眼、鸟瞰、低角度、微距等多种拍摄视角
### 工作流程
```mermaid
graph LR
A[输入源文件] --> B[输入主体描述]
B --> C[选择风格]
C --> D[Nano-Banana 推理引擎]
D --> E{分辨率选择}
E -->|2K| F[生成2K图像]
E -->|4K| G[生成4K图像]
F --> H[自动下载并预览]
G --> H
```
### 脚本使用
```bash
bash library/visual/nano-banana/scripts/generate-nano-art.sh \
--file ./my-source-image.jpg \
--subject "一只玻璃蜂鸟" \
--style "macro photography" \
--resolution "2k" \
--view
```
**参数说明**：
| 参数 | 必需 | 描述 |
|:---|:---:|:---|
| `--file` | 是 | 输入源图像文件路径 |
| `--subject` | 是 | 主体描述 |
| `--style` | 是 | 艺术风格（macro photography、cinematic、portrait 等） |
| `--resolution` | 否 | 输出分辨率（2k、4k），默认 2k |
| `--view` | 否 | 生成后自动打开预览 |
资料来源：[library/visual/nano-banana/SKILL.md]()
## UI Designer 界面设计
UI Designer 技能专注于生成高保真移动端和 Web 端界面设计稿，采用原子设计（Atomic Design）方法论构建可复用的设计系统。资料来源：[library/visual/ui-design/SKILL.md]()
### 设计方法论
该技能遵循原子设计的五级层次结构：
| 层级 | 描述 | 示例 |
|:---|:---|:---|
| 原子 | 基础UI组件 | 按钮、输入框、图标 |
| 分子 | 简单组件组合 | 搜索框（图标+输入框+按钮） |
| 有机体 | 复杂功能模块 | 导航栏、卡片组件 |
| 模板 | 页面骨架结构 | 列表页模板、表单页模板 |
| 页面 | 完整设计稿 | 登录页、个人中心页 |
### 脚本使用
```bash
bash library/visual/ui-design/scripts/generate-mockup.sh \
--type "mobile-app" \
--theme "modern-minimal" \
--output ./outputs/ui-mockup.png
```
支持生成类型包括：`mobile-app`、`web-dashboard`、`landing-page`、`e-commerce` 等。
资料来源：[library/visual/ui-design/SKILL.md]()
## Logo Creator 标识创作
Logo Creator 提供简洁高效的矢量风格品牌标识生成能力，通过几何原语构建专业级品牌视觉系统。资料来源：[library/visual/logo-creator/SKILL.md]()
### 设计特点
- **几何原语驱动**：使用基础几何形状构建复杂标识
- **品牌一致性**：生成标识时可同时输出品牌色板、字体配对建议
- **多格式输出**：支持 SVG、PNG、PDF 等多种格式
### 脚本使用
```bash
bash library/visual/logo-creator/scripts/create-logo.sh \
--name "TechCorp" \
--style "geometric" \
--colors "blue,white" \
--output ./outputs/logo.png
```
资料来源：[library/visual/logo-creator/SKILL.md]()
## 专业技能库
### 产品摄影类
| 技能 | 描述 | 适用场景 |
|:---|:---|:---|
| Action Figure Generator | 将人物照片转换为3D手办人偶造型 | 玩具、收藏品营销 |
| Amazon Product Listing | 亚马逊产品图组（主图+场景图+信息图+细节图） | 电商平台 |
| Photo Pack Generator | 多角度产品拍摄套组 | 产品展示 |
| Jewelry Product Video | 奢侈珠宝高定摄影与动画 | 高端品牌 |
### 品牌设计类
| 技能 | 描述 | 适用场景 |
|:---|:---|:---|
| Brand Kit | 品牌视觉套件（标识概念、色板、字体配对） | 品牌建设 |
| Brand Design Guide | 完整设计规范（色板、字体、UI组件、视觉规则） | 设计系统 |
| Logo + Branding Package | 标识+完整品牌包（深色/浅色/图标变体、色板、模型） | 品牌启动 |
| Logo Generator | 快速单次精致标识（干净矢量美学） | 快速原型 |
### 室内与空间设计
| 技能 | 描述 | 适用场景 |
|:---|:---|:---|
| Interior Design | 专业室内设计可视化 | 装修设计 |
| Interior Design Visualizer | 生成空房间并填充家具/装饰，或重设现有房间 | 室内软装 |
| Floor Plan Rendering | 2D平面图转3D建筑渲染 | 建筑设计 |
| Fashion Try-On | 虚拟试衣（人物照片+服装单品组合） | 时尚电商 |
### 社交媒体类
| 技能 | 描述 | 适用场景 |
|:---|:---|:---|
| YouTube Thumbnail | 高点击率YouTube缩略图 | 内容创作 |
| Instagram Post | 品牌风格Instagram帖子（主图+文案+标签） | 社交营销 |
| Social Media Pack | 主图转多平台比例（Instagram/TikTok/Shorts/X） | 跨平台运营 |
| RedNote Cover | 小红书封面图（活力生活方式美学） | 中文平台 |
资料来源：[README.md]()
## 模型支持
图像与设计技能库通过 `muapi-cli` 接入 100+ AI 图像生成模型：
### 主流模型
| 模型 | 类型 | 特点 |
|:---|:---|:---|
| Flux Kontext Pro | 图像编辑 | 提示词驱动的精准编辑 |
| Midjourney v7 | 通用生成 | 高美学质量 |
| HiDream Fast | 快速生成 | 速度快，适合预览 |
| HiDream | 高质量生成 | 细节丰富 |
| Kling 3.0 | 图生视频 | 图像转视频能力 |
| Seedance 2.0 | 视频生成 | 导演级电影效果 |
### 模型查询
```bash
# 列出所有图像模型
muapi models list --category image
# 查看具体模型参数
muapi models list --output-json | jq '.[] | select(.category == "image")'
```
资料来源：[README.md]()
## AI 代理集成
图像与设计技能库专为 AI 代理设计，支持多种集成方式：
### MCP 服务器模式
```bash
muapi mcp serve
```
在 Claude Desktop 配置中启用：
```json
{
"mcpServers": {
"muapi": {
"command": "muapi",
"args": ["mcp", "serve"],
"env": { "MUAPI_API_KEY": "your-key-here" }
}
}
}
```
### CLI 直接调用
```bash
# 生成图像并自动下载
muapi image generate "科技产品特写" --model flux-dev --download ./outputs
# 仅获取 URL（供代理后续处理）
muapi image generate "产品图" --model flux-schnell --output-json --jq '.outputs[0]'
```
### 执行代理技能
```bash
# 安装所有视觉技能
npx skills add SamurAIGPT/Generative-Media-Skills --skill muapi-visual
# 或安装到特定代理
npx skills add SamurAIGPT/Generative-Media-Skills --all -a claude-code -a cursor
```
资料来源：[README.md]()
## 常见工作流程
### 产品广告生成流程
```mermaid
graph TD
A[上传产品照片] --> B[Nano-Banana 增强处理]
B --> C[生成多角度视图]
C --> D[Interior Design 场景合成]
D --> E[AI Clipping 提取精华片段]
E --> F[Seedance 2.0 视频化]
F --> G[最终广告成品]
```
### 品牌设计流程
```mermaid
graph TD
A[品牌名称输入] --> B[Logo Creator 生成标识]
B --> C[Brand Kit 生成品牌套件]
C --> D[UI Designer 应用到界面]
D --> E[Social Pack 发布到各平台]
```
## 社区关注点
根据社区反馈，用户对以下功能表示关注：
- **发布到 Vynly**：Issue #89 中用户提议在媒体生成后添加一键发布到 Vynly 的技能，实现完整的生成到发布工作流
- **CUDA 加速**：Issue #70 中用户询问是否支持 CUDA 加速，目前图像生成主要依赖云端 API
- **多语言支持**：用户希望技能能支持不同语言的提示词处理，包括西班牙语等
## 环境要求
| 组件 | 要求 |
|:---|:---|
| muapi-cli | 最新版（npm 或 pip 安装） |
| curl | 系统自带 |
| jq | JSON 处理 |
| python3 | 脚本执行 |
| MUAPI_KEY | 通过 `muapi auth configure` 配置 |
资料来源：[core/edit/SKILL.md]()
## 下一步
- 探索 [运动与视频技能库](./motion-video-skills.md) 了解视频生成能力
- 查看 [MCP 服务器配置](./mcp-server.md) 了解代理集成详情
- 阅读 [架构设计文档](./architecture.md) 了解核心层与技能层交互
---
## 社交媒体技能库
### 相关页面
相关主题：[视频与动效技能库](#motion-skills), [图像与设计技能库](#visual-skills)
相关源码文件
以下源码文件用于生成本页说明：
- [library/social/youtube-shorts/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/youtube-shorts/SKILL.md)
- [library/social/youtube-shorts/scripts/run-youtube-shorts.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/youtube-shorts/scripts/run-youtube-shorts.sh)
- [library/social/instagram-post/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/instagram-post/SKILL.md)
- [library/social/product-campaign/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/product-campaign/SKILL.md)
- [library/social/rednote-cover/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/rednote-cover/SKILL.md)
- [library/social/social-media-video/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/social-media-video/SKILL.md)
# 社交媒体技能库
## 概述
社交媒体技能库是 Generative-Media-Skills 项目中专注于社交平台内容生成的专业技能集合。该技能库包含 5 个核心技能和 1 个视频处理技能，旨在帮助 AI Agent 自动化生成面向各大社交平台的营销内容和创意素材。
**核心功能定位：**
- 多平台适配：支持 Instagram、小红书 (RedNote)、YouTube Shorts、TikTok、抖音等多平台
- 一站式工作流：从素材输入到多平台分发的完整自动化流程
- AI 驱动的内容创作：利用 Nano-Banana、Seedance 2.0 等先进模型生成高质量内容
- UGC 风格支持：生成真实用户生成内容风格的口碑营销素材
**技能清单：**
| 技能名称 | 路径 | 描述 |
|:---|:---|:---|
| Instagram Post | `library/social/instagram-post/` | 品牌风格一致的 Instagram 帖子生成 |
| Product Campaign Pack | `library/social/product-campaign/` | 多渠道营销活动综合素材包 |
| RedNote Cover | `library/social/rednote-cover/` | 小红书封面图生成 |
| Social Media Pack | `library/social/social-pack/` | 主流社交平台多比例素材适配 |
| UGC Ads Workflow | `library/social/ugc-ads-workflow/` | UGC 风格视频广告制作流程 |
| YouTube Shorts | `library/social/youtube-shorts/` | 短视频平台垂直内容制作 |
资料来源：[README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
---
## 架构设计
### 技能分层模型
社交媒体技能库采用三层架构设计，实现从底层 API 调用到顶层创意策略的完整封装：
```mermaid
graph TD
A[社交媒体技能库] --> B[表现层 Skill]
A --> C[工作流层 Workflow]
A --> D[工具层 muapi-cli]
B --> B1[Instagram Post]
B --> B2[RedNote Cover]
B --> B3[Product Campaign]
C --> C1[UGC Ads Workflow]
C --> C2[YouTube Shorts]
D --> D1[muapi image generate]
D --> D2[muapi video generate]
D --> D3[muapi enhance]
style A fill:#f9f,color:#000
style D fill:#ff9,color:#000
```
### 核心执行流程
社交媒体内容的生成遵循标准的 AI Agent 工作流模式：
```mermaid
graph LR
A[输入素材] --> B[AI Agent 解析 SKILL.md]
B --> C[执行 muapi CLI 调用]
C --> D[生成主素材]
D --> E[多平台适配裁剪]
E --> F[输出多格式成品]
style B fill:#9ff,color:#000
style C fill:#9f9,color:#000
```
资料来源：[library/social/youtube-shorts/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/youtube-shorts/SKILL.md)
---
## 核心技能详解
### Instagram Post
**功能描述：** 生成符合品牌风格的专业 Instagram 帖子，包含主图、标题文案和话题标签推荐。
**输入参数：**
| 参数 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| subject | string | ✓ | 产品或内容主题 |
| brand_style | string | ○ | 品牌视觉风格要求 |
| keywords | string[] | ○ | 关键词用于 hashtag 生成 |
**输出产物：**
- 1080×1080 主图 (1:1 比例)
- 英文/双语 caption 文案
- 15-20 个相关话题标签
**执行脚本：**
```bash
bash library/social/instagram-post/scripts/generate-instagram.sh \
--subject "your product" \
--style "minimal luxury" \
--view
```
资料来源：[library/social/instagram-post/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/instagram-post/SKILL.md)
---
### RedNote Cover
**功能描述：** 专为小红书平台设计的封面图生成技能，强调生动活泼的生活美学和排版设计。
**设计特点：**
- 竖版 3:4 比例适配移动端浏览习惯
- 大标题 + 副标题双层文字排版
- 情感化视觉元素和人物主体突出
- 中文排版优化
**输出规格：**
| 属性 | 值 |
|:---|:---|
| 宽高比 | 3:4 |
| 推荐分辨率 | 1080×1440 |
| 主色调 | 活泼明亮 |
| 字体风格 | 中文手写体 + 粗体标题 |
**执行示例：**
```bash
bash library/social/rednote-cover/scripts/generate-rednote.sh \
--content "生活方式分享" \
--theme "温馨治愈" \
--view
```
资料来源：[library/social/rednote-cover/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/rednote-cover/SKILL.md)
---
### Product Campaign Pack
**功能描述：** 综合性的多渠道营销活动素材包，生成覆盖 Hero 视觉、社交资产、短视频和平台适配裁剪的完整素材集。
**生成素材类型：**
| 类型 | 用途 | 格式 |
|:---|:---|:---|
| Hero Visual | 主视觉 Banner | 1920×1080 横版 |
| Social Assets | 社交媒体用图 | 多比例裁剪 |
| Short Video | 短视频广告 | 9:16 竖版 |
| Platform Crops | Meta/Google/LinkedIn | 平台特定规格 |
**工作流配置：**
```mermaid
graph TD
A[产品图 + 品牌 Brief] --> B[生成 Hero 主图]
B --> C[分解为多平台素材]
C --> D[生成短视频广告]
D --> E[输出完整 Campaign 素材包]
B --> F[MuAPI: image generate]
D --> G[MuAPI: video generate]
style E fill:#9f9,color:#000
```
**执行命令：**
```bash
bash library/social/product-campaign/scripts/generate-campaign.sh \
--product-image "./product.jpg" \
--brand-brief "minimal, eco-friendly" \
--platforms "instagram,tiktok,facebook"
```
资料来源：[library/social/product-campaign/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/product-campaign/SKILL.md)
---
### Social Media Pack
**功能描述：** 将一张主素材自动转换为多个主流社交平台的适配版本，包括 Instagram、TikTok、Shorts (YouTube) 和 X (Twitter)。
**支持的平台比例：**
| 平台 | 比例 | 尺寸 |
|:---|:---|:---|
| Instagram Feed | 1:1 | 1080×1080 |
| Instagram Story | 9:16 | 1080×1920 |
| TikTok | 9:16 | 1080×1920 |
| YouTube Shorts | 9:16 | 1080×1920 |
| X (Twitter) | 16:9 | 1200×675 |
**执行脚本：**
```bash
muapi upload file ./hero-image.jpg --output-json
# 获取 URL 后执行裁剪
bash library/social/social-pack/scripts/generate-social-pack.sh \
--source-url "https://cdn.muapi.ai/..." \
--platforms all
```
---
### YouTube Shorts
**功能描述：** 基于 AI Clipping 技能的视频处理工作流，专门针对 YouTube Shorts、TikTok 和抖音等短视频平台优化。
**核心处理流程：**
```mermaid
graph TD
A[长视频输入] --> B[AI Clipping 智能剪辑]
B --> C[自动转录 + 时间轴]
C --> D[病毒性评分排名]
D --> E[人脸追踪自动裁剪]
E --> F[垂直 9:16 输出]
B -.->|服务端处理| G[无本地 Whisper]
B -.->|无本地 LLM| H[全云端推理]
style F fill:#9f9,color:#000
```
**关键特性：**
- **服务端转录**：无需本地 Whisper 模型，全云端处理
- **智能排序**：基于多维度评分自动排序高价值片段
- **去重机制**：自动识别并去除重复片段
- **人脸追踪**：自动保持人像在画面中心
**执行脚本：**
```bash
bash library/social/youtube-shorts/scripts/run-youtube-shorts.sh \
--video "./long-video.mp4" \
--platform "shorts" \
--max-clips 5 \
--aspect-ratio "9:16"
```
**参数说明：**
| 参数 | 默认值 | 说明 |
|:---|:---:|:---|
| --platform | shorts | 目标平台 (shorts/tiktok/reels) |
| --max-clips | 3 | 最大剪辑数量 |
| --aspect-ratio | 9:16 | 输出宽高比 |
| --language | auto | 视频语言检测 |
资料来源：[library/social/youtube-shorts/scripts/run-youtube-shorts.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/youtube-shorts/scripts/run-youtube-shorts.sh)
---
### UGC Ads Workflow
**功能描述：** 生成用户生成内容 (UGC) 风格的视频广告，将人物照片与产品图结合，创作真实感强的口碑营销素材。
**工作流组成：**
| 步骤 | 技能 | 输出 |
|:---|:---|:---|
| 1 | 人物自拍生成 | selfie-with-celebrities |
| 2 | 产品图合成 | 产品植入场景 |
| 3 | 文案撰写 | 脚本 + 配音 |
| 4 | 视频动画 | Seedance 2.0 i2v |
**执行流程：**
```mermaid
graph LR
A[人物照片] --> B[生成 UGC 风格自拍]
C[产品图片] --> D[产品植入]
B --> E[生成脚本]
D --> E
E --> F[Seedance 2.0 动画]
F --> G[10s 竖版 UGC 视频]
style G fill:#9f9,color:#000
```
**执行命令：**
```bash
bash library/social/ugc-ads-workflow/scripts/generate-ugc.sh \
--person "./person.jpg" \
--product "./product.jpg" \
--script "自然真实的使用体验分享" \
--view
```
资料来源：[library/social/ugc-ads-workflow/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/library/social/ugc-ads-workflow/SKILL.md)
---
## 社区反馈与功能建议
### 用户反馈的功能需求
根据 GitHub Issues 中的社区讨论，以下是用户对社交媒体相关内容的高频需求：
| 需求 | 状态 | 说明 |
|:---|:---:|:---|
| 发布到 Vynly 平台 | 功能建议 | Issue #89：用户希望在媒体生成后自动发布到 Vynly |
| 多语言内容支持 | 已支持 | 德语、西班牙语等非英语内容均可处理 |
| 本地文件批量导入 | 功能建议 | Issue #73：支持 NFS/CIFS 文件共享批量导入 |
**Issue #89 原文摘录：**
> "Generative-Media-Skills giving agents multi-modal generation is exactly the kind of workflow that needs a publish destination at the end."
该反馈指出当前工作流的局限：AI Agent 生成媒体内容后，成品仅保存在本地，缺乏直接的分发渠道集成能力。
### 常见问题排查
| 问题 | 原因 | 解决方案 |
|:---|:---|:---|
| 视频裁剪后人脸不居中 | 人脸追踪未启用 | 添加 `--face-track true` 参数 |
| 生成的 hashtag 不准确 | 关键词不足 | 增加 `--keywords` 参数提供更多上下文 |
| 平台比例不匹配 | 平台配置错误 | 检查 `--platform` 参数是否与目标平台匹配 |
---
## 快速上手指南
### 环境准备
```bash
# 安装 muapi-cli
npm install -g muapi-cli
# 配置 API Key
muapi auth configure --api-key "YOUR_MUAPI_KEY"
# 验证配置
muapi account balance
```
### 选择合适的技能
```mermaid
graph TD
A[需要生成什么内容?] --> B{内容类型}
B -->|单张图片| C{目标平台}
C -->|Instagram| D[Instagram Post]
C -->|小红书| E[RedNote Cover]
C -->|多平台| F[Social Media Pack]
B -->|视频内容| G{视频来源}
G -->|长视频剪辑| H[YouTube Shorts]
G -->|产品广告| I[UGC Ads Workflow]
G -->|综合活动| J[Product Campaign]
style D fill:#9f9,color:#000
style E fill:#9f9,color:#000
style F fill:#9f9,color:#000
style H fill:#9f9,color:#000
style I fill:#9f9,color:#000
style J fill:#9f9,color:#000
```
### 典型使用场景
**场景 1：新品发布社交媒体同步**
```bash
# 1. 生成 Instagram 帖子
bash library/social/instagram-post/scripts/generate-instagram.sh \
--subject "NEW PRODUCT LAUNCH" --view
# 2. 生成小红书封面
bash library/social/rednote-cover/scripts/generate-rednote.sh \
--content "新品首发" --view
# 3. 生成多平台素材包
bash library/social/social-pack/scripts/generate-social-pack.sh \
--source-url "https://..." --platforms all
```
**场景 2：KOL 风格 UGC 广告**
```bash
# 人物 + 产品 → UGC 视频广告
bash library/social/ugc-ads-workflow/scripts/generate-ugc.sh \
--person "./influencer.jpg" \
--product "./product.jpg" \
--script "真实使用体验分享" \
--view
```
**场景 3：长视频内容再利用**
```bash
# YouTube 长视频 → Shorts 剪辑
bash library/social/youtube-shorts/scripts/run-youtube-shorts.sh \
--video "./webinar.mp4" \
--platform shorts \
--max-clips 10
```
---
## 技术规格总结
| 属性 | 规格 |
|:---|:---|
| 支持平台 | Instagram, TikTok, YouTube, 小红书, Facebook, LinkedIn |
| 图片输出格式 | JPG/PNG, 最大 4096×4096 |
| 视频输出格式 | MP4 (H.264), 最大 1080×1920 |
| 音频支持 | MMAudio 音效生成, Suno 音乐生成 |
| 处理方式 | 全云端 API 调用, 无本地模型依赖 |
**与底层工具集成：**
| MuAPI 工具 | 用途 |
|:---|:---|
| `muapi_image_generate` | 社交图片生成 |
| `muapi_video_generate` | 短视频生成 |
| `muapi_enhance_upscale` | 图片质量增强 |
| `muapi_upload_file` | 素材上传 |
| `muapi_clipping` | AI 视频剪辑 |
资料来源：[README.md - MuAPI Tools](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
---
## 扩展与集成建议
### 发布到外部平台
当前版本 (v0.1.0) 的社交媒体技能库专注于内容生成阶段。社区反馈 (Issue #89) 建议在后续版本中增加：
- **Vynly MCP 集成**：自动将生成的媒体发布到 Vynly 平台
- **其他社交平台 API**：Twitter/X、LinkedIn 企业账号直连
- **本地文件系统输出**：支持保存到网络共享 (NFS/CIFS)
### 批量处理工作流
对于企业级用户，建议通过 AI Agent 编排实现批量社交媒体内容生成：
```bash
# 示例：批量处理产品目录
for product in ./products/*; do
muapi upload file "$product" --output-json
# 调用各平台技能生成...
done
```
---
## 相关资源
- **核心技能库**：查看 [Core Primitives](../core/) 了解底层 API 调用方式
- **视觉技能库**：查看 [Visual Skills](../library/visual/) 了解图片生成能力
- **视频技能库**：查看 [Motion Skills](../library/motion/) 了解视频制作能力
- **MuAPI CLI 文档**：[muapi-cli npm package](https://www.npmjs.com/package/muapi-cli)
---
## MCP服务器集成
### 相关页面
相关主题：[快速入门指南](#quick-start), [系统架构设计](#system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
# MCP服务器集成
## 概述
MCP（Model Context Protocol）服务器集成是 Generative-Media-Skills 项目为 AI 代理提供的核心功能之一。通过运行 `muapi mcp serve` 命令，可以将 muapi.ai 平台的所有多媒体生成工具以结构化的 MCP 工具形式暴露给支持 MCP 协议的 AI 代理客户端（如 Claude Desktop、Cursor、Windsurf 等）。[资料来源：README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
这种集成方式使 AI 代理无需通过 shell 脚本或命令行调用，即可直接调用多媒体生成工具，实现了**零脚本、零 JSON 解析**的原生代理体验。
## 架构设计
### 系统组件关系
```mermaid
graph TD
A[AI 代理客户端
Claude Desktop / Cursor / Windsurf] --> B[MCP Server
muapi mcp serve]
B --> C[muapi-cli 核心引擎]
C --> D[muapi.ai API]
D --> E[多媒体生成服务]
F[19个MCP工具] --> B
G[JSON Schema
输入/输出定义] --> F
```
### 工具分类总览
| 类别 | 工具数量 | 功能描述 |
|:---|:---:|:---|
| 图像生成 | 1 | 文本转图像（14种模型） |
| 图像编辑 | 1 | 图像转图像编辑（11种模型） |
| 视频生成 | 2 | 文本转视频、图像转视频 |
| 音频处理 | 2 | 音乐生成、音效合成 |
| 增强处理 | 4 | AI放大、背景移除、人脸交换、Ghibli风格转换 |
| 编辑功能 | 2 | 唇形同步、AI剪辑 |
| 账户管理 | 4 | API密钥管理、余额查询、充值 |
| 文件操作 | 1 | 本地文件上传至CDN |
## 快速配置
### 1. 启动 MCP 服务器
```bash
muapi mcp serve
```
该命令会在本地启动 MCP 服务器，默认监听标准 MCP 协议端口。[资料来源：README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
### 2. Claude Desktop 配置
编辑 Claude Desktop 配置文件：
**macOS 路径：** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows 路径：** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"muapi": {
"command": "muapi",
"args": ["mcp", "serve"],
"env": {
"MUAPI_API_KEY": "your-key-here"
}
}
}
}
```
### 3. API Key 配置
确保在环境变量中配置有效的 muapi.ai API Key：
```bash
# 方式一：通过环境变量
export MUAPI_API_KEY="your-api-key"
# 方式二：通过 muapi-cli 配置
muapi auth configure --api-key "your-api-key"
```
获取 API Key：访问 [https://muapi.ai/dashboard](https://muapi.ai/dashboard)
## MCP 工具清单
### 媒体生成工具
| 工具名称 | 输入参数 | 输出 | 模型支持 |
|:---|:---|:---|:---|
| `muapi_image_generate` | prompt, model, aspect_ratio, resolution | 图像URL数组 | 14种模型（Flux、Midjourney等） |
| `muapi_image_edit` | prompt, image, model | 图像URL | 11种模型 |
| `muapi_video_generate` | prompt, model, duration | 视频URL | 13种模型 |
| `muapi_video_from_image` | image, prompt, model | 视频URL | 16种模型 |
### 音频生成工具
| 工具名称 | 输入参数 | 输出 | 服务 |
|:---|:---|:---|:---|
| `muapi_audio_create` | prompt, style | 音频URL | Suno 音乐生成 |
| `muapi_audio_from_text` | text, type | 音频URL | MMAudio 音效 |
### 增强处理工具
| 工具名称 | 操作类型 | 输入 | 输出 |
|:---|:---|:---|:---|
| `muapi_enhance_upscale` | upscale | 图像URL | 高分辨率图像 |
| `muapi_enhance_bg_remove` | background-remove | 图像URL | 透明背景图像 |
| `muapi_enhance_face_swap` | face-swap | 图像/视频 + 人脸 | 换脸结果 |
| `muapi_enhance_ghibli` | ghibli-style | 图像URL | 吉卜力风格图像 |
### 编辑工具
| 工具名称 | 功能 | 输入 | 输出 |
|:---|:---|:---|:---|
| `muapi_edit_lipsync` | 唇形同步 | 视频 + 音频 | 同步后视频 |
| `muapi_edit_clipping` | AI剪辑 | 长视频 | 精选片段 |
### 账户管理工具
| 工具名称 | 功能描述 |
|:---|:---|
| `muapi_keys_list` | 列出所有API密钥 |
| `muapi_keys_create` | 创建新API密钥 |
| `muapi_keys_delete` | 删除指定API密钥 |
| `muapi_account_balance` | 查询账户余额 |
| `muapi_account_topup` | 充值（Stripe结账） |
### 文件操作工具
| 工具名称 | 功能描述 |
|:---|:---|
| `muapi_upload_file` | 上传本地文件并返回CDN URL |
## 工作流程示例
### 异步视频生成与轮询
```mermaid
sequenceDiagram
participant Agent as AI代理
participant MCP as MCP Server
participant API as muapi.ai API
participant Storage as 存储服务
Agent->>MCP: muapi_video_generate
"a dog running" --model kling-v3.0-pro
MCP->>API: 提交异步请求
API-->>MCP: 返回 request_id
MCP-->>Agent: { request_id: "xxx", status: "pending" }
Agent->>MCP: muapi_predict_result --id "xxx"
API-->>MCP: { status: "processing" }
MCP-->>Agent: { status: "processing" }
Agent->>MCP: muapi_predict_result --id "xxx"
API-->>MCP: { status: "completed", outputs: [...] }
MCP-->>Agent: 视频生成完成
```
### 典型代理对话流程
```mermaid
graph LR
A[用户请求] --> B[Claude Desktop
解析意图]
B --> C[MCP工具调用
muapi_image_generate]
C --> D[返回结构化JSON]
D --> E[代理整合结果]
E --> F[用户响应]
```
## JSON Schema 规范
每个 MCP 工具都提供完整的 JSON Schema 定义，包含：
- **输入模式（inputSchema）**：定义必需参数和可选参数
- **输出模式（outputSchema）**：定义返回数据结构
- **描述文档**：每个参数的用途和类型说明
```json
{
"name": "muapi_image_generate",
"description": "Generate image from text prompt",
"inputSchema": {
"type": "object",
"properties": {
"prompt": { "type": "string" },
"model": { "type": "string", "enum": ["flux-dev", "flux-schnell", ...] },
"aspect_ratio": { "type": "string" },
"resolution": { "type": "string" }
},
"required": ["prompt"]
}
}
```
## 兼容客户端
| 客户端 | 支持状态 | 配置方式 |
|:---|:---:|:---|
| Claude Desktop | ✅ 完全支持 | claude_desktop_config.json |
| Cursor | ✅ 完全支持 | MCP设置面板 |
| Windsurf | ✅ 完全支持 | MCP配置 |
| Gemini CLI | ✅ 兼容 | 环境变量 + 直接调用 |
| 自定义 MCP 客户端 | ✅ 兼容 | 标准 MCP 协议 |
## 常见问题
### Q1: MCP 服务器启动失败
**症状：** 执行 `muapi mcp serve` 无响应或报错
**解决方案：**
1. 确认已安装 muapi-cli：`npm install -g muapi-cli`
2. 检查 API Key 配置是否正确
3. 验证网络连接：确保能访问 muapi.ai
### Q2: 工具调用超时
**症状：** 调用生成工具后长时间无响应
**解决方案：**
使用异步模式 + 轮询机制：
```bash
# 提交任务（不等待）
muapi video generate "prompt" --model kling-v3.0-pro --no-wait
# 获取 request_id 后轮询结果
muapi predict wait "request-id" --download ./outputs
```
### Q3: API Key 无效
**症状：** 返回认证错误
**解决方案：**
```bash
muapi auth configure --api-key "your-new-key"
```
## 与传统 CLI 的对比
| 特性 | MCP Server 模式 | CLI 脚本模式 |
|:---|:---:|:---:|
| 调用方式 | 结构化工具调用 | shell 命令执行 |
| 结果处理 | 自动 JSON 解析 | 需要 `--output-json --jq` |
| 代理友好度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| 实时流输出 | 支持 | 支持 |
| 错误处理 | 结构化错误 | 文本解析 |
## 相关资源
- muapi-cli 官方文档：[https://www.npmjs.com/package/muapi-cli](https://www.npmjs.com/package/muapi-cli)
- muapi.ai 平台：[https://muapi.ai/dashboard](https://muapi.ai/dashboard)
- MCP 协议规范：[Model Context Protocol](https://modelcontextprotocol.io/)
## 扩展阅读
- [核心脚本模块](../core/index.md)
- [专家技能库](../library/index.md)
- [工具链概览](../tools/index.md)
- [快速入门指南](../getting-started/index.md)
---
## 常见问题与故障排除
### 相关页面
相关主题：[快速入门指南](#quick-start), [核心原语层详解](#core-primitives)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
- [core/platform/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/platform/SKILL.md)
- [core/platform/setup.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/platform/setup.sh)
- [core/platform/check-result.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/platform/check-result.sh)
- [core/edit/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/edit/SKILL.md)
# 常见问题与故障排除
本文档汇集了 Generative-Media-Skills 项目在使用过程中常见的问题及其解决方案，涵盖环境配置、API 集成、媒体生成和运行时问题等多个方面。
## 环境配置问题
### muapi-cli 安装失败
**问题描述**：使用 npm 或 pip 安装 muapi-cli 时出现错误。
**解决方案**：
```bash
# 通过 npm 安装（推荐，无需 Python 环境）
npm install -g muapi-cli
# 或通过 pip 安装
pip install muapi-cli
# 或直接运行而不安装
npx muapi-cli --help
```
**参考资料**：[README.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
### API Key 配置异常
**问题描述**：配置 API Key 后无法正常调用 API，提示认证失败。
**解决方案**：确保 API Key 正确配置并验证其有效性。
```bash
# 交互式配置
muapi auth configure
# 直接指定 API Key
muapi auth configure --api-key "YOUR_MUAPI_KEY"
# 测试 API Key 是否有效
bash core/platform/setup.sh --test
# 查看当前配置
bash core/platform/setup.sh --show-config
```
**API Key 验证流程**：
```mermaid
graph TD
A[开始配置] --> B[检查 MUAPI_KEY 环境变量]
B --> C{Key 是否存在?}
C -->|是| D[测试 API 连接]
C -->|否| E[提示配置 Key]
D --> F{连接成功?}
F -->|是| G[配置完成]
F -->|否| H[检查 Key 有效性]
H --> I[重新获取 Key]
```
**参考资料**：[core/platform/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/platform/SKILL.md)
### Ubuntu 服务器依赖缺失
**问题描述**：在 Ubuntu 服务器上安装依赖时缺少必要的开发工具。
**解决方案**：根据社区反馈，安装以下依赖：
```bash
apt install python3-dev make g++
pip install wheel
pip install -r requirements.txt
```
同时确保安装正确版本的 NodeJS：
```bash
curl -sL https://deb.nodesource.com/setup_18.x | sudo bash -
```
**参考资料**：[GitHub Issue #43](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/43)
## 媒体生成问题
### 图像生成返回乱码或异常响应
**问题描述**：模型训练后生成的响应出现乱码，如 `"H9E,:?&+8&1<*<2E(#!=)G68/?5C/BGC,..."`。
**可能原因**：
1. 模型加载不完整或损坏
2. 编码处理错误
3. 模型与输入数据不兼容
**解决方案**：
1. 重新下载并验证模型文件完整性
2. 确保上传的文档使用 UTF-8 编码
3. 检查训练数据集的质量和格式
**参考资料**：[GitHub Issue #39](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/39)
### 图像编辑操作失败
**问题描述**：使用 `edit-image.sh` 进行图像编辑时请求失败。
**基本用法**：
```bash
bash core/edit/edit-image.sh \
--image-url "https://example.com/image.jpg" \
--prompt "添加太阳镜" \
--model flux-kontext-pro
```
**支持的操作类型**：
| 操作 | 命令参数 | 说明 |
|:---|:---|:---|
| 提示词编辑 | `--op edit` | 基于文本提示修改图像 |
| 超分辨率 | `--op upscale` | 提升图像分辨率 |
| 背景移除 | `--op background-remove` | 移除图像背景 |
| 人脸替换 | `--op face-swap` | 换脸操作 |
| 吉卜力风格 | `--op ghibli` | 转换为吉卜力动画风格 |
**参考资料**：[core/edit/SKILL.md](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/edit/SKILL.md)
### 异步任务结果查询
**问题描述**：提交异步生成任务后无法获取结果。
**解决方案**：使用 `check-result.sh` 脚本查询任务状态。
```bash
# 持续轮询直到完成
bash core/platform/check-result.sh --id "your-request-id"
# 单次查询（不轮询）
bash core/platform/check-result.sh --id "your-request-id" --once
```
**异步任务流程**：
```mermaid
graph LR
A[提交任务] --> B[获取 request_id]
B --> C[轮询状态]
C --> D{完成?}
D -->|否| C
D -->|是| E[获取结果]
E --> F[下载媒体]
```
**参考资料**：[core/platform/check-result.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/platform/check-result.sh)
## 性能与加速问题
### GPU 加速支持
**问题描述**：用户询问是否支持 GPU 加速以加快处理速度。
**当前状态**：本项目主要依赖 muapi.ai 云端 API 服务，GPU 加速由服务端处理。客户端本地运行不受 GPU 限制影响。
**提升响应速度的建议**：
1. 使用更快的生成模型（如 `--model flux-schnell`）
2. 减少输入内容的复杂度
3. 使用异步模式处理批量任务
```bash
# 异步提交（不等待完成）
muapi video generate "a dog running" \
--model kling-master \
--no-wait \
--output-json
# 后续再查询结果
muapi predict wait "$REQUEST_ID" --download ./outputs
```
**参考资料**：[GitHub Issue #7](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/7)、[GitHub Issue #16](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/16)
### CUDA 支持
**问题描述**：用户询问是否支持 CUDA 进行本地计算加速。
**当前状态**：本项目的设计架构使用云端 API，CUDA 相关计算在 muapi.ai 服务端处理。客户端无需配置本地 CUDA 环境。
**参考资料**：[GitHub Issue #70](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/70)
## 运行时错误
### 500 内部服务器错误
**问题描述**：上传文档后提问时收到 500 Internal Server Error。
**错误信息**：
```
Error getting data.
500 Internal Server Error
Internal Server Error
The server encountered an internal error...
```
**可能原因**：
1. 服务器过载
2. 上传的文档处理异常
3. 后端服务暂时不可用
**建议操作**：
1. 稍后重试
2. 尝试重新上传文档
3. 检查文档格式是否受支持（PDF、DOCX、PPT 等）
4. 减小文档大小后重试
**参考资料**：[GitHub Issue #27](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/27)
### npm run dev 挂起
**问题描述**：在 PowerShell 中运行 `npm run dev` 时卡在某个点不继续。
**错误信息**：
```
Import trace for requested module:
./node_modules/next/dist/lib/is-api-route.js
./node_modules/next/dist/shared/lib/router/router.js
./node_modules/next/dist/lib/is-error.js
```
**解决方案**：
1. 清理 node_modules 并重新安装：
```bash
rm -rf node_modules package-lock.json
npm install
```
2. 确保使用正确版本的 NodeJS：
```bash
node --version # 应为 v18.x 或更高
```
3. 检查是否有端口冲突：
```bash
# Windows
netstat -ano | findstr :3000
# Linux/Mac
lsof -i :3000
```
**参考资料**：[GitHub Issue #34](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/34)、[GitHub Issue #45](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/45)
### 模型下载错误
**问题描述**：下载模型时进度达到 100% 后出现错误。
**错误信息**：
```
Download Progress: 100.0%
Found model file.
gptj_model_load: loading model from 'models/ggml-gpt4all-j-v1.3-groovy.bin'
```
**解决方案**：
1. 检查模型文件是否完整下载
2. 验证模型文件的 SHA256 校验和
3. 删除损坏的文件后重新下载
**注意**：如果使用的是 GPT4All 模型，该库不支持 GPU 加速。如需 GPU 支持，建议使用支持 CUDA 的模型如 Llama。
**参考资料**：[GitHub Issue #38](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/38)、[GitHub Issue #44](https://github.com/SamurAIGPT/Generative-Media-Skills/issues/44)
## CLI 使用问题
### 命令执行无响应
**问题描述**：执行 muapi 命令后无输出或无响应。
**排查步骤**：
```mermaid
graph TD
A[命令无响应] --> B[检查 API Key]
B --> C{Key 有效?}
C -->|否| D[重新配置 Key]
C -->|是| E[检查网络连接]
E --> F{网络正常?}
F -->|否| G[检查代理设置]
F -->|是| H[查看详细日志]
H --> I[使用 --json 输出]
```
**常用诊断命令**：
```bash
# 显示完整配置
muapi auth configure --show-config
# 测试 API 连接
muapi auth configure --test
# 列出可用模型
muapi models list
# 查看特定类别模型
muapi models list --category video --output-json
```
**参考资料**：[core/platform/setup.sh](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/core/platform/setup.sh)
### 输出格式问题
**问题描述**：需要以特定格式提取命令输出用于脚本处理。
**解决方案**：使用 `--output-json` 和 `--jq` 参数进行格式化输出。
```bash
# 获取纯 URL 输出
muapi image generate "a sunset" \
--model flux-schnell \
--output-json \
--jq '.outputs[0]'
# 提取 request_id
REQUEST_ID=$(muapi video generate "a dog running" \
--model kling-master \
--no-wait \
--output-json \
--jq '.request_id' | tr -d '"')
```
**管道组合示例**：
```bash
# 上传 → 编辑 → 下载
URL=$(muapi upload file ./photo.jpg \
--output-json \
--jq '.url' | tr -d '"')
muapi image edit "make it look like a painting" \
--image "$URL" \
--model flux-kontext-pro \
--download ./outputs
```
## MCP 服务器问题
### MCP Server 连接失败
**问题描述**：无法通过 MCP 协议连接到 muapi 服务。
**解决方案**：
1. 启动 MCP 服务器：
```bash
muapi mcp serve
```
2. 配置 Claude Desktop（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"muapi": {
"command": "muapi",
"args": ["mcp", "serve"],
"env": { "MUAPI_API_KEY": "your-key-here" }
}
}
}
```
3. 验证 MCP 工具列表是否包含所有 19 个工具：
| 工具类别 | 工具数量 | 说明 |
|:---|:---:|:---|
| 图像生成 | 1 | Text-to-image |
| 图像编辑 | 1 | Image-to-image |
| 视频生成 | 2 | 文本/图像转视频 |
| 音频创建 | 2 | 音乐/音效 |
| 图像增强 | 4 | 超分/背景移除/人脸替换/风格化 |
| 视频编辑 | 2 | 唇同步/AI剪辑 |
| 文件操作 | 1 | 文件上传 |
| 密钥管理 | 3 | 列出/创建/删除 |
| 账户管理 | 2 | 余额/充值 |
**参考资料**：[README.md - MCP Server 部分](https://github.com/SamurAIGPT/Generative-Media-Skills/blob/main/README.md)
## 故障排除工具
### 常用诊断脚本
| 脚本路径 | 功能 | 用法 |
|:---|:---|:---|
| `core/platform/setup.sh` | API Key 配置与验证 | `bash setup.sh --test` |
| `core/platform/check-result.sh` | 异步任务状态查询 | `bash check-result.sh --id "xxx"` |
| `core/edit/edit-image.sh` | 图像编辑操作 | `bash edit-image.sh --image-url "..." --prompt "..."` |
| `core/edit/enhance-image.sh` | 图像增强操作 | `bash enhance-image.sh --op upscale --image-url "..."` |
### 环境变量检查
确保以下环境变量正确设置：
```bash
# 检查 API Key
echo $MUAPI_API_KEY
# 设置 API Key（如果缺失）
export MUAPI_API_KEY="your-api-key-here"
```
### 依赖验证
```bash
# 验证 curl
curl --version
# 验证 jq
jq --version
# 验证 Python3
python3 --version
# 验证 muapi-cli
muapi --version
```
## 获取帮助
如果以上方案均无法解决您的问题：
1. 搜索 [GitHub Issues](https://github.com/SamurAIGPT/Generative-Media-Skills/issues) 查看是否已有类似问题
2. 创建新 Issue 并提供以下信息：
- 操作系统和版本
- muapi-cli 版本（`muapi --version`）
- 完整的错误信息
- 复现步骤
3. 访问 [muapi.ai](https://muapi.ai/dashboard) 检查账户状态和 API 余额
---
---
## Doramagic 踩坑日志
项目：SamurAIGPT/Generative-Media-Skills
摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Optional: add a 'publish to Vynly' skill after media generation?。
## 1. 安全/权限坑 · 来源证据：Optional: add a 'publish to Vynly' skill after media generation?
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Optional: add a 'publish to Vynly' skill after media generation?
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e801ed325bcf4fbbb8e0d9cac02b5f7f | https://github.com/SamurAIGPT/Generative-Media-Skills/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `generative-media-skills` 与安装入口 `skills` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx skills`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:645381450 | https://github.com/SamurAIGPT/Generative-Media-Skills | repo=generative-media-skills; install=skills
## 3. 安装坑 · 来源证据：Error downloading model
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Error downloading model
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ec1cdc92d8c84b2bbce43cf37a668443 | https://github.com/SamurAIGPT/Generative-Media-Skills/issues/44 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：Server install pre-requisites on Ubuntu
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Server install pre-requisites on Ubuntu
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c7a0e07d61b547aba3280ac82ac305e2 | https://github.com/SamurAIGPT/Generative-Media-Skills/issues/43 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：install vicuna13b?
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：install vicuna13b?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c6ace8e72f95491f945200849e083d96 | https://github.com/SamurAIGPT/Generative-Media-Skills/issues/46 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 安装坑 · 来源证据：npm run dev error
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：npm run dev error
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_de5cf59443c74838a8d10d1ecbec9457 | https://github.com/SamurAIGPT/Generative-Media-Skills/issues/45 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 安装坑 · 来源证据：npm run dev hang in certain point
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：npm run dev hang in certain point
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8082f7c5e7be496c89fac789d932e74c | https://github.com/SamurAIGPT/Generative-Media-Skills/issues/34 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 8. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:645381450 | https://github.com/SamurAIGPT/Generative-Media-Skills | host_targets=claude, claude_code, cursor
## 9. 配置坑 · 来源证据：Model download error on 100% progress
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Model download error on 100% progress
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_14498a89412f40ceb03d61889ea96de2 | https://github.com/SamurAIGPT/Generative-Media-Skills/issues/38 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 10. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:645381450 | https://github.com/SamurAIGPT/Generative-Media-Skills | README/documentation is current enough for a first validation pass.
## 11. 运行坑 · 来源证据：500 Internal Server Error
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：500 Internal Server Error
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_36c10c9b7ece4b10af4873b655817add | https://github.com/SamurAIGPT/Generative-Media-Skills/issues/27 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 12. 运行坑 · 来源证据：Error Fetching Answer. Please try again.
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Error Fetching Answer. Please try again.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a8e460757f114a9d8e4357758c834524 | https://github.com/SamurAIGPT/Generative-Media-Skills/issues/54 | 来源类型 github_issue 暴露的待验证使用条件。
## 13. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:645381450 | https://github.com/SamurAIGPT/Generative-Media-Skills | last_activity_observed missing
## 14. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:645381450 | https://github.com/SamurAIGPT/Generative-Media-Skills | no_demo; severity=medium
## 15. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:645381450 | https://github.com/SamurAIGPT/Generative-Media-Skills | no_demo; severity=medium
## 16. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:645381450 | https://github.com/SamurAIGPT/Generative-Media-Skills | issue_or_pr_quality=unknown
## 17. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:645381450 | https://github.com/SamurAIGPT/Generative-Media-Skills | release_recency=unknown