README

Convoworks 是一个 PHP 框架，用于管理对话式服务（亚马逊 Alexa 技能、谷歌操作和 Dialogflow、Viber、FB 消息等聊天机器人...）。以下是几个关键特性

• 它将对话定义为可重用的组件流，可以通过管理员 API 进行管理
• 它处理与连接平台的通信层
• 它高度依赖 PSR 和自己的接口定义，因此可以与任何 PHP 应用程序一起使用。

概述

Convoworks 框架内部有几个逻辑部分。

核心接口和实现

这部分定义了服务是什么，以及它可以使用哪些组件。它还定义了持久化和平台通信层。

以下是一些需要注意的部分

• \Convo\Core\Workflow 命名空间 - 定义工作流程组件类型 - 元素、处理器、过滤器
• \Convo\Core\Intent 命名空间 - 定义 Convoworks 意图模型
• \Convo\Core\Params 命名空间 - 定义如何访问或设置服务运行时参数
• \Convo\Core\Publisher 命名空间 - 定义如何将定义传播到平台
• \Convo\Core\Factory 命名空间 - 定义如何加载服务和创建组件
• \Convo\Core\ConvoServiceInstance 类 - 实际服务执行类

管理员 REST

管理员 REST 允许访问和管理对话工作流和发布过程。所有处理程序都放置在 \Convo\Core\Admin 命名空间中。

您可以使用 Convoworks 编辑器，该编辑器专为覆盖 Convoworks 管理员 API 功能而定制。

在文档文件夹中还有一个 Postman 定义，描述了完整的 API。

适配器

每个支持的平台在 \Convo\Core\Adapters 中都有自己的文件夹，其中包含 Convoworks 需要的几个特定实现。首先，它定义了接受平台请求的 HTTP 请求处理器。然后，它定义了如何创建 Convoworks 请求/响应对象，这些对象用于服务工作流。它还实现了服务定义如何传播到目标平台。

默认组件包

Convoworks 随带了一些包，您将在大多数情况下使用它们。

• 核心 - 此包在所有服务中都是必需的。包含您将经常使用的组件。它还包含标准意图和实体定义、常用函数和服务模板。
• Dialogflow - 谷歌助手特定组件
• Gnlp - 基于 Google NLP 的过滤 - 不能与 Alexa 一起使用
• Text - 基于纯文本的过滤 - 不能与 Alexa 一起使用
• Visuals - 视觉对话元素

集成

您可以在任何 PHP 网络应用程序中导入和运行 Convoworks。如果您的应用程序使用与 PSR 兼容的框架和依赖注入，那么这甚至更容易。

Convoworks 通过管理员和公共 REST API 暴露其功能。公共 API 由对话平台（例如亚马逊 Alexa）使用，并且不需要身份验证。每个支持的平台都有自己的处理程序。管理员 API 用于管理对话流程、配置和发布处理。它需要经过身份验证的用户请求。

为了挂载 Convoworks REST 处理程序，我们必须以某种方式引导它们，并必须提供系统所需的几个实现。

管理员用户

用于访问已登录用户，并允许保存一些特定的用户数据（例如平台访问配置）、服务所有权和共享。

Convoworks通过\Convo\Core\IAdminUserDataProvider接口访问用户数据，该接口返回\Convo\Core\IAdminUser对象。您必须实现这两个接口，因为用户管理始终是系统特定的。

服务数据存储

服务数据层定义了加载/保存服务数据、管理版本和发布以及存储与服务相关的运行时参数。它通过\Convo\Core\IServiceDataProvider、\Convo\Core\Params\IServiceParams和\Convo\Core\Params\IServiceParamsFactory接口定义。

我们提供了两种服务数据实现，一个将数据存储在文件系统中 - convoworks-data-filesystem，另一个与mysql协作 - convoworks-mypdo。

Http工厂

Convoworks需要一个PSR兼容的http客户端，并通过\Convo\Core\Util\IHttpFactory接口使用它。您可以使用我们的convoworks-guzzle实现。

引导启动

尽管您可以手动创建所有必需的类，但我们建议使用PSR兼容的DI容器。

以下是完整的生态系统

系统工具

核心功能

平台特定

管理API特定

公共API特定

REST路由

我们的处理器始终期望所有Convoworks请求以convo/v1为基本，因此您可以使用通配符将所有此类请求路由到Convoworks请求处理器。请注意，我们有两个独立的REST API，公共和行政，因此它们被单独处理和挂载。

而不是映射我们拥有的每个请求处理器，您可以使用我们的“分组”处理器，每个API一个。对于公共API使用\Convo\Core\Adapters\PublicRestApi，对于管理API使用\Convo\Core\Admin\AdminRestApi。唯一的区别是，在这种情况下，您必须使用DI容器。

注册包

您的应用程序还将定义哪些Convoworks自定义包可用于使用。包通过将\Convo\Core\Factory\IPackageDescriptor对象传递给\Convo\Core\Factory\PackageProviderFactory进行注册。

<?php

// example with function based factory
/** @var \Psr\Log\LoggerInterface $logger */
/** @var \Convo\Core\Factory\PackageProviderFactory $packageProviderFactory */
$packageProviderFactory->registerPackage( new FunctionPackageDescriptor('\Convo\Pckg\Trivia\TriviaPackageDefinition', function() use ( $logger, $packageProviderFactory) {
    return new \Convo\Pckg\Trivia\TriviaPackageDefinition(
        $logger, $packageProviderFactory
    );
}));

// example with class based factory - requires DI container!
/** @var \Psr\Container\ContainerInterface $container */
$packageProviderFactory->registerPackage( new ClassPackageDescriptor('\Convo\Pckg\Trivia\TriviaPackageDefinition', $container));

管理API身份验证

一旦您实现了它，您就必须使已登录用户可供REST处理器使用。在应用程序引导过程中某个地方，将请求属性Convo\Core\IAdminUser设置为您的用户（该用户实现了\Convo\Core\IAdminUser）。

<?php

$user       =   $this->_adminUserDataProvider->findUser( 'myusernameiremail');
$request    =   $request->withAttribute( \Convo\Core\IAdminUser::class, $user);

路线图

• APL支持 - Alexa展示语言允许为Alexa设备创建更多令人愉悦的用户界面。
• 在目标平台上前缀我们的意图模型 - 这将使用户能够直接在平台上手动创建额外的意图和实体，而不会在模型传播时被覆盖。
• 传播平台系统事件 - 能够以某种方式引用一些平台意图或实体，以便在传播Convoworks意图模型时自动打开。
• 组件迁移接口到包 - 能够将组件定义迁移到新版本。目前它处于核心级别，但应该在包中。
• 包文件 - 能够将文件部署到组件包中，用于服务（mp3音频提示、图像...）
• 增加单元测试覆盖率 -

Convoworks原型

您可以检查我们的名为Convoworks原型的示例集成。您可以下载它，并在此处找到更多信息这里

有关更多信息，请访问convoworks.com