hubot README

The project's README from github.com/hubotio/hubot. As one markdown file: README.md.

Pipeline Status

Build Status: MacOS Build Status: Ubuntu Build Status: Window

Hubot

Note: v10.0.4 accidentally contains the removal of CoffeeScript; v10.0.5 puts it back in Note: v11 removes CoffeeScript and converts this codebase to ESM

Hubot is a framework to build chat bots, modeled after GitHub's Campfire bot of the same name, hubot. He's pretty cool. He's extendable with scripts and can work on many different chat services.

This repository provides a library that's distributed by npm that you use for building your own bots. See the documentation for details on getting up and running with your very own robot friend.

In most cases, you'll probably never have to hack on this repo directly if you are building your own bot. But if you do, check out CONTRIBUTING.md

Create your own Hubot instance

This will create a directory called myhubot in the current working directory.

npx hubot --create myhubot --adapter @hubot-friends/hubot-slack
npx hubot --create myhubot --adapter @hubot-friends/hubot-discord
npx hubot --create myhubot --adapter @hubot-friends/hubot-ms-teams
npx hubot --create myhubot --adapter @hubot-friends/hubot-irc

Review scripts/example.mjs. Create more scripts in the scripts folder.

Command bus (robot.commands)

Hubot includes a deterministic command subsystem for slash-style commands. It is safe by default and does not interfere with legacy hear and respond listeners.

Basic Command Registration

export default (robot) => {
	robot.commands.register({
		id: 'tickets.create',
		description: 'Create a ticket',
		aliases: ['ticket new', 'new ticket'],
		args: {
			title: { type: 'string', required: true },
			priority: { type: 'enum', values: ['low', 'medium', 'high'], default: 'medium' }
		},
		sideEffects: ['creates external ticket'],
		handler: async (ctx) => {
			return `Created ticket: ${ctx.args.title}`
		}
	})
}

Invoke with addressing the bot:

Commands that declare side effects will require confirmation before execution.

The user is asked to confirm. They do so like so:

@hubot yes
@hubot no
@hubot cancel

Aliases are for discovery and search only. They do not execute commands or create proposals. They are intent utterances.

Built-in Help Command

Hubot automatically registers a help command that provides command discovery and documentation:

@hubot help                          # List all commands
@hubot help tickets                  # Filter commands by prefix
@hubot help search "create ticket"   # Search by keyword, alias, description, or example

Search for Commands

const results = robot.commands.search('ticket new')
// [{ id: 'tickets.create', score: 100, matchedOn: 'alias' }, ...]

Custom Type Resolvers

Extend validation with custom argument types:

export default (robot) => {
	// Register custom type resolver
	robot.commands.registerTypeResolver('project_id', async (value, schema, context) => {
		if (!value.startsWith('PRJ-')) {
			throw new Error('must start with PRJ-')
		}
		return value.toUpperCase()
	})

	// Use it in a command
	robot.commands.register({
		id: 'projects.deploy',
		description: 'Deploy a project',
		args: {
			projectId: { type: 'project_id', required: true }
		},
		handler: async (ctx) => {
			return `Deploying ${ctx.args.projectId}`
		}
	})
}

Configuration Options

When creating a CommandBus instance, you can configure:

Permissions

Control who can execute commands using room-based and role-based permissions.

Room-Based Permissions

Restrict command execution to specific chat rooms:

robot.commands.register({
	id: 'sensitive.action',
	description: 'Admin-only action',
	permissions: {
		rooms: ['#admin', '#ops']  // Only allowed in these rooms
	},
	handler: async (ctx) => {
		return 'Action executed!'
	}
})

Users in other rooms get: Permission denied: command not allowed in this room

Role-Based Permissions

Restrict command execution to users with specific roles:

robot.commands.register({
	id: 'deploy.production',
	description: 'Deploy to production',
	permissions: {
		roles: ['admin', 'devops']  // Only users with these roles
	},
	handler: async (ctx) => {
		return 'Deploying...'
	}
})

To enable role checking, provide a permissionProvider when creating CommandBus:

const commandBus = new CommandBus(robot, {
	permissionProvider: {
		hasRole: async (user, requiredRoles, context) => {
			// Custom logic to check if user has any of the required roles
			const userRoles = await fetchUserRoles(user.id)
			return requiredRoles.some(role => userRoles.includes(role))
		}
	}
})

Without a permission provider, role-based permissions are ignored (allow by default). Room-based permissions are always enforced.

License

See the LICENSE file for license rights and limitations (MIT).

Hubot History

Say hello to Hubot

Cartoon with Hubot

The Most Important Startup's Hardest Worker Isn't a Person

The Story of Hubot

Hubot by Hubotics

Automating Inefficiencies

Getting Started with Hubot

hubot (hubotio/hubot)

Searching Database…

16.8K ·GitHub
Hubot
Что это такое?Hubot — это фреймворк для создания чат-ботов, созданный по образцу одноимённого внутреннего бота GitHub для Campfire. Он распространяется как библиотека npm, с помощью которой вы создаёте собственного бота, способного работать во многих чат-сервисах.
Это готовый бот или фреймворк, на основе которого я сам создаю бота?Это библиотека/фреймворк, а не готовый бот. Вы создаёте на его основе собственный экземпляр Hubot, а затем расширяете его своими скриптами и адаптерами для чатов.
Как создать собственного бота с помощью этого инструмента?Запустите генератор, чтобы создать новый экземпляр (например, `bin/hubot --create myhubot`): он создаст каталог 'myhubot'. Затем добавьте свои скрипты в папку scripts, опираясь на готовый пример.
Что нужно установить перед запуском бота на Hubot?Нужны Node.js 18 или новее и npm 9 или новее; сама основная библиотека зависит от пакетов вроде express, express-basic-auth и pino.
Безопасно ли обновляться между версиями, особенно в части CoffeeScript?Будьте осторожны с версиями: версия v10.0.4 случайно убрала поддержку CoffeeScript, v10.0.5 вернула её, а в v11 CoffeeScript полностью удалён и кодовая база переведена на ESM, поэтому старые скрипты на CoffeeScript могут сломаться при обновлении.
Что такое функция командной шины (robot.commands)?Это детерминированная подсистема для команд в стиле слэш-команд, которые адресуются так: '@hubot tickets.create --title "VPN down"'. Она безопасно работает наряду с устаревшими обработчиками hear/respond и может требовать подтверждения пользователя для команд, имеющих побочные эффекты.
Можно ли ограничить, кто может использовать определённые команды?Да, командная шина поддерживает разрешения на уровне комнат (ограничение команд конкретными чат-комнатами) и разрешения на основе ролей через пользовательский permissionProvider; проверки по комнатам применяются всегда, а проверки ролей — только если вы передаёте провайдер.
Зачем создали Hubot?Он был создан в GitHub как «самый трудолюбивый работник самого важного стартапа» — внутренний чат-бот для Campfire, который автоматизировал такие неэффективные процессы, как деплой, а позже был открыт как этот фреймворк.
Есть ли встроенная система справки?Да, Hubot автоматически регистрирует команду help, которая предоставляет поиск и документацию по всем зарегистрированным командам, включая псевдонимы, которые используются только для поиска.
What are similar projects?ItChat, Baileys, whatsapp-web.js, botkit, openclaw, cc-connect, wechaty, botpress
Which topics is it in?event, hack, scripts, robot, bot, express, chat, chatbot, framework, npm, automation, server
Creator
hubotio
Size
4.5 MB
Stars
16.8K
Updated
CommitOct 14Releasev14.1.0Feb 24
Age
15y
Commits · 90 Days