Przejdź do treści

Wprowadzenie

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: 2cc7b2b

Queuety to wtyczka WordPress zapewniająca szybką kolejkę zadań, trwały silnik przepływów pracy i środowisko uruchomieniowe trwałych maszyn stanów. Procesy robocze pobierają zadania bezpośrednio z MySQL i przetwarzają je w długotrwałym procesie WP-CLI. Środowisko uruchomieniowe PHP, które ładuje WordPress i WP-CLI, wymaga mysqli lub pdo_mysql.

Dlaczego Queuety?

WordPress nie ma prawdziwego systemu zadań działających w tle. wp_cron uruchamia się tylko podczas odwiedzin strony. Domyślny mechanizm Action Scheduler działa przez WP-Cron i żądania HTTP do tej samej witryny, przetwarzając każdorazowo partie przez maksymalnie 30 sekund. Wywołanie API LLM trwające 60 sekund zostaje przerwane przez limit czasu 30 sekund w PHP. Nie ma sposobu na uruchamianie procesów wieloetapowych, które przetrwają awarie i wznowią pracę od miejsca przerwania.

Queuety rozwiązuje ten problem za pomocą trzech podstawowych elementów:

  1. Zadania do wykonywanej w tle pracy, której wyniku nie trzeba odbierać
  2. Przepływy pracy do trwałych, wieloetapowych procesów ze stanem zachowywanym między uruchomieniami
  3. Maszyny stanów do długotrwałych cykli życia sterowanych zdarzeniami

Szybki przykład

Zleć zadanie przy użyciu nowoczesnego API:

PHP
use Queuety\Contracts\Job;
use Queuety\Dispatchable;

readonly class SendEmailJob implements Job {
    use Dispatchable;

    public function __construct(
        public string $to,
        public string $subject,
        public string $body,
    ) {}

    public function handle(): void {
        wp_mail( $this->to, $this->subject, $this->body );
    }
}

SendEmailJob::dispatch( 'user@example.com', 'Welcome', 'Hello from Queuety!' );

Możesz też użyć klasycznego podejścia z nazwą procedury obsługi:

PHP
use Queuety\Queuety;

Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );

Uruchom trwały przepływ pracy:

PHP
Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );

Zamodeluj długotrwałą sesję za pomocą maszyny stanów:

PHP
use Queuety\Enums\StateMachineStatus;

Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

Uruchom proces roboczy:

Powłoka
wp queuety work

Jeśli tworzysz system oparty na agentach, zacznij od Orkiestracja agentów. Pokazano tam, jak współdziałają przepływy planowania i wykonywania, punkty weryfikacji przez człowieka oraz oczekiwanie na inne przepływy pracy.

Jeśli system jest sterowany zdarzeniami i długotrwały, obok przepływów pracy zacznij od Maszyn stanów.

Jeśli szukasz przykładów integracji od początku do końca, zobacz Przykłady, które obejmują teraz wzorce oparte na Neuron do przełączania dostawców, przesyłania strumieniowego, ponawiania weryfikacji z wykorzystaniem pamięci oraz zależnych przepływów pracy.

Jeśli chcesz uruchamiać przepływy pracy na podstawie zdarzeń domenowych WordPress, takich jak save_post, zobacz Wyzwalacze akcji.

Jeśli chcesz używać środowiska uruchomieniowego opartego na bazie danych poza WordPress, zobacz Użycie samodzielne.

