План: 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 <id> — переключиться,
  • /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/<session_id> — основной чат.
• POST /sessions/<id>/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 между запусками.
• Документация обновлена.
• Все тесты проходят.