概述

Generative-Media-Skills 是一个面向 AI 代理的多模态媒体生成技能库，旨在为 Claude Code、Cursor、Gemini CLI 等主流 AI 开发环境提供专业级的图像、视频和音频生成能力。该项目通过结构化的 CLI 工具和 MCP（Model Context Protocol）服务器，将复杂的生成式 AI 能力封装为可组合的工作流程，使 AI 代理能够自主完成从创意构思到成品产出的完整媒体制作流程。资料来源：README.md:1-5

核心设计理念

Agent 原生架构

项目采用"Agent 原生"（Agent-Native Design）的设计理念，所有工具都针对 AI 代理的使用场景进行了优化：

• 结构化 JSON 输出：所有命令返回格式化的 JSON 数据，便于 AI 解析和处理
• 语义化退出码：成功、失败、部分成功等状态通过明确的退出码标识
• --jq 过滤支持：内置 JSON 数据过滤功能，支持从复杂响应中提取所需字段
• 异步任务处理：支持异步提交任务并轮询结果，适合长时间运行的生成任务

资料来源：README.md:45-50

专业知识层

项目不仅仅是简单的 API 封装，还包含了多个领域的专业知识库：

资料来源：README.md:55-60

系统架构

Core/Library 分层架构

项目采用 Core/Library 分层架构以确保高效性和高信号发现：

graph TD
    A[AI Agent] --> B[Expert Library 专家知识层]
    A --> C[Core Primitives 核心原语]
    B --> D[muapi-cli]
    C --> D
    D --> E[muapi.ai API]
    E --> F[Image Generation 图像生成]
    E --> G[Video Generation 视频生成]
    E --> H[Audio Generation 音频生成]
    E --> I[Media Editing 媒体编辑]

核心原语层（/core）

核心原语层是对 muapi-cli 的轻量封装，提供底层 API 访问能力：

资料来源：README.md:62-68

专家技能库（/library）

专家技能库包含 41+ 个预置工作流配方，每个配方都是一个 SKILL.md 文件，AI 代理可直接读取并执行：

视频制作类（16 个）

资料来源：README.md:100-125

视觉设计类（21 个）

资料来源：README.md:130-150

社交媒体类（5 个）

资料来源：README.md:152-158

MCP 服务器

项目提供完整的 Model Context Protocol 服务器实现，使 AI 代理可以直接调用生成工具：

graph LR
    A[Claude Desktop / Cursor] --> B[MCP Server]
    B --> C[19 Structured Tools]
    C --> D[muapi.ai Platform]
    D --> E[100+ AI Models]

暴露的工具列表

资料来源：README.md:165-190

快速开始

安装 muapi CLI

项目核心脚本需要 muapi-cli，可通过以下方式安装：

# via npm（推荐）
npm install -g muapi-cli

# via pip
pip install muapi-cli

# 无需安装，直接运行
npx muapi-cli --help

资料来源：README.md:200-210

配置 API 密钥

# 交互式配置
muapi auth configure

# 或直接传入密钥
muapi auth configure --api-key "YOUR_MUAPI_KEY"

# 获取密钥地址：https://muapi.ai/dashboard

资料来源：README.md:215-225

安装技能到 AI 代理

# 安装所有技能
npx skills add SamurAIGPT/Generative-Media-Skills --all

# 安装特定技能
npx skills add SamurAIGPT/Generative-Media-Skills --skill muapi-media-generation

# 指定代理平台
npx skills add SamurAIGPT/Generative-Media-Skills --all -a claude-code -a cursor

资料来源：README.md:230-240

核心功能示例

图像生成

# 基础图像生成
muapi image generate "a cyberpunk city at night" --model flux-dev

# 自动下载到指定目录
muapi image generate "a sunset over mountains" --model hidream-fast --download ./outputs

# 提取纯 URL（适合代理处理）
muapi image generate "product on white bg" --model flux-schnell --output-json --jq '.outputs[0]'

资料来源：README.md:245-255

异步视频生成与轮询

# 提交异步任务，捕获 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

资料来源：README.md:260-270

管道式工作流

# 上传 → 编辑 → 下载
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

资料来源：README.md:275-280

媒体编辑与增强

核心编辑模块提供了丰富的媒体处理能力：

资料来源：core/edit/SKILL.md:1-25

编辑命令示例

# 提示词编辑
bash edit-image.sh --image-url "https://..." --prompt "add sunglasses" --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

资料来源：core/edit/SKILL.md:30-45

平台配置与轮询

平台工具提供认证配置和异步任务管理功能：

资料来源：core/platform/SKILL.md:1-20

平台命令示例

# 保存 API 密钥
bash setup.sh --add-key "YOUR_MUAPI_KEY"

