Настройка меток

Места хранения

• Конфигурация: ~/.craft-agent/workspaces/{id}/labels/config.json

Нет значений по умолчанию (обычные метки)

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

Визуальное представление

Метки — только цвет: в UI они отображаются как цветные круги. Иконки и эмодзи не поддерживаются.

Иерархические метки (вложенное дерево)

Метки образуют вложенное JSON-дерево. Иерархия — это сама структура: отношения «родитель/потомок» выражаются через массив children. Позиция в массиве определяет порядок отображения (поле order не нужно).

Пример:

{
  "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

Правила:

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

Схема config.json

{
  "version": 1,
  "labels": [
    {
      "id": "bug",
      "name": "Bug",
      "color": "destructive"
    },
    {
      "id": "feature",
      "name": "Feature",
      "color": "accent",
      "children": [
        { "id": "ui", "name": "UI", "color": { "light": "#6366F1", "dark": "#818CF8" } },
        { "id": "api", "name": "API", "color": { "light": "#10B981", "dark": "#34D399" } }
      ]
    }
  ]
}

Свойства меток

Формат цвета

То же, что и для статусов — см. документацию по статусам для полных деталей о поддерживаемых форматах и типичных ошибках.

Системные цвета: "accent", "info", "success", "destructive", "foreground" (с необязательным /opacity 0–100)

Кастомные цвета: { "light": "#EF4444", "dark": "#F87171" } — поддерживаются форматы hex, OKLCH, RGB, HSL

Метки сессий

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

{
  "labels": ["bug", "priority::3", "due::2026-01-30", "linear::https://linear.app/issue/ENG-456"]
}

• Метки дополнительные (у сессии может быть ноль или много меток)
• Булевы метки: "bug" — только наличие, без значения
• Метки со значением: "priority::3" — идентификатор и значение разделены ::
• Разделение по :: выполняется только по первому вхождению (значение может содержать ::)
• Некорректные идентификаторы меток тихо отфильтровываются при чтении
• Удаление метки автоматически удаляет её из всех сессий (вместе с потомками)
• Иерархическая фильтрация: клик по родительской метке показывает сессии, отмеченные ею или любым потомком

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

Типы значений выводятся из исходной строки при разборе:

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

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

Добавление меток

Предпочитайте команды craft-agent:

craft-agent label create --name "Bug" --color "destructive"
craft-agent label create --name "Priority" --color "accent" --value-type number
craft-agent label create --name "Due Date" --color "info" --value-type date
craft-agent label create --name "Docs" --color "info" --value-type link
craft-agent label create --name "Project" --color "foreground/60"
craft-agent label create --name "Alpha" --color "info" --parent-id project
craft-agent label create --name "Beta" --color "success" --parent-id project

Прямое редактирование JSON используйте только для пакетных или ручных операций, где CLI недостаточно.

Соглашения по цветам

При создании или изменении меток придерживайтесь этих правил, если пользователь явно не попросит иначе:

1. Всегда добавляйте цвет. У каждой метки должен быть color для визуального опознавания (отображается как цветной круг).
2. Используйте согласованные цвета внутри категории. Метки-соседи (дети одного родителя) должны использовать цвета из одной семьи или диапазона оттенков, формируя цельную визуальную группу. Например, группа «Backend» может использовать зелёные/бирюзовые цвета для своих детей (API, Database), а «Frontend» — индиго/синие (React, CSS).
3. Используйте семантические цвета для семантических значений:
   • баги/ошибки → "destructive" или красные оттенки
   • функции/улучшения → "accent" или синие/индиго оттенки
   • успех/готово → "success" или зелёные оттенки
   • информация/метаданные → "info" или небесно-голубые/циановые оттенки
   • нейтральное/разное → "foreground/60" или серые оттенки

Напоминание о формате цвета: для подметок используйте кастомные объекты { "light": "#hex", "dark": "#hex" }, чтобы точно управлять цветом. Системные цвета ("accent", "info", "destructive" и т. д.) оставляйте для родительских категорий верхнего уровня.

Валидация

ВАЖНО: всегда выполняйте валидацию после создания или редактирования меток:

config_validate({ target: "labels" })

Это проверяет:

• корректный JSON и рекурсивную структуру схемы
• глобально уникальные идентификаторы во всём дереве
• корректный формат слага (строчные буквы, цифры и дефисы)
• максимальную глубину вложенности (5 уровней)

Правила автометок

Правила автометок автоматически сканируют сообщения пользователя и применяют метки с извлечёнными значениями. Настройте регулярные выражения на любой метке, чтобы запускать автоматическое помечание.

Конфигурация

Добавьте autoRules к любой метке в config.json:

{
  "id": "linear-issue",
  "name": "Linear Issue",
  "color": "purple",
  "valueType": "string",
  "autoRules": [
    {
      "pattern": "linear\\.app/[\\w-]+/issue/([A-Z]+-\\d+)",
      "valueTemplate": "$1",
      "description": "Matches Linear issue URLs"
    },
    {
      "pattern": "\\b([A-Z]{2,5}-\\d+)\\b",
      "valueTemplate": "$1",
      "description": "Matches bare issue keys like CRA-123"
    }
  ]
}

Свойства AutoLabelRule

Регулярные выражения

Правила используют регулярные выражения JavaScript с группами захвата:

{
  "pattern": "github\\.com/([\\w-]+/[\\w-]+)/pull/(\\d+)",
  "valueTemplate": "$1#$2",
  "description": "Matches GitHub PR URLs"
}

• Глобальное совпадение: флаг g всегда принудительно включается, поэтому находятся все вхождения в сообщении
• Группы захвата: $1, $2 и т. д. заменяются на совпавшие группы в valueTemplate
• Несколько совпадений: «CRA-1 and CRA-2» создаёт две записи метки на одной и той же метке
• Удаление блоков кода: содержимое внутри блоков кода с ограждением и инлайн-кода игнорируется

Нормализация значений

Извлечённые значения нормализуются на основе valueType метки:

Поведение при оценке

• Время: правила оцениваются при отправке сообщения пользователя (как новых, так и поставленных в очередь)
• Только сообщения пользователя: вывод ассистента и результаты инструментов не сканируются
• Удаление кода: блоки кода с ограждением и инлайн-код удаляются перед оценкой
• Удаление дубликатов: одна и та же метка+значение не добавляется в сессию дважды
• Ограничение совпадений: максимум 10 совпадений на сообщение (предотвращает взрывное количество меток из вставленных данных)
• Сохранение: автоматически применённые метки хранятся в сессии
• Несколько правил: оцениваются все правила метки; собираются все совпадения
• Валидация: шаблоны проверяются при сохранении конфигурации (некорректные регулярные выражения и шаблоны ReDoS отклоняются)
• Обработка ошибок: некорректные регулярные выражения пропускаются во время выполнения (записываются как предупреждения)

Полный пример

Рабочее пространство, которое автоматически помечает задачи Linear, дедлайны, контакты и бюджеты:

{
  "version": 1,
  "labels": [
    {
      "id": "linear-issue",
      "name": "Linear Issue",
      "color": "purple",
      "valueType": "string",
      "autoRules": [
        { "pattern": "linear\\.app/[\\w-]+/issue/([A-Z]+-\\d+)", "valueTemplate": "$1", "description": "Linear URLs" },
        { "pattern": "\\b([A-Z]{2,5}-\\d+)\\b", "valueTemplate": "$1", "description": "Bare issue keys" }
      ]
    },
    {
      "id": "deadline",
      "name": "Deadline",
      "color": "orange",
      "valueType": "date",
      "autoRules": [
        { "pattern": "(\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2})?)", "valueTemplate": "$1", "description": "ISO dates" }
      ]
    },
    {
      "id": "contact",
      "name": "Contact",
      "color": "blue",
      "valueType": "string",
      "autoRules": [
        { "pattern": "([\\w.+-]+@[\\w.-]+\\.[a-zA-Z]{2,})", "valueTemplate": "$1", "description": "Email addresses" }
      ]
    },
    {
      "id": "budget",
      "name": "Budget",
      "color": "green",
      "valueType": "number",
      "autoRules": [
        { "pattern": "\\$([\\d,.]+[kKmMbB]?)", "valueTemplate": "$1", "description": "Dollar amounts" }
      ]
    }
  ]
}

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

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

All Sessions (flat, total count)
Flagged      (flat, flagged count)
States       (expandable → status sub-items)
Labels       (expandable)
  ├─ Views       (expandable → view sub-items)
  ├─ Engineering (label)
  └─ Bug         (label)
────────────
Sources      (expandable → API/MCP/Local)
Skills       (flat)
────────────
Settings     (flat)

Клик по метке фильтрует список сессий. Клик по родительской метке включает сессии, отмеченные любым потомком.

Решения по дизайну

• Вложенное JSON-дерево: иерархия — это сама структура, учить соглашения не нужно
• Позиция в массиве = порядок: поле order не нужно, позиция в массиве определяет порядок отображения
• Глобально уникальные идентификаторы: простые слаги, уникальные во всём дереве
• Только цвет: метки используют цветные круги — без иконок, что сохраняет UI чистым и последовательным
• Нет категорий: метки не влияют на фильтрацию входящих/архива (для этого есть статусы)
• Нет значений по умолчанию: рабочие пространства начинаются с нулём меток
• Нет фиксированных меток: все метки полностью контролируются пользователем (можно удалить, переименовать)
• Многозначный выбор: сессии хранят labels: string[], а не одно значение
• Каскадное удаление: удаление метки удаляет её и всех потомков из сессий
• Максимальная глубина 5: предотвращает чрезмерно глубокие иерархии
• Иерархическая фильтрация: клик по родительской метке включает все сессии потомков
• Значения через разделитель ::: простое плоское строковое хранение — без изменения схемы формата сессии
• Вывод типа при разборе: парсер всегда выводит тип (дата → число → строка), valueType — только подсказка для UI
• Только дата: ISO YYYY-MM-DD — без временной части, что избегает сложности с часовыми поясами