首款专用于构建聊天机器人的编程语言。

核心特性 • 示例 • 快速上手 • 更多信息

在线试用 CSML

CSML（会话标准元语言） 是一种领域特定的编程语言兼聊天机器人引擎，旨在让开发复杂聊天机器人变得简单易行。

CSML 拥有高度表达力且纯文本的语法，流程清晰易懂，便于部署和维护对话式智能体。它内置短期与长期记忆槽、元数据注入功能，并可通过其强大的运行时 API 连接任意第三方 API 或嵌入任何编程语言编写的自定义代码。

核心特性

• 纯文本、富有表现力的语法，易于学习，可快速开发复杂的聊天机器人场景。
• 丰富且可扩展的对话组件，如轮播图、图片、视频、按钮、卡片、输入框、日历等。
• 内置短期与长期记忆槽，无需再编写复杂的状态机模板代码。
• 跨平台、高效且易于部署：仅需一个标准的 MongoDB、PostgreSQL 或 SQLite 数据库即可运行。
• 拥有超过 2 万名活跃 CSML 开发者的活跃社区。

示例

start:
  say "你好，很高兴认识你，我是一个演示机器人 👋"
  if (name) {
    say "我已经知道你啦 😉"
    goto known
  }
  else 
    goto name

name:
  say Question(
    "我想更了解你，你叫什么名字呢？",
    buttons=[
      Button("我是匿名 😎", accepts=["No", "Nope"]) as anonBtn
    ],
  )
  hold
  if (event.match(anonBtn)) {
    remember name = "anon"
  } else {
    remember name = event
  }
  goto known

known:
  if (name == "anon")
    say "...不过我知道你不太想多聊自己吧！"
  else 
    say "你叫 {{name}}！"
  goto end

完整文档请访问 https://docs.csml.dev/language。

快速上手

开始使用 CSML 最简单的方式是通过 CSML Studio，这是一个免费的在线开发环境，已预先配置好所有内容，让你可以直接在浏览器中创建机器人。

立即开始使用 CSML Studio：https://studio.csml.dev

CSML Studio 提供了一个免费的实验平台，帮助你熟悉这门语言，同时还支持一键将你的聊天机器人规模化部署。

自托管 / 云端 / 本地安装

CSML 可以作为一款自托管的 Web 服务器使用，你可以通过以下方式轻松安装。

请注意，你需要准备一个数据库。默认选择 MongoDB，但也可以使用 Amazon DynamoDB、PostgreSQL 和 SQLite，只需在设置环境变量时选择 mongodb、dynamodb、postgresql 或 sqlite 作为数据库类型即可，对应的环境变量略有不同。

在开始之前，请确保已正确设置以下环境变量：

ENGINE_DB_TYPE=mongodb # 必须是 mongodb|dynamodb|postgresql|sqlite 中的一个

# 对于 MongoDB
MONGODB_URI=mongodb://username:password@localhost:27017
MONGODB_DATABASE=csml

# 对于 PostgreSQL
POSTGRESQL_URL=postgres://user:password@hostname:port/database

# 对于 SQLite
SQLITE_URL=csml.db

# 对于 DynamoDB（需要 S3 存储大文件）
AWS_ACCESS_KEY_ID= # 或使用本地 IAM 角色
AWS_SECRET_ACCESS_KEY= # 或使用本地 IAM 角色
AWS_REGION=
AWS_DYNAMODB_ENDPOINT= # 可选，若未设置则使用对应区域的 DynamoDB 默认端点。
AWS_DYNAMODB_TABLE=
AWS_S3_ENDPOINT= # 可选，若未设置则使用对应区域的 S3 默认端点。
AWS_S3_BUCKET=

# CSML 服务器配置
ENGINE_SERVER_PORT=5000
ENGINE_SERVER_API_KEYS=someAuthKey4CsmlServer,someOtherAuthKey

