Сессии и проекты¶

Проект — это контейнер: он объединяет сессии, рабочий каталог, план, инварианты и реестр git-репозиториев. Сессия — отдельный диалог с агентом; она может жить и без проекта.

Коротко

Проект отвечает за «где и над чем работаем» — каталог, репозитории, план, общий контекст. Сессия — за «что и как обсуждаем» — диалог, todo и режим.

Проект как контейнер¶

Сессии ссылаются на проект, а проект владеет общими для группы данными:

Что хранит проект	Назначение
Сессии	Все диалоги проекта; список можно фильтровать по проекту
Рабочий каталог	Папка, в которой работают файловые, shell- и git-инструменты
План	План работ проекта с приоритетами и зависимостями
Контекст	Инварианты проекта и лог работ — попадают в контекст агента
Репозитории	Реестр git-репозиториев проекта
Оформление	Имя, описание, иконка и цвет карточки проекта

У проекта есть владелец и участники с ролями: кто-то управляет проектом и его каталогом, кто-то может редактировать содержимое, а кто-то — только смотреть. Права на уровне сервера определяются ролевой моделью.

Сессия и проект¶

Сессия создаётся с проектом или без него — привязка к проекту необязательна.
Привязку и перенос можно сделать в интерфейсе (в том числе перетаскиванием) или через API: PATCH /api/v2/sessions/:id с полем project_id.

Сессия без проекта¶

Работа без проекта — штатный сценарий, а не ошибка:

Агент всегда знает свой контекст: есть проект или нет, какой рабочий каталог используется и какие ограничения действуют.
В сессии без проекта доступны диалог и todo, но нет плана проекта.
Если задача требует плана или длительной работы с файлами, агент подскажет завести проект или привязать сессию к существующему. Сделать это можно и самому — во вкладке «Проект».

Когда стоит создать проект

Если работа выходит за рамки одной короткой задачи, заведите проект: появятся план, общий рабочий каталог и реестр репозиториев.

Рабочий каталог проекта (workspace)¶

Workspace — это папка, в которой агент читает и пишет файлы, запускает команды и работает с git. У проекта он либо задан явно, либо используется рабочий каталог по умолчанию.

Режим	Кто владеет файловой системой	Как задаётся каталог
Серверный (managed)	Сервер	Каталог создаётся автоматически под корнем рабочих пространств; имя выводится из названия проекта. Путь виден, но не выбирается вручную
Локальный (standalone)	Пользователь	По умолчанию тоже автоматически, но доступен ручной выбор и создание каталога через диалог

Каталог создаётся автоматически — ошибка «каталог не найден» не возникает.
В локальном режиме можно выбрать произвольный абсолютный путь. Выход за пределы «безопасного» корня требует явного подтверждения; в серверном режиме он запрещён.

Гейт рабочего каталога

Файловые, shell- и git-инструменты доступны только когда у проекта задан рабочий каталог. Пока его нет, инструменты остаются в подсказке модели, но отклоняются — сначала задайте каталог. Относительные пути разрешены только внутри workspace.

Реестр git-репозиториев¶

У проекта может быть несколько git-репозиториев. Клонирование или инициализация автоматически добавляет запись в реестр, а список репозиториев показывает их все.

Репозитории живут внутри рабочего каталога проекта (допускается вложенность).
Git-инструменты принимают относительный repo_path — какой репозиторий взять за текущий. Абсолютный путь или выход через .. отклоняются.
В интерфейсе на вкладке Git видны назначение, тип, URL, SSH-ключ и время последнего обновления; там же можно клонировать, инициализировать, пересканировать и убрать запись из реестра.
Удаление записи из реестра не удаляет локальный каталог — файлы остаются.

SSH-ключи агентов¶

Для приватных репозиториев используются SSH-ключи:

Ключ хранится на агента и может быть привязан сразу к нескольким агентам.
Секреты ключей шифруются при хранении; в промптах и журналах ключи маскируются.
Поддерживаются ключи с парольной фразой.
Если репозиторий использует SSH-адрес, а ключ не задан, операция завершится явной ошибкой, а не молчаливым сбоем.

HTTPS или SSH

Публичные репозитории можно клонировать по HTTPS без ключа. Для приватных по SSH привяжите ключ к агенту в разделе настроек агентов.

Перенос сессии между проектами¶

Сессию можно перенести в другой проект — перетаскиванием или через API:

Todo остаётся с сессией.
План берётся от нового проекта: ссылки todo на пункты старого плана игнорируются, если таких пунктов в новом плане нет.
Интерфейс обновляет список проектов и дерево файлов, открытые вкладки сохраняют несохранённые правки.
У сессии без проекта todo есть, плана нет.