# 显示当前配置
bash setup.sh --show-config

# 测试 API 密钥有效性
bash setup.sh --test

# 轮询等待结果
bash check-result.sh --id "your-request-id"

# 单次查询（不轮询）
bash check-result.sh --id "your-request-id" --once

资料来源：core/platform/SKILL.md:25-40

专业技能详解

Cinema Director

Cinema Director 是一个专业技术电影导演技能库，封装了专业的 cinematography 知识和电影制作流程：

graph TD
    A[User Input] --> B[Intent Analysis]
    B --> C[Cinematography Planning]
    C --> D[Shot Composition]
    C --> E[Lighting Design]
    C --> F[Camera Movement]
    D --> G[Seedance 2.0 Generation]
    E --> G
    F --> G
    G --> H[Final Video Output]

资料来源：library/motion/cinema-director/SKILL.md:1-10

Nano-Banana

Nano-Banana 是推理驱动的图像生成技能，采用 Gemini 3 风格的思考链来优化生成质量：

• 支持 2K 分辨率输出
• 智能主体识别与风格迁移
• 自动视角优化

资料来源：library/visual/nano-banana/SKILL.md:1-10

支持的 AI 模型

项目通过 muapi.ai 平台支持 100+ 种 AI 模型，涵盖图像、视频、音频三大领域：

图像生成模型（14 种）

Flux 系列、Midjourney v7、Seedance、DALL-E、Stable Diffusion 等主流模型。

视频生成模型（13 种）

Kling 3.0、Seedance 2.0、Veo3、Luma Dream Machine 等。

图像转视频模型（16 种）

支持多种 i2v 模型，包括专业级和快速生成模式。

资料来源：README.md:190-200

命令行工具

所有脚本支持以下通用参数：

资料来源：core/edit/SKILL.md:48-55

兼容性

项目针对新一代 AI 开发环境进行了优化：

资料来源：README.md:285-295

许可证

MIT © 2026

社区反馈与常见问题

根据社区讨论，用户关注的主要问题包括：

资料来源：社区上下文

优势说明

相比本地部署方案，本项目通过云端 muapi.ai 平台处理生成任务，有效解决了以下问题：

1. 性能瓶颈：云端 GPU 集群提供高性能计算，响应速度快
2. 模型更新：100+ 模型自动更新，无需手动维护
3. 部署简化：无需配置 Docker 或复杂的依赖环境
4. 跨平台兼容：npm/pip 安装，开箱即用

快速入门指南

本文档为 AI Agent（Claude Code、Cursor、WindSurf 等）提供 Generative-Media-Skills 的完整安装与使用指南。通过本指南，您将能够快速配置 muapi-cli 环境、调用 100+ AI 模型生成专业级图像、视频和音频内容。

概述

Generative-Media-Skills 是一个面向 AI Agent 的多模态媒体生成工具集，采用 Core/Library 双层架构，将底层 API 封装与领域专家知识分离，使 AI 代理能够生成、编辑和展示专业级图像、视频和音频内容 资料来源：README.md

该架构的核心设计理念是：

• Agent 原生设计 — CLI 驱动的脚本配合结构化 JSON 输出，支持 --jq 过滤和语义化退出码，便于 AI 代理自动化执行
• 专家知识层 — 将专业领域知识（电影摄影、Atomic Design、品牌策略）固化为可执行的工作流程
• 零样板代码 — 所有原语操作委托给 muapi-cli，消除手动 curl 和 JSON 解析 资料来源：README.md

概述

schema_data.json 是 Generative-Media-Skills 项目的核心数据配置文件，位于仓库根目录。该文件为所有核心脚本提供运行时数据支持，是实现 Schema 驱动架构的关键组件。

主要功能

资料来源：README.md:120

架构设计

核心定位

graph TD
    A[用户/Agent] --> B[muapi CLI]
    B --> C[schema_data.json]
    C --> D{参数校验}
    D -->|通过| E[API请求]
    D -->|失败| F[错误提示]
    E --> G[异步任务提交]
    G --> H[结果轮询]
    H --> I[媒体下载]

schema_data.json 在执行流程中扮演数据契约角色，确保所有 muapi 工具调用都符合平台规范。

MCP服务器集成

当使用 muapi mcp serve 启动 MCP 服务器时，该 Schema 数据用于生成 19 个结构化工具的 JSON Schema 定义：

资料来源：README.md:95-120

工具命令参考

图像生成

muapi image generate "prompt" --model <model_id>

常用参数：

资料来源：README.md:140-150

图像编辑

muapi image edit "prompt" --image <url_or_path> --model <model_id>

支持的编辑模型包括 Flux Kontext Pro、GPT-4o、Midjourney 等。

