开发定制 AI 助手小程序手把手教程（一）

最新推荐文章于 2025-09-19 13:47:26 发布

原创最新推荐文章于 2025-09-19 13:47:26 发布 · 1.4k 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#小程序 #人工智能 #AI音频 #AI助手 #开发语言 #AI硬件 #App

1. 准备工作

注意事项

如果您仅想构建一个助手小程序，且不需要深度定制小程序的外观与功能，推荐直接使用智能体平台生成的小程序。

⚠️ 重要提示：从 0.2.x 版本开始，@ray-js/t-agent-plugin-assistant 已被废弃，请使用 @ray-js/t-agent-plugin-aistream 替代。

前提条件

已阅读 Ray 新手村任务，了解 Ray 框架的基础知识。
已阅读智能体开发平台，了解智能体的各项概念。

构建内容

您可以利用小程序开发构建出一个基于 Ray 框架的 AI 助手小程序，并充分利用小程序的扩展能力，实现自定义功能和外观，满足您多种多样的业务需要。

所需条件

智能生活 OEM App（必选）
- 如果未创建，请先创建智能生活 OEM App。
智能产品（可选，如果您不需要智能体来控制设备，仅需要对话问答，可以不需要创建智能产品）
- 如果未创建，请先创建产品。
Tuya MiniApp IDE
NVM 及 Node 开发环境（建议使用 18.x 系列版本）
Yarn 依赖管理工具

详见智能小程序 > 搭建环境。

2. 创建智能体

创建

准备好 智能生活 OEM App 和智能产品（可选）后，需要在智能体平台上创建智能体。

单击 创建 Agent 按钮，填入项目相关必选信息后，单击确定创建一个智能体。

依照您的需求，在 01 模型能力配置 下定制智能体的模型、记忆、工具、知识库及工作流等功能，再在 02 提示词开发 下配置提示词（Prompt），完成当前数据中心的智能体创建。

调试

配置完成 Prompt 后，单击 获取调试二维码 按钮获取二维码。

使用国内版 智能生活 App 扫码，即可在 App 上使用模板小程序体验您的智能体。尝试发起问答，查看智能体的回答是否符合您的预期。确认没有问题后，单击 前往配置 按钮。

在智能体的应用管理页面，绑定您拥有的 App，单击保存。在真机上安装您的 App，使用 App 内建的扫码功能，再次扫描获取的二维码，即可在您的 App 上测试该智能体。

发布

按照您的需要，分别配置不同数据中心的智能体，然后单击发布按钮，发布智能体。

复制并记录智能体的 Agent ID，在后续实现对话页面的配置中会使用到：

完成

至此，您已经成功创建了一个智能体。如果不需要深度定制功能和界面，则可直接使用智能体平台生成的小程序。

3. 创建项目

开发者平台创建智能小程序

智能小程序的开发在 小程序开发者 平台上进行操作，首先请前往小程序开发者平台完成平台的注册登录。

在平台上创建一个小程序后，单击 添加 App 将小程序投放到您的 OEM App 中，并选择您想发布的数据中心。

创建本地工程

接下来，创建本地工程，需要在 Tuya MiniApp IDE 上进行操作，详细操作步骤可以参考智能小程序 > 三、初始化工程。注意，选择模板为 App 通用的 Ray 应用 来创建一个智能小程序工程。

4. 关键能力依赖

App 版本

智能生活 v6.7.0 及以上版本。

Kit 依赖

在项目中的 project.tuya.json 添加以下依赖：

{
  "dependencies": {
    "BaseKit": "3.12.0",
    "BizKit": "4.10.0",
    "DeviceKit": "4.6.1",
    "HomeKit": "3.4.0",
    "MiniKit": "3.12.1",
    "AIStreamKit": "1.0.0"
  },
  "baseversion": "2.21.10"
}

组件依赖

在项目中的 package.json 的 dependencies 中添加以下依赖：

{
  "dependencies": {
    "@ray-js/ray": "^1.6.8",
    "@ray-js/t-agent": "^0.2.3",
    "@ray-js/t-agent-plugin-aistream": "^0.2.3",
    "@ray-js/t-agent-ui-ray": "^0.2.3"
  }
}

依赖安装

添加完成后，在项目根目录下执行以下命令安装依赖：

yarn install

5. 实现对话页面

修改 src/pages/Home/index.tsx 文件，引入助手 SDK，实现对话页面。将 填写你的 [Agent ID] 处改成您的智能体 ID，保存并等待编译完成。

import React from 'react'
import {View} from '@ray-js/components'
import {createChatAgent, withDebug, withUI} from '@ray-js/t-agent'
import {ChatContainer, MessageInput, MessageList, MessageActionBar} from '@ray-js/t-agent-ui-ray'
import {withAIStream, withBuildIn} from '@ray-js/t-agent-plugin-aistream'

const createAgent = () => {
  try {
    // 应用插件是有顺序的
    const agent = createChatAgent(
      withUI(), // 第一个插件 withUI 插件提供了一些默认的 UI 行为，必选
      withAIStream({
        // withAIStream 插件对接小程序 AI 智能体平台，在小程序中必选
        enableTts: false, // 是否开启语音合成
        earlyStart: true, // 是否在 onAgentStart 阶段就建立连接
        agentId: '填写你的 [Agent ID]', // 输入你的智能体ID
      }),
      withDebug(), // withDebug 会在 console 里打印日志
      withBuildIn() // withBuildIn 插件提供了一些内置的功能
    )

    const {onChatStart, createMessage, onChatResume, session} = agent

    // 创建一条初始的欢迎信息
    onChatStart(async (result) => {
      const hello = createMessage({
        role: 'assistant',
      })

      hello.bubble.setText('Hello, world!')
      result.messages.push(hello)
      // 持久化消息，下次进入时会展示
      await hello.persist()
    })

    // 恢复聊天时，发送一条消息
    onChatResume(async (result) => {
      const lastMessage = session.getLatestMessage()
      const lastMessageCreateTime = lastMessage?.meta?.createdAt
      if (lastMessageCreateTime < Date.now() - 1000 * 60 * 60 * 2) {
        const welcomeBack = createMessage({
          role: 'assistant',
        })

        welcomeBack.bubble.setText('Welcome back')
        result.messages.push(welcomeBack)
        await welcomeBack.persist()
      }
    })
    return agent
  } catch (error) {
    console.error('Agent creation failed:', error)
    throw error
  }
}

export default function Home() {
  return (
    <View style={{height: '100vh'}}>
      <ChatContainer createAgent={createAgent}>
        <MessageList/>
        <MessageInput/>
        <MessageActionBar/>
      </ChatContainer>
    </View>
  )
}

此时，您可以看到一个简单的对话页面，便可以和智能体进行对话了。