HarmonyOS NEXT 技术实践-基于意图框架服务实现智能分发

在智能设备的交互中，如何准确理解并及时响应用户需求，成为提升用户体验的关键。HarmonyOS Next 的意图框架服务（Intents Kit）为这一目标提供了强大的技术支持。本文将通过一个项目实现的示例，展示如何使用意图框架服务，实现意图共享与调用的功能，推动智慧分发的应用。

在这里插入图片描述

一、项目背景与目标

1. 意图框架介绍

Intents Kit（意图框架服务）是HarmonyOS级的意图标准体系，意图连接了应用/元服务内的业务功能。意图框架能帮开发者将应用/元服务内的业务功能，智能分发到各系统入口，这个过程即智慧分发。其中系统入口包括：小艺对话、小艺搜索、小艺建议等。

系统入口、意图框架、鸿蒙生态的关系如下：

在这里插入图片描述
利用HarmonyOS的大模型、多维设备感知等AI能力，准确且及时地获取到用户显性、潜在意图，从而实现个性化、多模态、精准的智慧分发。

HarmonyOS、应用/元服务的交互中，意图运行方式分为意图调用和意图共享：

在这里插入图片描述

方式	发起者	定义
意图共享	应用/元服务	指应用/元服务主动向HarmonyOS共享意图，可用于HarmonyOS构建本地内容索引、学习用户的行为规律，以支持本地搜索和主动建议。意图共享包含动作和实体两个部分。动作支持完成时和将来时两种机制： - 完成时：用户意图已执行，共享的数据可用于本地搜索和系统建议。- 将来时：意图是基于用户行为预测的，共享的数据可用于本地搜索。意图框架还支持开发者向系统进行辅助实体共享，例如位置信息等，用于场景推荐和其他智慧分发功能的增强。
意图调用	HarmonyOS	指HarmonyOS主动调用应用/元服务的功能。用户在系统入口输入信息或者系统主动推荐后，系统可向应用/元服务发起意图调用，例如播放音乐、查看旅游攻略、搜索视频等。

2. 项目目标

本项目的目标是展示如何在HarmonyOS中利用意图框架服务实现智能分发，准确匹配用户需求。通过@kit.IntentsKit进行意图共享，使用@kit.AbilityKit的InsightIntentExecutor实现意图调用，用户的需求将能够被智能解析并传递到相关服务或应用中。

具体来说，本示例包括两个主要部分：

意图共享：通过意图共享机制，将用户的需求从一个模块传递到其他模块，实现跨应用的需求匹配。
意图调用：在共享意图之后，通过意图调用机制，将数据回传至调用端，并根据需求执行相应操作。

本示例仅支持标准系统上运行，支持设备：华为手机、华为平板。

HarmonyOS系统：HarmonyOS NEXT Developer
Beta1及以上。 DevEco Studio版本：DevEco Studio NEXT Developer Beta1及以上。
HarmonyOS SDK版本：HarmonyOS NEXT Developer Beta1 SDK及以上。

二、项目实现

1. 项目目录结构

本项目的目录结构如下所示：

entry/src/main/
| --- ets
|     | --- entryability
|     |     | --- EntryAbility.ets                                  // 共享界面Ability
|     |     | --- InsightIntentExecutorImpl.ets                     // 意图调用逻辑
|     | --- pages
|     |     | --- Index.ets                                         // 共享界面UI
|     | --- utils
|     |     | --- ...                                               // 工具类

主要功能分布如下：

EntryAbility.ets：负责展示意图共享界面。
InsightIntentExecutorImpl.ets：处理意图调用的逻辑。
Index.ets：显示共享界面的UI，包含获取和展示示范数据的功能。

2. 意图共享实现

意图共享是实现智能分发的基础。我们通过@kit.IntentsKit来共享数据，确保用户需求能够跨应用或模块传递。

获取示范数据：用户点击获取insightIntent示例数据后，示范数据将展示在共享界面上方的输入框内。

@kit.IntentsKit.getInsightIntents().then((data) => {
    // 处理获取到的示范数据
    updateUI(data);
});

共享数据：用户点击“分享意图”按钮后，数据将通过@kit.IntentsKit.shareIntent()共享，结果将展示在共享界面的下方结果栏内。

@kit.IntentsKit.shareIntent(intentData).then((result) => {
    // 显示共享结果
    updateResult(result);
});

3. 意图调用实现

意图调用功能允许在共享的意图处理后，返回调用端并执行相应操作。通过使用小艺建议的模板卡片，我们可以展示共享的意图，并通过点击卡片触发相应的跳转和操作。

小艺建议展示模板卡片：我们使用音乐类模板卡片来展示共享意图。在点击卡片后，触发与共享界面跳转并执行意图调用逻辑。

@kit.AbilityKit.InsightIntentExecutor.execute(intent).then((result) => {
    // 处理执行结果，并展示在共享界面下方
    updateResult(result);
});

SID管理：项目中还实现了SID的获取和刷新功能，确保每次操作都能获取最新的会话标识。

@kit.AbilityKit.getSid().then((sid) => {
    updateSid(sid);
});

@kit.AbilityKit.getSidRenew().then((newSid) => {
    updateSid(newSid);
});

4. 实现结果

意图共享界面展示：用户可以查看共享意图的数据，并通过“获取示范数据”和“分享意图”按钮进行交互，数据将在共享界面的输入框和结果栏中显示。
意图调用逻辑展示：点击小艺建议模板卡片后，意图将被调用并返回结果，展示在共享界面的结果栏中。用户可以通过点击“获取SID”或“刷新SID”来管理会话状态。