资料来源：core/edit/SKILL.md:18-22

视频生成

muapi video generate "prompt" --model <model_id> --duration <seconds>

# 异步提交示例
REQUEST_ID=$(muapi video generate "a dog running on a beach" \
  --model kling-master --no-wait --output-json --jq '.request_id' | tr -d '"')

资料来源：README.md:125-135

异步任务处理

sequenceDiagram
    participant 用户
    participant muapi CLI
    participant muapi API
    participant schema_data

    用户->>muapi CLI: 提交异步请求
    muapi CLI->>schema_data: 验证模型ID和参数
    schema_data-->>muapi CLI: 校验通过
    muapi CLI->>muapi API: 发起请求
    muapi API-->>muapi CLI: 返回 request_id
    用户->>muapi CLI: 查询结果
    muapi CLI->>muapi API: 轮询 request_id
    muapi API-->>muapi CLI: 返回完成状态
    用户->>muapi CLI: 下载媒体

# 轮询等待结果
muapi predict wait "$REQUEST_ID" --download ./outputs

# 仅检查一次
muapi predict result "$REQUEST_ID" --once

资料来源：README.md:125-135

增强操作

# 图像增强
muapi enhance --op <operation> --image-url <url>

# 支持的操作

资料来源：core/edit/SKILL.md:23-30

唇形同步

muapi lipsync --video-url <url> --audio-url <url> --model sync

支持的唇形同步模型：Sync Labs、LatentSync、Creatify、Veed。

模型发现

列出可用模型

# 列出所有模型
muapi models list

# 按类别筛选
muapi models list --category video --output-json

# 获取模型详情
muapi models list --category image --output-json

模型类别

资料来源：README.md:155-165

工作流编排

管道链式调用

graph LR
    A[上传文件] --> B[媒体生成]
    B --> C[编辑增强]
    C --> D[下载结果]
    
    A1[muapi upload] --> B1[muapi generate]
    B1 --> C1[muapi edit]
    C1 --> D1[--download]

实际命令示例：

# 上传 → 编辑 → 下载 完整流程
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

# 从其他命令管道输入
generate_prompt | muapi image generate - --model flux-dev

资料来源：README.md:125-145

专业技能脚本

除了基础 CLI 命令，项目还提供了专家级技能脚本：

API Key 配置

环境变量设置

# 交互式配置
muapi auth configure

# 直接指定
muapi auth configure --api-key "YOUR_MUAPI_KEY"

# 或设置环境变量
export MUAPI_API_KEY="your-key-here"

验证配置

# 测试API Key有效性
muapi setup --test

# 显示当前配置
muapi setup --show-config

资料来源：core/platform/SKILL.md:20-30

参数校验规则

schema_data.json 定义的校验规则确保：

1. 模型存在性 - 请求的模型ID必须在平台支持列表中
2. 端点可用性 - 模型必须映射到有效的API端点
3. 参数合法性 - aspect_ratio、resolution、duration 必须在允许范围内

# 无效模型示例（会被 schema 校验拦截）
muapi image generate "test" --model invalid-model
# Error: Model 'invalid-model' not found in schema

# 无效参数示例
muapi video generate "test" --duration 1000
# Error: Duration '1000' exceeds maximum allowed value

常见问题

模型下载问题

社区反馈显示模型下载可能出现进度 100% 后报错的情况，通常是模型加载失败：

"Model download error on 100% progress" - 模型文件下载完成但加载失败

建议：确保 models/ 目录有足够空间，模型文件完整无损。

响应编码问题

部分用户报告出现编码异常响应：

"Encoded responses" - 回答显示为乱码或编码字符

这通常是服务器端编码问题，非 Schema 配置问题。

性能优化

用户关心的响应时间问题：

• GPU 加速可显著提升推理速度
• 异步模式（--no-wait）适合批量任务
• 选择合适的模型（如 flux-schnell 速度快于 flux-dev）

相关资源

概述

核心原语层（Core Primitives）是 Generative-Media-Skills 架构的基础层，提供与 muapi.ai 平台交互的底层能力。该层采用极简设计原则，通过薄封装（thin wrappers）包装 muapi-cli 工具，提供文件上传、图像编辑、平台配置和结果轮询等原子化功能。

核心原语层的设计目标是零样板代码——所有操作均通过标准 CLI 调用完成，无需手动处理 curl 请求或 JSON 解析。资料来源：README.md

架构设计

整体架构分层

