НЕ предполагается:

• Что оператор разбирается в HWID, base64, Reality, форматах подписки. Всё это — внутреннее, в логи (>&2), НЕ в речь пользователю.
• Что подписка уже заведена в какую-то панель. Это извлечение, не настройка.
• Что у оператора есть свободный слот устройства — это проверяется и при нужде он освобождает слот сам в приложении провайдера.</context>

Параметры

Все технические параметры — внутренние. Перед оператором их НЕ раскрываю. От него прошу только то, что он физически может знать/сделать: дать ссылку, посмотреть число устройств в приложении, удалить одно лишнее.

Процедура

Шаг 0: Чтение конфига (OPTIONAL)

Скилл работает и без полного vpn-блока — конфиг нужен в основном для INFRA (куда сохранить сервера). Поэтому режим OPTIONAL, не STRICT.

source "$SYSADMIN_ROOT/.claude/skills/_lib/find-config.sh"
find_sysadmin_config optional         # WARN + defaults если нет; $CONFIG = infra-config.json
find_brain_config || true             # $BRAIN_CONFIG = agent-config.json (язык)

# language — агент-поле (ADR-0013): живёт в мозге ($BRAIN_CONFIG).
# Legacy-совместимость: если мозга нет — top-level .language из $CONFIG.
REPORT_LANGUAGE=""
[ -n "${BRAIN_CONFIG:-}" ] && REPORT_LANGUAGE="$(jq -r '.operator.language // empty' "$BRAIN_CONFIG" 2>/dev/null)"
[ -z "$REPORT_LANGUAGE" ] && [ -n "${CONFIG:-}" ] && [ -f "${CONFIG:-}" ] && REPORT_LANGUAGE="$(jq -r '.language // empty' "$CONFIG" 2>/dev/null)"
[ -z "$REPORT_LANGUAGE" ] && REPORT_LANGUAGE="ru"

# Папка инфры активного проекта (ADR-0013): её знает реестр projects[] в мозге —
# resolve_active_project (внутри find_sysadmin_config) уже выставил $ACTIVE_INFRA_ROOT.
INFRA_DIR="${ACTIVE_INFRA_ROOT:-}"
# Legacy-совместимость: если мозга нет, но найден старый единый конфиг —
# берём infrastructure.root_path и резолвим относительно каталога конфига.
if [ -z "$INFRA_DIR" ] && [ "$SYSADMIN_CONFIG_FOUND" = "true" ]; then
    RAW_ROOT="$(get_config_field infrastructure.root_path "")"
    [ -n "$RAW_ROOT" ] && INFRA_DIR="$(resolve_infra_path "$RAW_ROOT" "$CONFIG" || true)"
fi

# Подсказка имени провайдера, если оператор его задавал в vpn-блоке (инфра-поле → $CONFIG).
if [ "$SYSADMIN_CONFIG_FOUND" = "true" ]; then
    PROVIDER_SLUG="${PROVIDER_SLUG:-$(get_config_field vpn.provider_slug subscription)}"
fi

Если INFRA_DIR пуст — не падаю: на Шаге 5 сохраню рядом и честно предупрежу.

Шаг 1: «Дай мне ссылку на подписку» (Green Zone)

Объясняю простым языком, БЕЗ терминов:

«Чтобы достать твои сервера, мне нужна ссылка на подписку. Это длинная ссылка, которую тебе выдал провайдер. Где её взять:

• открой личный кабинет провайдера (на сайте) или его бота в Telegram;
• найди кнопку вроде «Скопировать ссылку подписки», «Импорт», «Экспорт конфигурации» или «Subscription URL»;
• скопируй и вставь сюда.

Не путай с логином-паролем — мне нужна именно длинная ссылка, обычно начинается с https://.»

Получив ссылку — сохраняю в SUBSCRIPTION_URL. Если оператор не знает имя провайдера — спрошу мягко («как называется сервис? одним словом») для имени файла; не знает — оставлю subscription.

Шаг 2: Разведка — что это за подписка (Green Zone, READ-ONLY)

Прежде чем что-то тащить, смотрю состояние. Это безопасно — только чтение заголовков, ничего не меняет.

SUBSCRIPTION_URL="$SUBSCRIPTION_URL" ./scripts/inspect-subscription.sh > /tmp/verdict.json
KIND="$(jq -r '.kind' /tmp/verdict.json)"
ALIVE="$(jq -r '.alive' /tmp/verdict.json)"
HWID_STATE="$(jq -r '.hwid_state' /tmp/verdict.json)"
TITLE="$(jq -r '.profile_title // ""' /tmp/verdict.json)"
EXPIRE="$(jq -r '.expire_date // ""' /tmp/verdict.json)"
USED="$(jq -r '.traffic_used_gb // ""' /tmp/verdict.json)"
ANNOUNCE="$(jq -r '.announce // ""' /tmp/verdict.json)"

