PuzzleTide Puzzle Generator

PuzzleTide CLI — генератор поиска слов, кроссвордов и судоку

Генератор поиска слов, генератор кроссвордов и генератор + решатель судоку в одном локальном CLI-инструменте для создания головоломок — с печатными PDF-заданиями, стартовыми наборами слов, проверяемыми оценками LLM и встроенными навыками агента. От создателей puzzletide.com.

Установка

npm install -g puzzletide
ptide --version

Пакет устанавливает оба исполняемых файла:

• ptide
• puzzletide

Зачем генерировать головоломки с помощью CLI

Попросите языковую модель написать поиск слов, и вы получите сетку, где половина слов сломана; попросите судоку — и обычно получите вариант с несколькими решениями или без них. Сетки — это именно тот тип вывода, с которым LLM справляются плохо, а детерминированный код — хорошо.

PuzzleTide CLI — это тот самый детерминированный код:

• Каждое слово в поиске слов размещено и проверяемо — координаты размещения являются частью вывода, а генераторы протестированы на свойствах.
• Каждое сгенерированное судоку проверяется на наличие ровно одного решения.
• Каждый кроссворд проверяется по собственным подсказкам перед возвратом.
• Одинаковые --seed на входе — одинаковая головоломка на выходе, на любой машине.

Пакет также поставляет SKILL.md навыков агента, чтобы агенты по кодированию (Pi, Hermes, OpenClaw и другие системы на основе SKILL.md) обращались к CLI вместо рукописного создания сеток.

Модель команд

ptide <namespace> <operation> [input] [options]   # for humans
ptide run <tool-id> [input] [options] --json      # canonical, for scripts/agents
ptide tools list | search <q> | info <id> | docs <id>
ptide agent manifest

Используйте короткие команды в интерактивном режиме и канонические идентификаторы инструментов в автоматизации:

ptide sudoku generate --difficulty hard
ptide run puzzle.sudoku.generate --difficulty hard --json

Генератор поиска слов

Восемь направлений размещения с пресетами easy/medium/hard, автоматически подбираемые сетки (6–30), нормализация акцентов/пробелов/дефисов. Слова берутся из флагов, файлов или встроенных тем:

# Word search from your own words, printed in the terminal
ptide wordsearch generate --words "coral,shark,kelp,wave,tide"

# Themed printable word search (puzzle page + solution page)
ptide wordsearch generate --theme animals/ocean-animals --pdf ocean.pdf

# Kids mode: easy = forward-only words
ptide wordsearch generate --theme seasonal/halloween --difficulty easy

Генератор кроссвордов

Перекрестное размещение со стандартной нумерацией кроссвордов, проверкой сетки подсказок и детерминированными резервными подсказками для тематических слов. Слова, которые не могут быть перекрестно размещены, выводятся в отчете, а не удаляются молча:

# Crossword with your clues
ptide crossword generate --words "PARIS: Capital of France; TOKYO: Capital of Japan"

# From a JSON file, as a printable PDF
ptide crossword generate --file words.json --pdf review.pdf --title "Unit 4 Review"

Генератор и решатель судоку

Судоку уровней easy, medium, hard и expert (17–21 подсказка) с гарантией уникальности, мгновенным решателем и валидатором, который сообщает о конфликтах, решаемости и уникальности решения:

ptide sudoku generate --difficulty expert --seed 42
ptide sudoku solve "53..7....6..195....98....6.8...6...34..8.3..17...2...6.6....28....419..5....8..79"
ptide sudoku validate --file puzzle.txt
ptide daily        # today's daily sudoku, same for everyone on a given UTC day

Печатные головоломки: PDF-задания и SVG

Каждый генератор принимает --pdf <file> для готового к печати задания — страницы с головоломкой плюс страница с решением (--paper letter|a4, исключите ключ ответов с помощью --no-solution-page) — и --svg <file> для векторных изображений. Печатные листы для поиска слов и судоку для классного комплекта создаются в одном цикле:

for i in 1 2 3 4 5; do
  ptide sudoku generate --difficulty medium --seed "$i" --pdf "sudoku-$i.pdf" --title "Sudoku #$i"
done

Предпочитаете готовые листы? Детективный и криминальный печатный поиск слов — любимчик читателей, а сотни других доступны в разделе печатные головоломки.

Наборы слов и инструменты для работы со словами

30 стартовых тем (морские животные, фрукты, космос, хэллоуин, ...) — просмотр, поиск, сопоставление с образцом, анаграммы, случайный выбор. Используйте свои списки через --words/--file или играйте с полной курируемой коллекцией на puzzletide.com:

ptide words themes --search dinosaur
ptide words match "c_r_l"        # crossword-style pattern matching
ptide words anagram coral

В терминале также есть игра "Виселица": ptide play hangman.

Навыки агента

Pi может загружать встроенные навыки непосредственно из этого npm-пакета:

pi install npm:puzzletide

Манифест пакета объявляет:

{
  "pi": {
    "skills": ["./skills"]
  }
}

Включено пять навыков: поиск слов, кроссворд, судоку, печатные головоломки и оценки агента. Каждый предпочитает локальный CLI и проверяет ptide, puzzletide, затем npx puzzletide. Навыки никогда ничего не устанавливают автоматически; агенты должны спрашивать пользователя перед установкой.

