################## SUSI.AI 服务器 ##################

|加入聊天室：https://gitter.im/fossasia/susi_server| |Docker 拉取次数| |构建状态| |未解决问题占比| |平均问题解决时间| |Twitter| |Twitter 关注|

SUSI.AI 是一款智能的开源个人助理。它能够通过 API 进行聊天和语音交互，执行诸如播放音乐、创建待办事项清单、设置闹钟、收听播客、播放有声读物以及提供天气、交通等实时信息等操作。此外，还可以利用外部 API 将其他功能作为控制台服务添加进来。SUSI.AI 能够回答问题，并根据上下文请求更多信息以完成用户所需的操作。该助理的核心是 SUSI.AI 服务器，它承载着 SUSI.AI 的“智能”和“个性”。Android 和 Web 应用程序则通过 API 从托管服务器获取信息。

部署

开发环境: GitHub 开发分支的自动部署可用于测试，地址为 https://susi-server.herokuapp.com

主分支: 计划将主分支部署到 https://api.susi.ai。目前，部署每小时在 xx.45 分钟使用开发分支进行。我们计划很快切换到主分支用于生产环境。

部署分支

有两个分支用于部署：“dev-dist”和“stable-dist”。前者旨在与“susi_linux”的开发版本配合使用，而后者则与来自“master”分支的稳定版本一起使用。这两个分支目前仍需手动从“susi_server_binary_latest.tar.gz”更新（见下文），但未来的集成将定期更新“dev-dist”。

---

沟通

---

请加入我们的邮件列表讨论项目相关问题：https://groups.google.com/forum/#!forum/opntec-dev/

我们的聊天频道在 gitter 上：https://gitter.im/fossasia/susi_server

---

如何安装 Susi：下载、构建、运行

---

.. note::

- 您必须登录 Docker Cloud 才能使按钮正常工作。如果您未登录，将会看到 404 错误。

|在 Scalingo 上部署| |在 Docker Cloud 上部署| |在 Azure 上部署|

目前，SUSI.AI 尚未提供编译好的形式，您可以轻松自行构建。这并不困难，只需一分钟即可完成！源代码托管在 https://github.com/fossasia/susi_server，您可以下载并运行 SUSI.AI（在安装之前，您需要在 http://openjdk.java.net/install/ 安装最新版本的“Java 开发工具包”，并在 https://gradle.org/install/ 安装最新版本的“Gradle”）：

.. note:: - 对于 Armv6 处理器（例如 Raspberry Pi Zero / Zero W/ Zero WH/ 1A / 1B），请确保您的系统使用 Java 8（Oracle 或 OpenJDK），因为 Armv6 处理器存在一些兼容性问题。 - 您可以使用以下命令安装 OpenJDK 的 Java 8 JRE 和 JDK：

::

> sudo apt install openjdk-8-jdk-headless

::

> git clone https://github.com/fossasia/susi_server.git
> cd susi_server
> ./gradlew build
> bin/start.sh

对于 Windows 用户（使用 GitBash/Cygwin 或任何终端）：

::

> git clone https://github.com/fossasia/susi_server.git
> cd susi_server
> git checkout master
> ant jar
> java -jar dist/susiserver.jar
> git checkout development
> ant jar
> java -jar dist/susiserver.jar

::

停止：
> 按 Ctrl+C

所有服务器进程启动后，SUSI.AI 会尝试自动打开浏览器页面。如果未自动打开，请手动访问 http://localhost:4000；如果您是在无头或远程服务器上安装的，则需将“localhost”替换为您的服务器名称。

要停止 SUSI.AI，请运行：（此命令会阻塞，直到服务器完全停止）

::

> bin/stop.sh

还有一个自动升级流程，需通过 shell 命令触发。只需运行：

::

> bin/upgrade.sh

---

在哪里可以下载 SUSI.AI 的预编译版本？

---

最新的二进制文件可以从以下链接下载： http://download.susi.ai/susi_server/susi_server_binary_latest.tar.gz

运行 Susi 的步骤如下： tar xfz susi_server_binary_latest.tar.gz cd susi_server_binary_latest java -server -Xmx200m -jar build/libs/susi_server-all.jar

---

如何在 Google Cloud 上使用 Docker 安装 SUSI.AI？

---

要在 Google Cloud 上使用 Docker 安装 SUSI.AI，请参阅 Susi Docker 安装说明 </docs/installation/installation_docker_gcloud.md>__。

---