Перевожу вердикт в человеческую речь. Примеры:

• alive=true, kind=plain:

  «Вижу, подписка живая$([ -n "$EXPIRE" ] && echo ", оплачена до $EXPIRE")$([ -n "$USED" ] && echo ", потрачено $USED ГБ"). Сервера должны отдаться без фокусов — забираю список.»

• alive=true, kind=hwid_locked:

  «Подписка живая$([ -n "$EXPIRE" ] && echo " (до $EXPIRE)"). Но провайдер прячет сервера — отдаёт их только твоему устройству, как будто проверяет «свой/чужой». Сейчас аккуратно представлюсь твоим приложением и заберу список — это легально, подписка-то твоя.»

• alive=false:

  «Похоже, срок подписки истёк ($EXPIRE) — провайдер серверов не отдаст. Продли подписку и вернёмся.» (STOP — нечего извлекать.)

Если в announce была инструкция/ссылка на бот — запоминаю (пригодится на Шаге 3, если нужно освобождать слот). Оператору про x-hwid-*, base64, Remnawave — НЕ говорю.

Шаг 3: Если сервера спрятаны — представляюсь устройством (Yellow Zone)

Только при kind=hwid_locked. Логика — в references/hwid-mechanism.md.

3.1 — Сначала пробую без хлопот для оператора. Добываю «отпечаток» из уже установленного приложения Happ (если оно есть на маке) — тогда слот НЕ тратится:

HWID="$(MODE="${HWID_MODE:-auto}" PROVIDER_SLUG="$PROVIDER_SLUG" \
        INFRA_DIR="$INFRA_DIR" ./scripts/resolve-hwid.sh)"

Оператору говорю мягко, по-человечески (без слова HWID):

«Возьму отпечаток твоего устройства из приложения — этого хватит, чтобы провайдер меня узнал. Ничего делать не нужно, секунду.»

3.2 — Если приходит «лимит устройств» (hwid_state=max_devices_reached). Это значит — все «места под устройства» в подписке заняты. Объясняю просто и прошу действие, которое человек сделает сам:

«У тебя в подписке заняты все места под устройства — поэтому новое (моё) не влезает. Сделай, пожалуйста, так:

1. открой приложение провайдера (или его бота в Telegram$([ -n "$ANNOUNCE" ] && echo " — вот он: $ANNOUNCE"));
2. найди раздел «Мои устройства» / «Управление устройствами»;
3. удали одно, которым не пользуешься (например, старый телефон).

Как сделаешь — скажи мне, и я продолжу.»

Это действие НЕ автоматизируется (нет такой кнопки у провайдера через ссылку — только руками в приложении). Жду ответа оператора, потом повторяю Шаг 3.1.

3.3 — Если приходит «приложение не поддерживается» (hwid_state=not_supported). Это лечится автоматически правильным «представлением» — parse-subscription.sh сам пришлёт нужные заголовки. Оператору ничего делать не надо, иду дальше.

Шаг 4: Извлечение списка серверов (Yellow Zone)

parse-subscription.sh сам качает тело, понимает формат (список ссылок / base64 / Xray-JSON массив профилей / sing-box) и нормализует. Оператор про форматы НЕ слышит.

SUBSCRIPTION_URL="$SUBSCRIPTION_URL" HWID="$HWID" \
    ./scripts/parse-subscription.sh > /tmp/servers.json
RC=$?

Трактовка кода:

• 0 — успех. Считаю и говорю по-человечески:

  N="$(jq 'length' /tmp/servers.json)"
  # сводка по странам:
  jq -r 'group_by(.country)[] | "  \(.[0].country): \(length)"' /tmp/servers.json

  «Готово, нашёл $N серверов — вот в каких странах: …»

• 3 — всё ещё заглушка. НЕ сдаюсь молча. Значит: либо слот не освободили, либо отпечаток не подошёл. Возвращаюсь к Шагу 3 (сеньор-обёртка):

  «Провайдер пока не отдаёт список — скорее всего, свободного места под устройство всё ещё нет. Проверь, что удалил одно устройство (Шаг выше), и скажи мне — попробую снова.» Сервера не выдумываю (правило №1 CLAUDE.md).

• 1 — ни ссылок, ни JSON. Смотрю первые байты ответа (в логе скрипта), решаю: возможно Clash YAML (редко) → предложить оператору взять прямой vless-link из приложения. Без фантазий.

