夜雨聆风一、AppFunction 核心概述
AppFunction 是 Android 16（API 36）推出的平台级能力，搭配 Jetpack 库可将应用业务逻辑封装为标准化可调用函数。其核心价值是打通本地应用与端侧大模型（如 Gemini），让大模型通过自然语言理解直接调用 App 功能，全程在设备本地运行，兼顾交互效率与数据隐私。
二、原理解析：App 能力如何暴露给大模型
整体链路可总结为：代码声明 → 编译生成元数据 → 系统全局索引 → 大模型检索匹配 → 跨进程本地调用，下面分层拆解完整流程。
2.1 整体架构分层
从应用到大模型共四层架构，各司其职：
应用层：开发者通过专属注解标记需要对外暴露的函数与数据结构； 编译层：KSP 注解处理器在编译阶段自动生成标准化元数据文件； 系统索引层：Android 系统通过 AppSearch 统一收录、索引所有应用的 AppFunction 能力； 大模型调用层：端侧大模型依托系统 API 检索函数、发起调用、接收执行结果。
2.2 步骤1：应用声明可暴露能力（开发者编码）
开发者使用框架提供的两类核心注解，完成能力语义定义，也是大模型能理解功能的基础：
@AppFunction：标记需要对外暴露的业务方法，方法强制要求为suspend挂起函数，适配数据库、网络等异步耗时操作；@AppFunctionSerializable：标记函数入参、返回值的数据实体，规范数据结构；配置 isDescribedByKDoc = true后，代码注释会自动转为能力描述，作为大模型理解函数用途的语义依据。
示例注解使用片段：
// 数据实体注解@AppFunctionSerializable(isDescribedByKDoc = true)dataclassNote(val id: Int, val title: String, val content: String)// 业务函数注解@AppFunction(isDescribedByKDoc = true)suspendfuncreateNote(ctx: AppFunctionContext, title: String, content: String): Note2.3 步骤2：编译期自动生成能力元数据
项目编译时，KSP 注解处理器会自动扫描注解代码，无需手动编写接口文档、JSON Schema，自动生成两类核心文件：
函数元数据 XML（ appfunctions_metadata.xml）记录函数唯一ID、功能描述、参数名称/类型/说明、返回值结构，是标准化的“能力说明书”，简化示例：<functionid="com.example.note/createNote"><description>创建一条新笔记</description><parametername="title"type="string"description="笔记标题" /><parametername="content"type="string"description="笔记正文" /><returntype="Note" /></function>系统索引辅助类：用于配合系统完成能力注册，让系统可正常扫描识别。
2.4 步骤3：系统全局收录与索引
应用安装、系统重启后，Android 系统会执行以下动作：
AppSearchManager扫描设备内所有应用的appfunctions_metadata.xml；解析元数据并统一存入系统级 AppSearch 数据库，构建设备全局函数技能库； 所有暴露的函数实现全局可检索，系统也提供指令可查看设备内全部 AppFunction： adb shell cmd app_function list-app-functions
2.5 步骤4：大模型检索、决策与调用
端侧大模型结合用户自然语言指令，分四步完成函数调用，逻辑和云端 Function Calling 一致，区别在于执行端为本地应用：
检索能力：大模型调用 AppSearch API，根据用户意图（如“创建笔记”）检索匹配的函数列表，获取函数ID、参数、描述等信息； 智能决策：结合语义理解，筛选出最匹配当前需求的本地函数； 发起调用：通过 AppFunctionManager构造请求，跨进程调用目标应用函数，函数运行在原应用进程内，数据不离开设备；结果回传：应用执行完毕后将结果原路返回，大模型整理为自然语言回复用户。
2.6 安全机制
服务需配置专属权限 BIND_APP_FUNCTION_SERVICE，仅系统可绑定；调用方必须主动申请 EXECUTE_APP_FUNCTION执行权限；建议仅暴露通用非敏感能力，禁止直接开放支付、隐私数据等高风险接口。
三、实战 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)dataclassNote(val id: Int,val title: String,val content: String)3.3 步骤2：模拟数据仓库
简易实现内存数据层，模拟数据库增查逻辑：
classNoteRepository{privateval noteList = mutableListOf<Note>()privatevar autoId = 1// 查询全部笔记suspendfungetAllNotes(): List<Note> {return noteList.toList() }// 创建新笔记suspendfuncreateNote(title: String, content: String): Note {val newNote = Note(autoId++, title, content) noteList.add(newNote)return newNote }}3.4 步骤3：编写对外暴露的 AppFunction
使用 @AppFunction 注解标记业务方法，统一使用协程处理异步逻辑，并增加参数校验与标准异常：
import androidx.appfunctions.AppFunctionimport androidx.appfunctions.AppFunctionContextimport androidx.appfunctions.AppFunctionInvalidArgumentExceptionimport kotlinx.coroutines.Dispatchersimport kotlinx.coroutines.withContextclassNoteFunctionManager(privateval repository: NoteRepository) {/** * 查询当前所有笔记 * @param appFunctionContext 函数运行上下文 * @return 笔记列表 */@AppFunction(isDescribedByKDoc = true)suspendfunqueryAllNotes( appFunctionContext: AppFunctionContext ): List<Note> {return withContext(Dispatchers.IO) { repository.getAllNotes() } }/** * 新建一条笔记 * @param appFunctionContext 函数运行上下文 * @param title 笔记标题 * @param content 笔记内容 * @return 新建完成的笔记对象 */@AppFunction(isDescribedByKDoc = true)suspendfunaddNewNote( 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.AppFunctionServiceimport androidx.appfunctions.service.AppFunctionServiceRegistryclassNoteAppFunctionService : AppFunctionService() {privateval noteRepo = NoteRepository()privateval functionManager = NoteFunctionManager(noteRepo)overridefunregisterAppFunctions(registry: AppFunctionServiceRegistry) {// 自动注册类中所有 @AppFunction 标记的方法 registry.register(functionManager) }}3.6 步骤5：清单文件注册服务
在 AndroidManifest.xml 中声明服务，配置过滤器与安全权限：
<!-- 注册 AppFunction 服务 --><serviceandroid:name=".NoteAppFunctionService"android:exported="true"android:permission="com.google.android.appfunctions.permission.BIND_APP_FUNCTION_SERVICE"><intent-filter><actionandroid:name="androidx.appfunctions.service.action.APP_FUNCTION_SERVICE" /></intent-filter></service>3.7 步骤6：调用方代码（大模型/第三方应用视角）
调用方需先声明执行权限：
<uses-permissionandroid:name="com.google.android.appfunctions.permission.EXECUTE_APP_FUNCTION" />通过 AppFunctionManager 调用目标函数，模拟大模型执行逻辑：
import android.content.Contextimport androidx.appfunctions.AppFunctionManagerimport androidx.appfunctions.ExecuteAppFunctionRequestimport kotlinx.coroutines.CancellationSignalsuspendfuninvokeAddNoteFunction(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")}四、开发最佳实践
参数强校验：所有对外函数必须做入参校验，优先使用框架标准异常，便于大模型识别错误； 控制暴露范围：仅开放通用业务能力，严禁暴露隐私、支付、设备管控等高风险接口； 完善注释文档：依托 KDoc 补充函数、参数语义描述，保证大模型精准理解能力用途； 统一异步处理：耗时操作全部使用协程 + suspend函数，避免阻塞主线程；版本兼容：当前 AppFunction 处于 Alpha 阶段，API 存在变动风险，线上项目建议增加系统版本判断。
五、总结
AppFunction 本质是 Android 为端侧 AI 生态打造的标准化本地工具调用方案。依靠「注解声明+编译生成元数据+系统全局索引」的链路，让本地应用能力被大模型自动发现、理解并调用，彻底摆脱模拟界面操作的传统交互方式。
从开发角度，该方案接入成本低、侵入性小，只需少量注解和服务配置即可完成能力对外开放；随着 Android 16 逐步普及，AppFunction 会成为端侧大模型与原生应用联动的主流技术，适合提前预研落地。
-- END --
推荐阅读