Najważniejsze wyróżniki

  • Szybkie wykonywanie. Procesy robocze uzyskują bezpośredni dostęp do kolejki MySQL i unikają wzorca cron dla każdego żądania, który spowalnia pracę w tle w WordPress.
  • Trwałe przepływy pracy. Procesy wieloetapowe ze stanem zachowywanym między uruchomieniami, odporne na przekroczenia limitu czasu PHP, awarie i ponowienia. Granica każdego kroku jest atomową transakcją MySQL.
  • Jawne maszyny stanów. Modeluj sesje czatu, zatwierdzenia i inne długotrwałe cykle życia za pomocą nazwanych stanów, kontrolowanych przejść, kolejkowanych działań przy wejściu w stan oraz trwałych osi czasu zdarzeń.
  • Nowoczesne zlecanie API. Samodzielne klasy zadań z cechą Dispatchable, typowanymi właściwościami konstruktora jako danymi oraz deklarowanymi w klasie elementami $tries/$timeout/$backoff. Klasa readonly nie może ustawiać wartości domyślnych tych właściwości, dlatego zadeklaruj je w zwykłej klasie za pomocą promowanych właściwości konstruktora tylko do odczytu.
  • Potok oprogramowania pośredniczącego. Oprogramowanie pośredniczące o strukturze cebuli do ograniczania liczby żądań, łagodzenia skutków wyjątków, unikalnych zadań i własnej logiki. Deklarowane dla każdego zadania za pomocą metody middleware().
  • Kroki strumieniowe. Interfejs StreamingStep zwraca fragmenty, które są natychmiast zapisywane w bazie danych. Przy ponowieniu udostępniane są wcześniej zapisane fragmenty, aby strumień mógł wznowić pracę od miejsca przerwania. Idealne rozwiązanie dla odpowiedzi LLM i dużych pobrań.
  • Rozszerzalna warstwa pamięci podręcznej. CacheFactory automatycznie wykrywa APCu albo przechodzi na pamięć podręczną w pamięci operacyjnej. Własne mechanizmy przechowywania danych implementują Contracts\Cache. Warstwa służy wewnętrznie do sprawdzania limitów żądań i stanu kolejki.
  • Przetwarzanie partiami i łączenie zadań. Zlecaj grupy zadań z funkcjami zwrotnymi then/catch/finally i śledzeniem postępu albo łącz zadania sekwencyjnie, tak aby każde zależało od ukończenia poprzedniego.
  • Trwałe opóźnienia i oczekiwanie. delay() dodaje opóźnienia bezpieczne przy ponownym uruchomieniu procesu. wait_for_signal(), wait_for_signals(), wait_for_approval(), wait_for_input() i wait_for_workflow() pozwalają przepływom pracy czekać na zdarzenia zewnętrzne lub inne przepływy bez utrzymywania aktywnego procesu PHP.
  • Dynamiczna pętla for-each. for_each() rozwija gałęzie pracy wykryte podczas wykonywania na podstawie stanu przepływu pracy i obsługuje tryby ukończenia po sukcesie wszystkich, pierwszym sukcesie lub osiągnięciu kworum.
  • Asynchroniczne przekazywanie przepływów pracy. start_workflows() zamienia elementy wykryte podczas wykonywania w niezależne przepływy pracy najwyższego poziomu, na które można później czekać.
  • Wyzwalacze akcji WordPress. on_action() mapuje główne lub wtyczkowe haki akcji na trwałe zlecenia przepływów pracy z kontrolą warunków i idempotencją.
  • Trwałe artefakty. Przechowuj nazwane wyniki przepływu pracy poza głównym obiektem stanu i uwzględniaj je przy sprawdzaniu stanu, inspekcji CLI, eksporcie i odtwarzaniu.
  • Zabezpieczenia przepływów pracy. version(), deterministyczny skrót definicji, klucze idempotencji zleceń i budżety przepływów pracy ułatwiają analizę przebiegów agentów oraz utrudniają ich powielanie i niekontrolowane działanie.
  • Zarządzanie zasobami. Grupy współbieżności, jednostki kosztu, budżety przepływów pracy i przyjmowanie zadań przez procesy robocze pomagają utrzymać kosztowne operacje agentów w określonych granicach.
  • Kompensacja kroków. compensate_with() i compensate_on_failure() udostępniają mechanizmy wycofywania ukończonych kroków, gdy przepływy pracy zostaną anulowane lub zakończą się niepowodzeniem.
  • Sygnały aktywności. Długotrwałe kroki wysyłają sygnały aktywności, aby system odzyskiwania nieaktualnych zadań nie przejął aktywnej pracy.
  • Śledzenie przepływu pracy. Każde przejście kroku jest zapisywane wraz z danymi wejściowymi i wyjściowymi, stanem przed i po zmianie, kontekstem, artefaktami, fragmentami, błędami oraz debugowaniem w czasie przez workflow_state_at().
  • Kroki równoległe. Uruchamiaj kroki jednocześnie i czekaj na ukończenie wszystkich przed przejściem dalej.
  • Rozgałęzianie warunkowe. Pomijaj kroki i przechodź do nazwanych na podstawie wcześniejszego stanu za pomocą _next_step.
  • Uruchamianie przepływów pracy. Uruchamiaj podrzędne przepływy pracy, które przekazują wyniki z powrotem do nadrzędnego.
  • Kolejki priorytetowe. Cztery poziomy (Low, Normal, High, Urgent) za pomocą typowanych wyliczeń PHP.
  • Procesy robocze dla wielu kolejek. Przetwarzaj wiele kolejek z zachowaniem ścisłej kolejności priorytetów w jednym procesie roboczym.
  • Ograniczanie liczby żądań. Limity wykonywania dla każdej procedury obsługi w ruchomym oknie.
  • Zadania cykliczne. Planowanie według interwałów i cron z konfigurowalnymi zasadami nakładania się (Allow, Skip, Buffer).
  • Anulowanie przepływu pracy. Anuluj uruchomione przepływy pracy i wywołuj zarejestrowane procedury czyszczenia.
  • Przycinanie stanu. Automatycznie usuwaj stare wyniki kroków, aby ułatwić zarządzanie dużym stanem przepływu pracy.
  • Współbieżność procesów roboczych. --workers=N uruchamia wiele procesów z automatycznym ponownym uruchomieniem po awarii.
  • Pełna obserwowalność. Rejestrowanie w bazie danych, metryki dla poszczególnych procedur obsługi i webhooki zdarzeń.
  • Narzędzia do testowania. QueueFake rejestruje zlecone zadania i partie, aby umożliwić asercje w testach jednostkowych.
  • Atrybuty PHP. #[QueuetyHandler('name')] umożliwia rejestrowanie procedur obsługi bez konfiguracji.

