Skip to content

MagicBowen/aixbot

BranchesTags

Repository files navigation

小爱开放平台语音技能SDK

小爱开放平台语音技能的非官方nodejs SDK，帮助你轻松对接小爱开放平台，快速构建起属于自己的语音技能。

使用前需要先在小爱开放平台注册开发者身份，申请语音技能，并确定服务器URL。具体参见小爱平台文档。

安装

npm install aixbot

用法

AixBot和nodejs社区著名的koa框架用法基本一致，通过定义中间件和事件监听回调来完成任务。

快速启动

以下示例实现了一个简单的语音技能：

  • 支持进入和退出技能时的礼貌用语
  • 支持用户直接询问"你是谁"
  • 其它消息环回播放
const AixBot = require('aixbot');

const aixbot = new AixBot();

// define event handler
aixbot.onEvent('enterSkill', (ctx) => {
    ctx.speak('你好').wait();
});

// define text handler
aixbot.hears('你是谁', (ctx) => {
    ctx.speak(`我是Bowen`).wait();
});

// define regex handler, echo message
aixbot.hears(/\W+/, (ctx) => {
    ctx.speak(ctx.request.query);
});

// close session
aixbot.onEvent('quitSkill', (ctx) => {
    ctx.reply('再见').closeSession();
});

// run http server
aixbot.run(8080);

HTTPS启动

AixBot默认使用http协议。由于小爱开放平台需要开发者提供https，建议最好在nginx上配置好SSL证书，然后代理到内部aixbot的端口。

AixBot也支持直接以https启动，如下。

// config your ssl key and pem
let tlsOptions = {
    key: fs.readFileSync('./keys/1522555444697.key'),
    cert: fs.readFileSync('./keys/1522555444697.pem')
};

aixbot.run(8080, '0.0.0.0', tlsOptions);

定义中间件

AixBot支持像koa那样注册中间件。AixBot当前只支持中间件使用async和await的方式处理异步。

const AixBot = require('aixbot');

const aixbot = new AixBot();

// define middleware for response time
aixbot.use(async (ctx, next) => {
    console.log(`process request for '${ctx.request.query}' ...`);
    var start = new Date().getTime();
    await next();
    var execTime = new Date().getTime() - start;
    console.log(`... response in duration ${execTime}ms`);
});

// define middleware for DB
aixbot.use(async (ctx, next) => {
    ctx.db = {
        username : 'Bowen'
    };
    await next();
});

// define event handler
aixbot.onEvent('enterSkill', (ctx) => {
    ctx.speak('你好').wait();
});

// define text handler
aixbot.hears('你是谁', (ctx) => {
    ctx.speak(`我是${ctx.db.username}`).wait();
});

// define regex handler
aixbot.hears(/\W+/, (ctx) => {
    ctx.speak(ctx.request.query);
});

// close session
aixbot.onEvent('quitSkill', (ctx) => {
    ctx.reply('再见').closeSession();
});

// define error handler
aixbot.onError((err, ctx) => {
    logger.error(`error occurred: ${err}`);
    ctx.reply('内部错误，稍后再试').closeSession();
});

// run http server
aixbot.run(8080);

如上我们定义了两个中间件，一个打印消息的处理时间，一个为context添加访问DB的属性。 由于中间件或者消息处理过程中可能会抛出异常，所以我们为异常定义了处理方式aixbot.onError((err, ctx) => {...})。

和KOA结合使用

大多数场景下我们只用像上面那样将AixBot独立启动就可以了，但是某些场景下我们需要在同一个程序里同时发布其它的web接口，这时可以将AixBot和koa结合使用。

const AixBot = require('aixbot');

const aixbot = new AixBot();

// define axibot middleware
aixbot.use(async (ctx, next) => {
    ctx.db = {
        username : 'Bowen'
    };
    await next();
});

// define event handler
aixbot.onEvent('enterSkill', (ctx) => {
    ctx.query('你好');
});

// define text handler
aixbot.hears('你是谁', (ctx) => {
    ctx.speak(`我是${ctx.db.username}`).wait();
});

// define regex handler
aixbot.hears(/\W+/, (ctx) => {
    ctx.speak(ctx.request.query);
});

// close session
aixbot.onEvent('quitSkill', (ctx) => {
    ctx.reply('再见').closeSession();
});

