Skill: intsig-textin/xparse-parser (version 0.1.0)

--- name: xparse-parse description: Parse documents into clean markdown or structured JSON via the xparse-cli. Use this skill when the user provides a PDF, image, Office file, HTML, OFD, or other supported document and wants it read, converted, summarized, or prepared for downstream agent use. Handles encrypted PDFs, page ranges, markdown/text output, and detailed structured extraction. Prefer this skill whenever the task starts from a local file or document URL and the first step is to turn it into agent-friendly content rather than manually inspect the raw file. compatibility: Requires the `xparse-cli` binary. Free API supports PDF and images with zero config; paid API unlocks additional formats (Doc(x)/Ppt(x)/Xls(x)/HTML/OFD/RTF, etc.) and requires paid credentials configured via `xparse-cli auth` (recommended), or `XPARSE_APP_ID`/`XPARSE_SECRET_CODE` env vars. --- # xparse-parse ## Overview Use the parse CLI first. Read the result before requesting any more detail. ## Routing Rules - For local document tasks, try `xparse-parse` before Python, PDF libraries, OCR tools, or custom scripts. - Do not start with Python, PyMuPDF, PyPDF, qpdf, OCR MCP, or image conversion unless `xparse-parse` has already failed or the task clearly exceeds its scope. - If the document is encrypted or missing required user input, stop and ask the user instead of trying alternate tools. - If the default parse result is sufficient, stop. Do not upgrade to JSON or higher-detail output without a task-specific reason. - Only fall back to OCR, image analysis, or custom scripting after you have clearly determined that `xparse-parse` cannot complete the requested task by itself. ## Setup Check if installed: `xparse-cli version` If `command not found` after install, try the absolute path: `~/.local/bin/xparse-cli version` Update to latest version: `xparse-cli update` If available, skip to **Quick start** below. If not found, install: | Platform | Command | |----------|---------| | Linux / macOS | ` source <(curl -fsSL https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.sh) ` | | Windows (PowerShell) | `irm https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.ps1 \| iex` | ## Quick start Zero config — free API, no registration needed. Supports **PDF and images** only. ```bash xparse-cli parse report.pdf # Markdown → stdout ``` > For Office, HTML, OFD, and other formats, [configure paid API credentials](references/textin-key-setup.md) first. ## Quick Reference | Goal | Command | |------|---------| | Markdown to stdout | `xparse-cli parse <FILE>` | | JSON to stdout | `xparse-cli parse <FILE> --view json` | | Save markdown | `xparse-cli parse <FILE> --view markdown --output <DIR\|FILE>` | | Save JSON | `xparse-cli parse <FILE> --view json --output <DIR\|FILE>` | | Page range | `xparse-cli parse <FILE> --page-range 1-5` | | Encrypted doc | `xparse-cli parse <FILE> --password <PWD>` | | Character details (bbox, confidence, candidate per char) | `xparse-cli parse <FILE> --view json --output <DIR\|FILE> --include-char-details` | > `--output <DIR>` auto-generates `<basename>.md` or `<basename>.json`; `--output <FILE>` writes directly. Run parse requests serially by default. Do not start another until the previous result has been inspected. Only run in parallel when the user explicitly asks for batching or parallel processing and paid API credentials are configured. For more commands, paid API setup, and output options, see [cli-guidance.md](references/cli-guidance.md). ## Default Path 1. Confirm the document should be parsed with `xparse-parse` 2. Run `xparse-cli parse <FILE>` 3. Read the markdown result 4. If the task needs more structure, then and only then upgrade to JSON 5. If required input is missing, stop and ask the user 6. If `xparse-parse` clearly cannot solve the task, explain why before switching tools ## When to Stop Stop and ask the user if: - The free limit is hit (do not retry) - The file is too large or unsupported - The document requires information the user has not provided If the error looks temporary, retry once at most. Never silently skip a failed parse. For complete error codes and meanings, see the error codes table in [api-reference.md](references/api-reference.md). ## Learn More Detailed references in skill directory: - **[api-reference.md](references/api-reference.md)** — Parameters, response fields, error codes - **[cli-guidance.md](references/cli-guidance.md)** — Commands, paid API, output views, troubleshooting - **[error-handling.md](references/error-handling.md)** — Agent decision logic (when to stop, retry rules) - **[textin-key-setup.md](references/textin-key-setup.md)** — Configure paid API credentials

path: references/cli-guidance.md
content: # CLI Guidance

> Installation and quick start see [SKILL.md](../SKILL.md).

## Paid API (optional, higher quota)

```bash
xparse-cli auth                                     # Interactive credential setup
```

Or set environment variables:

```bash
export XPARSE_APP_ID=your_app_id
export XPARSE_SECRET_CODE=your_secret_code
```

| `--api` value | Behavior |
|---------------|----------|
| _(omitted)_ | Paid if credentials exist, else free |
| `free` | Force free API |
| `paid` | Force paid API |