graph TD
    subgraph "核心原语层 Core"
        A[core/platform] --> B[平台配置与认证]
        A --> C[结果轮询与状态管理]
        D[core/edit] --> E[图像编辑原语]
        D --> F[图像增强原语]
        D --> G[唇形同步原语]
        D --> H[视频特效原语]
    end
    
    subgraph "muapi-cli 引擎"
        I[muapi-cli] --> J[REST API 封装]
        J --> K[JSON Schema 验证]
        K --> L[结构化输出]
    end
    
    subgraph "Expert Library 专家库"
        M[Expert Skills] --> N[高级工作流编排]
    end
    
    B -.->|调用| I
    C -.->|轮询| I
    E -.->|调用| I
    F -.->|调用| I
    G -.->|调用| I
    H -.->|调用| I

核心目录结构

资料来源：README.md - Scalable Architecture

平台工具层

平台工具层位于 core/platform/，负责与 muapi.ai 平台的认证和通信基础建设。

可用脚本

资料来源：core/platform/SKILL.md

setup.sh 配置脚本

setup.sh 是平台配置的核心脚本，提供交互式和非交互式两种配置模式。

# 交互式配置
bash setup.sh

# 非交互式配置（自动化场景）
bash setup.sh --add-key "YOUR_MUAPI_KEY"

# 查看当前配置
bash setup.sh --show-config

# 测试API密钥有效性
bash setup.sh --test

关键参数说明：

资料来源：core/platform/setup.sh

check-result.sh 结果轮询脚本

异步生成任务需要轮询获取结果，该脚本封装了状态检查逻辑。

# 持续轮询直到完成
bash check-result.sh --id "your-request-id"

# 单次检查（不等待）
bash check-result.sh --id "your-request-id" --once

轮询机制：

sequenceDiagram
    participant A as 客户端
    participant M as muapi.ai API
    
    A->>M: POST /generate (async)
    M-->>A: request_id
    Note over A,M: 轮询循环开始
    loop 轮询
        A->>M: GET /predict/{request_id}
        M-->>A: status: processing
        A->>M: GET /predict/{request_id}
        M-->>A: status: success, outputs
    end
    Note over A,M: 轮询循环结束

资料来源：core/platform/check-result.sh

媒体编辑层

媒体编辑层位于 core/edit/，提供图像和视频处理的核心原语。该层封装了所有与 muapi.ai 编辑API的交互。

脚本概览

资料来源：core/edit/SKILL.md

edit-image.sh 图像编辑

支持多种AI模型的提示词驱动图像编辑。

bash edit-image.sh \
    --image-url "https://example.com/image.jpg" \
    --prompt "add sunglasses" \
    --model flux-kontext-pro

支持的模型：

常用参数：

资料来源：core/edit/edit-image.sh

enhance-image.sh 图像增强

一键式图像增强操作，无需复杂提示词。

# 图像超分
bash enhance-image.sh --op upscale --image-url "https://..."

# 背景移除
bash enhance-image.sh --op background-remove --image-url "https://..."

# 人脸替换
bash enhance-image.sh --op face-swap --image-url "https://..." --target-face "https://..."

# 吉卜力风格
bash enhance-image.sh --op ghibli --image-url "https://..."

增强操作类型：

资料来源：core/edit/enhance-image.sh

lipsync.sh 唇形同步

将音频与视频中的人物唇形同步。

bash lipsync.sh \
    --video-url "https://example.com/video.mp4" \
    --audio-url "https://example.com/audio.mp3" \
    --model sync

支持模型：

资料来源：core/edit/lipsync.sh

video-effects.sh 视频特效

应用各类AI视频特效。

# 舞蹈效果
bash video-effects.sh \
    --op dance \
    --image-url "https://..." \
    --audio-url "https://..."

# 人脸替换
bash video-effects.sh \
    --op face-swap \
    --video-url "https://..." \
    --target-face "https://..."

# 换装效果
bash video-effects.sh \
    --op dress-change \
    --video-url "https://..." \
    --garment-image "https://..."

特效操作类型：

资料来源：core/edit/video-effects.sh

通用参数

所有核心脚本支持以下通用参数：

资料来源：core/edit/SKILL.md - Common Flags

环境依赖

核心原语层依赖以下组件：

安装 muapi-cli：

# npm 安装（推荐）
npm install -g muapi-cli

# pip 安装
pip install muapi-cli

# 直接运行（无需安装）
npx muapi-cli --help

资料来源：README.md - Install muapi CLI

典型工作流

完整图像编辑工作流

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[查看结果]

示例代码：

# 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

批量处理工作流

# 批量超分处理
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 进行运行时验证：

{
  "models": {
    "flux-kontext-pro": {
      "endpoint": "/v1/image/edit/kontext",
      "aspect_ratios": ["1:1", "16:9", "9:16", "4:3"],
      "resolutions": ["1K", "2K", "4K"]
    }
  }
}