MCP-сервер для Claude Desktop, Cursor и любого MCP-клиента

Сопутствующий пакет puzzletide-mcp предоставляет каждый неинтерактивный инструмент через Model Context Protocol — тот же генератор поиска слов, генератор кроссвордов, генератор/решатель судоку, инструменты для работы со словами и оценки, вызываемые из Claude Desktop, Cursor, Windsurf или любого MCP- клиента:

{
  "mcpServers": {
    "puzzletide": {
      "command": "npx",
      "args": ["-y", "puzzletide-mcp"]
    }
  }
}

См. docs/mcp.md для получения имен инструментов, аргументов и настройки для каждого клиента.

Инструменты

MCP-сервер (и ptide run <tool-id>) предоставляет 15 инструментов:

• puzzle_wordsearch_generate: Сгенерировать сетку поиска слов из пользовательских слов, файлов или тематических наборов слов — каждое размещение проверяемо, доступно для печати через PDF/SVG.
• puzzle_crossword_generate: Сгенерировать перекрестный кроссворд со стандартной нумерацией и проверенными подсказками.
• puzzle_sudoku_generate: Сгенерировать судоку уровня easy, medium, hard или expert с гарантированно уникальным решением.
• puzzle_sudoku_solve: Решить судоку из его 81-символьной строки и сообщить, является ли решение уникальным.
• puzzle_sudoku_validate: Проверить сетку судоку — конфликты, решаемость и уникальность решения.
• words_categories: Список категорий наборов слов.
• words_themes: Список или поиск по встроенным тематическим спискам слов.
• words_list: Список слов в теме, отфильтрованный по длине или количеству.
• words_match: Найти слова, соответствующие шаблону в стиле кроссворда (c_r_l).
• words_anagram: Найти анаграммы заданных букв в наборе слов.
• words_random: Выбрать случайное слово, опционально из одной темы.
• words_stats: Статистика набора слов.
• eval_generate: Сгенерировать воспроизводимые, объективно оцениваемые задачи-головоломки для бенчмаркинга LLM и агентов.
• eval_check: Оценить ответы на сгенерированные оценочные задачи по конструкции — без доверия к ключу ответов.
• play_daily: Вывести сегодняшнее ежедневное судоку (одинаковое для всех в течение суток по UTC).

Проверяемые оценки LLM

Ответы головоломок проверяемы без ключа ответов: ответ судоку либо удовлетворяет правилам и сохраняет подсказки, либо нет; ответ поиска слов либо составляет слово по прямой линии в сетке, либо нет. Это делает головоломки чистыми задачами для бенчмаркинга LLM — без необходимости в LLM-судье:

ptide eval generate --type sudoku --n 20 --difficulty hard --seed 1 --out tasks.json
# ...run your model on tasks.json, collect [{id, answer}] ...
ptide eval check --tasks tasks.json --answers answers.json --json

Кортеж (тип, сложность, n, seed) полностью определяет набор задач, поэтому он задает воспроизводимый бенчмарк.

Использование библиотеки

Движки импортируемы на TypeScript без участия CLI:

import { generateSudoku, generateWordSearch, wordSearchPdf } from 'puzzletide';

const sudoku = generateSudoku({ difficulty: 'hard', seed: 42 });
const search = generateWordSearch({
  words: ['coral', 'shark', 'kelp'],
  directions: ['E', 'S', 'SE'],
  seed: 7,
});
const pdfBytes = await wordSearchPdf(search, { title: 'Ocean Animals' });

Дополнительная документация:

• Команды CLI
• Реестр инструментов
• Навыки агента

Онлайн-версии

Предпочитаете браузер?

• PuzzleTide поиск слов
• PuzzleTide кроссворд
• PuzzleTide судоку
• PuzzleTide виселица
• Печатные головоломки
• Создать свою головоломку
• Шрифты и настройки поиска слов для людей с дислексией

Конфиденциальность

Все работает локально. Никаких учетных записей, API-ключей, телеметрии, доступа к сети.

Разработка

npm install
npm run build     # tsc → dist/
npm test          # vitest + fast-check property tests (build first: CLI tests run dist/)

Стартовые наборы слов — это общие, оригинальные списки, написанные для этого пакета (scripts/wordbanks-source.json, скомпилированы с помощью npm run build:wordbanks). Вклад в темы приветствуется — добавьте запись в исходный файл и запустите сборку. Полная курируемая коллекция наборов слов PuzzleTide является собственностью puzzletide.com и не является частью этого репозитория.

Цитирование PuzzleTide CLI

Если вы используете PuzzleTide CLI в своей работе — например, проверяемые оценки головоломок в бенчмарке моделей — пожалуйста, процитируйте его (или используйте кнопку GitHub "Cite this repository"):

@software{puzzletide_cli,
  author  = {{Caravaca Labs}},
  title   = {PuzzleTide CLI: word search, crossword \& sudoku generator with verifiable LLM evals},
  year    = {2026},
  url     = {https://github.com/Caravaca-Labs/puzzletide-cli},
  note    = {From the makers of \url{https://puzzletide.com}}
}

Обычный текст: "PuzzleTide CLI (Caravaca Labs, 2026), https://github.com/Caravaca-Labs/puzzletide-cli — от создателей https://puzzletide.com."

Лицензия

MIT © Caravaca Labs