Ресурсы проектов

Ресурс проекта — это типизированный указатель: URL Git-репозитория, путь на вашей машине, завтра — страница Notion, прикреплённый к проекту. Когда агент работает над задачей внутри этого проекта, демон автоматически записывает список ресурсов проекта в рабочую директорию агента и в его промпт мета-навыка.

Результат: агент знает, какой репозиторий клонировать (или в какой локальной директории работать) и какие документы являются «основными ссылками» для этого проекта — без того, чтобы кто-то копировал контекст в тело задачи.

Ментальная модель

Проект — это больше не просто метка. Это небольшой контейнер ресурсов:

• У проекта есть 0..N ресурсов.
• Ресурс имеет resource_type (например, github_repo, local_directory) и resource_ref (JSON-нагрузка, типизированная по resource_type).
• Новые типы ресурсов добавляют строку + обработчик. Без миграции схемы. Без переписывания фронтенда.

Такая форма выбрана намеренно — это тот же паттерн, который AACWorkflow уже использует для провайдеров агентов: дискриминатор type и типизированная нагрузка. Это сохраняет схему стабильной, так что добавление «страницы Notion», «Google Doc», «загруженного файла» или «внешнего URL» позже будет небольшим аддитивным изменением.

На сегодняшний день доступно два типа ресурсов: github_repo (клонирование под задачу в изолированное worktree) и local_directory (запуск прямо в папке на машине конкретного демона).

Тип ресурса: github_repo

Тип ресурса по умолчанию — клонируется под каждую задачу в изолированное worktree:

{
  "resource_type": "github_repo",
  "resource_ref": {
    "url": "https://github.com/owner/repo",
    "default_branch_hint": "main"
  }
}

default_branch_hint опционален — если указан, демон отображает его в мета-навыке, чтобы агент знал, от какой ветки отталкиваться.

Тип ресурса: local_directory

Для репозиториев, которые неразумно переклонировать под каждую задачу — многогигабайтные игровые проекты, большие монорепозитории или любые проекты, где модель worktree-на-задачу болезненна — проект может вместо этого указывать на существующую директорию на машине конкретного демона. Агент работает прямо внутри этой папки, без клонирования, копирования и worktree.

{
  "resource_type": "local_directory",
  "resource_ref": {
    "local_path": "/Users/me/code/big-game",
    "daemon_id": "0001234e-…",
    "label": "основной checkout"
  }
}

Компромисс по сравнению с github_repo намеренный: только привязанный демон может брать задачи с этой директорией, и задачи на одной директории выполняются последовательно, а не параллельно. Взамен вы сохраняете свой существующий checkout, свою ветку, своё грязное состояние — AACWorkflow никогда не переклонирует его.

Когда выбирать local_directory вместо github_repo

Как работает параллельность

Директория является мьютексом. Когда одна задача работает в /Users/me/code/big-game, любая другая задача для той же директории в том же проекте получает статус waiting_local_directory и ждёт. Задачи для разных директорий или разных проектов не блокируются — блокировка действует только на уровне (daemon_id, local_path).

Это преднамеренное ограничение: две параллельные задачи, одновременно изменяющие файлы в одной директории, создали бы конфликты, которые невозможно разрешить автоматически. Последовательное выполнение — это компромисс.

Статус waiting_local_directory отображается в интерфейсе как жёлтый бейдж; задачи, ожидающие по этой причине, отображаются в списке задач демона.

Жизненный цикл при использовании local_directory

До запуска агента демон:

• Проверяет, что local_path существует и является директорией
• Проверяет права на чтение и запись
• Создаёт output/ и logs/ внутри workspacesRoot, но не трогает директорию пользователя
• Записывает CLAUDE.md / AGENTS.md (или эквивалент для провайдера вашего агента) и .aacworkflow/project/resources.json в корень директории, чтобы у агента был его мета-навык и список ресурсов. Добавьте их в .gitignore, если не хотите коммитить.

Во время работы агент:

• Прочитает любые файлы в директории
• Запишет любые изменения кода, которые решит сделать — точно так же, как если бы вы запустили агента локально сами
• Никогда физически не удалит директорию или что-либо внутри неё. Сборка мусора учитывает пути: для envRoot типа local_directory она очищает только свои output/ и logs/ внутри workspacesRoot, а директорию пользователя считает неприкосновенной.

Ограничения v1 (будут ужесточены в следующих версиях)

Первый релиз намеренно имеет более острые углы, чем github_repo. Ожидайте, что этот список сократится со временем — здесь документировано то, что актуально на сегодня:

• Нет автоматического переключения веток. Агент работает в той ветке, которая у вас checkout. Переключитесь перед отправкой задачи, если это важно.
• Нет защиты грязного дерева или авто-коммита. Незакоммиченные изменения видны агенту, могут быть изменены на месте и не будут спрятаны. Относитесь к директории как к реальному рабочему дереву и коммитьте перед рискованными запусками.
• Нет автоматического PR. По завершении задачи изменения остаются на той ветке, где были сделаны — ничего не пушится и PR не открывается. Запушьте и откройте PR сами, когда будете готовы.
• waiting_local_directory показывает статус, но не держателя. Бейдж сообщает, что задача припаркована; он не показывает, какая задача или какой путь к файлу в данный момент удерживает директорию.

Это отслеживается как продолжение работы над жизненным циклом задач агента для функциональности local-directory; пока это не реализовано, относитесь к local_directory как к «агент работает в вашей папке, так же, как работали бы вы».

Прикрепление репозиториев при создании проекта

В веб- или десктопном приложении окно Новый проект теперь показывает вкладку Repos рядом с Status / Priority / Lead. Выбор привязанных к пространству репозиториев (или вставка ad-hoc URL) прикрепляет их как ресурсы github_repo в момент создания проекта.

