一、AppFunction 核心概述

AppFunction 是 Android 16（API 36）推出的平台级能力，搭配 Jetpack 库可将应用业务逻辑封装为标准化可调用函数。其核心价值是打通本地应用与端侧大模型（如 Gemini），让大模型通过自然语言理解直接调用 App 功能，全程在设备本地运行，兼顾交互效率与数据隐私。

二、原理解析：App 能力如何暴露给大模型

整体链路可总结为：代码声明 → 编译生成元数据 → 系统全局索引 → 大模型检索匹配 → 跨进程本地调用，下面分层拆解完整流程。

2.1 整体架构分层

从应用到大模型共四层架构，各司其职：

1. 应用层：开发者通过专属注解标记需要对外暴露的函数与数据结构；
2. 编译层：KSP 注解处理器在编译阶段自动生成标准化元数据文件；
3. 系统索引层：Android 系统通过 AppSearch 统一收录、索引所有应用的 AppFunction 能力；
4. 大模型调用层：端侧大模型依托系统 API 检索函数、发起调用、接收执行结果。

2.2 步骤1：应用声明可暴露能力（开发者编码）

开发者使用框架提供的两类核心注解，完成能力语义定义，也是大模型能理解功能的基础：

• @AppFunction：标记需要对外暴露的业务方法，方法强制要求为 suspend 挂起函数，适配数据库、网络等异步耗时操作；
• @AppFunctionSerializable：标记函数入参、返回值的数据实体，规范数据结构；
• 配置 isDescribedByKDoc = true 后，代码注释会自动转为能力描述，作为大模型理解函数用途的语义依据。

示例注解使用片段：

// 数据实体注解
@AppFunctionSerializable(isDescribedByKDoc = true)
data class Note(val id: Int, val title: String, val content: String)

// 业务函数注解
@AppFunction(isDescribedByKDoc = true)
suspend fun createNote(ctx: AppFunctionContext, title: String, content: String): Note

2.3 步骤2：编译期自动生成能力元数据

项目编译时，KSP 注解处理器会自动扫描注解代码，无需手动编写接口文档、JSON Schema，自动生成两类核心文件：

1. 函数元数据 XML（appfunctions_metadata.xml）
   记录函数唯一ID、功能描述、参数名称/类型/说明、返回值结构，是标准化的“能力说明书”，简化示例：

   <function id="com.example.note/createNote">
     <description>创建一条新笔记</description>
     <parameter name="title" type="string" description="笔记标题" />
     <parameter name="content" type="string" description="笔记正文" />
     <return type="Note" />
   </function>
   

2. 系统索引辅助类：用于配合系统完成能力注册，让系统可正常扫描识别。

2.4 步骤3：系统全局收录与索引

应用安装、系统重启后，Android 系统会执行以下动作：

1. AppSearchManager 扫描设备内所有应用的 appfunctions_metadata.xml；
2. 解析元数据并统一存入系统级 AppSearch 数据库，构建设备全局函数技能库；
3. 所有暴露的函数实现全局可检索，系统也提供指令可查看设备内全部 AppFunction：

   adb shell cmd app_function list-app-functions
   

2.5 步骤4：大模型检索、决策与调用

端侧大模型结合用户自然语言指令，分四步完成函数调用，逻辑和云端 Function Calling 一致，区别在于执行端为本地应用：

1. 检索能力：大模型调用 AppSearch API，根据用户意图（如“创建笔记”）检索匹配的函数列表，获取函数ID、参数、描述等信息；
2. 智能决策：结合语义理解，筛选出最匹配当前需求的本地函数；
3. 发起调用：通过 AppFunctionManager 构造请求，跨进程调用目标应用函数，函数运行在原应用进程内，数据不离开设备；
4. 结果回传：应用执行完毕后将结果原路返回，大模型整理为自然语言回复用户。

2.6 安全机制

1. 服务需配置专属权限 BIND_APP_FUNCTION_SERVICE，仅系统可绑定；
2. 调用方必须主动申请 EXECUTE_APP_FUNCTION 执行权限；
3. 建议仅暴露通用非敏感能力，禁止直接开放支付、隐私数据等高风险接口。

三、实战 Showcase：笔记应用完整接入 AppFunction

基于上述原理，以笔记 App 为例，实现「创建笔记、查询所有笔记」两个能力，完成从依赖配置、代码编写、服务注册到调用的全流程演示。

3.1 环境与依赖配置

版本要求

• 运行系统：Android 16（API 36）及以上
• 编译工具：AGP 8.0+
• 开发语言：Kotlin

Module 级 build.gradle.kts 依赖

plugins {
    kotlin("kapt")
    id("com.google.devtools.ksp")
}

dependencies {
    // AppFunction 核心API
    implementation("androidx.appfunctions:appfunctions:1.0.0-alpha08")
    // Service 服务依赖
    implementation("androidx.appfunctions:appfunctions-service:1.0.0-alpha08")
    // 注解处理器
    ksp("androidx.appfunctions:appfunctions-compiler:1.0.0-alpha08")
}

同步 Gradle 后等待依赖拉取完成。

3.2 步骤1：定义可序列化数据实体

使用 @AppFunctionSerializable 标记笔记实体，用于函数参数与结果传递：

import androidx.appfunctions.AppFunctionSerializable

/**
 * 笔记实体类
 * @param id 笔记唯一标识
 * @param title 笔记标题
 * @param content 笔记正文
 */
