# AILab SCRUME Agent

Дистрибутив Hermes Agent: персона личного помощника, базовый конфиг, 58 скиллов.
Автор: AI laboratory SCRUM company.

Основано на **Hermes Agent** © Nous Research, лицензия MIT. Авторские права,
товарные знаки и сторонние компоненты описаны в `NOTICE` и `LICENSE`; вместе с
приложением поставляются `resources\LICENSE`, `resources\NOTICE` и
`resources\THIRD-PARTY-LICENSES.txt`. Это независимая сборка, не связанная с
Nous Research и не одобренная ими.

> ## ⛔ НЕ запускайте установку «от имени администратора»
>
> Откройте **обычное** окно PowerShell (Win+R → `powershell`). **Не** «Запуск от имени
> администратора».
>
> Запуск с повышением прав — главная причина отказа: папки в доме агента создаются от
> другой учётной записи, и потом движок не может прочитать свой собственный Python.
> Установка встаёт мгновенно с `Access is denied`, ещё до любой загрузки.
>
> Единственное, что запускается от администратора, — файл починки `FIX.cmd`
> (и `WIPE.cmd`), и только если установка уже остановилась.

**Получателю агента:** не нужно ничего скачивать и распаковывать руками. Откройте
PowerShell (Win+R → `powershell`) и вставьте **целиком, одной строкой**:

```powershell
$d = Join-Path $env:LOCALAPPDATA 'ailab-setup'; New-Item -ItemType Directory -Force -Path $d | Out-Null; Set-Location $d; Remove-Item -Recurse -Force ailab -ErrorAction SilentlyContinue; curl.exe -L --fail -o ailab.zip "https://github.com/AILABSCRUME/AI_Lab_SCRUME_Co/releases/latest/download/agent-setup.zip"; if (-not (Test-Path ailab.zip) -or (Get-Item ailab.zip).Length -lt 1MB) { throw "Архив не скачался. Папка: $d" }; Expand-Archive ailab.zip ailab -Force; .\ailab\setup.cmd
```

Дальше всё делает установщик: ставит движок и агента, открывает Блокнот для ключа,
прогревает окружение, качает и ставит окно приложения, кладёт ярлык **«AILab SCRUME Agent»**
на рабочий стол. Ключ API выдаёт владелец агента. Доступ к репозиторию не нужен.

Ссылка постоянная — не меняется при выпуске новых версий, повторный запуск обновляет агента
(ключ, память и переписка сохраняются). Подробности — [`INSTALL.md`](INSTALL.md).

### Если установка остановилась

В той же распакованной папке лежат файлы помощи — запускаются **двойным кликом**:

| Файл | Что делает | От администратора? |
|---|---|---|
| `CHK.cmd` | показывает, что видит установщик, и права на файлы | нет |
| `ACL.cmd` | показывает правила доступа к папке агента | нет |
| `FIX.cmd` | починка прав. **Ключ и переписка сохраняются** | **да** |
| `WIPE.cmd` | полный снос папки агента и установка заново. **Ключ вписывать заново** | **да** |

`CHK` и `ACL` ничего не меняют.

**Автору:** это исходник дистрибутива. Пакет для передачи собирается скриптом
`dist/vasily-setup/build-package.ps1` (имя папки историческое).

## Что внутри

| Путь | Что это |
|---|---|
| `distribution.yaml` | манифест: имя, версия, автор, требуемые переменные окружения |
| `SOUL.md` | персона агента: AILab SCRUME Agent, личный помощник |
| `config.yaml` | модель, провайдер (Polza.ai), инструменты, язык — **без ключей** |
| `skills/` | 62 скилла: 58 штатных Hermes + 4 наших (`skills/ailab/`) |
| `INSTALL.md` | пошаговая инструкция для получателя |
| `update-check.ps1` | ночная проверка обновлений; ставится задачей Планировщика `AILabAgentUpdate` |
| `desktop-plugins/` | шесть плагинов окна: `version-badge`, `slogan`, `hide-messaging`, `session-time`, `polza-limit`, `polza-models` |
| `.env.template` | шаблон `.env`, устанавливается как `.env.EXAMPLE` |

Ключ API живёт только в `.env` получателя: в `config.yaml` стоит
`key_env: HERMES_CUSTOM_POLZA_AI_API_KEY` — имя переменной, а не значение.
В репозитории ключей нет.

## Куда ставится

Агент ставится в **корневой дом Hermes** (`%LOCALAPPDATA%\hermes`), а не в именованный
профиль. Так у получателя ровно один агент и нет меню профилей — это требование сборки.

`hermes profile install` здесь не используется: он умеет только именованные профили, а
запарковать корневой профиль ядро Hermes не даёт (намеренно игнорирует `gateway.parked`
для `default`). Поэтому `setup.ps1` копирует `SOUL.md`, `config.yaml` и `skills/` в корень
сам и ставит файл-маркер `.ailab-install.json`, по которому следующий запуск понимает,
что это обновление, а не чужая установка.

## Что агент умеет