// define error handler
aixbot.onError((err, ctx) => {
    logger.error(`error occurred: ${err}`);
    ctx.reply('内部错误，稍后再试').closeSession();
});

const Koa = require('koa');
const koaBody = require('koa-body');
const Router = require('koa-router');

const router = new Router();
const app = new Koa();

// koa middleware
app.use(async (ctx, next) => {
    console.log(`process request for '${ctx.request.url}' ...`);
    var start = new Date().getTime();
    await next();
    var execTime = new Date().getTime() - start;
    console.log(`... response in duration ${execTime}ms`);
});

app.use(koaBody());
router.get('/', (ctx, next) => {
    ctx.response.body = 'welcome';
    ctx.response.status = 200;    
});

// register aixbot handler to koa router
router.post('/aixbot', aixbot.httpHandler());
  
app.use(router.routes());

app.listen(8080);
console.log('KOA server is runing...');

在上面的例子里，我们没有直接调用aixbot.run()，而是使用router.post('/aixbot', aixbot.httpHandler())将aixbot的处理绑定到koa router指定的/aixbot路由上。同时我们为AixBot和koa定义了各自的消息中间件。在运行时会先执行koa的中间件，然后再根据koa的路由规则进行消息分派。分派到/aixbot上的post消息先会执行AixBot的中间件，然后执行对应的已注册的AixBot消息回调。

对接NLU平台

AixBot支持对小爱发来的消息按照事件类型或者消息内容定义回调方法，并支持对消息内容以正则表达式的方式定义规则。但是如果需要完成复杂的语音技能，就必须对接功能完备的NLU处理平台。

对于NLU处理平台，最直接的是使用小爱开放平台的NLU配置界面进行配置，配置好后在收到的消息里就会携带NLU处理后得到的intent和slot信息。

AixBot可以监听指定的intent，在context中可以取出对应的slot信息。

// define intent handler
aixbot.onIntent('query-weather', (ctx) => {
    console.log(JSON.stringify(ctx.request.slotInfo));
});

如果需要完成更复杂的NLU处理，可以将AixBot对接其它更专业的NLU处理平台。遗憾的是DialogFlow、wit.ai目前都在墙外，微软的LUIS当前还可以用。国内类似的开放平台也有，基本和小爱当前的NLU能力差不多。作为一名程序员，说实话我不是很喜欢这种通过网页配置的方式来构建对话，我更喜欢经过良好封装的能够以代码的形式来定义和处理对话的chatbot引擎库，这样可以更加灵活地完成复杂功能。如果你自己有类似的NLU处理能力，那就会很方便了。

AixBot和非小爱的NLU平台对接，无非是在AixBot的回调里面将小爱发来消息里的对话内容转发到对应的NLU平台，然后根据NLU平台的返回结果构造给小爱的回复。这里和具体的NLU平台相关，就不再详述了。

API

AixBot

AixBot API reference

const AixBot = require('aixbot')

Constructor

Initialize new AixBot bot.

const aixbot = new AixBot([appId])

Param Type Description
[appId] String app_id of skill

在小爱开放平台上申请的每一个技能都有一个app_id。 如果需要对收到的每条消息的app_id进行严格校验，则在构造AixBot的实例时提供该值。

use

Registers a middleware.

aixbot.use(...middleware)

Param Type Description
middleware function Middleware function 
aixbot.use(async (ctx, next) => {
    ctx.db = {
        username : 'Bowen'
    };
    await next();
});

onEvent

Registers event handler.

aixbot.onEvent(eventType, handler)

Param Type Description
eventType String event type
handler function handler function

现在支持以下事件类型：

Event Type Description
enterSkill 进入技能
quitSkill 离开技能
inSkill 技能进行中
noResponse 音箱无响应
recordFinish 录音完成
recordFail 录音失败
playFinishing 录音播放即将完成 
aixbot.onEvent('enterSkill', (ctx) => {
    ctx.speak('你好').wait();
});

aixbot.onEvent('inSkill', (ctx) => {
    console.log(`received : ${ctx.request.query}`);
});

注意：inSkill事件的处理优先级是最低的，比随后介绍的onIntent、onText和onRegExp都要低。可以用它来做一些默认处理。

onIntent

Registers intent handler.

aixbot.onIntent(intent, handler)

