Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@ Restart your agent (Claude Code, Cursor, etc.) after updating.
| `/content-parser` | "parse this URL", "解析链接" | Extract content from URLs |
| `/asr` | "transcribe", "语音转文字", "ASR" | Transcribe audio files to text |
| `/creator` | "创作", "写公众号", "小红书", "口播" | Creator workflow — platform-ready content packages |
| `/slides` | "slides", "幻灯片" | Create slide decks with AI visuals |
| `/music` | "music", "音乐" | AI music generation and covers |

## Supported Inputs

Expand All @@ -60,12 +62,19 @@ Restart your agent (Claude Code, Cursor, etc.) after updating.
- Plain text
- Image prompts
- Audio files
- Music prompts
- Reference audio files

## Setup

**ListenHub API Key** — [Get yours](https://listenhub.ai/settings/api-keys) (Pro plan required)
**ListenHub CLI** — Install and login:

Keys auto-configure on first use.
```bash
npm install -g @marswave/listenhub-cli
listenhub auth login
```

**Note:** `/content-parser` and `/creator` still require a [ListenHub API Key](https://listenhub.ai/settings/api-keys) for content extraction.

## Directory Structure

Expand All @@ -78,7 +87,10 @@ Keys auto-configure on first use.
├── content-parser/ # URL content extraction
├── asr/ # Audio transcription
├── creator/ # Creator workflow (WeChat, Xiaohongshu, narration)
└── listenhub/ # Deprecated (see DEPRECATED.md)
├── slides/ # Slide deck generation
├── music/ # AI music generation and covers
├── listenhub-cli/ # CLI authentication and setup
└── listenhub/ # Router skill (alias for listenhub-cli)
```

## Supported Clients
Expand Down
18 changes: 15 additions & 3 deletions README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@ git pull origin main
| `/content-parser` | "解析链接"、"提取内容" | URL 内容提取 |
| `/asr` | "转录"、"语音转文字"、"ASR" | 音频文件转文字 |
| `/creator` | "创作"、"写公众号"、"小红书"、"口播" | 创作者工作流 — 一键生成平台内容包 |
| `/slides` | "幻灯片"、"slides" | 幻灯片生成 |
| `/music` | "音乐"、"music" | AI 音乐生成、翻唱 |

## 支持的输入

Expand All @@ -60,12 +62,19 @@ git pull origin main
- 纯文本
- 图片描述
- 音频文件
- 音乐描述
- 参考音频文件

## 配置

**ListenHub API Key** — [获取](https://listenhub.ai/zh/settings/api-keys)(Pro 订阅)
**ListenHub CLI** — 安装并登录:

首次使用时自动配置。
```bash
npm install -g @marswave/listenhub-cli
listenhub auth login
```

**注意:** `/content-parser` 和 `/creator` 仍需要 [ListenHub API Key](https://listenhub.ai/zh/settings/api-keys) 用于内容提取。

## 目录结构

Expand All @@ -78,7 +87,10 @@ git pull origin main
├── content-parser/ # URL 内容提取
├── asr/ # 音频转文字
├── creator/ # 创作者工作流
└── listenhub/ # 已弃用(见 DEPRECATED.md)
├── slides/ # 幻灯片生成
├── music/ # AI 音乐生成、翻唱
├── listenhub-cli/ # CLI 认证与配置
└── listenhub/ # 路由 skill(listenhub-cli 的别名)
```

## 支持的客户端
Expand Down
2 changes: 1 addition & 1 deletion asr/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Run `coli asr --help` for current CLI options and supported flags.

- No shell scripts. Use direct commands only.
- Always read config following `shared/config-pattern.md` before any interaction
- Follow `shared/common-patterns.md` for interaction patterns
- Follow `shared/cli-patterns.md` for interaction patterns
- Never ask more than one question at a time

<HARD-GATE>
Expand Down
234 changes: 225 additions & 9 deletions content-parser/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@ Extract and normalize content from URLs across supported platforms. Returns stru

## Hard Constraints

- No shell scripts. Construct curl commands from the API reference files listed in Resources
- Always read `shared/authentication.md` for API key and headers
- Follow `shared/common-patterns.md` for polling, errors, and interaction patterns
- No shell scripts. Construct curl commands from the API Reference (Inlined) section below
- See § API Reference (Inlined) below for API key and headers
- See § API Reference (Inlined) below for polling, errors, and interaction patterns
- URL must be a valid HTTP(S) URL
- Always read config following `shared/config-pattern.md` before any interaction
- Never save files to `~/Downloads/` or `.listenhub/` — save to the current working directory
Expand Down Expand Up @@ -200,13 +200,229 @@ Wait for explicit confirmation before calling the API.

**Estimated time**: 10-30 seconds depending on content size and platform.

## API Reference
## API Reference (Inlined)

- Content extract: `shared/api-content-extract.md`
- Supported platforms: `references/supported-platforms.md`
- Polling: `shared/common-patterns.md` § Async Polling
- Error handling: `shared/common-patterns.md` § Error Handling
- Config pattern: `shared/config-pattern.md`
### Authentication

**Environment variable**: `LISTENHUB_API_KEY` (format: `lh_sk_...`)

Store in `~/.zshrc` (macOS) or `~/.bashrc` (Linux):

```bash
export LISTENHUB_API_KEY="lh_sk_..."
```

**How to obtain**: Visit https://listenhub.ai/settings/api-keys (Pro plan required).

**Base URL**: `https://api.marswave.ai/openapi/v1`

**Required headers** (every request):

```
Authorization: Bearer $LISTENHUB_API_KEY
Content-Type: application/json
X-Source: skills
```

The `X-Source: skills` header identifies requests as coming from Claude Code skills (CLI tool).

**curl template:**

```bash
curl -sS -X POST "https://api.marswave.ai/openapi/v1/{endpoint}" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Source: skills" \
-d '{ ... }'
```

For GET requests, omit `-d` and change `-X POST` to `-X GET`.

**Security notes:**
- Never log or display full API keys in output
- API keys are transmitted via HTTPS only
- Do not pass sensitive or confidential information as content input — it is sent to external APIs for processing

---

### POST /v1/content/extract

Create a content extraction task for a URL. Returns a `taskId` for polling.

**Request body:**

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| source | **Yes** | object | Source to extract from |
| source.type | **Yes** | string | Must be `"url"` |
| source.uri | **Yes** | string | Valid HTTP(S) URL to extract content from |
| options | No | object | Extraction options |
| options.summarize | No | boolean | Whether to generate a summary |
| options.maxLength | No | integer | Maximum content length |
| options.twitter | No | object | Twitter/X specific options |
| options.twitter.count | No | integer | Number of tweets to fetch (1-100, default 20) |

**Response:**

```json
{
"code": 0,
"message": "success",
"data": {
"taskId": "69a7dac700cf95938f86d9bb"
}
}
```

**Error codes:**

| Code | Meaning |
|------|---------|
| 29003 | Validation error (`"source.uri" is required`, `"source.uri" must be a valid uri`) |
| 21007 | Invalid API key |

---

### GET /v1/content/extract/{taskId}

Get extraction task status and results.

**Path params:**

| Param | Type | Description |
|-------|------|-------------|
| taskId | string | 24-char hex task ID |

**Response states:**

- **processing** — Task is still running
- **completed** — Extraction finished, data available
- **failed** — Extraction failed, check `failCode` and `message`

**Response (processing):**

```json
{
"code": 0,
"message": "success",
"data": {
"taskId": "69a7dac700cf95938f86d9bb",
"status": "processing",
"createdAt": "2025-04-09T12:00:00Z",
"data": null,
"credits": 0,
"failCode": null,
"message": null
}
}
```

**Response (completed):**

```json
{
"code": 0,
"message": "success",
"data": {
"taskId": "69a7dac700cf95938f86d9bb",
"status": "completed",
"createdAt": "2025-04-09T12:00:00Z",
"data": {
"content": "Extracted text content...",
"metadata": {
"title": "Article Title",
"author": "Author Name",
"publishedAt": "2025-04-01T08:00:00Z"
},
"references": [
"https://example.com/related-article"
]
},
"credits": 5,
"failCode": null,
"message": null
}
}
```

**Response (failed):**

```json
{
"code": 0,
"message": "success",
"data": {
"taskId": "69a7dac700cf95938f86d9bb",
"status": "failed",
"createdAt": "2025-04-09T12:00:00Z",
"data": null,
"credits": 0,
"failCode": "EXTRACT_FAILED",
"message": "Unable to extract content from the provided URL"
}
}
```

**Key fields:**

| Field | Type | Description |
|-------|------|-------------|
| status | string | `processing`, `completed`, or `failed` |
| data.data.content | string | Extracted text content |
| data.data.metadata | object | Page metadata (title, author, publishedAt) |
| data.data.references | array | Referenced URLs (array of strings) |
| credits | integer | Credits consumed |
| failCode | string | Error code (null on success) |
| message | string | Error message (null on success) |

**Error codes:**

| Code | Meaning |
|------|---------|
| 29003 | Invalid taskId format |
| 25002 | Task not found |

---

### Polling Pattern

5-second interval, 60 polls max. Run with `run_in_background: true` and `timeout: 300000`.

**Two-step pattern:**

1. **Submit (foreground)**: POST the creation request, extract `taskId` from the response.
2. **Poll (background)**: Run the polling loop with `run_in_background: true`. You will be notified automatically when it completes.

The exact polling bash command is already specified in the Workflow section (Step 5).

---

### Error Handling

**HTTP status codes:**

| Code | Meaning | Action |
|------|---------|--------|
| 200 | Success | Parse response body |
| 400 | Bad request | Check parameters |
| 401 | Invalid API key | Re-check `LISTENHUB_API_KEY` |
| 402 | Insufficient credits | Inform user to recharge |
| 403 | Forbidden | No permission for this resource |
| 429 | Rate limited | Exponential backoff, retry after delay |
| 500/502/503/504 | Server error | Retry up to 3 times |

**Retry strategy:**

- **429 rate limit**: Wait 15 seconds, then retry (exponential backoff)
- **5xx server errors**: Retry up to 3 times with 5-second intervals
- **Network errors**: Retry up to 3 times

**Application error codes:**

| Code | Meaning |
|------|---------|
| 21007 | Invalid user API key |
| 25429 | Rate limited (application-level) |

## Example

Expand Down
Loading