# moark-skills

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

## Basic Information

- **Project Name**: moark-skills
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-02
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Moark Skills

## 1. 项目简介

Moark Skills 是一个为 [OpenClaw](https://github.com/nicepkg/openclaw) 等 AI 代理工具提供扩展能力的技能（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 包管理工具 `uv`。
   ```bash
   # macOS / Linux / WSL
   curl -LsSf https://astral.sh/uv/install.sh | sh
   # 如果能输出版本号，说明安装成功。
   uv --version
   ```

## 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`)，API Key (`--api-key`)。
- **输出**：生成的图像链接。

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

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

## 5. 环境变量与配置

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

- **依赖管理 (uv)**：所有 Python 脚本均使用 `uv` 运行。`uv` 会自动处理脚本所需的依赖包，无需手动创建虚拟环境或执行 `pip install`。
- **API 鉴权 (GITEEAI_API_KEY)**：当前所有技能均依赖 Gitee AI 提供的底层模型能力。你必须为技能配置API Key，或者在调用脚本时通过 `--api-key` 参数显式传入。

## 6. 本地脚本直跑

如果你不想通过 OpenClaw，也可以直接**在本地终端运行这些技能脚本**。由于脚本使用了 `uv` 的内联元数据（Inline script metadata），`uv` 会在执行时自动下载并隔离所需的依赖（如 `requests` 等），你无需手动配置虚拟环境。

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

**示例 1：文档内容提取**
```bash
# 使用 --api-key 参数显式传入
uv run 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"
uv run skills/moark-doc-extraction/scripts/perform_doc_extraction.py --file /path/to/document.pdf
```

**示例 2：AI 图像生成**
```bash
uv run skills/moark-image-gen/scripts/perform_image_gen.py \
  --prompt "一只戴着墨镜的赛博朋克猫咪" \
  --size "1024x1024" \
  --api-key "你的_GITEEAI_API_KEY"
```

*注意：所有脚本的输出结果都会打印在标准输出（stdout）中，通常以特定的前缀标识（如 `EXTRACTION_RESULT:` 或 `OCR_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:
      bins: ["uv"]           # 依赖的命令行工具
      env: ["GITEEAI_API_KEY"]  # 依赖的环境变量
    primaryEnv: "GITEEAI_API_KEY"
    install: []              # 依赖安装配置
---
```

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