docs(xray-proxy): добавлена спецификация консольного клиента

- Зачем: - нужен зафиксированный контракт переносимого Xray-клиента для удалённых Linux-систем. - Что: - описаны Python CLI, отдельный Bash-модуль и совместимость с внешним Hiddify. - закреплены преобразование VLESS-ссылок, версии Xray и обработка TLS. - определены жизненный цикл в tmux, безопасность файлов и проверки реализации. - Проверка: - выполнена проверка `git diff --cached --check`.
2026-07-16 00:06:10 +03:00
1 parent 3b7ebd29c8
commit 716fb7f5dd
@@ -0,0 +1,455 @@
 # Headless Xray-прокси для агентских CLI
 Дата: 2026-07-15
 Статус: дизайн утверждён, реализация не начата
 ## Проблема
 На удалённых Linux-серверах нет GUI-клиента Hiddify. Перед запуском Claude Code
 или Codex приходится вручную запускать Xray и выставлять proxy-переменные.
 Переменные легко забыть, после чего агент стартует без прокси.
 Нужны привычные команды `pclaude` и `pcodex`, которые не запускают агента,
 если явно настроенный прокси недоступен. Решение должно работать как часть этого
 репозитория и отдельно от остальных dotfiles.
 ## Контекст
 Существующий дизайн
 [`pclaude` / `pcodex`](../superpowers/specs/2026-05-19-proxy-cli-launchers-design.md)
 задаёт важный контракт: proxy-переменные видны только дочернему процессу,
 аргументы и код возврата сохраняются, а недоступный прокси приводит к отказу
 до запуска агента.
 Эта спецификация заменяет Linux-часть прежнего дизайна в вопросах расположения
 функций, источника настроек и вывода `proxy_on`/`proxy_off`. Windows-часть
 прежнего дизайна не меняется.
 Сейчас Bash-функции жёстко используют внешний Hiddify на
 `hproxy.local:12334`. Принесённый прототип `scripts/setup-xray-proxy.sh`
 умеет установить и запустить Xray из готового JSON, но смешивает установку и
 запуск, не разбирает ссылки Hiddify и небезопасно ищет чужие процессы через
 `pkill`.
 Xray принимает конфигурационные файлы, а не `vless://`-ссылки. При этом его
 SOCKS-вход принимает SOCKS и HTTP на одном порту, поэтому существующая схема
 proxy-переменных совместима с локальным Xray без второго порта. См.
 [командную строку Xray](https://xtls.github.io/en/document/command.html) и
 [SOCKS-вход](https://xtls.github.io/en/config/inbounds/socks.html).
 ## Цели
 - Дать headless Linux-серверу управляемый пользовательский Xray без systemd и
  прав root.
 - Сохранить явные `pclaude` и `pcodex`, которые нельзя случайно запустить через
  другой прокси или без настроенного прокси.
 - Принимать одну точечную VLESS-ссылку Hiddify и преобразовывать её в клиентский
  JSON Xray.
 - Сохранить совместимость Bash-функций с внешним Hiddify.
 - Позволить настраивать машинный `NO_PROXY` без правки файлов репозитория.
 - Поддержать выборочную установку после `git clone`: через stow, ручные
  симлинки или копирование.
 ## Не входит в объём
 - Windows, PowerShell, Windows Codex launcher и VS Code Server.
 - systemd, автозапуск после перезагрузки, sudo, firewall, TUN и изменение
  системной маршрутизации.
 - Автоматический выбор между Xray и Hiddify или переход на запасной прокси.
 - Одновременное управление несколькими профилями одного Unix-пользователя.
 - Универсальный импорт подписок или полного JSON-экспорта Hiddify.
 - Протоколы и сочетания за пределами двух явно поддержанных семейств.
 - pip, venv и любые сторонние Python-библиотеки.
 - Сетевая изоляция голых `claude` и `codex`: как и раньше, гарантию намерения
  дают явные команды с префиксом `p`.
 ## Рассмотренные варианты
 ### Только Bash
 Ближе всего к принесённому прототипу, но URL-кодирование, JSON, проверка схемы,
 контрольные суммы и безопасное управление процессом делают Bash-реализацию
 хрупкой и плохо тестируемой.
 ### Bash-контроллер и отдельный Python-преобразователь
 Оставляет жизненный цикл в Bash, а разбор VLESS переносит в Python. Граница
 между двумя реализациями усложняет ошибки, тесты и единый источник настроек.
 ### Один Python CLI и тонкий Bash-модуль
 Python отвечает за данные, установку Xray, процессы и запуск дочерних команд.
 Bash нужен только там, где необходимо изменить окружение текущей shell-сессии.
 Это выбранный вариант.
 ### Не создавать менеджер
 Можно хранить готовые JSON и вручную запускать Xray в tmux. Вариант почти не
 требует кода, но не решает основную боль: безопасный запуск `pclaude` и
 `pcodex` из точечной ссылки Hiddify.
 ## Рекомендуемое решение
 ### Границы компонентов
 `xray-proxy` — один исполняемый файл на Python 3.8+ без внешних библиотек. Он
 отвечает за установку Xray, запуск и остановку процесса, диагностику,
 преобразование VLESS и запуск произвольной дочерней команды через прокси.
 Переносимый `shell.bash` — единственный владелец `proxy_on`, `proxy_off`,
 `pclaude`, `pcodex`, `myip` и внутренних proxy-помощников. При реализации они
 удаляются из `bash/.bash_functions`, чтобы результат не зависел от порядка
 `source`. `update_hproxy` остаётся там как отдельная WSL-утилита управления
 `/etc/hosts`, а не часть переносимого интерфейса прокси. Модуль не разбирает
 машинный конфиг самостоятельно:
 - `pclaude` и `pcodex` делегируют запуск форме
  `xray-proxy run -- COMMAND ARG...`, где `--` отделяет параметры клиента;
 - `proxy_on` получает от `xray-proxy env` проверенный набор proxy-переменных и
  применяет его к текущей Bash-сессии;
 - `proxy_off` очищает верхний и нижний регистр proxy-переменных.
 Общий `bash/.bash_functions` и модуль Xray не зависят друг от друга. В составе
 dotfiles `.bash_custom` подключает их двумя независимыми строками. Без
 остальных dotfiles пользователь добавляет только один `source` модуля Xray в
 `.bashrc`. Для неинтерактивных сценариев и других оболочек остаётся прямой
 `xray-proxy run`.
 `xray-proxy env` сначала выполняет ту же проверку доступности, что и `run`, а
 затем печатает восемь строк `KEY=value`: HTTP, HTTPS, ALL и NO_PROXY в верхнем
 и нижнем регистре. Переносы строк и NUL в значениях запрещены. `shell.bash`
 сначала целиком получает успешный ответ, затем разбирает строки по первому `=`,
 проверяет точный белый список ключей и отсутствие повторов, и лишь после этого
 экспортирует значения через `printf -v`. `eval` не используется, частичного
 изменения окружения при ошибке нет.
 У `env` stdout зарезервирован только для восьми машинно-читаемых строк.
 Предупреждения и ошибки идут в stderr; обычная безопасная сводка этой командой
 не печатается.
 Совместимость существующих Bash-команд означает сохранение имён функций,
 набора переменных, fail-fast перед `pclaude`/`pcodex` и изоляции окружения
 дочернего процесса. Автоматический запрос внешнего IP из `proxy_on` и
 `proxy_off` удаляется: он замедляет переключение и смешивает изменение
 окружения с диагностикой. Для проверки остаются `myip` и `xray-proxy status`.
 ### Два независимых файла настройки
 Машинный файл `~/.config/proxy/config` хранит несекретное описание активного
 прокси: явный тип `xray` или `external`, отображаемое имя, адрес, порт и
 добавку к `NO_PROXY`. Формат — INI из стандартной библиотеки Python. Если файла
 нет, прокси-подсистема сохраняет прежний внешний адрес
 `hproxy.local:12334` ради обратной совместимости.
 Секретный `~/.config/xray-proxy/default.url` содержит одну VLESS-ссылку.
 Команда запуска принимает другой файл через `-f`. Профили можно хранить в
 нескольких файлах, но активным у пользователя бывает только один.
 CLI следует за симлинком, но проверяет права конечного файла: доступ группы или
 остальных пользователей считается ошибкой с подсказкой выполнить `chmod 600`.
 Файл должен содержать ровно одну непустую строку без комментариев и служебного
 текста.
 Базовый `NO_PROXY` всегда включает loopback-адреса и узел самого прокси.
 Машинная добавка расширяет его локальными IP и доменами. Документация должна
 предупреждать, что поддержка CIDR в `NO_PROXY` различается между программами.
 ### Явная семантика прокси
 Тип `xray` означает, что `pclaude` и `pcodex` требуют запущенный процесс,
 которым управляет `xray-proxy`. Если его нет, агент не запускается, а сообщение
 предлагает выполнить `xray-proxy start`.
 Тип `external` означает внешний процесс, например Hiddify. Проверяется только
 доступность явно заданного адреса и порта. Ни один тип не переходит на другой
 автоматически.
 `start` разрешён только при `type=xray`; при `type=external` он завершается с
 подсказкой изменить машинный конфиг. Для Xray адрес машинного конфига обязан
 быть loopback-адресом, а порт обязан совпадать с создаваемым входом. Так нельзя
 случайно поднять локальный Xray, оставив `pclaude` направленным во внешний
 Hiddify.
 `status` описывает именно активный тип из машинного конфига: состояние процесса
 и порта для Xray либо доступность адреса для external. `stop` от машинного типа
 не зависит и завершает записанный управляемый Xray, если он существует. Поэтому
 после явного переключения на external старый локальный процесс можно штатно
 остановить.
 HTTP, HTTPS и SOCKS используют один локальный порт, по умолчанию `12334`.
 Порт остаётся настраиваемым, чтобы разные Unix-пользователи одной машины могли
 запускать свои экземпляры без конфликта.
 Локальный вход Xray слушает только loopback: `127.0.0.1` и, если поддержано
 выбранной конфигурацией, `::1`. Он никогда не привязывается к `0.0.0.0`, адресу
 сетевого интерфейса или имени узла. Это закрывает вход от удалённой сети, но не
 изолирует его от других пользователей того же Linux-узла. Первая версия не
 добавляет локальную аутентификацию и предполагает доверенных пользователей
 машины.
 ### Поддерживаемые VLESS-ссылки
 Первая версия поддерживает две семьи:
 - VLESS с TCP/RAW и REALITY;
 - VLESS с XHTTP и TLS, включая HTTP/1.1, h2 и h3 через ALPN.
 Преобразователь сохраняет значимые параметры ссылки, проверяет обязательные
 поля и отклоняет неизвестное сочетание целиком. Он не должен молча пропускать
 неизвестные или несовместимые параметры. Поддержка REALITY опирается на
 [официальную схему REALITY](https://xtls.github.io/en/config/transports/reality.html),
 а XHTTP с TLS — на
 [схему TLS](https://xtls.github.io/en/config/transports/tls.html).
 Для REALITY преобразователь явно сопоставляет UUID с VLESS `id`, узел и порт с
 адресом назначения, `type=tcp` с RAW, `flow` с режимом VLESS Vision, `sni` с
 `serverName`, `fp` с `fingerprint`, `pbk` с `password`, а `sid` с `shortId`.
 `headerType=none` принимается как нейтральное значение, другое значение
 отклоняется. `hiddify`, `host` и `alpn` для TCP/REALITY считаются метаданными и
 не меняют Xray JSON; безопасная сводка явно помечает `host` и `alpn` как
 неиспользованные. Это не скрытая потеря параметра: в целевой
 [схеме REALITY Xray 26.3.27](https://github.com/XTLS/Xray-core/blob/v26.3.27/infra/conf/transport_internet.go#L3591-L3636)
 нет полей Host или ALPN. Повтор одного query-параметра считается ошибкой.
 Остальные правила соответствуют
 [стандарту VLESS-ссылок Xray](https://github.com/XTLS/Xray-core/discussions/716).
 Основной сценарий XHTTP/TLS — одиночная ссылка Hiddify с `type=xhttp`,
 `security=tls`, `sni`, `alpn`, `path`, `host`, `encryption`, `fp` и, возможно,
 `extra`. UUID, узел и порт преобразуются так же, как для REALITY. Остальные
 поля сопоставляются явно:
 - `type=xhttp` задаёт транспорт XHTTP;
 - `security=tls` включает TLS;
 - `sni`, `alpn` и `fp` задают `serverName`, список ALPN и fingerprint;
 - `path`, `host` и необязательный `mode` переходят в настройки XHTTP;
 - `encryption` задаёт шифрование VLESS и в первой версии должно быть `none`;
 - `extra` URL-декодируется, разбирается как JSON-объект без повторяющихся
  ключей и целиком передаётся в одноимённую секцию XHTTP;
 - `pcs` и `vcn` для Xray 26.3.27 переходят в `pinnedPeerCertSha256` и
  `verifyPeerCertByName`;
 - `hiddify=1` и `core=xray` принимаются как метаданные источника и не меняют
  JSON;
 - `headerType=none` принимается как устаревшее нейтральное поле Hiddify, другое
  значение отклоняется;
 - fragment после `#` используется только как отображаемое имя профиля.
 Если `mode` отсутствует, преобразователь не придумывает его и оставляет выбор
 Xray. Параметры query не зависят от порядка, но не могут повторяться. После
 перечисленных полей неизвестный параметр считается ошибкой: он может менять
 смысл соединения и требует явного добавления в преобразователь. `path`, `host`,
 `mode` и `extra` входят в официальный стандарт ссылок Xray; параметры TLS
 `pcs`/`vcn` заменяют удалённый `allowInsecure`:
 [стандарт VLESS-ссылок](https://github.com/XTLS/Xray-core/discussions/716).
 Перед запуском CLI печатает компактную безопасную сводку: сервер, порт,
 транспорт, защиту, SNI, ALPN, Host, путь, fingerprint и локальный порт. Обычный
 режим не выводит подробный журнал Xray: `-v` добавляет информационные сообщения,
 а `--debug` включает подробную диагностику. UUID, REALITY password/public key,
 short ID и другие чувствительные значения выводятся только сокращённо.
 В создаваемом JSON журнал доступа отключён, а уровень ошибок по умолчанию —
 `warning`.
 Hiddify Manager может добавлять `allowInsecure=true` и `insecure=true` даже к
 профилю с действительным публичным сертификатом — этот дефект описан в
 [hiddify/Hiddify-Manager#5438](https://github.com/hiddify/Hiddify-Manager/issues/5438).
 Современный Xray больше не поддерживает `allowInsecure`; удаление зафиксировано
 в [релизе 26.2.6](https://github.com/XTLS/Xray-core/releases/tag/v26.2.6).
 Поэтому преобразователь принимает эти поля, но для Xray 26.3.27 не переносит
 их в JSON и предупреждает, что сертификат будет проверен обычным способом.
 Соединение после этого может успешно заработать или завершиться ошибкой
 сертификата; отдельного раннего отказа нет.
 При явно выбранном Xray 25.12.8 преобразователь сохраняет
 `allowInsecure=true` и предупреждает одновременно об отключённой проверке
 сертификата и об использовании старой совместимой версии. Автоматический откат
 с 26.x на 25.12.8 запрещён. Новые `pcs`/`vcn` в режиме 25.12.8 отклоняются как
 несовместимые вместо попытки угадать их старое представление.
 ### Установка Xray
 `xray-proxy install` — отдельная явная операция. Она устанавливает Xray в
 `~/.local/bin`, скачивает официальный архив и файл контрольной суммы, затем
 проверяет SHA-256. Версия по умолчанию зафиксирована в коде клиента на текущем
 на момент реализации стабильном релизе 26.3.27. Пользователь может явно указать
 другую версию через `--version`; произвольная версия не становится заявленной
 как поддерживаемая только из-за успешной установки. Официальные релизы
 публикуют необходимые файлы `.dgst`:
 [релиз 26.3.27](https://github.com/XTLS/Xray-core/releases/tag/v26.3.27).
 Первая версия установщика поддерживает Linux x86_64 и aarch64. Архив
 распаковывается во временный пользовательский каталог, проверенный бинарник
 сначала запускается с `version`, а затем атомарно переносится в
 `~/.local/bin/xray`. Существующий файл другой версии не перезаписывается без
 явного `--replace`. После установки CLI проверяет, что `command -v xray`
 указывает именно на установленный файл; иначе завершается с подсказкой исправить
 `PATH`. `start` всегда показывает фактический путь и версию выбранного бинарника.
 Перед созданием JSON CLI читает фактическую версию из `xray version` и выбирает
 только совместимое с ней представление TLS-полей. Версия никогда не выводится
 из содержимого VLESS-ссылки.
 Xray 25.12.8 — документированный запасной вариант только для старых Hiddify-
 профилей, которым действительно требуется `allowInsecure=true`. Это последняя
 версия ветки 25.x, где поле применяется без календарного запрета:
 [релиз 25.12.8](https://github.com/XTLS/Xray-core/releases/tag/v25.12.8) и
 [реализация TLS 25.12.8](https://github.com/XTLS/Xray-core/blob/v25.12.8/infra/conf/transport_internet.go).
 `start` никогда не скачивает бинарник. Если `xray` отсутствует в `PATH`, команда
 завершается с подсказкой выполнить `xray-proxy install`.
 ### Жизненный цикл
 CLI предоставляет `install`, `start`, `stop`, `status`, `env` и `run`. Запуск
 без подкоманды не устанавливает и не стартует ничего.
 `start` остаётся на переднем плане как небольшой Python-супервизор и занимает
 текущую консоль. Он запускает один дочерний Xray без демонизации и без новой
 сессии процесса, ждёт его завершения и передаёт ему SIGINT, SIGTERM и SIGHUP.
 Ожидаемый способ работы — отдельная панель tmux или другого мультиплексора.
 Отсоединение от tmux не останавливает процесс, но закрытие панели или сессии
 останавливает Xray. Отдельный постоянный журнал и команда `logs` не нужны:
 достаточно истории tmux.
 Супервизор владеет блокировкой, дочерним процессом и служебным каталогом
 `~/.local/state/xray-proxy/`. Файл состояния содержит PID и время старта обоих
 процессов, путь к бинарнику, порт и безопасный отпечаток профиля, но не VLESS-
 ссылку и не её секреты. `status` и `stop` сверяют PID со временем старта и
 ожидаемым исполняемым файлом, поэтому повторное использование PID не считается
 управляемым процессом. `stop` посылает SIGTERM супервизору, а тот завершает Xray
 и очищает состояние. Если супервизор аварийно исчез, `stop` может завершить
 только дочерний Xray, идентичность которого подтверждена теми же данными.
 У пользователя может быть только один управляемый экземпляр. Повторный `start`
 не заменяет его другим профилем. Для смены профиля нужны явные `stop` и `start`.
 Перед успешным запуском должны пройти разбор ссылки, проверка поддерживаемого
 сочетания и `xray run -test`. После запуска процесс должен оставаться живым, а
 локальный порт — принимать соединения. Проверка внешнего IP через прокси носит
 диагностический характер: её сбой даёт предупреждение, но не останавливает уже
 прошедший обязательные проверки Xray.
 Сгенерированный JSON и временные файлы создаются внутри служебного каталога и
 удаляются супервизором после завершения Xray. Каталоги создаются с правами
 `0700`, файлы с конфигурацией и состоянием — `0600`. Исходная VLESS-ссылка не
 попадает в обычный вывод и никогда не передаётся аргументом командной строки.
 `run` никогда не запускает Xray. Для типа `xray` он проверяет PID управляемого
 процесса и локальный порт; для типа `external` — только явно настроенный адрес и
 порт. Лишь после успешной проверки он выставляет proxy-переменные для дочерней
 команды. Поэтому `pclaude` и `pcodex` не имеют скрытого автозапуска.
 ### Доставка
 Компоненты образуют отдельный stow-совместимый каталог `xray-proxy/`. Он
 доставляет CLI, Bash-модуль и два шаблона: машинного INI и файла VLESS-ссылки.
 Реальные пользовательские файлы не управляются stow и не входят в Git.
 CLI раскладывается как `~/.local/bin/xray-proxy`, а модуль — как
 `~/.config/xray-proxy/shell.bash`. Шаблоны лежат рядом с модулем в подкаталоге
 `examples/` и не подменяют настоящие пользовательские файлы.
 В корне этого каталога находится самостоятельный `README.md`. Он является
 основной инструкцией клиента и исключается из раскладки stow. README остаётся
 рядом с кодом при выборочном клонировании или копировании каталога. Корневой
 README репозитория только кратко описывает подсистему и ссылается на него.
 После клонирования репозитория пакет можно подключить отдельно от общего
 `install.sh`. README также должен описывать эквивалентные ручные симлинки и
 копирование файлов. Полный `install.sh` подключает этот же stow-пакет вместе с
 остальными dotfiles и не имеет отдельной реализации.
 ## Решения и отклонённые альтернативы
 - Выбран Python 3.8+, потому что стандартной библиотеки достаточно для URL,
  JSON, INI, ZIP, SHA-256, HTTP, процессов и тестов. Более новый синтаксис и
  сторонние пакеты запрещены ради старых и непредсказуемых серверных систем.
 - Выбран INI, а не TOML: модуль
  [`tomllib`](https://docs.python.org/3/library/tomllib.html) добавлен только в
  Python 3.11, что исключило бы штатный Python 3.10 в Ubuntu 22.04.
 - Bash оставлен отдельным тонким модулем, потому что дочерний Python-процесс не
  может изменить окружение родительской shell-сессии.
 - Машинный прокси и VLESS-ссылка разделены: первый файл описывает локальную
  политику shell, второй содержит секрет и меняется независимо.
 - Выбран один порт, потому что SOCKS-вход Xray совместим с HTTP и не требует
  второго локального слушателя.
 - Выбран явный тип прокси вместо автообнаружения. Предсказуемость канала важнее
  удобства автоматического перехода.
 - Выбрана одна активная конфигурация на пользователя. Именованные процессы и
  автоматическое распределение портов отложены до появления реальной нужды.
 - Официальный системный установщик отклонён: он требует root и создаёт
  systemd-службы. Пользовательская установка соответствует выбранной модели.
 - Готовые JSON и полный импорт Hiddify отклонены как основной интерфейс: точечная
  VLESS-ссылка проще для пользователя и ограничивает область преобразования.
 ## Риски и меры
 - Формат ссылок Hiddify может расширяться. Строгая проверка и явный отказ
  безопаснее частично неверного JSON.
 - Проверка открытого порта не доказывает работоспособность маршрута. CLI
  разделяет обязательную проверку процесса и необязательную внешнюю диагностику.
 - VLESS-ссылка содержит чувствительные данные. CLI сокращает секреты в выводе,
  не журналирует их и использует закрытые пользовательские файлы.
 - Устаревшие Hiddify-поля `allowInsecure` и `insecure` неоднозначны. Xray 26.x
  игнорирует их на уровне преобразователя и проверяет сертификат; Xray 25.12.8
  сохраняет их только после явного выбора версии. Оба пути сопровождаются
  предупреждением.
 - Старые дистрибутивы могут иметь Python ниже 3.8. CLI проверяет версию до
  основной работы и сообщает обнаруженную и требуемую версии.
 - `NO_PROXY` реализуется программами неодинаково. README рекомендует точные IP
  и домены, а CIDR описывает как совместимость best-effort.
 - Разные пользователи делят сетевое пространство имён. Настраиваемый порт и
  явная ошибка конфликта предотвращают случайный запуск на занятом порту, но
  loopback без аутентификации не запрещает намеренное подключение другого
  локального пользователя. Это принятое ограничение первой версии.
 ## Проверка реализации
 - Модульные тесты разбирают обезличенные ссылки обеих поддерживаемых семей и
  все показанные варианты ALPN. Отдельный регрессионный пример повторяет форму
  типичной ссылки Hiddify XHTTP/TLS с `hiddify`, `core`, `extra`,
  `headerType=none`, `allowInsecure` и `insecure`.
 - Неподдерживаемые транспорт, защита, отсутствующие обязательные поля и
  неизвестные критичные параметры дают понятный отказ до запуска Xray.
 - Сгенерированный JSON проходит `xray run -test` отдельно на Xray 26.3.27 и
  25.12.8 для заявленных совместимыми сочетаний. Интеграционная проверка каждой
  версии подтверждает, что один локальный вход принимает HTTP и SOCKS.
 - Тесты отдельно проверяют современное удаление устаревших insecure-полей и их
  сохранение для явно выбранного Xray 25.12.8.
 - Тесты подтверждают сокращение секретов и отсутствие полной VLESS-ссылки в
  stdout, stderr, служебных файлах и аргументах дочернего процесса.
 - Установка проверяется на корректной и повреждённой SHA-256 без записи вне
  пользовательского каталога.
 - Управление процессом покрывает повторный запуск, устаревший PID, чужой PID,
  повторно использованный PID, передачу сигналов, аварийно исчезнувший
  супервизор, очистку файлов, смену профиля, остановку и конфликт порта.
 - Сбой внешней проверки IP не отменяет успешный запуск, но отображается отдельно
  от состояния процесса и порта.
 - `run` сохраняет аргументы и код возврата, не оставляет proxy-переменные в
  родительской Bash-сессии и не запускает команду при недоступном прокси.
 - `env` не печатает частичный результат при ошибке, а `shell.bash` отклоняет
  неизвестные и повторные ключи без `eval` и без частичного экспорта.
 - Регрессионные Bash-тесты подтверждают прежнее поведение Hiddify при отсутствии
  машинного конфига, оба регистра proxy-переменных, настраиваемый `NO_PROXY` и
  отсутствие автоматического запроса внешнего IP в `proxy_on`/`proxy_off`.
 - Ручная проверка выполняется минимум на Ubuntu с Python 3.10 и на одной целевой
  удалённой системе; отдельным пунктом проверяется доступная версия Python в
  РЕД ОС перед заявлением её поддержки.
 ## Влияние на документацию
 Основная инструкция создаётся как `xray-proxy/README.md` одновременно с
 реализацией. Она должна описывать:
 - различие внешнего Hiddify и управляемого Xray;
 - выборочная установка через stow, ручные симлинки и копирование;
 - создание машинного INI из шаблона и отдельного файла VLESS-ссылки;
 - команды управления, `proxy_on/off`, `pclaude/pcodex`;
 - настройка `NO_PROXY`, ограничения CIDR и диагностика;
 - поддерживаемые семейства VLESS, современную проверку сертификата и явный
  запасной вариант Xray 25.12.8 для `allowInsecure`;
 - отсутствие systemd, автозапуска и автоматического перехода между прокси.
 Корневой README получает только короткий обзор, пример подключения пакета и
 ссылку на полную инструкцию клиента.
 Шаблоны должны содержать только вымышленные значения. Настоящие VLESS-ссылки,
 UUID и ключи никогда не входят в репозиторий.