PuzzleTide Puzzle Generator

PuzzleTide CLI — trình tạo trò chơi tìm từ, ô chữ & sudoku

Trình tạo trò chơi tìm từ, trình tạo ô chữ và trình tạo & giải sudoku trong một CLI tạo câu đố ưu tiên cục bộ — với bảng tính PDF có thể in, ngân hàng từ khởi đầu, đánh giá LLM có thể xác minh và các kỹ năng tác nhân đi kèm. Từ nhà sản xuất của puzzletide.com.

Cài đặt

npm install -g puzzletide
ptide --version

Gói cài đặt cả hai tệp nhị phân:

• ptide
• puzzletide

Tại sao nên tạo câu đố bằng CLI

Yêu cầu một mô hình ngôn ngữ viết một trò chơi tìm từ và bạn nhận được một lưới mà một nửa số từ bị hỏng; yêu cầu nó tạo một sudoku và bạn thường nhận được một câu đố có nhiều lời giải, hoặc không có lời giải nào. Lưới chính xác là loại đầu ra mà LLM làm không tốt và mã xác định làm tốt.

PuzzleTide CLI chính là mã xác định đó:

• Mỗi từ trong trò chơi tìm từ được đặt và có thể xác minh — tọa độ vị trí là một phần của đầu ra, và các trình tạo được kiểm tra thuộc tính.
• Mỗi sudoku được tạo ra đều được kiểm tra để có chính xác một lời giải.
• Mỗi ô chữ được xác thực dựa trên chính các gợi ý của nó trước khi được trả về.
• Cùng một --seed đầu vào, cùng một câu đố đầu ra, trên bất kỳ máy nào.

Gói cũng đi kèm các kỹ năng tác nhân SKILL.md, để các tác nhân lập trình (Pi, Hermes, OpenClaw và các hệ thống dựa trên SKILL.md khác) sử dụng CLI thay vì tự viết lưới thủ công.

Mô hình lệnh

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

Sử dụng lệnh ngắn khi tương tác và id công cụ chuẩn trong tự động hóa:

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

Trình tạo trò chơi tìm từ

Tám hướng đặt với các cài đặt sẵn dễ/trung bình/khó, lưới tự động điều chỉnh kích thước (6–30), chuẩn hóa dấu, khoảng trắng, dấu gạch nối. Từ đến từ cờ, tệp hoặc chủ đề đi kèm:

# 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

Trình tạo ô chữ

Vị trí đan xen với đánh số ô chữ tiêu chuẩn, xác thực lưới gợi ý và gợi ý dự phòng xác định cho các từ chủ đề. Các từ không thể đan xen được báo cáo thay vì bị loại bỏ một cách âm thầm:

# 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"

Trình tạo và giải sudoku

Sudoku dễ, trung bình, khó và chuyên gia (17–21 ô cho sẵn) với đảm bảo tính duy nhất, một trình giải tức thì và một trình xác thực báo cáo xung đột, khả năng giải và tính duy nhất của lời giải:

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

Câu đố có thể in: Bảng tính PDF và SVG

Mỗi trình tạo nhận --pdf <file> cho một bảng tính sẵn sàng in — trang câu đố cộng với một trang lời giải (--paper letter|a4, bỏ qua khóa trả lời với --no-solution-page) — và --svg <file> cho hình ảnh vector. Trò chơi tìm từ có thể in và bảng sudoku có thể in cho một gói tài liệu lớp học chỉ cách một vòng lặp:

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

Thích các bảng có sẵn hơn? Trò chơi tìm từ bí ẩn và án mạng có thể in là một yêu thích của độc giả, với hàng trăm cái khác tại câu đố có thể in.

Ngân hàng từ và công cụ từ

30 chủ đề khởi đầu (động vật đại dương, trái cây, không gian, halloween, ...) — duyệt, tìm kiếm, khớp mẫu, đảo chữ, chọn ngẫu nhiên. Mang danh sách của riêng bạn qua --words/--file, hoặc chơi toàn bộ bộ sưu tập được tuyển chọn tại puzzletide.com:

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

Cũng có một trò chơi hangman trong terminal: ptide play hangman.

Kỹ năng tác nhân

Pi có thể tải các kỹ năng đi kèm trực tiếp từ gói npm này:

pi install npm:puzzletide

Tệp kê khai gói khai báo:

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

Năm kỹ năng được bao gồm: tìm từ, ô chữ, sudoku, câu đố có thể in, và đánh giá tác nhân. Mỗi kỹ năng ưu tiên CLI cục bộ và kiểm tra ptide, puzzletide, sau đó là npx puzzletide. Các kỹ năng không bao giờ tự động cài đặt bất cứ thứ gì; tác nhân nên hỏi người dùng trước khi cài đặt.

Máy chủ MCP cho Claude Desktop, Cursor và bất kỳ máy khách MCP nào