如何在 AWS 上使用 Docker 安装 SUSI.AI？

---

要在 AWS 上使用 Docker 安装 SUSI.AI，请参阅 Susi Docker 安装说明 </docs/installation/installation_docker_aws.md>__。

---

如何在 Bluemix 上使用 Docker 安装 SUSI.AI？

---

要在 Bluemix 上使用 Docker 安装 SUSI.AI，请参阅 Susi Docker 安装说明 </docs/installation/installation_docker_bluemix.md>__。

---

如何在 Microsoft Azure 上使用 Docker 安装 SUSI.AI？

---

要在 Azure 上使用 Docker 安装 SUSI.AI，请参阅 Susi Docker 安装说明 </docs/installation/installation_docker_azure.md>__。

---

如何在 Digital Ocean 上使用 Docker 安装 SUSI.AI？

---

要在 Digital Ocean 上使用 Docker 安装 SUSI.AI，请参阅 Susi Docker 安装说明 </docs/installation/installation_docker_digitalocean.md>__。

---

如何使用 Heroku 部署 SUSI.AI？

---

您可以通过点击上方的“Deploy to Heroku”按钮轻松部署到 Heroku。要使用 Heroku Toolbelt 安装 SUSI.AI，请参阅 Susi Heroku 安装说明 </docs/installation/installation_heroku.md>__。

---

如何使用 cloud9 部署 SUSI.AI？

---

要使用 cloud9 安装 SUSI.AI，请参阅 Susi cloud9 安装说明 </docs/installation/installation_cloud9.md>__。

---

如何在 Eclipse 上设置 SUSI.AI？

---

要在 Eclipse 上安装 SUSI.AI，请参阅 Susi Eclipse 安装说明 </docs/installation/eclipseSetup.md>__。

---

如何使用 Travis 自动部署到 VPS？

---

要使用 Travis 自动部署 SUSI.AI 到 VPS，请参阅 readme 文件 </docs/installation/auto_deploy_to_vps_with_travis.md>__。

---

如何运行 SUSI.AI？

---

• 构建 Susi（只需执行一次，详见上文）
• 运行 bin/start.sh
• 在浏览器中打开 http://localhost:4000
• 要关闭 Susi，运行 bin/stop.sh

---

如何配置 SUSI.AI？

---

基础配置文件位于 conf/config.properties。要自定义这些设置，请将 customized_config.properties 文件放置在 data/settings/ 路径下。

---

如何使用 Gradle 编译？

---

• 在 Ubuntu 上安装 Gradle： ::

   $ sudo add-apt-repository ppa:cwchien/gradle
   $ sudo apt-get update
   $ sudo apt-get install gradle
  

• 在 Mac OS X 上使用 Homebrew 安装 Gradle ::

   brew install gradle
  

• 要编译，首先创建 Gradle 所需的目录 ::

   ./gradle_init.sh
  

  将源代码编译成类文件和 JAR 文件 ::

   gradle assemble
  

  编译后的文件可以在 build 目录中找到。最后，清理一下，以便我们仍然可以使用 Ant 构建项目。 :: ./gradle_clean.sh

---

如何为 SUSI.AI 开发技能（AI 对话规则）？

---

SUSI.AI 的技能语言在 技能开发教程 <https://github.com/fossasia/susi_skill_cms/blob/master/docs/Skill_Tutorial.md>__ 中有详细说明。

---

如何在 SUSI.AI 服务器中使用 Susi 技能数据？

---

如果您只是想将您的技能添加到 SUSI.AI 在线服务中，请访问 https://skills.susi.ai 并添加您的技能。

对于您自己的部署：Susi 技能数据 <https://github.com/fossasia/susi_skill_data>__ 是存储 Susi 技能的地方。要让 Susi 服务器使用这些技能，需要将 Susi 技能数据与 Susi 服务器一起克隆： ::

git clone https://github.com/fossasia/susi_skill_data.git

如果您想在本地服务器上创建私有技能，应该在 Susi 服务器旁边创建一个本地 Git 仓库 susi_private_skill_data。然后您必须创建一个本地 Git 仓库托管： ::

> cd <上述 susi 主目录>
> mkdir susi_private_skill_data_host
> cd susi_private_skill_data_host
> git init —bare
> cd ../susi_private_skill_data
> git remote add origin <susi_private_skill_data_host 的路径>
> git push --set-upstream origin master

---

为什么我应该使用 SUSI.AI？

---

如果您想创建属于自己的 AI，那么您可以考虑使用 SUSI.AI。