Из CLI:

# Создать + прикрепить одним действием. Сервер прикрепляет ресурсы в той же
# транзакции, что и создание проекта — некорректные ресурсы откатывают всю
# операцию, так что вы никогда не получите проект с половиной ресурсов.
aacworkflow project create \
  --title "Agent UX 2026" \
  --repo https://github.com/aacworkflow-ai/aacworkflow

# Управление ресурсами позже
aacworkflow project resource list <project-id>
aacworkflow project resource add  <project-id> --type github_repo --url <url>
aacworkflow project resource remove <project-id> <resource-id>

# Универсальный способ для любого resource_type, понятного серверу —
# изменений CLI не требуется при добавлении нового типа:
aacworkflow project resource add <project-id> \
  --type notion_page \
  --ref '{"page_id":"…","title":"…"}'

--repo можно повторять; каждое значение прикрепляется как отдельный ресурс github_repo.

Что видит агент во время выполнения

Когда демон запускает агента для задачи внутри проекта, происходят две вещи:

1. .aacworkflow/project/resources.json

Структурированная передача ответа API, записанная в рабочую директорию агента:

{
  "project_id": "…",
  "project_title": "Agent UX 2026",
  "resources": [
    {
      "resource_type": "github_repo",
      "resource_ref": {
        "url": "https://github.com/aacworkflow-ai/aacworkflow",
        "default_branch_hint": "main"
      }
    }
  ]
}

Навыки, вспомогательные скрипты или сам агент могут разобрать этот файл, когда им нужен точный набор ресурсов для запуска.

2. Секция «Project Context» в промпте мета-навыка

CLAUDE.md / AGENTS.md агента (в зависимости от провайдера) теперь включает человекочитаемую сводку:

## Project Context

Эта задача относится к проекту **Agent UX 2026**.

Ресурсы проекта (также записаны в `.aacworkflow/project/resources.json`):

- **GitHub repo**: https://github.com/aacworkflow-ai/aacworkflow (ветка по умолчанию: `main`)

Ресурсы — это указатели; открывайте их, только когда они имеют отношение к задаче.
Для ресурсов `github_repo` используйте `aacworkflow repo checkout <url>`, чтобы получить код.

Текст намеренно минимален. Полная нагрузка лежит на диске; промпт лишь ориентирует агента, чтобы он знал о существовании проекта и о том, что к нему прикреплено.

Режим отказа

Получение ресурсов — best-effort. Если вызов API завершился ошибкой, секция проекта исключается из промпта, и файл не записывается, но задача всё равно запускается. Агенты никогда не блокируются из-за отсутствия контекста проекта.

Добавление нового типа ресурса

Весь смысл абстракции в том, что новые типы дёшевы. Полный путь:

1. Валидатор сервера (server/internal/handler/project_resource.go) — добавить case в validateAndNormalizeResourceRef, который разбирает и нормализует новую нагрузку.
2. Форматтер мета-навыка демона (server/internal/daemon/execenv/runtime_config.go) — добавить case в formatProjectResource, чтобы промпт агента отображал новый тип как читаемый пункт.
3. Типы TypeScript (packages/core/types/project.ts) — расширить ProjectResourceType и добавить интерфейс нагрузки.
4. Отрисовщик UI (packages/views/projects/components/project-resources-section.tsx) — добавить case в ResourceRow для нового типа.

Нет миграции схемы, нет нового sqlc-запроса, нет нового эндпоинта и нет изменений CLI — универсальный флаг CLI --ref '<json>' принимает любую нагрузку, которую понимает валидатор, так что поддержка нового типа с первого дня — это чисто четыре шага выше. (Опционально позже можно добавить сокращение CLI для конкретного типа; не обязательно.)

Одна и та же таблица project_resource и три CRUD-вызова обрабатывают все типы.

Репозитории пространства и репозитории проекта

Список репозиториев, показываемый агенту (блок ## Repositories в CLAUDE.md / AGENTS.md), выбирается обработчиком демона со следующим приоритетом:

• У проекта есть хотя бы один ресурс github_repo → агенту показываются только эти репозитории. Репозитории, привязанные к пространству, намеренно скрыты, чтобы агенту не приходилось угадывать, какой из них относится к этой задаче.
• У проекта нет ресурсов github_repo (или задача не в проекте) → возврат к списку репозиториев пространства, как раньше.

Это держит рабочий набор агента компактным: когда проект явно указывает свои репозитории, это авторитетный ответ. Структурированный список ресурсов в .aacworkflow/project/resources.json всегда содержит полный набор, так что навык, желающий проверить всё, всё ещё может это сделать.

Демон отражает это и на стороне checkout: когда приходит задача с ограниченными проектом URL github_repo, эти URL объединяются с allowlist-ом уровня пространства и синхронизируются в локальный кеш репозиториев перед запуском агента. Так что URL репозитория проекта, не привязанный на уровне пространства, всё равно является допустимым аргументом для aacworkflow repo checkout — демон не отклонит его как «не настроенный». Разделение allowlist внутреннее: URL уровня пространства и URL уровня задачи отслеживаются раздельно, так что обновление репозиториев пространства случайно не отзовёт URL проекта во время выполнения.

Что намеренно не входит в область

• Общий доступ между проектами. Сегодня каждый ресурс принадлежит ровно одному проекту.
• Ограничение ресурсов по навыкам. Все ресурсы видны каждому навыку при запуске агента; фильтрация по типу — это дальнейшее развитие.
• Кеширование / синхронизация. github_repo — это просто метаданные; checkout по-прежнему происходит через aacworkflow repo checkout по требованию. Кешированный текст документов для Notion / Google Docs появится вместе с этими типами.

Это осознанные omission — цель первой версии: проверить абстракцию с минимальным набором движущихся частей.