Param Type Description
intent String intent name
handler function handler function 
aixbot.onIntent('query-weather', (ctx) => {
    console.log(JSON.stringify(ctx.request.slotInfo));
});

onText

Registers text handler.

aixbot.onText(text, handler)

Param Type Description
text String query content
handler function handler function 
aixbot.onText('hi', (ctx) => {
    ctx.speak('hello');
});

onRegExp

Registers regex handler.

aixbot.onRegExp(regex, handler)

Param Type Description
regex RegExp regular expression
handler function handler function 
aixbot.onRegExp(/\d+/, (ctx) => {
    ctx.speak(`收到数字：${ctx.request.query}`);
});

注意：所有regex handler的优先级低于text handler。

hears

Wrapper of onText and onRegExp.

aixbot.hear(text, handler)

Param Type Description
text String or RegExp query or regular expression
handler function handler function 
aixbot.hears('你是谁', (ctx) => {
    ctx.speak(`我是${ctx.db.username}`).wait();
});

aixbot.hears(/\W+/, (ctx) => {
    ctx.speak(ctx.request.query);
});

onError

Registers error handler.

aixbot.onError(handler)

Param Type Description
handler function handler function 
aixbot.onError((err, ctx) => {
    logger.error(`error occurred: ${err}`);
    ctx.reply('内部错误，稍后再试').closeSession();
});

run

Run http/https server.

aixbot.run(port, host, tlsOptions)

Param Type Description
port number port number
host String host address
tlsOptions object https options

如果不提供tlsOptions，则启动http server，否则启动https server

let tlsOptions = {
    key: fs.readFileSync('./keys/1522555444697.key'),
    cert: fs.readFileSync('./keys/1522555444697.pem')
};

aixbot.run(8080, '0.0.0.0', tlsOptions);

httpHandler

get middleware for KOA.

aixbot.httpHandler()

const router = new Router();
const app = new Koa();
app.use(koaBody());
router.post('/aixbot', aixbot.httpHandler());  
app.use(router.routes());
app.listen(8080);

Context

Context API reference.

Context是每一个Aixbot中间件和消息回调的参数，通过它可以得到request和response，访问request和response的属性和方法。

aixbot.onEvent('enterSkill', (ctx) => {
    console.log(JSON.stringify(ctx.request.body)); // 打印接收消息体的所有内容
    console.log(ctx.request.query); // 打印接收到的消息文本；具体Request封装过的属性和接口参见Request的API介绍
    ctx.response.reply('欢迎！'); // 构造回复消息；具体Response封装过的属性和接口参见Response的API介绍
    console.log(JSON.stringify(ctx.response.body)); // 打印发送消息体的所有内容
});

另外，为了方便使用，Context代理了Response的一些主要接口，这些接口可以通过Context直接使用。例如：

aixbot.onEvent('enterSkill', (ctx) => {
    ctx.reply('欢迎！'); // 效果和 ctx.response.reply('欢迎！') 相同
    console.log(JSON.stringify(ctx.body)); // ctx.body 和 ctx.response.body 相同
});

由于Response支持连贯接口调用，所以Context上代理的Response接口也同样支持。

aixbot.hears('你是谁', (ctx) => {
    ctx.speak('我是Bowen，你是谁？').wait(); // wait()指示开启麦克风，用于直接的多轮对话
});

最后，Context的存在方便中间件为其添加其它的属性和方法：

aixbot.use(async (ctx, next) => {
    ctx.db = {
        username : 'Bowen'
    };
    await next();
});

aixbot.hears('你是谁', (ctx) => {
    ctx.speak(`我是${ctx.db.username}`).wait();
});

Request

Request API reference.

Request封装了从小爱收到的消息体。通过Context可以访问到Request实例：ctx.request。

Request对接收消息体进行了封装，对常用字段提供了直接的读取属性。

attribute type Description
body object 消息体原始内容
query String message.request.query
session object message.session
appId String message.session.application.app_id
user object message.session.user
context object message.context
slotInfo object message.request.slot_info
intentName String message.request.slot_info.intent_name
eventType String message.request.event_type
eventProperty object message.request.event_property
requestId String message.request.request_id
requestType number message.request.type
isEnterSkill boolean message.request.type == 0
isInSkill boolean message.request.type == 1
isQuitSkill boolean message.request.type == 2
isNoResponse boolean message.request.no_response
isRecordFinish boolean message.request.event_type == 'leavemsg.finished'
isRecordFail boolean message.request.event_type == 'leavemsg.failed'
isPlayFinishing boolean message.request.event_type == 'mediaplayer.playbacknearlyfinished' 
aixbot.hears(/\W+/, (ctx) => {
    console.log(ctx.request.appId);
    console.log(ctx.request.query);
    if (ctx.request.isNoResponse) {
        console.log('received no response');
    }
    // ...
})