---

在哪里可以找到 API 文档？

---

文档可以在这里找到：API 文档 <https://github.com/fossasia/susi_server/tree/development/docs/api/api.md>__。

---

在哪里可以找到 JavaDoc？

---

您可以通过运行 'ant javadoc' 来生成它们。

---

我在哪里可以报告 bug 并提出功能请求？

---

该项目被视为社区协作项目。开发团队也包括您。我们非常感谢您的拉取请求。因此，如果您发现某些地方可以改进，请您自己动手修复并提交拉取请求。如果您发现了 bug，请尝试自行修复。如果您向我们报告 bug，我们可能会考虑它，但那通常会是在大量不断增长的工作之后才会被处理。让您能够推动问题解决的最佳方式就是您亲自尝试解决。我们的 问题跟踪器在此 <https://github.com/fossasia/susi_server/issues>__。

---

开发工作流程是怎样的？

---

修复问题

步骤 1：选择一个要修复的问题

选择问题后：

1. 在问题中留言，说明您正在处理该问题。
2. 我们希望您通过评论或在 Gitter 聊天中讨论解决方案。
3. 建议定期更新问题的状态或进展。

步骤 2：分支策略

从您的 development 分支开始，并确保它与提交者仓库的 development 分支保持最新。请务必只在 development 分支上工作。执行命令：git pull upstream development

如果您尚未添加上游仓库，请按照 此处 <https://help.github.com/articles/configuring-a-remote-for-a-fork/>__ 的步骤操作。

步骤 3：编码规范

• 请帮助我们遵循最佳实践，以便于审查者和贡献者的工作。我们更关注代码质量，而不是管理拉取请求的流程。
• 每个拉取请求只提交一次。
• 提交信息应遵循 提交风格指南 <docs/commitStyle.md>__。
• 遵循统一的设计规范。整个应用的设计语言必须保持一致。
• 只有在提交被压缩合并后，拉取请求才会被合并。如果拉取请求中有多个提交，提交者需要自行压缩合并，而不是由维护者挑选并合并。
• 如果您不了解什么是提交压缩合并，请参阅 此处 <http://stackoverflow.com/a/35704829/6181189>__。
• 如果拉取请求涉及前端更改，请在拉取请求描述中附上相关的截图。

步骤 4：提交拉取请求

一旦打开拉取请求，尽量在两周内完成，或者至少保持积极的参与。长时间不活动可能导致拉取请求被关闭。如前所述，定期更新状态是有帮助的。

步骤 5：代码审查

您的代码将按以下顺序被审查：

• Travis CI：通过构建和运行测试。如果有测试失败，构建将被标记为失败。您可以查看 CI 日志以确定哪些测试失败。请确保所有测试都通过后再触发下一次构建。
• CI 日志还将包含允许您在本地运行失败测试的命令。
• 审查者：核心团队成员将被指定为该拉取请求的审查者，他将批准您的拉取请求或提出修改建议。

---

软件许可证是什么？

---

LGPL 2.1 <LICENSE>__

.. |加入聊天室 https://gitter.im/fossasia/susi_server| image:: https://badges.gitter.im/fossasia/susi_server.svg :target: https://gitter.im/fossasia/susi_server?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge .. |Docker 拉取次数| image:: https://img.shields.io/docker/pulls/fossasia/susi_server.svg?maxAge=2592000?style=flat-square :target: https://hub.docker.com/r/fossasia/susi_server .. |构建状态| image:: https://travis-ci.org/fossasia/susi_server.svg?branch=development :target: https://travis-ci.org/fossasia/susi_server .. |仍未解决的问题百分比| image:: http://isitmaintained.com/badge/open/fossasia/susi_server.svg :target: http://isitmaintained.com/project/fossasia/susi_server .. |平均问题解决时间| image:: http://isitmaintained.com/badge/resolution/fossasia/susi_server.svg :target: http://isitmaintained.com/project/fossasia/susi_server .. |Twitter| image:: https://img.shields.io/twitter/url/http/shields.io.svg?style=social :target: https://twitter.com/intent/tweet?text=Wow%20Check%20Susi%20on%20@gitHub%20@susiai_:%20https://github.com/fossasia/susi_server%20&url=%5Bobject%20Object%5D .. |Twitter 关注| image:: https://img.shields.io/twitter/follow/susiai_.svg?style=social&label=关注&maxAge=2592000?style=flat-square :target: https://twitter.com/susiai_ .. |部署| image:: https://www.herokucdn.com/deploy/button.svg :target: https://heroku.com/deploy?template=https://github.com/fossasia/susi_server/tree/development .. |在 Scalingo 部署| image:: https://cdn.scalingo.com/deploy/button.svg :target: https://my.scalingo.com/deploy?source=https://github.com/fossasia/susi_server .. |部署到 Docker Cloud| image:: https://files.cloud.docker.com/images/deploy-to-dockercloud.svg :target: https://cloud.docker.com/stack/deploy/ .. |部署到 Azure| image:: https://azuredeploy.net/deploybutton.svg :target: https://deploy.azure.com/?repository=https://github.com/fossasia/susi_server

SUSI.AI Server 快速上手指南

SUSI.AI 是一个开源的智能个人助理服务器，具备聊天和语音交互能力，可通过 API 执行音乐播放、待办事项、闹钟设置、天气查询等操作。本指南将帮助开发者快速在本地构建并运行 SUSI.AI 服务器。

环境准备

系统要求

• 操作系统：Linux (推荐 Ubuntu), macOS, 或 Windows (需 GitBash/Cygwin)
• 处理器架构：
  • 通用架构：支持最新 Java 版本
  • ARMv6 架构 (如 Raspberry Pi Zero/1A/1B)：必须使用 Java 8 (Oracle 或 OpenJDK)，否则存在兼容性问题。

前置依赖

在开始之前，请确保已安装以下工具：

1. Java Development Kit (JDK)

   • 推荐安装最新版 JDK。
   • ARMv6 用户专用命令 (安装 OpenJDK 8):

     sudo apt install openjdk-8-jdk-headless
     

   • 下载地址：OpenJDK

2. 构建工具 (二选一)

   • Gradle (推荐): 安装指南
     • Ubuntu 安装:

       sudo add-apt-repository ppa:cwchien/gradle
       sudo apt-get update
       sudo apt-get install gradle
       

     • macOS (Homebrew) 安装:

       brew install gradle
       

   • Ant: Windows 用户或非 Gradle 环境可使用。

3. Git

   • 用于克隆源代码仓库。

安装步骤

方法一：源码编译运行 (推荐)

适用于大多数 Linux/macOS 用户及希望自定义开发的场景。

1. 克隆仓库

   git clone https://github.com/fossasia/susi_server.git
   cd susi_server
   

2. 构建项目 使用 Gradle 进行构建：

   ./gradlew build
   

   (注：如果是首次运行且网络受限，请确保 Gradle 能正常下载依赖，或配置国内镜像源)

3. 启动服务

   bin/start.sh
   

方法二：Windows 用户专用步骤

如果您在 Windows 上使用 GitBash、Cygwin 或其他终端：

1. 克隆并切换分支

   git clone https://github.com/fossasia/susi_server.git
   cd susi_server
   git checkout master
   

2. 编译与运行 (Master 分支)

   ant jar
   java -jar dist/susiserver.jar
   

3. 编译与运行 (Development 分支)

   git checkout development
   ant jar
   java -jar dist/susiserver.jar
   

4. 停止服务 在终端中按下 Ctrl+C。

方法三：使用预编译包 (免编译)

如果不想自行编译，可直接下载最新二进制包：

1. 下载并解压

   wget http://download.susi.ai/susi_server/susi_server_binary_latest.tar.gz
   tar xfz susi_server_binary_latest.tar.gz
   cd susi_server_binary_latest
   

2. 运行

   java -server -Xmx200m -jar build/libs/susi_server-all.jar
   

基本使用

访问界面

服务启动后，SUSI.AI 会尝试自动打开浏览器。如果未自动打开，请在浏览器中访问：

• 本地访问: http://localhost:4000
• 远程/无头服务器访问: 将 localhost 替换为您的服务器 IP 或域名。

常用管理命令

• 停止服务 阻塞式停止，直到服务器完全终止：

  bin/stop.sh
  

• 升级服务 触发自动升级流程：

  bin/upgrade.sh
  

配置自定义

基础配置文件位于 conf/config.properties。若要自定义设置，请勿直接修改原文件，而是创建自定义配置文件：

• 路径: data/settings/customized_config.properties
• 在此文件中覆盖所需的配置项即可。

技能开发提示

若需添加自定义对话技能（Skills）：

1. 在线添加：访问 skills.susi.ai
2. 本地部署：克隆技能数据仓库至服务器同级目录

   git clone https://github.com/fossasia/susi_skill_data.git