# Audion DevOps Tools — руководство

[English](USER_GUIDE_EN.md) · [О программе](README_RU.md) · [Справочник команд](COMMANDS_RU.md)

**Содержание**

- [Быстрый старт](#быстрый-старт)
- [Главное правило](#главное-правило)
- [Риски и подтверждения](#риски-и-подтверждения)
- [Как читать окно](#как-читать-окно)
- [Где рабочие данные](#где-рабочие-данные)
- [Разделы](#разделы)
- [Терминал](#терминал)
- [Проверка](#проверка)
- [Техническая часть](#техническая-часть)

Как работать: запуск, главное правило, разметка риска, разделы и что читать по
каждому из них.

## Быстрый старт

```cmd
Start.exe
```

`Start.exe` один раз спрашивает права администратора — большинству операций они
нужны: развёртывание, возможности подсистемы Linux, файл `hosts`, сетевые
адаптеры, политики умолчаний и драйверов, среда восстановления, работа с дисками.
Ответ «нет» открывает окно без прав: это видно по значку прав, щелчок по нему
перезапускает окно с правами.

Без вопроса о правах:

```cmd
set AUDION_GUI_NO_ELEVATE=1
Start.exe
```

## Главное правило

**Все операции идут средствами проекта:**

* через окно;
* через консольную команду `devops_cli.cmd run --operation <операция>` — ту же, что за кнопками окна;
* через `launcher_*.cmd`;
* через `runtime\python.exe system_core\cli_operation.py <операция>`.

Это особенно важно для подсистемы Linux и системных операций. Проверяя проектный
слой, не обходите его ручными командами — иначе проверяется не проект, а удача в
текущей консоли.

Опасная операция прямо из командной строки требует явного признака:

```cmd
runtime\python.exe system_core\cli_operation.py <операция> --yes-i-understand
```

## Риски и подтверждения

Каждая операция в описании помечена родом:

| род | что значит |
|---|---|
| `safe` | чтение, диагностика или запись только в проектную область |
| `dangerous` | меняет пользователя, систему, сеть, диски, политики или секреты |

И уточняющим уровнем:

| уровень | что меняется |
|---|---|
| `project_write` | пишет в проект |
| `user_write` | меняет текущего пользователя |
| `system_change` | меняет политику Windows |
| `destructive` | может удалять данные или разделы |
| `secret_export` | выгружает секреты, например ключи SSH |

Опасное требует отдельного подтверждения. Часть внешних мастеров дополнительно
просит набрать слово вручную. Встроенные операции без вопросов должны иметь явные
проектные признаки, а не скрытые запросы «да/нет».

## Как читать окно

Шесть разделов — большие кнопки под шапкой: СЕТЬ, WSL И VM, ДРАЙВЕРЫ, АССОЦИАЦИИ,
ЭКСПОРТ И ИМПОРТ, СИСТЕМА. Под разделом — строка о том, что в нём, и ряд его
страниц. Страница — карточки операций; карточки одного дела стоят в общей рамке.

Подписи окна русские или английские — переключатель RU/EN в шапке. Видимая подпись
короткая: её задача — помочь решиться за пару секунд. Подсказка у кнопки
раскрывает, что именно изменится, термины Windows, риск и порядок отката;
подтверждение опасного показывает полный текст. Имя операции видно в журнале — по
нему её же запускает консольная команда.

### Что означают рамки и цвета

Раскраска здесь не украшение, а приборная маркировка.

**Рамка вокруг карточек** означает пару или жизненный цикл: резерв и
восстановление, выгрузка и загрузка, запрет и снятие, слепок и применение.
Обратный ход всегда на виду.

| вид кнопки | смысл |
|---|---|
| залитая | главное действие своей рамки |
| оранжевая | удаляет или стирает |
| подсвеченный переключатель | состояние, в котором машина сейчас |
| обычная | выбор варианта: сама ничего не запускает |

Цвет не заменяет род операции, подтверждение и журнал — он помогает быстро
понять характер соседних кнопок внутри одной рамки.

### Устойчивые пары слов

| слово | значение |
|---|---|
| резерв | слепок состояния внутри проекта |
| выгрузка | вынести состояние наружу, в файл или папку |
| загрузка | занести файл обратно в систему или профиль |
| восстановление | применить сохранённое состояние обратно |
| запрет / снятие | поставить или снять ограничение |
| включить / выключить | режим или компонент |
| слепок / применение | сохранить слой и применить его обратно |
| очистка | уборка в выбранной области; сначала ищите проверку без удаления |

## Где рабочие данные

```
App\          окно и PowerShell программы
config\       описание команд, раскладка окна, история терминала, настройки окна
system_core\  службы, модули PowerShell, файлы подсистемы Linux
tools\        средства проекта и обёртки
profiles\     управляемые профили, например эталон ассоциаций
backup\       резервы системных и пользовательских состояний
output\       отчёты и выгруженное
logs\         журналы операций
report\       журналы с правами и диагностика
workspace\    рабочие папки инструментов
```

`backup\` — ключевая папка наравне с входной и выходной: она заводится при
подготовке, открывается отдельной кнопкой и содержит то, чем откатываются
изменения. Это не кэш и не временные файлы: слепки сети, ветки реестра, выгрузки
хранилища драйверов, закладки браузера до и после, сертификаты, материал SSH,
состояние виртуализации и файла `hosts`.

## Разделы

Каждая подсистема разобрана отдельным документом в `tools\` — там порядок
действий, особенности Windows и грабли.

| раздел окна | страницы | подробно |
|---|---|---|
| СЕТЬ | ПОДКЛЮЧЕНИЕ, WI-FI, DNS, РЕМОНТ, HOSTS | `tools\NETWORK_CONNECTIVITY_RU.md`, `tools\DNS_DOCTOR_RU.md`, `tools\BITRIX_HOSTS_RU.md` |
| WSL И VM | WSL, НАСТРОЙКА, ДИСТРИБУТИВ, UBUNTU, HYPER-V | `tools\WSL_TOOLKIT_RU.md`, `tools\VIRTUALIZATION_SWITCHER_RU.md` |
| ДРАЙВЕРЫ | WINDOWS UPDATE, ЗАМОК HWID, NVIDIA, DRIVER STORE, АУДИТ | `tools\HARDWARE_DRIVER_GUARD_RU.md` |
| АССОЦИАЦИИ | MICROSOFT, EDGE, ПОЛИТИКА, ОТСЛЕЖИВАНИЕ, СНИМОК, ГРУППЫ, ОТЧЁТ | `tools\ASSOCIATION_DEFENSE_RU.md`, `tools\DEFAULT_APPS_GUARD_RU.md` |
| ЭКСПОРТ И ИМПОРТ | КОМПЛЕКТ, SSH, СЕРТИФИКАТЫ, ДОСТУПЫ, ШРИФТЫ И ОБОЛОЧКА, ЗАКЛАДКИ, AI CLI | `tools\MIGRATION_RU.md`, `tools\OPENSSH_KEYKIT_RU.md`, `tools\CERTIFICATE_KEYKIT_RU.md`, `tools\BROWSER_BOOKMARKS_MASTER_RU.md` |
| СИСТЕМА | СРЕДА, ДИСКИ, ОЧИСТКА, ПРОГРАММА | `tools\STORAGE_DISK_PROCEDURES_RU.md`, `tools\MAINTENANCE_CLEANUP_RU.md` |

Два коротких порядка стоит знать наизусть.

**Умолчания после чистой установки Windows.** Проверить защиту → перезаписать
эталон текущими умолчаниями → оставить удаление предложенного включённым →
включить защиту → выйти из учётной записи и войти или перезагрузиться → проверить
защиту снова.

**Подмена адреса для Bitrix.** Определить точку → посмотреть состояние имён и
портов → включить подмену → поработать → выключить подмену. Выключение
возвращает `hosts` побитово из копии, названной в служебном комментарии.

## Терминал

Вывод показывается живьём, с разбором кодировок Windows и подсистемы Linux — без
кракозябр. Итоговое состояние живёт под терминалом и держится до следующего
запуска: серый — ожидание, синяя пульсация — работа, зелёный — успех, красный —
ошибка. Всплывающее сообщение источником истины не считается: если окно было
неактивно, его можно не увидеть.

Есть строка для ручного запуска команды — с историей и кэшем частых.

## Проверка

```bat
install\verify_portable_env.cmd
runtime\python.exe -m pytest -q
```

Что именно прогоняется перед выпуском — [список проверок](SMOKE_TEST_RU.md).


---

## Техническая часть

### Запуск отдельных разделов

```bat
cli\launcher_wsl.cmd
cli\launcher_bitrix.cmd
cli\launcher_default_apps.cmd
cli\launcher_association_defense.cmd
cli\launcher_hardware.cmd
cli\launcher_codex_nuke.cmd
cli\launcher_python_nuke.cmd
```

Первые идут через тот же слой описаний и служб, что и окно. Последние два —
обёртки над встроенными средствами очистки с запросом прав и подтверждением
вводом.

### Операции из командной строки

```cmd
devops_cli.cmd describe
devops_cli.cmd run --operation <операция> --set <поле>=<значение>
devops_cli.cmd check --operation <операция>
runtime\python.exe system_core\cli_operation.py <операция> --yes-i-understand
```

`devops_cli.cmd` — та же команда, что за кнопками окна: `check` говорит, можно ли
запустить форму и о чём спросить перед запуском, `run` запускает. Меню `cli\` идут
через `system_core\cli_operation.py`; опасная операция там требует явного признака.

Полный перечень операций и их полей — [справочник команд](COMMANDS_RU.md). Он
собирается из `config\tool_manifest.yaml` и включает подсказки, разметку риска,
наследуемые поля, значения по умолчанию и варианты выбора.


### Обслуживание

```bat
init_folders.cmd                  создать недостающие рабочие папки
cleanup_project.cmd               деликатная очистка
cleanup_project.cmd /DRYRUN /Y    показать план, ничего не удаляя
cleanup_project.cmd /BACKUP       только папка резервов, со своим подтверждением
```

Очистка оставляет скрипты, настройки, документацию, лицензии, собранное окно и
структуру папок.
Удаляет порождённое и скачанное: рантайм, склад пакетов, сборки, загрузки,
вложенные двоичные средства, журналы, отчёты, содержимое рабочих папок и кэши.
Соседние средства не трогает.

### Рабочие папки

Над терминалом две строки. **ИСТОЧНИК** — откуда читают импорты: ключи,
сертификаты, профили Wi-Fi, копии; пока не выбрана другая — папка `input`.
**НАЗНАЧЕНИЕ** — куда ложатся выгрузки, резервные копии и отчёты; пока не выбрана
другая — папка `output`. Обе строки помнят прежние и закреплённые папки; в строку
источника можно вписать сетевую папку `\\СЕРВЕР\Общая\Папка`. Выгрузка ключей и
паролей — секрет: храните её как ключ.