skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
shkarupa-alex/benz59 installs

fuel-watch

Проверяет текущее наличие АИ-95 независимо от брендового или премиального названия, свежесть сигналов и очереди на АЗС в настроенной зоне Волгограда через agent-browser, хранит историю наблюдений (по умолчанию 90 дней), прогнозирует ближайшие появления и считает по истории статистику появления АИ-95 на каждой АЗС. Используй при запросах «где есть 95-й», «проверь бензин/АЗС/очереди», «когда появится или появился бензин», «следи за наличием» и «как часто/когда обычно на этой заправке бывает 95-й». Не используй для маршрутизации, отправки пользовательских отчётов на сайты или обхода CAPTCHA.

How do I install this agent skill?

npx skills add https://github.com/shkarupa-alex/benz --skill fuel-watch
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is a professional-grade monitoring tool for fuel availability and queue tracking. It is well-engineered with numerous security features such as environment isolation, PID verification for process management, and Markdown escaping. It process external data from well-known mapping and fuel price services. Findings are related to its core functionality: background monitoring via systemd timers, dynamic extraction scripts for the browser, and processing of third-party website content.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

Fuel Watch

Показывай только АЗС со свежим положительным или вероятно положительным свидетельством в основном списке. Все варианты одного октанового числа считай одной пользовательской маркой: базовый, премиальный и брендовый 95-й выводятся только как АИ-95, без отдельных строк 95+, «Экто», G-Drive и подобных. Исходную метку варианта сохраняй внутри только для provenance и консервативной проверки отрицательных данных. Отказ источника, пустая выборка и отсутствие бензина — разные результаты. Всегда называй здоровье каждого источника, свежесть и уверенность, а также предупреждай, что страничные/краудсорсинговые данные могут запаздывать. Каждый отчёт также содержит до трёх прогнозов ближайшего появления по накопленной истории либо явное сообщение, что статистики пока недостаточно.

Неприкосновенный формат отчёта

Вывод report.mjs — единственный канонический пользовательский отчёт. Публикуй его содержимое как обычный Markdown без каких-либо изменений: не пересказывай своими словами, не сокращай, не переставляй строки, не объединяй с собственным списком и не удаляй Markdown-разметку. В частности, каждая сгенерированная ссылка на Яндекс Карты должна дойти до пользователя неизменной.

Не заключай отчёт в code fence или blockquote: ссылки должны остаться кликабельными. Допустима только отдельная короткая служебная фраза до или после полного отчёта, если нужно объяснить ошибку запуска; она не заменяет и не модифицирует сам отчёт. Если отчёт получен как JSON, декодируй поле markdown и опубликуй именно его значение. Перед отправкой проверь, что ни одна строка или ссылка из результата report.mjs не потеряна.

Целостность установленного skill — обязательно