验证功能：

# 列出所有可用模型
muapi models list

# 按类别筛选
muapi models list --category video --output-json

资料来源：README.md - Schema Reference

与 Expert Library 的关系

核心原语层为 Expert Library（专家库）提供底层支撑：

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]

分工原则：

专家库中的技能（如 Cinema Director）读取 SKILL.md 文件，按照步骤指示调用核心原语，实现专业级输出而无需暴露底层细节。

资料来源：README.md - Expert Library

常见问题与排查

认证问题

症状： API调用返回认证错误

排查步骤：

# 1. 确认密钥配置
bash core/platform/setup.sh --show-config

# 2. 测试密钥有效性
bash core/platform/setup.sh --test

异步任务卡住

症状： check-result.sh 长时间无响应

排查步骤：

# 1. 检查一次不过滤
bash core/platform/check-result.sh --id "YOUR_ID" --once

# 2. 查看任务状态
muapi predict result "YOUR_ID" --json

模型不支持

症状： 报错模型不存在

解决方案：

# 查看支持的模型列表
muapi models list --category image --output-json | jq '.models[].id'

总结

核心原语层是 Generative-Media-Skills 的基础设施，通过标准化的脚本封装提供：

• 平台无关性：统一的 CLI 接口，底层切换透明
• 零样板：无需编写 curl 或 JSON 解析代码
• 可组合性：脚本可自由组合构建复杂工作流
• 类型安全：Schema 验证确保参数正确性

核心原语层的设计哲学是简单、可信、持久——专注于做好一件事（与 muapi.ai API 交互），而不试图做太多。这与 Expert Library 的高级抽象形成良好互补，共同构成完整的 AI 媒体生成能力体系。

概述

视频与动效技能库是 Generative-Media-Skills 项目的核心模块之一，专门用于为 AI Agent 提供专业级的视频生成、编辑和动效制作能力。该技能库整合了文本转视频（Text-to-Video）、图片转视频（Image-to-Video）、视频剪辑（Video Editing）和短视频创作（Short Video Creation）等多条技术路线，支持从概念构思到最终成品的完整工作流。

资料来源：README.md

技术架构

分层设计

视频与动效技能库采用 Core/Library 分层架构：

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

技能分类

技能库包含 16 个视频动效技能，分为以下几大类：

资料来源：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

使用示例：

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

Seedance 2.0（字节豆包视频）

Seedance 2.0 提供导演级别的专业视频生成能力，支持三种工作模式：

资料来源：library/motion/seedance-2/SKILL.md

核心脚本参数：

资料来源：library/motion/seedance-2/scripts/generate-seedance.sh

AI Clipping（智能剪辑）

AI Clipping 提供从长视频自动提取高传播力短视频的能力，是内容创作者的效率利器。

核心能力：

• 服务端转录：无需本地 Whisper，在服务端完成语音识别
• 病毒式排名：基于传播潜力自动排序精彩片段
• 去重机制：智能检测并去除重复内容
• 人脸追踪自动裁剪：保持人物始终在画面中心

资料来源：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

Product Video Ad Maker（产品广告制作器）

高端电影级产品视频广告制作，从简单的产品照片即可生成专业级商业视频。

输出规格：

• 竖屏 9:16 格式
• 适配 TikTok/Reels/Shorts 平台
• 高端商业电影质感

资料来源：library/motion/product-video-ad-maker/SKILL.md

MCP 工具接口

视频与动效技能通过 MCP Server 暴露为结构化工具，Claude Desktop、Cursor 等 Agent 可直接调用。

资料来源：README.md

视频生成相关工具

视频编辑相关工具

异步处理流程

视频生成采用异步工作模式，需要通过轮询获取结果：

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

CLI 异步操作示例：

# 提交异步任务并获取 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

基础视频生成

# 文本转视频
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

使用高级技能

# 使用 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：