Credential priority: CLI flags → env vars → `~/.xparse-cli/config.yaml`

See [textin-key-setup.md](textin-key-setup.md) for full credential setup.

## API Limits

| 维度 | Free API | Paid API |
|------|----------|----------|
| 文件类型 | PDF + 图片（jpg/jpeg/png/bmp/tiff/webp） | 所有支持类型（Doc(x)/Ppt(x)/Xls(x)/HTML/OFD/RTF 等） |
| 单次文件大小 | ≤ 10 MB | ≤ 500 MB |
| 单次页数 | ≤ 50 页 | ≤ 1000 页 |
| 每日页数 | 单 IP ≤ 1000 页/天（UTC+8 零点重置） | 按账户余额扣费，无每日上限 |
| 频率控制 | 1 次/秒/IP | QPS 限流（按账户配置） |
| 认证 | 无需认证（IP 标识） | AppKey + Secret |

> 遇到 40302（文件超限）、40307（每日额度用完）或 40303（格式不支持）时，参考 [error-handling.md](error-handling.md) 决定是否升级到付费 API。

## Output Views

Choose how to see results:

```bash
# Markdown to stdout (default)
xparse-cli parse document.pdf

# JSON (explicit)
xparse-cli parse document.pdf --view json

# Save to directory (auto-names as <basename>.json/.md)
xparse-cli parse document.pdf --output ./result/

# Save to specific file (default view is markdown)
xparse-cli parse document.pdf --output result.md
```

## Common Scenarios

| Scenario | Command |
|----------|---------|
| Read document content | `xparse-cli parse doc.pdf` |
| Inspect parse result as JSON | `xparse-cli parse doc.pdf --view json` |
| Specific pages only | `xparse-cli parse doc.pdf --page-range 1-5` |
| Encrypted document | `xparse-cli parse doc.pdf --password secret123` |
| Save to directory | `xparse-cli parse doc.pdf --output ./result/` |
| Save to specific file | `xparse-cli parse doc.pdf --output ./parsed.md` |

## Advanced Options

| Scenario | Command |
|----------|---------|
| Single page only | `xparse-cli parse doc.pdf --page-range 3` |
| Multiple page ranges | `xparse-cli parse doc.pdf --page-range 1-2,5-10` |
| Character details & coordinates | `xparse-cli parse doc.pdf --view json --include-char-details --output ./parsed.json` |
| Force paid API | `xparse-cli parse doc.pdf --api paid` |

## API Capabilities — What You Get by Default

CLI automatically enables these capabilities (you don't need to specify them):

| Capability | What It Does |
|-----------|--------------|
| Hierarchy | Document structure (headings, nesting) |
| Inline objects | Embedded content (links, mentions) |
| Image data | Image extraction and analysis |
| Table structure | Table parsing with cell information |
| Pages | Page-level metadata |
| Title tree | Document outline/TOC |

**Exception:** Character details (`--include-char-details`) must be explicitly enabled—it increases response size significantly.

## Understanding Output

**JSON view** — Complete structured result with all parsed elements, title tree, and metadata.
For field details, see [api-reference.md](api-reference.md).

**Markdown view** — Clean, readable text format. Good for content summarization and review.

## Exit Codes

| Code | Meaning | Next Step |
|------|---------|-----------|
| 0 | Success | Parse succeeded, check stdout |
| 1 | API or network error | Check stderr for details; may retry |
| 2 | Parameter error | Check command syntax; fix and retry |
| 3 | API returned structured error | See stderr for error code + fix |

## Troubleshooting

For all error codes, recovery actions, and retry policy, see [error-handling.md](error-handling.md).


path: references/textin-key-setup.md
content: # TextIn Key Setup

Configure paid API credentials to remove file size limits and increase daily quota.

## When to Configure

- Free daily limit exceeded (40001 error)
- File size exceeds 10MB limit (40302 error)
- Want unlimited quota for production use

## Setup Steps

### Option 1: Interactive Setup (recommended)

```bash
xparse-cli auth                    # Interactive credential setup
```

Follow the prompts to enter your `APP_ID` and `SECRET_CODE` from [TextIn Console](https://www.textin.com/console/dashboard/setting). Credentials are saved to `~/.xparse-cli/config.yaml`.

### Option 2: Environment Variables

For CI/automation, set environment variables:

```bash
export XPARSE_APP_ID=<your_app_id>
export XPARSE_SECRET_CODE=<your_secret_code>
```

### Verify Setup

```bash
xparse-cli auth --show             # Show current credential source
xparse-cli parse <FILE>            # Should succeed without "unauthorized" errors
```

Credential priority: CLI flags → env vars → `~/.xparse-cli/config.yaml`

## Troubleshooting

For all error codes and recovery actions, see [error-handling.md](error-handling.md).

## References

- [TextIn Console](https://www.textin.com/console/dashboard/setting)
- [TextIn Documentation](https://docs.textin.com/)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)