Въведение

Преглед като Markdown Редактиране в GitHub Документация за 2cc7b2b

Queuety е плъгин WordPress, който осигурява бърза опашка за задачи, устойчив механизъм за работни процеси и среда за изпълнение на устойчиви автомати на състоянията. Работниците заемат задачи директно от MySQL и ги обработват в дълго работещ процес WP-CLI. Средата за изпълнение PHP, която зарежда WordPress и WP-CLI, изисква или mysqli, или pdo_mysql.

Защо Queuety?

WordPress няма истинска система за фонови задачи. wp_cron се задейства само при посещения на страници. Стандартният изпълнител на Action Scheduler разчита на WP-Cron и циклични заявки HTTP, като всяка обработва пакети за не повече от 30 секунди. Обаждане към LLM чрез API, което отнема 60 секунди, се прекратява от 30-секундния лимит на PHP. Няма начин да се изпълняват многоетапни процеси, които преживяват сривове и продължават от мястото, до което са стигнали.

Queuety решава този проблем с три основни примитива:

Задачи за фонова работа, която се стартира и забравя
Работни потоци за устойчиви многоетапни процеси със запазено състояние
Машини на състоянията за дълготрайно състояние на жизнения цикъл, управлявано от събития

Кратък пример

Изпратете задача с модерния 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!' );

Или използвайте класическия подход с име на обработчик:

PHP

use Queuety\Queuety;

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

Изпълнете устойчив работен поток:

PHP

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

Моделирайте дълготрайна сесия с машина на състоянията:

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 ] );

Стартирайте работник:

Обвивка

wp queuety work

Ако изграждате система с агенти, започнете с Оркестрация на агенти. Там е показано как работят заедно потоците с планиране и изпълнение, етапите за човешки преглед и изчакването между работни потоци.

Ако системата се управлява от събития и работи продължително, започнете с Машини на състоянията заедно с работните потоци.

За примери за интеграция от начало до край вижте Примери, където вече са включени модели, базирани на Neuron, за смяна на доставчик, поточно предаване, повторни прегледи с памет и зависими работни потоци.

За да стартирате работни потоци от събития в домейна на WordPress, като save_post, вижте Тригери за действия.

За да използвате средата за изпълнение, базирана на DB, извън WordPress, вижте Самостоятелна употреба.

Основни отличителни характеристики