Jak to działa

Procesy robocze działają w długotrwałym procesie WP-CLI i pobierają zadania bezpośrednio z MySQL. Wiersze kolejek, stan przepływów pracy, dzienniki, partie, sygnały i fragmenty strumieni znajdują się w MySQL, więc ponowne uruchomienie procesu roboczego nie powoduje utraty stanu orkiestracji.

Przepływy pracy dzielą długotrwałe zadania na kroki. Wynik każdego kroku jest zapisywany we wspólnym obiekcie stanu w bazie danych. Jeśli PHP zakończy działanie w trakcie kroku, proces roboczy ponowi ten krok z zachowaniem całego wcześniejszego stanu. Granica kroku jest pojedynczą transakcją MySQL: aktualizacja stanu, zakończenie zadania i dodanie następnego kroku do kolejki odbywają się atomowo.

Kod
Workflow: generate_report (3 steps)

Step 0: fetch_data     -> state: {user_data: {...}}
Step 1: call_llm       -> PHP dies -> retry -> state: {user_data: {...}, llm_response: "..."}
Step 2: format_output  -> state: {user_data: {...}, llm_response: "...", report_url: "/reports/42.pdf"}

Workflow: completed

Wymagania

  • PHP 8.2 lub nowszy
  • WordPress 6.4 lub nowszy
  • MySQL 8.0+ lub MariaDB 10.6+, ponieważ procesy robocze pobierają zadania za pomocą SELECT ... FOR UPDATE SKIP LOCKED
  • mysqli lub pdo_mysql w środowisku uruchomieniowym PHP, które ładuje WordPress i WP-CLI
  • WP-CLI do uruchamiania dedykowanych procesów roboczych za pomocą wp queuety work
  • Rozszerzenia pcntl i posix PHP do pul procesów roboczych (--workers, --min-workers, --max-workers)

Instrukcję instalacji znajdziesz w sekcji Pierwsze kroki.