# moark-skills

**Repository Path**: lowkey110/moark-skills

## Basic Information

- **Project Name**: moark-skills
- **Description**: Moark Skills 是一个为 OpenClaw 等 AI 代理工具提供扩展能力的技能（Skill）集合仓库
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Moark Skills

## 1. 项目简介

Moark Skills 是一个为 [OpenClaw](https://github.com/nicepkg/openclaw)提供扩展能力的技能（Skill）集合仓库。本项目旨在解决 AI 代理在处理特定任务时能力受限的问题，通过提供标准化的独立功能模块，使 AI 代理能够轻松**调用外部 API 或执行本地脚本，从而完成复杂任务**。

## 2. 快速开始

1. **下载 OpenClaw**
如果你还没有安装 OpenClaw，可以通过以下命令快速安装：

   ```bash
   curl -fsSL https://openclaw.ai/install.sh | bash
   ```

2. **克隆仓库**
   ```bash
   git clone https://gitee.com/moark/moark-skills.git
   cd moark-skills
   ```

3. **安装依赖**
   确保系统中已安装 Python 3.10 或更高版本，并在需要运行相应脚本前安装对应的依赖包（如 `openai`, `requests`, `requests-toolbelt` 等）：
   ```bash
   pip install openai requests requests-toolbelt
   ```

## 3. 在 OpenClaw 中使用

Moark Skills 采用标准化的 `SKILL.md` 描述文件，你可以通过命令行将这些技能直接导入到 OpenClaw 中使用。

**第一步：复制技能文件**
假设你的 OpenClaw 技能目录位于 `~/.openclaw/skills`（请根据你的实际安装路径进行调整）
```bash
# 若该目录不存在请先使用如下命令创建
mkdir -p ~/.openclaw/skills
```
在克隆了本仓库后，执行以下命令将仓库中的skill复制过去：

```bash
# 将仓库 skills 目录下的所有内容复制到 OpenClaw 的技能目录中
cp -r ./skills/* ~/.openclaw/skills/
```

**第二步：配置 API Key**
OpenClaw 在执行这些技能时需要用到 API 鉴权。你需要修改 OpenClaw 的配置文件 `~/.openclaw/openclaw.json`，在 `skills.entries` 下为对应的技能配置 `apiKey` 字段（即你的 GITEEAI_API_KEY）：

```json
{
  // 其他配置项...
  "skills": {
    "entries": {
      "moark-image-gen": {
        "apiKey": "你的_GITEEAI_API_KEY"
      }
      // 其他skill同理...
    }
  }
}
```

若想在GUI界面中配置 API KEY，则需要在 OpenClaw 的图形界面中找到技能管理模块，为每个技能单独配置 API Key。

```bash
# 运行此命令后打开 http://127.0.0.1:18789/skills
openclaw gateway --port 18789 --verbose
```

随后可在如下图红圈所示的区域为每个技能单独配置 API Key，在输入后保存：

![image](./docs/images/save_api_key.png)


**第三步：刷新并测试**
重新加载技能列表。现在你可以直接向 OpenClaw 发出自然语言指令了。例如：

> “帮我生成一张赛博朋克风格的城市夜景图”

OpenClaw 会自动读取 `SKILL.md`，匹配对应的技能，构造参数并执行底层的 Python 脚本，最后将结果返回给你。

## 4. 技能列表

目前仓库中包含以下技能：

### moark-doc-extraction (文档内容提取)
- **能力**：从 PDF 文件中提取并识别文本内容。
- **输入**：文档文件的本地路径或链接 (`--file`)，API Key (`--api-key`)。
- **输出**：提取出的纯文本内容。

### moark-image-gen (AI 图像生成)
- **能力**：根据文本描述生成高质量图像。
- **输入**：正向提示词 (`--prompt`)、图像尺寸 (`--size`)、负面提示词 (`--negative-prompt`)，生成时的迭代次数 (`--num-inference-steps`)，对用户提示词的遵从程度 (`--guidance-scale`)，API Key (`--api-key`)。
- **输出**：生成的图像链接。

### moark-ocr (光学字符识别)
- **能力**：识别并提取图像文件中的文字内容。
- **输入**：图像文件的本地路径 (`--image`)、用户的具体提取要求 (`--prompt`)，API Key (`--api-key`)。
- **输出**：识别出的文本内容及基于用户要求的输出。

### moark-tts (文本转语音)
- **能力**：将文本转换为语音，支持 `audiofly`、`chattts`、`cosyvoice2`、`cosyvoice3`、`cosyvoice-300m`、`fish-speech-1.2-sft`、`index-tts-1.5`、`index-tts-2`、`glm-tts`、`megatts3`、`moss-ttsd-v0.5`、`qwen-tts`、`spark-tts-0.5b`、`step-audio-tts-3b` 和 `vibevoice-large`；并支持 `FunAudioLLM-CosyVoice-300M` 的音色特征提取。
- **输入**：模型名称 (`--model`)、待合成文本 (`--text`)，以及按模型选择的参考音频、音色或风格参数，API Key (`--api-key`)。
- **输出**：生成的音频链接、保存到本地的音频文件路径，或可解析的任务结果。
- **IndexTTS-2 提示**：支持 4 种语气控制模式（音频控制语气/文本控制语气 × 同步/异步）。
- **Qwen3-TTS 提示**：支持单条或多条 `inputs`，可在同一请求中混用内置音色与自定义音色。

### moark-text-moderations (文本合规审查)
- **能力**：对用户输入的文本进行内容安全审查，识别不当或违规内容。
- **输入**：需要审查的文本字符串 (`--text`)，API Key (`--api-key`)。
- **输出**：审查结果（是否违规及具体原因）。

## 5. 环境变量与配置

为了保证技能的通用性，所有技能的执行环境和鉴权配置都遵循统一标准。

- **依赖管理**：所有 Python 脚本均使用标准的 `python` 命令运行。你需要提前配置好 Python 环境并使用 `pip` 安装各个脚本所需的依赖库。
- **API 鉴权 (GITEEAI_API_KEY)**：当前所有技能均依赖 Gitee AI 提供的底层模型能力。你必须为技能配置API Key，或者在调用脚本时通过 `--api-key` 参数显式传入。

## 6. 本地脚本直跑

如果你不想通过 OpenClaw，也可以直接**在本地终端运行这些技能脚本**。只需要确保在当前的 Python 环境中安装了对应的依赖。

**运行方式：**
使用 `python` 命令执行对应的 Python 脚本，并通过命令行参数传入所需信息。

**示例 1：文档内容提取**
```bash
# 确保已安装依赖：pip install requests requests-toolbelt
# 使用 --api-key 参数显式传入
python skills/moark-doc-extraction/scripts/perform_doc_extraction.py \
  --file /path/to/document.pdf \
  --api-key "你的_GITEEAI_API_KEY"

# 或者通过环境变量传入
export GITEEAI_API_KEY="你的_GITEEAI_API_KEY"
python skills/moark-doc-extraction/scripts/perform_doc_extraction.py --file /path/to/document.pdf
```

**示例 2：AI 图像生成**
```bash
# 确保已安装依赖：pip install openai
python skills/moark-image-gen/scripts/perform_image_gen.py \
  --prompt "一只戴着墨镜的赛博朋克猫咪" \
  --size "1024x1024" \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 3：文本转语音**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model step-audio-tts-3b \
  --text "The answer to the universe is 42" \
  --prompt-audio-url "https://gitee.com/realhugh/imgs/raw/master/zero_shot_prompt.wav" \
  --prompt-text "希望你以后能够做的比我还好呦。" \
  --failover-enabled false \
  --voice alloy \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 4：Spark-TTS-0.5B 音色克隆（异步）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model spark-tts-0.5b \
  --text "Hello, world!" \
  --prompt-audio-url "https://gitee.com/realhugh/imgs/raw/master/jay_prompt.wav" \
  --prompt-text "对我来讲是一种荣幸，但是也是压力蛮大的。不过我觉得是一种呃很好的一个挑战。" \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 5：IndexTTS-2 音频控制语气（同步）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model index-tts-2 \
  --text "我知道自己不是一个人在战斗，有大家的支持和协作，我相信我们一定能一起把事情做好。" \
  --prompt-audio-url "https://gitee.com/gitee-ai/moark-assets/raw/master/jay_prompt.wav" \
  --prompt-text "对我来讲是一种荣幸，但是也是压力蛮大的。不过我觉得是一种呃很好的一个挑战。" \
  --emo-audio-prompt-url "https://gitee.com/gitee-ai/moark-assets/raw/master/index-tts-2/emo_sad.wav" \
  --emo-alpha 0.5 \
  --voice alloy \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 6：IndexTTS-2 文本控制语气（异步）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model index-tts-2 \
  --mode async \
  --text "我知道自己不是一个人在战斗，有大家的支持和协作，我相信我们一定能一起把事情做好。" \
  --prompt-audio-url "https://gitee.com/gitee-ai/moark-assets/raw/master/jay_prompt.wav" \
  --prompt-text "对我来讲是一种荣幸，但是也是压力蛮大的。不过我觉得是一种呃很好的一个挑战。" \
  --emo-text "你吓死我了！你是鬼吗？" \
  --use-emo-text true \
  --voice alloy \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 7：fish-speech-1.2-sft（voice_url 克隆）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model fish-speech-1.2-sft \
  --text "The answer to the universe is 42" \
  --voice-url "https://gitee.com/gitee-ai/moark-assets/raw/master/ceshi.pt" \
  --voice alloy \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 8：CosyVoice-300M（voice_url 语音生成）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model cosyvoice-300m \
  --text "The answer to the universe is 42" \
  --voice-url "https://gitee.com/gitee-ai/moark-assets/raw/master/ceshi.pt" \
  --voice alloy \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 9：CosyVoice-300M 音色特征提取（URL-only）**
```bash
python skills/moark-tts/scripts/perform_voice_feature_extraction.py \
  --model FunAudioLLM-CosyVoice-300M \
  --prompt "提供用于声纹提取的提示文本" \
  --file-url "https://gitee.com/gitee-ai/moark-assets/raw/master/jay_prompt.wav" \
  --output "./voice-feature-output.bin" \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 10：MegaTTS3（OpenAI extra_body 参数映射）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model megatts3 \
  --text "The answer to the universe is 42" \
  --voice alloy \
  --prompt-language zh \
  --intelligibility-weight 1.6 \
  --similarity-weight 2.5 \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 11：MOSS-TTSD-v0.5 单音频模式（异步）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model moss-ttsd-v0.5 \
  --mode async \
  --text "[S1]诶，跟你说个事儿啊，我最近听了不少那种AI生成的播客。" \
  --audio-mode single \
  --prompt-audio-single-url "https://gitee.com/cryusxin/test/raw/master/single_reference.wav" \
  --prompt-text-single "[S1]我意思是说通用计算机是指我们所有人都能用的这种普通计算机的意思啊？[S2]不是，不是。" \
  --seed 123 \
  --use-normalize true \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 12：MOSS-TTSD-v0.5 角色音频模式（异步）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model moss-ttsd-v0.5 \
  --mode async \
  --text "[S1]诶，我最近看了一篇讲人工智能的文章。[S2]哦？是吗？" \
  --audio-mode role \
  --prompt-audio-1-url "https://gitee.com/wei-xiaohui1/test1/raw/master/zh_spk1_moon.wav" \
  --prompt-text-1 "周一到周五，每天早晨七点半到九点半的直播片段。" \
  --prompt-audio-2-url "https://gitee.com/wei-xiaohui1/test1/raw/master/zh_spk2_moon.wav" \
  --prompt-text-2 "如果大家想听到更丰富更及时的直播内容，记得在周一到周五准时进入直播间。" \
  --seed 123 \
  --use-normalize true \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 13：VibeVoice-Large（单个 prompt_audio_urls）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model vibevoice-large \
  --mode async \
  --text "Speaker 1:大家好，欢迎收看节目。Speaker 2:你好，很高兴来到这里。" \
  --prompt-audio-urls "https://gitee.com/gitee-ai/moark-assets/raw/master/vibevoice/demo_voices_zh-Xinran_woman.wav" \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 14：VibeVoice-Large（多个 prompt_audio_urls）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model vibevoice-large \
  --mode async \
  --text "Speaker 1:大家好，欢迎收看《危殆的星球》。Speaker 2:你好，爱丽丝，很高兴来到这里。" \
  --prompt-audio-urls "[\"https://gitee.com/gitee-ai/moark-assets/raw/master/vibevoice/demo_voices_zh-Xinran_woman.wav\",\"https://gitee.com/gitee-ai/moark-assets/raw/master/basic_ref_zh.wav\"]" \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 15：CosyVoice3（异步）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model cosyvoice3 \
  --mode async \
  --text "Hello, world!" \
  --prompt-wav-url "https://gitee.com/realhugh/imgs/raw/master/zero_shot_prompt.wav" \
  --prompt-text "希望你以后能够做的比我还好呦。" \
  --instruct-text "带有粤语口音，语速适中" \
  --speed 1 \
  --seed 123 \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 16：AudioFly（异步）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model audiofly \
  --mode async \
  --text "A cat meows, and it's drizzling" \
  --num-inference-steps 200 \
  --guidance-scale 3.5 \
  --output-format mp3 \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 17：Qwen3-TTS（单条输入 + 内置音色）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model qwen-tts \
  --mode async \
  --text "其实我真的有发现，我是一个特别善于观察别人情绪的人。" \
  --speaker Vivian \
  --language Chinese \
  --instruction "体现撒娇稚嫩的萝莉女声，音调偏高且起伏明显，营造出黏人、做作又刻意卖萌的听觉效果。" \
  --output-format mp3 \
  --api-key "你的_GITEEAI_API_KEY"
```

**示例 18：Qwen3-TTS（多条 inputs，混合内置+自定义音色）**
```bash
python skills/moark-tts/scripts/perform_tts.py \
  --model qwen-tts \
  --mode async \
  --qwen-inputs-json "[{\"prompt\":\"其实我真的有发现，我是一个特别善于观察别人情绪的人。\",\"speaker\":\"Vivian\",\"language\":\"Chinese\",\"instruction\":\"体现撒娇稚嫩的萝莉女声，音调偏高且起伏明显，营造出黏人、做作又刻意卖萌的听觉效果。\"},{\"prompt\":\"其实我真的有发现，我是一个特别善于观察别人情绪的人。\",\"language\":\"Chinese\",\"prompt_audio_url\":\"https://gitee.com/gitee-ai/moark-assets/raw/master/jay_prompt.wav\",\"prompt_text\":\"对我来讲是一种荣幸，但是也是压力蛮大的。不过我觉得是一种呃很好的一个挑战。\",\"instruction\":\"体现撒娇稚嫩的萝莉女声，音调偏高且起伏明显，营造出黏人、做作又刻意卖萌的听觉效果。\"}]" \
  --output-format mp3 \
  --api-key "你的_GITEEAI_API_KEY"
```

*注意：所有脚本的输出结果都会打印在标准输出（stdout）中，通常以特定的前缀标识（如 `EXTRACTION_RESULT:`、`OCR_RESULT:` 或 `TTS_RESULT:`），方便其他程序解析。*

## 7. 常见问题

**Q: 在 Windows 系统下运行 OpenClaw 和这些技能时遇到各种报错，无法正常执行怎么办？**

**A:** 目前 OpenClaw 官方推荐在 **macOS** 或 **Linux** 环境下使用。对于 Windows 用户，**强烈建议使用 WSL2（Windows Subsystem for Linux）** 进行安装和运行。如果直接在 Windows 原生系统中安装和运行，可能会因为路径解析、依赖编译或环境隔离等原因出现大量不可预知的问题，导致技能无法正常工作。

## 8. 开发与贡献

欢迎为 Moark Skills 贡献新的技能。新增技能请遵循以下规范：

### 目录结构
在 `skills/` 目录下创建你的技能文件夹：
```text
skills/
└── your-skill-name/
    ├── SKILL.md          # 必须：技能描述与配置文件
    └── scripts/          # 可选：执行脚本存放目录
        └── your_script.py
```

### SKILL.md 规范
`SKILL.md` 使用 frontmatter 定义 Skill 的元数据：

```yaml
---
name: your-skill-name
description: 简要描述你的技能功能
metadata:
  openclaw:
    requires:
      env: ["GITEEAI_API_KEY"]  # 依赖的环境变量
    primaryEnv: "GITEEAI_API_KEY"
---
```

正文部分应包含以下章节，以便 AI 代理准确理解和使用：
- **Usage**：命令行调用示例。
- **Options**：支持的参数列表及说明。
- **Workflow**：AI 代理调用此技能的标准执行步骤。
- **Notes**：输出解析规则及其他注意事项。