Настройка лейблов

Настройка лейблов

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

Рекомендуемый рабочий процесс через CLI: Используйте команды craft-agent label ... вместо прямого редактирования JSON.

• craft-agent label --help
• Справочник команд: craft-cli.md

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

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

Отсутствие значений по умолчанию (обычные лейблы)

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

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

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

Иерархические лейблы (вложенное дерево)

Лейблы образуют вложенное 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

Правила:

• ID — это простые слаг (строчные буквы, цифры и дефисы)
• ID должны быть глобально уникальными во всем дереве
• Максимальная глубина вложенности: 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

Лейблы сессий

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

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

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

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

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

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

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

Добавление лейблов

Предпочтительно использовать команды 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 и рекурсивную структуру схемы
• Глобально уникальные ID во всем дереве
• Валидный формат слага (строчные буквы, цифры и дефисы)
• Максимальную глубину вложенности (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 отклоняются)
• Обработка ошибок: Невалидные паттерны регулярных выражений пропускаются во время выполнения (логируются как предупреждения)

Семантические правила (требуется Decision Model)

Семантическое правило — это вопрос «да/нет» вместо регулярного выражения. Модель принятия решений (Jev, Настройки > AI > Модель принятия решений) отвечает на него для каждого сообщения пользователя, и лейбл применяется, когда вероятность «да» достигает порога. Регулярное выражение не может выразить «это сообщение о биллинге»; семантическое правило может.

{
  "id": "billing",
  "name": "Billing",
  "autoRules": [
    { "semantic": "Is the user asking about billing, invoices or charges?", "threshold": 0.9 }
  ]
}

• Неактивно без модели принятия решений: когда пользователь не включил ее (или отключил переключатель функции semanticLabels), семантические правила валидируются и хранятся, но никогда не оцениваются.
• Вне критического пути: правила регулярных выражений выполняются до начала хода; семантические правила выполняются в фоне, и их лейблы появляются чуть позже. Сообщения короче 20 символов ("ok", "thanks") пропускаются, как и правила, лейбл которых уже есть в сессии (без вызова модели); лейбл, который пользователь удалил, пока оценка была в процессе, не добавляется снова. Системно сгенерированные сообщения (повторы активации источника, фоновые напоминания) никогда не оцениваются.
• Ровно один вид на правило: правило содержит либо pattern, либо semantic, никогда оба (валидация отклоняет гибриды).
• Автоматизации: семантическое совпадение запускает автоматизации LabelAdd, как любое другое изменение лейбла. Именно поэтому порог по умолчанию высокий — снижайте его только для лейблов, которые не запускают ничего важного.
• Конфиденциальность: сообщение (с удаленными блоками кода, обрезанное до 8k символов) отправляется настроенному провайдеру решений; каждый вызов записывается в ~/.craft-agent/logs/decisions.jsonl без текста.
• CLI: craft-agent label auto-rule-add <id> --semantic "Is …?" [--threshold 0.9] [--value "…"]

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

Workspace, который автоматически размечает задачи 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 не требуется, позиция в массиве определяет порядок отображения
• Глобально уникальные ID: Простые слаги, уникальные во всем дереве
• Только цвет визуально: Лейблы используют цветные круги — без иконок, сохраняя интерфейс чистым и последовательным
• Нет категорий: Лейблы не влияют на фильтрацию инбокса/архива (для этого есть статусы)
• Нет значений по умолчанию: Workspaces начинаются с нулевым количеством лейблов
• Нет фиксированных лейблов: Все лейблы полностью контролируются пользователем (удаляемые, переименовываемые)
• Множественный выбор: Сессии хранят labels: string[], а не одно значение
• Каскадное удаление: Удаление лейбла удаляет его и всех потомков из сессий
• Макс. глубина 5: Предотвращает чрезмерно глубокие иерархии
• Иерархическая фильтрация: Клик по родительскому лейблу включает все сессии-потомки
• Значения через разделитель ::: Простое, плоское хранение строк — без изменений схемы формата сессии
• Вывод типа при разборе: Парсер всегда выводит (дата → число → строка), valueType — это просто подсказка для UI
• Только дата: ISO YYYY-MM-DD — без временной части, избегает сложности с часовыми поясами