{
  "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

常见问题与社区反馈

根据社区讨论，以下是用户关心的热点问题：

资料来源：GitHub Issues #89, #70, #68

相关技能推荐

视频与动效技能库可与以下技能协同使用：

技术参考

• CLI 文档：muapi-cli npm
• API Key 获取：https://muapi.ai/dashboard
• 支持的模型列表：muapi models list --category video
• 支持的分辨率：flux-dev、kling-v3.0-pro、seedance-2.0 等主流模型

架构概览

图像与设计技能库采用 核心层 / 技能层 双层架构：

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

可用脚本

常用参数

所有脚本支持以下通用参数：

--async      # 异步提交，不等待结果
--json       # 输出 JSON 格式
--timeout N  # 超时时间（秒）
--help       # 显示帮助信息

快速使用

# 图像编辑
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 高分辨率输出：支持超高清分辨率选项
• 多风格支持：涵盖微距摄影、电影感、人像、产品摄影等多种风格
• 视角控制：支持鱼眼、鸟瞰、低角度、微距等多种拍摄视角

工作流程

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 library/visual/nano-banana/scripts/generate-nano-art.sh \
  --file ./my-source-image.jpg \
  --subject "一只玻璃蜂鸟" \
  --style "macro photography" \
  --resolution "2k" \
  --view

参数说明：

资料来源：library/visual/nano-banana/SKILL.md

UI Designer 界面设计

UI Designer 技能专注于生成高保真移动端和 Web 端界面设计稿，采用原子设计（Atomic Design）方法论构建可复用的设计系统。资料来源：library/visual/ui-design/SKILL.md

设计方法论

该技能遵循原子设计的五级层次结构：

脚本使用

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 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

专业技能库

产品摄影类

品牌设计类

室内与空间设计

社交媒体类

资料来源：README.md

模型支持

图像与设计技能库通过 muapi-cli 接入 100+ AI 图像生成模型：

主流模型

模型查询

# 列出所有图像模型
muapi models list --category image

# 查看具体模型参数
muapi models list --output-json | jq '.[] | select(.category == "image")'

资料来源：README.md

AI 代理集成

图像与设计技能库专为 AI 代理设计，支持多种集成方式：

MCP 服务器模式

muapi mcp serve

在 Claude Desktop 配置中启用：

{
  "mcpServers": {
    "muapi": {
      "command": "muapi",
      "args": ["mcp", "serve"],
      "env": { "MUAPI_API_KEY": "your-key-here" }
    }
  }
}

CLI 直接调用

# 生成图像并自动下载
muapi image generate "科技产品特写" --model flux-dev --download ./outputs

# 仅获取 URL（供代理后续处理）
muapi image generate "产品图" --model flux-schnell --output-json --jq '.outputs[0]'

执行代理技能

# 安装所有视觉技能
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

常见工作流程

产品广告生成流程

graph TD
    A[上传产品照片] --> B[Nano-Banana 增强处理]
    B --> C[生成多角度视图]
    C --> D[Interior Design 场景合成]
    D --> E[AI Clipping 提取精华片段]
    E --> F[Seedance 2.0 视频化]
    F --> G[最终广告成品]

品牌设计流程

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
• 多语言支持：用户希望技能能支持不同语言的提示词处理，包括西班牙语等

环境要求

资料来源：core/edit/SKILL.md

下一步

• 探索 运动与视频技能库 了解视频生成能力
• 查看 MCP 服务器配置 了解代理集成详情
• 阅读 架构设计文档 了解核心层与技能层交互

概述

社交媒体技能库是 Generative-Media-Skills 项目中专注于社交平台内容生成的专业技能集合。该技能库包含 5 个核心技能和 1 个视频处理技能，旨在帮助 AI Agent 自动化生成面向各大社交平台的营销内容和创意素材。

核心功能定位：

• 多平台适配：支持 Instagram、小红书 (RedNote)、YouTube Shorts、TikTok、抖音等多平台
• 一站式工作流：从素材输入到多平台分发的完整自动化流程
• AI 驱动的内容创作：利用 Nano-Banana、Seedance 2.0 等先进模型生成高质量内容
• UGC 风格支持：生成真实用户生成内容风格的口碑营销素材

技能清单：

资料来源：README.md

概述

MCP（Model Context Protocol）服务器集成是 Generative-Media-Skills 项目为 AI 代理提供的核心功能之一。通过运行 muapi mcp serve 命令，可以将 muapi.ai 平台的所有多媒体生成工具以结构化的 MCP 工具形式暴露给支持 MCP 协议的 AI 代理客户端（如 Claude Desktop、Cursor、Windsurf 等）。资料来源：README.md

这种集成方式使 AI 代理无需通过 shell 脚本或命令行调用，即可直接调用多媒体生成工具，实现了零脚本、零 JSON 解析的原生代理体验。

架构设计

系统组件关系

graph TD
    A[AI 代理客户端<br/>Claude Desktop / Cursor / Windsurf] --> B[MCP Server<br/>muapi mcp serve]
    B --> C[muapi-cli 核心引擎]
    C --> D[muapi.ai API]
    D --> E[多媒体生成服务]
    
    F[19个MCP工具] --> B
    G[JSON Schema<br/>输入/输出定义] --> F

工具分类总览

快速配置

1. 启动 MCP 服务器

muapi mcp serve

该命令会在本地启动 MCP 服务器，默认监听标准 MCP 协议端口。资料来源：README.md

2. Claude Desktop 配置

编辑 Claude Desktop 配置文件：

macOS 路径： ~/Library/Application Support/Claude/claude_desktop_config.json

Windows 路径： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "muapi": {
      "command": "muapi",
      "args": ["mcp", "serve"],
      "env": {
        "MUAPI_API_KEY": "your-key-here"
      }
    }
  }
}