Response

Response API reference.

Response封装了发送给小爱的消息，通过ctx.response可以获取到Response的实例。

Response对发送消息体进行了封装，提供了更具有语义性的操作接口。

speak

Reply a text.

ctx.response.speak(text)

Param Type Description
text String 返回的消息文本

speak默认是关闭麦克风的，如果想要打开麦克风则需要和后面的wait接口一起使用。

wait

Open mic.

ctx.response.speak(text).wait()

wait接口不能单独使用，必须跟在其它有内容回复的接口后面。

query

response.speak(text).wait()的语法糖，可以直接写 response.query(text)

reply

与response.speak(text)等价，可以直接写 response.reply(text)

directiveAudio

Reply a audio directive.

directiveAudio(url, token, offsetMs)

Param Type Description
url String 资源url
token String 获取资源的token
offsetMs Long 偏移时间

directiveTts

Reply a tts directive.

directiveTts(text)

Param Type Description
text String 语音合成文本

directiveRecord

Reply a record directive.

directiveRecord(fileId)

Param Type Description
fileId String 录音文件ID

display

Reply a display.

display(type, url, text, template)

Param Type Description
type Int 1：html，2：native ui，3：widgets
url String html address
text String display text
template UlTemplate 参见 UlTemplate

setSession

Add paramter in session.

为当前对话上下文的session中添加变量，小爱会在随后的消息中携带该session参数。

setSession(obj)

Param Type Description
obj Any parameter store in session

playMsgs

Reply to play record msgs.

指示播放列表中所有的录音文件。

playMsgs(fileIdList)

Param Type Description
fileIdList Array file_id array

ctx.response.speak('请收听录音').playMsgs(['4747c167f000400f15f4d42x'])

registerPlayFinishing

指示播放录音即将完成后发送回调消息，具体参见小爱相关文档

ctx.response.speak('请收听录音').playMsgs(['4747c167f000400f15f4d42x']).registerPlayFinishing();

launchQuickApp

启动特定路径的快应用。 快应用语音技能的注册及配置见小爱文档。

launchQuickApp(path)

Param Type Description
path String path of quick app

ctx.response.launchQuickApp('/')

launchApp

启动APP。 启动APP的语音技能的注册及配置见小爱文档。

launchApp(type, uri, permission)

Param Type Description
type String 启动APP的intent的类型；支持的类型 1 activity； 2 service； 3 broadcast
uri String 启动APP的路径
permission String 权限信息；非必须参数

ctx.response.launchApp('activity', 'xxxxxxx')

record

指示开始录音，跟在回复后面使用。

ctx.response.speak('start record').record()

closeSession

指示结束回话，跟在回复后面使用。

ctx.response.speak('bye').closeSession()

notUnderstand

指示未理解的对话，跟在回复后面使用。

ctx.response.speak('what').notUnderstand()

body

获取消息体内容

ctx.response.speak('hello');
console.log(JSON.stringify(ctx.response.body));

context delegates

为了方便使用，Context对Response的下列属性和方法进行了代理：

  • speak
  • reply
  • query
  • directiveAudio
  • directiveTts
  • directiveRecord
  • display
  • playMsgs
  • launchQuickApp
  • launchApp
  • body
ctx.speak('hi').wait(); // same as : ctx.response.speak('hi').wait()

其它

源码在github，有问题请提issue。

使用 npm test可以对源码进行测试。

如果运行时想打开AixBot的debug打印，可以在启动时加上 DEBUG=aixbot:*，例如DEBUG=aixbot:* node index.js。

本人使用的是 node 8.11.1版本，其它更低版本的不支持class,const,let,async,await等特性的node版本请绕路。

作者

About

Robot SDK for XiaoAi Public Platform.

Resources

Readme
Activity

Stars

35 stars

Watchers

1 watching

Forks

7 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages