flowchart LR
    subgraph 设备端
        A[用户自然语言指令] --> B[Gemini / Agent App]
        B --> C[AppFunctionManager]
        C --> D[系统 AppFunctions 注册表]
        D --> E[你的 App<br/>@AppFunction 函数]
        E --> F[本地数据/服务]
    end
    G[云上 MCP Server] -.网络往返.-> H[远程工具]
    B -.可选.-> G

# 1. 确认 Android Studio 版本（需要支持 API 36 的 SDK）
# 2. 确认设备的系统版本
adb shell getprop ro.build.version.sdk
# 应该输出 36 或更高，低于 36 直接放弃

# 3. 确认 AppFunctions 系统服务存在
adb shell cmd app_function help
# 能打出帮助页就说明系统服务在；报 "Can't find service: app_function" 就是设备太老或 ROM 不支持

dependencies {
    implementation("androidx.appfunctions:appfunctions:1.0.0-alpha10")
    // 项目里有 Kotlin 源码就必须加 KSP 编译器
    ksp("androidx.appfunctions:appfunctions-compiler:1.0.0-alpha10")
}

@AppFunctionSerializable(isDescribedByKDoc = true)
data class Note(
    /** 笔记的唯一 ID */
    val id: String,
    /** 笔记标题 */
    val title: String,
    /** 笔记正文 */
    val content: String,
    /** 创建时间戳（毫秒） */
    val createdAt: Long,
)

@AppFunctionSerializable(isDescribedByKDoc = true)
data class CreateNoteParams(
    /** 新笔记的标题 */
    val title: String,
    /** 新笔记的正文 */
    val content: String,
)

class NotesAppFunctions(
    private val repository: NotesRepository,
) {
    /**
     * 列出当前用户的所有笔记。
     *
     * @param appFunctionContext 由 AppFunctions 运行时提供的执行上下文
     * @return 笔记列表，按创建时间倒序
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun listNotes(
        appFunctionContext: AppFunctionContext,
    ): List<Note> = repository.getAllNotes()
        .sortedByDescending { it.createdAt }
        .map { Note(it.id, it.title, it.content, it.createdAt) }

    /**
     * 创建一条新笔记。
     *
     * @param appFunctionContext 由 AppFunctions 运行时提供的执行上下文
     * @param params 包含标题和正文
     * @return 创建成功后的完整笔记对象
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun createNote(
        appFunctionContext: AppFunctionContext,
        params: CreateNoteParams,
    ): Note {
        val note = repository.create(
            id = UUID.randomUUID().toString(),
            title = params.title,
            content = params.content,
        )
        return Note(note.id, note.title, note.content, note.createdAt)
    }
}

@AppFunctionServiceEntryPoint(
    serviceName = "NotesAppFunctionService",
    appFunctionXmlFileName = "notes_app_function_service",
)
abstract class NotesAppFunctionService : AppFunctionService() {

    override fun createAppFunctionInstance(
        appFunctionContext: AppFunctionContext,
    ): AppFunction {
        val repository = (applicationContext as NotesApplication).repository
        return NotesAppFunctions(repository)
    }
}

<?xml version="1.0" encoding="utf-8"?>
<app-function-service xmlns:android="http://schemas.android.com/apk/res/android"
    android:name=".NotesAppFunctionService"
    android:exported="true">
    <app-function android:name="listNotes" />
    <app-function android:name="createNote" />
</app-function-service>

<service
    android:name=".NotesAppFunctionService"
    android:exported="true"
    android:permission="android.permission.EXECUTE_APP_FUNCTIONS">
    <intent-filter>
        <action android:name="android.app.appfunctions.action.EXECUTE_APP_FUNCTIONS" />
    </intent-filter>
</service>

class NotesAgent(
    private val appFunctionManager: AppFunctionManager,
) {
    suspend fun listNotesFromNotesApp(): List<Note> {
        // 先确认目标 App 的某个函数是否可用
        val enabled = appFunctionManager.isAppFunctionEnabled(
            packageName = "com.example.notes",
            functionId = NotesAppFunctionsIds.listNotes, // 编译器生成的 Ids 类
        )
        if (!enabled) return emptyList()

        val request = ExecuteAppFunctionRequest.Builder(
            appFunctionId = NotesAppFunctionsIds.listNotes,
            parameters = AppFunctionSerializableParams.Builder()
                .setSerializable(EmptyParams())
                .build(),
        ).build()

        val response = appFunctionManager.executeAppFunction(request)
        return response.result.getSerializable(Note::class.java)
    }
}

@AppFunction(isEnabled = false, isDescribedByKDoc = true)
suspend fun syncNotes(
    appFunctionContext: AppFunctionContext,
): SyncResult { ... }

class NotesAppFunctionsController(
    private val appFunctionManager: AppFunctionManagerCompat,
) {
    fun onUserLoggedIn() {
        appFunctionManager.setAppFunctionEnabled(
            appFunctionId = NotesAppFunctionsIds.syncNotes,
            enabled = true,
        )
    }

    fun onUserLoggedOut() {
        appFunctionManager.setAppFunctionEnabled(
            appFunctionId = NotesAppFunctionsIds.syncNotes,
            enabled = false,
        )
    }
}

# 1. 列出设备上所有已注册的 AppFunctions，过滤你自己的包名
adb shell cmd app_function list-app-functions | grep -A 10 com.example.notes

# 2. 直接命令行执行 listNotes
adb shell cmd app_function execute-app-function \
  --package com.example.notes \
  --function 'com.example.notes.NotesAppFunctionService#listNotes' \
  --parameters '{}'

# 3. 执行 createNote，传入参数
adb shell cmd app_function execute-app-function \
  --package com.example.notes \
  --function 'com.example.notes.NotesAppFunctionService#createNote' \
  --parameters '{"createNoteParams": {"title": "买牛奶", "content": "记得买脱脂的"}}'

AppFunctionId: com.example.notes.NotesAppFunctions#listNotes
  Display name: listNotes
  Description: 列出当前用户的所有笔记。
  ...
  Result: OK

# 按包名过滤，看某个 App 暴露了哪些函数
adb shell cmd app_function list-app-functions --package com.example.notes

# 调试阶段想临时停用某个函数，验证动态启停逻辑
adb shell cmd app_function set-app-function-enabled \
  --package com.example.notes \
  --function 'com.example.notes.NotesAppFunctions#syncNotes' \
  --enabled false

adb shell aflags list | grep enable_app_functions_schema_parser

unzip -l app/build/outputs/apk/debug/app-debug.apk | grep app_functions