3. API Key 配置

确保在环境变量中配置有效的 muapi.ai API Key：

# 方式一：通过环境变量
export MUAPI_API_KEY="your-api-key"

# 方式二：通过 muapi-cli 配置
muapi auth configure --api-key "your-api-key"

获取 API Key：访问 https://muapi.ai/dashboard

MCP 工具清单

媒体生成工具

音频生成工具

增强处理工具

编辑工具

账户管理工具

文件操作工具

工作流程示例

异步视频生成与轮询

sequenceDiagram
    participant Agent as AI代理
    participant MCP as MCP Server
    participant API as muapi.ai API
    participant Storage as 存储服务
    
    Agent->>MCP: muapi_video_generate<br/>"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: 视频生成完成

典型代理对话流程

graph LR
    A[用户请求] --> B[Claude Desktop<br/>解析意图]
    B --> C[MCP工具调用<br/>muapi_image_generate]
    C --> D[返回结构化JSON]
    D --> E[代理整合结果]
    E --> F[用户响应]

JSON Schema 规范

每个 MCP 工具都提供完整的 JSON Schema 定义，包含：

• 输入模式（inputSchema）：定义必需参数和可选参数
• 输出模式（outputSchema）：定义返回数据结构
• 描述文档：每个参数的用途和类型说明

{
  "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"]
  }
}

兼容客户端

常见问题

Q1: MCP 服务器启动失败

症状： 执行 muapi mcp serve 无响应或报错

解决方案：

1. 确认已安装 muapi-cli：npm install -g muapi-cli
2. 检查 API Key 配置是否正确
3. 验证网络连接：确保能访问 muapi.ai

Q2: 工具调用超时

症状： 调用生成工具后长时间无响应

解决方案： 使用异步模式 + 轮询机制：

# 提交任务（不等待）
muapi video generate "prompt" --model kling-v3.0-pro --no-wait

# 获取 request_id 后轮询结果
muapi predict wait "request-id" --download ./outputs

Q3: API Key 无效

症状： 返回认证错误

解决方案：

muapi auth configure --api-key "your-new-key"

与传统 CLI 的对比

相关资源

• muapi-cli 官方文档：https://www.npmjs.com/package/muapi-cli
• muapi.ai 平台：https://muapi.ai/dashboard
• MCP 协议规范：Model Context Protocol

扩展阅读

• 核心脚本模块
• 专家技能库
• 工具链概览
• 快速入门指南

环境配置问题

muapi-cli 安装失败

问题描述：使用 npm 或 pip 安装 muapi-cli 时出现错误。

解决方案：

# 通过 npm 安装（推荐，无需 Python 环境）
npm install -g muapi-cli

# 或通过 pip 安装
pip install muapi-cli

# 或直接运行而不安装
npx muapi-cli --help

参考资料：README.md

API Key 配置异常

问题描述：配置 API Key 后无法正常调用 API，提示认证失败。

解决方案：确保 API Key 正确配置并验证其有效性。

# 交互式配置
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 验证流程：

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

Ubuntu 服务器依赖缺失

问题描述：在 Ubuntu 服务器上安装依赖时缺少必要的开发工具。

解决方案：根据社区反馈，安装以下依赖：

apt install python3-dev make g++
pip install wheel
pip install -r requirements.txt

同时确保安装正确版本的 NodeJS：

curl -sL https://deb.nodesource.com/setup_18.x | sudo bash -

参考资料：GitHub Issue #43

媒体生成问题

图像生成返回乱码或异常响应

问题描述：模型训练后生成的响应出现乱码，如 "H9E,:?&+8&1<*<2E(#!=)G68/?5C/BGC,..."。

可能原因：

1. 模型加载不完整或损坏
2. 编码处理错误
3. 模型与输入数据不兼容

解决方案：

1. 重新下载并验证模型文件完整性
2. 确保上传的文档使用 UTF-8 编码
3. 检查训练数据集的质量和格式

参考资料：GitHub Issue #39

图像编辑操作失败

问题描述：使用 edit-image.sh 进行图像编辑时请求失败。

基本用法：

bash core/edit/edit-image.sh \
    --image-url "https://example.com/image.jpg" \
    --prompt "添加太阳镜" \
    --model flux-kontext-pro

支持的操作类型：

参考资料：core/edit/SKILL.md

异步任务结果查询

问题描述：提交异步生成任务后无法获取结果。

