# 迷宫猎人

**Repository Path**: shanewa/maze-hunter

## Basic Information

- **Project Name**: 迷宫猎人
- **Description**: 一个抓取迷宫（Maze）平台数据的爬虫
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# maze-hunter

Reproducible two-phase toolkit for collecting free printable maze books from [krazydad.com/mazes](https://krazydad.com/mazes/).

Krazydad allows personal / school / institutional reproduction of these puzzles. Please respect the site: keep polite delays, do not republish for profit without permission, and consider [donating](https://krazydad.com/mazes/) if you find the puzzles useful.

## Requirements

- Node.js 18+ (uses built-in `fetch`; no npm dependencies)

### Runtime environment

This repo was developed and verified on **Windows native PowerShell** (`win32`), not WSL2. The scripts are still cross-platform: the same `npm run scrape` / `npm run download` commands work in WSL2, macOS, and Linux as long as Node.js 18+ is available.

## Layout

```
scripts/
  lib.mjs                 # shared helpers (slug, fetch, urls)
  scrape-catalog.mjs      # Phase 1: collect download links
  download-books.mjs      # Phase 2: batch download PDFs
data/
  catalog.json            # generated by Phase 1
  catalog.yaml            # same catalog, YAML form
downloads/                # generated by Phase 2 (gitignored)
  简单迷宫-4-6岁/
    KD_Mazes_EZ_v1.pdf
    ...
```

Category folders under `downloads/` use Chinese names (no spaces), e.g. `Easy Mazes (Ages 4-6)` → `简单迷宫-4-6岁`. English `slug` remains in the catalog for stable IDs / `--only`.

## Collection stats

Full download of the current catalog (verified locally):

| | Count |
|---|---:|
| Categories | **9** |
| PDF books | **401** |
| Mazes (approx.) | **~7200+** |
| Total size | **~243 MB** |

Maze counts follow the site/blog: most books have **20** mazes each; dinosaur books have **12** each. *Kingdom of Mazes* is a separate story booklet (~6 pages) and is not counted into the ~7200 total.

### By category

| Folder | Source title | PDFs | Mazes / book | Mazes (approx.) | Notes |
|--------|--------------|-----:|-------------:|----------------:|-------|
| `简单迷宫-4-6岁` | Easy Mazes (Ages 4-6) | 50 | 20 | 1000 | Short paths, few junctions; ages ~4–6 |
| `中级迷宫-6-8岁` | Intermediate Mazes (Ages 6-8) | 50 | 20 | 1000 | Mild step up; ages ~6–8 |
| `进阶迷宫-7-9岁` | Challenging Mazes (Ages 7-9) | 50 | 20 | 1000 | More junctions; ages ~7–9 |
| `困难迷宫-9-12岁及以上` | Tough Mazes (Ages 9-12+) | 50 | 20 | 1000 | Longer paths; ages ~9–12+ |
| `超难迷宫-全年龄` | Super Tough Mazes (For robots of all ages) | 50 | 20 | 1000 | Hardest animal-shape set; all ages |
| `简单到进阶恐龙迷宫-6-12岁` | Easy to Challenging Dinosaur Mazes (Ages 6-12) | 50 | 12 | 600 | Dino shapes; within each book, easy → harder |
| `困难恐龙迷宫-9岁及以上` | Tough Dinosaur Mazes (Ages 9+) | 50 | 12 | 600 | Harder dino set; ages ~9+ |
| `综合动物迷宫-4-12岁及以上` | Assorted Animal Mazes Easy-Tough (Ages 4-12+) | 50 | 20 | 1000 | Mixed animal shapes, easy–tough mix |
| `迷宫王国` | Kingdom of Mazes | 1 | — | story booklet | Hand-drawn color mazes by Gleb Ganin; branching story |

The first five folders are the same animal-shape maze style at increasing difficulty. Dinosaur / assorted / kingdom are themed variants.

## Phase 1 — scrape catalog

```bash
npm run scrape
# or
node scripts/scrape-catalog.mjs
```

This visits the mazes homepage, discovers every difficulty / theme category, then opens each category page and records every book download URL into `data/catalog.json` and `data/catalog.yaml`.

Useful options:

```bash
node scripts/scrape-catalog.mjs --out data/catalog.json --delay-ms 500
```

## Phase 2 — batch download

Run manually after Phase 1:

```bash
npm run download
# or
node scripts/download-books.mjs
```

Useful options:

```bash
# preview without downloading
npm run download:dry

# one category only
node scripts/download-books.mjs --only 简单迷宫-4-6岁

# smoke-test first 3 files
node scripts/download-books.mjs --limit 3

# custom paths / rate limit
node scripts/download-books.mjs --catalog data/catalog.json --out downloads --delay-ms 800

# re-download existing files
node scripts/download-books.mjs --force
```

Already-downloaded PDFs are skipped unless `--force` is set.

## Site structure (reference)

1. Homepage lists categories such as `index.php?sv=EZ` (Easy Mazes).
2. Category pages list books as `index.php?sv=DL&pf=sfiles/KD_Mazes_EZ_vN.pdf&title=...`.
3. The real PDF URL is `https://files.krazydad.com/mazes/sfiles/KD_Mazes_EZ_vN.pdf`.

Donation-gated placeholders (PayPal links labeled as a book) are recorded as `status: locked_donation` and skipped by the downloader.