aiagent_ohos

pub package
HarmonyOS 平台专用 · Flutter 3.35.8-ohos+

基于 HarmonyOS 小艺智能体（AgentFrameworkKit）的 Flutter 插件，通过封装 FunctionComponent，在 Flutter 应用中嵌入原生智能体按钮，点击即可唤起智能体对话。

功能特性

  • 原生嵌入：通过 PlatformView 嵌入 HarmonyOS 原生 AI Agent 按钮组件
  • 可用性检测：isAgentSupport(agentId) 在展示前判断当前设备/智能体是否可用
  • 事件回调：支持智能体对话框打开、关闭及错误回调
  • 灵活配置：自定义按钮标题、默认问候语、渐变色、阴影等

前置条件

兼容性

在以下环境中已测试通过：

项目 版本
Flutter 3.35.8-ohos-0.0.2
Dart 3.9.2
HarmonyOS SDK 5.1.0(18)
IDE DevEco Studio 6.0.2 Release
设备 ROM 6.0.0.130 SP15

建议使用相同或相近版本；其他版本可能存在 API 差异，需自行验证。仅支持 HarmonyOS 平台，其他平台不会加载原生组件。

安装

在项目 pubspec.yaml 中添加依赖，任选其一：

方式一：Git 引入（推荐）

dependencies:
  aiagent_ohos:
    git:
      url: https://gitcode.com/oh-flutter/aiagent_ohos
      ref: main   # 或指定 tag，如 ref: v0.0.1

方式二：本地路径

dependencies:
  aiagent_ohos:
    path: ../   # 插件所在目录相对路径

方式三：pub 版本（发布到 pub.dev 后可用）

dependencies:
  aiagent_ohos: ^0.0.1

然后执行：

flutter pub get

快速开始

1. 基础用法

在需要展示智能体的页面中引入并配置 AiAgentView：

import 'package:aiagent_ohos/aiagent_ohos.dart';

// 在 Widget 树中使用
SizedBox(
  width: 130,
  height: 40,
  child: AiAgentView(
    options: AiAgentOptions(
      agentId: 'your_agent_id',  // 替换为你的智能体 ID
      title: '智能助手',
      queryText: '你好，有什么可以帮您的？',
    ),
    onAgentDialogOpened: () => debugPrint('对话框已打开'),
    onAgentDialogClosed: () => debugPrint('对话框已关闭'),
    onError: (error) => debugPrint('错误: $error'),
  ),
)

2. 先检查再展示（推荐）

在展示智能体前，建议先调用 isAgentSupport 判断当前环境是否支持：

final plugin = AiagentOhos();

Future<void> checkAndShow() async {
  bool isSupported = await plugin.isAgentSupport('your_agent_id');
  if (isSupported) {
    // 显示 AiAgentView
  } else {
    // 提示用户当前不支持或隐藏入口
  }
}

API 文档

AiAgentOptions

参数 类型 必填 默认值 说明
agentId String 是 - 智能体唯一标识，从华为开发者平台获取
title String 否 '智能助手' 按钮显示文字
queryText String 否 '你好' 点击后发送给智能体的初始问题
isShowShadow bool 否 false 是否显示阴影
titleColors List<String> 否 ['#1AD0F1', '#FFA4E5'] 标题渐变色（如 2 个颜色）

AiAgentView

参数 类型 必填 说明
options AiAgentOptions 是 智能体配置
onAgentDialogOpened VoidCallback? 否 对话框打开时回调
onAgentDialogClosed VoidCallback? 否 对话框关闭时回调
onError ValueChanged<String>? 否 发生错误时回调（如参数错误、网络等）

AiagentOhos 工具类

方法 返回值 说明
getPlatformVersion() Future<String?> 获取平台版本信息
isAgentSupport(agentId) Future<bool> 检查指定 agentId 在当前环境是否可用

使用示例

示例 1：带可用性检查的页面

class AgentPage extends StatefulWidget {
  @override
  State<AgentPage> createState() => _AgentPageState();
}

class _AgentPageState extends State<AgentPage> {
  final _plugin = AiagentOhos();
  bool _isSupported = false;
  bool _loading = true;

  @override
  void initState() {
    super.initState();
    _checkSupport();
  }

  Future<void> _checkSupport() async {
    final supported = await _plugin.isAgentSupport('your_agent_id');
    if (mounted) setState(() {
      _isSupported = supported;
      _loading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    if (_loading) return CircularProgressIndicator();
    if (!_isSupported) return Text('当前设备不支持智能体');
    return SizedBox(
      width: 130,
      height: 40,
      child: AiAgentView(
        options: AiAgentOptions(
          agentId: 'your_agent_id',
          title: '智能客服',
          queryText: '您好，有什么可以帮您的？',
        ),
      ),
    );
  }
}

示例 2：多智能体切换

final List<AiAgentOptions> _agents = [
  AiAgentOptions(agentId: 'id_1', title: '育儿助手', queryText: '您好，我是育儿助手'),
  AiAgentOptions(agentId: 'id_2', title: '健康顾问', queryText: '您好，我是健康顾问'),
];

// 使用 ValueKey 确保切换时重新创建视图
AiAgentView(
  key: ValueKey(_currentIndex),
  options: _agents[_currentIndex],
)

运行示例工程

本仓库包含完整示例应用，可直接运行以体验功能：

cd example
flutter pub get
# 使用 DevEco Studio 打开 example/ohos 并运行，或通过 Flutter 命令运行到已连接设备
flutter run

运行前请将示例中的 agentId 替换为你在华为平台创建的智能体 ID。

项目结构

aiagent_ohos/
├── lib/
│   ├── aiagent_ohos.dart                 # 主 API：AiAgentOptions、AiagentOhos、AiAgentView
│   ├── aiagent_ohos_platform_interface.dart
│   └── aiagent_ohos_method_channel.dart
├── ohos/
│   ├── index.ets
│   └── src/main/ets/components/plugin/
│       └── AiagentOhosPlugin.ets         # 原生：MethodChannel + PlatformView + FunctionComponent
├── example/
│   └── lib/main.dart                     # 示例应用
├── test/
├── CHANGELOG.md
├── LICENSE
└── README.md

原生层通过 AbilityAware 获取 UIAbilityContext，供 isAgentSupport 使用；PlatformView 将 Dart 的 creationParams（StandardMessageCodec 解码为 HashMap）传给 ArkUI 的 FunctionComponent。

常见问题

Q：提示 "Parameter error. The parameter of 'agentId' is required, but is undefined"
A：多为 creationParams 未正确传到原生或解码异常。请确认使用本插件最新版本，且 AiAgentOptions 中 agentId 已正确传入。

Q：isAgentSupport 返回 false 或报错
A：请确认 (1) 设备/ROM 支持小艺智能体；(2) Agent ID 在华为平台已创建且未下线；(3) 应用已正确配置所需权限与依赖。

Q：非 HarmonyOS 平台会怎样？
A：插件仅实现 OHOS 平台；在其他平台使用 AiAgentView 可能无效果或需要自行做平台判断与降级 UI。

开源协议

本项目采用 MIT License 开源协议。

Libraries

aiagent_ohos
aiagent_ohos_method_channel
aiagent_ohos_platform_interface