# 其他可选的引擎配置
ENGINE_ENCRYPTION_SECRET=some-secret-string # 若未设置，数据将以明文存储
TTL_DURATION=30 # X 天后自动清除聊天机器人用户数据
LOW_DATA_MODE=true # 不存储发送/接收的消息内容
DISABLE_SSL_VERIFY=false # 访问具有已知无效证书的可信端点
DEBUG=true # 在控制台输出调试信息
CSML_LOG_LEVEL=error # 将日志输出到 stderr。可选值为 error、warn、info、debug、trace。
MODULES_URL= # 默认模块仓库基础 URL
MODULES_AUTH= # 默认模块认证令牌

部署到 Heroku

使用预编译二进制文件（仅限 Linux 和 macOS）

在本地启动 CSML 引擎最简单的方法是使用我们提供的预构建优化二进制文件（适用于 MongoDB 和 Amazon DynamoDB）。这些二进制文件自 v1.3.0 版本起，随每个 CSML 发布版本一同提供。

请参考这篇博客文章中的安装指南（以 Ubuntu 为例，其他操作系统步骤类似）：https://blog.csml.dev/how-to-install-a-self-hosted-csml-engine-on-ubuntu-18-04/

要下载最新的 CSML 服务器二进制文件，请前往 最新发布页面，并确保下载适合你系统架构的版本。

Mac 用户：首次运行此二进制文件时，Mac 可能会弹出关于应用未签名的警告（更多信息请参见 Apple 官方文档）。由于这不是面向大众发布的应用，我们暂时未进行公证流程，因此你可以放心忽略该警告！不过，如果你愿意，也可以选择从源码编译安装（详见下方“使用 Rust 从源码编译”部分）。

使用 Docker

我们提供了一个 Docker 镜像，方便您进行自托管部署。

docker pull clevy/csml-engine

要在 Docker 上开始使用 CSML Engine，请参阅：https://github.com/CSML-by-Clevy/csml-engine-docker

使用 Rust 从源码编译

CSML 是用 Rust 构建的。不过，您无需掌握任何 Rust 知识即可运行它！请确保您的 Rust 版本为 v1.46 或更高，并且已在您的机器上安装 openssl（或适用于您 Linux 发行版的等效软件包，如 libssl），然后执行以下命令：

cd csml_server

# 用于 MongoDB
cargo build --release --features csml_engine/mongo

# 用于 Amazon DynamoDB
cargo build --release --features csml_engine/dynamo

之后，运行构建好的可执行文件（默认位于 ./targets/release/csml_server），并访问 http://localhost:5000 查看一些请求示例。

使用 Node.js

此仓库提供了该 Rust 库的 Node.js 绑定。要在 Node.js 项目中使用此库，您需要从源码进行编译。以下是所需条件：

• 当前稳定的 Rust 版本（v1.61.0 及以上）
• Node.js LTS
• cargo-cp-artifact v0.1.6 必需依赖项
• libssl-dev（或适用于您架构的等效软件包：openssl-dev、libssl-devel 等）

要将 CSML Engine 编译为 原生 Node.js 模块，请运行以下命令：

git clone https://github.com/CSML-by-Clevy/csml-engine csml
cd csml/bindings/node/native
npm run build -- --release

注意：您可以通过使用特定脚本（例如 npm run build:mongodb）针对 MongoDB、DynamoDB、SQLite 或 PostgreSQL 进行专门编译，这些脚本位于 package.json 中。

此方法会生成一个原生文件：csml/bindings/node/native/index.node，您可以在项目中直接通过 require() 或 import 引入它。有关如何在您自己的项目中使用此模块的更多详细信息，您可以查看我们为 Docker 版本提供的实现：https://github.com/CSML-by-Clevy/csml-engine-docker/blob/master/app/server.js。

请注意，如果您计划将项目部署到不同的架构上，您需要在该架构上重新编译项目。我们建议在将 CSML Engine 集成到您自己的 Node.js 项目时使用 Git 子模块。

REST API 文档

CSML Server 的 HTTP REST API 文档以 OpenAPIv3 格式提供：swagger.yaml。为了更方便地阅读该文件，您可以在 Swagger Editor 中打开它。

其他信息

体验 CSML 语言

• Studio - 在几分钟内创建并部署您的聊天机器人。
• Playground - 在浏览器中测试和学习 CSML。

获取帮助

• Slack - CSML 官方社区。
• CSML 文档 - 入门指南。

信息

• 发布说明 - 保持最新状态。

CSML Engine 快速上手指南

CSML (Conversational Standard Meta Language) 是专为构建聊天机器人设计的领域特定编程语言及其引擎。它拥有简洁的文本语法，内置长短时记忆槽，支持丰富的对话组件，并能轻松连接第三方 API。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (Docker 方式跨平台支持最好)。
• 数据库: 必须准备以下任一数据库：
  • MongoDB (默认推荐)
  • PostgreSQL
  • SQLite
  • Amazon DynamoDB
• 可选依赖 (仅当从源码编译时需要):
  • Rust: 版本 v1.46+ (Node.js 绑定需 v1.61.0+)
  • OpenSSL: 系统需安装 libssl 或等效库 (如 libssl-dev)
  • Node.js: LTS 版本 (仅当使用 Node.js 绑定时)

安装步骤

您可以根据需求选择以下任意一种方式进行部署：

方式一：使用 Docker (推荐)

这是最简便的自托管方式。

1. 拉取镜像：

   docker pull clevy/csml-engine
   

2. 配置并运行容器（需设置环境变量指向您的数据库）：

   docker run -d \
     -e ENGINE_DB_TYPE=mongodb \
     -e MONGODB_URI=mongodb://username:password@host:27017 \
     -e MONGODB_DATABASE=csml \
     -p 5000:5000 \
     clevy/csml-engine
   

   详细 Docker 配置请参考：https://github.com/CSML-by-Clevy/csml-engine-docker

方式二：使用预编译二进制文件 (Linux/macOS)

1. 前往 最新 Release 页面 下载对应架构的二进制文件。
2. 赋予执行权限并运行：

   chmod +x csml_server
   ./csml_server
   

   注意：macOS 用户首次运行时若出现“无法验证开发者”警告，可在系统设置中允许运行，或选择从源码编译。

方式三：从源码编译 (Rust)

如果您需要自定义功能或使用特定数据库驱动：

1. 克隆仓库并进入服务器目录：

   git clone https://github.com/CSML-by-Clevy/csml-engine csml
   cd csml/csml_server
   

2. 根据数据库类型编译 (以 MongoDB 为例)：

   cargo build --release --features csml_engine/mongo
   

   (若使用 DynamoDB，请将 feature 改为 csml_engine/dynamo)
3. 运行生成的可执行文件：

   ./target/release/csml_server
   

方式四：Node.js 绑定

若需在 Node.js 项目中集成：

1. 进入绑定目录并安装依赖编译：

   cd csml/bindings/node/native
   npm run build -- --release
   

2. 在项目中引入生成的 index.node 文件。

基本使用

启动引擎后，默认监听 http://localhost:5000。您可以通过 REST API 与引擎交互，或直接在代码中编写 CSML 脚本。

1. 编写一个简单的 CSML 脚本

创建一个名为 bot.csml 的文件，内容如下：

start:
  say "Hi, nice to meet you, I'm a demo bot 👋"
  if (name) {
    say "I already know you 😉"
    goto known
  }
  else 
    goto name

name:
  say Question(
    "I'd like to know you better, what's your name?",
    buttons=[
      Button("I'm anonymous 😎", accepts=["No", "Nope"]) as anonBtn
    ],
  )
  hold
  if (event.match(anonBtn)) {
    remember name = "anon"
  } else {
    remember name = event
  }
  goto known

known:
  if (name == "anon")
    say "...but I know you don't want to say too much about yourself!"
  else 
    say "You are {{name}}!"
  goto end

2. 在线体验与测试

无需本地部署即可快速验证语法和逻辑：

• CSML Playground: https://play.csml.dev (在线测试语言特性)
• CSML Studio: https://studio.csml.dev (完整的在线开发与部署环境)

3. 调用 API

引擎启动后，可通过 HTTP POST 请求发送消息。完整的 API 文档 (OpenAPIv3) 位于 swagger.yaml，也可在 Swagger Editor 中加载查看。

典型请求结构包含 client, bot, payload 等字段，具体格式请参考官方 API 文档。