Бързо изпълнение. Работниците осъществяват директен достъп до опашката MySQL и избягват модела cron за всяка заявка, който забавя фоновата работа в WordPress.
Устойчиви работни потоци. Многоетапни процеси със запазено състояние, които преживяват времевите ограничения PHP, сривовете и повторните опити. Границата на всяка стъпка е атомарна транзакция MySQL.
Явно дефинирани машини на състоянията. Моделирайте чат сесии, одобрения и други дълготрайни жизнени цикли с именувани състояния, защитени преходи, поставяни в опашка действия при влизане в състояние и устойчиви времеви линии на събитията.
Модерно разпределяне на задачи API. Самостоятелни класове за задачи с трейта Dispatchable, типизирани свойства на конструктора като полезен товар и $tries/$timeout/$backoff, декларирани в класа. Класът readonly не може да задава стойности по подразбиране за тези свойства, затова ги декларирайте в обикновен клас със свойства readonly, промотирани от конструктора.
Конвейер от междинен софтуер. Междинен софтуер с onion архитектура за ограничаване на честотата, ограничаване на изключенията, уникални задачи и персонализирана логика. Декларира се за всяка задача чрез метод middleware().
Поточни стъпки. Интерфейсът StreamingStep генерира части, които се записват незабавно в базата данни. При повторен опит предоставя вече записаните части, за да може потокът да продължи от мястото, до което е стигнал. Идеален за отговори от LLM и големи изтегляния.
Включващ се кеш слой. CacheFactory автоматично разпознава APCu или използва кеш в паметта като резервен вариант. Персонализираните бекендове имплементират Contracts\Cache. Използва се вътрешно за проверки от ограничителя на честотата и за състоянието на опашката.
Групиране и свързване. Разпределяйте групи задачи с обратни извиквания then/catch/finally и проследяване на напредъка или свързвайте задачи последователно, така че всяка да зависи от завършването на предишната.
Устойчиви забавяния и изчаквания. delay() добавя забавяния, които се запазват при рестартиране на процеса. wait_for_signal(), wait_for_signals(), wait_for_approval(), wait_for_input() и wait_for_workflow() позволяват на работните потоци да изчакват външни събития или други работни потоци, без да поддържат PHP активен.
Динамичен for-each. for_each() разширява работата по клонове, открити по време на изпълнение, въз основа на състоянието на работния поток и поддържа режими за завършване при успех на всички, първи успех или достигане на кворум.
Асинхронно предаване между работни потоци. start_workflows() превръща елементи, открити по време на изпълнение, в независими работни потоци от най-високо ниво, които могат да бъдат изчакани по-късно.
Тригери за действия WordPress. on_action() свързва основни или плъгин куки за действия с разпределяне на устойчиви работни потоци, като осигурява условия за изпълнение и идемпотентност.
Устойчиви артефакти. Съхранявайте именувани резултати от работните потоци извън основната колекция от състояния и ги включвайте в прегледа на състоянието, проверката чрез CLI, експортирането и повторното възпроизвеждане.
Предпазни механизми за работните потоци. version(), детерминистичен хеш на дефиницията, ключове за идемпотентно разпределяне и бюджети за работните потоци улесняват проверката на изпълненията с агенти и не позволяват задачите да се дублират или да продължават безконтролно.
Управление на ресурсите. Групите за паралелност, единиците за разходи, бюджетите за работните потоци и допускането на работници помагат скъпата работа с агенти да остане в зададените граници.
Компенсиране на стъпки. compensate_with() и compensate_on_failure() предоставят куки за връщане на завършени стъпки назад, когато работните потоци бъдат отменени или се провалят.
Пулсации. Дълго изпълняваните стъпки изпращат пулсации, за да попречат на системата за възстановяване на остарели задачи да присвои активна работа.
Проследяване на работните потоци. Всеки преход между стъпки се записва заедно с входните и изходните данни, състоянието преди и след прехода, контекста, артефактите, частите, грешките и отстраняването на грешки чрез пътуване във времето с workflow_state_at().
Паралелни стъпки. Изпълнявайте стъпките едновременно и изчаквайте завършването на всички, преди да продължите.
Условно разклоняване. Прескачайте към именувани стъпки въз основа на предишно състояние чрез _next_step.
Изпълнение на работни потоци. Стартирайте дъщерни работни потоци, които връщат резултатите към родителския.
Опашки с приоритети. Четири нива (Low, Normal, High, Urgent) чрез типобезопасни енуми PHP.
Работници с множество опашки. Обработвайте няколко опашки със строг ред на приоритетите в един работник.
Ограничаване на честотата. Лимити за изпълнение за всеки обработчик в рамките на плъзгащ се прозорец.
Повтарящи се задачи. Планиране по интервали и чрез cron с конфигурируеми правила за припокриване (Allow, Skip, Buffer).
Отмяна на работни потоци. Отменяйте изпълнявани работни потоци и задействайте регистрирани обработчици за почистване.
Ограничаване на състоянието. Автоматично премахвайте старите изходни данни от стъпките, за да поддържате управляеми големите състояния на работните потоци.
Паралелност на работниците. --workers=N стартира няколко процеса с автоматично рестартиране при срив.
Пълна наблюдаемост. Записване в база данни, показатели за всеки обработчик и уебкуки за събития.
Помощни средства за тестване. QueueFake записва разпределените задачи и пакетите, за да могат да се проверяват в модулни тестове.
Атрибути PHP. #[QueuetyHandler('name')] за регистриране на обработчици без конфигурация.

Как работи

Работниците се изпълняват в дълготраен процес WP-CLI и получават задачи директно от MySQL. Редовете на опашката, състоянието на работните потоци, регистрационните файлове, пакетите, сигналите и поточните части се съхраняват в MySQL, така че рестартирането на работниците не води до загуба на състоянието на оркестрацията.

Работните потоци разделят продължителната работа на стъпки. Изходните данни на всяка стъпка се запазват в обща колекция от състояния в базата данни. Ако PHP спре по средата на стъпка, работникът опитва отново тази стъпка с непокътнато предишно състояние. Границата на стъпката е една транзакция MySQL: актуализацията на състоянието, завършването на задачата и поставянето на следващата стъпка в опашката се извършват атомарно.

Код

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

Изисквания

PHP 8.2 или по-нова версия
WordPress 6.4 или по-нова версия
MySQL 8.0+ или MariaDB 10.6+, защото работниците получават задачи чрез SELECT ... FOR UPDATE SKIP LOCKED
mysqli или pdo_mysql в средата за изпълнение PHP, която зарежда WordPress и WP-CLI
WP-CLI за стартиране на специализирани работници с wp queuety work
Разширенията pcntl и posix PHP за пулове от работници (--workers, --min-workers, --max-workers)

За инсталиране вижте Първи стъпки.