解决方案：使用 check-result.sh 脚本查询任务状态。

# 持续轮询直到完成
bash core/platform/check-result.sh --id "your-request-id"

# 单次查询（不轮询）
bash core/platform/check-result.sh --id "your-request-id" --once

异步任务流程：

graph LR
    A[提交任务] --> B[获取 request_id]
    B --> C[轮询状态]
    C --> D{完成?}
    D -->|否| C
    D -->|是| E[获取结果]
    E --> F[下载媒体]

参考资料：core/platform/check-result.sh

性能与加速问题

GPU 加速支持

问题描述：用户询问是否支持 GPU 加速以加快处理速度。

当前状态：本项目主要依赖 muapi.ai 云端 API 服务，GPU 加速由服务端处理。客户端本地运行不受 GPU 限制影响。

提升响应速度的建议：

1. 使用更快的生成模型（如 --model flux-schnell）
2. 减少输入内容的复杂度
3. 使用异步模式处理批量任务

# 异步提交（不等待完成）
muapi video generate "a dog running" \
    --model kling-master \
    --no-wait \
    --output-json

# 后续再查询结果
muapi predict wait "$REQUEST_ID" --download ./outputs

参考资料：GitHub Issue #7、GitHub Issue #16

CUDA 支持

问题描述：用户询问是否支持 CUDA 进行本地计算加速。

当前状态：本项目的设计架构使用云端 API，CUDA 相关计算在 muapi.ai 服务端处理。客户端无需配置本地 CUDA 环境。

参考资料：GitHub Issue #70

运行时错误

500 内部服务器错误

问题描述：上传文档后提问时收到 500 Internal Server Error。

错误信息：

Error getting data.
<!doctype html>
<html lang=en>
<title>500 Internal Server Error</title>
<h1>Internal Server Error</h1>
<p>The server encountered an internal error...</p>

可能原因：

1. 服务器过载
2. 上传的文档处理异常
3. 后端服务暂时不可用

建议操作：

1. 稍后重试
2. 尝试重新上传文档
3. 检查文档格式是否受支持（PDF、DOCX、PPT 等）
4. 减小文档大小后重试

参考资料：GitHub Issue #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 并重新安装：

rm -rf node_modules package-lock.json
npm install

1. 确保使用正确版本的 NodeJS：

node --version  # 应为 v18.x 或更高

1. 检查是否有端口冲突：

# Windows
netstat -ano | findstr :3000

# Linux/Mac
lsof -i :3000

参考资料：GitHub Issue #34、GitHub Issue #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、GitHub Issue #44

CLI 使用问题

命令执行无响应

问题描述：执行 muapi 命令后无输出或无响应。

排查步骤：

graph TD
    A[命令无响应] --> B[检查 API Key]
    B --> C{Key 有效?}
    C -->|否| D[重新配置 Key]
    C -->|是| E[检查网络连接]
    E --> F{网络正常?}
    F -->|否| G[检查代理设置]
    F -->|是| H[查看详细日志]
    H --> I[使用 --json 输出]

常用诊断命令：

# 显示完整配置
muapi auth configure --show-config

# 测试 API 连接
muapi auth configure --test

# 列出可用模型
muapi models list

# 查看特定类别模型
muapi models list --category video --output-json

参考资料：core/platform/setup.sh

输出格式问题

问题描述：需要以特定格式提取命令输出用于脚本处理。

解决方案：使用 --output-json 和 --jq 参数进行格式化输出。

# 获取纯 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 '"')

管道组合示例：

# 上传 → 编辑 → 下载
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 服务器：

muapi mcp serve

1. 配置 Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "muapi": {
      "command": "muapi",
      "args": ["mcp", "serve"],
      "env": { "MUAPI_API_KEY": "your-key-here" }
    }
  }
}

1. 验证 MCP 工具列表是否包含所有 19 个工具：

参考资料：README.md - MCP Server 部分

故障排除工具

常用诊断脚本

环境变量检查

确保以下环境变量正确设置：

# 检查 API Key
echo $MUAPI_API_KEY

# 设置 API Key（如果缺失）
export MUAPI_API_KEY="your-api-key-here"

依赖验证

# 验证 curl
curl --version

# 验证 jq
jq --version

# 验证 Python3
python3 --version

# 验证 muapi-cli
muapi --version

获取帮助

如果以上方案均无法解决您的问题：

1. 搜索 GitHub Issues 查看是否已有类似问题
2. 创建新 Issue 并提供以下信息：

• 操作系统和版本
• muapi-cli 版本（muapi --version）
• 完整的错误信息
• 复现步骤

1. 访问 muapi.ai 检查账户状态和 API 余额

Pitfall Log / 踩坑日志

项目：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