@AppFunctionSerializable(isDescribedByKDoc = true)
data class Note(
    val id: Int,
    val title: String,
    val content: String
)

3.3 步骤2：模拟数据仓库

简易实现内存数据层，模拟数据库增查逻辑：

class NoteRepository {
    private val noteList = mutableListOf<Note>()
    private var autoId = 1

    // 查询全部笔记
    suspend fun getAllNotes(): List<Note> {
        return noteList.toList()
    }

    // 创建新笔记
    suspend fun createNote(title: String, content: String): Note {
        val newNote = Note(autoId++, title, content)
        noteList.add(newNote)
        return newNote
    }
}

3.4 步骤3：编写对外暴露的 AppFunction

使用 @AppFunction 注解标记业务方法，统一使用协程处理异步逻辑，并增加参数校验与标准异常：

import androidx.appfunctions.AppFunction
import androidx.appfunctions.AppFunctionContext
import androidx.appfunctions.AppFunctionInvalidArgumentException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

class NoteFunctionManager(
    private val repository: NoteRepository
) {
    /**
     * 查询当前所有笔记
     * @param appFunctionContext 函数运行上下文
     * @return 笔记列表
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun queryAllNotes(
        appFunctionContext: AppFunctionContext
    ): List<Note> {
        return withContext(Dispatchers.IO) {
            repository.getAllNotes()
        }
    }

    /**
     * 新建一条笔记
     * @param appFunctionContext 函数运行上下文
     * @param title 笔记标题
     * @param content 笔记内容
     * @return 新建完成的笔记对象
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun addNewNote(
        appFunctionContext: AppFunctionContext,
        title: String,
        content: String
    ): Note {
        // 入参校验，抛出框架标准异常
        if (title.isBlank() || content.isBlank()) {
            throw AppFunctionInvalidArgumentException("标题和内容不能为空")
        }
        return withContext(Dispatchers.IO) {
            repository.createNote(title, content)
        }
    }
}

3.5 步骤4：实现 AppFunction 服务入口

继承 AppFunctionService，注册自定义函数类，作为系统调用的唯一入口：

import androidx.appfunctions.service.AppFunctionService
import androidx.appfunctions.service.AppFunctionServiceRegistry

class NoteAppFunctionService : AppFunctionService() {
    private val noteRepo = NoteRepository()
    private val functionManager = NoteFunctionManager(noteRepo)

    override fun registerAppFunctions(registry: AppFunctionServiceRegistry) {
        // 自动注册类中所有 @AppFunction 标记的方法
        registry.register(functionManager)
    }
}

3.6 步骤5：清单文件注册服务

在 AndroidManifest.xml 中声明服务，配置过滤器与安全权限：

<!-- 注册 AppFunction 服务 -->
<service
    android:name=".NoteAppFunctionService"
    android:exported="true"
    android:permission="com.google.android.appfunctions.permission.BIND_APP_FUNCTION_SERVICE">
    <intent-filter>
        <action android:name="androidx.appfunctions.service.action.APP_FUNCTION_SERVICE" />
    </intent-filter>
</service>

3.7 步骤6：调用方代码（大模型/第三方应用视角）

调用方需先声明执行权限：

<uses-permission android:name="com.google.android.appfunctions.permission.EXECUTE_APP_FUNCTION" />

通过 AppFunctionManager 调用目标函数，模拟大模型执行逻辑：

import android.content.Context
import androidx.appfunctions.AppFunctionManager
import androidx.appfunctions.ExecuteAppFunctionRequest
import kotlinx.coroutines.CancellationSignal

suspend fun invokeAddNoteFunction(context: Context) {
    // 1. 获取系统管理器
    val functionManager = context.getSystemService(AppFunctionManager::class.java)

    // 2. 构造调用请求（包名 + 函数唯一ID）
    val request = ExecuteAppFunctionRequest.Builder(
        "com.example.note",
        "com.example.note/addNewNote"
    )
        .putParameter("title", "工作日志")
        .putParameter("content", "对接Android AppFunction能力")
        .build()

    // 3. 执行调用
    val cancelSignal = CancellationSignal()
    val response = functionManager.executeAppFunction(
        request,
        Runnable::run,
        cancelSignal
    )

    // 4. 解析返回结果
    val result: Note = response.getResult(Note::class.java)
    println("创建笔记成功：$result")
}

四、开发最佳实践

1. 参数强校验：所有对外函数必须做入参校验，优先使用框架标准异常，便于大模型识别错误；
2. 控制暴露范围：仅开放通用业务能力，严禁暴露隐私、支付、设备管控等高风险接口；
3. 完善注释文档：依托 KDoc 补充函数、参数语义描述，保证大模型精准理解能力用途；
4. 统一异步处理：耗时操作全部使用协程 + suspend 函数，避免阻塞主线程；
5. 版本兼容：当前 AppFunction 处于 Alpha 阶段，API 存在变动风险，线上项目建议增加系统版本判断。

五、总结

AppFunction 本质是 Android 为端侧 AI 生态打造的标准化本地工具调用方案。依靠「注解声明+编译生成元数据+系统全局索引」的链路，让本地应用能力被大模型自动发现、理解并调用，彻底摆脱模拟界面操作的传统交互方式。

从开发角度，该方案接入成本低、侵入性小，只需少量注解和服务配置即可完成能力对外开放；随着 Android 16 逐步普及，AppFunction 会成为端侧大模型与原生应用联动的主流技术，适合提前预研落地。