讓AI智能體理解螢幕：Jetpack Compose Semantics設計實踐指南

讓AI智能體理解螢幕：Jetpack Compose Semantics設計實踐指南

前言

要讓Jetpack Compose中的AI智能體和測試自動化工具精準理解「這個按鈕是做什麼的」，Semantics的合理設計是關鍵。

Compose內部擁有「Semantics Tree」，作為無障礙存取、UI測試和自動操作AI（Appium/UIAutomator/MCP等）參考的語義結構發揮作用。這相當於Web中的ARIA和DOM。

Semantics的主要屬性

contentDescription

為僅有圖示的按鈕賦予意義的最基本屬性。

IconButton(
    onClick = onDelete,
    modifier = Modifier.semantics {
        contentDescription = "刪除"
    }
) {
    Icon(Icons.Default.Delete, contentDescription = null)
}

AI和無障礙端將其識別為「刪除按鈕·可點擊·Button角色」。

role

向自訂UI明確指定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歸納為一個含義

將圖示、文字、Badge等複雜構成作為一個按鈕展示給AI時，使用clearAndSetSemantics。

Modifier.clearAndSetSemantics {
    contentDescription = "將商品加入購物車"
    role = Role.Button
}

可忽略內部巢狀結構和圖示群組，只將含義傳遞給AI。

Semantics設計能實現的功能

自動化操作的穩定化

有了testTag，無需座標或OCR即可實現穩定操作。UI重新設計後，只要testTag保持不變，自動化就不會中斷。多語言支援也會更加健壯。

降低Token使用量

僅依賴螢幕截圖時，圖像分析需要大量Token，但使用Semantics Tree可作為輕量結構化資料處理。

[
  {"type": "Button", "label": "登入"},
  {"type": "TextField", "label": "電子郵件"},
  {"type": "TextField", "label": "密碼"}
]

在長時間自動操作和大規模螢幕分析中尤為有效，還有助於抑制context overflow。

AI的狀態理解

透過stateDescription，AI能推斷螢幕當前狀態，從而做出「現在是暫停狀態，所以按播放按鈕」等判斷。可以讓AI將螢幕理解為狀態機。

MCP整合中的結構化分析

透過MCP Server取得Semantics Tree並傳遞給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傳達「這是什麼按鈕·按下去會發生什麼·現在是什麼狀態」，而不是顏色、位置、大小——這就是對AI友好的UI設計的核心。