🟡 Почему это Yellow, а не Green. Скилл делает реальные сетевые запросы к провайдеру под видом фирменного приложения и (по пути B) может занять один слот устройства. Это обратимо (слот освобождается в приложении), не деструктивно, но оператор должен понимать, что происходит — отсюда брифинг на Шагах 2–3.

Шаг 5: Экспорт «под ключ» — файл + сохранение в infra (Yellow Zone)

NORMALIZED_JSON=/tmp/servers.json \
PROVIDER_SLUG="$PROVIDER_SLUG" \
INFRA_DIR="$INFRA_DIR" \
${TXT_PATH:+TXT_PATH="$TXT_PATH"} \
./scripts/export-servers.sh > /tmp/txt-path.txt
TXT_FILE="$(cat /tmp/txt-path.txt)"

export-servers.sh делает:

• читаемый .txt: шапка (сколько серверов, когда), сводка по странам, по каждой стране — сервера с адресом/транспортом и готовой vless://-ссылкой;
• предупреждение про секретность внутри файла;
• JSON в $INFRA/inventory/shared/vpn-subscriptions/<provider>.json.

Если INFRA_DIR пуст — скрипт сам положит рядом (./) и выведет WARN. Тогда честно скажу оператору, что файл лежит в текущей папке, и предложу запустить /sysadmin-init, чтобы появилось постоянное место.

Шаг 6: Финальный отчёт «под ключ»

✓ Подписка: <title или provider>, живая, до <expire>, потрачено <N> ГБ
✓ Извлечено серверов: <N>
✓ По странам: 🇺🇸 США — X, 🇳🇱 Нидерланды — Y, …
✓ Файл со списком и ссылками: <TXT_FILE>
✓ Сохранено в твоей папке: <INFRA>/inventory/shared/vpn-subscriptions/<provider>.json

Дальше говорю простым языком:

«Вот что получилось: у тебя $N серверов в таких странах: … Я сложил их в файл — там по каждому серверу есть готовая ссылка, которую можно вставить в любое VPN-приложение.

Важно: эти ссылки — как ключи от квартиры. В каждой зашит твой личный код доступа. Не выкладывай их в открытые чаты и не пересылай посторонним.

Что можно сделать дальше (по желанию):

• завести эти сервера в свою VPN-панель, чтобы раздавать VPN семье и выбирать страну выхода — это команда /configure-vpn-routing;
• сделать QR-код и конфиг для телефона/ноутбука из своей панели — /generate-client-config;
• держать список свежим каждый день без меня — провайдеры меняют ключи и адреса, и сегодняшний файл через месяц может не работать. Для этого сервер сам раз в сутки забирает подписку и пересобирает твою: /setup-happ-subscription.

Если просто хотел получить список — всё, готово, он в файле.»

Файл, который я сохранил, — снимок на сегодня, а не живая копия. Этот скилл ничего по расписанию не запускает: разовое извлечение и ежедневная синхронизация — разные работы. Синхронизацию ставят на сервере, по образцу существующих синков оператора (см. /setup-happ-subscription). Если оператор просит «обновлять каждый день» — называю этот путь, а не обещаю, что файл обновится сам.

Если в подписке есть серверы Hysteria2 — они в .txt и в other_servers JSON, но не в servers: /configure-vpn-routing строит выходы только из VLESS. Говорю оператору, сколько их и что панелью они сами не подхватятся.

Что помню до чтения справки

Четыре правила обязаны срабатывать сразу — открывать справочник, чтобы их вспомнить, поздно:

• max_devices_reached ≠ тупик. Прошлый прогон встал на «обойти нельзя, только через бота» — это неверно. Сначала путь A (HWID из установленного Happ, слот не тратится), и только если слот реально надо освободить — просьба к оператору. Диагнозы max_devices_reached и not_supported не путать: второй лечится сам, заголовками.
• Ссылки содержат секреты (рабочий UUID). Место им — в приватной infra (она в .gitignore). НЕ на рабочий стол, НЕ в git публичного репозитория, НЕ в открытый чат.
• Заглушку не заменяю выдумкой. Не пришли сервера — говорю «не пришли» и возвращаюсь к Шагу 3. Правдоподобного списка не сочиняю никогда (C.2).
• Балансир — не моя задача. Завести извлечённые сервера в один балансир скопом умеет /configure-vpn-routing, и там есть защита от «скачущего по странам IP». Здесь только извлечение и сохранение.

Всё остальное — форматы ответа, устройство HWID-замка, гео-блокировка, разбор граблей — в справочниках ниже. Туда иду, когда шаг повёл себя не так, как написано.

Bundled resources

Следующие шаги для оператора: /configure-vpn-routing — завести сервера в свою панель; /generate-client-config — QR и конфиги для устройств.