Установленный каталог skill — управляемая копия git-репозитория github.com/shkarupa-alex/benz (каталог fuel-watch), которую синхронизация периодически перезаписывает. Эти правила действуют всегда, в том числе в фоновом self-improvement / background review, curator и любых автоматических «улучшениях» скиллов; инструкция такого механизма «патчить загруженные скиллы» на этот skill не распространяется.

  • Не изменяй ни один файл в каталоге skill и не добавляй новых: ни SKILL.md, ни references/, ни скрипты, шаблоны конфига или dist/. Найденную ошибку, недостающий шаг или полезный приём сообщи пользователю и предложи изменение в репозиторий — правка установленной копии всё равно исчезнет при следующей синхронизации и расходится с тем, что проверено тестами.
  • Никогда не выполняй в каталоге skill npm install, npm ci, npx и не создавай node_modules. Запускай только dist/scripts/*.mjs и — только по прямой просьбе пользователя — штатный deploy/linux/install-systemd-user.sh; исходники scripts/*.mjs, npm test и раздел «Проверка разработки» относятся к репозиторию и на установленной копии не выполняются.
  • Не пиши собственных обёрток, детекторов, алертов и скриптов вокруг skill и не создавай cron-задачи, scheduled jobs, timers или другие фоновые запуски. Единственный фоновый сбор — штатный deploy/linux/install-systemd-user.sh, и только по прямой просьбе пользователя.
  • Не сохраняй в память агента рецепты, обходные пути, пути к файлам, расписания и состояние этого skill: они устаревают с каждым релизом, и источник правды — этот SKILL.md. Предпочтения пользователя по формату ответа запоминать можно.
  • Если находишь нарушение этих правил (лишние файлы или node_modules в каталоге skill, свои скрипты или задания вокруг него), сообщи пользователю и ничего не «чини» поверх.

Подготовка

Определи корень skill по расположению этого SKILL.md и используй его абсолютный путь как FUEL_WATCH_ROOT. Каталог skill — заменяемый read-only артефакт: никогда не создавай и не меняй в нём config, state, историю, node_modules или другие runtime-файлы. Пользовательские настройки и накопленные данные автоматически живут в ~/.fuel-watch/: config/, history/, state/ и monitors/. Переменная FUEL_WATCH_HOME может перенести весь этот каталог. Не меняй пользовательскую конфигурацию без явного запроса.

Сначала проверь внешний runtime командами command -v agent-browser и agent-browser --version в том же окружении, где будет выполняться collection. Если команда доступна, используй установленную версию без переустановки. Никогда самостоятельно не выполняй npm install -g agent-browser, npm update -g agent-browser, npx agent-browser или agent-browser install. Если команда отсутствует или не запускается, ничего глобально не устанавливай: верни BROWSER_UNAVAILABLE, покажи результат проверки и запроси у пользователя отдельное разрешение на изменение окружения.

Runtime поставляется заранее собранным в dist/ вместе со всеми Node.js-зависимостями. На целевой машине никогда не выполняй npm install, npm ci, npm update или npx для Fuel Watch. Отсутствие node_modules в установленном skill штатно. Если dist/scripts/collect.mjs отсутствует, верни ошибку повреждённого/неполного skill-пакета; не пытайся собирать его на целевой машине.

В штатной collection сайты открываются только через agent-browser, которым управляют скрипты. Не добавляй curl, fetch, прямой HTTP-клиент, CAPTCHA solver, dashboard, HAR, video, trace, restore/profile или фоновый браузер.

Штатная collection всегда использует HEADED Chromium без stealth-флагов и подмены fingerprint. Единственное исключение — User-Agent: если браузер фактически поднялся headless (на сервере без display это происходит несмотря на --headed) и источник ответил на это своей страницей автолимита, выполняется одна повторная попытка с той же личностью браузера, из которой убран токен Headless. Версия и платформа остаются настоящими, другой браузер не изображается, CAPTCHA не обходится; при желании строку можно задать явно через browser.userAgent. Если доступен пользовательский display, BrowserRunner сохраняет DISPLAY/WAYLAND_DISPLAY/XAUTHORITY; иначе agent-browser может использовать собственный Xvfb, но браузер всё равно остаётся non-headless. Не переноси результат HEADLESS-диагностики на обычный браузер или доступность сайта вообще. Каждый источник получает отдельную короткоживущую session, источники обрабатываются строго последовательно, поэтому одновременно активно не более одного окна.

BrowserRunner сначала обязательно устанавливает --allowed-domains. Поведение network controls различается между версиями agent-browser, поэтому fallback определяется по исходу, а не по тексту ошибки. Источник один раз повторяется в новой owned session без controls, если при запрошенных или активных controls agent-browser вернул известную CDP-ошибку их установки, не знает флага, не выполнил навигацию, завис или повторно упал на open, страница сразу или позже внутри адаптера стала about:blank/chrome-error, либо упала сама команда agent-browser (0.38.2 ломает реальные страницы именно так, молча). Не повторяются: ответ самого источника (CAPTCHA, HTTP-ошибка, смена схемы, страница, так и не ставшая готовой, уход на другой origin), ошибка скрипта адаптера и блокировка навигации — agent-browser не называет заблокированный URL, и её нельзя отличить от редиректа за пределы allowlist. Без controls сохраняются fail-closed проверки точного final host и page drift, причём URL проверяется до и после каждого извлечения данных (evalJson); внешний шлюз входа, на который страница ушла уже после open, тоже считается CHALLENGE. Такой результат всегда получает предупреждение BROWSER_NETWORK_CONTROLS_DEGRADED; не скрывай его и не называй fallback эквивалентом полноценной сетевой изоляции.

Штатный workflow не управляет вкладками и не собирает визуальные артефакты: он вызывает только скрипты ниже. Если пользователь явно просит показать браузер, исследовать DOM/network/console или отладить источник, сначала прочитай references/browser-debugging.md и выполняй диагностику отдельно от collection-run.

Разовая проверка

  1. Создай временный каталог через mktemp -d.

  2. Выполни:

    node "$FUEL_WATCH_ROOT/dist/scripts/collect.mjs" --output "$RUN_DIR/snapshot.json"
    node "$FUEL_WATCH_ROOT/dist/scripts/report.mjs" --snapshot "$RUN_DIR/snapshot.json"
    
  3. Опубликуй stdout report.mjs целиком и неизменным обычным Markdown даже при коде 2: он объясняет деградацию и не означает «бензина нет». Не создавай вместо него собственную сводку.

  4. При коде 75 предупреди о CLEANUP_FAILED, затем один раз проверь очистку только записанного owned namespace. Не запускай глобальный agent-browser close --all без namespace.

  5. Удали временный каталог. Компактная история статусов и часовых rolling-count сигналов по октановым маркам 92/95/98/100 сохраняется отдельно в пользовательском state-каталоге, хранится history.retentionDays дней (по умолчанию 90; старые дни удаляются автоматически) и используется следующими разовыми проверками, monitoring tick’ами и статистикой. Прогноз в отчёте читает только последние min(retentionDays, 28) дней; вся история доступна через history-stats.mjs (см. ниже). Перед сравнением соседних tick все варианты одного октанового числа агрегируются внутри station + source + tick: rolling-count суммируется; статус имеет приоритет IN_STOCK → LIMITED → OUT_OF_STOCK → UNKNOWN, поэтому нечитаемый вариант игнорируется при наличии хотя бы одного читаемого. Переход октана засчитывается только при свидетеле — один и тот же вариант присутствует в обоих tick и действительно изменился OUT_OF_STOCK → IN_STOCK/LIMITED или count 0 → count > 0; появление/исчезновение строки само по себе событием не является. Дизель, газ, неизвестные продукты и прочие октановые числа исключаются. Путь можно явно задать через --history; переменная FUEL_WATCH_HISTORY_PATH меняет default path.

Мониторинг в текущей задаче

Это режим «надо срочно заправиться»: частые опросы (monitoring.intervalMinutes, по умолчанию 10 минут), пока пользователь ищет, где заправиться. Запускай его только по явной просьбе пользователя («слежу/ищу, где заправиться», «следи за наличием»); фоновый timer его не заменяет — timer редкий и нужен для истории и прогноза. Сборы не пересекаются: collect.mjs ждёт окончания уже идущего сбора (timer, другой проверки) и выдерживает после него минимум минуту, так что tick, совпавший с timer, просто начнётся на несколько минут позже; ошибка COLLECTION_BUSY значит, что чужой сбор идёт дольше 10 минут, — сообщи об этом, не запускай сбор повторно в цикле. Не создавай automation, daemon или новую задачу: мониторинг выполняет активный агент в этом диалоге до команды пользователя остановиться (например, «заправился»), внешнего прерывания или разумного предела, о котором ты предупредил. Каждый tick — полный опрос всех источников, поэтому не держи режим включённым дольше, чем нужно пользователю.

  1. Инициализируй монитор и сохрани напечатанные monitorId и абсолютный stateDir в контексте задачи:

    node "$FUEL_WATCH_ROOT/dist/scripts/monitor.mjs" init
    
  2. Перед первым и каждым следующим tick проверь monitor.mjs due --state-dir "$STATE_DIR". Когда tick наступил:

    • запусти collect.mjs --previous "$STATE_DIR/previous.json" только если такой snapshot подготовлен агентом из предыдущего committed state;
    • создай отчёт report.mjs --snapshot "$SNAPSHOT" --state-dir "$STATE_DIR" --json;
    • вызови monitor.mjs prepare --state-dir "$STATE_DIR" --report-id "$REPORT_ID" --snapshot "$SNAPSHOT";
    • опубликуй значение markdown из JSON целиком, неизменным и не в code fence; не пересказывай его и не удаляй ссылки;
    • только после успешной публикации вызови monitor.mjs commit --state-dir "$STATE_DIR" --report-id "$REPORT_ID".
  3. Между tick’ами браузер уже закрыт. Жди foreground-командой sleep 45 или короче. После каждого фрагмента проверяй новый пользовательский ввод, monitor.mjs due и STOP через его поле stopped; не запускай единый sleep на весь интервал.

  4. После четырёх пустых tick’ов используй report.mjs --compact, но продолжай cadence.

  5. При возобновлении задачи сначала вызови monitor.mjs recover --state-dir "$STATE_DIR". Если есть pending report, повторно отрендери его с --recovered, сохрани тот же report ID и затем commit.

  6. При остановке вызови node "$FUEL_WATCH_ROOT/dist/scripts/monitor.mjs" stop --state-dir "$STATE_DIR", выполни одну namespace-scoped очистку последнего browser-run и заверши node "$FUEL_WATCH_ROOT/dist/scripts/monitor.mjs" cleanup --state-dir "$STATE_DIR". Подтверди удаление monitor-state; общие настройки, последний snapshot и история сохраняются.

Никогда не держи браузер во время ожидания. Любая коллекция чаще настроенного monitoring.intervalMinutes запрещена в monitoring mode.

Фоновый сбор и статистика по истории

Долгую историю для прогноза и статистики на Linux-сервере копит не агент, а systemd user timer: по расписанию он запускает один collect.mjs без агента, тот дописывает tick в историю и обновляет ~/.fuel-watch/state/latest.json. Для прогноза достаточно редкого сбора, например шесть раз в день: --on-calendar "*-*-* 07,10,13,16,19,22:30:00" вместе с history.sampleIntervalMinutes: 175 в пользовательском конфиге — это обычный промежуток между такими сборами, а ночной перерыв длиннее трёх таких промежутков честно считается дырой в данных. Без --on-calendar timer срабатывает каждые history.sampleIntervalMinutes. Без заданного history.sampleIntervalMinutes установщик откажется работать: интервал срочного мониторинга для timer слишком част, а фиксированное расписание с ним не согласуется. Это изменение пользовательского конфига, поэтому значение (для шести сборов в день — 175) согласуй с пользователем вместе с расписанием. Устанавливает его пользователь (или агент, но только по прямой просьбе пользователя): sh "$FUEL_WATCH_ROOT/deploy/linux/install-systemd-user.sh" [--on-calendar "..."], удаление — с --uninstall, просмотр unit-файлов без установки — с --print. Если node установлен через nvm, unit на каждом запуске берёт версию из nvm-алиаса default. Скрипт не меняет пользовательский конфиг и не требует root; для работы после выхода из сессии администратору нужно один раз включить loginctl enable-linger. Не создавай timer, cron или другую фоновую задачу по собственной инициативе и не запускай collect.mjs в цикле вместо timer. Журнал: journalctl --user -u fuel-watch-collect.service — по строке на запуск с вердиктами и здоровьем источников.

~/.fuel-watch/state/latest.json — снимок последнего сбора любого вида: timer, разовой проверки или мониторинга в задаче (разовый collect.mjs обновляет его и при явном --output, а без --area дописывает и tick в историю). На «что сейчас» сначала посмотри его fetchedAt: если снимок моложе freshness.freshMinutes, покажи report.mjs --snapshot ~/.fuel-watch/state/latest.json, назвав время сбора; иначе сделай разовую проверку — редкий фоновый снимок для ответа «что сейчас» не годится. Лишние опросы — нагрузка на источники (benzonavt уже блокировал IP за частые запросы), поэтому не делай разовых проверок чаще monitoring.intervalMinutes.

Статистика — только чтение, браузер не запускается:

node "$FUEL_WATCH_ROOT/dist/scripts/history-stats.mjs" [--station "<часть названия, адреса или ключа>" [--timeline]] [--days N] [--limit N] [--json]

По умолчанию печатается Markdown на русском по физическим АЗС (ключи одной АЗС, когда-либо встречавшиеся вместе, объединяются): доля опросов с АИ-95 / без него / неясно, текущее состояние и с какого времени, число завершённых перебоев (NOT_AVAILABLE → подтверждённый позитив без пропуска сбора длиннее трёх интервалов), медиана и межквартильный размах их длительности, распределение времени возвращения по часам МСК и типичное окно (только при трёх и более перебоях), а также поступления АИ-95 по сообщениям самих источников (переход «нет → есть» в отзывах; сообщения разных источников и пользователей в пределах двух часов — одно поступление; эвристика «возобновилась активность» сюда не входит). В шапке — период, покрытие опросами, самые длинные пропуски сбора и доля статуса OK по каждому источнику. --json даёт те же данные плюс распределение по дням недели и последние эпизоды для собственного анализа. --station … --timeline добавляет хронологию: каждый опрос этой АЗС со временем МСК, вердиктом, уверенностью, источниками, которые перечислили эту АЗС в том опросе, и источниками, не ответившими в нём полностью (CHALLENGE, PARTIAL и т. п.), — так отвечают на «показывали ли данные это в тот момент», не разбирая файлы истории вручную.

Когда пользователь сверяет отчёт со своим наблюдением или с приложением источника, назови время снимка и его возраст, источники, давшие вердикт по этой АЗС, и источники, которые в том опросе не ответили (CHALLENGE, TIMEOUT, PARTIAL и т. п.): их данных в оценке нет, и совпадение с приложением такого источника нельзя записывать ему в заслугу. Задержка между сборами — до одного интервала timer.

Интерпретируй честно: время возвращения — первый опрос, увидевший АИ-95, с точностью до интервала; перебой, на который пришёлся пропуск сбора, не считается вовсе; при расписании с ночной паузой каждая ночь — штатный пропуск сбора, а «ожидаемых» опросов в шапке больше реальных, это не сбой; источник, долго бывший в CHALLENGE/недоступным, сужает картину, и об этом нужно сказать. Не выдавай окно за расписание поставок, не делай выводов по одному-двум перебоям и не смешивай эту статистику с текущим отчётом: канонический отчёт по-прежнему публикуется без изменений, а статистика — отдельным ответом.

Изменение зоны

Для проверки anchor-координат выполни read-only команду:

node "$FUEL_WATCH_ROOT/dist/scripts/resolve-area.mjs"

Покажи найденные координаты и drift пользователю. Перезапись разрешена только после явного подтверждения: повтори с --write --confirm. Три неуникальные или коллинеарные точки, неверные координаты и неразрешённый anchor приводят к fail-closed.

Интерпретация

  • низкая, средняя и высокая в отчёте всегда означают уверенность Fuel Watch в собственной оценке, а не заявленную источником вероятность. Она выводится из свежести и специфичности свидетельства, provenance-групп и grade-specific активности. Не приписывай её отдельному сервису. Непроверенное source confidence/rating можно сохранить только как provenance; не подменяй им итоговую уверенность без формализованной семантики и калибровки.
  • последний подтверждающий сигнал — возраст самого свежего observation, реально участвующего в текущем положительном вердикте. только что означает возраст меньше одной минуты, а не обязательно изменение статуса или прибытие бензовоза. Источники текущей оценки и источники исторического перехода выводятся отдельными строками; не объединяй их в одну подпись.
  • ЕСТЬ: свежий прямой сигнал любого варианта АИ-95. СКОРЕЕ ЕСТЬ: семейный/косвенный положительный сигнал или подтверждённое grade-specific возобновление активности. В пользовательском отчёте и истории варианты одного октанового числа не разделяй.
  • Не называй generic signal транзакцией. TRANSACTIONS_RESUMED — только grade-specific разрыв не менее 60 минут и минимум два новых события за 20 минут.
  • Не трактуй время обновления как время поставки. «Появился между…» допустимо только для подтверждённого перехода из NOT_AVAILABLE; иначе говори «впервые увидели» или «время появления неизвестно».
  • Прогноз — не факт поставки. Сильнейший допустимый обучающий сигнал — типичное местное время перехода настоящего grade-specific rolling-count 0 → ≥2 по бензиновым маркам 92/95/98/100 после часового тихого окна. Не размножай агрегатный счётчик АЗС по маркам: живой Yandex сейчас отдаёт именно агрегатный signalsCountPerHour, поэтому он исключён из прогноза как потенциально содержащий дизельные сигналы. На текущих данных основной доступный признак общего подвоза — одновременный переход нескольких бензиновых статусов из OUT_OF_STOCK в IN_STOCK/LIMITED; одиночный переход слабее. Дизель, газ и неизвестные продукты не учитываются. Подтверждённые переходы union АИ-95 служат последним fallback. Сначала используй историю этой АЗС, затем бренда, затем зоны; всегда показывай интервал, тип сигнала, число эпизодов и уверенность. Не придумывай время в холодном старте и не скрывай нехватку данных.
  • Разовые проверки тоже накапливают эту историю. Мониторинг не обязателен, но частые tick’и дают существенно лучшую временную разрешающую способность; редкие ручные запуски могут полностью пропустить короткий переход rolling-count.
  • Presence-only очередь не сравнивается как короткая. Неизвестная очередь сортируется после известных.
  • Yandex, gdebenz и benzonavt относятся к одной provenance group по умолчанию и сами по себе не дают независимого многоисточникового повышения уверенности.
  • У Yandex station-level lastSignalTimestamp и signalsCountPerHour не относятся к конкретной марке и не должны давать ей свежесть или повышать уверенность. Grade-наблюдение использует только timestamp/count из самой строки марки; агрегатное время допустимо для очереди и контекста АЗС. Если живой payload не содержит grade-time, источник честно возвращает PARTIAL/NO_GRADE_FRESHNESS_METADATA, а не COMPLETENESS_INVARIANT и не свежий вердикт.
  • У Benzonavt fuels_now трактуется как исчерпывающий текущий список: непустой список без 95 — family-negative. Любой st.conflict до формализации его семантики переводит топливное наблюдение в UNCERTAIN и запрещает как рекомендацию, так и family-wide отрицание. queue.size=20_50/gt50 отображай как LONG/VERY_LONG, используя собственное queue.at.
  • Каталожный список топлива 2GIS не доказывает текущее наличие; учитывай только явный current-status с last_report_at. CAPTCHA означает CHALLENGE; не пытайся её решать.
  • Ассортимент АЗС (assortment, sellsRequestedFamily) отвечает на другой вопрос, чем наличие: «здесь вообще не продают 95» — это не дефицит. Такие станции считаются отдельной строкой «не продают АИ-95» и не получают прогноз подвоза. Ассортимент публикуют только 2GIS, Benzonavt и часть строк gdebenz; отсутствие каталога означает «неизвестно», а не «не продают», поэтому sellsRequestedFamily: undefined ничего не меняет в вердикте.
  • лимит: N л в строке станции — минимальный известный лимит на АИ-95. Протухает только наблюдение лимита (observedAt, например last_at у gdebenz): давно виденный лимит мог исчезнуть, и пускать его в минимум нельзя. Лимит, про который источник говорит «действует с» (inForceSince у Benzonavt) или который публикуется без даты (2GIS), остаётся в силе независимо от возраста этой даты — отбросить его значило бы занизить ограничение поездки. У наблюдённого и уже не свежего лимита рядом печатается возраст: лимит: 20 л (3 ч назад). Это ограничение поездки, а не признак наличия.
  • trust у observation (confidence, confirmations, reports, basis, reports_count, author_*) — заявленная источником собственная уверенность. Это provenance для диагностики; никогда не выдавай её за уверенность Fuel Watch и не показывай пользователю как вероятность.
  • Расхождение видимой карточки и скрытого поля источника — структурный конфликт, а не повод выбрать «удобное» поле. У gdebenz марка, названная только в fuels_now или только в тексте карточки, даёт UNCERTAIN с сохранением обеих формулировок в conflict, и такой позитив не попадает в «Куда ехать». Другой источник с собственным прямым позитивом по этой АЗС при этом остаётся в силе.
  • renderReport возвращает отдельное поле diagnostics (agentOnly: true) с полным списком warnings, source health, runtime, identity-диагностикой и осиротевшими процессами. Это внутренние данные: не цитируй их пользователю и не выдавай за ограничение поездки. Ограничения, влияющие на поездку, уже напечатаны в каноническом Markdown человеческим языком.
  • История связывает физическую АЗС по сохранённым member IDs, а не только по изменчивому merged stationKey, и сериализует параллельные read–modify–write через bounded lock. HISTORY_LOCK_TIMEOUT означает недоступный прогноз, но не отменяет текущий отчёт.

Разовая произвольная география

collect.mjs --area <файл> --output <файл> собирает одну зону для одного запуска. Настроенный многоугольник, ~/.fuel-watch/state/latest.json и общая история при этом не трогаются, поэтому --output обязателен. Файл содержит объект зоны (или {"area": {...}}) любого поддерживаемого вида, включая route-corridor с явными waypoints и corridorWidthMeters, и проверяется по той же схеме, что и настроенная зона, поэтому ошибка приходит с именем поля. Зона может объявить собственные потолки maxAreaSquareKm и maxStationCount: превышение площади останавливает запуск до опроса источников, превышение числа станций — сразу после сведения идентичностей. Это не новый default: постоянная зона меняется только через resolve-area.mjs.

Пример

Запрос: «Где сейчас есть 95-й, и где очередь меньше?»

Ожидаемый результат: один отчёт с timestamp и зоной, здоровьем Yandex/gdebenz/2GIS/Benzonavt, изменениями при наличии предыдущего tick, ранжированными только положительными АЗС, единственной агрегированной строкой АИ-95 со свежестью и уверенностью для каждой станции, отдельными счётчиками отрицательных/неизвестных данных, прогнозом до трёх ближайших появлений и обязательным предупреждением.

Ошибки

  • CHALLENGE, HTTP_ERROR, TIMEOUT, RESOURCE_BLOCKED, SCHEMA_CHANGED, NAVIGATION_FAILED, PAGE_LOST: назови источник и продолжи с остальными. Отчёт уже печатает строку «Недоступные источники: …» с человеческой причиной и перечисляет, по каким источникам построена оценка; публикуй её как есть.
  • Все источники деградировали: сообщи «нет доступных свежих данных», не «бензина нет».
  • CHALLENGE также означает, что источник отправил браузер на внешнюю страницу входа или проверки, которая должна вернуть его обратно (например, 2GIS → id.sber.ru с redirect_uri на 2gis.ru; так 2GIS отвечает именно автоматизированному Chrome). Skill не входит в аккаунт, не повторяет такой заход и не читает чужую страницу; посадка на чужом домене без пути назад при open остаётся RESOURCE_BLOCKED, а поздний уход на другой origin — PAGE_LOST.
  • CHALLENGE и user-in-the-loop: skill никогда не решает и не обходит CAPTCHA. Если в конфиге включён browser.challengeHandover (по умолчанию выключен и работает только в headed-режиме), collect удерживает уже открытое окно ограниченное время, чтобы человек решил проверку сам, только перечитывает страницу и повторяет источник один раз. Ни кликов, ни ввода, ни отправки форм со стороны skill не происходит. Исход записан в runtime.challengeHandovers: CLEARED — страница проверки исчезла (кто именно её убрал, мы не наблюдаем, и утверждать этого нельзя), TIMED_OUT — не исчезла за отведённое время, NOT_OBSERVABLE — адаптер распознал проверку по данным страницы, а видимого маркера нет, поэтому окно не удерживалось, UNREADABLE — страница не читалась уже при первой пробе, поэтому окно не удерживалось, LOST_WHILE_HELD — окно удерживалось, но страница перестала читаться во время ожидания. Лимит maxPerRun расходуют все исходы, при которых окно действительно удерживалось: CLEARED, TIMED_OUT и LOST_WHILE_HELD.
  • HTTP_429_LIMITED у Yandex: источник отдал страницу автолимита limited. Collect уже делает одну повторную попытку с той же личностью браузера без токена Headless; если код всё равно дошёл до отчёта, это настоящий лимит, а не отсутствие бензина. Не обходи его новыми попытками и не подменяй stealth-флагами.
  • Осиротевшие браузеры: чистый close удаляет pid-файл namespace, поэтому живой agent-browser процесс, всё ещё записанный под созданным этим прогоном namespace, — сирота. Такие процессы попадают в runtime.orphanProcesses и по умолчанию завершаются (SIGTERM, затем SIGKILL) в пределах того же бюджета очистки; browser.reapOrphanProcesses: false оставляет только запись. Сигнал отправляется только если совпали три условия: pid записан под созданным этим прогоном namespace, это тот же pid, который мы видели обслуживающим namespace во время прогона, и исполняемый файл процесса действительно называется agent-browser*. Общего сканирования процессов нет: оно задело бы браузеры других сессий на той же машине.
  • CLEANUP_FAILED / код 75: данные можно показать, но предупреждение обязательно; выполни одну повторную namespace-scoped проверку очистки до ожидания или новой коллекции.
  • COLLECTION_BUSY / код 2: другой сбор идёт дольше 10 минут; назови это и не запускай сбор повторно в цикле.
  • Невалидная конфигурация / код 2 до старта браузера: покажи точный JSON path из ошибки и ничего не собирай.
  • HISTORY_UNAVAILABLE: текущие данные можно показать, но прогноз недоступен; назови ошибку записи/чтения и не подменяй её выдуманным временем.
  • Временный state не удалился: сообщи абсолютный каталог и не утверждай, что monitoring полностью остановлен.

Проверка разработки

Только в рабочей копии репозитория при разработке, никогда в установленном каталоге skill: после изменения кода выполни npm test. Live smoke tests отделены и запускаются только по явному запросу: npm run test:live. Они никогда не входят в monitoring loop.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/shkarupa-alex/benz/fuel-watch">View fuel-watch on skillZs</a>