# План: Navi Code — локальный терминальный клиент для Navi ## Цель Создать систему "Navi Code": локально запускаемый вариант Navi, управляемый через терминал. Без авторизации (`NAVI_AUTH_ENABLED=false`), с выделенным профилем, ориентированным на работу с кодом, терминалом и файловой системой. ## Что НЕ входит в этот этап - Docker-упаковка (отложено). - Рендеринг изображений, content_publish, share_file UI (отложено). - Авторизация (используем готовый `NAVI_AUTH_ENABLED=false`). ## Что входит в этот этап 1. Создание профиля `navi_code` на базе `developer`. 2. Механизм дефолтного профиля. 3. Подготовка bundled `.env` / конфигурации для локального терминального режима. 4. Подготовка персоны / системного промпта для Navi Code. 5. CLI-терминал-клиент для взаимодействия с Нави. 6. Документация по запуску и использованию. --- ## 1. Профиль `navi_code` ### 1.1. База - Скопировать `navi/profiles/developer/` → `navi/profiles/navi_code/`. - `id`: `navi_code`. - `name`: `"Navi Code"`. ### 1.2. Тюнинг инструментов Включить: - `terminal` — основной инструмент. - `filesystem` — чтение/запись файлов. - `code_exec` — выполнение кода. - `spawn_agent` — для сложных подзадач. - `list_tools`, `tool_manual`, `write_tool`, `reload_tools` — саморасширение. - `scratchpad`, `todo`, `reflect` — для планирования. Исключить (для упрощения терминального опыта): - `share_file`. - `content_publish`. - `image_view`. - `http_request` — оставить по необходимости, но по умолчанию убрать. - `web_search`, `ssh_exec` — оставить как опцию, но не включать по умолчанию. ### 1.3. Тюнинг параметров - `max_iterations`: сохранить высокое значение (например, 100), но не безгранично. - `temperature`: 0.3–0.4. - `model`: локальная модель по умолчанию, например `gemma4:26b-a4b-it-q4_K_M`. - Планирование: включить phase 1 и 3, отключить phase 2 (3 advisor) для снижения latency. - `iteration_budget_enabled`, `goal_anchoring_enabled`, `anti_stall_enabled`: оставить включёнными. - `step_validation_enabled`: отключить. - `adaptive_replan_enabled`: оставить выключенным. ### 1.4. Системный промпт - Скопировать `developer/system_prompt.txt`. - Адаптировать под терминальный контекст: Нави работает локально, у неё есть терминал, файловая система и возможность выполнять код. - Добавить инструкции по безопасности: перед разрушительными операциями (`rm`, перезапись) спрашивать подтверждение. --- ## 2. Механизм дефолтного профиля ### 2.1. Варианты Вариант A — env-переменная (предпочтительный): - Добавить в `navi/config.py`: `navi_default_profile_id: str = ""`. - Читать `NAVI_DEFAULT_PROFILE_ID` из `.env`. - Если задана и профиль существует, использовать её как fallback при создании сессии без `profile_id`. - REST `POST /sessions` разрешить отсутствие `profile_id`, взяв дефолт. Вариант B — клиент-side: - Терминал-клиент сам знает профиль `navi_code` и всегда шлёт его. - Проще, но менее универсально. ### 2.2. Решение Реализовать **вариант A**: серверная env-переменная + поддержка отсутствующего `profile_id` в `POST /sessions`. Это позволит любому клиенту (CLI, веб, скрипт) работать с дефолтным профилем. --- ## 3. Конфигурация для локального режима ### 3.1. Новые/изменённые env-переменные - `NAVI_AUTH_ENABLED=false` (уже есть). - `NAVI_DEFAULT_PROFILE_ID=navi_code` (новая). - `NAVI_PERSONA_FILE=persona_navi_code.txt` (новая персона). - `FS_ALLOWED_PATHS=*`. - `TERMINAL_ALLOWED_COMMANDS=*`. - `OLLAMA_HOST=http://localhost:11434`. - `DATABASE_URL=postgresql://navi:navipass@localhost:5432/navidb` (или локальная настройка пользователя). ### 3.2. Файлы, которые нужно подготовить - `.env.navi_code.example` — пример `.env` для Navi Code. - `persona_navi_code.txt` — глобальная персона для Navi Code. ### 3.3. Что не меняем - Структура конфигурации (`navi/config.py`) — добавляем только новые поля. - Поведение при `NAVI_AUTH_ENABLED=true` — не ломаем. --- ## 4. Персона Navi Code ### 4.1. Основные черты - Локальная ассистентка-разработчик. - Имеет доступ к терминалу, файловой системе и выполнению кода. - Умеет планировать, разбивать задачи на todo, работать с spawn_agent. - Перед опасными операциями спрашивает подтверждение. - Говорит с пользователем на его языке (русский/английский). ### 4.2. Правила работы с инструментами - Использует `terminal` для shell-команд. - Использует `filesystem` для чтения/записи. - Использует `code_exec` для быстрой проверки небольших фрагментов. - Использует `scratchpad` для длительных мыслей, `todo` для планирования. - Перед `write_tool` всегда вызывает `tool_manual("write_tool")`. --- ## 5. CLI-терминал-клиент ### 5.1. Расположение - `navi_code_cli/` в корне проекта (отдельный Python-пакет). - Или `clients/terminal/`. ### 5.2. Минимальный функционал MVP - Подключение к запущенному Navi backend по WebSocket. - Поддержка интерактивного режима (`navi-code` без аргументов → чат). - Поддержка one-shot режима (`navi-code "задача"` → выполнить и выйти). - Сохранение `session_id` между запусками (`~/.navi_code/state.json`). - Поддержка команд: - `/new` — новая сессия, - `/sessions` — список сессий, - `/switch ` — переключиться, - `/profile` — показать текущий профиль, - `/quit` — выход. ### 5.3. Рендеринг событий - `stream_delta` — печатать текст. - `thinking_delta` / `thinking_end` — показывать в сворачиваемом блоке или с флагом `--show-thinking`. - `tool_started` / `tool_call` — показывать имя инструмента и результат. - `stream_end` — завершение ответа. - `error` — красным цветом. ### 5.4. Зависимости - `click` или `typer`. - `websockets`. - `rich` — для цветного вывода, markdown, таблиц. - `pydantic` — для моделей. ### 5.5. Взаимодействие с сервером - `GET /agents/profiles` — проверить профиль. - `POST /sessions` — создать сессию (с дефолтным профилем). - `WS /ws/sessions/` — основной чат. - `POST /sessions//stop` — остановить генерацию. --- ## 6. Документация ### 6.1. Новые документы - `docs/navi_code.md` — полное руководство по Navi Code. - `docs/navi_code_cli.md` — документация по CLI. - `docs/profiles.md` — обновить: добавить профиль `navi_code`, описать `NAVI_DEFAULT_PROFILE_ID`. - `docs/config.md` — обновить: новые env-переменные. ### 6.2. README - Добавить раздел "Navi Code" в основной README. --- ## 7. Порядок реализации ### Этап 1 — Профиль и конфигурация 1. Создать `navi/profiles/navi_code/` на базе `developer/`. 2. Добавить `navi_default_profile_id` в `navi/config.py`. 3. Обновить `POST /sessions` для использования дефолтного профиля. 4. Создать `persona_navi_code.txt`. 5. Создать `.env.navi_code.example`. 6. Обновить документацию (`docs/profiles.md`, `docs/config.md`). ### Этап 2 — CLI клиент 1. Создать структуру `navi_code_cli/`. 2. Реализовать WebSocket-клиент. 3. Реализовать интерактивный режим. 4. Реализовать one-shot режим. 5. Реализовать сохранение состояния сессии. 6. Добавить README и документацию. ### Этап 3 — Тестирование и полировка 1. Проверить создание сессии с дефолтным профилем. 2. Проверить работу терминала через CLI. 3. Проверить персистентность сессий. 4. Проверить no-auth режим. 5. Добавить юнит-тесты на новые механизмы. --- ## 8. Риски и вопросы ### Риски - **Безопасность:** `TERMINAL_ALLOWED_COMMANDS=*` и admin-роль дают полный доступ к системе. Нужно ясно документировать, что Navi Code предназначена только для локального использования. - **Зависимость от Ollama:** пользователь должен сам запускать Ollama. Нужно документировать. - **Postgres:** нужен локальный Postgres с pgvector. Возможно, стоит позже предоставить docker-compose для БД. - **Приватная зависимость `gnexus-auth-client-py`:** при сборке/установке может потребоваться доступ к Git. Для локальной разработки текущий venv уже настроен. ### Открытые вопросы - Как именно CLI должен обрабатывать persistent терминалы? Сразу в интерактивном режиме или через отдельную команду? - Нужна ли команда `/cd` для смены рабочей директории в CLI? - Стоит ли добавить provider контекста (`cwd_provider`) или передавать cwd через параметры CLI? --- ## 9. Критерии завершения - [ ] Профиль `navi_code` создан и загружается. - [ ] `NAVI_DEFAULT_PROFILE_ID` работает, `POST /sessions` без `profile_id` создаёт сессию с дефолтным профилем. - [ ] Персона Navi Code подключена через `NAVI_PERSONA_FILE`. - [ ] CLI клиент умеет подключаться и вести диалог. - [ ] CLI клиент сохраняет `session_id` между запусками. - [ ] Документация обновлена. - [ ] Все тесты проходят.