Gói đồng hành puzzletide-mcp phơi bày mọi công cụ không tương tác qua Giao thức Ngữ cảnh Mô hình — cùng một trình tạo trò chơi tìm từ, trình tạo ô chữ, trình tạo/giải sudoku, công cụ từ và đánh giá, có thể gọi từ Claude Desktop, Cursor, Windsurf hoặc bất kỳ máy khách MCP nào:

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

Xem docs/mcp.md để biết tên công cụ, đối số và thiết lập cho từng máy khách.

Công cụ

Máy chủ MCP (và ptide run <tool-id>) phơi bày 15 công cụ:

• puzzle_wordsearch_generate: Tạo lưới tìm từ từ các từ tùy chỉnh, tệp hoặc ngân hàng từ theo chủ đề — mọi vị trí có thể xác minh, có thể in qua PDF/SVG.
• puzzle_crossword_generate: Tạo ô chữ đan xen với đánh số tiêu chuẩn và gợi ý được xác thực.
• puzzle_sudoku_generate: Tạo sudoku dễ, trung bình, khó hoặc chuyên gia với lời giải duy nhất được đảm bảo.
• puzzle_sudoku_solve: Giải một sudoku từ chuỗi 81 ký tự của nó và báo cáo liệu lời giải có duy nhất không.
• puzzle_sudoku_validate: Xác thực lưới sudoku — xung đột, khả năng giải và tính duy nhất của lời giải.
• words_categories: Liệt kê các danh mục ngân hàng từ.
• words_themes: Liệt kê hoặc tìm kiếm các danh sách từ theo chủ đề đi kèm.
• words_list: Liệt kê các từ trong một chủ đề, được lọc theo độ dài hoặc số lượng.
• words_match: Tìm các từ khớp với mẫu kiểu ô chữ (c_r_l).
• words_anagram: Tìm các đảo chữ của các chữ cái đã cho trong ngân hàng từ.
• words_random: Chọn một từ ngẫu nhiên, tùy chọn từ một chủ đề.
• words_stats: Thống kê ngân hàng từ.
• eval_generate: Tạo các nhiệm vụ câu đố có thể tái tạo, có thể chấm điểm khách quan để đánh giá chuẩn LLM và tác nhân.
• eval_check: Chấm điểm câu trả lời cho các nhiệm vụ đánh giá đã tạo theo cấu trúc — không cần tin cậy khóa trả lời.
• play_daily: In sudoku hàng ngày của ngày hôm nay (giống nhau cho mọi người trong một ngày UTC).

Đánh giá LLM có thể xác minh

Câu trả lời câu đố có thể kiểm tra mà không cần khóa trả lời: một câu trả lời sudoku hoặc thỏa mãn các quy tắc và bảo toàn các ô cho sẵn hoặc không; một câu trả lời tìm từ hoặc đánh vần từ dọc theo một đường thẳng trong lưới hoặc không. Điều đó làm cho câu đố trở thành nhiệm vụ đánh giá chuẩn sạch sẽ cho đánh giá LLM — không cần giám khảo 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

Bộ (loại, độ khó, n, seed) hoàn toàn xác định tập nhiệm vụ, vì vậy nó đặt tên cho một tiêu chuẩn có thể tái tạo.

Sử dụng thư viện

Các engine có thể nhập dưới dạng TypeScript mà không cần 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' });

Thêm tài liệu:

• Lệnh CLI
• Sổ đăng ký công cụ
• Kỹ năng tác nhân

Phiên bản trực tuyến

Thích trình duyệt hơn?

• PuzzleTide tìm từ
• PuzzleTide ô chữ
• PuzzleTide sudoku
• PuzzleTide hangman
• Câu đố có thể in
• Tự tạo câu đố của bạn
• Phông chữ và cài đặt tìm từ thân thiện với chứng khó đọc

Quyền riêng tư

Mọi thứ chạy cục bộ. Không cần tài khoản, không cần khóa API, không đo lường từ xa, không truy cập mạng.

Phát triển

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

Các ngân hàng từ khởi đầu là các danh sách gốc, chung chung được viết cho gói này (scripts/wordbanks-source.json, được biên dịch với npm run build:wordbanks). Đóng góp chủ đề được hoan nghênh — thêm một mục vào tệp nguồn và chạy bản dựng. Toàn bộ bộ sưu tập ngân hàng từ PuzzleTide được tuyển chọn là độc quyền của puzzletide.com và không thuộc kho lưu trữ này.

Trích dẫn PuzzleTide CLI

Nếu bạn sử dụng PuzzleTide CLI trong công việc của mình — ví dụ như đánh giá câu đố có thể xác minh trong một tiêu chuẩn mô hình — vui lòng trích dẫn nó (hoặc sử dụng nút "Trích dẫn kho lưu trữ này" của GitHub):

@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}}
}

Văn bản thuần túy: "PuzzleTide CLI (Caravaca Labs, 2026), https://github.com/Caravaca-Labs/puzzletide-cli — từ nhà sản xuất của https://puzzletide.com."

Giấy phép

MIT © Caravaca Labs