Як змусити AI-агентів розуміти екран: Практичний посібник із проектування Semantics у Jetpack Compose

Як змусити AI-агентів розуміти екран: Практичний посібник із проектування Semantics у Jetpack Compose

Вступ

Щоб AI-агенти та інструменти автоматизації тестів у Jetpack Compose точно розуміли "що робить ця кнопка", ключем є правильне проектування Semantics.

Compose внутрішньо має "Semantics Tree", що функціонує як семантична структура, на яку посилаються доступність, UI-тести та AI автоматичної операції (наприклад, Appium/UIAutomator/MCP). Це еквівалент ARIA і DOM у вебі.

Основні атрибути Semantics

contentDescription

Найбільш базовий атрибут для надання значення кнопкам, що містять лише іконки.

IconButton(
    onClick = onDelete,
    modifier = Modifier.semantics {
        contentDescription = "Видалити"
    }
) {
    Icon(Icons.Default.Delete, contentDescription = null)
}

AI і доступність розпізнають це як "кнопка Видалити · клікабельна · роль Button".

role

Чітко вказує тип UI для кастомного компонента. Простий Box(clickable) буде "щось клікабельне", але додавання role прояснює значення: Button, Switch, Checkbox, Tab тощо.

Modifier.semantics {
    role = Role.Button
}

stateDescription

Повідомляє AI про поточний стан UI.

Modifier.semantics {
    stateDescription =
        if (subscribed) "Підписано"
        else "Не підписано"
}

testTag

Найважливіший ідентифікатор для MCP, Appium та автоматичних UI-агентів. Забезпечує стабільну ідентифікацію, що не залежить від координат, OCR або змін тексту.

Modifier.testTag("login_button")

Налаштування для інтеграції з UIAutomator

Compose не створює безпосередньо ієрархію View, тому UIAutomator може не бачити testTag. Це вирішується додаванням наступного до кореня:

Scaffold(
    modifier = Modifier.semantics {
        testTagsAsResourceId = true
    }
)

testTag розпізнаватиметься як resource-id і може бути отриманий безпосередньо з UIAutomator.

Патерн реалізації, найбільш зрозумілий для AI

Найкраща практика — комбінувати кілька атрибутів.

Button(
    onClick = login,
    modifier = Modifier
        .testTag("login_button")
        .semantics {
            contentDescription = "Увійти"
            role = Role.Button
        }
) {
    Text("Увійти")
}

Об'єднання складного UI в єдине значення

Щоб показати AI складну комбінацію іконок, тексту та Badge як одну кнопку, використовується clearAndSetSemantics.

Modifier.clearAndSetSemantics {
    contentDescription = "Додати товар у кошик"
    role = Role.Button
}

Внутрішня вкладена структура та групи іконок можуть бути проігноровані, передаючи AI лише значення.

Що можна досягти проектуванням Semantics

Стабілізація автоматизації

За наявності testTag стабільна операція можлива без координат або OCR. Навіть після редизайну UI автоматизація не зламається, поки testTag залишається тим самим. Підтримка кількох мов також стає міцнішою.

Зменшення кількості токенів

При залежності лише від скриншотів аналіз зображень вимагає великої кількості токенів, але з Semantics Tree можна обробляти як легкі структуровані дані.

[
  {"type": "Button", "label": "Увійти"},
  {"type": "TextField", "label": "Email"},
  {"type": "TextField", "label": "Пароль"}
]

Особливо ефективно при тривалих автоматичних операціях та великомасштабному аналізі екранів, а також сприяє запобіганню context overflow.

Розуміння стану AI

Завдяки stateDescription AI може оцінити поточний стан екрана і приймати рішення на зразок "зараз на паузі, тому натисну кнопку відтворення". Дозволяє розуміти екран як машину станів.

Структурований аналіз в інтеграції MCP

Отримуючи Semantics Tree через MCP Server і передаючи його LLM Agent, стає можливим розуміння значення всього екрана, оцінка кандидатів для наступної операції та аналіз переходів між станами.

Compose UI → Semantics Tree → MCP Server → LLM Agent

Підсумок використання атрибутів Semantics

Висновок

Compose дозволяє розділяти "вигляд" і "значення". Суть проектування Semantics полягає у здатності незалежно проектувати UI для людини і семантичну структуру для AI.

Якщо ви збираєтесь використовувати AI-агентів, MCP, UIAutomator та автоматичні E2E-тести, наступна стандартизація для кожного компонента забезпечує високу рентабельність інвестицій:

Modifier
    .testTag(...)
    .semantics {
        contentDescription = ...
        role = ...
    }

Передавати "що це за кнопка · що відбувається при натисканні · який зараз стан" через Semantics замість кольору, позиції та розміру — це і є суть UI-дизайну, орієнтованого на AI.