三、核心代码解析

接下来，我们详细解析**InsightIntentExecutorImpl.ets**中的核心代码，重点展示如何通过InsightIntentExecutor类实现意图的执行与分发。

1. 引入模块和定义常量

首先，引入所需的模块：

import { Logger } from '../utils/Logger';
import { insightIntent, InsightIntentExecutor } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import type { BusinessError } from '@kit.BasicServicesKit';

Logger：用于记录执行日志，帮助开发者调试和跟踪意图执行过程。
insightIntent, InsightIntentExecutor：InsightIntentExecutor是基类，提供了意图执行的接口方法。insightIntent包含了定义意图及其执行结果的类型。
window：window.WindowStage用于管理UI窗口，允许我们在界面中展示意图的执行结果。
BusinessError：用于描述在意图执行过程中可能遇到的业务错误。

接着，我们定义常量：

private static readonly PLAY_MUSIC = 'PlayMusic';
private static readonly PLAY_MUSIC_LIST = 'PlayMusicList';

这两个常量分别代表两个不同的意图：播放单曲（PlayMusic）和播放音乐列表（PlayMusicList）。这些常量将用于后续的意图分发和执行。

2. 重写核心方法

下面，重写onExecuteInUIAbilityForegroundMode方法：

onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage):
  Promise<insightIntent.ExecuteResult> {
  Logger.info(TAG, `onExecuteInUIAbilityForegroundMode name: ${name}, param: ${JSON.stringify(param)}`);
  
  switch (name) {
    case InsightIntentExecutorImpl.PLAY_MUSIC:
      return this.playMusic(param, pageLoader);
    case InsightIntentExecutorImpl.PLAY_MUSIC_LIST:
      return this.playMusicList(param, pageLoader);
    default:
      break;
  }

  return Promise.resolve({
    code: -1,
    result: {
      message: 'unknown intent'
    }
  } as insightIntent.ExecuteResult)
}

onExecuteInUIAbilityForegroundMode：这是InsightIntentExecutor中的核心方法，负责根据意图名称（name）执行对应的操作，并返回执行结果。此方法首先记录日志，展示接收到的意图名称和参数。然后，根据意图名称分发处理逻辑。
播放音乐：如果接收到的意图是PlayMusic，则调用playMusic方法，执行播放音乐的逻辑。
播放音乐列表：如果接收到的意图是PlayMusicList，则调用playMusicList方法，执行播放音乐列表的逻辑。
未知意图：如果接收到的意图未知，返回一个错误信息。

3. 播放音乐方法实现

playMusic方法实现

private playMusic(param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {
  // 处理播放音乐的逻辑
  Logger.info(TAG, `Playing music with parameters: ${JSON.stringify(param)}`);
  
  // 假设这是一个简单的模拟逻辑，实际中可能调用外部音乐播放API
  return Promise.resolve({
    code: 0,
    result: {
      message: 'Music is playing successfully!'
    }
  });
}

playMusic：此方法模拟播放音乐的操作。在实际应用中，您可以根据传入的参数（如歌曲名称、歌手等）调用外部API来实现播放。这里，我们简单地记录日志并返回成功的结果。

playMusicList方法实现：

private playMusicList(param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {
  // 处理播放音乐列表的逻辑
  Logger.info(TAG, `Playing music list with parameters: ${JSON.stringify(param)}`);
  
  return Promise.resolve({
    code: 0,
    result: {
      message: 'Music list is playing successfully!'
    }
  });
}

playMusicList：与playMusic类似，但它是用于处理音乐列表播放的逻辑。在实际应用中，您可以将多个歌曲信息传递给该方法并调用相应的播放服务。

4. 错误处理

return Promise.resolve({
  code: -1,
  result: {
    message: 'unknown intent'
  }
} as insightIntent.ExecuteResult);

如果接收到一个未知的意图，该方法将返回一个错误信息，表示无法识别该意图。

四、效果预览

1. 意图共享

共享界面展示：

在这里插入图片描述
按获取insightIntents获取insightIntent示例数据，获取的示范数据将显示在共享界面上方输入框内。

在这里插入图片描述

按shareIntent进行数据共享，并在共享界面下方的结果栏内获取意图共享结果。

在这里插入图片描述

2. 意图调用

待共享的意图完成处理后，将会在小艺建议的卡片内展示共享的意图，点击展示的对应卡片，执行意图调用逻辑。

使用小艺建议模板卡片实现意图调用

小艺建议展示模板卡片，此项目内使用音乐类模板卡片。

在这里插入图片描述

点击模板卡片，按照意图注册配置内逻辑，执行对应跳转。此项目内跳转至共享界面，并在共享界面下方结果栏内展示意图调用回传参数

在这里插入图片描述

3. SID获取

点击getSid获取SID，并在结果栏内展示（优先获取缓存）。

在这里插入图片描述

点击getSidRenew强制获取新的SID，并在结果栏内展示。

在这里插入图片描述

五、总结

通过本项目，我们展示了如何利用HarmonyOS的意图框架服务（Intents Kit）实现智能分发功能，精准理解并响应用户需求。通过意图共享和调用机制，用户的需求得以在不同应用和模块之间流转，进而提供更加个性化、智能化的服务。这种基于AI和系统感知的智慧分发，极大提升了用户交互体验，并为开发者提供了更加灵活和高效的应用开发方式。

通过本示例，开发者可以学习到如何在实际项目中使用意图框架服务，并将其应用于自己的HarmonyOS应用中，打造更加智能、个性化的用户体验。