Сессии и проекты¶
Проект — это контейнер: он объединяет сессии, рабочий каталог, план, инварианты и реестр 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 в другой каталог нельзя. Записи фоновых прогонов переатрибутируются новому проекту.