Перейти к содержанию

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

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

Коротко

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

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

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

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

У проекта есть владелец и участники с ролями — подробности ниже.

Участники и доступ к проекту

Проект общий: у него есть владелец (автор) и участники. Доступ определяется ролью в проекте; серверные роли (ADMIN, LEAD) дают сквозной обзор, но не заменяют участие.

Роль в проекте Что даёт
Просмотр Читает всё содержимое проекта, включая историю сессий; ход не запускает
Изменение содержимого Всё то же плюс работа: сообщения и ход, файлы, git, план, терминалы, автоматизации
Владелец Всё то же плюс управление доступом и передача владения
  • Чтение не даёт права менять. «Просмотр» остаётся только чтением: сессию видно, но отправить в неё сообщение или поправить файл нельзя.
  • Администраторы и LEAD видят все проекты независимо от состава участников; это сквозной обзор, а не участие.

Кого можно добавить

  • Пользователей — из каталога: он показывает имя и отображаемое имя, так что выбирать участника можно по-человечески, а не по идентификатору.
  • Группы из OIDC — группу целиком: права получают все её участники. Каталог групп показывает только те группы, которые разрешены настройкой входа; группы вне списка в нём не появляются.
  • Всех — режим публикации: любой аутентифицированный пользователь инстанса получает выбранную роль. Роль «владелец» для режима «доступ всем» недоступна.

Состав доступа задаётся полной заменой списка: добавляя участника, вы отправляете итоговый набор. Менять доступ может владелец, администратор или LEAD; участник с ролью изменения содержимого — нет.

Что даёт доступ

  • Всё содержимое проекта — описание, файлы и рабочий каталог, git, план, журнал, инварианты, память, пайплайны, автоматизации и сессии с их историей. Частичной видимости нет: нельзя открыть только файлы, скрыв историю диалогов.
  • Запись в чужую сессию определяется ролью: «Просмотр» — только чтение, «Изменение содержимого» и владелец — обычный ход.
  • Уведомлений добавленным участникам нет. Проект просто появляется в их списке — о добавлении нужно сообщить отдельно.

Передача владения

  • Владение передаёт текущий владелец или администратор; получатель выбирается из каталога пользователей.
  • Новый владелец получает управление проектом, прежний остаётся с правом изменения содержимого — доступ к проекту не теряется.
  • Передать владение себе или сервисной учётной записи нельзя.
  • У удалённого проекта в гибридном режиме владение передаётся на сервере проекта.

Импорт, экспорт и копирование

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

  • в портативный архив проекта участники, группы и режим «доступ всем» не попадают;
  • после импорта проект в состоянии «только автор»: владелец — тот, кто импортировал;
  • копия и форк проекта тоже создаются «только автором», а публикация на другой инстанс гранты не переносит;
  • при слиянии с существующим проектом состав доступа цели не меняется.

Перенос сессии в другой проект

Перенос следует за сессией, но живая работа (ход, фоновые прогоны, терминалы, автоматизации) требует согласия человека — подробности в разделе «Перенос сессии между проектами» ниже.

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

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

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

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

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

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

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

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

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

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

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

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

Рабочий каталог сессии: worktree

Поверх каталога проекта у сессии может быть свой рабочий каталог — привязка к worktree, вторичной рабочей копии репозитория с отдельной веткой. Это позволяет вести несколько задач параллельно, не переключая основную копию.

  • Привязка выбирается в правой панели: вкладка «Сессия» → блок «Рабочий каталог» → «Worktree: {имя}».
  • Список копий проекта — во вкладке «Проект» → раздел «Worktree'ы»; там же создание, привязка и удаление.
  • Создание worktree само по себе сессию не привязывает — это отдельный шаг.
  • В режиме plan worktree'ы доступны только на чтение.
  • Если каталог копии исчез, инструменты вернут явную ошибку и не перейдут тихо на каталог проекта.

Подробнее — Git worktrees.

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

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

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

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

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

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

HTTPS или SSH

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

Файлы и лимиты

У файловых и git-операций есть пределы, которые защищают инстанс от случайной перегрузки. Значения ниже — по умолчанию; часть из них настраивается администратором.

Операция Предел Поведение при превышении
GET /api/v2/fs/read — чтение файла 5 МиБ 413 FILE_TOO_LARGE; в details — лимит, размер и причина (size — большой файл, binary — не текст)
GET /api/v2/fs/raw — предпросмотр 100 МиБ 413 FILE_TOO_LARGE с details.maxPreviewBytes
GET /api/v2/fs — листинг каталога глубина до 3, бюджет 10 000 записей обход прекращается, в ответе truncated: true — список неполный
GET /api/v2/git/commit — diff коммита 1 МиБ diff обрезается, в ответе diff_truncated: true; список изменённых файлов остаётся полным
POST /api/v2/fs/upload — загрузка файла 100 МиБ 413 PAYLOAD_TOO_LARGE
  • Чтение проверяет размер по метаданным до чтения содержимого, поэтому большой файл не поднимается в память целиком. Бинарный файл тоже даёт 413, а не пустую строку.
  • Предпросмотр отдаёт байты потоком. Встроенно (inline) показываются только изображения, видео, аудио и PDF; HTML, код, текст и неизвестные форматы отдаются как вложение — иначе HTML выполнился бы в приложении. Поддерживаются Range (частичная отдача, 206) и ETag (304 при повторном запросе).
  • Листинг при maxDepth = 0 не рекурсивный и бюджет записей не применяет.
  • Загрузка проверяет размер трижды: по заявленному content-length, по размеру файла и по фактически прочитанным байтам.

Пределы задаются в конфигурации инстанса:

Параметр Что ограничивает
storage.maxReadBytes GET /api/v2/fs/read (5 МиБ)
storage.maxPreviewBytes GET /api/v2/fs/raw (100 МиБ)
storage.maxUploadBytes POST /api/v2/fs/upload (100 МиБ)

Подробнее о значениях и способах их изменения — Конфигурация.

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

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

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

Если в сессии есть живая работа

Активный ход, фоновые прогоны, терминалы и автоматизации привязаны к старому проекту, поэтому перенос требует согласия человека:

  • Synth показывает, что будет затронуто, и переносит сессию только после подтверждения. Согласие даёт человек: агент и сервисный ключ этого сделать не могут, удалённая (гибридная) сессия переносится на сервере проекта.
  • Порядок детерминированный: останавливаются фоновые процессы и саб-агенты, закрываются терминалы, отменяются автоматизации, снимается привязка к worktree, затем переезжает сессия вместе с дочерними сессиями и меняется проект.
  • Если остановить что-то не удалось, перенос не выполняется — частичного состояния не остаётся.
  • Эффекты видны в истории: в сессию пишется служебное сообщение о переносе со списком последствий — что остановлено, что отменено и какие терминалы остались в старом проекте.
  • Закрытые терминалы остаются в старом проекте: безопасно перенести живой PTY в другой каталог нельзя. Записи фоновых прогонов переатрибутируются новому проекту.

Что дальше