| | |
|---|---|
| Документы | читает и **создаёт** Excel (`.xlsx`), Word (`.docx`), PowerPoint (`.pptx`), PDF — включая формы, объединение, шифрование и извлечение текста |
| Файлы | чтение и запись, поиск по содержимому |
| Терминал и код | **включены** — на них построены скиллы документов |
| Веб-поиск | через MCP-серверы, подключаются отдельно |
| Голос | **включён**: распознавание речи (локальный Whisper, без ключей) и синтез русским голосом (`edge`) |
| Номер сборки | виден в заголовке окна чипом `AILab v<версия>` (плагин `version-badge`) |
| Девиз | справа от номера сборки, в заголовке окна (плагин `slogan`); на узком окне скрывается сам |
| Время сессии | счётчик в композере слева от чипа Polza.ai (плагин `session-time`) |
| Цены моделей | чип `Модели` рядом с расходом: две секции — **по факту списания** (свои модели, ставка из `costLines`) и **прайс каталога — не факт** (плагин `polza-models`) |
| ГОСТ-ассистент | MCP-сервер `gostassistent` в конфиге; включается своим ключом в `.env` |
| Обновления | наши ставятся сами раз в сутки ночью (задача `AILabAgentUpdate`); сообщения об обновлениях самого Hermes выключены (`updates.check: false`) |
| Навигация | строка «Сообщения» убрана из боковой панели (плагин `hide-messaging`) |
| Настройки | экспорт, импорт и сброс — рабочие; после «Сброса» запустите установку заново |
| Управление рабочим столом | **выключено** (`computer_use`) |

Терминал и запуск кода включены осознанно. Без них не работают скиллы Excel, Word,
PDF и почты: они построены на запуске python-скриптов, а другого способа запустить
скрипт в Hermes нет. Пакеты для документов (`openpyxl`, `python-docx`, `python-pptx`, `pypdf`, `reportlab`, `pdfplumber`) установщик ставит сам на шаге 8 — на живом доме проверено создание и чтение всех четырёх форматов.

Скрыть их у получателя можно так:

```powershell
hermes config set agent.disabled_toolsets "[terminal, code_execution, computer_use]"
```

Голос работает без ключей: распознавание — локальная модель Whisper, синтез — бесплатный
русский голос `edge`. Модель распознавания скачается при первом использовании.

## Что не входит

- API-ключи, `auth.json`, пароли dashboard — только свои, локальные.
- MCP-серверы (Revit, AutoCAD и прочее) — не подключены, ставятся отдельно под свои задачи.
- SSH-бэкенд, cron-задачи, память и история автора.

## Передать получателю (файлом)

```bash
cd "$LOCALAPPDATA/hermes/dist/vasily-setup"
powershell -NoProfile -ExecutionPolicy Bypass -File build-package.ps1
```

Скрипт берёт версию из `distribution.yaml`, собирает бандл, копирует `setup.cmd`,
`setup.ps1`, `INSTALL.md`, `ПРОЧТИ-МЕНЯ.txt` и складывает всё в
`../ailab-setup-v<версия>.zip`.

Или вручную только бандл:

```bash
cd <этот каталог>
git bundle create ../ailab-v<версия>.bundle --all
git bundle verify ../ailab-v<версия>.bundle   # ожидается «is okay» + «complete history»
```

Получатель разворачивает по `INSTALL.md`.

## Обновить агента у получателя

**С v1.5.0 обновляется само.** Установщик заводит задачу Планировщика `AILabAgentUpdate`:
раз в сутки ночью она сравнивает установленную версию с последним релизом на GitHub и,
если вышла новая, ставит её. Условие одно — окно агента в этот момент должно быть закрыто,
иначе проверка отложится до следующей ночи. Журнал: `%LOCALAPPDATA%\hermes\logs\update-check.log`.
Отключается `update-check.ps1 -Off`.

**Вручную** (когда нужно сразу): поднять `version` в `distribution.yaml`, закоммитить,
поставить тег, пересобрать пакет `build-package.ps1` и передать новый архив. Получателю
достаточно положить новый `ailab-<версия>.bundle` рядом со `setup.cmd` и запустить его
снова: маркер в доме подскажет, что это обновление, а `.env` с ключом, память и переписка
не трогаются.

## Проверка перед передачей

Тест на подменённой машине — так собственный дом не участвует:

```powershell
# 1. "машина" получателя: рантайм без агента
$fake = 'C:\tmp\recv\AppData\Local'
New-Item -ItemType Directory "$fake\hermes" -Force
Copy-Item "$env:LOCALAPPDATA\hermes\tools" "$fake\hermes\tools" -Recurse
Copy-Item "$env:LOCALAPPDATA\hermes\bin"   "$fake\hermes\bin"   -Recurse

# 2. прогон установщика в ней
$env:LOCALAPPDATA = $fake
cd C:\tmp\recv\package          # распакованный ailab-setup-*.zip
powershell -NoProfile -ExecutionPolicy Bypass -File .\setup.ps1
```

Проверить после прогона: `%LOCALAPPDATA%\hermes\SOUL.md` (персона без имени автора),
58 скиллов, `.ailab-install.json` с версией, `.env` с ключом.

Публикация в git-репозиторий (вариант с обновлением одной командой):

```bash
git tag v<версия> && git push origin master --tags
```

## MCP (по желанию)

Добавляется уже в установленном агенте:

```bash
hermes mcp add <имя> --command <команда>
hermes mcp catalog          # посмотреть, что есть в каталоге
```