## Инструкция по установке и настройке инструмента агентной разработки `Kilo Code`

> **Обозначения сочетаний клавиш.** Здесь и далее сочетание `Ctrl+Shift+P` приведено для Windows и Linux. В macOS вместо него используется `Cmd+Shift+P`.

### Подготовка

Для подключения к кластеру на локальном компьютере должен быть установлен клиент OpenSSH. Проверить его наличие можно командой, выполненной в терминале (Windows: PowerShell; macOS и Linux: «Терминал»):

```bash
ssh -V
```

Если команда не найдена, установите клиент:

- **Windows 10/11:** «Параметры» → «Приложения» → «Дополнительные компоненты» → «Клиент OpenSSH». Также можно выполнить в PowerShell, запущенном от имени администратора, следующую команду:
  ```powershell
  Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
  ```
- **macOS:** клиент OpenSSH входит в состав системы, дополнительная установка не требуется.
- **Linux:**
  ```bash
  sudo apt install openssh-client    # Debian, Ubuntu
  sudo dnf install openssh-clients   # Fedora, RHEL, Rocky, Alma
  sudo pacman -S openssh             # Arch
  ```

### Установка и настройка

1. Установите среду разработки [Microsoft Visual Studio Code](https://code.visualstudio.com/):
   - **Windows:** запустите установщик (`User Installer` или `System Installer`) и следуйте указаниям мастера установки;
   - **macOS:** распакуйте загруженный архив и переместите приложение `Visual Studio Code` в папку «Программы» (`Applications`);
   - **Linux:** установите пакет `.deb` (Debian, Ubuntu) или `.rpm` (Fedora, RHEL) либо воспользуйтесь Snap: `sudo snap install code --classic`.

2. Запустите `VS Code`, на левой панели откройте вкладку `Extensions` и установите расширение [`Remote - SSH`](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).

3. На левой панели откройте вкладку `Remote Explorer`. Если в выпадающем списке в верхней части панели выбран иной режим, выберите `Remotes (Tunnels/SSH)`. Наведите указатель мыши на строку `SSH` и щёлкните по значку `+`.

4. В открывшейся строке введите следующую команду, заменив `user` на логин **учётной записи, выданной вам системным администратором**:

```
ssh -p 57322 user@cluster.vstu.ru
```

После ввода команды выберите в качестве хранилища записи пользовательский файл конфигурации SSH:

| ОС      | Путь к файлу                                   |
|---------|------------------------------------------------|
| Windows | `C:\Users\<имя_пользователя>\.ssh\config`      |
| macOS   | `/Users/<имя_пользователя>/.ssh/config`        |
| Linux   | `/home/<имя_пользователя>/.ssh/config`         |

После этого в файле `config` появится запись следующего вида:

```
Host cluster.vstu.ru
  HostName cluster.vstu.ru
  Port 57322
  User user
```

При необходимости данную запись можно скорректировать. После корректировки следует обновить список хостов в расширении `Remote - SSH`, нажав кнопку `Refresh` (значок круговой стрелки) в заголовке раздела `SSH` на левой панели.

5. Перед подключением убедитесь, что права доступа к папке `.ssh` и файлам в ней **предоставлены только вашему пользователю**. В противном случае при подключении могут возникать ошибки, например, `Bad owner or permissions on .../.ssh/config`.

   **Windows** (PowerShell):
   ```powershell
   icacls "$env:USERPROFILE\.ssh" /inheritance:r /grant:r "${env:USERNAME}:(OI)(CI)F"
   icacls "$env:USERPROFILE\.ssh\config" /inheritance:r /grant:r "${env:USERNAME}:F"
   # Проверка: в списке должен присутствовать только ваш пользователь
   icacls "$env:USERPROFILE\.ssh"
   ```

   **macOS и Linux** (Терминал):
   ```bash
   chmod 700 ~/.ssh
   chmod 600 ~/.ssh/config
   # Если владельцем папки является другой пользователь:
   sudo chown -R "$USER" ~/.ssh
   # Проверка
   ls -ld ~/.ssh && ls -l ~/.ssh
   ```

6. Щёлкните по кнопке с изображением стрелки (`Connect in Current Window`) рядом с появившимся хостом. Если `VS Code` запросит платформу удалённого узла, укажите `Linux` (независимо от операционной системы локального компьютера).

7. При запросе пароля от учётной записи введите его. Дождитесь установки соединения с кластером и завершения настройки удалённого сервера.

8. Установите в окне `VS Code` **на удалённом сервере** расширение [`Kilo Code`](https://marketplace.visualstudio.com/items?itemName=kilocode.Kilo-Code) тем же способом, что и ранее: на странице расширения нажмите кнопку `Install in SSH: cluster.vstu.ru`.

> Начиная с этого шага, расширение `Kilo Code` и его конфигурационные файлы располагаются на кластере (ОС Linux), поэтому дальнейшие действия не зависят от операционной системы локального компьютера (за исключением сочетаний клавиш).

9. Откройте файл пользовательских настроек `VS Code`: `Ctrl+Shift+P` → **Preferences: Open User Settings (JSON)**. Добавьте в корневой объект `JSON`-файла следующий фрагмент (не забудьте поставить запятую после предыдущего параметра):

```jsonc
{
    // ... существующие параметры ...
    "json.schemaDownload.trustedDomains": {
        "https://opencode.ai/": true,
        "https://models.dev/": true
    }
}
```

10. Перезагрузите окно `VS Code`: `Ctrl+Shift+P` → **Developer: Reload Window**.

11. Откройте страницу настроек `Kilo Code` и нажмите кнопку «**Global config (Глобальный конфиг)**». Если открывшийся конфигурационный файл пуст, вставьте в него приведённый ниже фрагмент целиком; если файл уже содержит параметры, добавьте недостающие ключи в существующий объект:

```jsonc
{
    "$schema": "https://opencode.ai/config.json",
    "disabled_providers": [],
    "provider": {
        "local-provider": {
            "npm": "@ai-sdk/openai-compatible",
            "name": "Local Provider",
            "options": {
                "baseURL": "http://sglang-host:30000/v1"
            },
            "models": {
                "RedHatAI/Qwen3.8-27B-INT4": {
                    "id": "RedHatAI/Qwen3.8-27B-INT4",
                    "name": "Qwen3.8-27B INT4",
                    "tool_call": true,
                    "reasoning": true,
                    "limit": {
                        "context": 160000,
                        "output": 32000
                    }
                }
            }
        }
    }
}
```

12. Перезагрузите окно `VS Code`: `Ctrl+Shift+P` → **Developer: Reload Window**. Дождитесь завершения загрузки.

13. Откройте в настройках `Kilo Code` раздел «Провайдеры» → «Подключённые провайдеры» → `Local Provider` → **«Редактировать провайдера»**. В открывшемся окне укажите `API key` для сервера моделей, **выданный вам системным администратором**. **Убедитесь в отсутствии сообщений об ошибках.**

![api-key](images/web-key.png)

14. Перезагрузите окно `VS Code`: `Ctrl+Shift+P` → **Developer: Reload Window**. Дождитесь завершения загрузки.

15. **Инструмент готов к работе.** В окне чата можно выбрать соответствующую роль, указать доступную модель и уровень рассуждения, после чего приступить к разработке.

![chat](images/chat.png)

> Для эффективного использования `Kilo Code` рекомендуется настроить его в соответствии с вашими задачами. Документация к инструменту доступна по адресу: [`Kilo Code Docs`](https://kilo.ai/docs/).

> Полезные ресурсы по `Kilo Code`:
> * [Kilo Framework example](https://github.com/h-nasu/kilo-framework)
> * [Kilo Marketplace](https://github.com/Kilo-Org/kilo-marketplace)

> **Обратите внимание!** Все файлы проекта располагаются на кластере. При необходимости их можно скопировать на локальный компьютер одним из следующих способов:
> * **Все ОС:** в панели `Explorer` окна `VS Code`, подключённого к кластеру, щёлкните правой кнопкой мыши по файлу или папке и выберите **Download...**;
> * **Все ОС** (терминал; в Windows — PowerShell):
>   ```bash
>   scp -P 57322 -r user@cluster.vstu.ru:~/<папка_проекта> ./
>   # или, с использованием записи из файла ~/.ssh/config:
>   scp -r cluster.vstu.ru:~/<папка_проекта> ./
>   ```
> * **Windows:** [WinSCP](https://winscp.net/eng/download.php);
> * **macOS:** [Cyberduck](https://cyberduck.io/) или [FileZilla](https://filezilla-project.org/);
> * **Linux:** `rsync`, [FileZilla](https://filezilla-project.org/) или встроенная поддержка `sftp://` в файловом менеджере (Nautilus, Dolphin).