> **Archived / done.** This plan was implemented. For current usage see [`docs/navi_code.md`](../navi_code.md) and [`docs/navi_code_cli.md`](../navi_code_cli.md).

# План: 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` между запусками.
- [ ] Документация обновлена.
- [ ] Все тесты проходят.
