Urban Bot

基于 React 的通用聊天机器人库。

• 声明式。 无需了解任何消息平台的 API，只需编写简单的 React 组件。
• 跨平台。 一次编写，即可部署到任意消息平台。
• 可复用。 轻松在不同聊天机器人之间共享逻辑，或直接使用公共组件。
• 会话支持。 应用程序为每个对话单独渲染，因此你可以像进行客户端渲染一样编写应用。
• 类型安全。 完全支持 TypeScript。

我们支持的平台

       

即将支持

   

开始使用

API 文档

教程

• 如何在 Telegram 中创建待办事项列表
• 如何在 Telegram 中创建待办事项列表

安装

请使用我们的零配置 入门模板。

TypeScript

npx create-urban-bot my-app

JavaScript

npx create-urban-bot my-app --template js

或者手动安装：

npm i react @urban-bot/core @urban-bot/telegram @urban-bot/facebook ...

示例

import React from 'react';
import { render, Route, Router, Root, Text, ButtonGroup, Button, useText } from '@urban-bot/core';
import { UrbanBotTelegram } from '@urban-bot/telegram';
import { UrbanBotSlack } from '@urban-bot/slack';

function Echo() {
    const [text, setText] = React.useState('Say something');

    useText(({ text }) => {
        setText(text);
    });

    return (
        <Text>
            <i>{text}</i>
        </Text>
    );
}

function Counter() {
    const [count, setCount] = React.useState(0);

    const increment = () => setCount(count + 1);
    const decrement = () => setCount(count - 1);

    return (
        <ButtonGroup title={count} isNewMessageEveryRender={false}>
            <Button onClick={increment}>+1</Button>
            <Button onClick={decrement}>-1</Button>
        </ButtonGroup>
    );
}

function App() {
    return (
        <Router>
            <Route path="/echo">
                <Echo />
            </Route>
            <Route path="/counter">
                <Counter />
            </Route>
        </Router>
    );
}

const urbanBotTelegram = new UrbanBotTelegram({
    token: 'telegramToken',
});

const urbanBotSlack = new UrbanBotSlack({
    signingSecret: 'slackSigningSecret',
    token: 'slackToken',
});

render(
    <Root bot={urbanBotTelegram}>
        <App />
    </Root>
);

render(
    <Root bot={urbanBotSlack}>
        <App />
    </Root>
);

Urban Bot 快速上手指南

Urban Bot 是一个基于 React 的通用聊天机器人库。它允许开发者使用声明式的 React 组件构建机器人，无需深入了解各即时通讯软件（如 Telegram、Slack、Facebook Messenger）的底层 API，实现“一次编写，多端运行”。

环境准备

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

• 操作系统：Windows、macOS 或 Linux
• Node.js：建议安装 LTS 版本（v14 或更高版本）
• 包管理器：npm 或 yarn
• 前置知识：具备基础的 React 和 JavaScript/TypeScript 知识

提示：国内开发者建议使用淘宝镜像源加速依赖安装： npm config set registry https://registry.npmmirror.com

安装步骤

推荐使用官方提供的零配置启动器来初始化项目。

方式一：使用 TypeScript（推荐）

npx create-urban-bot my-app

方式二：使用 JavaScript

npx create-urban-bot my-app --template js

执行上述命令后，进入项目目录并安装依赖：

cd my-app
npm install

方式三：手动安装

如果您希望将 Urban Bot 集成到现有项目中，需手动安装核心库及对应平台的适配器：

npm i react @urban-bot/core @urban-bot/telegram @urban-bot/slack @urban-bot/facebook

(注：根据目标平台选择安装对应的 @urban-bot/<platform> 包)

基本使用

Urban Bot 的核心概念是使用 React 组件来描述机器人的交互逻辑。以下是一个最简单的示例，展示了如何创建一个支持文本回显和计数器的机器人，并可同时部署到 Telegram 和 Slack。

创建或编辑入口文件（如 src/index.tsx 或 src/index.js）：

import React from 'react';
import { render, Route, Router, Root, Text, ButtonGroup, Button, useText } from '@urban-bot/core';
import { UrbanBotTelegram } from '@urban-bot/telegram';
import { UrbanBotSlack } from '@urban-bot/slack';

// 文本回显组件
function Echo() {
    const [text, setText] = React.useState('Say something');

    useText(({ text }) => {
        setText(text);
    });

    return (
        <Text>
            <i>{text}</i>
        </Text>
    );
}

// 计数器组件
function Counter() {
    const [count, setCount] = React.useState(0);

    const increment = () => setCount(count + 1);
    const decrement = () => setCount(count - 1);

    return (
        <ButtonGroup title={count} isNewMessageEveryRender={false}>
            <Button onClick={increment}>+1</Button>
            <Button onClick={decrement}>-1</Button>
        </ButtonGroup>
    );
}

// 主应用路由
function App() {
    return (
        <Router>
            <Route path="/echo">
                <Echo />
            </Route>
            <Route path="/counter">
                <Counter />
            </Route>
        </Router>
    );
}

// 配置 Telegram 机器人
const urbanBotTelegram = new UrbanBotTelegram({
    token: 'YOUR_TELEGRAM_BOT_TOKEN',
});

// 配置 Slack 机器人
const urbanBotSlack = new UrbanBotSlack({
    signingSecret: 'YOUR_SLACK_SIGNING_SECRET',
    token: 'YOUR_SLACK_BOT_TOKEN',
});

// 渲染机器人实例
render(
    <Root bot={urbanBotTelegram}>
        <App />
    </Root>
);

render(
    <Root bot={urbanBotSlack}>
        <App />
    </Root>
);

运行说明

1. 将代码中的 YOUR_TELEGRAM_BOT_TOKEN、YOUR_SLACK_SIGNING_SECRET 等替换为您在实际平台申请的真实凭证。
2. 运行启动命令（通常在 package.json 中定义为 npm start 或 npm run dev）。
3. 在对应的即时通讯软件中找到您的机器人，发送 /echo 或 /counter 即可体验功能。