Лейблы

Лейблы — это аддитивные цветные теги, которые можно применять к сессиям. В отличие от статусов (которые эксклюзивны — один на сессию), лейблы поддерживают множественный выбор — сессия может иметь ноль или множество лейблов. Они поддерживают иерархическую организацию через вложенные деревья.

На сессиях лейблы хранятся как плоский массив строк. Булевы (присутствие только) лейблы — это просто ID, например "bug". Лейблы со значением используют разделитель ::, например "priority::3" или "due::2026-01-30". Парсер определяет тип значения из исходной строки при чтении.

Как работают лейблы

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

Конфигурация на уровне workspace

Лейблы настраиваются для каждого workspace. Каждый workspace начинается с нулевого количества лейблов — вы создаёте те, которые вам нужны.

Конфигурация хранится по пути:

~/.craft-agent/workspaces/{workspace-id}/labels/config.json

Создание лейблов

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

• "Создай лейбл Bug с красным цветом"
• "Добавь лейблы проектов Alpha и Beta в группе Engineering"
• "Настрой лейбл Priority со значениями чисел"

Агент обрабатывает конфигурацию автоматически.

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

Базовый пример

{
  "version": 1,
  "labels": [
    {
      "id": "bug",
      "name": "Bug",
      "color": "destructive"
    },
    {
      "id": "feature",
      "name": "Feature",
      "color": "accent"
    }
  ]
}

Иерархические лейблы

Лейблы формируют вложенное дерево. Родительские/дочерние отношения выражаются через массив children. Позиция в массиве определяет порядок отображения.

{
  "version": 1,
  "labels": [
    {
      "id": "eng",
      "name": "Engineering",
      "color": "info",
      "children": [
        {
          "id": "frontend",
          "name": "Frontend",
          "children": [
            { "id": "react", "name": "React", "color": { "light": "#3B82F6", "dark": "#60A5FA" } }
          ]
        },
        { "id": "backend", "name": "Backend" }
      ]
    },
    { "id": "bug", "name": "Bug", "color": "destructive" }
  ]
}

Это отображается как дерево в боковой панели:

Engineering
  |- Frontend
  |    \- React
  \- Backend
Bug

Правила иерархии

• ID — это простые слаги (строчные буквы, цифры и дефисы)
• ID должны быть глобально уникальны по всему дереву
• Максимальная глубина вложенности: 5 уровней
• Позиция в массиве = порядок отображения (поле order не нужно)
• Фильтрация по родительскому включает все дочерние сессии

Свойства лейбла

Каждый объект лейбла поддерживает следующие свойства:

Цвета

Лейблы отображаются как цветные круги в интерфейсе. Вы можете использовать системные цвета или пользовательские значения HEX.

Системные цвета

Используйте семантические имена цветов для распространённых значений:

Системные цвета также поддерживают непрозрачность: "accent/80", "info/50" и т.д.

Пользовательские цвета

Для точного контроля используйте пары светлой/тёмной темы:

{
  "color": { "light": "#6366F1", "dark": "#818CF8" }
}

Поддерживаются форматы HEX, OKLCH, RGB и HSL.

Используйте пользовательские цветовые объекты для подлейблов, чтобы получить точный контроль цвета. Системные цвета оставляйте для основных категорий.

Значения лейблов

Лейблы могут дополнительно нести значение с определённым типом. Это превращает лейблы в структурированные метаданные — например, лейбл "priority" со значением 3, или лейбл "due" с датой.

Формат хранения

Сессии хранят лейблы как массив строк. Булевы лейблы — это просто ID; лейблы со значением используют разделитель :::

{
  "labels": ["bug", "priority::3", "due::2026-01-30", "linear::CRA-456"]
}

• Булевы лейблы: "bug" — присутствие только, без значения
• Лейблы со значением: "priority::3" — ID + значение, разделённые ::
• Разделение :: происходит только на первом вхождении (значения могут содержать ::)

Типы значений

Значения определяются из исходной строки при разборе:

Порядок определения: проверка ISO-даты → проверка числа → fallback на строку.

Свойство valueType в конфигурации — это подсказка для интерфейса — парсер всегда определяет тип из исходного значения. link — это элемент отображения: значение отображается как кликабельный чип (схема удаляется для отображения), который открывается во внешнем браузере, с действием Открыть ссылку в всплывающем окне значения для доступа с клавиатуры. Значение ссылки всё ещё хранится и разбирается как обычная строка.

Поведение боковой панели

Лейблы отображаются в левой боковой панели как многоуровневая расширяемая секция. Клик по лейблу фильтрует список сессий, показывая только соответствующие сессии. Клик по родительскому лейблу включает сессии, помеченные любым дочерним лейблом.

Валидация

Всегда проверяйте конфигурацию после внесения изменений.

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

config_validate({ target: "labels" })

Валидатор проверяет:

• Корректный JSON и рекурсивную структуру схемы
• Глобально уникальные ID по всему дереву
• Корректный формат слага (строчные буквы с дефисами)
• Максимальная глубина вложенности (5 уровней)

Ключевые различия от статусов