Doc Format Converter

SKILL.md

---
name: doc-format-converter
description: "Doc Format Converter — Convert between CSV, Excel, JSON, PDF, Markdown, DOCX, HTML, and images with one click. Batch processing supported. Triggers: format conversion, batch convert, file converter, CSV to Excel, Excel to JSON, PDF to image, convert files"
override-tools: []
---

# Doc Format Converter

Batch file format conversion: CSV ↔ Excel ↔ JSON ↔ PDF / Markdown / DOCX / HTML / PNG / TXT — one-click batch conversion.

---

## Features Overview

| Feature | Description |
|---------|-------------|
| Multi-format | CSV, Excel, JSON, PDF, Markdown, DOCX, HTML, PNG/JPG, TXT |
| Batch Processing | Convert multiple files in one execution |
| AI Custom Conversion | Rename fields, extract tables, restructure data (PRO) |
| Feishu Integration | Conversion complete → Feishu card notification |

---

## Supported Conversions

| Source | Targets |
|--------|---------|
| CSV | Excel (.xlsx), JSON |
| Excel (.xlsx/.xls) | JSON, CSV, PNG (table image) |
| JSON | Excel (multi-sheet) |
| Markdown | DOCX, HTML |
| DOCX | Markdown |
| HTML | Markdown |
| PDF | PNG/JPG (image) |
| Image (PNG/JPG) | PDF |
| TXT | CSV |

---

## Tiered Features

| Feature | FREE | PRO |
|---------|:----:|:---:|
| Total files | 10 (lifetime) | Unlimited |
| Batch size | 5 files | Unlimited |
| Formats | Basic | All |
| AI custom conversion | — | Yes |
| PDF OCR | — | Yes |
| Feishu result push | — | Yes |

---

## Technical Implementation

| Category | Technology |
|----------|------------|
| Spreadsheet | pandas (CSV/Excel/JSON) |
| PDF | PyMuPDF + pdfplumber |
| Document | pandoc + python-docx |
| Image | Pillow (PIL) |
| Encoding | UTF-8/GBK/ISO auto-detect |

---

## Usage

### Standard Conversion

```
Convert these files:
[upload file list]
Target format: XLSX
```

### AI Custom Conversion (PRO)

```
Rename fields in this CSV to English, then convert to JSON
Extract tables from this DOCX into Excel, convert other content to Markdown
```

---

## Core Script

See `scripts/converter.py` for full implementation:

```python
from scripts.converter import batch_convert, check_quota_free

# Free tier: check before converting
can_proceed, msg = check_quota_free(remaining=7)
if not can_proceed:
    print(msg)
    sys.exit(1)

# Batch conversion
results = batch_convert(
    file_paths=["data.csv", "report.xlsx"],
    target_format="json",
    output_dir="/tmp/output",
    plan="FREE",
)
print(results)
```

---

## Billing

- **Pay-per-call**: $0.0100 USDT per execution via SkillPay.me
- **Balance insufficient**: Payment URL returned — user tops up at `https://skillpay.me/doc-format-converter`
- **External data flow**: `FEISHU_USER_ID` transmitted to `skillpay.me/api/v1/billing` for billing identification
- **Billing model**: Each batch conversion run = 1 call = $0.0100 USDT

---

## Required Environment Variables

| Variable | Description |
|----------|-------------|
| `FEISHU_USER_ID` | User open_id for billing (passed by Feishu runtime) |
| `SKILL_BILLING_API_KEY` | SkillPay Builder API Key |
| `SKILL_BILLING_SKILL_ID` | SkillPay Skill ID (defaults to `doc-format-converter`) |

---

## Error Handling

| Error Type | Handling |
|------------|----------|
| Encoding error | Auto-try UTF-8 → GBK → ISO-8859-1 |
| Unsupported format | Friendly error + suggested formats |
| Corrupted file | Skip and report, continue to next |
| Quota exceeded | Card prompts upgrade option |